Creating Links to Other Topics

A topic can contain a link to another topic. Links let you navigate a Help database. When a topic is displayed, you can ask for Help on links contained in the topic. These links can be associated with other contexts in the same Help database, contexts in other Help databases, or even ASCII files on disk. You can view the cross-referenced material immediately by activating the link without having to search the Help system's indexes and tables of contents for the topic.

The keystroke that activates a link depends on the application. Consult the documentation for each product for the various ways to get Help on a link. In Microsoft language products, use ENTER, SPACEBAR, or F1. If the file that contains the link's destination is not already open, the Help reader finds it and opens it.

The topic text can present the link in various ways, depending on how you want to design your Help system. The link can appear as a “See:” cross-reference, for example, or as a button that contains a title surrounded by special characters. It can even be undistinguished from surrounding text.

A link is either explicit (coded) or implicit (available without coding). It is associated with either a global context (visible throughout the Help system) or a local context (visible only in one database). The following sections discuss these features of links.

Explicit Links

An explicit link is a word or phrase coded with invisible text that provides the context to which the link refers or the action which the Help reader is to take. Use the \v formatting attribute to delimit the invisible text. Format the explicit link in the source file using the following syntax:

string\vtext\v

If string consists of more than one word, you must anchor the string with the \a formatting attribute as follows:

\astring\vtext\v

An anchored link must be specified entirely on one line.

The \v attributes surround the invisible text, which is one of the following commands to the Help reader:

contextstring

Display the topic associated with contextstring when the link is activated. The context string must be available either as a local context in the same Help database or as a global context anywhere in the Help system. For a discussion of global and local contexts, see “Local Contexts”.

helpfile!contextstring

Search helpfile for contextstring and display the topic associated with it. Only the specified Help database or physical Help file is searched for the context. Since helpfile is not in the local database, contextstring must be a global context. Use this specification to confine the search to a single database if a context is contained in more than one database and you want only one of the topics to be found.

filename!

Display filename as a single topic. The specified file must be a text file no larger than 64K.

!command

Execute the command specified after the exclamation point (!). The command is case sensitive. Commands are application-specific. For example, in the Microsoft Advisor and QuickHelp, the command !B represents the previously accessed topic.

In the following example, the word Example is an explicit link:

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

The \v formatting attribute marks the explicit link in the Help text. The \b and \p are formatting attributes that mark See also: as bold text. (Formatting attributes are described on page 721.) The link refers to open.ex. On the screen, this line appears as follows:

See also: Example

If you select any letter in Example and request Help, the Help reader displays the topic whose context is open.ex.

To create an explicit link that contains more than one word, you must use an anchor, as in the following example:

\bSee also:\p \aExample 1\vopen.ex1\v, \aExample 2\vopen.ex2\v

The \a attribute creates an anchor for the explicit link. The phrase following the \a attribute refers to the context specified in the invisible text. The first \v attribute marks both the end of the anchored string and the beginning of the invisible text. The second \v attribute ends the invisible text. The anchored link must fit on one line.

Implicit Links

An implicit link is a single word for which a global context exists somewhere in the Help system. Any word that appears as a global context is implicitly linked. You do not code the word to create the link. When you ask for Help on a word that exists as an implicit link, the Help reader displays the topic that has a .context string that matches the selected word.

For example, suppose that the Help database contains a screen that starts with:

.context open

If you ask for Help on the word “open” (using the features for requesting Help that are available in your Help reader), the topic that begins with .context open is displayed. An explicit link to the topic is not necessary. For example, in PWB you can place the cursor on the word “open” as it appears in your source file or in a displayed Help topic, then click the right mouse button or press F1. Thus, every occurrence of “open” is a potential implicit link.

Local Contexts

A “local context” is a context string that begins with an at sign (@). Local contexts use less file space and speed access. However, a local context has meaning only within the database in which it appears.

HELPMAKE encodes a local context as an internally generated number rather than a context string. This saves space in the database. Unlike a global context (a context string that is specified without the preceding @), a local context is not stored as a string. Thus, topics headed by local contexts can only be accessed using explicit links and cannot be accessed from another database. Local contexts are not restored as strings when a database is decompressed.

The following source file contains two topics, one marked with a global context and one marked with a local context:

.context Global

This is a topic that is marked with a global context.

It is accessed using the context string "Global". It

contains a link to a topic marked with a local context.

See: \aA Local Topic\v@Local\v

.context @Local

This topic can be reached only by the explicit link in

the previous topic (or by sequentially browsing the file).

The text A Local Topic is explicitly linked to @local, which is a local context. If the user asks for Help on the text or scrolls through the Help file, the Help reader displays the topic text that follows the context definition for @local. This topic cannot be accessed any other way (except by sequentially browsing the database).

If you want a topic to be accessible in both local and global contexts, mark the topic text with both global and local .context statements:

.context Global

.context @Local

This is a topic that is marked with a global context and

a local context. It can be accessed using the context

string "Global" (as an explicit or implicit link) or the

context string "@Local" (as an explicit link only). (It

can also be reached by sequentially browsing the file).

Both .context statements must appear together, immediately before the topic text they are to be associated with.

To create a context that begins with a literal @, precede it with a backslash (\).