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

advertisement

AddThis Social Bookmark Button

Creating an Online Help System with JavaHelp and DocBook

by Austin King
10/15/2003

Providing end-user documentation can be the difference between a polished application and a throwaway product. Communicating to non-technical end users raises the bar even higher. Now that your team has created documentation, how do you deliver it to your user base? Don't re-invent the wheel -- you can deliver professional online help with minimal work.

This tutorial introduces you to an existing toolchain that will format and present your user manual within your Java application. Open standards and open source code will be leveraged. We want to use a Java-based framework, and to keep things flexible, we will be writing and maintaining our documentation in XML. A stylesheet that is freely available will serve as the glue.

Empowered with these tools and this tutorial, you will be able to deliver an online help system with minimal effort and research time.

This is an intermediate- to advanced-level article and assumes that you have a basic understanding of XML, the ability to use a command line, knowledge of how to set environment variables and other installation techniques for your operating system, and of course, knowledge of the Java programming language. In this tutorial, we will be installing JavaHelp, Saxon, and DocBook-xsl. Links to these packages will be given as we go along, and all links are organized at the end of this article.

JavaHelp

JavaHelp is an online help framework developed by Sun Microsystems and written in the Java programming language. It uses existing W3C standards: HTML 3.2 for content and markup, and XML for metadata. It also ships with a full-text search engine.

Currently, JavaHelp is an add-on product from Sun, so you will need to download it from their web site. We will use release version 2.0 for this article. There are a few things you'll need to do before using it in a Java program.

  1. Download and then decompress the .zip file.
  2. Move the resulting directory, jh2.0, into a suitable place on your system.
  3. Add an environment variable, JAVAHELP_HOME, and set it to the directory where you unzipped.
  4. Add jhall.jar to your CLASSPATH.
  5. Add JavaHelp's bin subdirectory to your PATH environment variable.

Here's what the last three steps look like in bash or similar shells:

export JAVAHELP_HOME=/usr/java/jh2.0
export CLASSPATH=$CLASSPATH:$JAVAHELP_HOME/javahelp/lib/jhall.jar
export PATH=$JAVAHELP_HOME/javahelp/bin

or, on Windows:

SET JAVAHELP_HOME=C:\java\jh2.0
SET CLASSPATH=%CLASSPATH%;%JAVAHELP_HOME%\javahelp\lib\jhall.jar
SET PATH=%PATH%;%JAVAHELP_HOME%\javahelp\bin

You have probably used online help systems many times, but let's refresh our memories and check out what JavaHelp has to offer. Sun has cleverly packaged their User's Guide into a JavaHelp "help set". Execute this UserGuide.jar as follows:

java -jar $JAVAHELP_HOME/demos/bin/UserGuide.jar

or, on Windows:

java -jar %JAVAHELP_HOME%\demos\bin\UserGuide.jar

The UserGuide application will appear in a new window, as shown in Figure 1.

Screenshot of JavaHelp
Figure 1. JavaHelp User's Guide shown in JavaHelp browser

What we are now looking at is the typical two-paned window layout. By clicking the tabs on the left pane, we can look at the Table of Contents, Index, Favorites and Search views. The pane on the right displays the actual contents for the topic you have selected.

So we have an idea of what we want our online help to look like, but where do we start?

Related Reading

DocBook: The Definitive Guide
By Norman Walsh, Leonard Muellner

Writing the Manual

We could author our help files directly in HTML, one page per topic. We would then have to create the following metadata files:

  • A helpset file, to describe what kinds of navigation (table of contents, index, etc.) are provided.
  • A map file to map topic IDs to URLs of topic files.
  • A table of contents (TOC) file.
  • An index file, to provide the index.

However, creating and maintaining all of those files is a lot of work and prone to human error. Wouldn't it be nice to have a more semantically valuable way to mark up our content and let a program process it into our target framework?

DocBook is a standard format defined in both XML and SGML for writing books, articles, and especially technical documentation. We will use the XML "book" subset of DocBook. Although the DocBook DTD is vast, you don't need to learn every element in order to mark up your documents. We will focus on a small subset that is sufficient for delivering our online help system. We will be using Version 4.1.2, as maintained by the OASIS group.

As an example, I have created a User's Manual for the FooMatic 5000. You can download the entire example.xml. Below we will examine important fragments to learn how to mark up your documentation.

First, we include the standard XML declaration and doctype declaration:

<?xml version="1.0" standalone="no"?>
<?!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/DocBook/xml/4.1.2/DocBookx.dtd">
<book>

Next, we open the document with a <book> element. Our entire manual will be a child of this book element. This example is a single file, but for large manuals, you can obviously break up the file using standard XML inclusion techniques.

The first child of the book element is the bookinfo element, which sets the title to "FooMatic 5000."

<bookinfo>
    <title>FooMatic 5000</title>
</bookinfo>

This becomes the name of our helpset. Here you may also add copyright, authorship, and other information.

Next we add a chapter element. Chapters become top-level nodes in our JavaHelp set.

<chapter>
    <title>Quick Start</title>
    <para>You know you can't wait!
     Let's get started.</para>
</chapter>

This makes "Quick Start" the first item in the list of our help set's contents view. We can also create chapters with a deeper structure:

<chapter>
   <title>How Do I...</title>
    <section>
      <title>New File</title>      
      <section>
	      <title>New Foo</title>
	      <para>New Files can be created 
              by going to the
              file menu...</para>
      </section>
      <section>
	      <title>New Bar</title>
      </section>
  </chapter>

In this chapter, we have nested section elements to further break up a chapter into logical pieces. In this case, we have grouped together different actions. Sections create nodes in our table of contents and allow the user to drill down into the subject matter they need.

Sections contain paragraphs, which look like this:

<para><indexterm>
<primary>Importing</primary> an 
    <secondary>alien</secondary> 
    file format from </indexterm> 
    our competitors file formats has never...
<!-- more content -->

Here we mark up an important term or phrase inside of indexterm and primary tags (there are also secondary and tertiary tags for providing more context). Later, we will see these elements automagically create an entry in our JavaHelp index view.

The link tag is used to refer to another DocBook element by ID:

<para>Now that we have finished 
    installing, let's learn about some <link 
    linkend="concepts">Concepts</link> 
    used in FooMatic 5000</para>
  </chapter>
  <chapter id="concepts">
    <title>Concepts</title>
 ...<!-- more content -->
</book>

In our chapter tag, we have set the attribute id to "concepts", which creates a target for the earlier link. When transformed by the JavaHelp stylesheets, these links will become anchor tags in HTML. Lastly, notice that we have finished our document with a closing book tag.

With just these few simple tags -- book, bookinfo, title, chapter, para, section, indexterm, primary, and link -- we have all of the tools we need for a simple help system. Other useful tags are tip, ulink, and screenshot.

Groovy, but how do we massage our DocBook file into JavaHelp? Somehow we need to metamorphose our single document into all of the files that make up the JavaHelp set.

Pages: 1, 2

Next Pagearrow