CREATING WINDOWS HELP FILES --------------------------------- Copyright December 1993 by Theodore Kahn. All rights reserved. tedkahn@netcom.com CIS 70353,2603 (510) 562-9900 ABSTRACT ----------------------------------------------------- There are a number of Help Authoring Tools that simplify the more mechanical tasks of creating a Help file, such as creating topics, making topic jumps, and running the Help compiler. However, diagnosing errors (especially the nontrivial ones) is still mostly left to you, the programmer. Also, claims notwithstanding, Help Authoring Tools do not provide access to all features. This article fills in these gaps. Specifically: * We concentrate on the most used and needed Help features, providing the technical background necessary to understand what your Help Authoring Tool is doing, or not doing. * We point out problems and errors and offer work- arounds and alternate solutions. * We provide information about features not contained in the Microsoft Help Complier documentation that comes with VB. * We include detailed information for integrating the Help file with your VB program. * We are making available a companion Help file and VB program that illustrates many of the features and ideas discussed in this article, and more. While some of this information is specific to Visual Basic programmers, the vast majority is applicable to all Help developers. THE HELP COMPLIER --------------------------------------------- The Help Complier (a DOS program) is at the center of the Help file creation process. It takes as input the Help Project File and creates the Help file. There are a number of versions of the Help Complier. The one you want (for Windows 3.1) is HC31.EXE Version 3.10.504 (extended), or later. This is the version that has been shipping with VB Professional. (Note, this is the same identical version as the HCP version that ships with the SDK.) Some Help Authoring Tools also include the Help Complier. However, they may not be the latest version, which can cause problems when compiling larger Help files. If you are using WinWord 6, you will need to get version 3.10.505 or later as WinWord 6 RTF files will not work with earlier versions of the Help compiler. Below are a few Compiler errors that we found troublesome or had difficulty understanding: * Error 1319 Disk Full. Microsoft documentation says that this error occurs when the disk the Help file is created on is full, which is true. However, this error also occurs when the disk referenced by the TEMP environment variable is full, which is not documented. * Error 4792. Nonscrolling region defined after scrolling region. One or more non-title paragraphs have the attribute "Keep with next" set. To quickly find the offending paragraphs, (in WinWord), search for this attribute being set, and unset it. * Errors 4733, 4753, and 4763. Hidden page break, paragraph mark and carriage return, respectively. As in the previous error, search for these attributes being set, and unset them. *Error 4813. Nonscrolling region crosses page boundary. Look for a hard page break where one shouldn't be. Hard page breaks should only occur at the end of a topic. HELP PROJECT FILE --------------------------------------------- The Help Project file is an ASCII text file that you create and edit using an editor (such as Notepad). It consists of up to nine sections which either control various options or reference files required by your Help file. fIGURE 2 shows a sample Help Project File with the six most commonly used sections. The [OPTIONS] section is generally pretty straight forward. Two things to note: * Be sure and set COMPRESS to False, unless its the final release version, then set it to True. There are significant differences in both compile times and Help file size depending on this option setting. * The documentation doesn't mention the CITATION keyword. The text you enter here is automatically included in the Copy Dialog Box. Consider using the same text as in the COPYRIGHT keyword. The [FILES] section is the only required section. You must specify at least one RTF file. You may want to consider multiple RTF files for larger Help file projects. As an example, each such file could correspond to a different area of the program for which the Help file is being written. This has two advantages. First, your word processing file won't get so large as to be unmanageable. Second, for debugging purposes, you can compile only the RTF file of interest. To exclude RTF files, precede the file name with a semicolon. In this case, you may get warning messages about missing topics. Nonetheless, this a good method for quickening compile times when you are mostly dealing with basic structure and syntax issues. The [BUILDTAGS] section allows you selectively compile topics depending on each topics BUILDTAG value. For example, suppose you have two versions of your program, regular and deluxe. The deluxe version has more options which need their own Help topics. You might then set the Build tag Control code for deluxe topics to "deluxe" and exclude them from the regular version Help file. In this case, you would enter the following lines in the BUILDTAGS and OPTIONS sections: [BUILDTAGS] deluxe [OPTIONS] BUILD=~deluxe The tilde (~) character denotes "not." That is, the Help file will consist of all topics having Control code Build tags other than deluxe, or no Build tag control code. (Control codes are discussed in their own section.) The [CONFIG] section is where you but all the Help macros that should be executed when the Help file is started. A lot of the visual customization of your Help file occurs here. This is discussed more fully in the Help Compiler Macro section below. The [BITMAPS] section is where you specify the graphics files you included "By Reference" in your word processing files. Note, the name notwithstanding, you also specify .wmf, .shg, and .mrb files here as well. This is discussed more fully in the Graphics section below. The [MAP] section is the one place in the entire project that connects your VB program to the Help file. Specifically, it associates each Help topic (context string) to a VB Form or Control HelpContexID property value. You can enter the relationships directly, one per line, or reference a file. A typical map relationship might look as follows: Print_dialog_box 60015 In this example, the Help file has a topic with a context string of "Print_dialog_box." The corresponding VB form for which this topic applies would have its HelpContexID property value set to 60015. Then, when the user presses F1 while print form has the focus, the Help File would be invoked and the "Print_dialog_box." topic displayed. There are other related issues that are discussed in the section "Integrating Help Files with a VB Program." The [ALIAS] section allows you to assign multiple context strings to the same topic. You may never need this facility, however, if you do, its nice to know it exists. It is probably most useful when, after writing the Help file, you decide to merge several topics into one. Without an ALIAS you would have to change all references to the original topics to the merged topics, both in the Help file as well as your VB program. Using an ALIAS requires just one line in the [ALIAS] section for each topic being merged. The [WINDOWS] section controls various characteristics of the window display, such as size, position, and colors. Setting the background color of the topic non-scrolling region can be a nice visual enhancement. This section is required if you intend to have secondary windows, a feature many Help files can benefit from. The [BAGGAGE] section is where you specify multimedia files, such as wave files. Unless you know that all your users are going to have the necessary hardware to use these files, it is best to avoid them. THE HELP FILE ------------------------------------------------- The Help file (as it appears to you in your word processor) consists of a series of topics. Each topic contains text and/or graphics which are displayed when the topic is selected. A topic also includes one or more codes (discussed below) which provide hypertext related information. A topic may also contain jumps and Help compiler macros (discussed in their own section) which the user can execute. There are two types of topics (as it appears to the user), regular and popup. It is important to note that the difference is not coded into the topic itself, but rather, is dependent on the type of jump which caused the topic to be displayed. Please note that the order the topics appear in your word processor has no bearing on how it appears in the Help file. The display of topics in the Help file is dependent on how you coded the hypertext control codes and the user selection. TOPIC ORGANIZATION ------------------------------------------- The first paragraph of a topic is, by definition, is the topic title. The title can include both text and graphics. Usually topics have only one line titles, but this does not have to be the case. You could, for example, use a second line as a subtitle. You might also consider different fonts, sizes, and colors for titles and subtitles. VB help does this. A nice touch for many Help files is to make the topic title a non-scrolling region. This simply means that as the user scrolls through the topic, the title always remains on the screen. A further enhancement is to specify a different background color for the non-scrolling region. This is done in the [WINDOWS] section of the Help Project File. All non- scrolling regions of a Window must have the same background color. The [WINDOWS] section at the bottom of Figure 2 shows how to specify a pale yellow non-scrolling region. All paragraphs after the title are considered the body of the topic. There is no preset limit to how large a topic can be or how many topics a Help file can have. The end of a topic is indicated by a hardpage code (Ctrl-Enter in WinWord). The paragraph following a hardpage code, would then, by definition, be the title of the next topic. CONTROL CODES ---------------------------------------------------- There are six control codes. Entering these codes and specifying the correct information can be the most difficult aspect to understanding how a Help file is constructed. This is especially true if you don't understand what the different hypertext elements do and how they work together. Help Authoring Tools largely take care of the mechanical aspects of entering the codes and associated information. However, they don't all do them equally well. So, when an error occurs (and they will!) or your Help Authoring Tool does not support a feature you want, you will have to know what's going on behind the scene to get the job done. First, some general information Control codes: * Control codes are indicated by custom footnote characters. * Control codes are usually put before the first text or graphic of the topic title. * Four Control codes (#, $, k, +) provide different hypertext methods for displaying topics. A topic with no codes is possible, but can never be displayed. To insert a custom footnote character in WinWord Version 2, choose Insert Footnote and select the Custom Footnote Mark option. The character you enter here defines the type of Control code you are specifying. Then enter the footnote text, which becomes the hypertext information for that code. To see and edit the footnotes (in WinWord), choose View Page. All Help Authoring Tools perform this task for you in a more automated fashion. But we have encountered problems where we needed to do this manually to achieve the desired effect. Examples include multiline topic titles, mid-topic jumps, and mid-topic keyword jumps. The Control code names and associated footnote characters are listed below. The first four codes control the hypertext nature of the topic. CONTEXT STRING (#) The context string identifies each topic in the Help file and must be unique to that topic. That is, no two context strings can be the same. The string can be any letter (a-z, A-Z), number (0-9), period (.), and underscore (_). The string is not case-sensitive and can be up to 255 characters. Context strings are required if you intend to jump to the topic. Generally, all topics are given context strings as there is no reason not to and you'll never know if you might want to provide a jump to the topic in the future. Topics can have any number of context strings located anywhere in the text. This allows you to jump to any part of a topic, not just the beginning. This feature is not well documented and many Help Authoring Tools do not provide a mechanism for coding mid-topic jumps. Nonetheless, many Help files could benefit from mid-topic jumps. To see an example of this, run the VB Help and click on the Glossary. Then click on the various letters at the top. The jumps being executed go to different parts of the same topic. The letters are simply hotspots with jumps referencing the various context strings in the topic. Consider including mid-topic jumps anytime a topic contains a lot of text in an ordered fashion. Remember, you can also execute mid-topic jumps directly from your application. It is likely that your Help Authoring Tool does not support mid-topic jumps, so you'll have to enter them manually. This procedure is identical to entering the main context string: Move the cursor to the text where you want to jump to and insert a # footnote character. Then type the context string as the footnote text. TOPIC TITLE ($) The title text is entered using the $ footnote character. The text you enter here is displayed in the Goto section of the Help Search Dialog Box when a keyword (see next section) is selected. This text can be the same or different than the title text in the first paragraph. Some Help Authoring Tools may not allow you to directly enter different text for $ footnote, in which case you will have to do so manually. Topics usually include the $ footnote. The two exceptions are when: * The topic appears only as a popup or; * The topic appears only in a secondary window. If the $ topic footnote is omitted, you should also not insert the k footnote keywords, as the Search Dialog Goto list would display ">>Untitled Topic <<". KEYWORDS (K) Keywords are entered using the k footnote character. The footnote text contains the keywords, which should have the following syntax: * Keywords can include any ANSI character except a semicolon. * A semicolon is used to separate multiple keywords. * The maximum length for all keywords is 255 characters. Keywords work in conjunction with the $ footnote title. Therefore, for any particular topic, you would code both $ and k Control codes, or neither. Be careful when using different forms of a keyword (or phrase) in different topics. For example, if in each of four topics you had coded "print information", "print dialog box", "printing graphics", and "printing documents", the index would contain the four keyword phrases, each pointing to its own topic. Its better to code the same generic keyword in all four topics. In this case, it might be "printing." Now when the user selects "printing" from the keyword list the four topic titles appear in the Goto list below it. Here is an example of multiple keywords: Suppose you had a topic titled "Printing Documents." The two keywords might then be "printing" and "document." Note that lower case is used as this is an index and that the singular form of document is used, not the plural as in the title. Then, the word "document" might also appear in topics titled "Opening Documents" and "Saving Documents." The Keyword footnote does not have to be at the beginning of the topic. This is not well know and almost no Help Authoring Tool supports it. Place the footnote any where you want. When the user selects the topic from the Search Dialog Box, the topic text at the keyword footnote is displayed at the top of the Help window. This is simular to a mid-topic jump. BROWSE SEQUENCE (+) The browse sequence is entered using the + footnote character. The footnote text contains the sequence which is composed of two parts: the group name and a sequence number separated by a colon (:). The browse sequence provides the user with a quick and convenient way to move through topics in an ordered fashion. Forward or backward movement is accomplished by clicking the browse (>> or <<) buttons on the Help screen (or pressing the period or comma keys). As an example, suppose you had the following three topics Printing Overview, Print Dialog Box, and Print Dialog Box Options. The information goes from general to specific, and so follows a natural progression. In this case the browse sequences might look as follows: Printing Overview PRINT:00010 Print Dialog Box PRINT:00020 Print Dialog Box Options PRINT:00030 Each click of a browse button displays the topic having the next higher or lower sequence. When the topic with the highest sequence is being displayed, the >> button is disabled, conversely, when the topic having the lowest sequence is displayed, the << button is disabled. Pressing the browse buttons will never jump the user to a topic with a different Group Name. If the topic being displayed does not have a browse sequence, both buttons are disabled. Some Help Authoring Tools do not provide a direct method for changing the Group Name, or do not include a group name. This diminishes the browse sequence utility, as clicking the browse button displays topics that may or may not have related information. Note: In order to make the browse buttons (<< and >>) visible you need to add the BrowseButtons() macro to the [CONFIG] section of your Help Project File BUILD TAGS (*) A Build tag is added to the topic using the * footnote character. This unique identifier allows you to include or exclude particular topics from the Help file based on the string. See [BUILDTAGS] in the Help Project File section for more information. EXECUTE MACRO (!) To execute a macro when the topic is displayed insert the ! footnote character before the topic title. This facility is not discussed in the Microsoft documentation. By being able to execute a macro upon topic display you can customize the Help file visual appearance and options on a topic by topic basis. At first glance, this appears to be a very powerful feature. Unfortunately, there is no corresponding method for reverting to the appearance/options in place before the topic was displayed. In order to do so you would have to put in such a macro in all other topics to which the user could jump. And of course, using the Search Dialog Box, the can jump to just about all other topics. For this reason, this Control code is rarely used. There is one situation is which you might consider using it. If you had a "special" topic for which different options were applicable, you could disable the Search Dialog Box, and History, Bookmark, and Browse buttons, and all other means of the user jumping to another topic. You would then include in the topic one macro that jumps to the topic of your selection. This topic would have ! footnote macro to change the Help file options and appearance back to their standard form. TEXT FORMATTING Text formatting can be a very frustrating experience when creating Help files. While your word processor contains a wide variety of features for controlling the visual appearance and positioning of the text, the Help Compiler supports few of them. In many cases, the compiler simply ignores your formatting commands, and in others it will generate an error message. CHARACTER FORMATTING You can use any font and point size, but your users must also have the font on their machines. Therefore its best to stick with fonts that are installed with Windows, such as Arial, Courier New, Symbol, and Times New Roman. Bold, underline , italics, and color can be selected, super- and subscript cannot. Sometimes subscript can be approximated by using a smaller font size. Be careful when using color, as users with monochrome screens may find it difficult to read, and certainly not pretty. SPECIAL SYMBOLS Windows 3.1 includes the Symbol TrueType font which contains Greek alphabet, as well as many other useful characters. This font can used just like any other TrueType font. However, there is an incompatibility between WinWord Version 2 and the Help Complier which leads many people to think otherwise. (If you are using another word processor, you may not have this problem.) The logical and straight-forward way to insert a symbol is to use the Insert Symbol command. This looks fine in the WinWord file, but the character will not display in the Help file. Instead, select the Symbol TrueType font from the font list box; then enter the character. There is one further issue, many of the characters do not map to a standard keyboard character. In these cases, you must enter the character by turning keyboard NumLock on, pressing the Alt key and entering the four digit code (be sure and enter leading zeros). Use the Character Map program that comes with Windows to find the character codes. PARAGRAPH FORMATTING Paragraphs can be left, centered, and right justified, but not full justified. When Help text is displayed, lines are automatically wrapped at word boundaries to fit the window width. If you want text lines to always break at the same place in the line, enter a line break at the end of each line, as you want it to appear in the Help file (Shift- Enter in WinWord). Then, select the "keep lines together" paragraph format attribute. (This attribute keeps a paragraph on one page.) TABLES Tables are the best way for working with columnar formatting. You cannot, however, apply any line or shading attributes to the table, such as cell boarders. Your only choice is to apply paragraph borders. To add paragraph borders (in WinWord) for text inside a table, select one or more characters in the paragraph and then select the Format Boarder Dialog Box. If you do not select the characters, the Border Dialog Box applies to the Table cells, not the paragraph. This causes Help Compiler error 4652, Table formatting too complex. Also, remember you can include graphics in the table cells. There are some other formatting features relating to tables that are discussed in the Microsoft Help Authoring Guide (see the sidebar Additional Information on how to get this guide at no charge.) POPUP TOPICS As we already mentioned, topics appearing in a popup window are really no different than other topics. It only means that a popup macro (or jump) was used to jump to the topic. However, as a general rule, topics displayed only as popups do not have entries in the Search Dialog Box or a browse sequence (Control codes $, k, and +). They do, however, have to have a context string (Control code #) so that the jump to the topic can be made. The popup window width is a function of the screen and Help window sizes. This can cause them to become very wide. To make the popup window have a constant size, manually insert line breaks where you want them and select the paragraph attribute "keep lines together." See Paragraph Formatting for more information. Another alternative is put the text inside a one cell table. IMPORTANT: The title paragraph of pop-up topics should NOT have the "Keep with next" attribute set. If it is set, the remaining paragraphs in the topic are not displayed (and there is no error message). The "Keep with next" attribute indicates that the topic is to have a non-scrolling title region. Some Help Authoring Tools use one style for all topic titles. In this case, specifying a non-scrolling region causes the "Keep with next" attribute to be set for popups, which results in popup topic text not displaying. GRAPHICS ---------------------------------------------------- The Help Compiler supports four types of graphics files: bitmaps (BMP), windows metafiles (WMF), hypergraphic (SHG), and multiple-resolution bitmaps (MRB). The latter two formats are special formats that can only be used by the Help Complier. The programs to create SHG and MRB files are included with VB professional. INSERTING GRAPHICS FILES BMP and WMF files can be put directly into your word processing file, at the position where they are to appear. However, the preferred method is to insert them "by- reference." SHG and MRB files can only be inserted by- reference. To insert a graphic "by reference": 1. In your word processing document you need to enter {bmX filename} where X is L for a left justified graphic, C for a character and R for a right justified graphic. (WinWord users note: this is not a field code as the braces would otherwise indicate.) 2. In your Help Project file [BITMAPS] section add a line referencing the file. Note, if the bitmap file is located in the project directory or a bitmap root directory, you don't need to include a specific reference in the HPJ file. A graphics file is specified only once in the [BITMAPS] section, no matter how many times it is referenced in the word processing document (Step 1). Inserting graphics by-reference leads to a smaller Help file, especially when the same graphic is referenced multiple times. CREATING HYPERGRAPHICS FILES SHG files are BMP or WMF files that have been processed by the hotspot editor (SHED.EXE). SHED allows you to define hotspots (rectangular regions) to a BMP or WMF file. A macro (such as a jump macro) is then assigned to each hotspot. When the SHG graphic is displayed in the Help file and the cursor is positioned over a hotspot, the cursor changes to a hand. This indicates to the user that clicking the mouse initiates the macro, such as jumping to another topic. Make sure you are using SHED Version 3.50.784 or latter. This version has a new feature in the Edit menu called Replace. Documentation on how to use SHED can be found in the Microsoft Help manual and the SHED Help file. However, neither document contains information on Replace, so here's what it does. Suppose you had created a SHG file with 10 hotspots, each with a different macro. Now, your colleague responsible for creating the original BMP file comes up to you and says she has newer version with better colors. Here's how you'd handle it using Replace: 1) Start SHED and open up the SHG file having the 10 hotspots. 2) Start a graphics program that can read BMP files (such as PaintBrush) and open up the new BMP file. 3) Copy the BMP file to the Clipboard. 4) Go back to SHED and select Edit Replace. The new graphic image replaces the graphic image in the shg file, leaving the hotspots in place, along with their macros. If the hotspot positions did not change there is nothing left to do but save the new version. Otherwise, you have to move the hotspots to their new correct regions, which is a very easy task. Then save the file. CREATING MULTIPLE-RESOLUTION BITMAP FILES Bitmap graphics do not scale easily to different resolutions from the one that created them. The Multiple Resolution Bitmap Compiler (MRBC) allows you to create the dame bitmap image under different resolutions and puts them together into one file. The WINHELP.EXE will then use the version that best matches the screen resolution at the time. If your application is not intended to run under CGA and EGA resolutions then will not likely need to bother with this step Consider using Windows Metafiles whenever possible. They don't have resolution scaling problems and can also be much smaller. MACROS Macros (which can also be thought of as programming statements) greatly extend the intrinsic Help Complier capabilities. The first thing to realize is that macros can be started in six different ways: 1) When the Help file is started. These macros are put in the [CONFIG] section of your Help Project file. 2) Double underlined text or graphic hotspot. The jump or macro follows directly after the underlined text, is marked hidden, and (if a macro) is preceded by an explanation point. 3) Hypergraphic hotspot. Hotspots are created using SHED.EXE. Each hotspot is assigned its own jump or macro. 4) When a topic is displayed. The macro is put into the ! footnote text. 5) When menu items or buttons at the top of the Help screen are selected. 6) By your VB program. Use the WinHelp function and pass the macro as a parameter. MACRO SYNTAX Pay close attention to the syntax when writing macros, as the error message you are most likely to get is "Syntax error in macro..." When you get this message, check for unbalanced parentheses and quotation marks, and commas in the right places. Also make sure that open and close quotes are used in the correct place. Remember, they must be used with nested strings. * The general syntax is MacroName(`parameter1', `parameter2',...) * Macros can be nested. * Macros can be executed sequentially by separating them with semicolons. In some cases, when the macros are executed from the Help Project file, you may need to use a colon, as the semicolon is used for indicating comments. I have not seen the colon documented anywhere. * String parameters must be enclosed in a single open and single close quotation marks. Double quote marks can also be used. * Nested strings must be enclosed using the single open and single close quotation marks. * Note, the single open quotation is often found with the tilde (~) key and the single close quotation is found with the double quotation mark. They are not the same characters. * To include the above syntax characters in a string, precede the character with a backslash (\). EXAMPLE ----------------------------------------------------- Jumping to a secondary window is probably the most commonly used macro. In this example we show how to execute the macro from three different places: the Help file, the Help Project File, and your VB application. In all cases, the name of the Help file is "myapp.hlp," the secondary window is called "glossary." and the context-string of the topic being jumped to is "g_topic." (Note, in order to jump to a secondary window, you it must have been defined in the [WINDOWS] section of the Help Project File.) The name of the jump macro we will use is JumpId. Its general syntax is JumpID(`filename>windowname', `context-string') This macro jumps to a topic based on its context string. A similar macro, JumpContext, jumps to a topic based on its context number. The ">" character separates the two parts of the parameter. The >windowname is optional if you not jumping to a different window and the filename is optional if you are not jumping to a different Help file, therefore a null string is acceptable. However, if you are jumping to a different window, the filename must always be specified, whether or not the topic is in a different Help file. Substituting our values into the above syntax, we have: JumpID(`myapp.hlp>glossary', `g_topic') To use this macro in a Help file, precede it with and explanation point (!) and format it and macro as hidden text. Then format text or graphic preceding !macro as double underlined to indicate to the user that clicking the text/graphic causes an action to occur (macro to execute). Because this type of jump is so common, the Help Complier supports a second, simpler syntax for jumping to topics: context-string>windowname@filename You only need to specify the >windowname or @filename if you are jumping to a different window or Help file. As above, format this text as hidden and precede it with double underlined formatted text or graphics. Note, you do not need the explanation point. This form also works for hotspot jumps created by SHED. While these simpler forms work fine for jumps initiated within the Help file, they cannot be used from the Help Project File or from your VB program. In either of these cases, you will need to use the JumpID macro. Next, we show how to create a button on the main Help button-bar to execute the jump macro. First, because we want the button available when the Help file starts (that is, not to be dependent on the topic being displayed), the macro should be put in the [CONFIG] section of the Help Project File. The general syntax is : CreateButton("button-id", "button-label", "button-macro") The button-id gives you a method for referencing the button in other macros; the button-label is the text displayed on the button; and the button-macro is the macro string that is to be executed when the button is clicked. Our CreateButton macro might look as follows: CreateButton("g_button", "&Glossary", "JumpID(`myapp.hlp>glossary',`g_topic')") Notice the single quotes in the JumpId macro above, in this case double quotes generates a syntax error. Executing Help macros from your VB program involves passing the macro string as a parameter to the WinHelp function. This is discussed in detail in the next section. INTEGRATING THE HELP FILE INTO YOUR VB PROGRAM ---------------------------- There are two distinctly different methods for integrating the Help file into your VB program. The first method, which is largely built-in to VB, provides context- sensitive help. If, however, you want to include a Help menu item, or execute Help macros from within your program, you will need to use the WinHelp API. In either case, the first thing you need to do is specify the name of the help file. By convention it usually has the same name as the exe file, but with a hlp extension. The easiest way to set the file name is at design time: Select Options Project from the menu and enter the file name into the box labeled Help file. From then on (in design or exe modes) the method App.HelpFile returns the specified help file. CONTEXT SENSITIVE HELP Forms and controls (that can receive the focus) have a property called HelpContextID. This value is associated with a specific Help topic using the context string. The associations are made in the Help Project File [MAP] section. When the user presses F1, the Help topic for the control (or Form) having the focus is displayed. If the control (having the focus) HelpContextID has not been set, then the Help topic for the controls container is used, and so on. When no Control or Form HelpContextID has been set, the Contents Help topic is displayed. For example, suppose a form has a picture box containing two command buttons. The HelpContextID values are: Button1 = 1 and Picture = 2. Button2's HelpContextID has not been set. When Button1 has the focus then its Help topic is used. However, when Button2 has the focus, the Picture control Help topic is displayed. One source of confusion here is that the Microsoft documentation uses inconsistent terminology: The VB manuals refer to HelpContextID whereas the Help Compiler uses the term context number, they are the same. Also, remember that you can change the HelpContextID programatically. This might be useful in situations where the selection of certain option(s) changes the availability of other options. In these situations, you could have multiple Help topics for the same control, each specific to a different option set. Using the WinHelp API opens up many other possibilities for customizing not only the text, but how its presented to the user. THE WINHELP API Included with every copy of Windows is a program called WINHELP.EXE. This program is used by all applications to display help files complied by the Help Complier. The WinHelp function allows you to send instructions to WINHELP.EXE for performing a variety of tasks. Examples include: displaying topics that may not be associated with a specific control, bringing up the Search Dialog Box, and closing the Help file when your application ends. Knowing how to use the WinHelp functions can significantly increase your programs usability. Figure 6 shows the required WinHelp declarations which need to be included in your application, and four routines that illustrate typical help usage. In essence, the WinHelp function provides a mechanism for accessing Help Compiler macros from within your program. There are, of course, issues that need special handling. Figure 6 address two common ones. Displaying the Search Dialog Box. Some programs provide direct access to the Help Search Dialog Box from the Help menu. If you look through the Help macros you would find Search(), which indeed performs exactly that task. Using Search(), the WinHelp function would look as follows: r = WinHelp(frmMain.hWnd, App.HelpFile, HELP_COMMAND, `Search()') This function invokes the Help file, displays the Contents topic and brings up the Search Dialog Box. A better way, not mentioned in the Help Compiler documentation, is to use HELP_PARTIALKEY and pass a null string. When this function executes, the Search Dialog Box is displayed over your program. Then, when the user selects the topic the Help file is brought up at that topic, bypassing the Contents topic altogether. This in fact is the way VB Help works. Displaying secondary windows. Before a secondary window can be displayed, the main window must be available. This is done by using the HELP_FORCEFILE command. (See Figure 6, Sub mnuHelpGlossary_Click.) If you don't want the main window displayed, add the following statement at the end of the routine: r = WinHelp(frmMain.hWnd, App.HelpFile, HELP_COMMAND, "CloseWindow(`main')") Displaying popup topics. The HELP_POPUPID function displays a topic in a popup window. However, there is a bug that causes the focus to be lost, so for now it is best to avoid using it. There are Shareware programs available for providing balloon-type help. (See Sidebar XXX.) Summary. Most programs will only use a few WinHelp functions. Nonetheless, using them at the right time and place can make big difference, with very little programming. For example, two other things you can easily change are the Contents topic ([HELP_SETCONTENTS]) and the Help file. You might consider these changes if the help information is dependent on user controlled options or data. Finally, for those so inclined, you can write your own DLL's to access custom macros. See the enclosed VB program for more detailes. SIDEBAR: ADDITIONAL INFORMATION The Microsoft Help Compiler documentation that comes with VB Professional is very terse, and for the beginner, difficult to understand. Even worse, its incomplete. Below is a short list of places to look for additional information to supplement what Microsoft provides. * If you have VB professional, the HC subdirectory contains all the programs necessary to create a Help file (except a word processor), additional documentation relating to API calls, and a sample project (ICONWRKS). * We highly recommend the book Developing Online Help for Windows, Scott Boggan, etal., Sams Publishing 1993. (800-428-5331, $39) This covers everything from writing styles for Help files to a spreadsheet to project its development cost. It also includes a disk with a number of sample Help files that illustrate various features. The disk also has a simple Help Authoring Tool (macros for WinWord Version 2). * The Help Authoring Guide. This is a Help file created by Microsoft (possibly as a precursor to a more comprehensive help document). It contains far more information than the manual that comes with VB. Its available on CompuServe in the WinSDK forum, Lib 16 as file HAG.ZIP. This a highly technical document, most people would be better served getting Boggan's book. * Check out the sample Help file and VB program included with this article. They illustrate many of the issues and features discussed here, and a lot more. SIDEBAR: HELP AUTHORING TOOLS Even if you are only going to write a small Help file, you should look into getting a Help Authoring Tool of some sort. Coding Help topics is just too tedious to do manually. (Remember, Developing Online Help for Windows mentioned above includes a basic Help Authoring Tool for WinWord 2.) A Help Authoring Tool can be as simple as a few macros that automate Control code insertion, or complete stand- alone programs that include custom text editors and facilities for manipulating the Help Project File. They range in price from nothing to $500. While its generally true that the higher priced offering provide more features, that's not always the case. More important, you may not need or use the additional features. There are two types of Help Authoring Tools. The first type provide their own editor for you to enter topic text. These products tend to be more self-contained and somewhat easier to use, since the vendor can control all aspects of the process. The downside is that the text editors tend to be limited, at least when compared to a full-featured word processor. For example, you may not be able to define all the paragraph formats the exactly as you want, or the editor may not contain a spell-checker, glossary or macro features you've grown accustomed to. The second type of Help Authoring Tool uses a word processor for text editing and provide macros for automating the topic coding process. Many of these types of products also include mechanisms for running the Help Compiler from within the word processor. Most use WinWord. There are, however, products available for AmiPro and WordPerfect and perhaps other word processors. Check with the vendor, user support groups, or online forums for more information. If you already have and use WinWord, then a Help Authoring Tool that uses it would be a reasonable choice. After all, do you really need to learn another word processor? One further note: I have yet to find a Help Authoring Tool which uses its own editor and that supports all the Help Compiler features. The most glaring missing feature is the lack of support for tables. Nor do these products provide any reasonable work-arounds. That is, you cannot insert a table manually. For this reason, I would not recommend these products for any serious project. There a number of good shareware products that may meet your needs. Look for them in the WinSDK forum on CompuServe. The one I like is CreateHelp ($40, CompuServe 100111,3452). If you're in the market for a commerical product, and support is important, try HelpBreeze (Solutionsoft, $279, (408) 736-1431). One thing to remember is that people create help files for different reasons and have different technical backgrounds. Online documetation is the obvious reason for creating a Help file. However increasingly, standard printed documents, such as procedures manuals, are being converted to Help files. Different Help Authoring Tools reflect these various needs and skills.