JMRI Code: Creating Help Pages and Using JavaHelp
Organization of the help Files
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
jmri.jmrit.speedometer.SpeedometerFrameclass (from the
src/jmri/jmrit/speedometer/SpeedometerFrame.javafile) should have its window-specific help in a file at
- 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.
Web Access to Help Pages
- 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, you can include the Sidebar.shtml from the parent directory but ONLY if that file does not have any relative URLs (URLs with "../" and similar). It is does, the sidebar links will not work when incorporated into your page. Look at the contents of Sidebar.shtml in the parent directory before attempting to reference it.
- 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.
Standards for and Limitations of JavaHelp HTML
- 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
%20in 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:
- 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.]
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":
- 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.]
- 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.
- 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".
- 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".
- 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.
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:
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.
Help Table of Contents and Index
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.
Creating the control files with JHelpDev
JHelpDev is now included in the JMRI dist. To use the tool:
- Make sure you've updated to the most recent version in the code repository before getting started.
- You can run in batch mode by running
antfrom 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.
- 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.)
- 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)
- 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".
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.
- 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.
- Click the "Create All" button to recreate the TOC, Index, etc.
- 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.
Access To Help in the Code
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
inherits from JmriJFrame, and adds a help menu with the
addHelpMenu("package.jmri.jmrit.simpleclock.SimpleClockFrame", true);The help file is then located at
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.
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.