Welcome to Australian PC User Magazine Offline CD-ROMPC User Online - Your complete guide to the Internet
Get on the Net Guide Games' Guide Education General & Business Applications Online Tools - All your Net Essentials Utilities Patches & Support Files PC User Interactive - Exclusive tutorials
Software Contents

Home
Search
Help!

PC User Interactive

Adding a help file - Part 1

Helen Bradley shows you how to add a help file to your Visual Basic projects.

 

The help file that you'll create in this project will fit into the Quote of the day program which was the project in the May and July '98 issues.

If you didn't complete the project you can still complete all of this month's project and create and test your own help file (see Figure 1e). Next month you'll learn how to link the help file to your Visual Basic project - if you haven't created the Quotes project you won't be able to link the help file to it but you will learn how it can be done for your own projects.

 

On this month's CD-ROM
you'll find the help topic file quotes.rtf and the help project file quotes.hpj.

You'll also find a plain text file quotes.txt containing the unformatted text for the topic file to which you can format and add the footnotes required to create your help topic file -- this file just saves you having to type the text yourself. Use these files to follow the tutorial and to practice compiling and testing the help application.

You will find these files in the interact/helpfile folder on the CD

Installing the Help Compiler
Before you can create a help file you'll need to install the Help compiler which is included in the Visual Basic Professional edition but isn't installed in a Typical install. If you don't have the Professional edition you can download the Help Compiler (called Help Workshop) from Microsoft's Web site; see the box 'Help Workshop and Word 97 incompatibility warning' for details on finding it.

To install the Help Complier from your CD-ROM:

Step 1: Place the Visual Basic program disc in your CD-ROM drive and select Start, Run.

Step 2: Select Browse and change to the \Tools\Hcw directory of your CD and select the file Setup.exe from that directory. Click Open and then OK.

Step 3: Follow the installation routine (select Typical) and the help program will be installed in a new group called Microsoft Help Workshop in your Programs list.

 

 
note.gif (244 bytes)Footnote symbols used in help file.
Tools you'll need
In addition to installing the Help Compiler, you'll need a word processor capable of saving files in Rich Text Format (*.rtf) and one capable of saving pure ASCII text files. All recent versions of Microsoft Word for Windows allow you to do both as will a number of other word processors. In this column we'll use Word 97 as the word processor; see box 'Help Workshop and Word 97 incompatibility warning' for overcoming incompatibility problems with Word 97.

 

The only theory you really need know
Your help file will be compiled from two separate files: the first is the topic file and the second is a project file. The topic file contains the actual text which will appear in the help screens as well as information about the hyperlinks contained in the text. Like any other Windows help file your help can contain two types of links: popup links and jump links.

The jump phrases for your popup links appear in the help window with green dashed underlines; when the user clicks on one a small box appears over the current help window. Typically this box will contain additional information such as a definition of the term or word that the user has clicked on although it can also contain graphics or multimedia files.

Jump phrases for jump links appear in the help window with solid green underline. When a user selects one of these they will 'jump' to another help window containing more information about that topic.

You'll create the topic file as a rich text file and each popup topic or jump topic will appear on a separate page of your text file. Within the text, the type of link will be indicated by the formatting of the jump phrase itself -- jump links are formatted with a double underline and popup links with a single underline.

Each underlined phrase is followed immediately (no spaces between them) by a topic ID which is a piece of text identifying the topic which you will 'jump' to or which will 'pop up'. The topic ID should be formatted as hidden text (no underlining) and can be up to 255 characters in length. A handy rule of thumb is to use only characters and numbers for your topic IDs and don't use spaces or other special characters (look up 'Topic ID' in the Help Author's Guide if you are interested in exactly what you can and can't use).

The actual links within the help file are created using the footnote function of your word processor. There are three main types of footnote symbols you can use -- each topic must have, at least, a topic ID footnote. See the table 'Footnote symbols used in help file' for the footnote symbols used in this month's help file.

If this all seems a little complicated, it is! However, once you've created your first help file come back to this section and study the file alongside these notes and it will all make sense.

 


Figure 1e: In this month's Visual Basic column you'll learn how to create professional looking help files for your projects.

 

 



Figure 2e: Your help topic file should look like this when you have formatted the jump phrases and the topic IDs to jump to.

Creating the Topic file
To create the topic file for the Quotes program:

Step 1: Open your word processor. If you're using Word 97 (or an earlier version) turn on display of Hidden text by selecting the Show/Hide button on the Standard toolbar. You'll also find that it is easier to see what's going on if you select View, Normal.

Step 2: Select Arial, nine point type and then type the Topic file text from the box 'Code for Topic file'. Just before each topic heading (they are formatted in bold type in the table) select Insert, Break, Page Break (or press Control+Enter) to insert a page break and format each topic heading as bold type.

Step 3: Apply the required formatting to these words which all appear on the first page of your document (this is your main help screen). Do this by selecting the text and, for single underlining, select the underline button on the Formatting toolbar or press Control+U. For double underline select Format, Font, select the Font tab and from the Underline list box select Double and OK, or press Control+Shift+D to toggle double underline on and off. For hidden text select Format, Font, select the Font tab and select Hidden and OK, or simply press Control+Shift+H to toggle hidden text on and off. The Explanations are to help you follow what is being created with each format selection.

Note that there are no spaces between the underlined text (jump phrase) and the topic ID which follows it. Your first page should now resemble the one in Figure 2e.

Step 4: Add the footnote text for each of the help topics. To do this, place the insertion point immediately before the text to add a footnote for and select Insert, Footnote. Select the 'Custom mark:' option button, type the footnote symbol in the text box and click OK (see Figure 3e). The footnote area will appear on the screen with the footnote symbol and you can then type the text for that footnote (see Figure 4e). Repeat for each footnote required for each topic. The explanations are simply to help you follow what is being defined.

Step 5: Save the topic file using File, Save As. In the Filename text box type quotes.rtf and from the Save As Type list box select Rich Text Format (*.rtf) and click Save.

 


Figure 3e: Help topics are marked for indexing and as places to jump to or popup using the footnote function in your word processor.

 

note.gif (244 bytes)Code for Topic file

 

 

 

note.gif (244 bytes)Text for footnotes
Create the project file
The project file contains all the information that Help Workshop needs to create a help file from your topic file. The project file used here contains the minimum information required in a project file.

Step 6: Open a new word processing document and type the text of the project file from the box 'Project file'.

Step 7: Save the project file in the same directory as your topics file (quotes.rtf) using File, Save As. In the Filename text box type quotes.hpj and from the Save As Type list box select Text Only (*.txt) and click Save.

The project file has an [OPTIONS] section containing the Topic ID of the main contents screen which is the page titled 'Daily Quotes' and text which specifies the title for the Help window -- 'Daily Quotes Help'. It also has a [FILES] section which contains the name of the topics file -- quotes.rtf.

 


Figure 4e: Topic pages are marked so that they can be jumped to using the footnote function in your word processor.
Compiling your help file
Once you've created the topic file and the project file you're ready to compile your help file. Load the Help Workshop (from the Microsoft Help Workshop program group) and select File, Open. Locate your quotes.hpj file in the Open window, select it and click Open. From the Help Workshop's main screen select the 'Save and Compile' button to compile your help file.

Once the file is compiled the screen will display a report from the compiler (see Figure 5e). Read this as it will tell you if there were any errors during the compiling process, what they were and where the compiler found them (Note: if you are using Word 97 see the box 'Help Workshop and Word 97 incompatibility warning' for details of overcoming the incompatibility between Word 97 and the Help Workshop).

If the compiler encountered errors you'll need to return to your word processor, open quotes.rtf or quotes.hpj file (the problems are most likely to occur in quotes.rtf), make your changes and save the file again. Then return to the Help Workshop, open quotes.hpj again and run the compiler a second time. Repeat this process until you eliminate all errors in your help file.

 


Figure 5e: Once you've compiled your help file you'll see a report from the compiler indicating if there were any errors encountered.
Testing your help file
To test your help file, open Windows Explorer and locate the file quotes.hlp which will be in the directory that contained your project file. Double-click on the file and it will be loaded so that you can test it. The contents page should look like the one in Figure 1e. Experiment with selecting the popup links and the jump links and select Index to view an index of help topics.

 

note.gif (244 bytes)Help Workshop and Word 97 incompatibility warning

note.gif (244 bytes)Project File

note.gif (244 bytes)Topic File

Simple refinements to your help file
The help file that you have created is only the 'bare bones' of a help file. The topics 'The Main Quotes Screen' and 'Managing your Quotes file' need more information added to them and you may want to add more help topics to the file and other jump or popup links.

You can add to your help file and change any of the details in it by editing your quotes.rtf file. You can also alter the formatting of the text as this will be retained in the compiled help file. After you have made alterations to your quotes.rtf file, save it and then compile it again using the above instructions.

 

toppage.gif (1757 bytes)copyrite.gif (1355 bytes)