Difficulty: ★☆☆ (easy)
Keywords: lists, itemizedlist, orderedlist, variablelist, bibliolist, calloutlist, glosslist, segmentedlist, simplelist, numeration

Problem

You want to know what list types are available in DocBook.

Solution

DocBook provides three basic lists that are used most often:

  • itemizedlist, for unordered lists (like ul in HTML)

  • orderedlist for numbered lists (like ol in HTML)

  • variablelist, for lists containing terms and their definition (like dl in HTML)

Additionally, for specific purposes, DocBook provides special lists (not explained in this topic):

  • bibliolist is a wrapper for bibliographic content. A bibliolist is usually inserted in section-like elements where a bibliography is not allowed.

  • calloutlist, a usually numbered list that points to lines in a listing

  • glosslist is a wrapper for glossary content. A glosslist is usually inserted in section-like elements where a glossary is not allowed.

  • segmentedlist is a list that can be used for items that have a one-to-one correspondence to their title. A segmentedlist can be formatted in a number of ways (tabular or as a list block).

  • simplelist is an unordered list for single words or small phrases.

The previous lists are used to maintain semantic distinction.

Discussion

The list types orderedlist and itemizedlist are structurally identical (except for their enclosing element) as you will see in the following subsections.

The variablelist is slightly different and contains the term element for its term.

Features of itemizedlist

An itemizedlist is an unordered list and can be written as shown in the following example:

Example 1.6. Unordered List with Three Entries
<itemizedlist>
  <listitem>
    <para>The first entry</para>
  </listitem>
  <listitem>
    <para>The second entry</para>
  </listitem>
  <listitem>
    <para>The third entry</para>
  </listitem>
</itemizedlist>

The itemizedlist list in DocBook uses by default a bullet character (• solid circle). If you nest an itemizedlist, it will start with a bullet (• solid circle), then use a circle (○ open circle) and finally a square (■ solid square). If you nest your list deeper, the sequence is repeated. The hierarchy looks like this:

LevelShown as
1.• • •
2.○ ○ ○
3.■ ■ ■

The default bullet character can be overwritten with the mark attribute:

<itemizedlist mark="circle">

It is even possible to deviate from its default symbol in a listitem by using the overwrite attribute:

<itemizedlist>
  <listitem>
    <para>The first entry</para>
  </listitem>
  <listitem overwrite="square">
    <para>The second entry</para>
  </listitem>
  <listitem>
    <para>The third entry</para>
  </listitem>
</itemizedlist>

Features of orderedlist

An orderedlist can be written as shown in the following example:

Example 1.7. Numbered List with Three Entries
<orderedlist>
  <listitem>
    <para>The first entry</para>
  </listitem>
  <listitem>
    <para>The second entry</para>
  </listitem>
  <listitem>
    <para>The third entry</para>
  </listitem>
</orderedlist>

The orderedlist in DocBook numbers as Arabic numbers by default. If you nest an orderedlist, it will be automatically numbered as shown in the following sequence:

LevelShows as
1.1, 2, 3
2.a, b, c
3.i, ii, iii
4.A, B, C
5.I, II, III

The numbering style in an orderedlist can be changed with the numeration attribute. Allowed values are arabic, loweralpha, lowerroman, upperalpha, or upperroman.

Features of variablelist

An variablelist, despite its confusing name, holds all sort of terms and their definitions. It is not limited to variables only. The following example shows how to use a variablelist.

Example 1.8. Definition List with Two Entries
<variablelist>
  <varlistentry>
    <term>Hamburg</term>
    <listitem>
       <para>Town in the northern part of Germany</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Nueremberg</term>
    <listitem>
       <para>Town in the south-eastern part of Germany</para>
    </listitem>
  </varlistentry>
</variablelist>

A varlistentry can contain more than one term. How the terms are displayed usually depends on the output formats. Each term can either be printed on a separate line or all terms on the same line separated by commas.

See Also


Project@GitHubIssue#6