Dot commands identify topics and convey other topic-related information to the Help reader.
The most important dot command is the .context command, described in “Defining a Topic”. Every topic begins with one or more .context commands. Each .context command defines a context string for the topic. You can define more than one context for a single topic, as long as you do not place any topic text between the context definitions.
Most dot commands have an equivalent colon command, which consists of a colon (:) followed by a character. If you decode a database without using /T, commands in the database are shown as colon commands. You can use both colon commands and dot commands in the same source file. If you use any dot commands other than .context or .comment, you must supply the /T option when encoding.
Table 20.2 lists the dot commands. Some commands are not supported by all Help readers.
Table 20.2 Dot Commands
| Dot Command |
Colon Command | Action |
| .category string | :c | 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 list of topics. Supported only by QuickHelp. | |
| .command | :x | Indicates that the topic cannot be displayed. Use this command to hide command topics and other internal information. | |
| .comment string .. string | none | The string is a comment that appears only in the source file. Comments are not inserted in the database and are not restored during decoding. | |
| .context string | none | The string defines a context. | |
| .end | :e | Ends a paste section. See the .paste command. Supported only by QuickHelp. | |
| .execute | :y | Executes the specified command. For example, .execute Pmark context represents a jump to the specified context at the specified mark. See the .mark command. | |
| .freeze numlines | :z | Locks the first numlines lines at the top of the screen. These lines do not move when the text is scrolled. | |
| .length topiclength | :l | Sets the default window size for the topic in topiclength lines. | |
| .line number | none | 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. See .source. The .line command is not inserted in the Help database and is not restored during decoding. | |
| .list | :i | Indicates that the current topic contains a list of topics. Help displays a highlighted line; you can choose a topic by moving the highlighted line over the desired topic and pressing ENTER. If the line contains a coded link, Help looks up that link. If it does not contain a link, Help looks within the line for a string terminated by two spaces or a newline character and looks up that string. Otherwise, Help looks up the first word. | |
| .mark name [[column]] | :m, 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 reader 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 | :p | Begins a paste section. The pastename appears in the QuickHelp Paste menu. Supported only by QuickHelp. | |
| .popup | :g | Tells the Help reader to display the current topic as a pop-up window instead of as a normal, scrollable topic. Supported only by QuickHelp. | |
| .previous context | :< | Tells the Help reader 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 | :u | Turns off special processing of certain characters by the Help reader. | |
| .ref topic[[,topic]] ... | :r | Tells the Help reader to display the topic in the Reference menu. You can list multiple topics; separate each additional topic with a comma. A .ref command is not affected by the /W option. 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 word on the line. Supported only by QuickHelp. | |
| .source filename | (none) | Tells HELPMAKE that subsequent topics come from filename. HELPMAKE error messages contain the name and line number of the input file. The .source command tells HELPMAKE to use filename in the 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. See .line. The .source command is not inserted in the Help database and is not restored during decoding. | |
| .topic text | :n | Defines text as the name or title to be displayed in place of the context string if the application Help displays a title. This is always the first line in the context unless you also use the .length or .freeze commands. | |
The following example is in QuickHelp format:
.context Sample
.context @Sample
.topic Sample Help Topic
.length 20
.freeze 3
\i\p\aBack\v!B\v\i\p
----------------------------------------------------
Help can contain text with three attributes:
\bAttribute\p \bQuickHelp Code\p
\iItalic\p \\i
\bBold\p \\b
\uUnderline\p \\u
The visual appearance of each attribute
or combination of attributes is determined
by the application that displays the help.
\bSee:\p
Coding, Expressions, Grammar, Keywords, Syntax
\i\p\aFlow Control\v@flow\v\i\p
\i\p\aRelease Notes\v$DOC:README.DOC!\v\i\p
.context @flow
.topic Sample Help: Flow Control
.length 8
.freeze 3
\i\p\aBack\v!B\v\i\p
----------------------------------------------------
Here's another sample help screen.
This is an explicit link: \i\p\aSample\v@Sample\v\i\p
This is an implicit link: Sample