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

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