Writing documentation with DocBook-XML 4.2

A bullet list is a set of narrower paragraphs shown with a round dot (the bullet) before each one. Typical uses are lists of features, lists of important points, and such.

Enclose the entire bullet list inside an <itemizedlist>...</itemizedlist> element. Each item is then enclosed within a <listitem>...</listitem> element containing one or more <para> or <simpara> elements.

For example, this input:

    <itemizedlist>
      <listitem>
        <para>Mangos.</para>
      </listitem>
      <listitem>
        <para>Chirimoya.</para>
      </listitem>
    </itemizedlist>

produces this output:

Normally, bullet lists have a fairly generous amount of space between the bullets. To reduce this space, add a spacing="compact" attribute to the <itemizedlist> element. Here is the example list again in compact spacing:

To produce a numbered list of items, use the <orderedlist> construct. Here's an example:

Here's how the above list looks in source form:

      <orderedlist>
        <listitem>
          <para>DocBook renders documents in both print and Web
            form.</para></listitem>
        <listitem>
          <para>It frees the author from most concerns of
            presentation.</para></listitem>
      </orderedlist>

There are a number of attributes you can add to the <orderedlist> element to change the way the entries are numbered:

A step-by-step procedure is generally presented in a form similar to the bullet list, but with step numbers taking the place of bullets.

Enclose the entire procedure within a <procedure>...</procedure> element. Each step is enclosed within a <step>...</step> element containing one or more <para> or <simpara> elements.

For example, this input:

    <procedure>
      <step><para>Throw the football.</para>
      </step>
      <step><para>Pick it up first.</para>
      </step>
    </procedure>

produces this output:

If the steps of your procedure refer to other steps, you can get DocBook to insert the step number into each reference automatically. To do this:

Here's an example. This is a (facetious) solution to the famous Halting Problem. First, in output form:

And now the source for the above:

      <procedure>
        <step id="start-step">
          <para>Has the program halted?  If so, go to
            <xref linkend="done-step"/>.</para></step>
        <step id="loop-step">
          <para>Go to <xref linkend="start-step"/>.</para></step>
        <step id="done-step">
          <para>Done: we now know that the program halts.</para></step>
      </procedure>

Another commonly used special paragraph shape is to display a list of terms to be defined, each followed by an indented paragraph containing the description.

For this shape, enclose the entire list in a <variablelist> tag. Each term-definition pair is enclosed in a <varlistentry> element. Inside that element, enclose the term to be defined inside a <term> element, and enclose the paragraph or paragraphs defining the term inside a <listitem> element.

Here is an example of a list containing two terms:

      <variablelist>
        <varlistentry>
          <term><userinput>.__abs__(self)</userinput></term>
          <listitem>
            <para>Defines the behavior of the
              <userinput>abs()</userinput> function when
              applied to an object of your class.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><userinput>.__add__(self,<replaceable
            >other</replaceable>)</userinput></term>
          <listitem>
            <para>Defines the behavior of this class for
              <userinput>self+<replaceable>other</replaceable
              ></userinput>.</para></listitem>
        </varlistentry>
      </variablelist>

And here is how that looks when formatted:

Sometimes you need to make some text stand out against the background. DocBook has several tags for such purposes:

Typically you will put one or more regular paragraphs (using the <para> tag) inside such elements. Here's an example:

And here's that warning in source form:

    <warning>
      <para>Do not touch the electric fence!</para>
    </warning>

Two different elements are used to present quotations set off in separate blocks:

In either case, the content of the element consists of an optional <attribution> element that tells the reader who said this. The actual quotation follows, typically wrapped in one or more <para> elements. Generally the attribution will be presented after the quotation.

Here's an example:

The source for the quote looks like this:

      <blockquote>
        <attribution>C. A. R. Hoare</attribution>
        <para>
          There are two ways of constructing a software
          design. One way is to make it so simple that there are
          obviously no deficiencies. And the other way is to make
          it so complicated that there are no obvious
          deficiencies.
        </para>
      </blockquote>