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

#### See Also

- Chapter 2, "Organizing and Writing a Help Volume," describes the general structure of a help volume, including how to create a topic hierarchy.

## 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 `<p>` 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 `<p>` 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:

    <p indent> 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:

  #### See Also

  - "<list>" summarizes the use of the `<list>` element.
  - "<lablist>" summarizes the use of the `<lablist>`.

  ### 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.

  #### See Also

  - "To Display a Computer Literal."
  - "<ex>"
  - "<vex>"

  ### 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

  #### See Also

  - "To Create a Run_Time Help Volume" describes using a `helptag.opt` file.

  - "Using Entities".

  ## 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>` , `<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 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.

  #### See Also

  - "Registering Your Application and Its Help"
  - "<figure>"
  - "<image>"
  - "<link>"
  - "<p>"
  - "<xref>"

  ### 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).

  #### See Also

  - "Creating a Glossary."
  - "<term>"
  - "<link>"

  ### 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.

  #### See Also

  - "<link>"

  ### 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.

  #### See Also

  - "Built_in IDs" lists the Help System predefined IDs.

  ## 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 `<p>` 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.

  #### See Also

  - "<link>"
  - "<figure>"
  - "<p>"
  - `DtHelpDialog(3)`
  - `DtHelpQuickDialog(3)`

  ## 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

  1. 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.

  2. 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>

  #### See Also

  - "<figure>"
  - "<link>"

  ### To Display an Inline Graphic

  1. 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.

  2. 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

  1. Declare a file entity to identify the image file to be included with the paragraph.

         <!entity graphic-entity  FILE  "filename.ext">

  2. Use the `<p>` element (paragraph) with the `gentity` parameter as shown:

         <p gentity=graphic-entity> 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:

      <p gentity=HelpKeyIcon gposition=left> 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.

  #### See Also

  - "<p>"

  ## 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

  1. 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.

  2. 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.

  3. 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.

  #### See Also

  - Chapter 6, "Summary of Special Character Entities"

  ## 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 (`<!--`) and end marker (`-->`) as shown:

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

  The HelpTag software ignores all markup between the `<!--` and `-->`. 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.

      <!-- Here is my rough draft of the introduction: -->

      Welcome to my application. This software
      is <!-- perhaps --> 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.

  #### See Also

  - "<dterm>"
  - "<glossary>"
  - "<term>"

  ### 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.

  Generated with CERN WebMaker