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.

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.
html - general descriptions, tutorials, etc.
DecoderProManual - a version of the DecoderPro manual reformatted for use in the help system.

Limitations of JavaHelp HTML

JavaHelp displays "plain old HTML", 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 can't be self contained. Specifically, <a id="foo"/>Foo! needs to be replaced by <a name="foo">Foo!</a> The indicator that you have to do this is an < character just appearing 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. (We hope to eventually have an automated solution to make this work better)

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.
Include the top- and bottom-matter from the help/en/TemplateBar.shtml and help/en/TemplatePlain.shtml files, depending on whether or not you want to include a "Sidebar" via a file of the same name.

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.

To do this:

You have to put some files in your help/en directory Download this .zip archive and put in in your project's help/en directory, then expand it. It should create a jhelpdev.jar file, and a lib directory containing additional .jar files. These files don't show up in CVS, for various reasons.
It's important that you update the configuration files from CVS before running the tool. The configuration info is complicated, and a CVS merge may not go well later.
cvs -q update Map.jhm *.xml
Start the tool by clicking on the jhelpdev.jar file.
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.

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