The QuickHelp format uses a dot command and embedded formatting flags to convey information to HELPMAKE.
QuickHelp provides a number of dot commands that identify topics and convey other topic-related information to the help system. If your help file contains dot commands other than .context or .comment, you must supply the /T option when encoding and decoding with HELPMAKE.
Summary: You can define more than one context for a single topic.
The most important dot command is the .context command. Every topic in a QuickHelp file begins with one or more .context commands. Each .context command defines a context string for the topic text. You can define more than one context for a single topic, as long as you do not place any topic text between them.
Typical .context commands are shown below. The first defines a context for the #include C preprocessor directive. The second set illustrates multiple contexts for one block of topic text. In this case, the same topic text explains all of the string-to-number conversion routines in C.
.context #include
.
. description of #include goes here
.
.context strtod
.context strtol
.context strtoul
.
. description of string-to-number functions goes here
.
The QuickHelp format includes several other dot commands. Table 11.3 lists the dot commands available in QuickHelp format.
Table 11.3 QuickHelp Dot Commands
| Command | Action |
| .category string | Lists the category in which the current topic appears and its position in the list of topics. The category name is used by the QuickHelp Categories command, which displays the topics list. Supported only by QuickHelp. |
| .command | Indicates that the topic text is not a displayable help topic. Use this command to hide hyperlink topics and other internal information. |
| .comment string .. string | The string is a comment that appears only in the help source file. Comments are not inserted in the help database, so they cannot be restored when you decompress a help file. |
| .context string | The string introduces a topic. |
| .end | Ends a paste section. See the .paste command below. Supported only by QuickHelp. |
| .freeze numlines | Locks the first numlines lines at the top of the screen. This can be used to preserve a bar of cross-reference buttons for a help topic and prevent it from being scrolled. |
| .length topiclength | Indicates the default window size, in topiclength lines, of the topic about to be displayed. |
| .line number | Tells HELPMAKE to reset the line number to begin at number for subsequent lines of the input file. Line numbers appear in HELPMAKE error messages. HELPMAKE does not put the .line command into the help database, so it is not restored during decompression. See .source. |
| .list | Indicates that the current topic contains a list of topics. QuickHelp displays a highlighted line; you can choose a topic by moving the highlighted line over the desired topic and pressing ENTER. Help searches for the first word of the line. Supported only by QuickHelp. |
| .mark name [[column]] | Defines a mark immediately preceding the following line of text. The marked line shows a script command where the display of a topic begins. The name identifies the mark. The column is an integer value specifying a column location within the marked line. Supported only by QuickHelp. |
| .next context | Tells the help system to look up the next topic using context instead of the topic that physically follows it in the file. You can use this command to skip large blocks of .command or .popup topics. |
| .paste pastename | Begins a paste section. The pastename appears in the QuickHelp Paste menu. Supported only by QuickHelp. |
| .popup | Tells the help system to display the current topic as a popup instead of a normal, scrollable topic. Supported only by QuickHelp. |
| .previous context | Tells the help system to look up the previous topic using context instead of the topic that physically precedes it in the file. You can use this command to skip large blocks of .command or .popup topics. |
| .raw | Turns off special processing of certain characters by the application. |
| .ref topic [[,topic]] ... | Tells the help system to display the topic in the Reference menu. You can list as many topics as needed; separate each additional topic with a comma. A .ref command is formatted without regard to the /W option. Supported only by QuickHelp. |
| If no topic is specified, QuickHelp searches the line immediately following for a See: or See Also: reference; if present, the reference must be the first non-white-space characters on the line. | |
| .source filename | Tells HELPMAKE that subsequent topics come from filename. By default, when an error occurs, the error message contains the name and line number of the input file. The .source command tells HELPMAKE to use filename in the error message instead of the name of the input file and to reset the line number to 1. This is useful when you concatenate several sources to form the input file. HELPMAKE does not put the .source command into the help database, so it is not restored during decompression. See .line. |
| .topic text | Defines text as the name or title to be displayed in place of the context string if the application help displays a title. This command is always the first line in the context unless you also use the .length or .freeze commands. |
The QuickHelp format provides 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. Table 11.4 lists the formatting flags.
Table 11.4 QuickHelp Formatting Flags
| Formatting Flag | Action |
| \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) |
| \\ | Inserts a single backslash in text |
On monochrome monitors, text labeled with the bold, italic, and underline attributes appears in various ways, depending on 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.
The \b, \i, \u, and \v options are toggles, turning on and off their respective attributes. You can 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. Only visible characters 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 Section 11.3.1, “Options for Encoding,” for more information on truncation and application-specific control characters.
In the example below, the \b flag initiates boldface text for Returns:, and the \p flag changes the remaining text to plain text.
\bReturns:\p a handle if successful, or -1 if not.
errno: EACCES, EEXIST, EMFILE, ENOENT
In the example below, the \a flag anchors text for the hyperlink Example. The \v flags define the cross-reference sample_prog and make the text between the \v flags invisible. Cross-references are described in the following section.
\aExample \vsample_prog\v
Help databases contain two types of cross-references, implicit and explicit. They are described in Section 11.1.1, “Contents of a Help File.”
Any word that appears as a global context is implicitly cross-referenced. For example, any time you request help in PWB on close, the help window displays information about that function. You do not code implicit cross-references into your help text files.
Summary: Insert formatting flags to mark explicit cross-references.
Explicit cross-references (hyperlinks) are words or phrases on the screen that point to a context. For example, almost every “See:” and “See also:” reference in online help has a hyperlink pointing to the appropriate context. You can view the cross-referenced material immediately by activating the hyperlink, without having to search the help system's menus for the topic. 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
Put the first \v flag immediately following the word you want to be the hyperlink. Following the flag, insert the context that the hyperlink points to. 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 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 an 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.
The C functions abs, cabs, and fabs in the following examples are implicit cross-references because they have a global context in the help system.
See also: abs, cabs, fabs
The next example shows the encoding for an explicit cross-reference to an example program and a function template from the help database for the Microsoft C run-time library:
See also: Example\vopen.ex\v, Template\vopen.tm\v, close
Here, the hyperlinks are Example and Template, which reference the contexts open.ex and open.tm. The example also contains an implicit cross-reference to the close function.
The final example shows the encoding for an explicit cross-reference to an entire family of functions:
See also: \ais... functions\vis_functions\v, atoi
The cross-reference uses anchored text to associate a phrase, rather than just a word, with a context. In this example, the hyperlink is the anchored phrase is... functions, and it cross-references the context is_functions. In addition, the example contains an implicit cross-reference to the C-language atoi routine.
The code below is an example in QuickHelp format that contains a single entry:
.context open
.length 13
\bInclude:\p <fcntl.h>, <io.h>, <sys\\types.h>, <sys\\stat.h>
\bPrototype:\p int open(char *path, int flag[, int mode]);
oflag: O_APPEND O_BINARY O_CREAT O_EXCL O_RDONLY
O_RDWR O_TEXT O_TRUNC O_WRONLY
(can be joined by |)
pmode: S_IWRITE S_IREAD S_IREAD | S_IWRITE
\bReturns:\p a handle if successful, or -1 if not.
errno: EACCES, EEXIST, EMFILE, ENOENT
\bSee also:\p \uExample\p\vopen.ex\v, \uTemplate\p\vopen.tp\v,
access, chmod, close, creat, dup, dup2, fopen, sopen, umask
The .length command near the beginning of the example specifies the size of the initial window for the help text. Here, the initial window displays 13 lines.
The manifest constants (such as O_WRONLY and EEXIST), the C keywords (such as int and char), and the other functions (such as access and sopen) are implicit cross-references. The words Example and Template are explicit cross-references to the example open.ex and to the open template open.tp, respectively. Note the use of double backslashes in the include file names.