Programming Windows help files. (Programming Power) (Column) (Column)
by Tom Campbell

To create a WinHelp HLP file, you need at least two source files. The first is a project file, with the default extension HPJ. The project file contains, at a minimum, a list of all the help source files (called topic files) in the project. The other file or files are the actual help source files, which use a default extension of RTF.

Project files are in sections and look somewhat like the INI files so common to Windows applications and the Windows system itself. At a minimum, you need a [Files] section and a list of the topic files. For example, the minimum HPJ file for a product called SuperNote might be named SUPRNOTE.HPJ and contain just one topic file in its [Files] section. It would look like this.

[Files] SUPRNOTE.RTF

Most help files also have an [Options] section with such items as compression level, copyright, title, and so on; but you can get by just fine without it to start.

Topic files are much more complicated, even at a minimum, and that's what brought this column about. I have to create large help files frequently. They need good indexes, generous keyword lists, and lots of hyperlinks. They don't need the many impressive bells and whistles that come with the help engine, such as user-defined buttons, custom DLLs, or CD-ROM file systems. All that stuff is great, and I strongly encourage you to read the help compiler documentation. It won't take you long to realize that the Windows help system is an unsung hero in the development world. But that doesn't solve the simple problem of creating a minimal help system. The help docs just don't tell you what to leave out. So, here goes.

RTF is a minilanguage in which the keywords start with a backslash, and compound statements employ the curly braces and semicolons so familiar to C programmers. All the rest is ASCII text.

1. The file must begin with a left brace and end with a right brace.

{ }

2. The first keyword is \rtf.

{\rtf}

3. The second is the \ansi statement.

{\rtf\ansi}

4. Next, you should include a \fonttbl statement enclosed in braces. The syntax is

{\fonttbl{\f ;} . . . }

where is replaced by a number such as 0, 1, or 15, is the one-word font name, is the typeface family name, and the three dots mean 0 or more more occurrences of the \f statement. It's much easier to see the following example.

{\rtf\ansi {\fonttbl {\fO\froman Times New Roman;} {\f1\fdecor Courier New;} {\f2\fswiss Arial;}} }

5. Specify the default font using the \def statement. The syntax is \deff

where is a number, such as 0.

Here's an example.

{\rtf\ansi {\fonttbl {\fO\froman Times New Roman;} {\f1\fdecor Courier New;} {\f2\fswiss Arial;}} \deffO }

In this case, the default is fO, for Times New Roman.

RTF is interesting in that, like most "real" programming languages, white space is irrelevant. That is, between the backslash keywords and the curly brace statements, you can use any number of spaces, tabs, or newlines - or none. The dreary part is that a simple blank line needs its own\par keyword and a tab uses the \tab keyword, instead of an ASCII 9. (This is actually good. DOS uses a different ASCII convention for blank lines than UNIX and the Mac, and IBM mainframes use something different from all of them. Consequently, RTF files offer an accurate, though bulky, means of assuring correct formatting on all computer systems.)

6. Create the topics with

#{\footnote } ${\footnote } \page

where is replaced by a unique context name. The name may consist of letters, digits, and the underscore character.

is just that - what you want to talk about in the help file. Note that newlines are ignored. To start a new paragraph, use the \par statement.

The really isn't optional. if you want the topic to show up in the search dialog, you need it. The string is what gives it a position in the file - titles don't have to be unique, but contexts, like subroutine names, do.

Here's an example.

{\rtf1\ansi \deff2 {\fonttbl {\fO\froman Times New Roman;} {\f1\fdecor Courier New;} {\f2\fswiss Arial;}} #{\footnote SuperNoteOverview} ${\footnote Overview of SuperNote} SuperNote makes note taking easier than ever. \par \page }

Why are the critical help context and topic title functions given \footnote commands? It's a kludge, that's why. Remember, RTF wasn't designed for the creation of help systems. Microsoft just chose RTF as the vehicle for help sources, perhaps because it's easy to create RTF filters for word processors. 7. End each topic with a \page statement, as shown above. You can have as many topics per file as you wish; one common convention is to have one file per menu and dialog in the application.

8. While you've just been given the absolute minimum, a help system is nothing without keywords. Keywords appear in the search dialog, using WinHelp's cool word-completion algorithm, which jumps to the first word matching the letters as you type them. You can have as many keywords as you wish per topic, and they too use a footnote (this time, the K footnote:

K{\footnote Overview;Starting out}).

Footnotes can consist of more than one word, and you use semicolons to separatethem. You can put them anywhere, but I put them right after the title.

9. Your last task is to include hypertext links within the help text. The link consists at a minimum of the {\v} command with the name of the context following the \v. Normally, you will precede it with the text you want to show in green as the highlight using the {\uldb} command with the text following the \uldb. As an example, here's a link to the SuperNoteOverview context shown in the example above.

{\uldb The Overview}{\v SuperNoteOverView} will give you the basics if you're new to Windows text editors.

Technically, the \uldb isn't required. If you omit it, the context name will appear, which often works out fine in the case of SuperNoteOverView.

That's it. Fewer than ten steps as a basis for creating commercial-quality help systems with tools you already have. Your applications will have a burnished, well-rounded appearance that matches that of professional software.

Tune in again next month for an easier way!