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

5 HelpTag Markup Reference

Contents of Chapter:

<abbrev>

<abstract>

<<annotation text>>

<book>

<caution>

<chapter>

<computer>

<copyright>

<dterm>

<emph>

<!entity>

<esc>

<ex>

<figure>

<glossary>

<graphic>

<head>

<helpvolume>

<hometopic>

<idx>

<image>

<item>

<keycap>

<lablist>

<lineno>

<link>

<list>

<location>

<memo>

<metainfo>

<newline>

<note>

<otherfront>

<otherhead>

<procedure>

<quote>

<rsect>

<s1>...<s9>

<super>

<term>

<title>

<user>

<var>

<vex>

<warning>

<xref>

This chapter describes all of the HelpTag markup elements (and their associated tags) in alphabetical order. 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):

     <metainfo>
     <title>
     <copyright>
     <abstract>
     <otherfront> (nonhierarchical topic)

Structure of a help volume:

     <!entity>
     <helpvolume>
     <hometopic>
     <chapter>
     <s1> ...<s9>  (heading)
     <rsect>  (reference section)
     <otherhead>
     <procedure>
     <p>  (paragraph)

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

<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

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

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

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:

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

<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

<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

The following markup:
```
<computer>Enter the correct numerical value.<\computer> 
```
produces the following output:
Enter the correct numerical value.
The following markup uses the shorthand form:
```
Everything in "computer" comes out looking "like this."
```
and it produces:
Everything in computer comes out looking like this.
Variables can be nested within computer text. For example, this markup:
```
``void DisplayTopic (%%topic%%);'' 
```
produces:
void DisplayTopic (topic);

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

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

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

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

Text that is associated with an entity name appears only once so that changing the text requires making a change in only one place. All references to the entity automatically change when HelpTag reprocesses the files.
The inefficiency of typing the same long or complex text string many times can be avoided (along with typing mistakes) by typing just a short entity reference wherever that text string will appear. The full text string needs to be typed only once.
The <figure> and <graphic> elements do not accept a file name. The name of the file that contains the figure must be specified in an entity declaration.
It is convenient to put the help text into multiple files, yet HelpTag accepts only one source file. These needs can be balanced by creating one file that contains entity declarations and entity references that refer to the files that contain the actual help text.

Examples

The volume.htg source file can contain the following entity declarations and entity references so that the actual text can be put into the named files:
```
<!entity topic1 FILE "topic1"> 
<!entity topic2 FILE "topic2"> 
<!entity topic3 FILE "topic3"> 

&topic1;
&topic2;
&topic3;
```
The following entity declaration causes the words "Architectural Analysis of Aircraft Precision Components" to be displayed wherever the &apc; entity reference appears in the marked-up files.
```
<!entity apc "Architectural Analysis of Aircraft Precision
Components"> 
```
The following entity declaration for a figure is placed at the beginning of the source file:
```
<!entity CloseUpFig FILE "figname.tif"> 
```
and the figure would be inserted where the following markup appears:
```
<figure entity=CloseUpFig> 
Close Up View
<\figure> 
```

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

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

<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

The following markup inserts a graphic with the specified caption and an automatically generated figure number:

<!entity MapFigure FILE  "worldmap.xwd"> 
   .
   .
   .
<figure entity=MapFigure> 
Caption for Figure
<\figure>

The following markup inserts a figure that is numbered but does not have a caption.

<!entity StateMap FILE  "oregon.xwd"> 
   .
   .
   .
<figure entity=StateMap>
<\figure> 
   .
   .
   .

The following markup inserts a figure using a specific figure number and a caption. The caption is split into two lines where the \ (backslash) character appears.
```
<figure number=99 entity=SchemDiag> 
Schematic that Illustrates\the Overall System Design
<\figure> 
```

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

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

The following markup first defines an entity (mini-icon) as being associated with the contents of a graphics file (named mini.pm). Then the <graphic> element indicates the location of the graphic within a line of text.
```
<!entity mini-icon FILE "mini.pm">
 .
 .
 .
The <graphic entity=mini-icon> icon is used to represent very 
small images.
```

The following markup first defines a topic whose ID is mini-icon-topic. It then shows how to use the inline graphic as a hyperlink to this topic.

<s1 id=mini-icon-topic>When you click on the inline graphic, it 
will bring you to this topic.
.
.
.
The <link mini-icon-topic> <graphic entity=mini-icon> <\link>  
icon is to represent very small things.

<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

The following markup adds a title to a list and specifies the start of a new line where the \ (backslash) appears:
```
<list><head>Printing Options\for the QRZ Hardware
```
It produces this output:

The following markup overrides the default "Note" heading:


<note><head>Tips and Shortcuts

Keyboard menu accelerators provide quick access to menu commands.
<\note>

It produces this output:

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

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

<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

The following markup shows the definition of some simple index entries using the shortform. The index entries are indented to make the source text easier to read.

A portable personal computer has a full-sized keyboard, built-in 
disk drives and a detachable LCD screen.

      <idx|keyboard|
      <idx|disk drive|
      <idx|screen, LCD|
      <idx|personal computer, portable|
      <idx|portable, personal computer|

The following example displays "+" in the index, but it appears where "plus" would appear in the alphabetical list of entries.
```
<idx>+<sort>plus<\idx> 
```

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

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

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

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

An empty line
Start of another labeled item
<\lablist> end tag

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:

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

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

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

Avoid using the type keywords (listed above) as values for hyperlink. If you must do so, explicitly identify the parameters as shown in the second syntax line.
The <link> element is not needed in a cross-reference that uses the <xref> element because a hyperlink is automatically created where the <xref> element is used.

Examples

The following markup defines a simple hyperlink to a topic with the ID Intro. Notice that capitalization of the ID is not significant.
```
<s1 id=Intro>Introducing the Desktop
.
.
.
Refer to the <link intro>Introduction<\link>.
```
The following markup defines the same hyperlink jump as in the previous example but the <link> element is not used because a cross-reference (<xref...>) is automatically a hyperlink. In this case, the title of the Intro topic is automatically supplied by HelpTag.
```
Refer to <xref intro>.
```
This markup produces this output:
```
Refer to Introducing the Desktop.
```
The following markup defines a hyperlink that is activated when the inline graphic is chosen. A new window is opened to display the "clockfeatures" topic.
```
Whenever you see the <link clockfeatures JumpNewView> 
<graphic entity=StopWatchIcon><\link> symbol, stop and answer the 
quiz questions.
```
It produces this output:
The following markup creates a link that displays the man page for the grep command:
```
For more details, refer to the <link grep Man>grep man 
page<\link>.
```
The following markup creates an execution link using an execution alias named startDtterm. The alias name and the command it executes are defined in the application's application defaults file.
```
To open a terminal window, click <link hyperlink="DtHelpExecAlias 
startDtterm" Execute>Start Terminal Emulator.<\link>
```
For information about execution aliases and how to define them, see "Execution Aliases."

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

<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, (∅), 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>
.
.
.

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

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

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

<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

The following markup uses the default heading:

<note> 
Warranty information is in your installation manual.
<\note>

The following markup specifies a different heading:

<note><head>Read This First
Warranty information is in your installation manual.
<\note>

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

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

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

Here are two paragraphs, the second of which is indented:

Some people do not like to read instruction manuals. This is not always a good idea.

produces:

Some people do not like to read instruction manuals.
This is not always a good idea.

This markup creates a paragraph style with a run-in head.

<p><head>Examples and Illustrations <\head>
Examples, perhaps the most common pattern of organization, are
appropriate whenever the reader might be tempted to ask <quote>
For example?<\quote>

It produces this output:

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

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

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

Required heading
Optional introductory text
Optional reference subsections (<rsub>)

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

<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

The following illustrates a three-level hierarchy within a topic.

<chapter>Running the Processor
topic text...

<s1>Getting Started
To run the program, type in the usercode and your password.

<s1>Customizing
You may now set up this conversion program to change your computer from beige to red.

<s2>Configuration
Use either the disk drive or the tape drive to archive your files.

<s3>Disk Drive Advantages
See data sheet for specifications.

<s3>Tape Drive Advantages
See data sheet for specifications.

<s2>Support
If you really need help, call technical support.

In the following markup, a section end tag (<\s1>) is used to make the <rsect> section be at the same level in the hierarchy.

<s1>first-level heading
text

<s1>first-level heading
text
<\s1> 
<rsect>first-level heading
text
In contrast, leaving out the end tag causes the <rsect> section 
to become a subtopic of the second <s1> section: 

<s1>first-level heading
text

<s1>first-level heading
text

<rsect>second- level heading
text

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 contains two hydrogen molecules.

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

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

<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

<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

<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

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

<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

The following markup creates a warning message:

<warning> 
Failure to follow these guidelines could result
in serious consequences.
<\warning>

The following markup specifies a different heading for the warning message:

<warning><head>Danger!
Do not open the high-voltage compartment.
<\warning>

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

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

5 HelpTag Markup Reference

Syntax

Example

See Also

Syntax

Examples

See Also

Syntax

Example

Note

See Also

<<annotation text>>

Syntax

Example

Syntax

Example

Syntax

Example

See Also

Syntax

Example

See Also

Syntax

Examples

See Also

Syntax

Example

See Also

Syntax

Example

See Also

<emph>

Syntax

Example

See Also

Syntax

Purposes for Entities

See Also

<esc>

Syntax

See Also

Syntax

Example

See Also

Syntax

Examples

See Also

Syntax

Example

See Also

Syntax

Examples:

See Also

Syntax

Examples

See Also

<helpvolume>

Syntax

See Also

Syntax

Example

See Also

Syntax

Examples

Syntax

See Also

Syntax

See Also

<keycap>

Syntax

Example

See Also

Syntax

Example

See Also

<lineno>

Syntax

Example

See Also