test

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

Part II The Author's Job

Chapter 2 Organizing and Writing a Help Volume

This chapter describes the organization and components of a help source file. It also provides a step-by-step example that shows how to process a help source file to create an online help volume.

Help Volume Components

A help volume has six major types of components: the home topic, topics, subtopics, entity declarations, meta information, and the glossary.

Home Topic

The home topic is the top-level topic in the topic hierarchy. It is the first topic, or beginning of the help volume. All other topics are subtopics. Your topic hierarchy may be several levels deep. However, to help prevent users from getting lost, you should keep your hierarchy as shallow as possible.

Topics and Subtopics

Topics and subtopics form a hierarchy below the home topic. Typically, the first level of topics following the hometopic are divided into chapters, using the <chapter> element. Within a chapter, topics are organized into sections. Subtopics of an <s1> section are entered with <s2>, subtopics of <s2> entered as <s3>, and so on.

Either element, chapter or section, can follow the home topic. There is no visible difference to the user if you start your hierarchy with <chapter> or <s1>. Figure 2-1 shows a simple hierarchy that includes three chapters. Each chapter contains several first-level sections. The third chapter adds two second-level sections.

Figure 2-1 Help volume topic organization

Graphic

Entities

An author-defined entity can represent a string of characters or a file name. An entity declaration defines the entity name and the string or file it represents.

Entities are useful for:

All entity declarations must be entered before any other markup in your help volume. To include an entity that you have defined, you use an entity reference. Entity references can be used anywhere within your help volume. When you process your help volume with the HelpTag software, each entity reference is replaced with the text or file that the entity represents. " Using Entities" describes how to define and use entities.

Meta Information

Meta information is information about your information. It includes information such as the volume's title, copyright notice, and abstract. The abstract is a brief description of the volume's contents.

The Help System uses the meta information to display the title of a help volume and its copyright information. The abstract description is displayed by the desktop Help Viewer in the Front Panel. Other applications capable of displaying help volumes could also make use of this information.

Meta information can also include help topics that are not part of the normal topic hierarchy. Nonhierarchical topics placed in the meta information section are accessed with links.

"Creating Meta Information Topics" shows you how to create a meta information section.

Glossary

The glossary includes definitions for terms that you've used throughout your help volume. If a term is entered using the <term> element, then it automatically becomes a definition link that, when selected, displays the glossary entry for that term.

General Markup Guidelines

Online help is written in ordinary text files. You use special codes, or tags, to markup elements within the information. The tags form a markup language called HelpTag. If a standard text editor is used, HelpTag markup is typed. Or, if the editor provides a macro package, tags can be stored and inserted using command keys. HelpTag markup can also be generated using a structured editor (see "Formal Markup").

The HelpTag markup language defines a hierarchy of elements that define high-level elements, such as chapters, sections, and subsections, and low-level elements, such as paragraphs, lists, and emphasized words.

Markup in Your Source Files

The markup for most elements consists of a start tag and an end tag. Start tags are entered with the element name between angle brackets (< and >). End tags are similar, but the element name is preceded by a \ (backslash). 

<element>  ... text ... <\element>

For example, to mark the start and end of a book title you use markup like this: 

<book>Geographical Survey of Northern Wisconsin<\book>

Where <book> is the start tag, and <\book> is the end tag.

Shorthand Markup

Shorthand markup is a streamlined tag set designed for authors who are using a standard text editor to "hand-tag" information. Shorthand markup provides several shortcuts. First, it minimizes the use of end tags. For example, you do not need to enter end tags for chapters, sections, or paragraphs. In addition, when possible, intermediate tags are automatically assumed. For instance, the chapter and section elements allow you to omit a <head> tag; you just type your headline.

Shorthand markup axlso simplifies the markup for many inline elements as well as stylistic changes. Rather than entering a begin and end tag, vertical bars are used to delimit the text like this: 

<element| ... text ... |

For example, here's the short form of the <book> element shown previously: 

<book| Geographical Survey of Northern Wisconsin|

If the element has parameters, they're entered before the first vertical bar like this: 

<element parameters| ... text ... |

Some elements support an even shorter form where the start and end tags are replaced with a special two-character shortcut. For example, the <emph> (emphasis) element, whose normal syntax looks like this: 

<emph>  ... text ... <\emph>

can be entered using this shorthand form: 

!! ... text ... !!

Chapter 3, Writing a Help Topic, introduces shorthand markup and gives examples of the most frequently used elements. Chapter 5, HelpTag Markup Reference, provides an alphabetical list of elements and describes each element in detail.

Formal Markup

If you intend to use formal markup, you still need to become familiar with the information covered in Part 2 of this book. Then refer to Chapter 8, Reading the HelpTag Document Type Definition, for a description of formal markup.

Displaying HelpTag Symbols

At times, you may need to use the < (left angle bracket), the \ (backslash), or the & (ampersand) as text characters. To do so, precede each with an ampersand (&<, &\, or &&).

A Help Volume at a Glance

The following markup illustrates important elements of a help volume and the tags used to enter them. This example uses shorthand markup, which omits intermediate SGML structural tags and minimizes the number of required end tags. Indentation is used to highlight the hierarchical relationship of the elements; you don't need to indent the help files that you write. 

All entity declarations go here (before any other markup).
<helpvolume>
      <metainfo>
          <title>  Volume Title
          <copyright>
          Copyright topic goes here ...
          <abstract>
           The abstract describing your help volume goes here.
                             There may be other meta information topics.
            .
            .
            .
      <\metainfo> 
      <hometopic>  Home Topic Title
                     Help volume introduction  goes here ...
           <s1>  Title of First Topic Goes Here
                   Body of the first topic goes here ...
           <s1>  Title of Second Topic
                   Body of the second topic goes here ...
                   <s2>  Title of Suptopic
                          Body of the subtopic goes here ...
             .
             .
             .
 
     <glossary>
      The body of the glossary, which contains term definitions, goes here ...
 <\helpvolume>

Help Source Files

Online help is written in ordinary text files. You process, or compile, these files with the HelpTag software to create run-time help files that can be read by the Help System.

Creating Your volume.htg File

HelpTag expects a primary control file named volume.htg or volume.ctg, where volume is a name you choose. File extensions are used to distinguish whether the control file references shorthand (.htg) or formal (.ctg) markup.

Be sure your volume name is unique and meaningful. If your volume name is too general, it may conflict with another volume that someone else has created. If you are writing application help, one recommended practice is to use the application's class name. For example, the class name for the Icon Editor is Dticon, so its help volume is named Dticon.htg.

Multiple Source Files

The volume.htg file contains entity declarations and entity references to files that make up the help volume. Although HelpTag expects a single volume.htg file as input, you can separate your work into multiple source files. Additional files are sourced into the volume.htg file using file entities. A file entity is like a pointer to another file. That file, in effect, is inserted wherever the entity's name appears in the volume.htg file. The referenced files can also contain entity references to yet other files. (Entities can also be used to reference text strings.)

Example

Suppose a help volume has six chapters and each chapter is a separate file. The files are: HomeTopic, Metainfo, TOC, Tasks, Reference, and Glossary. The volume.htg file for the help volume includes file entities for each of the six files and a list of entity references that instruct the HelpTag software to process the files.

<!entity HomeTopic              FILE "HomeTopic">
<!entity MetaInformation        FILE "Metainfo">
 <!entity TableOfContents        FILE "TOC">
 <!entity Tasks                  FILE "Tasks">
 <!entity Reference              FILE "Reference">
 <!entity Glossary               FILE "Glossary">

&HomeTopic;
 &MetaInformation;
 &TableOfContents;
 &Tasks;
 &Reference;
 &Glossary;

The details of running HelpTag are covered in "To Create a Run-Time Help Volume".

Help Files in File Manager

File Manager represents help files as file icons with a question mark. In Figure 2-2, there are two source files (.ctg and.htg extensions) and one run-time file (.sdl extension). If you double-click a markup file, your standard editor opens the file for editing. Double-clicking a .sdl file displays the run-time file using the Help Viewer.

Figure 2-2 File Manager view of help files

Graphic

To create a run-time help volume, first select the .htg or .ctg file icon in File Manager. Then, choose Compile from the File Manager Selected menu.

See Also

Writing Your First Help Volume: A Step-by-Step Example

Typically you organize your help files in a help directory. This step-by-step example demonstrates how to create and view a standalone help volume. (As a standalone volume, it does not involve interaction with an application.)

To create and process a help volume, you follow these steps:

  1. Create the source directory for help files.

  2. Create the build directory.

  3. Create the master HelpTag file.

  4. Create the helptag.opt file.

  5. Create the run-time help files.

  6. Display the help volume.

    Each task is described in the section that follows. The markup language used in the text files is introduced later in this chapter. HelpTag markup is described more fully in Chapter 3, Writing a Help Topic and Chapter 5, HelpTag Markup Reference.

Create the Source Directory

  1. Create a directory named helpfiles where you will create and process your help files.

  2. Create a text file named Commands in the directory just created.

    For this example, all the information is put into a single file. Typically, you will use multiple files to fully explain the system or application you are writing help for.

    The Commands file contains text and element tags. The element tags within the < and > (angle brackets) indicate the structure of the information.

  3. Type the following markup text in the Commands file.

      <hometopic>  Command Summary
                         <idx|commands|

 Your &product; is capable of the following operations:
<list bullet>
  * <xref ChannelChange>
  * <xref VolumeUp>
  * <xref VolumeDown>
  * <xref VolumeMute>
 <\list>

 Choose one of the hyperlinks (underlined phrases)
 to find out how to perform that operation.

 <s1 id=ChannelChange>  Changing the Channel
                         <idx|channel, changing|
 Speak the command:
 <ex> channel<\ex>
 followed by a number from one to ninety nine.

 <s1 id=VolumeUp>  Turning Up the Volume
                         <idx|volume, changing|
 Speak the command:
 <ex> volume up<\ex>

 For additional volume, speak the command:
 <ex> more<\ex>

 (See also <xref VolumeDown> )

 <s1 id=VolumeDown> Turning Down the Volume
                         <idx|volume, changing|
 Speak the command:
 <ex> volume down<\ex>

 To further reduce the volume, speak the command:
 <ex> more<\ex>

 (See also <xref VolumeUp>  and <xref VolumeMute> )

 <s1 id=VolumeMute> Turning Off the Sound
                         <idx|volume, changing|
                         <idx|sound, on/off|
 Speak the command:
 <ex> sound off<\ex>

 To restore the sound, speak the command:
 <ex> sound on<\ex>

 (See also <xref VolumeDown>  and <xref VolumeUp> )

  4. Create a text file that gives the information a title, provides copyright information, and provides other information about the online help.

    In this example, the following text is put into a file called Metainfo in the same directory as the Commands file. 

    <metainfo>
      <title> Using the &product;
      <copyright>
      &copy; 1995 Voice Activation Company.  All rights reserved.
      <abstract> Help for Using the &product;.
 <\metainfo>

Create the Build Directory

Create a subdirectory named build in the helpfiles directory.

Graphic

Create the Master HelpTag File

  1. In the build subdirectory, create a text file whose name is of the form volume.htg. In this example, the file is named voiceact.htg.

  2. In the .htg file, define entities that associate the names of the Commands and Metainfo files with entity names. Also, define any entities that are used (either directly or indirectly) in the Commands and Metainfo files. Finally, refer to the Commands and Metainfo files by their entity names.

    In this example, the contents of the voiceact.htg file look like this. The text within the <!--...--> elements are comments, which are ignored. 

    <!-- Declare an entity for each of the source text files. -->
<!entity MetaInformation     FILE   "Metainfo">
 <!entity Commands            FILE   "Commands">

 <!-- Define an entity that names the product and includes
      the trademark symbol (&tm;). -->

 <!entity product  "VoAc&tm; Voice-Activated Remote Control">

 <!-- Include the text files. -->

 &MetaInformation;
 &Commands;

Create the helptag.opt File

  1. In the build subdirectory, create a file named helptag.opt and put the following text into it. This information selects HelpTag options and indicates where to search for any files defined in FILE entity declarations. 

    onerror=go
 memo
 search=./
 search=../

    The onerror=go option instructs the HelpTag software to continue processing input files even if an error occurred. See "Parser Options" for an explanation of parser options. For a complete list and description of parser options, refer to the dthelptag(1) man page.

  2. Verify that the /usr/dt/bin directory is in your search path by typing this command in a terminal window:

    echo $PATH

    If the directory is not in your path, add it to your PATH environment variable. If you're not sure how to do this, refer to your system documentation or ask your system administrator.

Create the Run-Time Help Files

  1. Open File Manager and change to the build subdirectory. Select the voiceact.htg file icon and choose Compile from the Selected menu in File Manager.

    This executes the HelpTag software which creates a run-time version of your online help volume (voiceact.sdl). Status and error messages are placed in a new file, whose name is of the form volume.err.

  2. Open the voiceact.err file to check that your file processed without errors. If errors occurred, fix them by editing or renaming the text files as needed.

    Note -

    You can run HelpTag manually in a terminal window.

    To do so, execute the following command:

    dthelptag -verbose voiceact.htg

    The -verbose option tells HelpTag to display its progress on your screen.

Display the Help Volume

From the build subdirectory, double-click the voiceact.sdl file icon.

This displays the help volume using the desktop Help Viewer. You can now scroll the information and jump to related information by choosing hyperlinks.

Note -

You can run the Help Viewer manually in a terminal window.

To do so, execute the following command. It displays the new help volume.

dthelpview -h voiceact.sdl

See Also

Creating a Topic Hierarchy

The topic hierarchy within your help volume begins with the home topic. Each help volume must have one home topic. The first level of subtopics below the home topic may be entered with <chapter> or <s1>.

Additional levels of subtopics are entered with <s2>, <s3>, and so on. The HelpTag markup language supports nine topic levels, <s1> to <s9>. However, information more than three or four levels deep often leads many readers to feel lost.

When a help volume is displayed, the help window displays a list of topics in its topic tree. Any topic entered with a <chapter> or <s1...s9> tag automatically appears in the topic tree. This provides an easy way to browse and view topics.

To enable users to display other related information from within a topic, you create hyperlinks. To do so, you assign a unique ID to each destination topic. Hyperlinks make it possible to reference a specific ID anywhere in your help information.

Example

Suppose you want to create a hierarchy to match this simple outline: 

Tutorial for New Users
       Module 1: Getting Started
       Module 2: Creating Your First Report 
      Module 3: Printing the Report
       Module 4: Saving Your Work and Quitting 
 Task Reference 
      Starting and Stopping 
           To Start the Program 
           To Quit the Program
       Creating Reports 
           To Create a Detailed Report
            To Create a Summary Report
  Concepts for Advanced Users
       Using Report Hot Links 
      Sharing Reports within a Workgroup  Reference
       Command Summary 
      Report Attributes Summary

Then the general outline of your help volume would look like this. (The body of each topic and IDs for the topics are not shown.) 

<hometopic>  Welcome to Report Master
   <chapter>  Tutorial for New Users
     <s1>  Module 1: Getting Started
     <s1>  Module 2: Creating Your First Report
     <s1>  Module 3: Printing the Report
     <s1>  Module 4: Saving Your Work and Quitting
   <chapter>  Task Reference
     <s1>  Starting and Stopping
       <s2>  To Start the Program
       <s2>  To Quit the Program
     <s1>  Creating Reports
       <s2>  To Create a Detailed report
       <s2>  To Create a Summary report
   <chapter>  Concepts for Advanced Users
     <s1>  Using Report Hot Links
     <s1>  Sharing Reports within a Workgroup
   <chapter>  Reference
     <s1>  Command Summary
     <s1>  Report Attributes Summary

Indentation is used here to make it easier to see the structure of the help volume. You do not have to indent your files.

See Also

To Create a Home Topic

    Use the <hometopic> element as follows: 

<hometopic> Title
 Body of topic.

If you include a meta information section (<metainfo>), the home topic must follow it.

Examples

Here's a home topic with a title and a single sentence as its body: 

<hometopic> Welcome to My Application
 Congratulations, you've entered
 the online help for My Application.
Here's a sample home topic that includes hyperlinks to its four subtopics: 
<hometopic> Welcome to Report Master

 Welcome to the online help for Report Master.
 Choose one of the following hyperlinks:

 <list bullet>
  * <xref Tutorial>
  * <xref Tasks>
  * <xref Concepts>
  * <xref Reference>
 <\list>
 If you need help, press F1.

The preceding markup produces this output:

Graphic

To Add a Topic to the Hierarchy

    To add another topic at the same level, repeat the same element.

Or, to add a subtopic (a topic one level deeper in the hierarchy), use the element that is one level deeper than the preceding topic.

Example

If the current topic is an <s1>, enter a subtopic using <s2>. 

<s1 id=getting-started>  Getting Started

 <s2 id=starting-the-program>  Starting the Program
 Here's the body of the first subtopic.
 
 <s2 id=stopping-the-program>  Stopping the Program
 Here's the body of the second subtopic.

The second <s2> is also a subtopic of the <s1>.

Note -

Sometimes a parent-child-sibling metaphor is used to describe the relationships between topics in a hierarchy. In the preceding example, the <s1> topic is the "parent" of both <s2>s (the "children" topics). The two <s2>s are "siblings" of one another. All three topics are "descendents" of the home topic.

Creating Meta Information Topics

The meta information section is primarily intended for information about information. Similar to providing a copyright page in a book, this section includes information such as the volume title, copyright, trademark, and other notices.

A secondary use of the meta information section is to enter help topics that are not part of the normal topic hierarchy. These nonhierarchical topics are useful for creating custom definition links that pop-up a topic in a quick help dialog box.

To Create a Meta Information Section

  1. Enter the <metainfo> tag to start the section, and enter the required subelements <title> and <copyright> as shown: 

    <metainfo>

 <title> Volume Title Here
 
 <copyright>
 Body of copyright topic here.
 .
 .
 .

  2. Enter any of the optional elements as shown: 

    <abstract>
 Body of the abstract topic here.
 Do not use any HelpTag markup within the abstract!

  3. Enter the <\metainfo> end tag to end the section. 

    .
 .
 .
 <\metainfo>
    Note -

    Some elements in the meta information section require a <head> tag before the topic heading.

    The <abstract> section is recommended. Applications that access help volumes can use this information to present a brief description of the volume. Because the abstract might be displayed in plain text windows (that do not support multiple fonts and graphic formatting), avoid including any HelpTag markup in the abstract.

Example

Here's a typical meta information section: 

<metainfo>
  <title>  Report Master, Version 1.0

   <copyright>
     <otherhead> Report Master

     <image>
     Version 1.0
     &copy; Copyright Reports Incorporated 1995
     All rights reserved.
     <\image>

   <abstract>
     This is the online help for the mythical Report Master
     application. This help includes a self-guided tutorial,
     a summary of common tasks, general concepts, and quick
     reference summaries.

 <\metainfo>

The <image> element is used to preserve the author's line breaks. The &copy; entity inserts the copyright symbol.

See Also

Adding a Nonhierarchical Topic

Topics entered with a <chapter> or <s1...s9> element tag automatically appear in the topic tree. When a title is selected in the topic tree, the corresponding help topic is displayed in a general help dialog box. However, sometimes you may want to create and display a topic independent of the topic hierarchy you have created. For example, you might want to display a topic in a separate, quick help window.

To Add a Nonhierarchical Topic

    Add the topic just before the end of your meta information section using the <otherfront> element as follows: 

<otherfront id=id><head>  Topic Title
 Body of topic.

The ID parameter and <head> tag are required.

You can add as many <otherfront> topics as you want. They may be in any order, but they must be the last topics in the <metainfo> ... <\metainfo> section.

Example

This partial help volume shows how a general topic is added to the meta information section. The topic's title is "Pop-up!" and its ID is my-popup-topic. 

<metainfo>
   <title> My Help
   <copyright>
      This is My Help, Version 1.0.  &copy; 1995.
         .
         .
         .
   <otherfront id=my-popup-topic> <head> Pop-up!

   This is a pop-up topic, displayed via a definition link
   somewhere in my help volume.
 <\metainfo>

 <hometopic>  Welcome to My Help
         .
         .
         .

Presumably, within some other topic in the help volume, there's a definition link to display this topic.

The link might look like this: 

Here's a sample of a pop-up <link my-popup-topic Definition> definition link<\link>.

The words "definition link" become the active hyperlink and will be displayed with a dashed underline. Selecting the link displays the "Pop-up!" topic in a quick help dialog box.

See Also

Accessing Topics

Many elements in the HelpTag language support an ID attribute. An ID is a unique name used internally to identify topics and elements within topics. An ID is defined only once, but multiple hyperlinks and cross-references can refer to the same ID. IDs are not seen by the user.

If you are writing help for an application, IDs are also used by the application to identify particular topics to display when the user requests help. For example, you might write several topics that describe an application's menus. The IDs that you assign to the topics are used by the application developer. By defining identical IDs within the application code, the developer can integrate specific topics. This allows the application to access and display the correct topic when help is requested for a particular menu.

Rules for ID Names

To Add an ID to a Topic

    Use the id parameter for the element as follows: 

<element id=id>  ...

The elements that start a new topic and support an author-defined ID are:

Built-in IDs

A few elements have built-in IDs and, therefore, do not support an author-defined ID. Each of the following elements also starts a new topic, but these elements have predefined IDs (shown in parentheses):

<abstract>

(_abstract)

<copyright>

(_copyright)

<glossary>

(_glossary)

<hometopic>

(_hometopic)

<title>

(_title)

To Add an ID to an Element within a Topic

    If the element supports an author-defined ID, use the id parameter for the element as follows: 

<element id=id>  ...

The elements (within a topic) that support an ID attribute are:

Or, use the <location> element to set an ID at an arbitrary point within the topic as follows: 

<location id=id> text <\location>

Where text is any word or phrase where you want to add an ID. The <\location> end tag is required. When you activate a link to a location ID, the Help Viewer displays the topic containing the ID and scrolls the window to the ID position.

Examples

If you add an ID to a figure, you must have a caption. The caption is needed in case a cross reference is made to the figure's ID. In that case, the caption becomes a hyperlink to the figure.

Here's the markup for a figure with the ID my-big-picture. 

<figure id=my-big-picture entity=big-picture-TIFF>
 Here's My Figure
 <\figure>

Here's a paragraph where the phrase "easier than ever" has been assigned the ID easy-spot: 

Getting help is <location id=easy-spot> easier than ever<\location>.

Using Entities

An entity can represent a string of characters or the contents of a file. An entity declaration defines the entity by associating the entity name with a specific character string or file name. An entity reference is replaced by the string or file contents when you process the help volume with the dthelptag command.

Entities are useful for:

File entities are also useful for splitting your HelpTag source into multiple files. Use entity references to include other files into your master HelpTag file for processing.

Rules for Entity Declarations

To Create a Text Entity

  1. Declare an entity as follows: 

    <!entity Entityname  "text">

    Where Entityname is the name of the entity and text is the string that you want substituted for every reference to the entity. Remember, all entity declarations must come before any other markup in your help volume.

  2. For each location where you want the text string to be inserted, enter the entity reference as follows: 

    &Entityname;

    The & (ampersand) and ;(semicolon) characters are required for the HelpTag software to properly recognize the entity reference.

Example

The following line declares a text entity named Assoc that contains the string "Society of Agricultural Engineers": 

<!entity Assoc "Society of Agricultural Engineers">

The following sentence includes a reference to the entity: 

Welcome to the &Assoc;.

When the help volume is processed with the HelpTag software, the entity reference is replaced with the value of the entity. So, the sentence reads:

Welcome to the Society of Agricultural Engineers.

To Create a File Entity

  1. Declare an entity as follows: 

    <!entity Entityname FILE  "filename">

    Where Entityname is the name of the entity and filename is the name of the file. The keyword FILE is required.

  2. Reference the entity as follows:

    • If the file is a text file, enter the following entity reference at each location where you want the contents of the file inserted. 

      &Entityname;

      The & (ampersand) and ; (semicolon) characters are required for the HelpTag software to properly recognize the entity reference.

    • If the file is a graphics file, include the name of the entity as a parameter in one of the following markup lines: 

      <figure entity=Entityname ... >

      Or: 

      <graphic entity=Entityname ... >

      Or: 

      <p gentity=Entityname ... >
      Note -

      Do not include any path in the file name. If the file is not in the current directory when you run the HelpTag software, add the appropriate search path to the helptag.opt file. (See "To Create a Run-Time Help Volume".)

Example: Text File Entities

Suppose you wrote the text for your help volume in three files named file1, file2, and file3, plus a fourth file containing your <metainfo> ...</metainfo> section. You could include them in your volume.htg file like this: 

<!entity MetaInformation   FILE  "metainfo">
<!entity MyFirstFile       FILE  "file1">
 <!entity MySecondFile      FILE  "file2">
 <!entity MyThirdFile       FILE  "file3">

 &MetaInformation;

 <hometopic>  My Home Title

 Welcome to my application's help volume.

 &MyFirstFile;
 &MySecondFile;
 &MyThirdFile;

Example: A Graphic File Entity

Suppose a simple help volume has a figure in the home topic and the graphic image for the figure is stored in a file named picture.tif. The following example shows how that image would be used in a figure. 

<!entity MetaInformation  FILE  "metainfo">
<!entity MyPicture        FILE  "picture.tif">

 &MetaInformation;

 <hometopic> A Sample Graphic

 Welcome to my application's help volume

 <figure nonumber entity=MyPicture>
 A Picture
 <\figure>

The text "A Picture" is the figure's caption.

The markup produces this output:

Graphic

See Also

Chapter 3 Writing a Help Topic

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

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:

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:

Graphic

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:

Graphic

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:

Graphic

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:

Graphic

See Also

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:
Graphic

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:

Graphic

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

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.

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

Graphic

See Also

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:

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.

Graphic

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.

See Also

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

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

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

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

Displaying Graphics

Help supports four graphics formats:

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

See Also

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.

Graphic

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

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

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

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.

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.

See Also

Chapter 4 Processing and Displaying a Help Volume

This chapter shows you how to process your marked-up help files to create an online format that you view using the Help System. It also describes how to make your help volume accessible from the desktop Front Panel Help Viewer.

Overview

Before a help volume can be displayed, you must create a run-time help file by processing your files with the HelpTag software. Run-time files use an online presentation format called Semantic Delivery Language. A .sdl file extension identifies a run-time help file.

Graphic

The Help System defines desktop actions and data types for help-specific files. This lets you easily process and view a run-time help file from the desktop.

HelpTag Software

The HelpTag software can be invoked automatically by double-clicking a help source file in File Manager or by running the dthelptag command manually in a terminal window.

Helptag does two significant tasks:

  1. The HelpTag parser converts your marked-up files into an internal format (Semantic Delivery Language) understood by the Help System. If you've made any markup errors, the errors are reported in a file named volume.err.

  2. If there are no parser errors, the master help volume file (volume.sdl) is created.

Viewing Your Volume

After processing your source files with HelpTag, your help volume is ready to be displayed. You can display it by double-clicking the volume.sdl file icon in File Manager, or use the dthelpview command in a terminal window.

Graphic

If you have written help for an application and the application is ready to use, you can display your help by running the application and asking for help.

Creating Run-Time Help Files

When you run HelpTag, it reads your volume.htg or volume.ctg file and any additional source files that are included using entities. Also, graphics file names are validated.

Be sure the /usr/dt/bin/dthelptag command is in your search path. (If you're not sure how to do this, ask your system administrator.)

To Create a Run-Time Help Volume

  1. Open File Manager and change to the directory where your volume.htg file is located.

    Graphic

  2. Select the file icon.

  3. Choose Compile from the File Manager Selected menu.

    The volume.htg file is processed and creates a volume.sdl file and volume.err file.

HelpTag Output

The output from HelpTag is a run-time help volume, named volume.sdl. If any errors occurred during processing, they are reported in an error file (volume.err). If no errors were encountered, the volume.err file contains copyright information and several status lines.

Setting the onerror=go option in your helptag.opt file allows the parser to continue processing (if possible) after encountering an error. Without the onerror=go option, the parser halts when the first error is detected. The volume.sdl file is not created until the source file is without errors.

The volume.sdl file, plus your graphics files, are read by the Help System to display help topics. The run-time help file has the same base name as your volume.htg file. For example, if your volume.htg is named Librarian.htg, then the help volume name is Librarian.sdl.

Caution - Caution -

Never rename a run-time help file or graphics file after running HelpTag. The information stored in the volume.sdl file depends on the original names. If you rename your volume.htg file or any of your graphic files, be sure to rerun HelpTag.

To Run the dthelptag Command Manually

    Run the dthelptag command as follows: 

dthelptag  command-options  volume  parser-options

Where command-options are options entered before the volume name and parser-options are options entered after the volume name. "Processing HelpTag Files (dthelptag)" lists all available options.

Example: Commands

The following command processes a help volume named MyVolume: 

dthelptag MyVolume

Using the -verbose option causes the progress of the processing to be displayed on your screen: 

dthelptag -verbose MyVolume

Adding a search path enables HelpTag to find files stored in a subdirectory (of the current directory) named graphics: 

dthelptag -verbose MyVolume search=graphics

Example: A helptag.opt File

Here's a sample helptag.opt file showing that each option is on a separate line. It would be appropriate for creating a draft version of the volume. 

memo
onerror=go 
search=graphics/
search=entityFiles/

Before producing the final version of the help volume, you would remove the memo and onerror=go lines.

See Also

To Review and Correct Parser Errors

    Look at the contents of the volume.err file after running HelpTag (where volume is the base name of your volume.htg file).

Each error listed in the volume.err file begins with a string of asterisks (*****). For example, the following error was detected at line 54 of the file actions: 

*****
Line 54 of actions,
Missing end tag for LIST:
...the execution host becomes the current working directory.

<s2 id=EverythingYouNeedToKnow> E...
Current element is LIST begun on Line 28 of actions.

A few lines of the file are shown to give you some context for the error. Also, there is a hint that the current element is a LIST started on line 28 of the same file. An <s2> is not allowed within a list, so it appears that the author forgot to enter the <\list> end tag.

It's possible for a single, simple error to produce several error messages. This is because the first error may cause the parser to lose track of the intended context, making it impossible to interpret subsequent markup properly.

Common Errors

Most processing errors result from these common mistakes:

Omitting an end tag for an element is a common mistake. When creating elements, such as a list, figure, note, caution, or warning, be sure to include the end tag. Check your markup carefully especially if you have nested one element within another, such as a figure within a list,

Errors can also be introduced by using an incorrect entity name. In most instances, it is simply a misspelled word. In other cases, an entity name may have been changed, but cross-references to the original name were overlooked. When you change an entity name, remember to search your source file (or files) for all instances of the entity name.

Similarly, changing the ID assigned to an element affects any cross-reference or link to that topic.

Viewing a Help Volume

The Help Viewer can be used to display any help volume. It supports all types of hyperlinks except application-defined links (because it cannot know how your links are to be interpreted).

If you are writing application help and your application is ready to use, you can also view your help by running your application, then requesting help just as a user would.

To Display a Help Volume

  1. Open File Manager and change to the directory where the volume.sdl file is located.

  2. Double-click its icon.

    The default action displays the file using the Help Viewer.

To Run the dthelpview Command Manually

    If the volume.sdl file for the volume you want to display is either in the current directory or has been registered, execute this command: 

dthelpview -helpVolume volume.sdl

Or, if the volume.sdl is in another directory (and hasn't been registered), execute this command: 

dthelpview -helpVolume /full-path/volume.sdl

The -helpVolume parameter can be shortened to -h in any of these commands.

Example

Suppose you just edited your help volume. First, process it with the HelpTag software: 

dthelptag MyVolume

If no errors occurred, you could then display it with this command: 

dthelpview -h MyVolume.sdl

See Also

Example: A Personal Help Directory

During a project, you may want to access the help volume you are developing, but not expose it to all users on your system. For example, suppose your working directory is /projects/help and your help volume is named Myvolume.

First, create the personal help directory in your home directory where you can register the volume: 

mkdir -p $HOME/.dt/help/C

Now create a symbolic link to the Myvolume.sdl file (which is created by the HelpTag software): 

ln -s /projects/help/Myvolume.sdl $HOME/.dt/help/C/Myvolume.sdl

You can now display the volume with the following command (regardless of your current directory) because the.dt/help/C directory within your home directory is one of the first places the Help System looks for help volumes. 

dthelpview -helpVolume Myvolume

Adding Your Help to the Browser Volume

The desktop provides a special help volume called the browser volume that lists help volumes available on your system. The browser volume is displayed by clicking the Help Viewer control in the Front Panel.

You can view assorted help volumes directly from the browser volume. This allows access to application-specific help without starting the application. Or, if you are writing standalone help, this is the only way for users to get to your help.

Figure 4-1 Browser help volume displaying help families

Graphic

To make your help volume available in the browser volume, you create a help family file. When your application is registered on the desktop, the presence of a family file causes the help volume to be included in the browser volume.

Browser Volume

A desktop utility creates and updates the browser volume. When a user clicks on the Front Panel Help Viewer for the first time, the utility is automatically run. It identifies help volumes and help family files that are located in the help search path directories. It creates a file called browser.hv in the user's HomeDirectory/.dt/help/$DTUSERSESSION directory. After initial creation, the volume is updated only if changes have occurred.

To manually update the browser volume, refer to "Generating a Browser Help Volume (dthelpgen)".

Any help volume listed in the browser volume can be viewed by selecting the volume title. Because you can display and navigate through different volumes, the browser help window includes an additional button, called Top Level. You can use this button to return to the browser list after displaying one or more volumes.

Help Family File

The desktop utility examines help family files to identify which help volumes are gathered into the browser volume. Figure 4-1 shows two help families, Common Desktop Environment and Overview and Basic Desktop Skills, listed in the browser volume. Each family file consists of one or more related help volumes. For example, the Common Desktop Environment family includes different volumes that describe the desktop.

Refer to the CDE Advanced User's and System Administrator's Guide for a detailed explanation of how an application and its help files are installed on the desktop.

To Create a Help Family

  1. Pick a file name that is unique to your product. Use the.hf extension to identify the file as a help family. 

     
family.hf

  2. Enter the following lines into the file: 

    *.charSet:      character-set
 *.title:        family title
 *.bitmap:       icon file
 *.abstract:     family abstract
 *.volumes:      volume volume volume ...

    Where character-set specifies the character set used by the family title and family abstract strings. See "Understanding Font Schemes" for a list of supported character sets. The family title and family abstract should not contain any HelpTag markup; this file is not processed with the HelpTag software.

    The icon file is optional. If you provide one, the path you use to specify the location of the file should be a complete path name. If you do not provide an icon, do not include the *.bitmap resource in your family file.

    The list of volume names identifies which volumes belong to the family. The volumes will be listed in the order they appear on this line. A volume may be listed in more than one family.

    If any of the values occupy more than one line, end each line -- except the last -- with a backslash (\).

    Any line in the file that begins with an ! (exclamation mark) is a comment line and is ignored.

  3. When you prepare your final product, you should install your family.hf file with the rest of your help files. When the desktop integration script, (dtappintegrate) is run, it creates the symbolic links to your family file.

    The CDE Advanced User's and System Administrator's Guide describes how to run the dtappintegrate script.

Example

Here's a family file for the desktop's online help. Comments at the top of the file identify the family and release version. 

!##############################################
 !#                                            #
 !#          Desktop  Help Family              #
 !#                                            #
 !#                 Version 1.0                #
 !#                                            #
 !##############################################
 *.charSet:      ISO-8859-1
 *.title:        Desktop Version 1.0
 *.bitmap:       /usr/dt/appconfig/help/C/cdelogo.pm
 *.abstract:     Overview and Basic Desktop Skills \ 
                 * File Manager and the Desktop \ 
                 * Front Panel \ 
                 * Application Manager \ 
                 * Style Manager \ 
                 * Text Editor \ 
                 * Mailer
 
*.volumes: Intromgr.sdl Filemgr.sdl FPanel.sdl
            Appmanager.sdl Stylemgr.sdl
            Textedit.sdl Mailer.sdl

The help family file actually included with the desktop software may not exactly match this example.

See Also

To Display the Browser Volume

  1. Choose the Help Viewer control from the desktop's Front Panel.

    Graphic

  2. Scroll the help window to view the help families available on your system.

  3. If desired, display a volume by selecting the help family title.

    Note -

    To view help information about the Help System, choose the title Common Desktop Environment and then Desktop Help System.

To Display the browser Volume Manually

    Run the dthelpview command as follows: 

dthelpview -helpVolume browser

See Also

Printing Help Topics

After displaying your help volume, you can print help topics. Using the Print dialog box shown in Figure 4-2 you can print an individual topic, a table of contents and index information, or the entire help volume. Printed output omits graphics.

Figure 4-2 Help print dialog box

Graphic

Testing Your Help

Testing your help volume is as important as testing any software product. Here are some tips to help you plan your testing.

Validating Hyperlinks

Verifying Entry Points

If you are writing application-specific help that uses IDs to access particular help topics, there are two ways to verify that the IDs have been properly established within the help volume:

Checking Index Entries

Users search or browse a help volume index to find help topics. Examine your index entries carefully to eliminate any vague terms or duplicate entries. Also select each index entry to verify that the topic displayed is the most appropriate information.

Testing Graphics

Checking for Parser Errors

When developing a help volume, it is often convenient to set the onerror=go option in the helptag.opt file. If you have done this, you should remove the option and process your source files a final time to ensure that no errors are encountered.

See Also

Chapter 5 HelpTag Markup Reference

This chapter describes all of the HelpTag markup elements (and their associated tags) in alphabetical order.

Element Descriptions

To help determine the name of a tag based on how it is used, the elements are grouped below according to use. (A few elements appear in more than one group.)

Meta information (information about your volume):

Structure of a help volume:

Inline elements: 

<book>
<computer>  (shorthand: "text")       
<emph>  (emphasis) (shorthand: !!text!!)      
 <ex>  (example) and <vex>  (verbatim example)       
<image>       
<keycap> (shorthand: [[ text ]])       
<lineno> (line number)       
<newline>       
<p>  (paragraph)       
<quote> (directional quotes)       
<sub> (subscript) (shorthand: _ _ text _ _)       
<super> (superscript) (shorthand: ^^text^^)       
<term>  (shorthand:  ++text++)       
<user>  (user input)       
<var>  (variable) (shorthand: %%text%%)       
&...; (see <!entity> )

Important information: 

<note>       
<caution>       
<warning>       
<emph>  (emphasis) (shorthand: !!text!!)

Lists: 

<list>       
<lablist>  (labeled list)       
<item>  (shorthand: *)

Graphics: 

<figure>       
<graphic>

Glossary and index: 

<glossary>       
<dterm>  (definition of term)      
<term>  (shorthand: ++text++)       
<idx>  (index)

Cross-references and hyperlinks: 

<xref>  (cross-reference)       
<link>       
<location>       
<term>

Hidden text: 

<!-- ... --> (comment)       
<memo>

Titles and headings: 

<abbrev>      
<head>       
<otherhead>       
<procedure>       
<title>  (title of help volume)

Override meaning of HelpTag markup: 

<vex>  (verbatim example)

<!-- ... -->

Comment: Identifies text you want the HelpTag software to ignore. Comments cannot be nested.

Syntax

<!-- comment text here -->

The comment text can contain any text except two dashes (--).

Example

The following markup hides both a comment and a figure: 

<!-- Let's leave out this figure for now:
<figure entity=ProcessFlowChart>
 Before and After Processing
 <\figure>
 -->

See Also

<abbrev>

Abbreviated title: Indicates an alternate, typically shorter, heading for a topic that has a long title. When an abbreviated title is provided, it is used in the Index and History dialog boxes rather than the full title.

If a heading contains a graphical element, you must provide an <abbrev> that contains only the text of the heading. Although the graphic image can be displayed in the topic tree, the Index and History dialog boxes cannot display graphic elements.

An <abbrev> should not contain any markup.

Syntax

<topic-element> title
<abbrev> short title

Where topic-element is <hometopic>, <chapter>, <s1>, or any other element that begins a new topic.

The <abbrev> tag must appear on the line immediately following the heading.

An end tag is not required.

Examples

Here is a simple example: 

<chapter> Ways of Treating Headings that are Too Long
<abbrev> Long Headings

Suppose you want to have a topic that doesn't have its title displayed in the help topic display area, but you do want a title to appear in the topic tree. The following markup shows how this can be done: 

<chapter> &empty;

<abbrev> chapter title

See Also

<abstract>

Abstract: Provides a short description of the help volume.

Syntax

<metainfo>
   .
    .
    .
   <abstract>
   abstract text here ...
   <\abstract>
    .
    .
    .
 <\metainfo>

The abstract text should not contain HelpTag markup because the abstract may be read and displayed by applications that don't recognize markup.

The <abstract> element is automatically assigned the ID string _abstract. An author-defined ID cannot be assigned. The _abstract ID can be used with the <link> element, but not with the <xref> element.

Abstract text may contain an optional <head>.

Example

This markup briefly describes the contents of a help volume: 

<abstract>
 Online help for the Application Manager Version 1.0.
 <\abstract>

Note

When creating a link to an element within the <metainfo> element, be sure it is a type=Definition link.

The following markup shows how to create a link to the abstract: 

<link hyperlink= "_abstract" type=Definition>
 Choose this link for an abstract.<\link>

See Also

<<annotation text>>

Annotation: Provides an explanatory note or comment within an example (<ex> tag).

Syntax

<ex [side | stack]>
text of the example ...<<annotation text >>
<\ex>

 Where:
side

Default. Places the annotation to the right of the example text and on the same line as the first line of the example.

stack

Places the annotation below the example text.

Enclose the text of an annotation in double angle brackets, as follows: << this is the annotation text>>. An annotation can only be used within an <ex> tag. The side and stack parameters of the <ex> tag can be used to position the annotation in relation to the example text.

To insert a blank line in an annotation, use a space followed by an empty annotation, wordspace <<>>.

Example

The following markup uses the default side placement for the annotation:

<ex>
 Login: <<Enter your name>>
 <\ex>

It produces:

Login: Enter your name

The following markup uses the stack parameter to accommodate a long annotation:

<ex stack>
 Quarterly Sales Reports
<<Q1: January, February, March Q2: April, May, June Q3: July, August, 
September Q4: October, November, December>>
 <\ex>

It produces:

Graphic

<book>

Book title: Identifies the title of a book.

Syntax

<book>book title<\book>

Or: 

<book|book title|

HelpTag formats book titles using an italic font.

Example

Either of the following two variations: 

Refer to <book>The Elements of Style<\book>
 for further details.

Or: 

Refer to <book|The Elements of Style|
 for further details.

produce:

Refer to The Elements of Style for further details.

<caution>

Caution notice: Specifies information that warns the user about a potential loss of data or hazard.

Syntax

<caution>
text of caution
 <\caution>

The default heading is "Caution". To specify a different heading, use the <head> tag as shown here: 

<caution><head>alternate heading
text of caution
<\caution>

The <\caution> end tag is required.

To specify that an icon be displayed with the caution, define a file entity at the top of your help volume as follows: 

<!entity CautionElementDefaultIconFile FILE  "filename">

Where filename is the name of the icon graphic. A sample caution icon named cauticon.pm is provided in the /usr/dt/dthelp/dthelptag/icons directory.

Example

Here is a caution message: 

<caution>
There is no Undo for this selection. Before performing this task, 
save any changes to your document.
 <\caution>

The markup produces this output:

Graphic

See Also

<chapter>

Chapter: Indicates the start of a new topic with a new title.

Syntax

<chapter id=id>title
topic text ...

An end tag is not required.

If the topic title is long, you may want to provide an alternate abbreviated title using <abbrev>. The short title is used in the Index and History dialog boxes. If the title contains a graphical element, create an <abbrev> with the title text only.

Example

Here are two markups that begin a new topic: 

<chapter>A Manual of Style
<chapter id=DesktopTools>Desktop Tools

See Also

<computer>

Computer literal: Displays text that represents computer input or output.

Syntax

<computer>text<\computer>

Or: 

"text"

The shorthand form uses two " (left apostrophes) and two "(right apostrophes).

Examples

See Also

<copyright>

Copyright notice: Identifies text for the copyright notice.

Syntax

<metainfo>
  <title>Title (always before copyright)
   <copyright>
   &copy; Copyright notice here ...

This element is optional within the <metainfo> section. If used, it must follow the <title> element.

The end tag is not required.

The predefined entity &copy; produces the copyright symbol (©).

Example

The following markup assigns a title to the help volume and provides copyright information: 

<metainfo>
<title>XYZ World Almanac
 <copyright>
 &copy; Copyright 1995 XYZ Company. All rights reserved.

It produces:

© Copyright 1995 XYZ Company. All rights reserved.

See Also

<dterm>

Defined term: Identifies a term and the term's definition within the glossary.

Syntax

<glossary>
  <dterm>first term
   definition of first term
    .
    .
    .
   <dterm>Nth term
   definition of Nth term

This element is used within the <glossary> section.

The name of the term follows the <dterm> tag and appears on the same line. The term's definition begins on the line following the <dterm> tag.

An end tag is not required.

Example

The following markup defines the first two words in a glossary: 

<glossary>
 <dterm>algorithm
 A mathematical rule or procedure for solving a problem.
 <dterm>click
 To press and release a mouse button.

See Also

<emph>

Emphasized text: Formats the text in a font that draws attention to the text.

Syntax

<emph>text<\emph>

Or: 

!!text!!

The shorthand form for the <emph> element is a set of double exclamation marks (!!) before and after the text.

If you use the <emph> start tag, the <\emph> end tag is required.

Example

Either of the following two markups: 

A thousand times <emph>no<\emph>.
A thousand times !!no!!.

produces:

A thousand times no.

See Also

<!entity>

Entity declaration: Assigns an entity name to a string of characters or to an external file.

Syntax

<!entity entityname "string">

Or: 

<!entity entityname FILE "filename">

An entity name can contain up to 64 letters, digits, and hyphens. Case is not significant in entity names, but is often used to improve readability for the author. The first character must be a letter. No space is permitted between the < ( left angle bracket), ! (exclamation mark), and entity in an <!entity> declaration.

Entity declarations must always precede any other markup or text in the help volume.

Where you want the defined entity to appear, insert an entity reference using this syntax: 

&entityname;

The entity reference consists of an & (ampersand), followed by the entity name (as defined in the entity declaration), and ends with a ; (semicolon).

Purposes for Entities

There are four common reasons for defining an entity:

Examples

See Also

<esc>

Escape: Causes text to be passed directly to the run-time help file without being interpreted by HelpTag. In a customized application for example, an author could embed Semantic Delivery Language (SDL) markup in the help source file. The <esc> element prevents the SDL markup from being read by the HelpTag parser. When the help volume is displayed with the Help Viewer, the authored SDL markup is processed.

Do not use the <esc> tag to escape individual HelpTag symbols or markup examples. To display HelpTag symbols, such as < (left angle bracket), \ (backslash), or & (ampersand), precede each symbol with an ampersand. Use the <vex> element to provide HelpTag markup examples in a help volume.

Syntax

<esc>text<\esc>

Or: 

<esc|text|
Note -

If the long form is used, the text cannot contain the three-character sequence <\x (the less-than symbol followed by a backslash followed by a letter). If the short form is used, the text cannot contain the |(vertical bar) character.

If you use the first syntax, the <\esc> end tag is required.

See Also

<ex>

Computer example: Shows computer text without changing the spacing or line breaks.

Syntax

<ex [nonumber | number] [smaller | smallest] [side | stack]>
example text here ...
 <\ex>

Where:

nonumber

(Default.) Omits the adding of line numbers to the beginning of each line.

number

Puts a line number at the beginning of each line.

smaller

Displays the example using smaller fonts.

smallest

Displays the example using smallest fonts. This makes long lines fit within a narrower width.

side

Applicable only when using an annotation within the example. Specifies the position of the annotation text in relation to the example text. The default position is side, which places the annotation to the right of the example text and on the same line as the first line of the example.

stack

Places the annotation below the example text.

Examples are printed in computer font, and they are indented from the left text margin.

If you include the number attribute, the line numbers of the example will be numbered. This is useful for referring to specific lines.

The following character pairs, which have special meanings in other contexts, are treated as ordinary text within an example: 

!!	double exclamation
--	double minus sign
 ++	double plus sign
 "	double quote

The <\ex> end tag is required.

Example

The following markup: 

<ex>
 Examples are printed in computer
 font. Line breaks are preserved.
 <\ex>

produces:

Graphic

See Also

<figure>

Figure: Inserts a graphical image.

Syntax

<figure entity=entity [id=id [nonumber | number=n]
[left |center | right] [cappos=[capleft | capcenter | capright]]
 [ghyperlink=id [glinktype=type] [gdescription=text ]]] >
 caption string
 <\figure>
entity=name

Specifies a file entity which identifies the file that contains the graphic image to be inserted.

id=name

Optional. Defines an ID name that can be used in cross-references to this figure.

nonumber

Optional. Suppresses the word "Figure" and the automatically generated figure number.

number=n

Optional. Used to override the automatically generated figure number.

left, center, or right

Specifies horizontal alignment of the image within the current page width.

cappos=position

Specifies the horizontal alignment of the caption using the values capleft, capcenter or capright. A caption is optional.

ghyperlink="id"

Optional. Specifies that the graphic portion of the figure be a hyperlink. Follows the same usage as the hyperlink attribute in the <link> element. References to this location would use the specified id identifier.

glinktype=type

Optional. Specifies the type of hyperlink. The default type is Jump. Other type values include JumpNewView, Definition, Man, Execute, and AppDefined. The ghyperlink parameter and id value are required when using parameter. Follows the same usage as the type attribute in the <link> element.

gdescription="text"

Optional. Provides a description of the hyperlink. The ghyperlink parameter and id value are required when using this parameter.

The <\figure> end tag is required.

To integrate an external graphics file into a help topic, you must have an entity declaration (<!entity entityname FILE "filename">) that associates the entity name with the graphic's file name.

Examples

See Also

<glossary>

Glossary: Starts the glossary section which contains the definitions for all the terms that are marked with the <term> element.

Syntax

<glossary>
<dterm>first term
 definition of first term can continue over multiple lines or paragraphs

 <dterm>second term
 definition of second term ...
    .
    .
    .

"Glossary" is automatically used as the heading for the glossary section.

A <dterm> element identifies each term and its definition.

All terms marked with <term> without the nogloss parameter are required to be in the glossary. If the term is not in the glossary, omitted terms are listed in the volume .err file, which is created when you run HelpTag.

An end tag for <glossary> is not required.

Example

Here is a simple glossary with two definitions: 

<glossary>
 <dterm>oxymoron
 A combination of contradictory words.
<dterm>veritable
 Being in fact the thing named. Authentic.

See Also

<graphic>

Inline graphic: Inserts a graphical element within a line of text.

Syntax

<graphic entity=name [id=id]>

Where:

name

An entity name that is defined in an entity declaration. The entity declaration associates the entity name with the name of the file that contains the graphic to be inserted.

id=name

Optional. Defines an ID name that can be used in cross-references to this figure.

The <graphic> element is similar to <figure> except that the <graphic> element is intended for embedding small graphics within text, whereas the <figure> element inserts figures between paragraphs.

Examples:

See Also

<head>

Heading: Indicates the title for elements that normally do not have a title (such as <abstract>, <paragraph>, <list>, or <otherfront>) or have a default title (such as <note>, <caution>, and <warning>).

Syntax

<element><head>title text

A heading starts with the first nonblank character after the <head> tag. The <head> tag can appear on the same line as the element to which a heading is being added, or on the following line.

The <head> element can be used with elements that expect a title, but it is not required in those cases.

Headings that are wider than the heading area are automatically wrapped onto successive lines. To force a specific line break, put a \ (backslash) where you want the line to break.

A heading ends at the end of the line in the source file unless the line ends with an & (ampersand). If a heading spans multiple lines in your source file, put an ampersand after all the lines except the last.

The <\head> end tag is not required.

Examples

See Also

<helpvolume>

Application help volume: This is the "root" structural element; it contains all the markup for an entire help volume.

Syntax

all entity declarations
    .
    .
    .
 <helpvolume>
    .
    .
    .
    all of your help is included here, either
    literally or using file entity references
    .
    .
    .
 <\helpvolume>

If you do not enter this tag, its presence is automatically assumed by the HelpTag software.

All entity declarations must appear before the <helpvolume> start tag.

See Also

<hometopic>

"Home" or top-level help topic: Identifies the start of the top-level help topic.

Syntax

<hometopic>heading
 topic text begins here ...

There is only one home topic for a help volume. It comes after the meta information (<metainfo>) and before the first <chapter> or <s1>.

The <hometopic> element does not support an author-defined ID. The HelpTag software assigns the predefined ID _hometopic.

To create a hyperlink to the home topic, use this syntax:

<link hyperlink= "_hometopic">...<\link>.

Example

 <hometopic>Welcome to Online Help
 This is the home topic for the online help ...
 
 <chapter>First Subtopic
 This is the first subtopic ...

 <chapter>Second Subtopic
 This is the second subtopic ...
    .
    .
    .

See Also

<idx>

Index entry: Defines an entry to appear in the help volume index.

Syntax

<idx>text<\idx>

Or: 

<idx|text|

Or: 

<idx>text<sort>sort key<\idx>

Where:

text

The text string that appears in the keyword index.

sort key

An optional text string used when sorting the index. The sort key influences where the text appears in the keyword index. The sort key string does not appear in the keyword index.

Choosing the Index button in a general help dialog box displays a help index. Adding index entries to help topics is important because a user can search the index for a word or phrase to find help on a subject.

Either the <idx> start and end tags or the short form can be used.

The <sort> element changes the sort order for an index entry. Specifically, the <sort> element is used within the <idx> element to request that the keyword appear at the location indicated by the sort key string. No end tag for <sort> is required.

Examples

<image>

As-is image: Shows text with the same line breaks as the source text.

Syntax

<image [indent][id=id][gentity=graphic-ent [gposition=pos] [ghyperlink=gid [glinktype=type]]]>
text
 <\image>

Where:

indent

Optional. Specifies that the paragraph be indented 6 spaces from the current left margin.

id=id

Optional. Defines an ID name that can be used in cross-references to this location.

gentity=graphic-ent

Optional. The name of a graphic entity around which the text is to be wrapped. The gentity parameter and graphic-ent value are required if the gposition, ghyperlink, or glinktype parameter is used.

gposition=pos

Optional. Either left or right to indicate whether the optional graphic is to be left-justified or right-justified.

ghyperlink=gid

Optional. Specifies that the graphic be a hyperlink and specifies the destination of the hyperlink. The ghyperlink parameter and gid value are required if the glinktype parameter is used. Follows the same usage as the hyperlink attribute in the <link> element. (The id value, not the gid value, would be used to reference the location of the image text.)

glinktype=type

Optional. Specifies the type of hyperlink. The default type is Jump. Other type values include JumpNewView, Definition, Man, Execute, and AppDefined. Follows the same usage as the type attribute in the <link> element.

text

The text of the paragraph that wraps around the graphic.

Text between the <image> and <\image> tags is shown with the same spacing, indentation, and line breaks that appear in the actual text. No justification, word wrapping, or removal of empty lines is done. However, a proportional font is used, so columns of text that are lined up on a computer screen may not line up in the displayed help information. If the displayed text is too wide to fit within the display area, a horizontal scroll bar automatically appears.

All inline text elements and special characters are recognized.

An optional <head> can be used with <image>. If you intend to create a cross-reference to the element using <xref>, the <head> tag is required.

The indent parameter causes the displayed text to be indented from the left margin.

Either the start and end tags (<image> and <\image>) or the short form (<image|...|) can be used.

See Also

<item>

List item: Identifies an item in a list.

Syntax

<list [id=id]>
 * List item
  * List item
 <\list>

Or: 

<list order>
   <item id=name1>List item
   <item id=name2>List item
   <item id=name3>List item
    .
    .
    .
 <\list>

The shorthand form, which is an * (asterisk), is almost always used.

The long form allows you to cross-reference an item in a list. You can only cross-reference items in an ordered (numbered) list. The automatically assigned item numbers are used in the cross-reference text (which HelpTag substitutes for the <xref> element). Unlike a number, a bullet character is not a meaningful substitution for the cross-reference text.

See Also

<keycap>

Keyboard keys: Represents keyboard keys.

Syntax

<keycap>keycap characters<\keycap>

Or: 

[[keycap characters]]

The shorthand form is [[ (two left square brackets) and ]] (two right square brackets) before and after the keycap characters.

Entity references for special symbol characters, such as arrows, can be used. Multiline keycaps are not available.

Example

The following markup:

Press [[Control]] + [[Home]] to go to the beginning of your document.

produces this output:

Graphic

See Also

<lablist>

Labeled list: Starts a labeled list in which the labels appear in the left column and the items (to which the labels refer) appear in the right column.

Syntax

<lablist [loose | tight][wrap | nowrap]>
[ <labheads>  \Heading 1 \  Heading 2 ]
 \label\ text for the first item
 \label\ text for the second item
    .
    .
    .
 <\lablist>

Where:

loose

Default. Requests a vertical gap between the items in the list.

tight

Requests no extra vertical space between items in the list.

wrap

Default. Allows long labels to wrap to multiple lines.

nowrap

Prevents labels from wrapping to multiple lines.

Backslashes (\) indicate the start and end of a label; leading and trailing spaces are ignored. Long labels are broken into multiple lines unless nowrap is used. The predefined character entity, (&sigspace;), can be used to insert a nonbreaking space into a label.

The text of the labeled item follows the second backslash, either on the same line or on the following line. The end of the item is indicated by one of the following:

If a labeled item consists of more than one paragraph, leave an empty line between the paragraphs. The end of the labeled list is indicated by the required <\lablist> end tag.

The optional column headings, one for each column, immediately follow the <labheads> tag (on the same line). The column headings are separated from one another by the \ (backslash). The <\labheads> end tag is not required. However, the <lablist> end tag is required.

Example

The following markup: 

<lablist tight>
 <labheads>  \ Unit \ Meaning
 	\in\ inches
 	\mm\ millimeters
 	\cm\ centimeters
 <\lablist>

produces this output:

Unit

Meaning

in

inches

mm

millimeters

cm

centimeters

The following markup allows long labels to break into multiple lines. 

<lablist>
 \Creating Your System Password:\
 To log into your computer, you must enter a password.

 \Viewing the Message of the Day:\
 To view the message of the day when you log into your computer, edit 
your startup configuration file.

 \Setting the System Time and Date:\
 To set the date enter the day, month, and year in the format dd-mm-
yy. To set the time, use the format hh-mm-ss.
 <\lablist>

It produces the following output:

Graphic

Adding the nowrap parameter in the same markup produces this output:

Graphic

See Also

<lineno>

Line number: Provides a cross-reference to a specified line in an example.

Syntax

<ex number>
 example text <lineno id=name>
 .
 .
 .
 <\ex>

This element is used only in a numbered example. Enter the <lineno> tag at the end of the line you want to refer to. The id parameter assigns an ID that can be used to create a cross-reference to the line number.

Example

This markup creates a numbered example that includes a cross-reference to the third line.

<ex number>
 Enter Daily Account Total
 Run Invoice Summary Report
 Go to Monthly Ledger <lineno id=ledger>
 Run Daily Update
 <\ex>
 .
 .
 .
 To run closing reports, return to <xref ledger> and run the Past Due Accounts Report.

The line number where the ID is located is substituted for the <xref ledger> cross-reference. It produces this sentence:

To run closing reports, return to 3 and run the Past Due Accounts Report.

The end tag is not required for <lineno>.

See Also

<link>

Hyperlink: Delimits text or an inline <graphic> to be used as a hyperlink.

Syntax

<link hyperlink [type] ["description"]>text<\link>

Or: 

<link hyperlink= "hyperlink" [type=type] [description= "description"]>

The hyperlink attribute, which is required, is a value that identifies the destination or the behavior for the link. For a standard "jump" link, hyperlink is the ID of the element you want to jump to.

The type parameter can have the following values:

Jump

Default. Jumps to the topic that contains the ID hyperlink.

JumpNewView

JumpNewViewJumps to the topic that contains the ID hyperlink, but requests that the hosting application display the topic in a new window.

Definition

Displays, in a temporary pop-up window, the topic that contains the ID hyperlink.

Execute

Executes the hyperlink string as a command.

Man

Displays a man page using the hyperlink string as the parameter to the man command.

AppDefined

Sends the hyperlink string to the hosting application for special processing.

The text between the start and end tag becomes the "hot spot" that the user will choose to invoke the link. Any word or phrase used as a hyperlink is underlined when displayed. Capitalization is not significant for the hyperlink and type values.

A hyperlink that executes a command is called an execution link. The command to be executed can be included in the <link> command or defined as an execution alias, which is a type of resource. For information about using execution links, see "Execution Link Control".

Notes

Examples

See Also

<list>

List: Starts a list consisting of items that are optionally marked with bullets or automatically generated numbers or letters.

Syntax

<list [bullet | order | plain] [loose | tight][continue]
[lalpha |ualpha | lroman | uroman | arabic] >

   * first item
   * second item
    .
    .
    .
 <\list>

Where:

bullet

Default. Displays a bullet before each item.

order

Displays a number in front of each item. The numbers are automatically generated and begin with the number one. The default is Arabic numbers. Ordered lists can also use alphabetical sequences or Roman numerals.

plain

Does not put a bullet, number, or letter in front of each item.

continue

Requests that the numbering of items continue from the previous list.

loose

Default. Requests a vertical gap between the items.

tight

Requests no extra vertical spacing between the items.

lalpha

Lowercase alphabet.

ualpha

Uppercase alphabet.

lroman

Lowercase Roman numeral.

uroman

Uppercase Roman numeral.

arabic

Default for order list type.

Each item must start on a new line preceded by either an asterisk (*) or the <item> tag. The asterisk is the shorthand form of the <item> tag. Spaces and tabs may appear on either side of the asterisk. Items may continue over multiple lines. An item can consist of multiple paragraphs, in which case an empty line must separate the paragraphs. The nesting of lists is allowed, so a list can appear within a list.

The <\list> end tag is required.

Examples

The following markup examples: 

<list>
 * chocolate
 * raspberry
 * vanilla
 <\list> 
 <list plain tight>
 * Word Processing
 * Graphics
 * Printing
 <\list> 
 <list order lalpha>
 * Word Processing
 * Graphics
 * Printing
 <\list>

produce:

Graphic

See Also

<location>

Location: Defines an ID as referring to the location of the <location> element. The <location> element enables a portion of a topic to serve as a destination for a hyperlink using the <link> or <xref> element.

Syntax

<location id=id>text<\location>

Or: 

<location id=id|text|

Where:

id

The identifier for the current location, which can be used as a destination for hyperlinks.

text

The block of text where you want to assign the ID.

The <location> element is not needed at locations where there is already an element (such as <hometopic> or <figure>) that has a built-in ID or accommodates an author-defined id parameter.

Cross-references created with the <xref> element substitute the text between the <location> start and end tag for the <xref> element.

Examples

The following markup names a location and elsewhere creates a hyperlink to the location. 

<s1 id=ConfigTopic> Configuration
 	...
 <location id=ConfigTopicBody>some text<\location>
     ...
 <s1 id=UseTopic> Usage
     ...
 See <link ConfigTopicBody>Configuration<\link>
 for additional information.

The advantage of linking to the ID in the <location> element is that the help window automatically scrolls to the point where the <location> tag is entered. In contrast, a link to the topic's ID ("ConfigTopic" in this case), always goes to the top of the topic.

The <location> element can also reference a position in your file using the predefined entity, (&empty;), as a placeholder.

Adding this markup at a key position in your file, allows you to create a link to that specific location:

paragraph text
 .
 .
 .
 <location id=pointA>&empty;<\location>
 .
 .
 .

See Also

<memo>

Memo: Identifies a writer's comments or questions, which do not appear in the final help volume.

Syntax

<memo>
 memo text
 <\memo>

Or: 

<memo|memo text|

Memo text is printed in drafts of your help volume if you specify memo in the helptag.opt file. Otherwise, memo text is not printed, especially when you create the final version of the help volume. Memo text, when it appears, is printed in a different typeface. Do not use markup within memo text.

Examples

Here is an example of a memo: 

<memo>
 Patti: We need a drawing to illustrate this.
 <\memo>

The following markup uses the short form of the <memo> element: 

<memo|Mike: Please explain how the following
 command is supposed to work|

See Also

<metainfo>

Meta information: Starts the meta information section, which contains information about the information contained in the help volume. Meta information includes the volume's title and a copyright notice.

Syntax

<helpvolume>
   	<metainfo>
     		<title>volume title
				<copyright>      &copy; Copyright XYZ Company 1995...  
				<abstract>      brief description of help volume  
   		.
     	.
     	.
      <\metainfo>
  <hometopic> ...
     .
     .
     .

The meta information section is optional, but it is typically included in a help volume. Although optional, the title, copyright, and abstract subsections provide useful information about your help volume and are recommended.

If you include any of these subsections, the meta information section is required.

The <otherfront> element can be used to define subsections other than the predefined title, copyright, and abstract subsections.

The <\metainfo> end tag is required.

Example

<metainfo>
 <title>Inventory Tracking Software

 <copyright>
 &copy; Copyright 1995 XYZ Company.
 All rights reserved.

 <abstract>
 Explains how to use the Inventory Tracking Software

 <\metainfo>

See Also

<newline>

New line: Starts a new line within a paragraph or annotation.

Syntax

text<newline>text on next line

Text that follows the <newline> element begins on a new line.

Example

The following markup ensures that the path name begins on a new line: 

Put your files for the manual in the special directory
 <newline>/projects/userguide/draftdoc.

See Also

<note>

Note: Creates a special format which attracts attention to text that makes an important point.

Syntax

<note>
 text of note
 <\note>

The default heading for the note is "Note". To specify a different heading, use the <head> element.

If you want an icon to appear with the note, define NoteElementDefaultIconFile in an <!entity ...> declaration.

The default note icon named note icon.pm is located in the /usr/dt/dthelp/dthelptag/icons directory.

The <\note> end tag is required.

Examples

See Also

<otherfront>

Other meta information (front matter): Used for meta information (front matter) that does not fit within one of the predefined categories such as title, copyright, and abstract. The <otherfront> element can also be used to create a nonhierarchical topic. Because a nonhierarchical topic does not appear in the topic tree, a hyperlink must be added to display the topic. The <link> or <xref> element can be used to create a hyperlink to the <otherfront> element.

Syntax

<metainfo>
    .
    .
    .
 <otherfront [id=id]><head>title of section
   text

If a heading is needed, use the <head> element.

<otherfront> must follow all other subsections of <metainfo>.

See Also

<otherhead>

Other heading: Creates a subheading within a topic.

Syntax

<otherhead>heading

Headings may occur anywhere within the text of a topic. The <otherhead> element does not appear in the list of help topics displayed in the topic tree.

The <\otherhead> end tag is not required.

Example

Here is an example in which <otherhead> elements identify two subsections within an <s1> topic: 

<s1>Integration Tasks
There are two main tasks required to integrate your application.

 <otherhead> Editing Configuration Files
 Configuration files identify the colors, icons, and actions used by an application.
  <otherhead> Archiving Configuration Files
 .
 .
 .

This markup produces:

Graphic

See Also

<p>

New paragraph: Starts a paragraph that is indented or wrapped around a graphic.

Syntax

<p [indent] [gentity=graphic-ent [gposition=pos]
 [ghyperlink=gid [glinktype=type]]] [id=id] >text...

Where:

indent

Optional. Specifies that the paragraph be indented 6 spaces from the current left margin.

gentity=graphic-ent

Optional. The name of a graphic entity around which the paragraph is to be wrapped. The gentity parameter and graphic-ent value are required if the gposition, ghyperlink, or glinktype parameter is used.

gposition=pos

Optional. Either left or right to indicate whether the optional graphic is to be left-justified or right-justified.

ghyperlink=gid

Optional. Specifies that the graphic be a hyperlink and specifies the destination of the hyperlink. The ghyperlink parameter and gid value are required if the glinktype parameter is used. Follows the same usage as the hyperlink attribute in the <link> element. (The id value, not the gid value, would be used to reference this paragraph's location.)

glinktype=type

Optional. Specifies the type of hyperlink. The default type is Jump. Other type values include JumpNewView, Definition, Man, Execute, and AppDefined. Follows the same usage as the type attribute in the <link> element.

id=id

Optional. Defines an ID name that can be used in cross-references to this location.

text

The text of the paragraph that wraps around the graphic.

Use the <p> element if you need to indent a paragraph, wrap the paragraph around a graphic, or use a run-in head style paragraph.

An optional <head> can be used with <p>. If you intend to create a cross-reference to the element using <xref>, a <head> tag is required. Use the <head> and <\head> tags to delimit the heading text.

A <\p> end tag is not required.

Examples

See Also

<procedure>

Procedure: Starts a section within a topic.

Syntax

<procedure>heading
procedure text...

Procedures may occur anywhere within the text of a topic. They are not included in the list of topics displayed in the topic tree.

The end tag is not needed.

Example

This markup:

<procedure> Entering Special Characters
To enter Greek or mathematical characters in your document, use the Symbols font.

produces this output:

Graphic

See Also

<quote>

Quote: Puts text within double quotation marks using open and close quote characters.

Syntax

<quote>text<\quote>

Or: 

"text"

Use the start and end tags (<quote>...<\quote>) or a pair of double quotation marks ("...") to delimit the text.

Example

The following markup: 

... referred to in this manual as "the Standard" ...

produces:

...referred to in this manual as "the Standard"...

See Also

<rsect>

Reference section: Identifies an entry in the reference section.

Syntax

<rsect [id=id]>reference section heading

   .
    .
    .
 <rsub>reference subsection heading

The <rsect> element can be used to identify a reference section. It is useful to identify reference material that is presented in a series of similar sections. For example, each reference section could describe one software command.

An <rsect> consists of:

Each <rsect> section can have multiple <rsub> sections. Each <rsub> element must have a heading. A cross-reference to a reference subsection is not allowed.

The topic tree includes <rsect> headings but excludes <rsub> headings.

End tags (for either <rsect> or <rsub>) are not required.

Example

The following markup illustrates the use of this element: 

<rsect>purge
    .
    .
    .
 <rsub>Syntax
 purge filename

 <rsub>Example
 purge file01
 <rsub>Related Commands
 delete

See Also

<s1>...<s9>

Subsection (<s1>, <s2>, ... , <s9>): Starts a topic in the hierarchy.

Syntax

<sn [id=name]>heading
topic text...

Where n is the level number (1, 2,..., or 9).

Topics entered with <chapter> can have subtopics entered with <s1>, <s1> topics can have <s2> subtopics, and so on. You cannot skip a level.

The heading for a section can be on the same line as the <sn> tag or on the next line; a heading is required. Text within a section is optional.

The end tag is usually omitted, but in some instances the end tag may be necessary. For example, when a section is followed by an <rsect> element that is on the same level, an end tag for the section is required. Without the end tag, the <rsect> element would be considered a subsection of the section preceding it.

Examples

See Also

<sub>

Subscript: Creates a subscript character.

Syntax

<sub>character to subscript<\sub>

Or: 

__text__

The shorthand form uses two _ _ (underscore) characters before and after the characters to subscript.

Example

The following markup:

<p>The chemical element H<sub>2<\sub>O contains
two hydrogen molecules.

produces the following output:

The chemical element H2O contains two hydrogen molecules.

See Also

<super>

Superscript: Creates a superscript character.

Syntax

<super>character to superscript<\super>

Or: 

^^text^^

The shorthand form uses two ^^ (caret) characters before and after the characters to superscript.

Example

The following markup:

<p>The answer to the problem is 2<super>8<\super>.

produces this output:

The answer to the problem is 2 8 .

See Also

<term>

Glossary term: Writes a newly introduced term in a special font and establishes a hyperlink to its definition in the glossary.

Syntax

<term baseform [gloss | nogloss]>text<\term>

Or: 

<term baseform [gloss | nogloss]|text|

Or: 

++text++

Where:

baseform

The form of the term as it appears in the glossary if it is not the same as used in the text. This difference can occur, for example, when the term is used in the text in its plural form but appears in the glossary in its singular form. If the term includes spaces or special characters, put the baseform string in quotes.

gloss

Default. Requests that HelpTag verify that the term is in the glossary.

nogloss

Omits the term from the glossary; however, the term is formatted in a bold font.

The shorthand form uses two ++ (plus signs) before and after the glossary term.

Note -

If your help volume does not include a glossary, use the nogloss parameter.

When HelpTag processes the help volume, warning messages are issued to indicate glossary terms that were not marked with the nogloss parameter and do not have corresponding definitions in the glossary.

Tagging a term with the <term> element automatically creates a hyperlink to the glossary. If there is no glossary, the link will not work.

A <\term> end tag is required if the long form is used.

Example

The following markup puts "structural elements" in a special font (boldface with a dotted underscore) to indicate it is a glossary term and creates a hyperlink to the glossary. Because the glossary entry contains a space, the text is in quotes. The plural form appears in the text. HelpTag checks for the singular form in the glossary and reports an error if it is not found.

SGML views a document as a hierarchy
of <term "structural element"|structural elements|.

See Also

<title>

Help volume title: Specifies the title of the help volume.

Syntax

<metainfo>
<title>help volume title

The <title> element is an optional element in the <metainfo> (meta information) section. It is recommended, however, because the title provides the volume name displayed in the help dialog boxes.

The <title> follows immediately after the <metainfo> tag. Because the title of the volume may be displayed by other applications (information viewers, for example) that may not be able to format the title, you should use only plain text within the title.

The <\title> end tag is not required.

Example

Here is a sample volume title: 

<metainfo>
<title>The Super Hyperlink User's Guide

See Also

<user>

User's response: Indicates the user's response to a computer prompt.

Syntax

<user>response<\user>

Or: 

<user|response|

This element is used to distinguish user input from computer output in a computer dialog. It is typically used within the <ex> element, where spaces and line breaks between the <user> start tag and the <\user> end tag are significant.

If used within a paragraph, <user> text must not break across lines in your source file.

The <user> end tag is required if the long form is used.

Example

The following markup produces two different fonts, one to indicate what the computer displays and another to indicate what the user types: 

<ex>
 Do you wish to continue? (Yes or No) <user>Yes<\user>
 <\ex>

The output looks like this:

Do you wish to continue? (Yes or No) Yes

See Also

<var>

Variable: Indicates a user-supplied variable in a command.

Syntax

<var>
text
 <\var>

Or: 

%%text%%

The <\var> end tag is required if the long form is used.

The shorthand form uses two %% (percent signs) before and after the text.

Example

These markups: 

INPUT <var>filename<\var>

Or: 

INPUT %%filename%%

produce:

INPUT filename

See Also

<vex>

Verbatim example: Indicates a verbatim example in which HelpTag elements are not interpreted as elements.

Syntax

<vex [number | nonumber][smaller | smallest]> text<\vex>

Where:

nonumber

Default. Omits line numbers.

number

Puts a line number at the beginning of each line.

smaller or smallest

Displays the example using smaller fonts.This makes long lines fit within a narrower width.

Within a verbatim example, no HelpTag elements are recognized except <\, which is assumed to be an end tag.

Use this element when you need to display markup tags or other characters that could otherwise be interpreted as markup. Line breaks and spacing are preserved as they appear in the source file.

The smaller and smallest fonts enable wide examples to fit within the margins.

Example

The following markup: 

<vex>
<!ELEMENT copyright    - O (text)
          -memo | location | idx) >
 <\vex>

produces this output:

Graphic

See Also

<warning>

Warning: Calls the user's attention to a situation that could be dangerous to the user.

Syntax

<warning>
text
<\warning>

The text of the warning message is printed in boldface.

The default heading for the warning is "Warning". To specify a different heading, use the <head> element.

To display a graphic with the warning, define WarningElementDefaultIconFile in an <!entity> declaration. The default warning icon named warnicon.pm is located in the /usr/dt/dthelp/dthelptag/icons directory.

The <\warning> end tag is required.

Example

See Also

<xref>

Cross-reference: Inserts text that identifies another location in the help volume and creates a hyperlink to that location.

Syntax

<xref id>

Where:

id is the identifier of the topic or location that is being cross-referenced.

Cross-references are translated into chapter or section titles, heads, figure captions, list items, or line numbers. The cross-reference text becomes a hyperlink that, when chosen by a user, jumps to the cross-referenced location.

To create a cross-reference, an id must be defined in the element that you intend to refer to. You use the id of the destination element as the id parameter in the <xref> tag. This creates a hyperlink from the <xref> element to the destination element. The id must be spelled exactly the same. Capitalization, however, is not significant.

The id parameter can appear with: 

<chapter>
<s1>, <s2>,...<s9>
 <otherfront>
 <p>
 <image>
 <item>
 <figure>
 <location>
 <rsect>

A cross-reference to an id that contains an underscore (such as "_abstract" or "_hometopic") is not allowed. Instead, use the <link> element.

Examples

To refer a reader to a chapter for more information, use the chapter's id to create a reference. For instance, to refer to a chapter titled "Window Management" whose id is windowmgr, you would write, "Refer to <xref windowmgr> for details."

In your online help volume, the result would be: "Refer to Window Management for details." The chapter title, "Window Management", is substituted for the id and is a hyperlink.

The following markup assigns an id named "analyzer" to a section element:

<s1 id=analyzer>Logic Analyzers

Here is markup that contains a cross-reference to this topic: 

The DX16500A logic analysis system, described in
 <xref analyzer>, can be configured to a user's needs.

After processing, the <xref> element would be replaced by "Logic Analyzers" as shown here:

Graphic

The text "Logic Analyzers" is a hyperlink that, when chosen by a user, jumps to the cross-referenced help topic.

See Also

Chapter 6 Summary of Special Character Entities

This chapter provides a list of special characters that can be used when writing a help topic.

Special Character Tables

The following special characters can be inserted into text by typing the associated entity name in the position where the special character is to appear.

To use any of the entities whose description is marked with an * (asterisk), you must use the helpchar.ent file (see "Including Special Characters").

Table 6-1 Typographical Symbols

Symbol  

Entity Name 

Description 

©

&copy;

Copyright symbol  

\256  

&reg;

Registered symbol 

(TM)  

&tm;

Trademark symbol 

-

&endash;

En dash (short dash) 

--

&emdash;

Em dash (long dash) 

o 

&bullet;

* Bullet 

 

&cr;

Carriage return 

...

&ellipsis;

Ellipsis (horizontal) 

....

&pellipsis;

Ellipsis (end-of-sentence) 

&vellipsis;

Vertical ellipsis 

'

&squote;

Single quote 

"

&dquote;

Double quote 

&vblank;

Vertical blank 

( )

&empty;

Empty (no text) 

( ) 

&sigspace;

Significant space 

-  

&sigdash;

Non line-breaking hyphen 

§

&S;

* Section 

&P;

* Paragraph 

Table 6-2 Greek Characters

Symbol  

Entity Name 

Description 

Lowercase Greek Letters

 

N/A  

&alpha;

* Lowercase Greek Alpha 

N/A 

&beta;

* Lowercase Greek Beta 

N/A 

&chi;

* Lowercase Greek Chi 

N/A 

&delta;

* Lowercase Greek Delta 

N/A 

&varepsilon;

* Alternate lowercase Greek Epsilon 

N/A 

&phi;

* Lowercase Greek Phi 

N/A 

&varphi;

* Open lowercase Greek Phi 

N/A 

&gamma;

* Lowercase Greek Gamma 

N/A 

&eta;

* Lowercase Greek Eta 

N/A 

&iota;

* Lowercase Greek Iota 

N/A 

&kappa;

* Lowercase Greek Kappa 

N/A 

&lambda;

* owercase Greek Lambda 

N/A 

&mu;

* Lowercase Greek Mu 

N/A 

&nu;

* Lowercase Greek Nu 

N/A 

&pi;

* Lowercase Greek Pi 

N/A 

&varpi;

* Alternate lowercase Greek Pi (or Omega) 

N/A 

&theta;

* Lowercase Greek Theta  

N/A 

&vartheta;

* Open lowercase Greek Theta 

N/A 

&rho;

* Lowercase Greek Rho 

N/A 

N/A

* Lowercase Greek Sigma 

N/A 

&tsigma;

* Lowercase Greek Sigma1 

N/A 

&tau;

* Lowercase Greek Tau 

N/A 

&upsilon;

* Lowercase Greek Upsilon 

N/A 

&omega;

* Lowercase Greek Omega 

N/A 

&xi;

* Lowercase Greek Xi  

N/A 

&psi;

* Lowercase Greek Psi 

N/A 

&zeta;

* Lowercase Greek Zeta  

Uppercase Greek Letters

 

N/A 

&Udelta;

* Uppercase Greek Delta 

N/A 

&Uphi;

* Uppercase Greek Phi 

N/A 

&Ugamma;

* Uppercase Greek Gamma 

N/A 

&Ulambda;

* Uppercase Greek Lambda 

N/A 

&Upi;

* Uppercase Greek Pi 

N/A 

&Utheta;

* Uppercase Greek Theta 

N/A 

&Usigma;

* Uppercase Greek Sigma 

N/A 

&Uupsilon;

* Uppercase Greek Upsilon 

N/A 

&Uomega;

* Uppercase Greek Omega 

N/A 

&Uxi;

* Uppercase Greek Xi 

N/A 

&Upsi;

* Uppercase Greek Psi  

Table 6-3 Math Symbols

Symbol  

Entity Name  

Description  

Basic Math Symbols 

 

-  

&minus;

Minus 

+-  

&pm;

Plus over minus 

/

&div;

Divide 

x  

&times;

Multiply 

<=  

&leq;

Less than or equal to 

>=  

&geq;

Greater than or equal to 

[ne ]  

&neq;

Not equal to 

Advanced Math Symbols

 

2

&squared;

* Squared 

3

&cubed;

* Cubed 

1/4  

&one-fourth;

* One-fourth 

1/2 

&one-half;

* One-half 

3/4 

&three-fourths;

* Three-fourths 

[infin ]  

&infty;

* Infinity 

N/A 

&equiv;

* Exactly equals 

[ne ] 

&not-eq;

* Not equal to 

[ap ] 

&approx;

* Approximate sign 

ÿ 

&neg;

* Not 

« 

&cap;

* Cap (Set intersection) 

» 

&cup;

* Cup (Set union) 

v 

&vee;

* Vee (Logical OR) 

^ 

&wedge;

* Wedge (Logical AND) 

N/A 

&in;

* In 

N/A 

&subset;

* Proper subset 

N/A 

&subseteq;

* Subset 

N/A 

&supset;

* Proper superset 

N/A 

&supseteq;

* Superset 

[forall] 

&forall;

* For all (Universal symbol) 

[exist ] 

&exists;

* There exists (Existential symbol) 

N/A 

&not-in;

Not element 

N/A 

&function;

* Function symbol (or florin sign) 

N/A 

&angle;

* Angle 

[cong ] 

&cong;

* Congruent 

N/A 

&propto;

* Proportional to 

N/A 

&perp;

* Perpendicular to 

· 

&cdot;

* Centered dot 

N/A 

&oplus;

* Plus in circle 

N/A 

&otimes;

* Times in circle 

ø  

&oslash;

* Slash in circle (Empty set) 

N/A 

&partial;

* Partial differential delta  

N/A 

&sum;

* Summation (Uppercase Greek Sigma) 

x  

&prod;

* Product (Uppercase Greek Pi)  

Table 6-4 Arrow Symbols

Symbol  

Entity Name 

Description 

<-

&leftarrow;

* Left arrow 

N/A 

&rightarrow;

* Right arrow 

N/A 

&uparrow;

* Up arrow 

N/A 

&downarrow;

* Down arrow 

N/A 

&leftrightarrow;

* Left/right arrow 

<=  

&bigleftarrow;

* Big left arrow 

=> 

&bigrightarrow;

* Big right arrow 

N/A 

&biguparrow;

* Big up arrow 

N/A 

&bigdownarrow;

* Big down arrow 

N/A 

&bigleftrightarrow;

* Big left/right arrow  

Table 6-5 Miscellaneous Symbols

Symbol  

Entity Name 

Description 

Current Date and Time 

 

//

&date;

Today's date (when HelpTag is run) 

09:50

&time;

Current time (when HelpTag is run)  

Currency Symbols 

 

¢ 

&cents;

Cents 

£ 

&sterling;

Sterling 

¥ 

&yen;

Yen 

Units 

 

o  

&deg;

Degrees 

N/A 

&minutes;

Minutes, prime, or feet 

" 

&seconds;

Seconds, double prime, or inches 

AM

&a.m.;

AM 

PM

&p.m.;

PM 

Card Suits

 

[loz ]  

&diamondsuit;

* Diamond suit 

N/A 

&heartsuit;

* Heart suit 

N/A 

&spadesuit;

* Spade suit 

N/A 

&clubsuit;

* Club suit  

Other Symbols 

 

[loz ]  

&diamond;

* Diamond 

¿  

&invert-question;

Inverted question mark 

¡  

&invert exclamation;

Inverted exclamation mark 

¤  

&currency;

Currency 

N/A 

&therefore;

Therefore 

«  

&openanglequote;

Open angle quotes 

»  

&closeanglequote;

Close angle quotes 

N/A 

&aleph;

* Hebrew Aleph 

[nabla ] 

&nabla;

* Nabla (Inverted uppercase Greek Delta) 

N/A 

&surd;

Radical segment, diagonal 

N/A 

&wp;

* Weierstraussain symbol 

N/A 

&Re;

* Fraktur R 

N/A 

&im;

* Fraktur I 

Chapter 7 Command Summary

This chapter summarizes the command-line options available when the help commands are run manually in a terminal window.

Help System Commands

Desktop actions and data types provided by the Help System enable you to compile and view run-time help files by clicking a help file icon or choosing a menu item. However, if you want to select particular command options, you must enter the command manually in a terminal window or create new actions.

Help actions and data types are defined in two files, dthelp.dt and dthelptag.dt, located in the /usr/dt/appconfig/types/lang directory.

The commands summarized here are:

dthelptag

Compiles HelpTag source files into a run-time file.

dthelpview

Displays a help volume, help topic, text file, or man page.

dthelpgen

Collects help family files into a new help volume, browser.hv, which contains an entry for each family file.

Processing HelpTag Files (dthelptag)

The HelpTag software, invoked with the dthelptag command, compiles your HelpTag source files into a run-time help file. You run dthelptag in the directory where your volume.htg file is located.

Command Syntax

dthelptag  [command-options]  volume  [parser-options]

Where command-options are options entered before the volume name and parser-options are options entered after the volume name.

Command Options

-clean

Removes all files generated from any previous run of HelpTag for the given volume.

-shortnames

Causes the names of all generated files to be limited to a maximum of eight characters for the base name and three characters for the extension. This allows run-time help files to be moved to systems where longer names may not be supported.

-verbose

Displays the progress of the dthelptag command and displays any parser errors that occur. Parser errors are also saved in a file named volume.err.

-formal

Uses the formal parser to interpret help files tagged with SGML-compliant markup. If not specified, dthelptag assumes the input file contains shorthand markup.

Because there are two types of markup--shorthand and formal--it is recommended to distinguish the types by using a file extension. Use.htg for shorthand markup and use.ctg for formal markup.

Parser Options

Parser options, which are entered after the volume name, are passed directly to the parser, which is the part of the HelpTag software that converts your marked-up files into a run-time file.

These options can be applied in the following ways:

Options entered on the command line override those options that may have also been set using a different method.

onerror

Specifies whether the dthelptag command should continue if a parser error is encountered. The default is onerror=stop, which causes the command to stop even if one parser error is encountered. If you specify onerror=go, processing will continue, but the created run-time help file may not work properly.

charset

Specifies which character set was used to author the text files. The correct character set name is needed to ensure that the help topics are displayed in the proper font. The default is charset=ISO-8859-1. You can also specify a character set within your help volume by declaring an entity named LanguageElementDefaultCharset. The /usr/dt/dthelp/dthelptag/helplang.ent file includes this entity declaration. See Chapter 14, Native Language Support, for a list of supported character sets.

search

Adds another directory to the list of directories that are searched to find referenced file entities. To specify multiple directories, use multiple search=directory options. If no search options are used, only the current directory is searched.

clearsearch

Ignores the list of search directories. This option is useful in the command line to override search options specified in the helptag.opt file.

memo

Causes author's memos (which are entered using the <memo> element) to be included. The default is nomemo, which causes HelpTag to ignore memos.

nomemo

Causes HelpTag to ignore author's memos (which are entered with the <memo> element). This is the default.

See Also

Displaying Help Topics (dthelpview)

The dthelpview command can be used to display a help volume, individual help topic, text file, or man page.

Command Syntax

The various ways to invoke Helpview are:

Where:

-helpVolume volume

Specifies the name of the volume.sdl file you want to view. A path name is not required unless the volume is not in the current directory and the volume has not been registered.

-locationId id

Specifies an ID. dthelpview displays the topic that contains id. If you do not specify an ID, Helpview uses _hometopic by default.

-man

Displays a dialog that prompts for a man page to view, then displays the requested man page.

-manPage man

Specifies that a particular man page be displayed.

-file filename

Specifies that a particular text file be displayed.

The default volume and id can be set in dthelpview's app-defaults file, /usr/dt/app-defaults/C/Dthelpview.

See Also

Generating a Browser Help Volume (dthelpgen)

The dthelpgen utility creates a special help volume that enables users to display help volumes registered on their system using the Front Panel Help Viewer. When a user initially clicks the Help Viewer control in the Front Panel, dthelpgen is run automatically. It locates help family files by searching the help search path directories (local or networked), and then creates a browser volume (browser.hv) in the user's HomeDirectory/.dt/help/$DTUSERSESSION directory. Once built, the volume is updated in response to any of these actions:

Command Syntax

dthelpgen -dir [options]

Where:

-dir

Specifies the directory in which to place the browser volume and intermediate files. This is a required parameter.

Options

-generate

Specifies that a new browser help volume should be created even if the family files and help volumes on the system have not been modified.

-file basename

Specifies the name of the help volume and any intermediate files generated by dthelpgen. The default name is browser.hv.

-lang

Specifies which language directories to search for help families and help volumes. If the -lang option is set, it takes precedence over the current value of the LANG environment variable.

Note -

If you run dthelpgen while the browser volume is displayed in a help window, you should close the window, then reopen the browser volume.

See Also

Chapter 8 Reading the HelpTag Document Type Definition

This chapter explains how to read the HelpTag 1.3 Document Type Definition (DTD) and how to use it to create fully compliant Standard Generalized Markup Language (SGML) help files.

Document Type Definition

A Document Type Definition (DTD) defines a set of elements to create a structured (or hierarchical) document. The DTD specifies the syntax for each element and governs how and where elements can be used in a document.

Helptag 1.3 DTD

The Helptag 1.3 DTD tag set and its associated rules are referred to as formal markup. The DTD conforms to the Standard Generalized Markup Language (SGML) ISO specification 8879:1986. This means that you can use formal markup to create help files that are SGML compliant.

Appendix A contains the complete DTD specification. The DTD is also available in the Developer's Toolkit. It is located in the /usr/dt/dthelp/dthelptag/dtd directory and is named helptag.dtd.

See Also

DTD Components

The DTD defines each of the HelpTag elements described in previous chapters in a technical notation. This section introduces some key terms and explains how to read the syntax of the element notations. It does not attempt to fully describe each section of the DTD.

Element Declarations

The DTD defines each element in an element declaration. The declaration uses a precise notation to describe an element, its required components, and any elements it can or cannot contain. An element may also have characteristics defined in an attribute declaration, which is discussed in the section "Attribute List Declarations".

The syntax of an element declaration is:

<ELEMENT element_type minimization (content model) >

Where:

element_ type

Specifies the element name, which is also used as the tag name. For example, the tag for the element type head is <head>.

minimization

A two-character entry that indicates whether a start or an end tag is required. The first character represents the start tag; the second character represents the end tag. A space separates the two characters. The letter o means that the tag is optional. A - (minus sign) indicates the tag is required. For example, an entry like this, - - , indicates that the element requires both start and end tags. The DTD for Helptag 1.3 requires start and end tags for every element.

content model

Specifies a list of the required and optional elements that the element type can contain. It defines the sequence of elements and, if applicable, the number of occurrences that may occur.

The content model uses these notations:

|

A vertical bar represents "or".

+

Element must appear at least once. It can be repeated.

*

Element can appear zero or more times.

?

Element can appear zero or one time.

,

A comma describes sequence, that is, the element type must be followed by the element specified after the comma.

+ (element_ type(s))

The + (plus sign) indicates that the listed element or elements can be used within the element type or within any of the elements it contains. It is called an inclusion. Parentheses are used to enclose one or more elements.

- (element_ type(s))

A - (minus sign) indicates that the listed element or elements cannot be used within this element, or within any of the elements it contains. It is called an exclusion. Parentheses are used to enclose one or more elements.

Examples

Each example contains a word description for the element declaration provided. Required start and end tags are assumed.

Element Declaration Keywords

Some elements include a keyword in the element declaration that describes the data content of the element. Three keywords appear in the DTD: EMPTY, CDATA, and #PCDATA.

EMPTY

Specifies that the element has no data content that will be displayed in the online information. newline and xref elements are examples.

CDATA

Represents "character data"; that is, the data content of the element is not recognized as markup.

#PCDATA

Represents "parsed character data"; that is, the data content may include both text and markup characters that the Help System parser interprets accordingly.

Attribute List Declarations

An attribute list declares additional properties that further describe an element. An attribute list declaration has the syntax:

<!ATTLIST element_type attribute_values default_value>

For example, a list element has four attributes: type, ordertype, spacing, and continue. Values for each type are declared. The last column shows the default values. Because only one value exists for the continue attribute, a default value is omitted. 

<!ATTLIST list type      ( order 
                           bullet
                            plain
                            check )       bullet
               ordertype ( ualpha
                            lalpha
                            arabic
                            uroman
                            lroman )      arabic
                spacing   ( tight
                             loose )      tight
                continue  (continue)    #IMPLIED >

This markup creates a numbered list (uppercase alphabet) that supplies extra spacing between list items.

<list order ualpha loose>
   <item>
      <text>
        <p>
          <partext>Introducing the Front Panel></partext>
        </p>
      </text>
     </item>

Formal Markup

Using a structured editor is the best approach for creating formal markup. After learning the basic set of elements, an author can get started. This is done by choosing elements from a menu. In response, the structured editor generates all of the tags required for each element. In addition, the application verifies that the structural framework being created conforms to the Document Type Definition.

See the section "Write Help Topics with HelpTag" for a description of shorthand and formal markup, and structured editors.

Formal Markup Caveats

Shorthand and formal markup share a common set of elements, such as chapter, section, head, list, paragraph, and so forth. However, formal markup differs from shorthand markup in these important ways:

Explicit Start and End Tags

Each element, its component parts, and elements it contains must be explicitly tagged. For example, here is the formal markup for a chapter head. To read this, and other markup examples easily, tags are indented. Indentation is not required in actual markup.

<chaphead>
      <head>
              <partext>Front Panel Help</partext>
       </head>
 </chaphead>

Notice the additional tags, <head> and <partext>; these are subcomponents of the <chaphead> element. Each of these elements requires an explicit start and end tag.

Explicit Hierarchy of Elements

Each element declaration contributes to a set of rules that governs how and where elements can be used. Because elements contain other elements, which may contain other elements, a document is a hierarchy of elements. At the top level, <helpvolume> is a container for every other element.

To decide what markup is necessary to create a help topic, you need to become familiar with the rules. For example, suppose you want to create a chapter. First, look at the declaration for chapter listed below. It specifies that a chaphead is required. Next, look at the rules for chaphead. It, in turn, requires a head. Consequently, look at the declaration for head, and continue until you have reached the last nested element--in this case, partext. Until you are familiar with the elements you commonly use, this approach will help you enter markup correctly.

<!ELEMENT chapter - - (chaphead, text?, (s1*, rsect*)) >
<!ELEMENT chaphead - - (head, abbrev?)
                        -(memo | location | idx | footnote) >
<!ELEMENT head - - (partext)
                    -(memo | location | idx)>
<!ELEMENT partext - - ((#PCDATA . . . ))>

Using a structured editor minimizes what an author needs to know about the DTD. The editor application "reads" the DTD and creates each element's required tags, many of which are intermediate structural tags.

Example

This formal markup sample is an excerpt from the desktop Text Editor help volume. To view the corresponding online information, choose the Help Viewer in the Front Panel. Select Common Desktop Environment and then choose Text Editor Help from the listed volumes. In the Text Editor volume, choose Text Editor Tasks and then To Open an Existing Document.

Indentation is used in this example to make it easier to read the text and corresponding element tags. 

<s2 id="TOOPENANEXISTINGDOCUMENT">
<chaphead><head>
<partext>To Open an Existing Document</partext>
     </head></chaphead>
<text>
<p>
<partext>You can use Text Editor or File Manager to open an existing 
document.
 </partext></p>
<idx><indexprimary>
<partext>document</partext></indexprimary>
     <indexsub>
<partext>opening</partext></indexsub></idx>
<idx><indexprimary>
<partext>opening</partext></indexprimary>
     <indexsub>
<partext>existing document</partext></indexsub></idx>
<procedure>
<chaphead><head>
<partext>From Text Editor</partext>
     </head></chaphead>
<text>
<list type="ORDER">
<item><text><p>
<partext>Choose Open from the File menu.</partext></p>
<p>
<partext>The Open a File dialog box lists files and folders on your 
system.You can browse the documents listed, or change to a new folder 
to locate other files on your system.</partext>
     </p></text></item>
<item><text><p>
<partext>Select the document you want to open in the Files list or 
type the file name in the Open a File field.</partext></p>
<p>
<partext><emph><partext>Or,</partext></emph> if the document is not 
in the current folder, first change to the folder that contains your 
document. Then choose a name in the Folders list or type the path 
name of the folder you wish to change to in the Enter path or folder 
name field.</partext></p></text></item>
<item><text><p>
<partext>Press Return or click OK.
 </partext></p></text></item></list>
<figure tonumber="NONUMBER" entity="TEXTEDITOROPENFILE">
</figure></text></procedure>

<procedure><chaphead><head>
<partext>From File Manager</partext>
     </head></chaphead>
<idx><indexprimary>
<partext>opening</partext></indexprimary>
     <indexsub>
<partext>document from File Manager</partext></indexsub></idx>
<idx><indexprimary>
<partext>document</partext></indexprimary>
     <indexsub>
<partext>opening from File Manager</partext></indexsub></idx>
<idx><indexprimary>
<partext>File Manager</partext></indexprimary>
     <indexsub>
<partext>opening document</partext></indexsub></idx>
<text>
<list type="BULLET">
<item><text><p>
<partext>Display the document's file icon in a File Manager 
window.</partext>
     </p></text></item>
<item><text><p>
<partext>Do <emph><partext>one</partext></emph> of the 
following:</partext></p>
<list type="BULLET">
<item><text><p>
<partext>Double-click the document's file icon.</partext>
     </p></text></item>
<item><text><p>
<partext>Select the document, then choose Open from the Selected 
menu.</partext>
     </p></text></item>
<item><text><p>
<partext>Drag the document to Text Editor's control in the Front 
Panel.</partext>
     </p></text></item></list></text>
     </item></list><text> </procedure>
<procedure><chaphead><head>
<partext>See Also</partext>
     </head></chaphead>
<text>
<list type="BULLET" spacing="TIGHT">
<item><text><p>
<partext><xref id="ENTERINGANDEDITINGTEXT"></partext>
     </p></text></item>
<item><text><p>
<partext><xref id="TOSAVEADOCUMENTTOTHECURRENTFILE"></partext>
     </p></text></item>
<item><text><p>
<partext><xref id="TABLEOFCONTENTS"></partext>
     </p></text></item></list></text>
     </procedure></text></s2>

File Entity Declarations

To declare a file entity in formal markup, use this syntax:

<!entity entityname SYSTEM "filename">

Where entityname is the name of the entity and filename is the name of the file. The keyword SYSTEM is required.

Note -

To use entity declarations previously created for shorthand markup, you must replace the FILE parameter with SYSTEM.

Example

Here are the entity declarations for a help volume that consists of three text files and contains a graphic image.

<!entity MetaInformation SYSTEM "metainfo>"
<!entity BasicTasks SYSTEM "basics">
 <!entity AdvancedFeatures SYSTEM "advanced">
 <!entity process_diagram SYSTEM "process.tif">

Entities are referenced in formal markup exactly as they are in shorthand markup.

Processing Formal Markup

When you process formal markup using dthelptag, you must use the -formal command-line option. For example, to process a formal markup file named Icons.ctg in verbose mode, enter this command:

dthelptag -verbose -formal Icons.ctg
Note -

The command option specifies the type of markup in the input file. The run-time file created by running dthelptag is always volume.sdl. The online format is identical whether you used shorthand or formal markup.