There are two primary things to consider when you set up your help system:
The JavaHelp system is file1 based--topics are contained in files that are displayed in the help viewer one file at a time. It is a good idea to group related topics together to keep them organized and to make it as easy as possible to link the topics together.
It is also important to organize topics to easily package them into a compressed JAR file for delivery to your users.
For both of these reasons, it is usually best to organize your topics in a folder hierarchy that you can "tear off" and place in the JAR file.
The following diagram shows such a hierarchy:
In most cases, the destination of a link should be specified relative to the file that contains the link. The following is an example of such a relative link:
<A HREF="../subtopicB/topic.html">new topic</A>In contrast, the following link uses a full path name to describe the path to the destination of the link:
<A HREF="C:/product/help/subtopicB/topic.html">new topic</A>
Relative links will remain valid when the topic hierarchy is packaged into a JAR file and then installed on the user's computer.
All files within the JavaHelp system are specified as URLs. The
separator between elements (files) in a hierarchy should be
"/". In some cases "\" works on the Win32 platforms, however
when the files that contain these references are added to JAR
files or moved to different platforms, these references no longer
work.
In addition to the topic files, the help information includes metadata files that contain information about the help system. Where you locate these metadata files can affect how you package, deliver, and update the help information for your users.
In JavaHelp systems there are two kinds of metadata:
Navigational data files contain information that is used by the JavaHelp system navigators. The standard JavaHelp system navigators are:
Each of these navigators has a metadata file associated with it that contains navigational data. These metadata files should be located in close hierarchical proximity to the topic files so you can conveniently package them into JAR files with the topic files for delivery to customers. The following diagram displays an example.
HelpSet data is information that the JavaHelp system needs to run your help system. It is contained in two files:
When the JavaHelp system is activated by your application, the first thing it does is read the HelpSet file. The HelpSet file contains all the information needed to run the help system. As you can imagine, your application must be able to find the HelpSet file after the product is installed on your user's system.
The HelpSet file contains the location of the map file and in most cases, the map file is read when the HelpSet is initialized. The map file is used to associate topic IDs with URLs (paths to HTML topic files).
The following diagram shows how a help hierarchy might be set up to include the HelpSet file and map file.
You will generally package your help information into JAR files for delivery to your users. Usually, you package the HelpSet file and map file in the JAR file along with the topic files and navigational files.
On JDK1.1 systems, this is the only option--applications
running on JDK1.1 (which does not support the jar:
protocol), must include all help information
(including the HelpSet file and map file) in the JAR file.
On the JavaTM 2 Platform, the jar: protocol makes other packaging options available. The inclusion or exclusion of the HelpSet and map files from the JAR file has an effect on how you deliver the help information and how you can later update it. The following two sections describe some of the issues to consider when making that decision.
Under some installation conditions, the HelpSet file could be excluded from the JAR file, while the map file is included. The following diagram illustrates this arrangement:
Note that the map file is referred to using the jar:
protocol.
The HelpSet file is the only help system file referenced explicitly by the application--the JavaHelp system derives all information about the help system from that file. If the HelpSet file is outside of the JAR file, the installation program can update the HelpSet file so the JAR files can be installed anywhere in the user's file system. This is not possible if the HelpSet file is included in the JAR file.
Another advantage of locating the HelpSet file outside of the JAR file is that it can be updated independent of the rest of the HelpSet. For example, additional help information can be added to the user's help system by adding more JAR files and updating the HelpSet file.
Excluding the map file from the JAR file is possible, but usually not useful.
If the map file is located outside of the JAR file, all URLs
in the map must use the jar: protocol. For
example:
jar:file:/c:/product/help/Ajar.jar!/File1.html
| 1 | The JavaHelp system actually deals with URLs. The URL may resolve to the contents of a file in a file system, a file on the web, a portion of a JAR file, or may even be generated dynamically by a server. |
See also: