Introduction
{literal}As more and more features get added to your software, the Help system for the software becomes extensive. It could probably contains hundreds of HTML files plus a similar number of images. We could always face the problems listed below.
- There could be broken links in the help index.
- Some files may not be listed in the index, therefore they can not be read by the customers.
- Some of the contextual help buttons could show the wrong topic.
- Some of the HTML files can contain broken links or incorrect image tags.
- Not all of the file titles would match their index entry.
Another problem could occur when the user does a free text search of the help system. The result of such a search is a list of files, each represented by its title. In our system, documents could have the title “untitled“.
In fact, the JavaHelp 2.0 System User’s Guide contains the recommendation
“To avoid confusion, ensure that the <TITLE> tag corresponds to the title used in the table of contents.”
Given that customers mostly use the Help system when they are already frustrated by our software, we should always see to it that such errors do not exist in our help system. To do this, we will write a tool, HelpGenerator, that generates some of the boilerplate XML in the help system and checks the HTML and index files for the problems listed above. We will also build tools for displaying and testing the contextual help. We’ve re-engineered and improved these tools and present them in this article.
In this article we are assuming familiarity with the JavaHelp system. Documentation and sample code for JavaHelp can be found at: http://java.sun.com/products/javahelp.
Overview
A JavaHelp package consists of:
- A collection of HTML and image files containing the specific Help information to be displayed.
- A file defining the index of the Help topics. Each index item in the file consists of the text of the index entry and a string representing the target of the HTML file to be displayed for that index entry, for example:
<index version="1.0">
<indexitem text="This is an example topic."target="Topic">
<indexitem text="This is an sub-topic."target="SubTopic"/>
</indexitem>
</index> - A file associating each target with its corresponding HTML file (or more generally, a URL)—the map file. Each map entry consists of the target name and the URL it is mapped to, for example:
-
<map version="1.0">
<mapID target="Topic" url="Topic.html"/>
<mapID target="SubTopic" url="SubTopic.html"/>
</map> - A HelpSet file (by default HelpSet.hs) which specifies the names of the index and map files and the folder containing the search database.
Our software will normally have a main menu item to activate the Help and, in addition, buttons or menu items on specific dialogs to activate a Help page for a particular topic, that is, “context-sensitive” Help.
What Tests Do We Need??
At an overall structural level, we need to check:
- For each target referred to in the index file, is there a corresponding entry in the map file? In the previous example, the index file refers to targets called Topic and SubTopic. Are there entries for these targets in the map file?
- For each URL referred to in the map file, is that URL reachable? In the example above, do the files Topic.html and SubTopic.html exist?
- Are there HTML files in our help package which are never referred to?
- If a Help button or menu item on some dialog or window is activated, does the Help facility show the expected topic?
- If the Help search facility has been activated, do the expected search results show? That is, has the search database been built on the latest versions of our Help pages?
At a lower level, we need to check the contents of each of the HTML files:
- Do the image tags in the files really point to images in our help system?
- Are there any broken links?
Finally, we need to check that the contents of the files and the indexes are consistent
- Does the title of each help page match its index?
To simplify these tests, we will follow a simple naming pattern as follows:
We adopt the convention that the name of each HTML file should be in CamelCase format (conventional Java class name format) plus the .html extension. Also, we use this name, without the extension, as the target name. For example, the target named SubTopic will correspond to the file SubTopic.html.
Furthermore, we assume that there is a single Java package containing all the required help files, namely, the HTML files, the image files, the index file, and the map file. Finally, we assume a fixed location for the Help search database.
With this convention, we can now write a program that:
- Generates the list of available targets from the names of the HTML files.
- Checks that this list is consistent with the targets referred to in the index file.
- Checks that the index file is well-formed in that:
- It is a valid XML document.
- It has no blank index entries.
- It has no duplicate index entries.
- Each index entry refers to a unique target.
- Generates the map file, thereby guaranteeing that it will be consistent with the index file and the HTML files.
The class HelpGenerator in the package jet.testtools.help does all this,and, if there are no inconsistencies found, it generates the map file. If an inconsistency or other error is found, an assertion will be raised. HelpGenerator also performs the consistency checks at the level of individual HTML files. Let’s look at some examples.
An HTML File That is Not Indexed
Here is a simple help system with just three HTML files:
The index file, HelpIndex.xml, only lists two of the HTML files:
<index version="1.0">
<indexitem text="This is an example topic."
target="ExampleTopic">
<indexitem text="This is an example sub-topic."
target="ExampleSubTopic"/>
</indexitem>
</index>
When we run HelpGenerator over this system (we’ll see how to do this later in this article), we get an assertion with the error message
The Help file: TopicWithoutTarget.html was not referenced in the Index file: HelpIndex.xml.
