Better Help with JavaHelp

Programmers find it easier to build applications than authoring help contents
required for users. The reason is simple. It requires more patience to create a
proper help system for software than creating the software itself. One has to
run up and down the programs, generate screenshots, insert hyperlinks and solve
doubts that might arise in the minds of all clients.

Authoring help content for programs has been difficult using Java. Initially,
Java programmers had to be content with text help displayed on a notepad-like
help window. Otherwise, 'javax. swing.JeditorPane' class was used to provide
HTML based help. But, JavaHelp system offers a complete help-authoring tool
which needs almost no coding. While we have omitted code from this article, you
can access the source code at http://forums.pcquest.com under the Developer
thread.

Package and architechture

JavaHelp is located in javax.help package. It's not a standard inclusion with
JDK. Download it from http://java.sun. com/products/javahelp. After downloading
and unpacking, the library part of JavaHelp system should be included in the 'classpath'
environment variable. If the extraction directory is called '{jh-directory}'
-usually c:\jh2.0-the main help library is located at {jh-directory}\javahelp\lib\
jh.jar. This JAR file should be incorporated in the CLASSPATH variable.

In Win NT/2000/XP, right click on My Computer and go to
Properties>Advanced>Environment variables. Here choose Edit if CLASSPATH
already exists, or New to create it and append. Under Win 9x and Me, type in 'set
classpath=%classpath%;{jh- directory}\javahelp\lib\jh.jar' in c:\

autoexec.bat file and reboot the computer. If you are using Linux, add 'export
CLASSPATH=$CLASSPATH: {jh-directory}/javahelp/lib/jh.jar' either in
/etc/profiles or .bash_profile (in the home directory) and login again to make
the changes effective.

You can divide the JavaHelp system into two separate parts-Non-Programming
Part and Programming Part. The non-programming part involves the creation of
HTML based help in suitably named files. After creating the HTML based help
system, XML based configuration files are to be prepared for deciding how the
HTML help should be organized. This article describes creating of help system
for a program called ClipReader, which reads the text content available on the
system clipboard. Creating HTML help is fairly simple and is not deliberated
here. We will rather focus on the configuration files and the program required
to load them. The help window contains a small left pane for topics and larger
area on the right side for displaying actual help.

Help configuration files

There are three essential configuration files. The first is the help set file
which ends with HS extension. The second is a TOC (table of contents) file with
XML extension. This file controls what topics are presented to the user, how the
help tree nodes appear (open or closed) and the type of node (parent node or
child node). The TOC doesn't use actual help filenames but logical names,
which are fictitious names. The mapping of these fictitious names into actual
HTML file names is done in the third configuration file, which usually ends with
JHM extension. In the sample implementation, the files are called
ClipReaderHelp.hs, ClipReaderHelpTOC.xml and Map.jhm.

The ClipReaderHelp.hs file contains the following sections: Title definition
(with

The map file (Map.jhm) contains one major section for mapping logical target
names into actual URL names. The

The TOC entries are in ClipReaderTOC.xml file and specified by
tag. This tag can be closed in two ways. If it's closed just at the end with a
/, like ,
the specified item is displayed as the lowest node in the help tree. If we want
to create a major node in a tree, close the tag with a corresponding
tag. For example, to create a tree with major node called

License and leaves called License for Clip Reader, FreeTTS Notification, Licesne
for JRE, License for 'JavaHelp', the definition should look like:

text="License" target="clip.license" expand =
"true"> target="clip.license"/>

Here we show the Help for ClipReader software as displayed by the Java Help System

Packing Help

These files can be packed into a .jar file or can be left as such. Packing them
can make the distribution easier and faster. Hence, we may consider creating a
.jar file by issuing the command 'jar cf Clip ReaderHelp.jar *'.

Loading Help

Loading help system requires simple coding. This code uses javax.help package.
This package contains two main classes called HelpSet and JHelp. The HelpSet
class loads the specified URL using a java.net.URLClassLoader instance. This
takes the name of help set configuration file (ClipReaderHelp.hs). Then, pass
the HelpSet instance as argument to create JHelp instance.Help information for
our case is loaded using HelpLoader.java. The class has a constructor, which
calls the method loadURLs with URL name and help set filename as arguments. The
loadURLs method creates java.net.URLClassLoader instance with URL string as
argument, then calls the static method findHelpSet of HelpSet class to get the
actual URL that points to the help set files. This URL is passed as argument
into the HelpSet constructor. HelpSet object then goes into JHelp constructor to
complete the GUI.

The JHelp instance is added into a JFrame. The HelpLoader class is so
designed that it can load any help system. The first argument to its constructor
is the name of the help set file and the second one the location of the help
file. The location can be a simple directory name or jar file name. The
HelpLoader class that extends JFrame, doesn't display help when the
constructor is called. Unsolicited help may not be worth its effort. Hence, the
help is loaded and ready, but invisible until the setVisible method is called
with true as argument.

Use Help loader

HelpLoader.java file is to be compiled by issuing the command 'javac —cp
\lib\jh.jar;. HelpLoader.java'. Running the file can be done in
three different ways. First, we can use it for displaying the help system for
ClipReader software, by issuing the command java HelpLoader. Second, we can use
it for viewing any other help system by issuing the command 'java HelpLoader
test.hs temp' or 'java HelpLoader test.hs temp.jar'. This will load the
help set file test.hs from either temp directory or temp.jar file as
appropriate. The third way of using this class is to load and display help from
within another program. In that case, the parent program should invoke
HelpLoader constructor with two arguments: the name of the help set file and the
location of the help set file (name of a directory or that of the JAR file).

V Nagaradjane