Creating Effective JavaHelp

Understanding the Files in a HelpSet

Each online help project (such as the Aviation project previously illustrated) is implemented as a set of files, called the HelpSet . A HelpSet includes HTML-format topic files along with JavaHelp-specific configuration files.

The HelpSet includes three kinds of files:

• HelpSet data files

• Navigation files

• Topic files

HelpSet data files contain overall information about the structure and content of the HelpSet. These are text files, structured in Extensible Markup Language (XML) format. There are two HelpSet data files:

• The HelpSet file, with filename suffix .hs, is the HelpSet’s “master control” file. It specifies the navigation components to be used, along with the files that configure the navigation components. It also specifies the HelpSet’s map file.

  Don’t confuse the similar terms HelpSet file and HelpSet. The HelpSet is the set of all files in a particular project; the HelpSet file is the project’s master control file.

• The map file, with filename suffix .jhm, assigns a map ID (shorthand name) to each help topic. It maps ID strings to the uniform resource locators (URLs) of topic files. The HelpSet file and navigation files always use map IDs to refer to help topics; they never use the topic’s URLs directly.

The navigation files configure the HelpSet’s TOC, index, and word-search index. The TOC and index files (also in XML format) are similar in structure. The JavaHelp system reads the information in these files to know what to display in the TOC and index tabs in the navigation pane.

Note

What is the difference between “JavaHelp system” and “HelpSet”? I use the term JavaHelp system to mean the HelpSet Viewer (or a viewer embedded in another application) in action: loading a HelpSet, displaying its help topics and enabling the user to navigate between topics. The term HelpSet is just the set of files you provide to implement a particular online help project.

The word-search index is a bit more complex; it refers to a folder that contains several files. You create these files using an indexing utility Sun provides with JavaHelp. The indexing utility builds a full-text search database for the HelpSet. The database is then searched when users type in a specific word under the word-search tab in the navigation pane.

The actual topic files for a HelpSet are HTML files. You can have only one topic per HTML file because the map file assigns one map ID to one HTML file. The topic files can include images and links just as with ordinary HTML pages. Additionally, you can use controls for pop-up windows, secondary windows, and multimedia clips.