May 2000: Modular Help

This Help Corner column was originally published in May, 2000, and written for RoboHELP Office Version 8.

by Char James-Tanny

In this section...

January 2000: Setting the Tool Options

February 2000: Macros and Scripting

March 2000: Formatting Topics

April 2000: Using Dynamic Linking

June 2000: Context-sensitive Help

August 2000: Using the Single-Source Wizards in RoboHelp Office

September 2000: RoboHelp Version 9 is here!

October 2000: Generating WebHelp

November 2000: Creating Glossaries

December 2000: Using Browse Sequences

Modular Help

When I first developed my outline of topics for Help Corner, I made the mistake of listing dynamic linking before modular Help. Therefore, some information from last month's dynamic linking column is repeated this month. I apologize for any confusion this might cause.

This month's column covers modular Help in more detail, including instructions for creating modular HTML Help.

What is Modular Help?

Modular Help systems combine several independent Help files into one oohesive system. Unless you code your projects to indicate that several Help files have been combined, users will never know that they are navigating through more than one Help file. (OK, there's one exception: if you use identical A- or K-Keywords in your merged WinHelp projects, they display with the name of the WinHelp file in the Topics Found dialog box.)

Modular WinHelp systems are created with commands in the Contents (.cnt) file. Modular HTML Help systems are created with commands in the Contents (.hhc) and project (.hhp) files. Both Help systems allow you to display as much or as little information as desired.

Consider using modular WinHelp or HTML Help when:

You are developing Help for an application that can easily be divided into sections (for example, an Accounting application that includes General Ledger, Accounts Payable, Accounts Receivable, and so on) that users don't have to purchase at one time, if ever.
You have one (or more) sections that are common to several applications (for example, a Glossary).
You are part of a multi-authoring development team, with each developer responsible for a portion of the Help system.

In addition, consider using modular WinHelp when:

Your project contains large RTF and/or graphic files, which take a long time to compile. It is easier to work with multiple Help files; individually, they compile more quickly. You can also divide your project conceptually, making it easier to work with the individual files.
You want to include links to future Help files.

Designing for Your Users

Planning your modular Help system lets you verify the results of your links and the accuracy of your plan. Since dynamic links use keywords (either K-Keywords, which make up the index, or A-Keywords or ALink Names, which are only used for these links), you can decide the results of the links before you start entering project information.

Why is planning so important? A Topics Found dialog box is only effective if it presents a reasonable list of topics for the user to choose from. If you've ever clicked a link that displayed a Topics Found dialog box that contained 10, 20, or 40 topics, you have probably experienced the frustration of "Are all these topics really related?" By limiting your Topics Found lists, you provide useful functionality while not overwhelming the user.

Possible planning methods include:

Storyboarding the Help system (colored stickies, a bulletin board, tacks, and string help you visualize it)
Using a Topic Map, drawing the topics and their corresponding links
Customizing a Topic List with a column for A- and K-Keywords

It's harder to map K-Keywords ahead of time, since good indexes aren't done on the fly but after the content has been developed. However, if you're using existing Help files, you can use the Index and See Also reports in RoboHELP and RoboHTML to list your existing entries.

Creating Modular WinHelp

Modular WinHelp uses commands in the Contents file, which is nothing more than an ASCII (text) file with a .cnt extension. The three commands that produce modular WinHelp systems are built into two different RoboHELP 2000 for WinHelp dialog boxes: New External CNT in the TOC Composer and the Contents tab in Project Settings.

:Include inserts all the commands in another Contents file in the current Table of Contents. RoboHELP inserts this command when you add an external CNT file in the TOC Composer.
:Index merges the K-Keywords of the specified file with the current Index in alphabetical order. RoboHELP enters the command as :Index Help File Name=filename.hlp (which displays Help File name instead of just filename.hlp). This command also merges the Find tab information.
:Link gives you access to the A- and K-Keywords of the specified file for use with dynamic linking (ALinks and KLinks). It doesn't update the Index or the Find tab information.

The Windows 95 Help system (back when Microsoft still distributed .hlp files and not .chm files) had the best Contents file for learning how these commands work. While it did contain some actual references to the Windows Help file, it mostly contained these commands to other Help files that may or may not be on your system. This enabled Microsoft to distribute small Help files that displayed as one large Help system, depending on the software you had installed.

One feature of the commands in the Contents file is that no errors result if the specified Help file doesn't exist on the user's system. For example, if a user purchases General Ledger but not Accounts Payable, and the Accounts Payable information is included in the Contents file, nothing is displayed. The user never realizes that something isn't being displayed.

This can also be a hindrance. If the file name is typed incorrectly, the file isn't displayed-but neither is an error message.

For a complete modular help system, you would include all three commands in the Contents file. However, each command is independent, allowing you to access only the piece(s) you want. For example, you could include only the Table of Contents, or only the Index and Find tab information, or both.

To use the :Index and :Link commands in RoboHELP, select the Contents tab in the Project Settings dialog box.

From this field...	Do this...
Title	Enter a title if you wish to override the currently entered project title, which is the default.
Default Help File	Defaults to the current help file name.
Default Window	Select the default window for the Table of Contents. The window must already be defined.
Include Help filename with pages	Select this if you will be including this project's Contents information in another help file's Contents file, so that all topics display correctly. With this option, you must assign topic windows to every topic in the TOC Composer, because the default window setting is ignored (a WinHelp bug).
Master CNT	Enter or modify the Master Contents file name for this project's help file.
Files Included in Index	Specify K-Keywords, A- Keywords, or both.
Custom Tabs	Use this if you have a custom program written specifically for this function. For example, the AnswerWorks application creates a custom tab and provides a natural language query for a help file.

Then, click the Add button under Files Included in Index. The following dialog box displays:

Select the Help File by clicking the Open Folder icon to display the File Open dialog box. Navigate to the correct folder and select the Help file. If you're merging the Indexes, type a title in the input box. Then, click OK.

If you want to specify a Help file that hasn't been created yet, type the name in the input box. When you click OK, a message is displayed, stating that the file doesn't exist. To include it, click Yes.

Typically, the names of the Help and Contents files are the same. However, they don't have to be, as long as the Help file "knows" the name of the Contents file it is to use. This allows us to create Master Contents files, linking multiple help systems into one.

Creating a Master Contents File

Technically, whenever you include another Help file's Contents file, your current Contents file becomes a Master CNT.

You can also create a Master CNT project that allows you to develop the CNT independently of any Help files. You don't need to create any topics in this project, unless you want to. Select Master CNT as the New Project type when creating a new project and fill in the other project information as required.

To make your development life a little easier, use the folder where Master CNT project resides as a testing folder. In the individual Help file projects, use the Copy Help File To option (on the Compile tab in the Project Settings dialog box) to copy the compiled help files to this folder. You also have to use the Master CNT button to set the proper contents files.

Because the change for the Master CNT is made to the project file, not the CNT file, you have to recompile the individual Help files to reflect the change. You can test your Help file from the Master CNT project or by double-clicking any help file in the testing folder. If you run the Help file from any of the individual projects folders, there won't be a Contents tab because the Help file can't find the CNT file.

Installing WinHelp Files

When deploying a Master CNT project, all files must be installed in the same folder. However, if the referenced file isn't found in the current folder, the WinHelp engine searches the following folders:

Windows
Windows/System
The system PATH
The Windows Registry

Creating Modular HTML Help

While the concepts of modular Help are the same for WinHelp and HTML Help, the implementation is slightly different. The tricky thing here is this: Even though the primary Help file doesn't look for the secondary pieces until runtime, those Help files must exist at compile time. RoboHELP 2000 for HTML Help doesn't allow you to add a file that doesn't exist to the project (even if you edit the HHP file with Notepad).

Use this checklist before merging files.

You cannot create a binary TOC if you will be merging this project's Help file with another one.
You must create a binary Index for the master, or primary, Help project. However, you don't have to create a binary Index for the secondary projects.
Topic keywords, if used, are automatically included in the binary Index.
Secondary HTML Help files and their Tables of Contents file names must not contain spaces.
You cannot use merged files with 1.0 Compatibility.
For the compiled Help system to display correctly, make sure the individual Help files are installed into the same folder.

Linking to Other HTML Help Files

If you're creating modular HTML Help, you will probably want to link to topics in the other HTML Help files. When creating these links, the target topic must be included in the hyperlink. For example:

<A HREF="ms-its:filename.chm::/topic.htm">hotspot</A>

If the topic is in a subfolder, you have to type the folder information also.

<A HREF="ms-its:filename.chm::/folder/topic.htm">hotspot</A>

Merging HTML Help files requires two steps:

Adding the merged file information in Project Settings
Adding the merged file's Table of Contents in the TOC Composer

Adding a .chm File

To merge .chm files, use the Advanced tab in the Project Settings dialog box.

Click the Add button next to Merged Files.
In the Open File dialog box, select the desired .chm file and click Open.
When the confirmation message displays, click OK to copy the .chm file to the current project folder.
Click OK.

This merges the Index and (if specified) full-text search information. If you update the secondary .chm file, be sure to copy it to the current project folder.

For index terms to merge correctly, they must use the same case.

Merging the Tables of Contents

The next step is to merge the secondary .chm file's Table of Contents into the current project.

Display the TOC Composer.
Position your cursor on the last book in your current Table of Contents and create a new book.
Select File | New | External TOC (or right-click to select the same option). The External TOC dialog box displays.
Click the drop-down arrow next to HTML Help File Name and select the desired .chm file. The name of the contents file displays under TOC File.
Click OK.
Compile and test your Help file.

What you'll notice is that the merged file information doesn't display correctly in the merged Contents file. The first book of the merged file displays under the book you created, and all subsequent books display indented under the first book.

For example, the following screen shots describe this process and the workaround:

	This is the TOC for the sample project, before adding any merged file information.
	In the sample project, I've added the new book and the merged .chm file information.
	The compiled file shows that the merged file displays incorrectly. The newly created book displays as a first level book. The first book in the merged file (Paint Tutorial) becomes a first level subentry. The first topic under that book (Introduction) becomes a second level sub-book and the remaining books also display as second level sub-books.
<li><object type="text/sitemap"> <param name="Name" value="Colors Menu"> <param name="Local" value="menus\Colors_Menu.htm"> </object></ul> <li><object type="text/sitemap"> <param name="Name" value="Merged .chm File"> </object> <ul><object type="text/sitemap"> <param name="Name" value="paint1.chm::/paint.hhc"> <param name="Merge" value="paint1.chm::/paint.hhc"> </object></ul></ul>	After closing the project, open the .hhc file in Notepad. The newly created book displays (value="Merged .chm File") and the merged file information displays below it.
<li><object type="text/sitemap"> <param name="Name" value="Colors Menu"> <param name="Local" value="menus\Colors_Menu.htm"> </object></ul> <li><object type="text/sitemap"> <param name="Name" value="Merged .chm File"> </object></ul> <object type="text/sitemap"> <param name="Name" value="paint1.chm::/paint.hhc"> <param name="Merge" value="paint1.chm::/paint.hhc"> </object>	To fix the display problem, delete the last two </ul> tags. Then, change the <ul> preceding the merged file information to </ul>. Save the .hhc file and reopen the project in RoboHTML.
	The edited TOC displays a little differently now. The newly created book displays without any subentries. Since books without entries don't display in the .chm file, it won't cause any problems. The merged file information aligns to the left, where it belongs.
	The resulting .chm file shows the correctly aligned merged file information, with all books at their proper levels.

When using this method to correctly align merged file information, DO NOT make any other changes to the TOC in RoboHTML, as all changes will be overwritten and restored to their original settings.

Portions of the material in this column were originally presented as a conference session at the Seventh Annual WinWriters Conference in February 1999. Portions of the WinHelp section have been taken from Advanced RoboHELP 2000 for WinHelp, a training seminar provided by SOLUTIONS, Inc. and taught by Char James-Tanny. Portions of the HTML Help section have been taken from Sams Teach Yourself RoboHELP 2000 for HTML Help in 24 Hours by Char James-Tanny, ISBN 0-672-31625-0. Used with permission from Macmillan Computer Publishing USA.