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