Easier Windows Help files

Easier Windows Help files. (creating source files) (Programming Power) (Column)
by Tom Campbell

Last month we covered the laborious process of creating source files for the Microsoft Windows Help Compiler (HC31.EXE) using an ordinary ASCII text editor. This month we will look at a much easier way. I'm offering a vastly simplified translator called MiniHelp, which has just five commands but handles 90 percent of your Help file needs: topics, keywords, hypertext links, titles, and changing the font size. MiniHelp reads a file consisting of MiniHelp commands interspersed with standard RTF commands (if you need them). It spits out an RTF topic file that HC31 can read.

To illustrate, let me show you the minimal RTF input file for the Microsoft Help Compiler.

{/rtf1/ansi/deff2{/fonttbl {/fO/froman Times New Roman;} {/f1/fdecor Courier New;} {/f2/fswiss Arial;} } #{/footnote SuperNoteOverview} ${/footnote A SuperNote Overview} SuperNote lets you write several different notes at once. /par /page}

Here's the MiniHelp file that created it.

.topic SuperNoteOverview .title A SuperNote Overview SuperNote lets you write several different notes at once.

As you can see, MiniHelp lets you think in terms of things like topics and titles, not nested RTF commands and # footnotes. I've uploaded a MiniHelp package to COMPUTE's forum on America Online containing the source for MiniHelp, an executable version, full documentation, and examples. MiniHelp is freely distributable, and you may use it for any purpose, as long as you leave the copyright notices intact.

OK, let's cut to the chase. Here's the MiniHelp manual.

As its input, MiniHelp expects an ASCII tect file containing one or more Help topics; the output is an RTF topic file. You will list each of these filenames under the [Files] heading of a text file with the extension HPJ file. HC31.EXE reads the HPJ file, then looks for each of the RTF files listed under [Files].

A MiniHelp file consists of "dot commands," lines of text, blank lines, and hypertext links. Dot commands start with a period as the first character and contain a MiniHelp keyword, followed by one or more identifiers of your choice. Dot commands get the whole line to themselves; don't follow them with any text. It's important to note that word-wrap is handled by the Windows Help system.

The MiniHelp dot commands are .Topic, .Title, .Keywoard, and .FontSize. They're listed in order of importance. The .Topic dot command is the only one that must be followed by a unique identifier. The identifier must be a single word that starts with a letter and may consist of letters, numbers, and underscores. It's just like naming a variable in any other language. Here are some examples.

.topic SuperNoteOverview .topic MenuFile

A topic tells you where to find the topic text, but doesn't display anything. You need a title after the topic if you want to use keywords, or if you want to show the topic in the History and Search dialogs. A title can be any string of text, including spaces.

.title SuperNote: An Overview .title The File Menu

Title don't have to be unique, although it's less confusing if they are.

Optionally following the title is a set of keywords. These too can include spaces. They're separated using semicolons.

.keywords File menu; Print; Exit; Open; Save

All of the keywords will appear in the Search dialog. Double-click on the keyword in the Search dialog, and you'll jump to that topic.

The Help text follows. Remember that, because of the way word-wrap is handled in RFT, two words which are separated by a carriage return/linefeed will print as a single word. To ensure that they're separated, precede the second word with a space.

To include a hypertext link to a topic within the text, you enclose, the phrase to be printed, a colon, and the topic name in curly braces.