Info on JMRI:
Development tools
Techniques and Standards
How To
Functional Info
Background Info

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:

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.

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.

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:

  1. Make sure you've run "update" from SVN before getting started.
  2. 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)
  3. Once the window appears, select "Open Project" under the "File" menu.
  4. 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".
  5. Click the "Create All" button to recreate the maps, index, etc.
  6. 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.