ImplicitEach help input file consists of one or more help “topics.” A topic is the fundamental unit of help information. It is usually a screenful of information about a particular subject. You identify the subject by one or more “context strings,” which are the words and phrases for which you want to be able to request help. When help is requested on a context string, the topic is displayed.
The .context command defines a context string for the topic that follows it. In the source file for C help, for example, this line introduces help for the #include directive:
.context #include
The .context command and other formatting elements are described in Section 11.5, “Help Text Conventions.”
Whether a context string contains one word or several words depends on the application. For example, because Microsoft QuickBasic considers spaces to be delimiters, a context string in QuickBasic help files is limited to a single word. Other applications, such as PWB, can handle context strings that span several words. In either case, the application hands the context string to an internal “help engine” that searches the database for information.
Often, especially with library routines, the same information applies to more than one subject. For example, the C-language string-to-number functions strtod, strtol, and strtoul share the same help text. The help file lists all three function names as contexts for one block of topic text. The converse, however, is not true. You cannot associate a single context string with several blocks of topic text located at different places in the help file.
Summary: Cross-references help you navigate a help database.
Cross-references make it possible to view information about related topics, including header files and code examples. The help for the C-language open function, for example, references the access function. Cross-references can point to other contexts in the same help database, to contexts in other help databases, or even to ASCII files outside the database.
Help files can have two kinds of cross-references:
Implicit
Explicit, or hyperlinks
Summary: Implicit cross-references are coded with an ordinary .context command.
The word “open” is an implicit cross-reference throughout Microsoft C help, and introduces help for the open function. If you select the word “open” anywhere in C help, the help system displays information on the open function. The context for open begins with an ordinary .context command. As a result, anywhere that you select “open,” the help system references this context.
Summary: Hyperlinks are explicit cross-references marked by invisible text.
A “hyperlink” is an explicit cross-reference tied to a word or phrase at a specific location in the help file. You create hyperlinks when you write the help text. The hyperlink consists of a word or phrase followed by invisible text that gives the context to which the hyperlink refers.
For example, to cause an instance of the word “formatting” to display help on the printf function, you would create an explicit cross-reference from the word “formatting” to the context “printf.” Elsewhere in the file, “formatting” has no special significance, but at that one position, it references the help for printf. For details on how to create hyperlinks, see Section 11.5.4.
Summary: Formatting flags let you change the appearance of text.
Help text can also include formatting attributes to control the appearance of the text on the screen. Using these attributes, you can make certain words appear in various colors, inverse video, and so forth, depending on the application displaying help and the graphics capabilities of your computer.