Lists
DocBook has several list structures to choose from. It has the standard numbered lists
and bulleted lists. In addition it provides specialized types of lists for glossaries and
other occasions. All of these lists may be used in Evergreen documentation.
Simple Lists
Overview
Simple lists are like a grocery list. They are a simple list of words or phrases without
any delimiter. Their elements can only consist of simple, in-line tags, and therefore cannot
contain sublists, examples, code listings or multiple paragraphs. Simple lists are rarely
used in Evergreen' documentation.
Specifying a simple list
A simple list is specified by a simplelist element. simplelist has two optional attributes:
Attributes of the simplelist Element
Attribute
Values
Description
type
inline, horiz, vert (default)
Specifies how the items in the list are to be listed.
columns
>=1
Specifies the number of columns to use when type
is set to horiz or vert.
The elements of a simple list are specified using a member
element. The contents of each member element can only contain
character data and in-line elements.
Example
shows the markup for a simple list.
Simple List Markup
<simplelist>
<member>Swedish Fish</member>
<member>Mike & Ike</member>
<member>Sour Patch Kids</member>
<member>Gummy Bears</member>
</simplelist>
Itemized Lists
Overview
An itemized list is used for lists where the order of the items in the list does not
matter. They are like bulleted lists or the lists that are created by the ul tag in HTML.
Specifying an itemized list
An itemized list is specified by an itemizedlist element. You
can specify an xml:id attribute for itemized lists. If the list
is going to referenced by an xref element, you should also
specify a value for the xreflabel attribute.
Each item in an itemized list is specified by a listitem
element. The listitem element is a wrapper element and can
contain any container elements such as a para element. All
content within a listitem element will be indented to the same
level. You can also specify sub-lists within a listitem
element.
Example
shows the markup for an itemized list.
Itemized List Markup
<itemizedlist>
<listitem>
<para>This is the first item in my list</para>
</listitem>
<listitem>
<para>This is the second item in my list.</para>
<para>It has two paragraphs.</para>
</listitem>
<listitem>
<para>This item has a sublist.</para>
<itemizedlist>
<listitem><para>first</para></listitem>
<listitem><para>second</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
Ordered List
Overview
An ordered list is a list where the order of the elements is important and made
explicit. They are like numbered lists and lists that are created using the ol tag in HTML.
Specifying an ordered list
Ordered lists are specified by an orderedlist element. In
addition to the xml:id attribute and xreflabel attribute, orderedlist elements have three
optional elements.
Attributes of the orderedlist Element
Attribute
Values
Description
continuation
continues, restarts
(default)
Specifies whether the item numbering should restart at one or continue from the
previous ordered list.
inheritnum
inherit, ignore
(default)
Valid only for nested lists. Specifies whether the items in the nested list
contain a reference to the item of the parent list.
numeration
arabic, loweralpha,
lowerroman, upperalpha,
upperroman
Specifies the numbering style to use for the list.
Items in an ordered list are specified using a listitem
element. The listitem element is a wrapper element and can
contain any container elements such as a para element. All
content within a listitem element will be indented to the same
level. You can also specify sub-lists within a listitem
element.
Variable Lists
Overview
A variable list looks similar to a glossary. It consists of a word, or phrase, and some
text describing the word, or phrase. shows a variable list.
List of Rooms
Kitchen
The room where food is stored and prepared.
Garage
Where the cars are parked.
Bikes are also here.
Living room
Family room
This is where we watch TV.
Specifying the list
Variable lists are specified by a variablelist element. The
variablelist element can have the optional xml:id attribute and xreflabel
attribute specified. You can also supply a title for a variable list by adding a title element as the variablelist
element's first child.
The items in a variable list are specified using a varlistentry element. The varlistentry element has two
children elements that specify the contents of the item:
term
listitem
Specifying terms
You can specify one or more term elements in a varlistentry element. Each term element
can contain text and in-line markup elements. Each term element
should contain a single term or phrase that the list item describes.
Describing a term
You describe the term, or terms, defined by the term elements
using a single listitem element. The listitem element is a wrapper element and can contain any container elements such
as a para element. All content within a listitem element will be indented to the same level. You can also specify sub-lists
within a listitem element.
Example
shows the markup representing .
Variable List Markup
<variablelist xml:id="varexample">
<title>List of Rooms</title>
<varlistentry>
<term>Kitchen</term>
<listitem>
<para>The room where food is stored and prepared.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Garage</term>
<listitem>
<para>Where the cars are parked.</para>
<note>
<para>Bikes are also here.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>Living room</term>
<term>Family room</term>
<listitem>
<para>This is where we watch TV.</para>
</listitem>
</varlistentry>
</variablelist>
Glossary Lists
Overview
A glossary list is a special case of a variable list. It is used specifically for lists
that define terms and where you may want to refer the reader back to the definition of a
specific term. shows a use
of a glossary list.
List of Terms
consumer
The end user of a service, also called a client for that service.
endpoint
The point of contact that a service
provides for its consumers.
service
A collection of operations that perform a useful set of functions in a network,
access to which is implemented as an endpoint. In a service-oriented network, services are defined by a
service contract.
service consumer
Specifying the list
A glossary list is specified using the glosslist element. If
you want to refer back to a glossary list, you can provide values for the xml:id attribute and the xreflabel
attribute. Like variable lists, glossary lists can have titles.
The entries in a glossary list are specified using a glossentry element. The glossentry element typically has
two children: glossterm and glossdef.
You can also use the glosssee element to xref with other
definitions.
Specifying a term
A glossentry element can have only one glossterm element. This element specifies the term being defined by this entry. If
you are going to refer back to this term, you can supply a value for the parent glossentry element's xml:id
attribute.
The glossterm element can also be used in text entries to
refer to terms defined in a glossary entry. When used in this manner, you supply a value
for the linkend attribute.
Defining a term
You define a term using either one or more glossdef elements
or a glosssee element. The glossdef
element is a content element that contains markup specifying a definition. If you use more
than one glossdef element, they are treated as separate
definitions for the same term.
The glosssee element redirects the reader to a term with the
same meaning. It acts like a "See" entry in a dictionary. It has one attribute,
otherterm, whose value is the id of the term to which the
reader is redirected.
Example
shows the markup for .
Glossary List Markup
<glosslist xml:id="glossexample" xreflabel="List of terms";>
<glossentry xml:id="consumerdef">
<glossterm>consumer</glossterm>
<glossdef>
<para>The end user of a service, also called a
client for that service.</para>
</glossdef>
</glossentry>
<glossentry xml:id="endptdef">
<glossterm>endpoint</glossterm>
<glossdef>
<para>The point of contact that a
<glossterm linkend="servicedef">service</glossterm>
provides for its
<glossterm linkend="consumerdef">consumers</glossterm>.
</para>
</glossdef>
</glossentry>
<glossentry xml:id="servicedef">
<glossterm>service</glossterm>
<glossdef>
<para>A collection of operations that perform a
useful set of functions in a network, access to
which is implemented as an
<glossterm linkend="endptdef">endpoint</glossterm>.
In a service-oriented network, services are defined
by a service contract.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>service consumer</glossterm>
<glosssee otherterm="consumerdef" />
</glossentry>
</glosslist>