Collection of Hack-Phreak Scene Programs/cleanhpvac.zip/cleanhpvac/HELPINFO.ZIP/ARTICLE.TXT

Text File | 1994-01-10 | 44KB | 1,025 lines

CREATING WINDOWS HELP FILES ---------------------------------

     Copyright December 1993 by Theodore Kahn. All rights reserved.
     [e-mail]
     CIS 70353,2603
     [phone]

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, [phone]).

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.