JMRI Code: Use of JavaHelp

This page talks about technical aspects of how JMRI provides help information using JavaHelp and JHelpDev.

Organization of the help files

The help files are located in the "help" directory within the JMRI distribution directory.

The master copy of this is stored in our repository as the "help" directory in the JMRI code repository. This means to get your own local copy, just follow the steps on the "getting the code" page.

Within that, all the English-language files are located within the "en" subdirectory. Eventually, this will let us internationalize the help pages.

Within that, there are several file trees:

package - organized like the source package tree, this contains code-specific help files for e.g. a particular window or component. For example, a window that's created by the jmri.jmrit.speedometer.SpeedometerFrame class (from the src/jmri/jmrit/speedometer/SpeedometerFrame.java file) should have its window-specific help in a file at package/jmri/jmrit/speedometer/SpeedometerFrame.shtml.
html - general descriptions, tutorials, etc. This in turn in organized into directories that represent general areas.
manual - the most recent version of the DecoderPro et al manuals reformatted for use in the help system. (Older ones are stored in the main web site)

In the long run, we want only two branches to this structure: the "package" part of the tree for help information that is specific to a particular piece of code, and another part of the tree for more general information. (It's a religious issue whether that 2nd part should be called "html" or "manual"; the key thing is we end up with just one). The web is meant to be a web, with many paths through it to reach content. The second part of the tree should also be organized as "one page, one topic", with links to connect them as needed.

All the page formatting on JMRI help and other web pages is done through included CSS files, originally created by John Plocher. These are included from "/css" via Server-Side Includes (SSI). The main file is at /css/default.css and works with a few other files in that same directory. Because JavaHelp ignores SSI, the CSS formatting is ignored when JavaHelp is displaying the pages within the JMRI itself. In that case, JavaHelp provides the formatting.

Limitations of JavaHelp HTML

JavaHelp displays "plain old HTML 4.0", without providing some of the syntactic sugar provided by many browsers to allow poor HTML to render. Do not include any particular formatting options, specifically including embedded CSS commands. There are a couple of specific things to watch for:

Anchor tags need a specific format. Specifically, they should be written
```
<a name="pull">...</a>
```
around text content only. It's OK to be empty between the open and close tags. It's not OK to combine them into a single <a name="pull"/> tag; don't do that, as it confuses JavaHelp.
For example, to put an anchor on a heading, do
```
<h2><a name="foo">Foo!</a></h2>
```
Note: Incorrectly structured anchor tags (not like the above) often cause just a < character appearing by itself on the rendered help page.
Anchors need to use the "name" attribute rather than the "id" attribute. See the item above for an example.
Do not use spaces or %20 in anchor names. If you must use a phrase for a name, use the underscore character: "This_Anchor", not "This Anchor.
You can use the <code> element, or the <pre> element, but you can't use both together. <code> is good for highlighting in-line text as being code (like we've used it here); <pre> is good for making a block of inline HTML or Java look right. To give a code-like appearance to a block, wrap it in <pre style="font-family: monospace;">
You can't count on any particular location for your files on the local machine, so all links to other help pages need to be relative.
Links to web pages outside the help system work. In most cases they'll be automatically opened in an outside web browser.

Checking Your Changes

The Continuous Integration process checks all changes to JMRI Help files to make sure they're OK. If you'd like to run that same check while you're working, do:

   
    ant scanhelp

Web access to help

It's inconvenient to have to maintain two separate web pages for the main web site and the help system. To reduce the need for that, we use a particular form for the web pages in the help system.

Use ".shtml" file extensions so that the main web servers will search the files for server-side includes.
When you create a new page, start with a copy of either the help/en/TemplateBar.shtml or help/en/TemplatePlain.shtml template file, depending on whether or not you want to include a "Sidebar" via a file of the same name. This will put the proper top and bottom matter in place to get the page properly displayed.

Access in the code

Within the JMRI code, access the help system comes via the jmri.util.HelpUtil class. (For historical reasons, there's a little bit of code in apps.Apps, but you should ignore that).

The easiest way to add a help menu to a frame is to have it be a JmriJFrame (which you should do anyway), and call addHelpMenu(...) after you've built any other menus.

By convention, we use a similar file tree for the source code and help files. For example, the jmri.jmrit.simpleclock.SimpleClockFrame class inherits from JmriJFrame, and adds a help menu with the line

  addHelpMenu("package.jmri.jmrit.simpleclock.SimpleClockFrame", true);

The help file is then located at help/en/package/jmri/jmrit/simpleclock/SimpleClockFrame.shtml.

You should add the new page to the JHelpDev index to have JMRI accept it as a Help target (see next the heading).

A number of help files have been put in place without any contents; hopefully some users will edit them and contribute them back.

Creating the control files with JHelpDev

JavaHelp uses various XML files to control how the table of contents and index are displayed. We create those with JHelpDev. Please don't edit them manually.

JHelpDev is now included in the JMRI dist. To use the tool:

Make sure you've updated to the most recent version in the code repository before getting started.
You can run in batch mode by running ant from the command line in the help/en/ directory. It'll still pop windows, but should run to completion by itself. It might take a minute or so.
If you'd like to operate it manually, please follow the rest of these bullets. (Or if using Eclipse, right-click on the help/en/build.xml file and select Run As Ant Build.)
Start the tool by clicking on the jhelpdev.jar file. (If that doesn't work, try running either JHelpDev.csh or JHelpDev.bat, depending on what kind of computer you have)
Once the window appears, select "Open Project" under the "File" menu.
Navigate to the "help" directory in your checked out copy of the code, then the "en" directory within that, then select the "JHelpDev.xml" file and click "Open".
You may get a message about "[Fatal Error] index.html:1:3: The markup declarations contained or pointed to by the document type declaration must be well-formed." Although it says it's fatal, it's really not a problem. Just ignore it. On startup the Map (a file containing the JHelpDev index of all anchors in the JMRI help system) is regenerated.
By clicking the "Index Editor" tab or the "TOC Editor" tab, review and update the Help entries. A red line marks a hyperlink that JHelpDev can't locate on disk. Right-click on such a line to open the Edit context menu.
Click the "Create All" button to recreate the TOC, Index, etc.
Then, back on the command line and in the help/en directory, invoke "ant index TOC" to create the web index and table of contents pages.

The various control files that JavaHelp uses are stored in our code repository, so once you've done this they will show as modified. Please check them in when you check in new Help files so other people don't have to recreate those control files for themselves.

Table of Contents and Index

Java Help includes a table of contents and an index. These are both available as hyperlinks on the web, and provided via a nicer user interface when using JavaHelp in the program.

The underlying information must be manually maintained in the help/en/JmriHelp_enTOC.xml and help/en/JmriHelp_enIndex.xml files, respectively. JHelpDev then makes the files that Java Help needs, and an "ant" step in the directory makes the webtoc.shtml and webindex.shtml files that are displayed on the web.

Note: This means you should not manually change the webToc.shtml and webindex.shtml files, because those changes will be overwritten by later steps.

The JmriHelp_enTOC.xml and JmriHelp_enIndex.xml files are straight-forward XML, and you can manually edit them. Make sure to run the JHelpDev "create all" step and "ant" after doing so.

You can also use the JHelpDev tool to add items to the table of contents and index if you'd like. There's more info on how to do that on the JHelpDev web site. Remember to run "ant" after that to include your updates on the web versions.

Updating the JMRI.org site

Changes to Help pages which are checked-in should show up automatically on the JMRI.org site after a short while. There's a Jenkins job that handles periodic updates for the static (from repository, unlike e.g. Javadoc) pages.