11.5.4 Hyperlinks

Explicit cross-references, or hyperlinks, are marked with invisible text in the help text file. A hyperlink is a word or phrase followed by invisible text that names the context to which the hyperlink refers.

The keystroke that activates the hyperlink depends on the application. Consult the documentation for each product for the specific keystroke.

When the user activates the hyperlink, the help system displays the topic referenced by the invisible text. The invisible cross-reference text is formatted as one of the following:

Hidden Text Action  
contextstring Displays the topic associated with contextstring. For example, exeformat displays the topic text for the context exeformat.  
filename! Treats filename as a single topic to be displayed. For example, $INCLUDE:stdio.h! searches the directories in the INCLUDE environment variable for file stdio.h and displays it as a single help topic.  
filename!contextstring Works the same as contextstring, except only the help file 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, $BIN:readme.doc!patches searches for readme.doc in the BIN environment variable and displays the topic associated with patches.  
!command Executes the command specified after the exclamation point (!).  

In the following example, the word Example is a hyperlink. The \b,\p, and \v formatting flags mark hyperlinks in the help text. (The formatting flags are listed later in this chapter, in Table 11.4.)

\bSee also:\p Example\vopen.ex\v

The hyperlink refers to open.ex. If you select any of the letters of Example, the help system displays the topic whose context is open.ex. On the screen, this line appears as follows:

See also: Example

An application might display See also: and Example in different colors or character types, depending on factors such as your default color selection and type of monitor.

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

\bSee also:\p \uExample\p\vprintf.ex\v, fprintf, scanf, sprintf, vfprintf, vprintf, vsprintf

\aformatting table\vprintf.table\v

This part of the example is an anchored hyperlink:

\aformatting table\vprintf.table\v

Summary: The anchor must fit on one line.

The \a flag creates an anchor for the cross-reference. In the example, the phrase following the \a flag (formatting table) is the hyperlink. It refers to the context printf.table. The first \v flag marks both the end of the hyperlink and the beginning of the invisible text. The name printf.table is invisible; it does not appear on the screen when the help is displayed. The second \v flag ends the invisible text.