THE PROGRAMMER'S GUIDE. BASIC 7.1
CHAPTER 22: CUSTOMIZING ONLINE HELP
The Microsoft Help File Creation Utility (Helpmake) allows you to create or modify Help files for use with Microsoft products. For example, you could write Help text describing a new function you have written for a Quick library. This would let you display Help information about your function anytime you're working in the QBx environment.

Helpmake translates Help text files into a Help database accessible from within the following:
O.~ The QBx environment
O.~ Microsoft QuickHelp utility
O.~ Other Microsoft language products

To use Helpmake, you need one or more input files that contain information specially formatted for the Help system. Specify the name of a Help text file formatted in one of several simple styles and the amount by which to compress the file. Helpmake can also decompress a Help database to its original text format.

WHAT'S IN A HELP FILE?
This section defines some of the terms involved in formatting and outlines the types of files Helpmake can use as input. A Help database file can contain the following elements:

O.~ Contexts and topic text
O.~ Implicit cross-references
O.~ Explicit cross-references
O.~ Formatting flags
Each of these elements is discussed in the following sections.

CONTEXTS AND TOPIC TEXT
If you have used the online Help system in QBx you probably have a good idea of what a Help file looks like. As you might expect, each file starts with a subject and some information about the subject, then lists another subject and some information about it, then another, and so on.

In the Helpmake terminology, the subjects are called "contexts" and the information is called "topic text" The application simply hands the context to an. internal Help engine, which searches the database for information.

Whenever someone asks for Help on the Open statement from within the QBx environment, for example, the Microsoft Advisor Online Help System looks for the context "open" and displays its topic text. (The name of every function in the Basic statement and function library is a context throughout the Help database).

Often the same information applies to more than one subject. For example, the Basic functions Cvi, Cvs, Cvl, and Cvd are all contexts for one block of topic text. The converse, however, is not true. You cannot specify different blocks of topic text, in different places in the Help file, to describe a single subject.

CROSS-REFERENCES
To make it easier for users to navigate through a Help database, you can put cross-references in your Help text. Cross-references bring up information on related topics, including header files and code examples.

The Help for the Print statement, for example, refers to the Print Using and Print# statements. Cross-references can point to other contexts in the same Help database, to contexts in other Help databases, or to Ascii files outside the database.

Help files can have two kinds of cross-references:
O.~ Implicit cross-references
O.~ Explicit cross-references, or hyperlinks

IMPLICIT CROSS-REFERENCES
The word "open" is an implicit cross-reference throughout the QBx Help database because it is the name of a Basic function. If a user selects the word "open" anywhere in QBx or Help, the Help system displays information on the Open function.

Cross-references like this are called implicit cross-references because they are implicit in the Help file and require no special coding. Anywhere a context appears, the Help system makes an implicit cross-reference to its topic text.

EXPLICIT CROSS-REFERENCES
Explicit cross-references, also called "hyperlinks", are tied to a word or phrase at a specific location in the Help file. You set up explicit cross-references when you write the Help text. For example, suppose that you want to display Help on the Print statement at a particular position in the QBx Help system if the user selects the word "formatting".

You would create an explicit cross-reference from the word "formatting" to the context Print. Anywhere else in the file, "formatting" would have no special significance, but at that one position, it would display the topic text for Print.

FORMATTING FLAGS
Help text can also include formatting flags to control the appearance of the text on the screen. Using these flags, you can make certain words appear in boldface, others underlined, and so on, depending on the graphics capabilities of the user's computer.

In the Help database Microsoft supplies for QBx, the active cross-references are surrounded by green symbols on a color monitor. Other applications may represent cross-references differently; for example, in bold or in color.

Specific formatting flags for QuickHelp format and Rich Text Format are discussed in "Using-Help Database Formats" later in this chapter.

HELP FILE FORMATS
You can create Help files using any of three formats:
O.~ QuickHelp format
O.~ Rich Text Format (Rtf)
O.~ Minimally formatted Ascii
In addition, you can reference unformatted Ascii files, such as include files, from within a Help database.

QUICKHELP
QuickHelp format is the default and is the format in which Helpmake writes files it decodes from existing Help databases. Use any text editor to create a Help text file in the QuickHelp format. The QuickHelp format also lends itself to a relatively easy automated translation from other document formats.

QuickHelp files can contain all the various cross-references and formatting flags. For more information about QuickHelp formatting flags, see the section "QuickHelp Formatting Flags" later in this chapter. Typically, you would use QuickHelp format for any changes you want to make to the standard Help database. Most of the examples in this chapter are in QuickHelp format.

Note.~ The QuickHelp format supported by QBx is a subset of the format supported by the OS/2 QuickHelp utility. QBx does not support the complete set of OS/2 QuickHelp dot commands.

RICH TEXT FORMAT
Rich Text Format (Rtf) is a Microsoft word-processing format that many other word processors also support. You can create Rtf Help text with any word processor capable of generating Rtf output. You may also use any utility program that takes word-processor output and produces an Rtf file.

Use Rtf when you want to transfer Help files from one application to another while retaining formatting information. You can format Rtf files directly with the word-processing program and need not edit them to insert any special commands or tags.

Like QuickHelp files, Rtf files can contain formatting codes and cross-references. For a list of the Rtf formatting codes recognized by Helpmake, see the section "Rtf" later in this chapter.

MINIMALLY FORMATTED ASCII
Minimally formatted Ascii files define contexts and their topic text. They are intended for Help files less than 256 kbs. that do not require compression, and for access of Readme-type text directly by online Help. These files cannot contain explicit cross-references or formatting flags.

UNFORMATTED ASCII
Unformatted Ascii files must be smaller than 64 kbs. and are exactly what their name implies: regular Ascii files with no special formatting commands or context definitions. An unformatted Ascii file does not become part of the Help database. Instead, only its name is used as the object of a cross-reference. For example, unformatted Ascii files could contain program examples.

INVOKING HELPMAKE
Helpmake encodes or decodes Help files. Encoding is the process of converting a text file into a compressed Help database. Decoding reverses the process: it converts a Help database into a text file. Helpmake can decode any Microsoft Help database file (unless it was encoded with the /L option) to a QuickHelp formatted text file for editing.

It can also encode an Rtf, QuickHelp, or minimally-formatted Ascii text file into Help database format. Helpmake is required to create and modify Microsoft-compatible Help databases. It is not required, however, merely to access databases supplied with Microsoft language products.

The Helpmake command-line syntax is as follows:

Helpmake [options%]@AE@% {/E [n] | /D [letter]} sourcefiles

The options are described in the next section. In addition, you can type Helpmake by itself or with the /H option to display a summary of valid Helpmake options. Either the /E (encode) or the /D (decode) option must be supplied.

When encoding (/E) to create a Help database, you must use the /O option to specify the filename of the database. The optional n parameter specifies the amount of compression to take place (described in "Options for Encoding" later in this chapter).

The sourcefiles field is required. It specifies the input files for Helpmake. If you use the /D (decode) option, sourcefiles may be one or more Help database files. Helpmake decodes the database files into a single text file.

If you use the /E (encode) option, sourcefiles may be one or more Help text files. Separate filenames with a space. Standard wildcard characters may also be used.

Example.~ The following Helpmake command line encodes a source file by invoking Helpmake with the /V, /E, and /O options:

Helpmake /V /E /Omy.hlp My.txt > My.log

Helpmake reads input from the text file My.txt and writes the compressed Help database in the file My.hlp. The /E option causes maximum compression. Note that the Dos redirection symbol (>) sends a log of Helpmake activity to the file My.log.

You may find it helpful to redirect the log file because, in its more verbose modes (given by /V), Helpmake may generate a lengthy log. For additional encoding options, see "Options for Encoding" later in this chapter.

The following command line decodes the Help database My.hlp into the text file my.src by invoking Helpmake with the /O option:

Helpmake /V /D /Omy.src My.hlp > My.log

Once again, the /V option results in verbose output, and the output is directed to the log file my.log. For additional decoding options see "Options for Decoding" later in this chapter.

HELPMAKE OPTIONS
Helpmake accepts a number of command-line options, which are listed in the sections that follow. You may specify options in uppercase or lowercase letters, and precede them with either a forward slash (/) or a dash (-). For example, -L, /L, -l, and /l all represent the same option.

Most options apply only to encoding; others apply only to decoding; and a few apply to both. See "Options for Encoding" for the options that apply to encoding and "Options for Decoding" for the options that apply to decoding.

OPTIONS FOR ENCODING
To encode a database, specify the /E option to Helpmake. In addition, you may supply various other options that control the way Helpmake encodes the database. All the options that apply when encoding are listed in the following table:

/Ac
Specifies C as an application-specific control character for the Help database file. The character marks a line that contains special information for internal use by the application. For example, the QBx database uses the colon (:).

/C
Indicates that the context strings for this Help file are case sensitive. At run time, all searches for Help topics are case sensitive if the Help database was built with the /C option in effect.

/E[n]
Creates (encodes) a Help database from a specified text file. The optional N indicates the amount of compression to take place. If n is omitted, Helpmake compresses the file as much as possible, thereby reducing the size of the file by about 50 percent.

The more compression requested, the longer Helpmake takes to create a database file. The value of n is a number in the range 0 - 15. It is the sum of successive powers of 2 representing various compression techniques, as follows

0 No compression
1 Run-length compression
2 Keyword compression
4 Extended keyword compression
8 Huffman compression

Add values to combine compression techniques. For example, use /E3 to get run-length and keyword compression. This is useful in the testing stages of Help database creation where you need to create the database quickly and are not too concerned with size.

/H
Displays a summary of Helpmake syntax and exits without encoding any files.

/L
Locks the generated file so that it cannot be decoded by Helpmake at a later time.

/Odestfile:
Specifies Destfile as the name of the Help database.

/Sn:
Specifies the type of input file, according to the following /S n values:
/S1 Rich Text Format (Rtf)
/S2 QuickHelp (default)
/S3 Minimally formatted Ascii

/T
Translates a number of dot commands. Each translated command corresponds to a statement using the application control character, which by default is a colon (:). For example, .length 20 is equivalent to :l20. Using /T directs Helpmake to perform the following translations:

.category :c
.next :>
.command :x
.mark :m
.dup :d
.paste :p
.end :e
.popup :g
.execute :y
.previous :<
.file :f
.ref :r
.freeze :z
.suffix :s
.list :i
.topic :n
.length :l

/Vn:
Indicates the amount of diagnostic and informational output, depending on the value of n. Increasing the value adds more information to the output. If you omit this option or specify only /V, Helpmake gives you its most verbose output. The possible values of /V n follow:

/V Maximum diagnostic output.
/V0 No diagnostic output and no banner.
/V1 Prints only Helpmake banner (default).
/V2 Prints pass names.
/V3 Prints contexts on first pass.
/V4 Prints contexts on each pass.
/V5 Prints any intermediate steps within each pass.
/V6 Prints statistics on Help file and compression.

/Wwidth:
Indicates the fixed width of the resulting Help text in number of characters. The values of width can range from 11 to 255. If the /W option is omitted, the default is 76. When encoding Rtf source files (/S1), Helpmake automatically formats the text to width. When encoding QuickHelp (/S2) or minimally formatted Ascii (/S3) files, Helpmake truncates lines to this width.

OPTIONS FOR DECODING
To decode a Help database into QuickHelp files, use the /D option. In addition, Helpmake accepts other options to control the decoding process. The following table shows all the options that are valid when decoding:

/D% @AI@%letter:
Decodes the input file into its component parts. If a destination file is not specified with the /O option, the Help file is decoded to stdout. Helpmake decodes the file differently depending on the letter specified, as follows:

/D
Fully decodes the Help database, leaving all cross-references and formatting information intact.

/Ds
Decode split. Splits the concatenated, compressed Help database into its components using their original names. If the database was created without concatenation (the default), Helpmake simply copies it to a file with its original name. No decompression occurs.

/Du
Decode unformatted. Decompresses the database and removes all screen formatting and cross-references. The output can still be used later for input and recompression, but all screen formatting and cross-references are lost.

/H
Displays a summary of Helpmake syntax and exits without decoding any files.

/Odestfile:
Specifies destination file for the decoded output from Helpmake. If destfile is omitted, the Help database is decoded to stdout. Helpmake always decodes Help database files into QuickHelp format.

/Vn:
Indicates the amount of diagnostic and informational output displayed depending on the value of n. The possible values of n follow:
/V Maximum diagnostic output.
/V0 No diagnostic output and no banner.
/V1 Prints only the Helpmake banner (default).
/V2 Prints pass names.
/V3 Prints contexts on first pass.

CREATING A HELP DATABASE
You can create a Microsoft-compatible Help database using two methods. The first method is to decompress an existing Help database, modify the resulting Help text file, and recompress the Help text file to form a new database. The second and simpler method is to append a new Help database onto an existing Help database. This method involves the following steps:

O.~ 1. Create a Help text file in QuickHelp format, Rtf, or minimally formatted Ascii.
O.~ 2. Use Helpmake to create a Help database file. The following Helpmake command line invokes Helpmake, using Sample.txt as the input file and producing a Help database file named Sample.hlp: Helpmake /V /E /OSample.hlp Sample.txt > Sample.log

O.~ 3. Make a backup copy of the existing database file (for safety's sake).
O.~ 4. Append the new Help database file onto the existing Help database. The following command line concatenates the new database Sample.hlp onto the end of the Bas7qck.hlp database using the append feature of the Dos Copy command.

Copy Bas7qck.hlp /B + Sample.hlp /B

You can append additional Help files to Bas7qck.hlp by adding them to the command line, separating each file with a plus sign (+).

5. Test the database. Suppose that the Sample.hlp database contains the context Sample. If you type the word "Sample" in the QBx environment and request Help on it after appending Sample.hlp to Bas7qck.hlp, the Help window should display the text associated with the context Sample.

HELP TEXT CONVENTIONS
Using common structure and conventions ensures that Help files for one application will make sense when viewed using another. This section outlines organizational conventions used in Help databases supplied by Microsoft. You should follow the same conventions to create Microsoft-compatible Help files.

CONTEXT CONVENTIONS
Certain contexts are defined by convention across the Help databases for all Microsoft languages. If you decompress any of the Help database files that Microsoft supplies, you will see these contexts in the text output.

RECOMMENDED CONTEXTS
The following contexts are recommended, and are present in most Microsoft Help files. If you use these contexts, make sure that they conform to these conventions.

H.contents.~ The table of contents for the Help file. You can also define the string "contents" for direct reference to this context.

H.index.~ The index for the Help file. You can also define the string "index" for direct reference to this context.

H.pg#.~ A specific page within the Help file. This is used in response to a "go to page #" request.

Note that each of the preceding contexts begins with the "h." prefix. The Microsoft Advisor Online Help system considers context strings beginning with x., where x is a specified character prefix, as internal or constructed Help contexts.

Except for the preceding contexts listed, these apply to menu items, error numbers, and so forth; in general, you do not need to insert these in your Help files.

REQUIRED CONTEXTS
The following contexts are required and are present in all Microsoft Advisor Help files. If you modify or replace the standard files, be sure to retain these definitions.

H.default.~ The default Help screen, typically displayed when the user presses Shift+F1 at the top level in most applications. The contents are generally devoted to information on using Help.

H.notfound.~ The Help text that is displayed when the Help system cannot find information on the requested context. The text could be an index of contexts, a topical list, or general information on using Help.

H.pg1.~ The Help text that is logically first in the file. This is used by some applications in response to a "go to the beginning" request made within the Help window.

H.pg$.~ The Help text that is logically last in the file. This is used by some applications in response to a "go to the end" request made within the Help window.

INTERNAL HELP CONTEXT PREFIXES
The following character prefixes denote internal Help contexts:

H..~ Help item. Prefixes miscellaneous Help contexts that may be constructed or otherwise hidden from the user. For example, the internal Help context, h.index, refers to the Basic Language Keyword Index which is part of the QBx online Help.

M..~ Menu item. Contexts that relate to product menu items are defined by their accelerator keys. For example, the Exit selection on the file menu item is accessed by Alt+F+X, and is referred to in Help by m.f.x.

E..~ Error number. If a product supports the uniform error numbering scheme used by Microsoft languages, it refers to the Help for each error using the error number with the e prefix. For example, the context e.c1234 refers to the C compiler error message number C1234.

D..~ Dialogs. Dialogs are assigned a number, and the Help context string is constructed by d. followed by the Ascii text number (for example, d.12).

M..~ Messages.

THE HELP TEXT FILE
The Help retrieval facility that is built into Microsoft products is simply a data retrieval tool. It imposes no restrictions on the content and format of the Help text. Helpmake and the display routines built into Microsoft language environments.

However, make certain assumptions about the format of Help text. This section provides some guidelines for creating Help text files that are compatible with those assumptions.

In all three Help text formats, the Help text source file is a sequence of topics, each preceded by one or more unique context definitions. The following table lists the various formats and the corresponding context-definition statement:

QuickHelp: .context context
Rtf: \par >> context \par
Minimally formatted Ascii: >> context

In QuickHelp format, each topic begins with one or more .context statements that define the context strings that map to the topic text. Subsequent lines up to the next .context statement constitute the topic text.

In Rtf, each context definition must be in a paragraph of its own (denoted by \par), beginning with the Help delimiter (>>). Subsequent paragraphs up to the next context definition constitute the topic text.

In minimally formatted Ascii, each context definition must be on a separate line, and each must begin with the Help delimiter (>>). As in Rtf and QuickHelp files, subsequent lines up to the next context definition constitute the topic text.

For detailed information about these three formats see "Using Help Database Formats" later in this chapter.

EXPLICIT CROSS-REFERENCES
Explicit cross-references, or "hyperlinks", in the Help text file are marked with invisible text. A hyperlink comprises a word or phrase followed by invisible text that gives the context to which the hyperlink refers.

When the user activates the hyperlink, the Help system displays the topic named by the invisible text. The keystroke that activates the hyperlink depends on the application. Consult the documentation for each product to find the specific keystroke needed.

To specify hyperlinks in your Help database, you must use either QuickHelp format or Rtf. See "Using Help Database Formats" later in this chapter for the specific QuickHelp and Rtf options that turns invisible text on and off.

The invisible cross-reference text is formatted as one of the following:

Context_string:
Causes the Help topic associated with context_string to be displayed. For example, exe_format results in the display of the Help topic associated with the context exe_format.

Filename!
Causes the entire file filename to be treated as a single topic to be displayed. For example, $Include: Myincl.inc would search the $Include environment variable for the file Myincl.inc.

Filename!context_string
Works the same way as context_string, except that filename is searched for the context. If the file is not already open, the Help system finds it (by searching either the current path or an explicit environment variable), and opens it. For example, Basadvr.hlp!Fsinr would search the Basadvr.hlp file and bring up the topic associated with Fsinr.

LOCAL CONTEXTS
Context strings that begin with an at sign (@) are defined as local and have no implicit cross-references. They are used in cross-references instead of the context string that would otherwise be generated.

When you use a local context, Helpmake does not generate a context string that can be used from elsewhere in the Help file. Instead, it embeds a cross-reference that has meaning only within the current Help file. An example of this usage follows:

.context normal
This is a normal topic, accessible by the context string "normal". [button\v@local\v] is a cross-reference to the following topic.

.context @local
The topic @local can be reached only if the user uses the cross-reference in the previous topic or if the user browses sequentially through the file.

In the example, the text [button\v@local\v] refers to @local as a local context. If the user selects the text [button], or scrolls through the file, the Help system displays the topic text that follows the context definition for local.

Because local is defined with the at sign, it can be accessed only by a hyperlink within the Help file or by sequentially browsing through the file. This saves space in the file and makes it faster to search for and locate the context.

APPLICATION-SPECIFIC CONTROL CHARACTERS
The Help database supports application-specific characters that have special meaning for Microsoft language products. The application-specific character may appear at the beginning of any line of Help text. This special character is interpreted by the application. If the application does not support this character, it is ignored.

Within the databases and applications provided with Microsoft languages, a colon is used as the control character, and the following colon commands are supported:

:ln
Indicates the default initial window size, in n lines, of the topic about to be displayed. Always the first line in the topic if present.

:n text
Defines text as the name (or title) to be displayed in place of the context string if the application Help displays a title. Always the first line in the context unless :l is used, in which case :n appears on the line following the :l command.

:p
Indicates a screen break for environment Help. The lines following :p are accessible only by using the PgDn command within the environment-Help dialog box.

Example.~ The following example shows the first two lines from the Basic Help entry for the ABS function:

.context Abs
:nAbs Function Syntax
.
.(Topic text for Abs)
.

The :nAbs command directs the application to display the line Help: Abs Function Syntax whenever the context Abs is selected.

USING HELP DATABASE FORMATS
The text format of the database may be any of three types. The following table briefly describes these types. The sections that follow describe each formatting type in detail.

QuickHelp:
Uses dot commands and embedded formatting characters (the default formatting type expected by Helpmake); supports highlighting, color, and cross-references. This format must be compressed before using.

Minimally formatted Ascii:
Uses a Help delimiter (>>) to define Help contexts; does not support highlighting, color, or cross-references. This format may be compressed, but compression is not required.

Rtf:
Uses a subset of standard Rtf; supports highlighting, color, and cross-references. This format must be compressed before using. An entire Help system (such as the one supplied with Microsoft Basic) may use any combination of files formatted with different format types. You could, for example, encode a Readme.doc information file as minimally formatted Ascii; in the save Help system, you could encode the Help files and user-defined statements and functions in QuickHelp format.

QUICKHELP FORMAT
The QuickHelp format uses two dot commands and embedded formatting flags to convey information to Helpmake.

THE QUICKHELP CONTEXT COMMAND
To specify a context string, use the .context command. The form of the command is as follows:

.context
ContextOne or more .context commands precedes each topic in a QuickHelp file. Each .context command defines a context string for the topic text. You may define more than one context for a single topic as long as you do not place any topic text between them.

Multiple context commands refer to the first Help-text block, while one context command refers to the second Help-text block. For example, the following shows how the Cvi, Cvs, Cvl, and Cvd context strings could all refer to the same topic text, while Data refers to a separate topic:

.context Cvi
.context Cvs
.context Cvl
.context Cvd
.
. (Topic text describing string-to-number functions)
.
.context Data
.
. (Topic text describing the Data statement)
.

THE QUICKHELP COMMENT COMMAND
To embed comments in your Help file, use the .comment command. The syntax of this command is as follows:

.comment
TextNote that this command is useful while you are working in the source file; however, Helpmake removes .comment commands and comment text as it encodes the database.

QUICKHELP FORMATTING FLAGS
The QuickHelp format supports a number of formatting flags that are used to highlight parts of the Help database and to mark hyperlinks in the Help text. Each formatting flag consists of a backslash (\) followed by a character. The following table lists the formatting flags:

\\ Inserts a single backslash in text.
\a, \A Anchors text for cross-references.
\b, \B Turns boldface on or off.
\i, \I Turns italics on or off.
\p, \P Turns off all attributes.
\u, \U Turns underlining on or off.
\v, \V Turns invisibility on or off
(hides cross-references in text).

On monochrome monitors, text labelled with the bold, italic, and underlining attributes appears in various ways, depending upon the application (for example, high intensity and reverse video are commonly displayed).

On color monitors, these attributes are translated by the application into suitable colors, depending on the user's default color selections. Depending on the monitor, \b and \i may produce the same effect. It is a good idea to display a small help file on a target machine as a test before writing a large help file.

The \b, \i, \u, and \v options are toggles, turning on and off their respective attributes. You may use several of these on the same text. Use the \p attribute to turn off all attributes. Use the \v attribute to hide cross-references and hyperlinks in the text.

Helpmake truncates the lines in QuickHelp files to the width specified with the /W option. The formatting flags do not count toward the character-width limit. Lines that begin with an application-specific control character are truncated to 255 characters regardless of the width specification. See "Options for Encoding" for more information about the preceding options.

Examples

In the following example, the \b flag initiates boldface text for the word Cls and the \p flag that follows the word reverts to plain text for the remainder of the line:

\bCls\p
A device I/O statement that clears the display screen.
In the following example, the \a anchors text for the hyperlink:

\aExample\vsample_prog\v
The \v flags define the cross-reference to be sample_prog and causes the text between the flags to be invisible. Cross-references are defined in the following section.

QUICKHELP CROSS-REFERENCES
Help databases contain two types of cross-references: implicit and explicit.

An implicit cross-reference is any word that appears both in the topic text and as a context in the Help file. For example, any time you request Help on the word "close", the Help window will display Help on the Close statement. You need not code implicit cross-references in your Help text files.

Explicit cross-references are words or phrases on the screen that are associated with a context. For example, the word "Example" in the initial Help-screen area for a Basic function is an explicit cross-reference to the program example for that function.

You must insert formatting flags in your Help text files to mark explicit cross-references. If the hyperlink consists of a single word, you can use invisible text to flag it in the source file. The \v formatting flag creates invisible text, as follows:

hyperlink\vcontext\v

Specify the first \v flag immediately following the word you want to use as the hyperlink. Following the flag, insert the context that the hyperlink cross-references. The second \v flag marks the end of the context, that is, the end of the invisible text.

Helpmake generates a cross-reference whose context is the invisible text, and whose hyperlink is the entire word. If the hyperlink consists of a phrase, rather than a single word, you must use anchored text to create explicit cross-references. Use the \a and \v flags to create anchored text as follows:

\ahyperlink-words\vcontext\v

The \a flag marks the anchor for the cross-reference. The text that follows the \a flag is the hyperlink. The hyperlink must fit entirely on one line. The first \v flag marks both the end of the hyperlink and the beginning of the invisible text that contains the cross-reference context. The second \v flag marks the end of the invisible text.

Examples

In the following example, the topic text for the Sin function in the QBx Help database contains three implicit cross-references to the Basic functions Cos, Tan, and Atn:

\bSee Also\p Cos\vCos\v Tan\vTan\v Atn\vAtn\v

In the following example, the word Example is a hyperlink:

\bSee also:\p \uExample\p\vopen.ex\v
The hyperlink example refers to open.ex. A mouse click or other form of selection with the cursor on any of the letters of Example brings up the Help topic whose context is open.ex.

\bExample\vBasadvr.hlp!.sqrx\v
On a color monitor, Example appears in boldface and the characters appear highlighted. Any time Example is selected, Helpmake searches for the context .sqrx in the file Basadvr.hlp.

When a hyperlink needs to cross-reference more than one word, you must use an anchor, as shown in the following example:

\aProduct Support\v@prodsupp\v
Anchored hyperlinks must fit on a single line. In this case, the hyperlink consists of the phrase Product Support, which refers to the local context @prodsupp. The \v flag makes the name @prodsupp invisible; it does not appear on the screen when Help is displayed.

MINIMALLY FORMATTED ASCII
You can use uncompressed, minimally formatted Ascii Help files instead of compressed QuickHelp format files, although they are larger and slower to search. Minimally formatted Ascii files are of fixed width, may not contain highlighting (or other nondefault attributes) or cross-references, and cannot be larger than 256 kbs.

A minimally formatted Ascii text file comprises a sequence of topics, each preceded by one or more unique context definitions. Each context definition must be on a separate line beginning with a Help delimiter (>>). Subsequent lines up to the next context definition constitute the topic text.

Example.~ The following code shows how Help for a user-defined context would be implemented using minimally formatted Ascii format:

>>Sample
Sample Statement Syntax

Sample.~ A sample statement that performs a user-defined function.

Syntax: Sample

The Help file begins with the Help delimiter (>>), so that Helpmake can verify that the file is indeed an Ascii Help file. When displayed, the Help information appears exactly as it is typed into the file. Any formatting codes are treated as Ascii text.

>>Troff
>>Tron
.
. (Topic text describing trace statements)
.
>>Type
.
. (Topic text describing the Type statement)
.

To create smaller and faster-to-search minimally formatted Ascii files, compress the files using Helpmake.

RTF
Rich Text Format (Rtf) is a Microsoft word-processing format supported by many other word processors. It allows documents to be transferred from one application to another without losing any formatting information. Helpmake recognizes a subset of the full Rtf syntax.

If your file contains any Rtf code that is not part of the subset, Helpmake ignores the code and strips it out of the file. Certain word-processing and file-conversion programs generate the Rtf code automatically as output.

You need not worry about inserting Rtf codes yourself; you can simply format your Help files directly with a word-processor that generates Rtf, using the attributes supported by the subset. The only items you need to insert are the Help delimiter (>>) and context string that start each entry.

Helpmake recognizes the subset of Rtf listed in the following table:

\plain
Default attributes. On most screens this is nonblinking normal intensity.

\b
Boldface. The way this is displayed depends upon the application; often it is intensified text.

\i
Italic. The way this is displayed depends upon the application; often it is reverse video.

\v
Hidden text. Hidden text is used for cross-reference information and for some application-specific communications; it is not displayed.

\ul
Underline. The way this is displayed depends upon the application. For example, if underlining is not supported (either by one application or by the video adapter), it may be displayed as blue text.

\par End of paragraph.
\pard Default paragraph formatting.
\fi Paragraph first-line indent.
\li Paragraph indent from left margin.
\line New line (not new paragraph).
\tab Tab character.

Using the word-processing program, you can break the topic text into paragraphs. When Helpmake compresses the file, it formats the text to the width given with the /W option, ignoring the paragraph formats.

As with the other text formats, each entry in the database source consists of one or more context strings, followed by topic text. The Help delimiter (>>) at the beginning of any paragraph denotes the beginning of a new Help entry. The text that follows on the same line is defined as a context for the topic.

If the next paragraph also begins with the Help delimiter, it also defines a context string for the same topic text. You may define any number of contexts for a block of topic text. The topic text comprises all subsequent paragraphs up to the next paragraph that begins with the Help delimiter.

Note.~ Rtf uses curly braces for nesting. For a Help database, the contents of the entire file is enclosed in curly braces, as is each specially formatted text item.

Examples.~ The following code is a portion of the context and topic text for the Beep statement written in Rtf format:

\par
>>Beep \par
{\iSyntax}{\bDetails}\vBasadvr.hlp!.beepr\v
{\bBeep} - a device I/O statement that sounds the speaker
{\bSyntax}
Beep

The \i option displays the word Syntax in reverse video and the \b option displays Details, Beep, and Syntax in bold. The following code shows two context statements that refer to the same topic text.

(Note that the actual Rtf output of a word processor normally contains significantly more information that is not visible to the user; this additional information is ignored by Helpmake).

{rtf0
\par
>>Troff \par
>>Tron \par
.
. topic text describing the Troff and Tron statements
.
>>Type \par
.
. topic text describing the Type statement
.
}