Code documentation

Development tools

Code Structure

Techniques and Standards

Help and Web Site

How To

Functional Info

Background Info

JMRI Help:
Contents/ Index
Glossary

Donate to JMRI Donate to JMRI.org

JMRI Code: Creating Help Pages and Using JavaHelp

This page talks about technical aspects of how JMRI provides help information using JavaHelp and JHelpDev as well as some suggestions on common approaches for help pages.

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:

  • 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 - the most recent version of the DecoderPro et al manuals reformatted for use in the help system. (Older ones are stored in the main web site)

While this is how we would LIKE our help files organized, help pages are created by members of the community and sometimes general descriptions are put in the package directory rather than the html directory and vice versa. [If you see something that needs to be moved, please post a note to the jmri-developers online groups.io forum as there are members who occassionally try to do some housekeeping.]

In the long run, we want only two branches to the help file 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 ("html") should also be organized as "one page, one topic", with links to connect them as needed.

[Go to top of page]

Web Access to Help Pages

It is 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. [Additional information can also be found here.]
  • 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 named Sidebar.shtml). This template will put the proper top and bottom matter in place to get the page properly displayed.
  • In general, all help files in the html directory tree use a sidebar. In general, files in the package part of the tree do not. If you are using a sidebar, you may find one that suits your purpose in the specific subdirectory in which you are working, in its parent directory, or, in rare cases, you can use the one in the html directory itself (either /help/en/html or /help/fr/html).

    If none of these meet your needs (or do not exist), you may create a Sidebar.shtml in the subdirectory, in which case, you should follow the format of other Sidebar.shtml files in other subdirectories at the same level or in the parent directory. In 2020, there was a major effort to standardize the sidebar files, using server-side includes for common parts files in the /help/en/parts directory. Typically a Sidebar.shtml file in a terminal subdirectory (one with no lower level) will further reference a "local part" in a file in the same subdirectory and named Sidebar[type]LocalPart.shtml, where [type] would be based on the name of the parent directory, such as Hardware or Tool. This use of local part files allows Sidebar.shtml files in terminal subdirectories to use identical code, something that makes maintenance significantly easier.

    If you do not need a local part, use the Sidebar.shtml in the parent directory by including the following statement in your help file:

         <!--#include virtual="../Sidebar.shtml" -->
            
    This line exists in the help template files but does not have the "../". Note also there is no space before the hash sign and a space after the final quote.
  • 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.

[Go to top of page]

Standards for and 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:
  • Anchor tags need a specific format. Specifically, they should be written
    <a name="pull" id="pull">...</a>
    
    around text content only. It's OK to be empty between the open and close tags. It's not OK to combine them into a single <a name="pull"/> tag; don't do that, as it confuses JavaHelp.

    For example, to put an anchor on a heading, do

    <h2><a name="foo" id="foo">Foo!</a></h2>
    

    Note: Incorrectly structured anchor tags (not like the above) often cause just a < character appearing by itself on the rendered help page.

  • Anchors need to use the "name" attribute as well as the "id" attribute for future compatibility. Name is recognized by JavaHelp but not by the latest versions of html while id is not recognized by JavaHelp. See the item above for an example.
  • Do not use spaces or %20 in anchor names. If you must use a phrase for a name, use the underscore character: "This_Anchor", not "This Anchor.
  • You can use the <code> element, or the <pre> element, but you can't use both together. <code> is good for highlighting in-line text as being code (like we've used it here); <pre> is good for making a block of inline HTML or Java look right. To give a code-like appearance to a block, wrap it in <pre style="font-family: monospace;">
  • When describing a sequence of user actions or pulldowns, use the double right arrow to indicate sequence, HTML 4 tag ampersand-rArr-semicolon, label the whole sequence as "strong" and put the terminal command in quotes:
    File⇒"Store Panels"
  • You cannot 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 XML contents also need to be relative even though they are not displayed by JavaHelp.
  • Links to web pages outside the help system work and should be specified as fully qualified, preferably with https://. In most cases they will be automatically opened in an external web browser. [If you are already looking at the help page in an external browser, these pages may be opened in a new tab or in the same tab (overwriting the current page), depending on how the person who wrote the help page coded the reference. As of this writing (2020/04/04), there is an on-going debate as to the prefered method.]

[Go to top of page]

Creating Help/Web Pages for New Hardware

When you integrate support for new hardware into JMRI, you should also create a page or pages for the help system and the web. There are several steps involved to ensure that your new hardware help is integrated into the JMRI Help system and its web site. All references below to files are to the JMRI Repository structure in Github. Note use of capitalization in references to (fictitious) product "X" from manufacturer "M":

  1. Create the general help page or pages for the new hardware:
    • See other hardware help pages linked off the Hardware Index page for examples before beginning. There are a variety of styles based on how much information you want to provide. You can also provide a link to external manufacturer pages.
    • Create your help page and put it into "/help/en/html/hardware", either directly as "X.shtml" if only a single file or in its own subdirectory "/help/en/html/hardware/m/" if there are going to be multiple pages. You should name the first file "index.shtml" when in its own subdirectory.
    • If your help pages have images, create a subdirectory "/help/en/html/hardware/m/images" to store them.
    • Put in the standard sidebar by an "include" of "/help/en/html/hardware/Sidebar.shtml" (using appropriate relative addressing) in your help page or pages. [Some creators of hardware and hardware families create their own "SidebarHardwareLocalPart.shtml" file in the "m" subdirectory to have custom information in the sidebar. This also requires creating a file "Sidebar.shtml" in "standard format" in the "m" subdirectory. See some exising hardware entries such as this one for examples.]
  2. Create any "code-specific" help page or pages for the new hardware:
    • As discussed in the first section of this page, "code-specific" help (i.e. related to a particular window or component) should be in pages in a different part of the file directory tree. Any pages you create to explain windows or code should be placed under "/help/en/package/" branch based on where the actual code is stored.
    • Make sure you provide links to these pages in your general help pages.
  3. Create entries in the Hardware Index page:
    • Add a hardware listing entry and paragraph in "/help/en/html/hardware/index.shtml" following the formats and categorization of other similar hardware.
    • Add an entry for "M X" to the Category/Alphabetic Index in the appropriate place near the top of "hardware/index.shtml".
  4. Create an entry in the Supported Hardware "sidebar part":
    • Add an entry in alphabetic order for "M X" to the hardware sidebar part "/help/en/parts/SidebarSupportedHardware.shtml".
  5. Create Help TOC and Index entries:
    • Add an entry for "M X" under "Hardware Support" to the file "JMRIHelp_enTOC.xml" found in the /help/en/ directory.
    • Add one or more entries for "M X" such as "X (M)" or other helpful index items to the file "JMRIHelp_enindex.xml" found in the /help/en/ directory.
    • See the section below on Help Table of Contents and Index for additional steps to update the TOC and Index.

Following all these steps will ensure that other users will be able to find and use the new hardware you have integrated into JMRI.

[Go to top of page]

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   

If you do not have access to ant, you should use one of the HTML validation programs available online, such as from the W3C Markup Validation Service. These services will find many common errors (unmatched tags, etc.), but also sometimes give warning or even error messages that do not impact JMRI integration.

[Go to top of page]

Help 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 maintained manually 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.

[Go to top of page]

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.

[Go to top of page]

Access To Help 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.

[Go to top of page]

Updating the JMRI.org Web Site

Changes to Help pages which are checked-in should show up automatically on the JMRI.org web site after a short while. There's a Jenkins job that handles periodic updates for the static (from repository, unlike e.g. Javadoc) pages.

[Go to top of page]