Chapter 17. Lists

Bulleted list items start with a single dash or one to five asterisks followed by some white space then some text. Bulleted list syntaxes are:

- List item.
* List item.
** List item.
*** List item.
**** List item.
***** List item.

List item numbers are explicit or implicit.

Explicit numbering. List items begin with a number followed by some white space then the item text. The numbers can be decimal (arabic), roman (upper or lower case) or alpha (upper or lower case). Decimal and alpha numbers are terminated with a period, roman numbers are terminated with a closing parenthesis. The different terminators are necessary to ensure i, v and x roman numbers are are distinguishable from x, v and x alpha numbers. Examples:

1.   Arabic (decimal) numbered list item.
a.   Lower case alpha (letter) numbered list item.
F.   Upper case alpha (letter) numbered list item.
iii) Lower case roman numbered list item.
IX)  Upper case roman numbered list item.

Implicit numbering. List items begin one to five period characters, followed by some white space then the item text. Examples:

. Arabic (decimal) numbered list item.
.. Lower case alpha (letter) numbered list item.
... Lower case roman numbered list item.
.... Upper case alpha (letter) numbered list item.
..... Upper case roman numbered list item.

You can use the style attribute (also the first positional attribute) to specify an alternative numbering style. The numbered list style can be one of the following values: arabic, loweralpha, upperalpha, lowerroman, upperroman.

Here are some examples of bulleted and numbered lists:

- Praesent eget purus quis magna eleifend eleifend.
  1. Fusce euismod commodo velit.
    a. Fusce euismod commodo velit.
    b. Vivamus fringilla mi eu lacus.
    c. Donec eget arcu bibendum nunc consequat lobortis.
  2. Vivamus fringilla mi eu lacus.
    i)  Fusce euismod commodo velit.
    ii) Vivamus fringilla mi eu lacus.
  3. Donec eget arcu bibendum nunc consequat lobortis.
  4. Nam fermentum mattis ante.
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  * Fusce euismod commodo velit.
  ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
     adolescens. Sit munere ponderum dignissim et. Minim luptatum et
     vel.
  ** Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc consequat lobortis.
- Nulla porttitor vulputate libero.
  . Fusce euismod commodo velit.
  . Vivamus fringilla mi eu lacus.
[upperroman]
    .. Fusce euismod commodo velit.
    .. Vivamus fringilla mi eu lacus.
  . Donec eget arcu bibendum nunc consequat lobortis.

Which render as:

A predefined compact option is available to bulleted and numbered lists — this translates to the DocBook spacing="compact" lists attribute which may or may not be processed by the DocBook toolchain. Example:

[options="compact"]
- Compact list item.
- Another compact list item.

	To apply the compact option globally define a document-wide compact-option attribute, e.g. using the -a compact-option command-line option.

You can set the list start number using the start attribute (works for HTML outputs and DocBook outputs processed by DocBook XSL Stylesheets). Example:

[start=7]
. List item 7.
. List item 8.

Labeled list items consist of one or more text labels followed by the text of the list item.

An item label begins a line with an alphanumeric character hard against the left margin and ends with two, three or four colons or two semi-colons. A list item can have multiple labels, one per line.

The list item text consists of one or more lines of text starting after the last label (either on the same line or a new line) and can be followed by nested List or ListParagraph elements. Item text can be optionally indented.

Here are some examples:

In::
Lorem::
  Fusce euismod commodo velit.

  Fusce euismod commodo velit.

Ipsum:: Vivamus fringilla mi eu lacus.
  * Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc consequat lobortis.
Dolor::
  Donec eget arcu bibendum nunc consequat lobortis.
  Suspendisse;;
    A massa id sem aliquam auctor.
  Morbi;;
    Pretium nulla vel lorem.
  In;;
    Dictum mauris in urna.
    Vivamus::: Fringilla mi eu lacus.
    Donec:::   Eget arcu bibendum nunc consequat lobortis.

Which render as:

17.3.1. Horizontal labeled list style

The horizontal labeled list style (also the first positional attribute) places the list text side-by-side with the label instead of under the label. Here is an example:

[horizontal]
*Lorem*:: Fusce euismod commodo velit.  Qui in magna commodo, est
labitur dolorum an. Est ne magna primis adolescens.

  Fusce euismod commodo velit.

*Ipsum*:: Vivamus fringilla mi eu lacus.
- Vivamus fringilla mi eu lacus.
- Donec eget arcu bibendum nunc consequat lobortis.

*Dolor*::
  - Vivamus fringilla mi eu lacus.
  - Donec eget arcu bibendum nunc consequat lobortis.

Which render as:

Lorem	Fusce euismod commodo velit. Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Fusce euismod commodo velit.
Ipsum	Vivamus fringilla mi eu lacus. Vivamus fringilla mi eu lacus. Donec eget arcu bibendum nunc consequat lobortis.
Dolor	Vivamus fringilla mi eu lacus. Donec eget arcu bibendum nunc consequat lobortis.

Current PDF toolchains do not make a good job of determining the relative column widths for horizontal labeled lists. Nested horizontal labeled lists will generate DocBook validation errors because the DocBook XML V4.2 DTD does not permit nested informal tables (although DocBook XSL Stylesheets and dblatex process them correctly). The label width can be set as a percentage of the total width by setting the width attribute e.g. width="10%"

AsciiDoc comes pre-configured with a qanda style labeled list for generating DocBook question and answer (Q&A) lists. Example:

[qanda]
Question one::
        Answer one.
Question two::
        Answer two.

Renders:

AsciiDoc comes pre-configured with a glossary style labeled list for generating DocBook glossary lists. Example:

[glossary]
A glossary term::
    The corresponding definition.
A second glossary term::
    The corresponding definition.

For working examples see the article.txt and book.txt documents in the AsciiDoc ./doc distribution directory.

	To generate valid DocBook output glossary lists must be located in a section that uses the glossary section markup template.

AsciiDoc comes with a predefined bibliography bulleted list style generating DocBook bibliography entries. Example:

[bibliography]
.Optional list title
- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
  Programming'. Addison-Wesley. ISBN 0-13-142901-9.
- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
  'DocBook - The Definitive Guide'. O'Reilly & Associates. 1999.
  ISBN 1-56592-580-7.

The [[[<reference>]]] syntax is a bibliography entry anchor, it generates an anchor named <reference> and additionally displays [<reference>] at the anchor position. For example [[[taoup]]] generates an anchor named taoup that displays [taoup] at the anchor position. Cite the reference from elsewhere your document using <<taoup>>, this displays a hyperlink ([taoup]) to the corresponding bibliography entry anchor.

For working examples see the article.txt and book.txt documents in the AsciiDoc ./doc distribution directory.

	To generate valid DocBook output bibliography lists must be located in a bibliography section.

Another list or a literal paragraph immediately following a list item is implicitly appended to the list item; to append other block elements to a list item you need to explicitly join them to the list item with a list continuation (a separator line containing a single plus character). Multiple block elements can be appended to a list item using list continuations (provided they are legal list item children in the backend markup).

Here are some examples of list item continuations: list item one contains multiple continuations; list item two is continued with an OpenBlock containing multiple elements:

1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.

2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.

a. This list is nested and does not require explicit item continuation.
+
This paragraph is part of the preceding list item.

b. List item b.

This paragraph belongs to item two of the outer list.
--

Renders: