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

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.

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

HelpTag expects a primary input file named volume.htg, where volume is a name you choose. 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 HP VUE File Manager is "Vuefile," so its helpvolume was named Vuefile.htg.

The details of running HelpTag are covered in “To run `helptag'”.

Multiple Source Files. 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.)

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>The OSF/Motif Style Guide<\book>

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

Short Form Markup.  Short form markup provides another way to enter the markup for many inline elements. 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 above:

   <book|The OSF/Motif Style Guide|

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

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

Shorthand Markup.  Some elements support an even shorter form where the begin 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 ...

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