Developing and Delivering Better Documentation with the JavaHelp System

Print-friendly Version

An online help system is an integral part of any software system. Help systems provide intuitive help information facilities that allow its users to navigate, search, and display help information, and can aid users in learning how to use the system and thus reduce the learning cycle for many applications. Traditionally, however, Java developers have had to create their own custom help systems from scratch as there was no help system integrated into the Java language. Such development is costly and time-consuming.

With JavaHelp technology, developers no longer need to invent their own help systems for each platform the application will run on. It is designed to meet the needs of today's industrial-strength applications.

This article provides a tutorial and step-by-step instructions on how to use the JavaHelp system to deliver better help information for your software systems. It provides:

• A description of alternatives for implementing help information
• An introduction to JavaHelp technology
• Discussion of features and benefits of JavaHelp technology
• A flavor of the effort involved in developing help information
• Sample code that you can adapt to your own applications

Help Systems Alternatives

Java developers have the following options for implementing a help system for their applications:

• No help system: Let users figure out how everything works. A software system, however, is incomplete without its documentation, help information system, or manual. Not only it is incomplete, but it will frustrate its users. Just imagine using Adobe Photoshop without a manual!
• Use HTML: This is a low-cost option, but is limited in terms of capabilities and navigation.
• Custom system: This is a high-cost option, both in terms on resources and time.
• Third-part proprietary solution: This is a viable alternative to the custom system; however, it has its own consequences, including: cost and long term support. What do you do if the software vendor goes bankrupt?

That is why JavaHelp technology was designed.

JavaHelp Technology

JavaHelp is an extensible, platform-independent help system that enables authors and developers to incorporate online help into applets, applications, operating systems, and devices. It can also be used to deliver online documentation for the Web and corporate Intranet. It is designed to be network-centric where help data and search functionality can be on the client- or server-side, and help data can be dynamically updated over the Web.

The JavaHelp system is written in Java, and therefore runs on any platform or browser that supports the Java Runtime Environment (JRE). This means it can be used in a heterogeneous environment such as the Web or corporate Intranets. In addition, it can be used to develop and present online help for any software application and not just those applications developed in Java. Also, it can be used on its own without associating it with any software -- just as a delivery mechanism for Web-centric documentation in categories such as human resources, technical support, etc.

JavaHelp 1.0 was first released in 1999, and this means that this technology is mature. The JavaHelp 2.0 technology is designed by Java Community Process (JCP) as JSR-97. This means that unlike WinHelp, JavaHelp offers the cross-platform advantage of HTML content, as it doesn't lock companies into a single platform. It is important to note that the JavaHelp system can be used to deliver and present online help for any software application, and not just Java-based applications, deployed on any platform.

The JavaHelp system has received widespread support from the industry as well as leading help authoring tool vendors.

JavaHelp Features and Benefits

JavaHelp provides several features that are useful for authoring documentation. In addition, there are reusable components that save Java developers lots of time re-inventing the wheel. Some JavaHelp features are:

• Help Navigators: Table of contents (TOCs) support a collapsible and expandable display of topics, unlimited number of hierarchical levels, and merging of multiple TOCs; an index supporting merging of multiple indexes; and full-text search that is flexible and configurable.
• Compression: A JavaHelp-based help system can be compressed and encapsulated in a single Java ARchive (JAR) file.
• Extensible and Customizable: The JavaHelp APIs can be used to customize or extend the user interface and its functionality. Extensions can be custom navigation, or even voice and sound. This gives authors great flexibility and control in designing help systems.
• Context-Sensitive Help: This is provided through Swing.
• Merging Capabilities: Multiple help components can be merged before they are presented to the user.
• Dynamic Updating: Allows an online help system to be dynamically updated after it has been released.
• Adaptable: It enables help systems to be adaptable in presenting and displaying information. This is especially useful when the final deployment environment is not known ahead of time.
• Localizable: Java supports internationalization (I18N), and therefore the JavaHelp system can be easily localized into international markets.

Deployment and Operating Scenarios

JavaHelp technology offers authors and developers several options for deploying or invoking it from within applications. It is network-centric, so that it can be launched independently of the application it supports. It can even be embedded within the application. And since it is written in Java, it is platform- and browser- independent and can run on any platform and browser that supports the Java Runtime Environment (JRE). This makes it ideal for use in today's heterogeneous computing environment.

Here are some scenarios where JavaHelp can be deployed to present help information:

• Standalone applications: This is a local application that runs on the desktop without the need for a browser. The JavaHelp help viewer can be launched as a separate application or one that is embedded within the application itself.
• Network applications: These are network applications that fetch data from remote servers. It is possible for the JavaHelp system to load its help information from remote servers. This is useful for software vendors so they can provide their customers with a lightweight client application that fetches the help information from remote servers. Vendors can change help information as they wish, without having to ship a new release.
• Applets: Mini applications that run within a web browser. The JavaHelp system itself can be part of the browser and the help data may or may not be part of the application.
• Server-based Applications: This is an application that runs on a Java server but uses the browser for its GUI.

The Reference Implementation

Sun Microsystems provides a Reference Implementation (JavaHelp System), which implements the JavaHelp specification. It is mature, robust, reliable, and can be used by developers. The JavaHelp System can be downloaded from http://java.sun.com/products/javahelp. You should download the latest release, which is 2.0_01.

The reference implementation comes in a zip archive and can be easily installed simply by unpacking the distribution in a directory of your choice. If you choose c:\ on Windows as the destination, it will be installed under c:\jh2.0.

The reference implementation comes with documentation, tools, and several demos. The binary demos are located at c:\jh2.0\demos\bin, and you can easily run them using java -jar demoName.jar. In addition to the demos, the directory c:\jh2.0\javahelp\bin contains the jhindexer and jhsearch tools, which are used for creating an index database and searching, respectively. Finally, the directory c:\jh2.0\javahelp\lib contains the JAR files of the JavaHelp APIs, which are:

• jh.jar: The standard library that includes everything needed to use the standard navigators (table of contents, index, full-text search).
• jhbasic.jar: A subset of jh.jar that doesn't include support for the full-text search engine. This might be useful for help information systems where the size is critical, or systems that do not require full-text search databases.
• jhall.jar: Contains all the JavaHelp system classes as well as the tools required to create a search database.
• jsearch.jar: Contains the full-text search engine that is used in the JavaHelp system.

JavaHelp Help Viewer

One of the interesting demos that comes with the reference implementation is the help viewer (c:\jh2.0\demos\bin\hsviewer.jar), which is a helpset viewer that can be used to view the help information we will be developing later in this article. It is worth noting that it is 508 compliant.

The standard viewer, as shown in Figure 1, consists of a toolbar (that can be used to display various buttons such as Back, Forward, Print, etc) and two panes:

1. Content pane: Displays help topics formatted using HTML and frames, tables, and lightweight components
2. Navigation pane: A tabbed interface that allows users to switch between table of contents, index, and full text-search displays. It is worth noting that navigators are synchronized with the content viewer, so the user is always aware of the relative location and options

Figure 1: JavaHelp Standard Viewer Click to enlarge

Authoring Help Information

In order to develop help information using the JavaHelp system, the help author is required to create the metadata files that the JavaHelp system uses to present information. In addition, the help author is required to create the topics that inform the application's users. The metadata and topics files are known as a helpset. Some help authoring tools simplify the task of creating such helpsets, but in this article we will create them ourselves.

The genesis of creating a helpset consists of the following steps:

1. Create HTML topics using your favorite editor
2. Create a helpset file
3. Create a map file
4. Create a table of contents
5. Create an index file
6. Create a full-text search database
7. Compress and encapsulate the help files into a JAR file for deliver to customers

Note that steps 5 and 6 are necessary only if you wish to have an index and a full-text search database integrated with your help information system.

To view your helpsets, a helpset viewer is provided with the RI. The helpset viewer is located at c:\jh2.0\demos\bin\hsviewer.jar

When the viewer opens click on "Browse" to navigate to a helpset (has the extension .hs). Alternatively you can view it as follows:

java -jar c:\jh2.0\demos\bin\hsviewer.jar -helpset c:\PathToMyHelpSet.hs

The Java Help system is file-based in the sense that help topics are contained in files that are displayed in the help viewer one file at a time. Related topics should be grouped together in order to keep them organized and so that it is easy and possible to link them together. It is best to organize your help topics in a folder hierarchy that you can easily copy and place in a JAR file. Links from one topic to another should be specified relative to the file that contains the link, and absolute paths shouldn't be used. Also, you should use the forward slash "/" as the file separator. Here is an example:

<a href="../subtopicC/topic.html">New Topic</a>

1. Create HTML topics The actual help information is created using HTML; the helpset viewer is able to parse and render HTML. Your HTML files can contain links to other files as well as images. Code Sample 1 shows the welcome.html sample:

Note: The HTML rendering engine is a JRE component and not part of JavaHelp, and therefore rendering can vary a bit depending on the version of Java used. The rendering engine only displays HTML 3.2 (with a few 4.0 features). It does, however, include support for a CSS1 stylesheet.

Code Sample 1: welcome.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>
Help Overview
</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<H1>My Sample Online Help</H1>
This help system is organized into the following main
<br>
topics. You can access these topics directly from the  
<br>
Help menu.
<p>
<table width=98% border=0 cellpadding=5>
<tr valign="top">
<td width=30%><A HREF="manager.html">Managing Projects</A>
</td>
<td width=70%>
How to create and use projects and
<br>portfolios
</td>
</tr>

<tr valign="top">
<td width=30%><A HREF="debug.html">Debugging Projects</A>
</td>
<td width=70%>
How to debug Java programs
</td>
</tr>

<tr valign="top">
<td width=30%><A HREF="profile.html">Profiling Projects</A>
</td>
<td width=70%>
How to analyze the performance of
<br>
Java programs
</td>
</tr>
</table>

</ul>

<hr>
<pre>
<font size="-1">
Some Copyright Information Goes Here!
</font>
</pre>
<hr>
</BODY>
</HTML>

2. Create the Helpset File
The helpset file is the only file referenced explicitly by the application. The JavaHelp system derives all the needed information about the help system from that file. When the JavaHelp system is activated by an application, it starts by reading the helpset file, which is the set of data that comprises the help system, and includes the following information:

• Map file: Used to associate topic IDs with URL or path name of HTML topic files.
• View information: Describes the navigators being used in the helpset. The standard navigators are: table of contents, index, full text-search. Additional navigators include the glossary and the favorites navigators.
• Helpset title: The <title> defined in the helpset file, and it appears at the top of the main windows and any secondary windows defined in your helpset file.
• Home ID: the name of the default ID displayed when the help viewer is called without specifying an ID.
• Presentation: The window in which to display the help topics. The <presentation> tag is used to define the windows used in the helpset.
• Sub-helpsets: This is an optional section to include sub-helpsets that can be automatically merged into the helpset that contains it.
• Implementation: This is an optional section to create a registry that provides key data mapping to define the HelpBroker class.

A sample helpset file, Sample.hs, is shown in Code Sample 2:

Code Sample 2: Sample.hs

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE helpset
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN"
         "../dtd/helpset_2_0.dtd">

<helpset version="1.0">

  <!-- title -->
  <title>My Sample Help - Online</title>

  <!-- maps -->
  <maps>
     <homeID>top</homeID>
     <mapref location="Map.jhm"/>
  </maps>

  <!-- views -->
  <view>
    <name>TOC</name>
    <label>Table Of Contents</label>
    <type>javax.help.TOCView</type>
    <data>SampleTOC.xml</data>
  </view>

  <view>
    <name>Index</name>
    <label>Index</label>
    <type>javax.help.IndexView</type>
    <data>SampleIndex.xml</data>
  </view>

  <view>
    <name>Search</name>
    <label>Search</label>
    <type>javax.help.SearchView</type>
    <data engine="com.sun.java.help.search.DefaultSearchEngine">
      JavaHelpSearch
    </data>
  </view>

  <presentation default="true" displayviewimages="false">
     <name>main window</name>
     <size width="700" height="400" />
     <location x="200" y="200" />
     <title>My Sample Help - Online</title>
     <image>toplevelfolder</image>
     <toolbar>
	<helpaction>javax.help.BackAction</helpaction>
	<helpaction>javax.help.ForwardAction</helpaction>
	<helpaction>javax.help.SeparatorAction</helpaction>
	<helpaction>javax.help.HomeAction</helpaction>
	<helpaction>javax.help.ReloadAction</helpaction>
	<helpaction>javax.help.SeparatorAction</helpaction>
	<helpaction>javax.help.PrintAction</helpaction>
	<helpaction>javax.help.PrintSetupAction</helpaction>
     </toolbar>
  </presentation>
  <presentation>
     <name>main</name>
     <size width="400" height="400" />
     <location x="200" y="200" />
     <title>My Sample Help - Online</title>
  </presentation>
</helpset>

As you can see from Code Sample 2, each windows is defined by its own <presentation> tag. The presentation tags include:

• <name>: Names the window so that it can be called by name from a Java program.
• <size>: Specifies the size (width and height) of the window in pixels.
• <location>: Specifies the position of the window using the horizontal (x) and vertical (y) coordinates.
• <title>: Defines the text that appears in the title bar at the top of the window.
• <toolbar>: Indicates that that window is to have a toolbar. Buttons on the toolbar are defined using a <helpaction> tag for each action and a Java class name for the action. As an example, this piece of code: <helpaction>javax.help.PrintSetupAction</helpaction> defines a print setup action so that the user would be able to setup/select a printer.

3. Create a Map File
After reading the helpset file, the JavaHelp system reads the map file listed in the helpset. The map file is used to associate topic IDs with paths to HTML topics files using URLs. Code Sample 3 shows a sample map file:

Code Sample 3: Map.jhm

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE map
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"
         "http://java.sun.com/javase/technologies/desktop/javahelp/map_1_0.dtd">

<map version="1.0">
	<mapID target="toplevelfolder" url="images/toplevel.gif" />
	<mapID target="top" url="help/welcome.html" />

	<mapID target="intro" url="help/welcome.html" />
	<mapID target="start" url="help/start.html" />
        <mapID target="overview" url="help/welcome.html" />
	<mapID target="one" url="help/start.html" />
	<mapID target="two" url="help/start.html" />

	<mapID target="bean.story" url="help/welcome.html" />
	<mapID target="bean.story" url="help/start.html" />
	<mapID target="bean.story" url="help/welcome.html" />
</map>

4. Create a Table of Contents File
The table of contents file describes the TOC to be displayed in the TOC navigator and the layout of the TOC. A sample table of contents file is shown in Code Sample 4.

Code Sample 4: SampleTOC.xml

<?xml version='1.0' encoding='ISO-8859-1'  ?>
<!DOCTYPE toc
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 2.0//EN"
         "../dtd/toc_2_0.dtd">
<toc version="2.0">
<tocitem text="My Sample Help" image="toplevelfolder">

   <tocitem text="Introduction to Sample Online Help" target="intro"/>

   <tocitem text="Tutorial" target="start" expand="true">
       <tocitem text="Welcome" target="overview"/>
       <tocitem text="Tutorial One: Help One" target="one"/>
       <tocitem text="Tutorial Two: Help Two" target="two"/>
   </tocitem>

   <tocitem text="Beans In IDE" target="bean.story"/>
   <tocitem text="Beans In IDE - in SecondaryWindow" target="bean.story" //
presentationtype="javax.help.SecondaryWindow" presentationname="main"/>
   <tocitem text="Beans In IDE - in Popup" target="bean.story" presentationtype="javax.help.Popup"/>
</tocitem>
</toc>

This sample table of contents would be rendered as shown in Figure 2.

Figure 2: Sample Table of Contents

5. Create an Index File
The index file describes to the index navigator the content and layout of the index. Code Sample 5 shows a sample index file.

Code Sample 5: SampleIndex.xml

<?xml version='1.0' encoding='ISO-8859-1'  ?>
<!DOCTYPE index
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN"
         "http://java.sun.com/javase/technologies/desktop/javahelp/index_1_0.dtd">

<index version="1.0">
   <indexitem text=".prof extension (profile data)" target="prof.profile"/>
   
   <indexitem text="accelerators (keyboard), see 'keyboard commands'"/>
   
   <indexitem text="adding an existing project" expand="false">
      <indexitem text="naming the project" target="proj.importdirectory"/>
      <indexitem text="naming the storage directory" target="proj.importdirectory"/>
      <indexitem text="procedures for" target="proj.importproject2"/>
   </indexitem>
   
   <indexitem text="arguments" expand="false">
      <indexitem text="passing" target="debug.arguments"/>
      <indexitem text="specifying" target="debug.arguments"/>
   </indexitem>

   <indexitem text="beans" expand="false">
      <indexitem text="adding existing sources to a bean project" target="proj.existingbeans"/>
      <indexitem text="changing bean file status" target="proj.existingbeans"/>
      <indexitem text="creating a bean project" target="proj.beansproject"/>
      <indexitem text="removing existing sources from a bean project" target="proj.existingbeans"/>
   </indexitem>
   
</index>

This sample index file would be rendered as shown in Figure 3.

Figure 3: Sample index file

Seeing is Believing
At this point you are ready to see the help information you have created. The easiest way to experiment with this is by following these steps:

1. Create a directory under c:\ and call it whatever you like. For the purpose of demonstration, I will call the directory myhelp.
2. Copy the files: Sample.hs, map.jhm, SampleTOC.xml, SampleIndex.xml into the myhelp directory
3. Create a subdirectory of myhelp and call it help
4. Copy the file welcome.html into that subdirectory
5. Run the following command (helpset viewer) to view the help information you have created above

prompt> java -jar c:\jh2.0\demos\bin\hsviewer.jar -helpset c:\myhelp\Sample.hs

If all goes well, you should see something similar to Figure 4.

Figure 4: Sample Help Information Click to enlarge

As I have mentioned above, you can encapsulate and compress all the help information files into a single Java ARchive (JAR) file. Here is how to do that:

c:\myhelp> java -cvf help.jar *

Now, you can view the help system using the following command:

prompt> java -jar c:\jh2.0\demos\bin\hsviewer.jar -helpset c:\myhelp\help.jar

Creating the Full-Text Search

The full-text search engine uses a natural language search technology that, in addition to retrieving documents, locates specific passages within those documents where answers to queries may be found. It includes a conceptual indexing engine that analyzes the documents to produce an index of their content, and a query engine that uses the index to find relevant passages in the material.

The search database is created using the jhindexer command. This will create six files under the directory JavaHelpSearch. This is located in the same folder as the rest of the metadata files. As an example, suppose you have three subdirectories of that folder called "topic-a", "topic-b", and "topic-c". These topics would be specified as arguments to the jhindexer command:

jhindexer topic-a topic-b topic-c

When it finishes creating the database, it will be saved under JavaHelpSearch.

To verify it is a valid database, issue the following command:

jhsearch JavaHelpSearch

You should see:

initialized; enter query

Now enter a query or a term to search for or a dot . to quit.

Adding JavaHelp to Applications

Now that you have developed a help information system for your application, the next logical question is how to add this to your application. The amount of code needed to integrate the help information system into your applications depends on whether you wish to have the help information system as part of the application or simply as another standalone window that is displayed when the user clicks on the help button, for example. In either case, however, adding JavaHelp to an application is as easy as 1-2-3:

1. Create HelpSet and HelpBroker objects.
2. Assign the help to the individual components.
3. Add the appropriate help callback for the individual components.

Code Sample 6 shows how to add the help information system developed above to an application so that when the help menu item is selected, the help information window is displayed. As an exercise, you may want to re-engineer the code so that it can be easily integrated in any application.

Code Sample 6: HelpMenu.java

import java.net.*;
import javax.help.*;
import javax.swing.*;
import java.awt.event.*;

public class HelpMenu {
   JFrame f;
   JMenuItem topics;

   public HelpMenu() {
     f = new JFrame("Menu Example");
     JMenuBar mbar = new JMenuBar();
     
     // a file menu
     JMenu file = new JMenu("File");
     JMenu help = new JMenu("Help");

     // add an item to the help menu
     help.add(topics = new JMenuItem("Help Topics"));

     // add the menu items to the menu bar
     mbar.add(file);
     mbar.add(help);

     // 1. create HelpSet and HelpBroker objects
     HelpSet hs = getHelpSet("sample.hs"); 
     HelpBroker hb = hs.createHelpBroker();

     // 2. assign help to components
     CSH.setHelpIDString(topics, "top");
     
     // 3. handle events
     topics.addActionListener(new CSH.DisplayHelpFromSource(hb));

     // attach menubar to frame, set its size, and make it visible
     f.setJMenuBar(mbar);
     f.setSize(500, 300);
     f.setVisible(true);
   }

   /**
    * find the helpset file and create a HelpSet object
    */
   public HelpSet getHelpSet(String helpsetfile) {
      HelpSet hs = null;
      ClassLoader cl = this.getClass().getClassLoader();
      try {
        URL hsURL = HelpSet.findHelpSet(cl, helpsetfile);
        hs = new HelpSet(null, hsURL);
      } catch(Exception ee) {
        System.out.println("HelpSet: "+ee.getMessage());
        System.out.println("HelpSet: "+ helpsetfile + " not found");
      }
      return hs;
   }

   public static void main(String argv[]) {
      new HelpMenu();
   }
}

The easiest way to experiment with this code is to copy HelpMenu.java to c:\myhelp. Compile it and run it. If all goes well, you should see something similar to Figure 5. If you click on Help Topics, the help information windows in Figure 4 will be launched.

Figure 5: Clicking on Help Topics invokes the helpset viewer Click to enlarge

Server-Based Help

One of the new features in JavaHelp 2.0 is server-based help. This an important feature that allows JavaHelp to provide help information for web-based applications in a browser window. Help information can now be easily added to web-based applications using the new JavaHelp JST tag libraries. This works as follows: when a browser initiates a JSP request, the Java server turns the request into a Java Servlet that accesses the appropriate information from the helpset using the classes in the JavaHelp library (jh.jar) and the JavaHelp tag library (jhtags.jar), and returns HTML and possibly JavaScript or dynamic HTML to the browser. Figure 6 shows sample help information for a Web-based application.

Figure 6: Server-based help Click to enlarge

For more information on server-based help, please refer to the JavaHelp 2.0 specification.

Conclusion

The JavaHelp API is the technology of choice of authors and developers of online help information systems that need to run in a heterogeneous environment. The JavaHelp system allows developers to add value, and deliver complete software applications, without an enormous investment in programming and development. In addition, many companies have endorsed JavaHelp and plan to use the APIs to establish a uniform interface for displaying and navigating through internal and external documents.

The code samples in this article demonstrate the effort involved in creating help information documents that can be easily integrated into new and existing applications.

See Also

JavaHelp Homepage
JSR 97: JavaHelp 2.0 Specification
Download the JavaHelp System
JavaHelp Authoring Tools
JavaHelp-Interest Archives

Acknowledgments

Special thanks to Roger Brinkley and Larry Hoffman of Sun Microsystems, whose feedback helped me improve this article.