HP OpenVMS Systems Documentation

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

3 Writing a Help Topic

Contents of Chapter:

Creating Help Topics

Creating Structure within a Topic

To Start a Paragraph
To Enter a List
To Enter a Lablist
To Enter a Lablist with Headings
To Provide Subheadings within a Topic
To Show a Computer Listing
To Add a Note, Caution, or Warning

Entering Inline Elements

To Emphasize a Word or Phrase
To Enter a Book Title
To Emphasize Using a Bold Font
To Display a Computer Literal
To Display a Variable

Creating Hyperlinks

Using the <xref> Element

To Create a Link Using <xref>

Using the Link Element

To Create a Link Using <link>
To Create a Link to a Predefined ID
To Create a Link to a Topic in a Different Volume
To Create a Definition Link
To Create a Man Page Link
To Create an Application-Defined Link
To Link to a Meta Information Topic

Execution Link Control

Execution Policy Default Behavior

Execution Aliases

To Create an Execution Alias

Using Execution Aliases in Hyperlinks

To Create an Execution Link Using an Execution Alias

DtNexecutionPolicy Resource

Displaying Graphics

To Create a Figure
To Display an Inline Graphic
To Wrap Text around a Graphic

Including Special Characters

To Include a Special Character

Including Comments and Writer's Memos

To Insert a Comment
To Insert a Writer's Memo

Creating an Index

To Mark an Index Entry

Creating a Glossary

To Mark a Glossary Term
To Define a Term in the Glossary

This chapter describes elements that you can use to format your text. It also explains how to include graphics and how to create hyperlinks to other help topics. Examples shown in this chapter use shorthand markup.

Creating Help Topics

A help topic is a unit of information identified with a unique ID. Help topics are grouped into a logical framework that best describes the product you are writing online help for.

Each topic you write should have an element (or tag) that marks the start of the topic:

<element id=id>  Help Topic's Title
The body of the topic

Where element is one of the following: chapter, s1, s2, ..., s9. The body of the topic may begin on any line after the title.

The topic's position within the topic hierarchy is determined by the element used to start the topic and by the element used to start the immediately preceding topic. For example, a topic that starts with <s2> and immediately follows a topic that starts with <s1> makes the <s2> topic a subtopic of the <s1> topic.

The id is required if the topic is to be accessed either from the application (if you are writing application help) or from a hyperlink.

The help topic title can be any string. If the title string occupies more than one line in your source file, end all but the last line with an & (ampersand). To force a line break at a particular place within the title, use a \ (backslash) character.

Example

The following line marks the start of a topic using the <s1> tag:

<s1 id=welcome>Welcome to My Application

To force the title to be displayed on two lines, you use a \(backslash) like this:

<s1 id=welcome> Welcome to \ My Application

Creating Structure within a Topic

Within the body of a help topic, you have the following elements to choose from to organize and present your information:

Paragraphs are used for bodies of text.
Lists are used for itemized information. There are several types of lists including bulleted, ordered (numbered), and plain.
Subheadings are used to partition sections within a topic.
Graphics can be included within your text as inline graphics or displayed between paragraphs as standalone figures.
Hyperlinks provide references to related topics. A hyperlink may lead to a subtopic, deeper in the hierarchy, or branch to a topic in a completely different part of the hierarchy, or even in another help volume.
Computer literals are computer-recognized text, such as file names and variable names, that can be displayed as either separate example listings or inline elements.
Notes, cautions, and warnings call the reader's attention to important information.
Emphasis is used to highlight important words and phrases within paragraph text.

To Start a Paragraph

Insert a blank line after the previous paragraph or other element.

: Or, use the <p indent> element and parameter if the paragraph is to be indented.
: Or, use the <image> element if you want the paragraph to maintain the line breaks that you enter in your source file.

An end tag for  is not required. However, the <\image> end tag is required with the <image> element.

Examples

Here are two paragraphs, separated by a blank line. Because neither paragraph has any special parameters, the  tag does not have to be entered (it is assumed when you enter one or more blank lines):

The Application Builder provides an interactive, graphical environment that facilitates the development of desktop applications. The Application Builder is designed to make it easier for developers to construct applications that integrate well into the desktop. It provides two basic services: assembles Motif objects into the desired application user interface, and generates appropriate calls to the routines that support desktop integration services.

If you want a paragraph indented from the left margin, include the optional indent parameter:

 An indented paragraph can be used to draw the reader's attention to an idea.

The following paragraph overrides the automatic word wrap in help windows and maintains the line breaks exactly as entered in the source file. The <image> element is especially useful for entering addresses.

<image>
Brown and Reed Financial Investors
100 Baltic Place  Suite 40 New York, New York
<\image>

To Enter a List

Use the <list> element as shown:


<list type spacing>
* item
* item
 .
 .
 .
* item
<\list>

Where type indicates the type of list you want: bullet (default), order, or plain; and spacing is loose (default) or tight. Each item in the list is marked with an * (asterisk).

Examples

Here's a simple list. Because the type isn't specified, it defaults to a bulleted list. Because spacing isn't specified, it defaults to loose, which leaves a blank line between each item.

<list>
* Creating a Mail Message
* Sending a Message
* Reading Your Mail
<\list>

The online format of the preceding markup is:

To format the same list with numbers and reduced spacing between items, use:

<list order tight>
* Creating a Mail Message
* Sending a Message
* Reading Your Mail
<\list>

The output is:

To Enter a Lablist

A lablist is a two column list with optional column headings.

To create a labeled list without headings, use the <lablist> element as shown:


<lablist spacing>
    \ label 1\ item 1  text
    \ label 2\ item 2  text
      .
      .
      .
    \ label N\ item N  text
<\lablist>

Where spacing is loose (default) or tight.

Example

Here's a list of labeled chapter descriptions. The optional label headings are not provided.

<lablist tight> \Chapter 1\ An Overview of the System \Chapter 2\ Installing the Operating System \Chapter 3\ Configuring the Desktop \Appendix A\ System Commands Quick Reference <\lablist>

The output is:

To Enter a Lablist with Headings

Use the <lablist> and <labheads> elements as shown:


<lablist spacing>
 <labheads>  \ heading for labels \ heading for items
 \ label 1\  item 1 text
    \ label 2\  item 2 text
.
.
.

    \ label N\ item N text
<\lablist>

Example

This markup:

<lablist>
<labheads>\Key \Action
\Previous\ Scroll to previous page
\Next\ Scroll to next page
\First\ Go to first page in document
\Last\ Go to last page in document
<\lablist>

produces this output:

To Provide Subheadings within a Topic

For medium headings (slightly smaller than the topic title), use the following markup:


 <otherhead>  Heading
Or, for small headings, use the following markup: 
 <procedure>  Heading

Subheadings add structure within a topic, but they do not appear in the list of topics in the topic tree.

Example

Here, the <procedure> element is used to add a small heading before each list.

<procedure>Keyboard
<list order>
* Use the Tab and direction keys to move the highlight to the icon
  you want to select.
* Press Return or Spacebar.
<\list>
<procedure>Mouse
<list bullet>
* Click the icon.
<\list>

This markup creates this output:

To Show a Computer Listing

For computer listings that do not contain any special character sequences that will be interpreted as HelpTag markup, use the <ex> (example) element as shown:

<ex size>
Computer text here.
<\ex>

For computer listings that contain special character sequences used by HelpTag, use the <vex> (verbatim example) element as shown:

<vex size>
Computer text here.
<\vex>

The optional size attribute, which determines the size of the font used to display the example, can be specified as smaller or smallest.

Example

Here the <ex> element is used to represent a directory listing in a terminal window.

In this tutorial, you will edit these graphics files: <ex> H_ActionIcons.xwd H_HelpWindows.xwd H_AppHelp.xwd H_Hyperlinks.xwd H_Canonical.xwd H_Icons.xwd H_FrontPanel.xwd H_InlineGraphic.xwd <\ex>

The markup produces this output:

Line breaks appear where you enter them in your source file. If the example is too wide for the help window, a horizontal scroll bar appears so the user can scroll to see all the example text.

To Add a Note, Caution, or Warning

Include the <note>, <caution>, or <warning> element as follows:


<note>
Body of note here.
<\note>

<caution>
Body of caution here.
<\caution>

<warning>
Body of warning here.
<\warning>

To associate an icon with the note, caution, or warning element, define a file entity that identifies the graphics file containing the icon. Use one of the predefined entity names:

<!ENTITY NoteElementDefaultIconFile FILE "filename">
<!ENTITY CautionElementDefaultIconFile FILE "filename">
<!ENTITY WarningElementDefaultIconFile FILE "filename">

If you do not want icons with notes, cautions, or warnings, don't declare the corresponding entities. (Remember, all entity declarations must come before any other markup at the beginning of your help volume.) If you include such an entity reference, be sure the graphics file is in your HelpTag search path (helptag.opt).

Names of the default icons used by the Help System for note, caution, and warning elements are specified in the following entities.

<!ENTITY NoteElementDefaultIconFile FILE "noteicon.pm">
<!ENTITY CautionElementDefaultIconFile FILE "cauticon.pm">
<!ENTITY WarningElementDefaultIconFile FILE "warnicon.pm">

These default icons are located in the /usr/dt/dthelp/dthelptag/icons directory.

If you create your own icon images for notes, cautions, and warnings, be sure to keep them small so they will fit into the area allotted. Also, the graphic images must be in your HelpTag search path, which is specified in your helptag.opt file.

Example

The following markup for a note, warning, and caution produces the output shown in Figure 3-1.

<note>
Before installing your application, complete the options checklist
to determine the amount of disk space required.
<\note>

<warning>
This product is highly acidic and can cause skin irritation. Wearing
protective gloves is mandatory when applying this product.
<\warning>

<caution>
    Do not place your fingers near the parrot cage!
<\caution>

Figure 3-1 Note, warning, and caution help icons

Entering Inline Elements

Inline elements are used to mark words or phrases within a paragraph of text. These elements affect the font used to format particular items.

To Emphasize a Word or Phrase

Use the <emph> element (emphasis) as shown:


<emph> text <\emph>

Or, use the shorthand form:

!! text !!

Emphasized text is displayed using an italic font.

Example

Here's how you might emphasize an important word:

A thousand times <emph>no<\emph>

Or, using the shorthand form:

A thousand times !!no!!

In both cases, the word "no" is displayed in italics.

To Enter a Book Title

Use the <book> element as shown:


 <book>  title <\book>

Or, use the short form:

 book| title |

Book titles are displayed using an italic font.

Example

Here's how you would enter the title of this guide:

<book|The Help System Author's and Programmer's Guide|

To Emphasize Using a Bold Font

Use the <term> element as shown:


<term nogloss> bold text <\term>

Or, use the shorthand form:

<term nogloss |bold text |

The <term> element is used to create a glossary entry. However, by adding the nogloss parameter, the text is displayed in a bold font without being added to the glossary.

To Display a Computer Literal

Use the <computer> element as shown:


 <computer>  text  <\computer>

Or, use the shorthand form:

 `` text ''

Example

Computer text is useful for identifying a file name. Here the helptag.opt file name is tagged using shorthand markup. The file name will be displayed in computer text.

This markup:

Add the search path to your "helptag.opt" file.

produces this output:

Add the search path to your helptag.opt file.

To Display a Variable

Use the <var> element (variable) as shown:


<var> text <\var>

Or, use the short form:

<var |text |

Or, use the shorthand form:

%% text %%

Variables are displayed using an italic font.

Example

This command-line syntax uses a variable to show that the user supplies a file name.

dtpad %%filename%%

It produces this output:

dtpad filename

Variables can appear within computer text or computer example listings. This example specifies volume as a variable part of a file name:

The HelpTag software takes your "%%volume%%.htg" file as input.

It produces:

The HelpTag software takes your volume.htg file as input.

In both of these examples, the %% pairs could have been entered with the long form (<var>...<\var>) or the short form (<var|...|).

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>, , <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 , <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 in the section"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.

Execution Link Control

Most hyperlinks display a related help topic, but hyperlinks can also execute shell commands and scripts. Links of this type are called execution links. Because execution links interact with a user's system, the Help System provides an execution policy to control how execution links are handled.

The Help System uses resources to define the behavior of execution links. The DtNexecutionPolicy resource is set in an application's application defaults file to modify how execution links are handled by the Help System. In addition the Help System uses a set of resources called execution aliases. An execution alias is a resource that assigns a name (or label) to the command string or script that an execution link executes.

Execution Policy Default Behavior

When an execution link is selected, if the link has an execution alias, the Help System retrieves the value of the alias and executes the command. If an execution alias has not been defined, the Help System displays a confirmation dialog box that shows the command to be executed and asks the user whether to execute the command or to cancel the operation.

Execution Aliases

When using execution links in a help volume, it is recommended to create execution aliases. That is, in the application's application defaults file you define an alias (a name) that represents the actual command to be executed. One advantage of this method is that it isolates the actual commands from the help volume source files. This makes it possible to edit the commands in the application defaults file without changing the hyperlinks in the help volume. Each hyperlink references an alias name, which remains unchanged even though its content may have been edited. For instance, a tutorial help volume that uses scripts could be easily customized to accommodate a particular shell environment by modifying the shell script commands in the application defaults file.

To Create an Execution Alias

To create an execution alias in an application's application defaults file, use this resource specification syntax:

application_name.executionAlias.alias_name: command

Where:

application_name: Name or class name of the application that owns the help volume
executionAlias: Keyword that identifies the resource is an alias
alias_name: Name assigned to the command
command: Shell command or script to be executed for this link

There is no restriction on the length of the command string. To enter commands with multiple lines, end each line (except the last) with a \ (backslash).

Examples

This resource entry creates an execution alias named, StartDtterm, which starts a terminal emulator. The & (ampersand) starts the command in the background.

Dtterm.executionAlias.StartDtterm: dtterm &

This entry creates an alias named, xclockAlias, that executes the xclock application in an application named NightAlert.

NightAlert.executionAlias.xclockAlias: xclock &

Using Execution Aliases in Hyperlinks

An execution alias can be referenced using the <link> element or used in conjunction with elements that have a hyperlink parameter, such as  or <figure>.

To Create an Execution Link Using an Execution Alias

Use the <link> element as shown:


<link "DtHelpExecAlias alias_name [default_command]" Execute >text<\link>

Where:

DtHelpExecAlias: Keyword that identifies this link has an execution alias
alias_name: Name defined as an alias in the execution alias resource specification
default_command: Optional. If provided, this command is executed when an execution alias has not been loaded from an application's application defaults file. For example, application resources are not loaded when a help volume is displayed from an information viewer, such as Help View.
text: The portion of your help text that you want to designate as the hyperlink text (underlined)

Note: If the command you are executing doesn't finish immediately, run it in the background by appending an &(ampersand) to the command. If you don't, the help window will not operate until the command finishes.

Examples

This hyperlink references the execution alias named, xclockAlias. The resource definition for the alias is shown in the section "Execution Aliases."

The link starts the xclock program running in the background. The phrase "Start the Clock" becomes the hyperlink. Clicking the hyperlink runs the xclock program in a separate window. To end the program, close the window.

<link "DtHelpExecAlias xclockAlias" Execute>Start the Clock<\link>

Here is the same hyperlink including an optional default command.

<link "DtHelpExecAlias xclockAlias xclock &" Execute>Start the
Clock<\link>

DtNexecutionPolicy Resource

The DtNexecutionPolicy resource enables a system administrator or user to select an appropriate level of security for a given application.

The resource values that can be set are:

help_execute_query_all: Query all execution links.
help_execute_query_unaliased: Query only link commands that do not have execution aliases defined.
help_execute_none: Do not execute any execution links.
help_execute_all: Execute all execution links.

The default value is help_execute_query_unaliased. Any execution links defined as execution aliases will be automatically executed, whereas the Help System will display a confirmation dialog box for any other execution links.

It is not recommended for the application developer to set the DtNexecutionPolicy because this prevents a system administrator or user from altering the value.

Displaying Graphics

Help supports four graphics formats:

Tagged Image File Format (TIFF)--Color, grayscale, and black-and-white images created by many standard drawing and scanning applications (filename.tif).
X Window dump--Screen dumps from the X Window System created with the xwd utility (filename.xwd).
X pixmap--Color icon images (filename.pm).
X bitmap--Two-color icon images (filename.bm).

Each graphic is maintained as a separate file. The file format is determined using the file name extensions listed.

To Create a Figure

Declare a file entity to identify the image file to be included in the figure.
```
<!entity graphic-entity FILE "filename.ext"> 
```
Remember, all entity declarations must come before any other markup at the top of your help volume.
Use the <figure>element as shown:
```
<figure entity=graphic-entity>
caption string
<\figure> 
```
Where graphic-entity is the entity name for the graphic file you want to display, and caption string is an optional string. Caption text is displayed above the graphic.

By default, figures are numbered and the number is prepended to your caption string. To create a nonnumbered figure, include the nonumber parameter (as shown in one of the following examples).

If you want the figure to be a hyperlink, use the ghyperlink (graphic hyperlink) and glinktype (graphic link type) parameters as shown:

<figure entity=graphic-entity ghyperlink="id" glinktype=type>
caption string
<\figure>

The ghyperlink and glinktype parameters work just like the hyperlink and type parameters for the <link> element.

Examples

For these examples, assume that you've declared these two file entities at the top of your help volume:

<!entity FirstPicture  FILE "first.tif">
<!entity SecondPicture FILE "second.pm">

The following figure displays the graphic in the first.tif file and displays a number (by default) and caption:
```
<figure entity=FirstPicture>
Here's the First Picture
<\figure> 
```
Here's a figure that displays the second.pm file without a number or a caption:
```
<figure nonumber entity=SecondPicture>
<\figure> 
```
If you add an ID to a figure, you must have a caption. The caption is needed in case an <xref> uses the figure's ID; if so, the caption is inserted in place of the <xref> and becomes a hyperlink to the figure.

The following figure is an execution hyperlink that runs the xclock program:

<figure entity=SecondPicture ghyperlink="xclock &" glinktype=execute>
Choose This Figure to Start the Clock
<\figure>

To Display an Inline Graphic

Declare a file entity to identify the image file to be used in the figure.
```
<!entity graphic-entity FILE "filename.ext"> 
```
Remember, all entity declarations must come before any other markup at the top of your help volume.
Use the <graphic> element as shown:
```
... text <graphic entity=graphic-entity> text ...
```
Where graphic-entity is the entity name for the graphic file you want to display.

To use a graphic as a hyperlink, place it inside a <link> element:

<link parameters><graphic entity=graphic-entity><\link>

Note: The <graphic> element is intended for small graphics, although larger images can be used. Additional white space is added between lines to accommodate the height of the graphic.

Example

Here's an example that uses a small X bitmap image in the middle of a sentence. First, at the top of the volume, the bitmap file must be declared as a file entity:

<!entity StopWatch FILE  "stopwatch.bm">

Within the help text, the image is inserted using the <graphic> element:

Whenever you see the <graphic entity=StopWatch> symbol, stop and
answer the quiz questions.

This markup produces this output.

To Wrap Text around a Graphic

Declare a file entity to identify the image file to be included with the paragraph.
```
<!entity graphic-entity FILE "filename.ext"> 
```
Use the  element (paragraph) with the gentity parameter as shown:
```
 Paragraph text here ...
```
Where graphic-entity is an entity name that refers to the graphic file you want inserted.

Example

Suppose you want to display an icon named sample.pm and wrap paragraph text around it. First, declare the file entity:

<!entity HelpKeyIcon FILE  "helpkey.xwd">

Then, enter the paragraph:

 The F1 key is a Help key. When you press F1, the application you are using displays the help topic most closely related to your current activity.

To right-justify the graphic, add the gposition parameter like this:

<p gentity=HelpKeyIcon gposition=right>Many desktop components
support multicolor icons, in addition to two-color images.

Here's the markup for a paragraph wrapped around an icon, where the icon is a hyperlink that displays a topic with the ID icon-editor in a new window:

<p gentity=my-icon ghyperlink="icon-editor" glinktype=JumpNewView>
Many desktop components support multicolor icons, in addition to the
two-color images.

Including Special Characters

Many special characters and symbols are available within HelpTag. You display a particular character by entering the appropriate entity reference.

Some special character entities are declared in the file helpchar.ent. The helpchar.ent file is located in the /usr/dt/dthelp/dthelptag directory. To access these characters, either copy the particular entity declaration into your own volume, or include the entire helpchar.ent file. Unused entity declarations are ignored.

Refer to Chapter 6, "Summary of Special Character Entities," for a complete list of the available characters.

To Include a Special Character

Refer to Chapter 6, "Summary of Special Character Entities," to determine the entity name for the character you want to display. Also, note whether it is a built-in special character.
If the character is not a built-in special character, add the following two lines among your other entity declarations (where entity-name is a meaningful name to you):
```
<!entity entity-name FILE "helpchar.ent"> &entity-name;
&entity-name;
```
Also, add this line to your helptag.opt file:
```
search=/usr/dt/dthelp/dthelptag
```
If the character is built into HelpTag, you can skip step 2.
Wherever you want to display the special character, enter its entity reference:
```
&entity-name;
```

Examples

The entity for the copyright symbol (©) is a built-in special character, so all you have to do to display it is use this entity:

&copy;

To display the uppercase greek letter sigma (

), you must first include the helpchar.ent file (at the top of your help volume with your other entity declarations) as shown here:

<!entity  SpecialCharacterEntities  FILE   "helpchar.ent">
&SpecialCharacterEntities;

Then you can place the following entity reference where the sigma character is to appear:

&Usigma;

As with any entity, case is not significant in the entity names for special characters.

Including Comments and Writer's Memos

Frequently it is useful to include within your source files comments that are not intended to be part of the help text. Text marked with the comment element is always ignored by the HelpTag software. Comments can be used to make notes to yourself or to another author, or to exclude some markup without taking it out of the file.

In addition to standard comments, HelpTag also provides a <memo> element for entering writer's memos. Memo notes appear in your help topics during reviews, but not when you make your final help files. Authors commonly use the <memo> element to write questions or make notes to reviewers.

To Insert a Comment

Use the comment begin marker () as shown:


<!-- text here is completely ignored -->

The HelpTag software ignores all markup between the . A comment cannot be nested within another comment.

Example

Here's an example that has two comments, a line before the paragraph, and a single word within the paragraph.

 Welcome to my application. This software is  the fastest and most efficient software you'll ever own.

To Insert a Writer's Memo

Use the <memo> element as shown:


<memo> text <\memo>

By default, the text within the <memo> element is ignored by the HelpTag software (just like a comment). However, if you add the memo option to your helptag.opt file (or specify the memo option with the dthelptag command), all memos within your help volume appear in a bold font.

Example

Suppose you are writing about your application and have a question for the project team. You can include the question within the text using the <memo> element like this:

<memo>Team: Will the product also
support 32-bit characters?<\memo>

If you process the help volume with the following command (or include memo in your helptag.opt file), the memo appears in the help text in a bold font.

dthelptag volume memo

If the memo option is not used (or the nomemo option is used), the text within the memo is ignored and does not appear in the help text.

Creating an Index

The index for a help volume is similar to the index for a book. As an author, it is important to create index entries for your topics that will allow users to search for keywords or concepts. Creating a thorough index ensures that users will be able to find topics quickly and accurately.

To Mark an Index Entry

Within the topic you want to index, use the <idx> element as shown:


<idx>keyword<\idx>

Or, the short form:

 <idx|keyword|

Or, to control how the entry is sorted, use the <sort> subelement as shown:

<idx>keyword<sort>sortkey<\idx>

Where keyword is the text you want to display in the index and sortkey is the text used during sorting.

The <idx> element can be used anywhere within the topic. Neither the keyword nor the optional sortkey are displayed in the topic.

Examples

Here's the start of a topic with two keyword index entries:

<s1 id=getting-started>Getting Started with Helpview
<idx>starting Helpview<\idx>
<idx> Helpview, starting<\idx>

Welcome ...
.
.
.

The following example indexes the + (plus character), putting it in the keyword index where the word "plus" would appear:

<idx>+<sort>plus<\idx>

Creating a Glossary

Like a glossary in a book, your help volume can contain a glossary that defines important terms. The glossary, which is marked using the <glossary> element, is the last topic in your help volume.

Throughout your help volume, each key word or phrase that you enter with the <term> element automatically becomes a definition hyperlink to the term's definition in the glossary.

To Mark a Glossary Term

Use the <term> element as shown:


<term>word or phrase<\term>

Or, use the short form:

<term|word or phrase|

Or, use the shorthand form:

++word or phrase++

If the term within the help text isn't spelled exactly the same as the definition in the glossary, you can specify the "glossary form" of the term like this:

<term "glossary form">word or phrase<\term>

Where glossary form is the term exactly as it appears in the glossary. This is useful if the term must be plural in a help topic (because of its context), but must be singular in the glossary.

Terms are displayed using a bold font and automatically become a definition hyperlink. When the term is chosen, its glossary definition appears in a quick help dialog.

Note: If you mark a term that you intentionally do not define in the glossary, add the nogloss attribute to the <term> element. This allows the term to be displayed in the bold font used for terms, but without creating a link to the glossary.

Examples

If your glossary has a definition for the term "widget", you can enter it as a term like this:

A ++widget++ is the fundamental building block of OSF/Motif user interfaces.

If the glossary entry is "widget", but you need to use the plural form within the sentence, you could enter the term like this:

<term  "widget">Widgets<\term> are the fundamental building blocks
of OSF/Motif user interfaces.

If you want to enter the same term, but you either don't want to include it in the glossary or you don't want it to be a hyperlink, use the nogloss parameter like this:

<term nogloss> Widgets<\term>are the fundamental building blocks of
OSF/Motif user interfaces.

The equivalent short form is:

<term nogloss|Widgets| are the fundamental building blocks of
OSF/Motif user interfaces.

To Define a Term in the Glossary

Enter the <dterm> element into the glossary as shown:


<glossary>
.
.
.
<dterm>word or phrase
Definition of the term
.
.
.

Be sure to keep the <dterm>words and phrases sorted within the glossary.

Example

Here's part of a glossary that includes the definition of the term SGML:

<glossary>

. . . <dterm>SGML Standard Generalized Markup Language. An international standard [ISO 8859: 1986] that establishes a method for information interchange. SGML describes constructs for marking the structure of information separate from its intended presentation or format.

HP OpenVMS Systems Documentation

3 Writing a Help Topic

Creating Help Topics

Example

See Also

To Start a Paragraph

Examples

To Enter a List

Examples

To Enter a Lablist

Example

To Enter a Lablist with Headings

Example

See Also

To Provide Subheadings within a Topic

Example

To Show a Computer Listing

Example

See Also

Example

See Also

To Emphasize a Word or Phrase

Example

To Enter a Book Title

Example

Example

To Display a Variable

Example

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

See Also

Execution Policy Default Behavior

To Create an Execution Alias

Examples

Examples

DtNexecutionPolicy Resource

See Also

To Create a Figure

Examples

See Also

To Display an Inline Graphic

Example

Example

See Also

To Include a Special Character

Examples

See Also

To Insert a Comment

Example

Example

To Mark an Index Entry

Examples

See Also

To Mark a Glossary Term

Examples

To Define a Term in the Glossary

Example