Building a Simple Help File Without Help Author

This section explains how to create and build a simple Help file using Microsoft Word for Windows. The simple Help file consists of two topics, and one of the two topics includes a jump to the other topic.

To build this simple Help file, you will:

nCreate a project directory for the source files.

nCreate two topics using Word for Windows: enter context strings for the two topics, code a jump from one topic to the other, add a bitmap to one topic, and save the topic file as RTF.

nCreate a Help project file with information for building the Help file.

nBuild the Help file with the Help compiler.

nTest the Help file by displaying it in Windows Help.

Creating a Help Project Directory

When you develop a Help file, you ordinarily create a separate project directory on your hard disk drive to hold and organize all the source files. (You might also create separate subdirectories for the text files and bitmaps in your Help file.) For this example, create a temporary project directory called SAMPLE and copy the Windows Help software to that directory.

To set up the SAMPLE subdirectory

nEnter the following commands at the MS-DOS prompt:

cd \
md sample
copy [sourcepath]\hc31.exe c:\sample\hc.exe
copy [sourcepath]\hc31.err c:\sample\hc.err
copy [sourcepath]\winhelp.exe c:\sample

The sourcepath is the floppy drive letter or other drive letter or path that describes where the files are located.

Creating a Help Topic File

The first step in creating a Help file is to create the topic files. Topic files contain the text and other information that appears in your Help file.

Creating Individual Topics

The topic is the basic building block of a Help file. You create topics using Word for Windows (or other RTF editor) and then save them in a topic file.

To create a topic file

1.1.Start Word for Windows and open a new document.

2.2.Type the following text:

Topic 1

3.3.Press CTRL+ENTER to insert a hard page break.

Hard page breaks separate topics in a topic file.

4.4.Type the following text for the second topic:

Topic 2

Your screen should look like the one in Figure 2.19.

Note:

All Word for Windows screens in this guide are shown as they appear with Hidden Text and Paragraph Marks selected from the View Preferences (version 1.1) or the Tools Options (version 2.0) dialog box.

Entering Context Strings

Each topic usually has a context string. The context string identifies the topic within the Help file. For example, to jump to a topic you must provide the context string of the topic string to which you want to jump. You insert the context string using the pound-sign (#) footnote in Word for Windows.

To enter a context string

1.1.Position the cursor at the beginning of the line containing the words “Topic 1.”

2.2.From the Insert menu, choose Footnote.

3.3.Type a pound sign (#) as the footnote character.

4.4.Type the following text as the footnote reference:

topic1_ID

5.5.Repeat steps 1 through 4 for Topic 2. However, type topic2_ID as the footnote text.

Your screen should look like the one in Figure 2.20.

Inserting a Jump

Now that you’ve identified your two topics, you can insert a jump from Topic 1 to Topic 2. To insert a jump, you first type the hot-spot text—that is, the text the user will click to make the jump—and then you identify the destination topic for the jump.

To insert a jump

1.1.Position the insertion point at the end of the first paragraph in Topic 1 and press ENTER. Then type:

Jump to Topic 2

2.2.Select the text you typed in step 1.

3.3.From the Format menu, choose Character.

4.4.Select the Double Underline check box, and then choose OK.

Formatting text as double underline tells the compiler to make the text “Jump to Topic 2” into a hot spot.

5.5.Position the insertion point immediately after the “Jump to Topic 2” text and type:

topic2_ID

6.6.Select the text you typed in step 5.

Be sure not to select any of the double-underlined text or the paragraph mark at the end of the line.

7.7.From the Format menu, choose Character.

8.8.Clear the Double Underline check box, select the Hidden check box, and then choose OK.

Formatting text as hidden tells the compiler that “topic2_ID” is the context string of the destination topic for the jump.

Your screen should look like the one in Figure 2.21.

Note:

When you remove the selection highlight from the text, you will be able to see the hidden text formatting.

Adding a Picture

The next step is to add a picture to one of your topics. Although you can add bitmaps directly to a topic, it is usually better to enter a bitmap reference that tells Windows Help the name of the bitmap file to display in the topic.

To insert a bitmap in the topic

1.1.Create a new line after the line containing the words “Topic 2.”

2.2.On the new line, type the following:

Your screen should look like the one in Figure 2.22.

The bmc command tells the Help compiler to position the SAMPLE.BMP bitmap below the text in your topic. (SAMPLE.BMP is one of the sample bitmaps provided with the Windows Help software.)

Saving the Topic File

After you’ve created the topic file, save it as RTF.

To save your topic file and close Word for Windows

1.1.From the File menu, choose Save As.

2.2.In the File Name box, type this filename:

sample.rtf

3.3.Choose the Options button.

4.4.From File Format, select RTF.

5.5.Choose OK to save the file.

6.6.From the File menu, choose Exit.

If word hen Word for Windows asks if you want to save changes to SAMPLE.RTF, choose No. You already saved your changes in RTF format in steps 4 and 5.

Saving the Project File

Now you’re ready to save the Help project file.

To save the project file

1.1.From the File menu, choose Save Project As.

2.2.In the File Name box, type this filename:

sample.hpj

3.3.Choose OK to save the file.

Creating a Help Project File

Now that you’ve created topics for your Help file, you create a Help project file—a text file that tells the Help compiler exactly how to build the Help file. The Help project file can include different types of information. Depending on the complexity of the Help file you are building, the Help project file may have very little information or quite a lot. At minimum, the Help project file must include a list of the topic files used to build the Help file.

The structure of the Help project file is the same as .INI files in Windows—the file is divided into sections, each of which contains information or settings for a particular aspect of an application. In the Help project file, the sections contain information about different aspects of the Help file. However, except for the [FILES] section, a section is required only if you want to include a specific feature that it contains.

The Help project file should have the same name as your Help file but with an .HPJ extension. You can use any text editor to create it, as long as you save it as unformatted text (standard ASCII format). For this exercise, save the Help project file in the SAMPLE directory.

Listing Topic Files

List the files that you’re using to build your Help file in a section beginning with the following heading:

[FILES]

Under this heading, type the names of the RTF files to be included in the Help file. Because you have only one topic file, SAMPLE.RTF, the [FILES] section looks like this:

[FILES]
SAMPLE.RTF

Specifying Options

Although not required, you will usually include an [OPTIONS] section so that you can specify particular build options for the Help file. Enter these options under the following heading:

[OPTIONS]

To identify the project directory where the source files are stored, to indicate the window title you want displayed in the Help title bar, and to specify the level of warning messages to display during the build, type the following lines exactly as they are shown below:

[OPTIONS]
ROOT=C:\SAMPLE
TITLE=SAMPLE HELP
WARNING=3

Note:

You also included a bitmap in one of the topic files. But because the bitmap resides in the same project directory as the other files, you don’t have to specify anything in the Help project file.

The Complete Help Project File

Once you’ve finished these steps, your Help project file should look like this:

[OPTIONS]
ROOT=C:\SAMPLE
TITLE=SAMPLE HELP
WARNING=3

[FILES]
sample.rtf

The [OPTIONS] section, if used, must appear first in the Help project file.

Save this file as SAMPLE.HPJ in the SAMPLE directory. Be sure you save the file as Text Only if you are using a word processor instead of an ASCII text editor.

Building Your Help File

The final step is the simplest.

To build your Help file

nUsing the Windows Run command (or from the MS-DOS prompt), run the Help compiler from the SAMPLE directory, giving the name of your Help project file.

For the sample you created in this chapter, type the following command:

hc sample.hpj

The compiler builds your Help file and displays messages during the build. When it is complete, you have a Help file named SAMPLE.HLP.

Testing Your Help File

After you build a Help file, open it in Windows Help to test it and to make sure the features you added work correctly.

To start Windows Help

1.1.From Program Manager, press F1 or use the Run command to start Windows Help.

2.2.After Windows Help is running, choose Open from the File menu.

3.3.Type the name (and path if necessary) of your Help file (SAMPLE), and then choose OK.

Or use the Browse button to locate and select the SAMPLE.HLP file.

When Windows Help first opens the Help file, it appears as in Figure 2.23.

As you can see, “Jump to Topic 2” appears in green, underlined text, indicating that it is a jump hot spot.

To test the jump

1.1.Move the mouse pointer over the green text.

Notice that the pointer changes to a hand shape with a pointing finger.

2.2.Click the left mouse button.

Your second topic appears, as in Figure 2.24.

The SAMPLE.BMP bitmap file appears below the “Topic 2” text.

Quitting Help

Now that you have your Help file working, you can quit Windows Help.

To quit Windows Help

nFrom the File menu, choose Exit.