Common Desktop Environment: Help System Author's and Programmer's Guide

Creating Hyperlinks

A hyperlink references a specific topic or location in a help volume. This requires that the element you want to reference is given a unique ID. These HelpTag elements can be assigned IDs: <chapter>, <s1...s9>, <location>, <p>, <image>, <figure>, and <graphic>.

Help supports five types of hyperlinks:

Hypertext links "jump" to another help topic. By default the new topic is displayed in the same window, but you may request that the new topic be displayed in a new window.
Definition links display a topic in a simple pop-up help window. Most frequently, definition links are used to access the definition of a new term or phrase used within a sentence.
Man page links display any man page installed on the system.
Execution links execute a shell command or program. This greatly expands the possibilities for what happens when the user activates a hyperlink.
Application-defined links create custom links that the application interprets. This provides facilities for communication between the Help System and the application.

To create a hyperlink to an element, you include its ID in a hyperlink command. HelpTag provides two elements, <xref> and <link>, that can be used to create hyperlinks to an ID. In addition, the <p>, <image>, and <figure> elements can be used to create hyperlinks using a graphic image.

Using the <xref> Element

If you are linking to an element with a title, such as a chapter or section, the simplest way to do so is with the <xref> element. When you use <xref> to create a link, you specify the ID of the topic that you want to link to. The title of the topic is inserted in place of the <xref> element and becomes the active hyperlink.

Hypertext links created with <xref> display the new topic in the same window. If you desire different behavior by using the other link types, then you must use the <link> element.

Also, you cannot use <xref> to jump to topics that have built-in IDs (such as <hometopic> or <glossary>). To create a hyperlink to any of those elements, you must use the <link> element.

To Create a Link Using <xref>

Use the <xref> element as shown:

 <xref id>

where id is the ID of the chapter or section that you want to create a link to. Notice that capitalization of the ID is not significant.

Here's an example that creates a link to a section title.

<s1 id=colorpalettes>Desktop Color Palettes
.
 .
 .
 To learn how to change the colors used on your desktop,
 refer to <xref colorpalettes>.

The section title replaces the <xref> element. The title is a hyperlink, designated by an underline. This is how the sentence would appear in a help volume.

Using the Link Element

You can use either the <xref> or <link> element to create standard hypertext links. However, to use the other types of links listed on "Creating Hyperlinks", you must use the <link> element.

To Create a Link Using <link>

To jump to a topic within the same volume, use the <link> element as shown:

<link id>text<\link>

Where id is an ID declared somewhere in the help volume, and text is the portion of your help text that is underlined to indicate it is an active hyperlink.

Example

Here is the previous example using the <link> element instead of the <xref> element.

<s1 id=colorpalettes>Desktop Color Palettes
 .
 .
 .
 To learn how to change the colors used on your desktop,
 refer to <link colorpalettes>Desktop Color Palettes<\link>.

To Create a Link to a Predefined ID

To jump to a topic (within the same volume) that has a predefined ID, use the <link> element as shown:

<link hyperlink="id">text<\link>

All the predefined IDs start with a _ (underscore) character. So this makes it necessary to use the hyperlink= "id" form.

Example

This link jumps to the home topic of the current volume:

Return to <link hyperlink="_hometopic">Introduction<\link>.

To Create a Link to a Topic in a Different Volume

To jump to a topic in another help volume:

<link hyperlink="volume id" JumpNewView>text<\link>

If the other volume is registered, the volume parameter is just the base name of the volume file. If the volume is not registered, you must include a complete path name to the volume.

The JumpNewView parameter is recommended for links to other volumes so that users realize they have jumped into another volume. The previous view remains displayed so they can see where they came from.

Examples

This link jumps to the home topic of a help volume called GeoMap:

To view a map of the United States, see <link hyperlink="GeoMap 
_hometopic"> Geography Maps <\link>.

Here's the same link, but it displays the topic in a new window:

To view a map of the United States, see <link hyperlink="GeoMap 
_hometopic" type=JumpNewView> Geography Maps <\link>.

This link jumps to the topic, DesktopKeyboardNav, in the help volume named Intromgr.

For more information, see <link hyperlink="Intromgr 
DesktopKeyboardNav">Keyboard Shortcuts for the Desktop<\link>.

If the help volume you are targeting is not registered on the desktop, then you must provide a complete path name to the volume or specify the appropriate search path in your helptag.opt file.

To Create a Definition Link

If you are linking to a term in the glossary, use the <term> element as shown:

<term>text<\term>

Or, use the shorthand form:

++text++

Whenever you use the <term> element, be sure you include the corresponding definition in the Glossary.

If you are linking to a topic within the same help volume, use the <link> element as shown:

<link id Definition>text<\link>

Where id is a topic ID (or the ID of an element within the topic) and text is the portion of your help text that you want to be the active hyperlink. The Definition keyword specifies that the link should pop-up a quick help dialog box.

Or, if you are linking to a topic in another help volume, use the <link> element as shown:

<link hyperlink="volume id" Definition>text<\link>

If the other volume is registered, the volume parameter is just the base name of the volume file. If the volume is not registered, you must include a complete path name to the volume.

Example

The following link creates a definition link that displays the copyright topic in the meta information:

<link hyperlink="_copyright" type=Definition>Version Information<\link>

The phrase "Version Information" becomes the hyperlink text (dashed underline).

To Create a Man Page Link

Use the <link> element as shown:

<link manpage Man>text<\link>

To request a man page from a particular section, use the hyperlink parameter like this:

<link hyperlink="section manpage" Man>text<\link>

For man page links, the hyperlink parameter is the same string you would enter if executing the man command in a terminal emulator window.

Note -

If you are writing help for an application and you include any man page links, your application must include special support for man pages. See "To Display a Man Page". (The desktop Help Viewer includes support for man page links.)

Example

Here's a link that displays the man page for the grep command:

Refer to the <link grep Man> grep(1)<\link> command.

"Man" is a keyword for the <link> element, so if you want to create a link that displays the man page for the man command, you must use the hyperlink parameter:

Refer to the <link hyperlink="man" Man>man(1)<\link> command.

To display a man page in a particular section, precede the man page name with the section number. The following link displays the "mkdir" man page from section 2 (which is different from the man page of the same name in section 1):

Refer to the <link hyperlink= "2 mkdir" Man>mkdir(2)<\link> command.

To Create an Application-Defined Link

Use the <link> element with the AppDefined parameter as shown:

<link hyperlink="data" AppDefined>text<\link>

Where data is a text string passed to the application when the link is invoked and text is the hyperlink.

Example

Suppose you are writing help for an application that prints three styles of reports. You might create three hyperlinks like this:

Choose a report type:
<list plain tight>
* <link hyperlink="Report-Daily" AppDefined>Daily Report<\link>
* <link hyperlink="Report-Month-To-Date" AppDefined>MTD Report<\link>
* <link hyperlink="Report-Year-To-Date" AppDefined>YTD Report<\link>
<\list>

If your application is set up to handle these special links and to interpret the hyperlink strings, it could generate the appropriate report based on the hyperlink chosen by the user.

For a complete example, refer to the sample application code located in the /usr/dt/share/examples/dthelp directory.

To Link to a Meta Information Topic

Use the <link> element as shown:

<link hyperlink="_id">text<\link>

Where id is the predefined ID associated with the element you want to link to and text is the word or phrase that you want to be the active hyperlink.

Most topics within the meta information section have predefined IDs, so they do not allow author-defined IDs. The predefined IDs consist of the element name preceded by an underscore character. For example, the ID for the <copyright> topic is _copyright. (Case is not significant.)

The predefined IDs for the meta information topics are listed below:

<abstract>: (_abstract)
<copyright>: (_copyright)
<title>: (_title)

Topics entered with the <otherfront> element can be linked to just like any normal topic in the topic hierarchy.

Creating Hyperlinks

Using the <xref> Element

To Create a Link Using <xref>

Using the Link Element

To Create a Link Using <link>

Example

To Create a Link to a Predefined ID

Example

To Create a Link to a Topic in a Different Volume

Examples

See Also

To Create a Definition Link

Example

See Also

To Create a Man Page Link

Example

See Also

To Create an Application-Defined Link

Example

To Link to a Meta Information Topic

See Also