ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

Creating an Online Help System with JavaHelp and DocBook
Pages: 1, 2

DocBook, XSL, and Saxon

DocBook XSL StyleSheets are a collection of stylesheets that allow you to transform your XML into PDF, HTML, and more importantly, JavaHelp format. This ability to derive JavaHelp and PDF from the same source is an extra bonus to us! With this approach, there is little added maintenance for delivering help in several formats to your users. This DocBook-xsl package is actually a set of stylesheets, so we also need an XSLT style engine to drive the transformations. We will be using the open source tool Saxon.

To get these tools:

  1. Download and decompress the DocBook-xsl 1.61.3 file from SourceForge.net and put it somewhere convenient on your system.
  2. Download Saxon 6.5.2 from their page on SourceForge.net. Decompress the file and put saxon.jar into your CLASSPATH environment variable.

For convenience you may set an environment variable, DOCBOOK_XSL_HOME, for DocBook, and you need to put saxon.jar in your CLASSPATH:

export DOCBOOK_XSL_HOME=/usr/local/DocBook-xsl-1.61.3
export CLASSPATH=$CLASSPATH:/usr/java/jar/saxon.jar

or, on Windows:

SET DOCBOOK_XSL_HOME=C:\local\DocBook-xsl-1.61.3
SET CLASSPATH=%CLASSPATH%;C:\java\jars\saxon.jar

Now that we have installed these libraries, we can use Saxon to generate our JavaHelp files from the DocBook markup (note that these commands should all be on one line):

java com.icl.saxon.StyleSheet example.xml 

or, on Windows:

java com.icl.saxon.StyleSheet example.xml 

This will create the following output:

Writing ch01.html for chapter
Writing ch02.html for chapter
Writing ch03.html for chapter
Writing ch04.html for chapter(concepts)
Writing ch05s02.html for section
Writing ch05s03.html for section
Writing ch05s04.html for section
Writing ch05.html for chapter
Writing index.html for book
Writing jhelpset.hs
Writing jhelptoc.xml
Writing jhelpmap.jhm
Writing jhelpidx.xml

It seems a bit too easy, but we are really 90% complete. If we take a moment to think about the amount of time and effort we will save on creating and maintaining all of this HTML, we can see that it is worth the time of installing this toolchain. Examine the new files Saxon has created in a text editor. The files with the html extension are the contents of your help system, formatted in HTML 3.2 format. The reason for this older doctype is that JavaHelp displays these files with a JEditorPane, which can only handle 3.2 format. Swing's support for HTML is still maturing, but for most help systems, HTML 3.2 is adequate.

As for the other files, jhelpmap.jhm is a mapping file between JavaHelp's internal naming system, and the URLs and anchor names of your content. These system names are called "mapIDs". The jhelptoc.xml file describes our table-of-contents tree as it appears in the Contents view of our online help. jhelpidx.xml is a list of index terms and their corresponding mapIDs. Lastly, jhelpset.hs is our entry point from the JavaHelp framework point of view. This file references our map, TOC, index, and which search engine implementation to use.

Did someone say search? If you look in the current directory, you will see many new files. We need to index our HTML pages for our search engine. From the current directory, execute:

jhindexer.sh .

This creates a new directory called JavaHelpSearch, which contains all of the data files that the default search engine requires.

If you can't wait to see what your help files look like, JavaHelp has another demo called hsviewer.jar. Invoke it from the command line (again, all on one line):

java -jar $JAVAHELP_HOME/demos/bin/hsviewer.jar
   -helpset /path/to/current/directory/jhelpset.hs

or, on Windows:

java -jar %JAVAHELP_HOME%\demos\bin\hsviewer.jar 
   -helpset C:\path\doc\test\jhelpset.hs

This brings up your help set in the JavaHelp viewer, as seen in Figure 2.

Screenshot of FooMatic 5000
Figure 2. Screenshot of example help set FooMatic 5000

Easy huh? Let's wire up JavaHelp to our application. In the next section, we will add a new ActionListener that shows our help set when the user clicks on a menu item.

Integrate JavaHelp into our Application

In terms of integrating up our online help, the most important file that has been created is jhelpset.hs. If you open this file in a text editor, you will see that it is an XML file that tells JavaHelp where to find various pieces of our help set, including jhelpmap.jhm. This map file contains mapID elements and locations, which are your various HTML documents.

The JavaHelp API has three main classes that you will be using to leverage the framework: javax.help.HelpSet, javax.help.HelpBroker, and javax.help.CSH.DisplayHelpFromSource. The HelpSet represents our content and metadata that we generated from our DocBook. A HelpBroker is responsible for determining what to show, based on a HelpSet and a given mapID (which is basically an atomic piece of help). CSH.DisplayHelpFromSource is a convenience class that implements the java.awt.event.ActionEventListener interface and sets the system into motion upon callback.

//import help classes
import javax.help.*;
import javax.swing.*;
import java.net.URL;

String hsName = "myHelpSet.hs";

//Somewhere in your class
try {

    ClassLoader cl = 
    URL hsURL = HelpSet.findHelpSet(cl,
    hs = new HelpSet(null, hsURL);
} catch (Exception ee) {
    System.out.println ("HelpSet "+
        hsName + " not found");
hb = hs.createHelpBroker();
JMenu help = new JMenu("Help");
menu_help = new JMenuItem("Contents");
    new CSH.DisplayHelpFromSource(hb) );

In this example, JavaHelp searches the classpath for a HelpSet called myHelpSet.hs. If it is found, a HelpBroker is created. From that, we can create the CSH.DisplayHelpFromSource, which is an ActionListener that can be added to a JMenuItem, in this case the "Contents" menu item in the "Help" menu.

All of the files relating to your new help system should be distributed with your application. If you .jar them up with your other resources, then a ClassLoader will be able to find and display the help set's pages, images, and data. JavaHelp is an add-on that your users may not have installed, so you will probably want to ship jh.jar and jsearch.jar with your application.

For further examples, open up the Java source files that ship with JavaHelp under the demos/src directory.


We have learned the basic techniques and API involved with integrating a JavaHelp system into your Java application. This is a brief tutorial, but JavaHelp, Saxon, and DocBook-xsl all have documentation under their respective directories. If DocBook has piqued your curiosity, Norman Walsh's DocBook: The Definitive Guide is an excellent reference. I encourage you to experiment with more DocBook tags, or customize the JavaHelp XSL stylesheets to your liking.

Related Resources

Austin King is a developer living and working in Seattle Washington, working with web applications, Open Source, and documentation tools.

Return to ONJava.com.