There are two primary things to consider when you set up your help projects:
The JavaHelp system is file-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.
| |
The JavaHelp system uses URLs. A URL can resolve to the contents of a file in a file system, a file on the web, or a portion of a JAR file, or it can even be generated dynamically by a server. |
You might also consider organizing topics to make it easy to package them into a compressed JAR file for delivery to your users.
For both 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:
The destination of a link to another topic in the helpst 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>Do not specify links to other topics by using an absolute link. For example, the following link uses a full path name to the destination of the link:
<A HREF="C:/product/help/subtopicB/topic.html">new topic</A>
Only relative links remain valid when the topic hierarchy is packaged into a JAR file and then installed on the user's computer.
All files in a JavaHelp system are specified as URLs, which use the forward slash ("/") as the separator between elements (files) in a hierarchy. Although in some cases a backslash ("\") works on Windows platforms, if files that contain such references are installed on a different platform, the 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 proximity to the topic files to make it easier to 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 can 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. For more information on packaging helpsets, see JAR Files.
See also: