Code documentation

Development tools

Code Structure

Techniques and Standards

How To

Functional Info

Background Info

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:

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:

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.

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:

  1. Make sure you've updated to the most recent version in the code repository before getting started.
  2. 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.
  3. 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.)
  4. 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)
  5. Once the window appears, select "Open Project" under the "File" menu.
  6. 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".
  7. 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.

  8. 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.
  9. Click the "Create All" button to recreate the TOC, Index, etc.
  10. 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.