DocBook lists are very similar to their counterparts in HTML except that DocBook contains several more types of lists for specialized purposes.
The tags covered in this chapter are listed below.
SimpleList - List of single words or short phrases |
Member - Member of a SimpleList |
ItemizedList - List in which each entry is marked with a bullet, dash, or other dingbat |
ListItem - Wrapper for the elements of items in an ItemizedList or OrderedList |
OrderedList - List in which each entry is marked with a sequentially incremented label |
VariableList - List in which each entry is composed of sets of one or more Terms with associated ListItems |
VarListEntry - Wrapper for Term and its associated ListItem in a VariableList |
Term - Hanging term attached to a ListItem within a VarListEntry in a VariableList |
SegmentedList - List of sets of information |
SegTitle - Title that pertains to one Seg in each SegListItem |
SegListItem - List item in a SegmentedList |
Seg - Component of a SegmentedList |
QandASet - A question-and-answer set |
QandAEntry - A question/answer set within a QandASet |
Question - A question in a QandASet |
Answer - An answer to a question posed in a QandASet |
Procedure - List of operations to be performed |
Step - Part of a Procedure |
SubSteps - Wrapper for Steps within Steps |
The easiest of all the lists to use is the SimpleList. It is designed for lists of short phrases (like a grocery list) and only requires two tags for building the list as you can see in the example below. The <Member> tag can only contain inline content, so a SimpleList cannot contain other lists.
Example 3-3. Example of a SimpleList
<simplelist> <member>Apples</member> <member>Oranges</member> <member>Bananas</member> <member>Grapefruit</member> <member>Black Beans</member> </simplelist> |
When converted to HTML, a SimpleList will look something like this:
Apples |
Oranges |
Bananas |
Grapefruit |
Black Beans |
An ItemizedList is similar to the SimpleList except that each entry contains a paragraph instead of just a short phrase, allowing you to put more varied content in your list. ItemizedLists can contain other lists.
Example 3-4. Example of an ItemizedList
<itemizedlist> <listitem><para>Apples - my favorite fruit.</para></listitem> <listitem><para>Oranges - yummy, but sticky.</para></listitem> <listitem><para>Bananas - they ripen too quickly!</para></listitem> <listitem><para>Grapefruit - great when eaten in halves.</para></listitem> <listitem><para>Black Beans - go well with rice.</para></listitem> </itemizedlist> |
The example will look something like this when converted to HTML:
Apples - my favorite fruit.
Oranges - yummy, but sticky.
Bananas - they ripen too quickly!
Grapefruit - great when eaten in halves.
Black Beans - go well with rice.
The OrderedList is like the ItemizedList except that each ListItem is numbered or lettered. The Numeration attribute specifies what kind of numbering will be used and can be one of the following values: Arabic, Upperalpha, Loweralpha, Upperroman, Lowerroman. There are several other attributes that control the appearance of an OrderedList. See the DocBook Reference for details. OrderedLists can contain other lists.
Example 3-5. Example of an OrderedList
<orderedlist numeration="arabic"> <listitem><para>Wake up.</para></listitem> <listitem><para>Eat Breakfast.</para></listitem> <listitem><para>Take a shower.</para></listitem> <listitem><para>Contemplate my navel.</para></listitem> <listitem><para>Go to Sleep.</para></listitem> </orderedlist> |
The example will look something like this when converted to HTML:
Wake up.
Eat Breakfast.
Take a shower.
Contemplate my navel.
Go to Sleep.
The VariableList is similar to an HTML definition list. It is used when you have a list of terms and definitions. The VariableList consists of several tags: <VarListEntry>, which is used to group related terms together, <Term>, which contains the term, and <ListItem>, which contains the decription of the term.
Example 3-6. Example of a VariableList
<variablelist> <varlistentry> <term>Black Beans</term> <listitem><para>My favorite black bean recipe is black bean soup, but they also go well with rice.</para></listitem> </varlistentry> <varlistentry> <term>Apples</term> <term>Bananas</term> <listitem><para>You can eat them straight, but they also go well in salads and in desserts.</para></listitem> </varlistentry> </variablelist> |
When converted to HTML, the example VariableList will look something like this:
My favorite black bean recipe is black bean soup, but they also go well with rice.
You can eat them straight, but they also go well in salads and in desserts.
SegmentedLists are used to list information in distinct fields like the contents of an address book. The name of each field is put inside of a <SegTitle> tag. Then, use the <SegListItem> tag to start and end each set of data. The actual data is put in the <Seg> tag.
Example 3-7. Example of a SegmentedList
<segmentedlist> <segtitle>Name</segtitle> <segtitle>Occupation</segtitle> <segtitle>Favorite Food</segtitle> <seglistitem> <seg>Tux</seg> <seg>Linux mascot</seg> <seg>Herring</seg> </seglistitem> <seglistitem> <seg>Konqui</seg> <seg>The KDE Dragon</seg> <seg>Gnomes</seg> </seglistitem> </segmentedlist> |
This silly example looks something like this when converted to HTML:
Name: Tux
Occupation: Linux mascot
Favorite Food: Herring
Name: Konqui
Occupation: The KDE Dragon
Favorite Food: Gnomes
The QandASet is a specialized list designed specifically to deal with sets of questions and answers, like you would see in a FAQ. Each set of questions and answers are contained within a <QandAEntry> tag. The <Question> and <Answer> tags contain the questions and answers respectively.
Example 3-8. Example of a QandASet
<qandaset> <qandaentry> <question> <para>What are little boys made of?</para> </question> <answer> <para>Snips and snails and puppy dog tails.</para> </answer> </qandaentry> <qandaentry> <question> <para>What are little girls made of?</para> </question> <answer> <para>Sugar and spice and everything nice.</para> </answer> </qandaentry> </qandaset> |
The QandASet looks something like this when converted to HTML:
Procedure Lists are a specialized OrderedList used for listing step-by-step procedures like you would find in a recipe or Linux HowTo.
Example 3-9. Example of a Procedure List (Stolen from the DocBook reference)
<procedure> <title>Waking Up</title> <para>This is what you must do to awaken.</para> <step performance="required"> <para> Bring yourself to a hypnopompic state, either from an ongoing dream or by use of your internal clock. You may feel unable to move, but you will no longer be dreaming. </para> <para>Now you are ready for real-world readjustment.</para> <substeps> <step performance="optional"> <para>Roll over.</para> </step> <step performance="required"> <para>Squint out of one eye.</para> </step> </substeps> </step> <step performance="required"> <para>Yawn and rise from your bed. </para> </step> </procedure> |
The above example would look something like this when converted to HTML:
Waking Up
This is what you must do to awaken.
Bring yourself to a hypnopompic state, either from an ongoing dream or by use of your internal clock. You may feel unable to move, but you will no longer be dreaming.
Now you are ready for real-world readjustment.
Roll over.
Squint out of one eye.
Yawn and rise from your bed.