General Markup Guidelines

Online help is written in ordinary text files. You use special codes, called tags, to markup elements within the information. The tags form a markup language called DocBook.

If a standard text editor is used, DocBook markup is typed. If the editor provides a macro package, tags can be stored and inserted using command keys. DocBook markup can also be generated using a structured editor (see “Formal Markup”).

The DocBook markup language defines a hierarchy of elements that define high-level elements, such as chapters and sections, block-oriented elements, such as paragraphs, lists, and tables, and low level in-line elements such as emphasized words and symbols.

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 / (forward slash). Case is not significant in DocBook markup tags.

<Element attribute name="attribute value"> ... text ... </Element>

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

<Title id="GSNW">Geographical Survey of Northern Wisconsin</Title>

Where <Title> is the start tag, and </Title> is the end tag, and GSNW is the value of the ID attribute of the Title element. If the element has more than one attribute with a specified value, the attribute name="attribute value" expressions are separated by spaces.