JMRI: Use of JavaHelpThis page talks about technical aspects of how JMRI provides help information using JavaHelp and JHelpDev.
Organization of the help filesThe 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:
- 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 - a version of the DecoderPro manual reformatted for use in the help system.
Limitations of JavaHelp HTMLJavaHelp 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.
- Anchor tags aren't XML. Specifically,
needs to be replaced by
The indicator that you have to do this is an < character just appearing by itself on the rendered page.
- Anchors also need to use the "name" attribute rather than the "id" attribute. See the item above for an example.
- You can't 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 web pages outside the help system work, but JavaHelp can't display PDF files. Links to those should be shown explicitly as links, so they can be copied to an outside web browser.
Web access to helpIt'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.
- 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 of the same name. This will put the proper top and bottom matter in place to get the page properly displayed.
Access in the codeWithin 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,
class inherits from JmriJFrame, and adds a help menu with the line
The help file is then located at
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 JHelpDevJavaHelp 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:
- Make sure you've run "update" from SVN before getting started.
- 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".
- Click the "Create All" button to recreate the maps, index, etc.
- 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.