AsciiDoc User Guide
Warning
•Use vertical labeled lists in preference to horizontal labeled lists — current PDF toolchains do not make a good job of determining the relative column widths.
•If you are generating DocBook markup the horizontal labeled lists should be nested because the DocBook XML V4.2 DTD does not permit nested informal tables (although DocBook XSL Stylesheets process them correctly).
Question and Answer Lists
AsciiDoc comes pre-configured with a labeled list for generating DocBook question and answer (Q&A) lists (?? label delimiter). Example:
Question one??
Answer one.
Question two??
Answer two.
Renders:
1.
Question one
Answer one.
2.
Question two
Answer two.
Glossary Lists
AsciiDoc comes pre-configured with a labeled list (:- label delimiter) for generating DocBook glossary lists. Example:
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.
Note
To generate valid DocBook output glossary lists must be located in a glossary section.
28
AsciiDoc User Guide
Bibliography Lists
AsciiDoc comes with a predefined itemized list (+ item bullet) for generating bibliography entries. Example:
+[[[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.
Note
To generate valid DocBook output bibliography lists must be located in a bibliography section.
List Item Continuation
To include subsequent block elements in list items (in addition to implicitly included nested lists and Literal paragraphs) place a separator line containing a single plus character between the list item and the ensuing list continuation element. Multiple block elements (excluding section Titles and BlockTitles) may be included in a list item using this technique. For example:
Here's an example of list item continuation:
1.List item one.
+
List item one continued with a second paragraph followed by an Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item one continued with a third paragraph.
2.List item two.
List item two literal paragraph (no continuation required).
-Nested list (item one).
Nested list literal paragraph (no continuation required).
+
Nested list appended list item one paragraph
-Nested list item two.
Renders:
29
AsciiDoc User Guide
1.List item one.
List item one continued with a second paragraph followed by a Listing block.
$ ls *.sh
$ mv *.sh ~/tmp
List item one continued with a third paragraph.
2.List item two.
List item two literal paragraph (no continuation required).
•Nested list (item one).
Nested list literal paragraph (no continuation required).
Nested list appended list item one paragraph
•Nested list item two.
List Block
A List block is a special delimited block containing a list element.
•All elements between in the List Block are part of the preceding list item. In this respect the List block behaves like List Item Continuation except that list items contained within the block do not require explicit + list item continuation lines:
•The block delimiter is a single line containing two dashes.
•Any block title or attributes are passed to the first element inside the block.
The List Block is useful for:
1.Lists with long multi-element list items.
2.Nesting a list within a parent list item (by default nested lists follow the preceding list item).
Here's an example of a nested list block:
.Nested List Block 1. List item one.
+
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
30