Writing Help Text

Writing Help Text

You write Help text in an RTF file, using special formatting codes that mean something
rather different than they usually do. The traditional way to do this has been in
Microsoft Word, but a large crop of Help authoring tools have sprung up that are far
easier to use than Word. Rather than teach you yet another tool, this section presents
instructions for writing Help text in Word. However, do keep in mind that there are
easier ways, and on a project of a decent size, you easily save the time and money you
invest in a Help authoring tool. An entire chapter in Designing Windows 95 Help discusses
choosing an authoring tool.
TIP: You can open Word documents from within Developer Studio. Simply
choose File, Open and select the file - the starter RTF files for ShowString
are in the HLP folder. The Word menus and toolbars will appear. This works
because Word documents are ActiveX Document Objects, discussed in
Chapter 15, "Building an ActiveX Server Application." Most developers
prefer to switch from Word to Developer Studio with the taskbar rather
than have a number of files open in Developer Studio and switch among
them with the Window menu, so the explanations in this section assume that
you are running Word separately. If you would rather work entirely
within Developer Studio, feel free to so do.
Figure 11.6 shows afxcore.rtf open in Word. Choose View, Footnotes to display the
footnotes across the bottom of the screen - they are vital. This is how the text connects
to the Help topic IDs. Choose Tools, Options; select the View tab; and make sure the
Hidden Text check box is selected. This is how links between topics are entered. The
topics are separated by page breaks.
FIG. 11.6 Help text, such as this boilerplate provided by AppWizard, can be edited in Word.
There are eight kinds of footnotes, each with a different meaning. Only the first three
footnote types in the following list are in general use:
l #, the Help topic ID. The SDK WinHelp function looks for this topic ID when
displaying Help.

l $, the topic title. This title displays in search results.
l K, keywords. These appear in the Index tab of the Help Topics dialog box.
l A, A-keyword. These keywords can be jumped to but don't appear in the Index tab of
the Help Topics dialog box.
l +, browse code. This marks the topic's place in a sequence of topics.
l !, macro entry. This makes the topic a macro to be run when the user requests the
topic.
l *, build tag. You use this to include certain tags only in certain builds of the Help
file.
l >, window type. This overrides the type of window for this topic.
The double-underlined text, followed by hidden text, identifies a jump to another Help
topic. If a user clicks to follow the link, this Help topic leaves the screen. If the text
before the hidden text was single-underlined, following the link opens a pop-up over
this Help topic, perfect for definitions and notes. (You can also see Help text files in
which strikethrough text is used; this is exactly the same as double-underlined - a jump
to another topic.) In all three cases, the hidden text is the topic ID of the material to be
jumped to or popped up.
Figure 11.7 shows how the File, New Help material appears from within ShowString. To
display it yourself, run ShowString by choosing Build, Execute from within Developer
Studio and then choose Help, Help Topics in ShowString. Open the menus book, doubleclick
the File menu topic, and click New. Alternatively, choose the File menu, and while
the highlight is on New, press F1.
FIG. 11.7 ShowString displays the boilerplate Help generated by AppWizard.
With the programming out of the way, it's time to tackle the list of Help tasks for
ShowString from the "Planning Your Help Approach" section earlier in this chapter.
These instructions assume you are using Word.