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.


