Introduction to Creating Help Files

I know the last thing some programmers think about is creating a help file, when in fact having a help file in some cases can make or break the success of your application. I have downloaded software that didn't have a help file, which was to bad. The program has such promise but with out a help file I couldn't figure out how to use the program.

Actually most people think creating help files are hard. But creating a basic help file is as easy as writing a letter. You break the topic down and explain each topic. The only difference is that once your done you compile that letter in to a help file using a compiler.

This month we will learn how to create a basic help file and how to add that file to your program. Once you compile your help file it can be used with either a VB, C++ or Delphi programs for Windows. So kick back and lets get started.

Syllabus

What You Will Need

In order to create a help file you will need the following things.

  1. A program that can save your work as an RTF file.
  2. The WinHelp Compiler

If you have Word then you're all set since documents created in Word can be saved as an RTF file. Since I have Office 97 I will be using Word 8.0 for this tutorial as for the help compiler, if you have the professional version of VB or VC++ it comes with WinHelp. However if you do not you can get a free copy of HWC from Microsoft at the link below.

A quick note, I will be using version 4.03 of the winhelp compiler. Older versions can not compile Word 8.0(Office 97). More on that during week 3 handling errors.

Hcwsetup

We will also need a project in which to create a help file. If you already have a application that requires a help file then good, if not I will be using the DialPad Project that we did on the HandsOn project. To see the DialPad project you can check out the link below.

DialPad

 

Creating the RTF File

The first thing well need to do is turn on the Hide/Show formatting (paragraph mark) that lets you see the all the formatting of the text. It looks like the image below and its located on the upper right had corner of Word.

Now its time to set up the topic that we will need for our help file. On the DialPad project lists three parts to the project, the interface, dialing and the phone book. We too will have three topics for our help file they will be as follows.

So your RTF file should look like Figure 1 . Now start typing a explanation under each topic. Since this is a sample project the explanations will be brief. It should look like Figure 2. Before we go any further lets save our file, we'll call our file DialPad.

Using FootNotes

Now that we have basically completed the contents of our help file, we now have to format the text so the compiler can compile it in to a help file. The first thing we need is to make each of our topics a separate page. So at the bottom of each topic insert a page break. To add a page break in Word use, CTRL+ENTER or click on the insert menu; break , then select page break. Your file should now look like Figure 3.

There will be 3 formatting tags we will be using to create our help file, they are as follows.

The first thing we are going to do is create Titles for our help file. This is done by adding the $ character in front of each of the titles. So to add the formatting characters do the following.

  1. Pace the cursor in front of the title, "About Dial Pad"
  2. Under Insert select FootNotes
  3. Select Custom Marks and enter a $ in the box
  4. Next to the $ character in the FootNotes type, About Dial Pad.
  5. Now place the cursor in front of the About topic again
  6. Select Insert then FootNotes
  7. Select Custom Marks and enter a # in the box
  8. Next to the # character type, About
Do this for the rest of your topics, your file should now look like Figure 4 . Even though we are not done we can still compile this file in to a help file. But at this point you will only see the first topic once the help file is compiled.

Adding Jumps

Adding Jumps and Popups are very easy. Jumps and Popups are just like hyper-links on a web page. When you click on a link you are taken to that web page. If you click on a Jump you are taken to that topic. A popup will display a message when you click on it, popups can give the user a quick explanation of a word or command.

We are going to create a jump, to do this we will need to add topic and link characters. So under the, "About Dial Pad" topic add the topics, "Using Dial Pad" and "Using Phone Book". Now do the following.

  1. Select the topic, Using Phone Book
  2. Right click the mouse and select Fonts
  3. In the Underline column select double then click OK.
  4. Now make sure that the pointer is at the end of the topic and type Dial Pad
  5. Now select just the, "Dial Pad" word while that is highlighted click Format and select Font. Make sure that the Underline column has none selected and under, "Effects" check the "Hidden" box, then click OK.

You have just created a Jump, Now do the same for the other topic. Your RTF file should look likeFigure 5.

Adding Popups

Like I stated earlier creating a popup is just like creating a jump but instead of jumping to a new topic a window will popup that contains a message. We are going to add a popup out of one of the words in the About Dial Pad topic. So on the second line of the About Dial Pad select, "phone book" add a single under line. Right at the end type phone, select that word and make it hidden. Now at the bottom of the file add a new page break. Now select Insert then FootNote. Under the custom option type the # character now type phone at the FootNote location. Then at the # character under the new page break type the following message. "Dial Pad has a built in database to store all your phone numbers". Your file should look like Figure 6.

Adding Keywords

As I stated earlier keywords show up in the Index search box, so any words that you wish listed in the Index search box that can help users find what there looking for should be set up as keywords in your RTF file.

  1. Under the Using Dial Pad topic place the cursor at the end of 10 10 20.
  2. Then select Insert then FootNote
  3. Select custom and enter K in the box and click OK
  4. Under FootNotes type 10 10 220
That's it you have just created a keyword and your RTF file should look like Figure 7.

Adding Graphics to your RTF file

With the Help Compiler, four types of graphics can be displayed within help topics: bitmaps, metafiles, segmented hypergraphics, and multiple resolution bitmaps.

Bitmaps - A bitmap is an image that is described by a matrix of memory bits that, when copied to a device, define the color and pattern of a corresponding matrix of pixels on the display surface of the device. Any one familiar with MS Paint has seen bitmaps(bmp). The draw backs are bmp can be large files.

Metafiles - A metafile is a collection of GDI commands that creates desired text or images. There are two advantages to using metafiles: the size of the metafile is small, and metafiles are less device- dependent than bitmaps. The disadvantage of using a metafile is that it takes a long time to draw one.

Segmented Hypergraphics - A segmented hypergraphic is a graphic that has hot spots defined in various regions of the graphic.

Multiple Resolution Bitmaps - A multiple resolution bitmap is a single bitmap file that contains one or more bitmaps that have been marked for use with specific displays. For out help file we will us a bitmaps since any one that has windows will have MS Paint and can create a bitmap.

There are two ways to add graphics to your help file. Copy and Paste is obviously the easiest, however if you are using versions 3 or 3.1 of the WinHelp you have a 64k limit per page. The other alternative is by Reference. So instead of being able to actually see how it will look in the actual help file you will just see a command to display the graphic when someone selects that help topic.

Copy & Paste

We will be adding the graphic you can download from the link below. You can add the graphic to your RTF by using the copy pasting method or using the insert option. To copy and paste just copy the bmp to the clip board and insert the picture where you want it displayed in the help file. If you wish to use the insert option, select Insert/ picture/ from file. That's it you have just added a graphic to your help file.

dialpad.bmp

By Reference

To adding a graphic by reference is easy, just make sure that you have the image you wish to display in the same directory as your help file. Use the following code to add the graphic to your help file.

{bml graphicName.bmp}

That's it when you run help and select the topic the graphic will be displayed. There are three(3) commands you can use to display your graphic by reference.

Figure 8 shows the copy method of adding graphics to your help file. Figure 9 show what it looks like by adding graphics by reference.

Adding HotSpots

Creating a HotSpot is as easy as creating a jump or popup message. Just select the graphic and turn on the double underline followed immediately by the hidden text. Just like creating the jumps and popup messages in the text earlier.

Using the Hotspot Editor

If you installed the WinHelp program then the Hotspot editor was included. With this editor you can create hotspots on your graphics. I will walk you through this method of creating hotspots. To load the Hotspot editor do the following:

  1. Load the Microsoft Help Workshop
  2. Under tools click on Shed
  3. Add the dialpad.bmp to the editor
  4. While holding your mouse drag it across the Dial button. It should now look like Figure 9a.
  5. Double click on the dial button, a dialog box will pop up. Figure 9b
  6. Under content string type "Dial"
  7. For type select popup, for Attribute type visible.
  8. Under HotspotID enter, "Dial" and click ok
  9. Save the file as dialpad.shg

You have just created a hotspot on the dialpad.bmp. Open the dialpad.rtf file and do the following to add the updated bmp file to your rft file.

  1. Add the following code {bml DialPad.shg} right under the About DialPad topic.
  2. Now select insert footenote and under Custom marks add the # character
  3. Now under footenotes add Dail
  4. Under the new # character type, "You clicked the Dial Button".

That's it, not only have you added graphics to your help file you have also add a HotSpot to the graphic.

Compiling your RTF Help file

By the time you finishing creating your help file you will have several new files.

Extension

File description

.hpj

help project files

.hlp

help files

.cnt

help contents files

.gid

help index files

The .gid file is generated by Windows the first time you run your help file and do a search. This file can be deleted. Now lets compile our help file.

To compile a RTF file open the HCW and select new/project. Name your help file and click the save button(if you are using the dialPad project then name the help file DialPad). You have just created the hpj file needed to create a hlp file. The application should now look like Figure 10.

Click the "Files" button located on the right, then click the add button. A dialog box will pop up, select the RTF file that you created for your help file(DialPad.rtf)then click ok. The file should now look likeFigure 11. Now click the, "Save and Compile" button on the bottom of the application. This will compile your RTF file in to a hlp file. To test the hlp file that was just created, click file then run WinHelp. A dialog box will pop up it should have the correct path of your help file (see Figure 12) then click, "View Help". Your help file will be loaded so you can test it out.

Handling Errors

While there are many error that can be generated when compiling help files I will deal with the two most popular.

Error HC1003 - Note A paragraph mark is formatted as a hidden character.

This happens when paragraph mark was included in the hidden selection when you were creating a jump or popup. To correct this just select the paragraph mark character and select format and make sure that under, "Effects" the hidden box is unchecked.

Error HC1017 -: Note: A non-scrolling region crosses a page break

This happens when the Keep With Next paragraph formatting used for specifying a non-scrolling region crosses a page break boundary. The topic beginning with the page break will have a non-scrolling region, whether or not one is intended.: Remove the Keep With Next paragraph formatting from the page break, and then recompile.

Notes Warnings & Errors

While it is possible for a help file to be generated even though there are Notes and Warnings attached. But a help file will not be generated if you get an error message.

Creating a Content File

To create a content file open help workshop and select new then help content then click OK. The program should look like Figure 13. Under default file name and default title type, "DialPad" (this is the name we named or help file). Now we are going to create the titles that will be displayed when the help file is loaded. to add the topics do the following.

  1. Click the, "Add Above" button
  2. When the dialog box pops up select Headings
  3. In the Title box type, "About Dial Pad" then click OK.

Now do the same for the rest of the Topics in your help file. However instead of clicking the add above button click the, "Add Below" button..

Remember when we created our topics we used the # character to tell the compiler that this is a link. We are going to use those link IDs to add jumps to our help titles.

The jump we used for About Dial Pad was About, so select the Abut Dial Pad title and click on the Add Below button. Select , Topic and type About Dial Pad in the title box and type About in the Topic ID and click OK. Do the same for the rest of your topics. Use the topic IDs below for the corresponding topics.

Using Dial Pad - Dial Pad
Using The Phone Book - PhoneBook

Your Help Content file should look like Figure 14. To see your new help file in action select File, Run WinHelp and click the View Help button. It should look like just like the one in figure 14.

Adding Help to your program

Here are a couple of ways to add your help file to your program.

Visual Basic

Make sure that your help and content file is in the same directory as your VB app. Then under the main form add the code below.

Private Sub Form_Load()
App.HelpFile = "DialPad.hlp"
End Sub

This code will load the help file when you click on the F1 key.

If you added a Help topic to your VB program menu the following code will display your help file. Of course you must add the CommonDialog control to the form.

Private Sub mnuHelp_Click()
CommonDialog1.HelpFile = App.Path & "DialPad.hlp"
CommonDialog1.HelpCommand = cdlHelpContents
CommonDialog1.ShowHelp
End Sub

VC++

void YourClass::WinHelp(DWORD dwData, UINT nCmd)
{
//you can use dwData, nCmd if you want
::Winhelp(..........\yourhelpfile.hlp.......);
}

this will invoke your help file while the user presses F1. But if you have help support included in the project all you have to do is add the help file where your exe is.

Conclusion

Congratulations! You have completed your first help file. Now that wasn't too hard now was it? It maybe a little over whelming but the more help files you create the easier it will become.

Help authoring tools

However there is more then one way to do anything including creating help files. There are a lot of Help Authoring tools on the market. Some are free and other are very expensive. Below is a list of Help tools, while I can not a test to all of them, I have used the free version of HelpWriter. HelpWriter has a VB and Delphi version.

HelpWriter http://www.helpwriter.com/

Visual Help http://www.winwareinc.com/visualhelp.html

RoboHelp http://www.ehelp.com/ehelp.shtm

.hlp http://www.auricvisions.com/welcome.htm

Help Magician http://www.helpmagician.com/

 

Resources

Microsoft Knowledge Base

Q171958 Tips for Creating and Compiling Your Windows Help File

Q90291 Using Graphics Within a Help File

Delphi WinHelp Delphi does WinHelp

WinHelp Questions & Answers This site has a list of Q & A on WinHelp

WinHelp This site help explain the WinHelp lingo.

Helpmaster This site is filled with resources on creating help files

WinHelp Mailing list You can join the list or search through its archives.

 

 

 

Copyright© 2001 Marietta Crockett
Disclaimer