The Windows WinHelp Program

If you've used commercial Windows-based applications, you've probably marveled at their sophisticated help screens: graphics, hyperlinks, and popups abound. At some software firms, including Microsoft, help authoring has been elevated to a profession in its own right. This section won't turn you into a help expert, but you can get started by learning to prepare a simple no-frills help file.

Rich Text Format

The original Windows SDK documentation showed you how to format help files with the ASCII file format called rich text format. We'll be using rich text format too, but we'll be working in wysiwyg mode, thereby avoiding the direct use of awkward escape sequences. You'll write with the same fonts, sizes, and styles that your user sees on the help screens. You'll definitely need a word processor that handles RTF. I've used Microsoft Word for this book, but many other word processors accommodate the RTF format.

Several commercial Windows help tools are available, including RoboHELP from Blue Sky Software and ForeHelp from the Forefront Corporation. RoboHELP is a set of templates and macros for Microsoft Word, and ForeHelp is a stand-alone package that simulates WinHelp, giving you immediate feedback as you write the help system.

Writing a Simple Help File

We're going to write a simple help file with a table of contents and three topics. This help file is designed to be run directly from WinHelp and started from Windows. No C++ programming is involved. Here are the steps:

1. Create a \vcpp32\ex21a subdirectory.

2. Write the main help text file. Use Microsoft Word (or another RTF-compatible word processor) to type text as shown here.

   Be sure to apply the double-underline and hidden text formatting correctly and to insert the page break at the correct place.

   

   To see hidden text, you must turn on your word processor's hidden text viewing mode. In Word, choose Options from the Tools menu, click on the View tab, and select All in the Nonprinting Characters section.

3. Insert footnotes for the Table Of Contents screen. The Table Of Contents screen is the first topic screen in this help system. Using the specified custom footnote marks, insert the following footnotes at the beginning of the topic title.

   Footnote Mark	Text	Description
   #	HID_CONTENTS	Help context ID
   $	SIMPLE Help Contents	Topic title

   When you're finished with this step, the document should look like this.

   

4. Insert footnotes for the Help Topic 1 screen. The Help Topic 1 screen is the second topic screen in the help system. Using the specified custom footnote marks, insert the footnotes shown here.

   Footnote Mark	Text	Description
   #	HID_TOPIC1	Help context ID
   $	SIMPLE Help Topic 1	Topic title
   K	SIMPLE Topics	Keyword text

5. Clone the Help Topic 1 screen. Copy the entire Help Topic 1 section of the document—including the page break—to the clipboard, and then paste two copies of the text into the document. The footnotes are copied along with the text. In the first copy, change all occurrences of 1 to 2. In the second copy, change all occurrences of 1 to 3. Don't forget to change the footnotes. With Word, seeing which footnote goes with which topic can be a little difficult—be careful. When you're finished with this step, the document text (including footnotes) should look like this.

   

6. Save the document. Save the document as \vcpp32\ex21a\Simple.rtf. Specify Rich Text Format as the file type.

7. Write a help project file. Using Visual C++ or another text editor, create the file \vcpp32\ex21a\Simple.hpj, as follows:

    [OPTIONS] CONTENTS=HID_CONTENTS TITLE=SIMPLE Application Help COMPRESS=true WARNING=2 [FILES] Simple.rtf 

   This file specifies the context ID of the Table Of Contents screen and the name of the RTF file that contains the help text. Be sure to save the file in text (ASCII) format.

8. Build the help file. From Windows, run the Microsoft Help Workshop (HCRTF) utility (located by default in Program Files\Microsoft Visual Studio\Common\Tools). Open the file \vcpp32\ex21a\Simple.hpj, and then click the Save And Compile button.

   This step runs the Windows Help Compiler with the project file Simple.hpj. The output is the help file Simple.hlp in the same directory.

   

   If you use Word 97 to create or edit RTF files, make sure you use version 4.02 (or later) of the HCRTF utility. Earlier versions of the HCRTF cannot process the rich text flags generated by Word 97.

9. Run WinHelp with the new help file. From Windows Explorer, double-click the file \vcpp32\ex21a\Simple.hlp. The Table Of Contents screen should look like this.

   

   Now move the mouse cursor to Topic 1. Notice that the cursor changes from an arrow to a pointing hand. When you press the left mouse button, the Help Topic 1 screen should appear, as shown here.

   

   The HID_TOPIC1 text in the Table Of Contents screen links to the corresponding context ID (the # footnote) in the topic page. This link is known as a jump.

   The link to Help Topic 2 is coded as a pop-up jump. When you click on Topic 2, here's what you see.

   

10. Click the WinHelp Contents pushbutton. Clicking this button should take you to the Table Of Contents screen, as shown at the beginning of step 9. WinHelp knows the ID of the Table Of Contents window because you specified it in the HPJ file.

11. Click the WinHelp Index pushbutton. When you click the Index button, WinHelp opens its Index dialog, which displays the help file's list of keywords. In Simple.hlp, all topics (excluding the table of contents) have the same keyword (the K footnotes): SIMPLE Topics. When you double-click on this keyword, you see all associated topic titles (the $ footnotes), as shown here.

    

    What you have here is a two-level help search hierarchy. The user can type the first few letters of the keyword and then select a topic from a list box. The more carefully you select your keywords and topic titles, the more effective your help system will be.

    An Improved Table of Contents

    You've been looking at the "old-style" help table of contents. The latest Win32 version of WinHelp can give you a modern tree-view table of contents. All you need is a text file with a CNT extension. Add a new file, Simple.cnt, in the \vcpp32\ex21a directory, containing this text:

     :Base Simple.hlp 1 Help topics 2 Topic 1=HID_TOPIC1 2 Topic 2=HID_TOPIC2 2 Topic 3=HID_TOPIC3 

    Notice the context IDs that match the help file. The next time you run WinHelp with the Simple.hlp file, you'll see a new contents screen similar to the one shown here.

    

    You can also use HCRTF to edit CNT files. The CNT file is independent of the HPJ file and the RTF files. If you update your RTF files, you must make corresponding changes in your CNT file.