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
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
class (from the
file) 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
- 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
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
- 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.
[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
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
<pre> element, but you can't use
<code> is good for
highlighting in-line text as being code (like we've used it
<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
- When describing a sequence of user actions or pulldowns, use the double right arrow to indicate
sequence, HTML 4 tag ampersand-rArr-semicolon, and label the whole sequence as "strong":
File ⇒ Store Panels
A non-blanking space can be used before the right arrow to control line breaks.
- 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
[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":
- 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
- 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
[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:
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
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
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
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
- 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
from the command line in the
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
- 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,
- 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
inherits from JmriJFrame, and adds a help menu with the
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
[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]