Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Broken internal link in French help #1432

Closed
bobjacobsen opened this issue Jun 4, 2016 · 11 comments
Closed

Broken internal link in French help #1432

bobjacobsen opened this issue Jun 4, 2016 · 11 comments
Labels
Documentation Pending closure This issue or PR has not been updated for a while

Comments

@bobjacobsen
Copy link
Member

From JMRIusers:

Use of help or ? change page with index give blank page or following error

http://jmri.org//C:/Program%20Files%20(x86)/JMRI/help/fr/manual/index.shtml http://jmri.org//C:/Program%20Files%20(x86)/JMRI/help/fr/manual/index.shtml
An error has been encountered in accessing this page. 1. Server: jmri.org 
2. URL path: /C:/Program Files (x86)/JMRI/help/fr/manual/index.shtml

To recreate:

  • open Help
  • select main DecoderPro page
  • click 'Manuel Complet de DecoderPro' link

The link being followed is: help/fr//html/apps/DecoderPro/index.shtml:<a href="../../../manual/index.shtml">Manuel Complet de DecoderPro</a>

That file doesn't exist in help/fr, but does exist in help/en. The fallback access code doesn't know to try help/en if help/ fails.
@silverailscolo
Copy link
Contributor

I guess this refers to the on line html help structure.
The (US)English DP Help was updated a couple of months ago. Sure the French Help either has to redirect to /en/ when encountering a missing piece, or have its contents updated some time soon. Broken links are something else; they shouldn't have developed at all. We might use the same type of redirect in the HTML as used for moved elements on the site. But users won't come back to the French help as soon as they follow links that have an /fr/ counterpart.
I've been thinking about a way to switch Help languages on our on line help pages to fix that, but stumbled upon the non-english help lagging behind, and the magic HTML4 trick to arrive at the same page when clicking some language button will be a wild guess.
Let me start to fix the real broken links, ideally maintaining a mirror of the English help. W3C has a handy tool for that.

@bobjacobsen
Copy link
Member Author

@silverailscolo Thanks!

We can add code within JMRI help that will provide the default (English) page when a relative reference from a help page isn't found. That'll still resolve back to the local language pages on the next link.

But that doesn't help with the help pages on the web. Is there something that could be added to the Header file that would help with that?

@rhwood
Copy link
Contributor

rhwood commented Jun 12, 2016

Can I make an alternate suggestion:

  1. Remove the French help (its years, not months, behind the English help in many cases).
  2. Rewrite the English help from scratch using DocBook and then translate the DocBook into French.

There are multiple reasons for this:

  • Using Server Side Includes (SSI), help content HTML validity cannot be checked using a CI service.
  • Jetty (the JMRI web server) does not support SSI (nor does any other java-based server I can find), so the help content is broken and incomplete when served by a JMRI instance.
  • JavaHelp cannot process SSI either, so the JavaHelp has the same problem Jetty has.
  • There is no HTML or XML editor I can find that is SSI aware (i.e. no inline validation of HTML or XML with SSI is possible).
  • We can produce HTML Jetty and the web site, JavaHelp, and PDFs all from the same source, using unique stylesheets and XML transforms for each.

The docbook branch on GitHub is current with master, and has build targets and a sketch for a DecoderPro Users Guide (which probably should be a JMRI Users Guide).

@bobjacobsen
Copy link
Member Author

I haven't thought through a migration to DocBook yet, so have no opinion on that now.

But I'd like to clarify this:

JavaHelp cannot process SSI either, so the JavaHelp has the same problem Jetty has.

That's intentional, and I don't think it's a problem.

JavaHelp has its own navigation & framing. By having the help/ files plain content with SSI for header, sidebar(s) and footer, JavaHelp can display the content as it wants to. The SSI the makes web pages independent of that.

It sounds like making every from a single DocBook source would end up with a similar effect.

@rhwood
Copy link
Contributor

rhwood commented Jun 13, 2016

The real problem with the way we use SSI is the HTML help content without SSI invariably is structured like:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
</head>
<body>
<!--#include virtual="/Header" -->
<!--#include virtual="Sidebar" -->
<div id="mainContent">
<!--#include virtual="/Footer" -->
  </div><!-- closes #mainContent-->
 </div> <!-- closes #mBody-->
 </body>
</html>

where the file does not conform to its DocType declaration, because the mBody div is created only by the SSI. We are merely lucky

This may be intentional, but intentionally shipping something broken feels wrong. We also have lots of navigation embedded in some HTML documents not in SSI, so its wholly inconsistent.

@bobjacobsen
Copy link
Member Author

@rhwood wrote:

The real problem with the way we use SSI is the HTML help content without SSI invariably is structured like:

where the file does not conform to its DocType declaration, because the mBody div is created only by the SSI. We are merely lucky

Perhaps I’m misreading the above. Are you pointing at the close for mBody without the open for mBody?

That’s a problem in those files that should be fixed, but it’s (a) not solely due to SSI nor (b) invariably present. The included Header file (from the website repository) doesn’t define that either, so just removing the SSI won’t fix it in files without Sidebar included. I did a quick sample across help/en and it looks to me like about half the files are OK and half aren't. If that’s correct, there are about 350 files to update in help/en. (There are probably a lot more in the website folder itself, as the files in the “manual” family seem to miss this particularly often)

If this is worth fixing (and I’m not sure that it is if we’re going to be migrating the help files & web site at some point), then the first step would be to find some tools to validate HTML and start running them for a total report in Jenkins. That’ll start bringing the total down as people learn how to fix things. But I don’t think it’s worth devoting lots of hours, even incidental hours, to converting help files to “good HTML 4” if that’s not going to be their long term residence.

@rhwood
Copy link
Contributor

rhwood commented Jun 13, 2016

Are you pointing at the close for mBody without the open for mBody?

Yes, I am.

That’s a problem in those files that should be fixed, but it’s (a) not solely due to SSI nor (b) invariably present. The included Header file (from the website repository) doesn’t define that either, so just removing the SSI won’t fix it in files without Sidebar included. I did a quick sample across help/en and it looks to me like about half the files are OK and half aren't. If that’s correct, there are about 350 files to update in help/en. (There are probably a lot more in the website folder itself, as the files in the “manual” family seem to miss this particularly often)

It’s defined in the Sidebar.

If this is worth fixing (and I’m not sure that it is if we’re going to be migrating the help files & web site at some point), then the first step would be to find some tools to validate HTML and start running them for a total report in Jenkins. That’ll start bringing the total down as people learn how to fix things. But I don’t think it’s worth devoting lots of hours, even incidental hours, to converting help files to “good HTML 4” if that’s not going to be their long term residence.

I don’t want it fixed—I’m pointing this out as a reason to move away from directly editing HTML and using SSI. There are lots of editors that validate HTML (Eclipse, NetBeans, IntelliJ, BBEdit, etc), but given the built in errors from using SSI, errors those editors point out have to be ignored, and once you begin ignoring some errors, its easy to miss errors you shouldn’t ignore.

@bobjacobsen
Copy link
Member Author

I don’t want it fixed—I’m pointing this out as a reason to move away from directly editing HTML and using SSI. There are lots of editors that validate HTML (Eclipse, NetBeans, IntelliJ, BBEdit, etc), but given the built in errors from using SSI, errors those editors point out have to be ignored, and once you begin ignoring some errors, its easy to miss errors you shouldn’t ignore.

I’m pointing out that it’s a single, replicated error. If it’s really a problem, it’s straightforward to fix. If it’s not a problem, it’s not a reason to move to another approach besides SSI + HTML/JavaHelp.

There may well be reasons to rewrite 1000+ files, but I don’t think that’s one.

@bobjacobsen bobjacobsen mentioned this issue Dec 24, 2016
Closed
@jerryg2003
Copy link
Contributor

The missing “mbody” open statement problem discussed above has been fixed (some time in 2019-2020). It now appears in all shtml files and was taken out of all Sidebar.shtml files. As to the broken link in the French help, or the broader discussion, perhaps someone can re-open these if still relevant.

@stale
Copy link

stale bot commented Apr 30, 2021

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. JMRI is governed by a small group of maintainers which means not all opened issues may receive direct feedback.

@stale stale bot added the Pending closure This issue or PR has not been updated for a while label Apr 30, 2021
@stale
Copy link

stale bot commented May 15, 2021

This issue has been automatically closed due to lack of activity. In an effort to reduce noise, please do not comment any further. Note that the maintainers may elect to reopen this issue at a later date if deemed necessary.

@stale stale bot closed this as completed May 15, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Pending closure This issue or PR has not been updated for a while
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@rhwood @bobjacobsen @silverailscolo @jerryg2003