JMRI: 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 SVN as the "help" module. 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 - a version of the DecoderPro manual reformatted for use in the help system.

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.

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. In particular, there are a couple things to watch for.

Anchor tags aren't XML. Specifically, <a id="foo"/>Foo! needs to be replaced by <a id="foo">Foo! or <a name="foo">Foo!</a> The indicator that you have to do this is an < character just appearing by itself on the rendered page.
Anchors also need to use the "name" attribute rather than the "id" attribute. See the item above for an example.
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, but JavaHelp can't display PDF files. Links to those should be shown explicitly as links, so they can be copied to an outside web browser.

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.

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 run "update" from SVN before getting started.
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".
Click the "Create All" button to recreate the maps, index, etc.
Then, back on the command line and in the help/en directory, invoke "ant" to create the web index and table of contents pages. (Or if using Eclipse, right-click on the help/en/build.xml file and select Run As Ant Build.)

The various control files that JavaHelp uses are stored in SVN, so once you've done this SVN will show them 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.

You can also use the tool to add them to the table of contents, etc, if you'd like. There's more info on how to do that on the JHelpDev web site.

Updating the JMRI.ORG site

Changes to Help pages which are checked into svn should show up automatically on the JMRI.ORG site after a short while. If this does not work, you can visit [this page] to push the update along.