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 CVS as the "help" module. This means to get your own local copy, just do:

cvs -d:pserver:anonymous@jmri.cvs.sourceforge.net:/cvsroot/jmri login
cvs -d:pserver:anonymous@jmri.cvs.sourceforge.net:/cvsroot/jmri co all

(If asked for a password, just hit return; see our "getting the code" page for more information on getting JMRI content with CVS)

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.

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.