June 2000: Context-sensitive Help

This Help Corner column was originally published in June, 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

May 2000: Modular 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

Context-sensitive Help

In this month's Help Corner, I'll discuss the mechanics of creating context-sensitive WinHelp and HTML Help and provide links for more information.

I'd like to thank Don Lammers of Shadow Mountain Tech for his contributions this month. Don updated existing documents on his website and created new ones, explaining his views on context-sensitive Help and discussing the specifics of linking Help to Visual Basic and Visual C++. Don has created PDF versions of these documents. See below for links to Don's articles.

What is Context-sensitive Help?

Context-sensitive Help displays the appropriate Help topic when a user presses F1 or clicks the ? (What's This?) button in a window, dialog box, or field while using the application.

There are two kinds of context-sensitive Help: window-level and field-level. The following graphic displays a sample window and explains the various types of Help and how they are accessed.

Read Don's article, Context Sensitive Help Concepts. Don discusses his views on the UI as Help, traditional context-sensitive Help, embedded Help, how basic context-sensitive Help should be triggered, and how to give users even more help.

Window-Level Context-Sensitive Help

Window-level context-sensitive Help is easier for you to develop because all fields are in one topic. However, this makes it harder for users to find help for the field they are uncertain about. Window-level Help displays in a specific Help window. It can also be designed to display the Table of Contents and other navigational features.

The following example displays a window-level topic in a secondary HTML Help window. The window would look slightly different in WinHelp, but the topic would look the same.

Field-Level Context-sensitive Help

Field-level Help displays one topic for each object (fields, buttons, and so on). It displays either in a specific Help window or in a popup.

This is the easiest type of context-sensitive Help to use, because the specific information displays at the user's request. But this Help is harder to write and maintain because you have to document every field, including those that are easily understood. If you omit some fields, a user who selects one of those fields won't realize you have implemented context-sensitive Help.

What's This? Help is a type of field-level Help that answers the question, "What is this <object>?" Usually, What's This? topics are short and don't include topic headings.

In HTML Help, What's This? Help displays in a text- only popup. If desired, you can use WinHelp What's This? Help and take advantage of formatting and graphics.

The following samples show a WinHelp formatted popup, and an HTML Help field-level topic in a secondary window and in a text-only popup.

How Does Context-sensitive Help Work?

The exact process depends on your company and your application developers. You can do the steps in almost any order, although the process shown in the following graphic makes the most sense when using RoboHELP and RoboHTML.

When developing context-sensitive WinHelp, you'll use steps 1, 2, and 4. Occasionally, you'll use step 3 to create aliases for your context-sensitive topics.

When developing context-sensitive HTML Help, you'll use steps 1, 2, 3, and 4.

When a programmer builds a form, window, or dialog box, it and all fields (or objects) are assigned a unique control ID. This control ID, also called a map number, is one of the links between the application and the Help file.

Map numbers for the project are stored in a map (or header) file, which is a text file with a .h, .hh, or .hm extension. The map file links the objects in the application together with the topics in the Help file.

When developing context-sensitive WinHelp files, the map number for an object is associated with the topic ID. (If you aren't familiar with WinHelp, think of the topic ID as the address for the topic.) When developing HTML Help files, we don't use topic IDs, so another step is required for context- sensitive Help to work. This step is the Alias file.

An alias is a way of providing an alternate ID for a context- sensitive Help topic. Aliases enable us to reassign topics in WinHelp and, when developing context-sensitive HTML Help, to assign topic IDs to the appropriate HTML topic files.

Context-sensitive WinHelp

Visit Shadow Mountain Tech and read Don's articles on connecting applications to WinHelp Help files: Connecting WinHelp to Visual Basic Programs and Connecting WinHelp to C++/MFC Programs.

For context-sensitive WinHelp, start by creating the topics normally. If you have changed Heading 1 in the RoboHELP template (by adding Keep With Next formatting), be sure to change it for any topics in the context-sensitive Help documents. Otherwise, only the headings display in the compiled Help file (which is NOT what you want!).

Typically, headings don't display in context- sensitive Help topics. One trick I use while developing context-sensitive Help is to display the headings until the testing is finished. This makes it easy to verify that the correct topic is connected to the object. Once all topics have been verified, I format the headings as hidden. This makes future development easier, since I know exactly which topic I'm working with.

Typically, topics developed for context-sensitivity are not accessible to the user through the Index Tab, the Topics Found dialog box, or a browse sequence. The easiest way to keep the context-sensitive topics separate is to create them in a separate Help file for the project and only access them through their map numbers.

Notice that I said "typically." I've talked with Help developers who don't follow this method, making their context-sensitive topics available through the Index and Find tabs. There's nothing wrong with this method, as long as it works for your users.

The programmers have to code the application to recognize context-sensitive topics developed in this manner. For example, Paint under Microsoft Windows 95 uses mspaint.hlp for its help menu file, but windows.hlp for its context-sensitive Help.

Because of the restrictions inherent in HTML Help popups at this time, Microsoft uses WinHelp to produce context- sensitive Help for its standard Windows 98 applications. The Help file for the application (accessed through the Help menu) is a .chm file. The context-sensitive Help (accessed with F1 or ?) is a .hlp file.

When a user requests WinHelp context-sensitive Help, the steps that take place are:

A call is made to WinHelp, requesting the topic for the specified map ID (coded into the object where the user requested help).
Using the map file, the topic ID is found.
The WinHelp file displays the specified topic.

Working with Map Numbers

To assign map numbers to topics, you can import an existing map file or enter the map numbers on the Advanced tab of the Topic Properties dialog box.

To import a map file through RoboHELP:

Select File | Import | Map file.
When the Open dialog box appears, navigate to the correct folder and select the map file you want to import. RoboHELP copies the map file to your project folder automatically.

To assign map numbers to individual topics:

Display the Topic Properties dialog box for the topic.
If necessary, select the Advanced tab.
In the Map # field, under Options, type the map number. If desired, view the number in hexadecimal format by selecting the checkbox.

Auto-Generating Map Numbers

RoboHELP includes two ways to auto-generate map numbers:

By the project
By individual documents

You should only auto-generate map numbers if you are in charge of creating the map numbers. Otherwise, they won't match those assigned by the application developer, which means that the context-sensitive Help won't work.

To auto-generate map numbers for the project:

Select File | Project Settings.
Select the Map Files tab.
Select the documents from the documents list by clicking inside the checkbox.
Click OK. The map files will be created for the selected documents.

To auto-generate map numbers for individual documents:

Display the list of documents under the Topics folder on the Project tab.
Right-click over the desired document and select Properties. The Document Properties dialog box displays.
Under Map IDs, click inside the checkbox next to Auto Generate Map IDs.
If desired, enter the starting map number. If left at the default value, RoboHELP controls the starting map number.
If map numbers have already been assigned to the topics in this document and you want to overwrite them, click inside the checkbox next to Apply Starting Value to Existing Map IDs.
Click OK.

Context-sensitive HTML Help

Visit Shadow Mountain Tech and read Don's articles on connecting applications to HTML Help Help files: Connecting HTML Help to Visual Basic Programs and Connecting HTML Help to C++/MFC Programs.

Before creating aliases, you must create your topics. Then, you can:

Import an existing map file, through RoboHTML or the Context-Sensitive Aliases dialog box.
Assign map numbers through the Context-Sensitive Aliases dialog box.

To import a map file through RoboHTML:

Select File | Import | Map file.
When the Open dialog box appears, navigate to the correct folder and select the map file you want to import. RoboHTML copies the map file to your project folder automatically.

To display the Context-Sensitive Aliases dialog box:

Double-click Aliases under the Context-Sensitive Help folder on the Project tab.
Right-click over Aliases and select Edit.
Select File | Aliases. The Edit Map IDs dialog box displays.

For this option...	Do this...
Topic ID	Select the topic from the Topic ID/Map # field that you want to work with. The map number automatically displays in the next field.
Map #	Displays the map number for the selected topic. If you haven't imported a map file, you can assign map numbers automatically (default) or manually. Type an entry in the Topic ID field and (Auto) displays in the Map # field. If you don't change (Auto), map numbers are assigned automatically, starting at 1 and incrementing by 1. If you want to assign a specific map number, type it in this field. If you imported a map file but then discover that you need to add entries to it, type the entry in the Topic ID field and (Auto) displays. In this case, (Auto) will start at the lowest possible number so that it doesn't overwrite any existing map numbers.
Map File	Controls what displays in the Topic ID/Map # list below. Select from <Aliases>, <All Map Files>, <Project Map File>, or a specific map file (displayed at the bottom of the list).
New Map File icon	Click to create a new map file or import an existing map file. The New Map File dialog box displays. Type the name of the new map file in the input box, or click the Open File icon to display the Open File dialog box and import an existing map file.
Topic ID/Map #	Displays a list of topic IDs and associated map numbers from the map file. If <Aliases> is selected in the Map File field, this list also displays a list of aliases in this project.
Folders	Select the project folder for the Topics List, from All Folders, Top Level Folders, URLs, or a specific project folder.
Topics List	Displays the appropriate topics for the selected folder.
Assign	Click to assign the alias (explained below).
Unassign	Click to remove the alias assignment.
Properties	Click to display the current aliases for the selected topic from the Topics List (on the right side of the dialog box).
Preview	Click to view the selected topic.

To assign aliases:

Type the Topic ID in the Topic ID field on the left.
Accept the default Map # (Auto) or replace it with the desired number.
Select the topic that will be associated with this topic ID from the Topics list on the right.
Click Assign.
Repeat steps 1 through 4 as necessary.

Resources - Websites

Don Lammers' Shadow Mountain Tech includes other articles in addition to the ones mentioned earlier. You can download the WinHelp FAQ File by Charlie Munro, Using WinHelp 4 under Win32s by Don Lammers, and A Programmer's Reference to WinHelp by Don Lammers and Paul O'Rear. Utilities include Help Link Tester and Window Tracker.
Paul O'Rear's Helpful Solutions provides articles and presentations on context-sensitive Help.
David Liske's HTML Help Center provides "HTML Help Techniques for Developers and Authors." David provides an HTML Help Class Module, HHWindows Object Library, HTML Help Popup Tester, plus more.
Dana Cline's TANSTAAFL Software includes articles on Help Jargon, Style Issues, VB-WinHelp, and Is It Helpful? Dana also moderates forums on his site for WinHelp and HTML Help.
Visit eHelp Corporation's Help Community. Included are articles, forums where you can post questions and see answers, and the eHelp Knowledge Base.

Resources - Books

Boggan, Scott, Dave Farkus, and Joe Welinske. Developing Online Help for Windows 95. SOLUTIONS, Inc., 1999 (second printing).
Hickman, Nancy. Building Windows 95 Help. M&T Books, 1996. ISBN 1-55851-477-5.
Wexler, Steve. Official Microsoft HTML Help Authoring Kit. Microsoft Press, 1998. ISBN 1-57231-603-9.

Portions of the material in this column were originally presented as a conference session at the Sixth Annual WinWriters Conference in February 1998. 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.