1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 17. Lists</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="home" href="index.html" title="AsciiDoc User Guide" /><link rel="up" href="index.html" title="AsciiDoc User Guide" /><link rel="prev" href="ch16.html" title="Chapter 16. Delimited Blocks" /><link rel="next" href="ch18.html" title="Chapter 18. Footnotes" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch16.html"><img src="images/icons/prev.png" alt="Prev" /></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch18.html"><img src="images/icons/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="X64"></a>Chapter 17. Lists</h1></div></div></div><div class="itemizedlist"><p class="title"><strong>List types</strong></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Bulleted lists. Also known as itemized or unordered lists.
</li><li class="listitem">
Numbered lists. Also called ordered lists.
</li><li class="listitem">
Labeled lists. Sometimes called variable or definition lists.
</li><li class="listitem">
Callout lists (a list of callout annotations).
</li></ul></div><div class="itemizedlist"><p class="title"><strong>List behavior</strong></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
List item indentation is optional and does not determine nesting,
indentation does however make the source more readable.
</li><li class="listitem">
Another list or a literal paragraph immediately following a list
item will be implicitly included in the list item; use <a class="link" href="ch17.html#X15" title="17.7. List Item Continuation">list item continuation</a> to explicitly append other block elements to a
list item.
</li><li class="listitem">
A comment block or a comment line block macro element will terminate
a list — use inline comment lines to put comments inside lists.
</li><li class="listitem">
The <code class="literal">listindex</code> <a class="link" href="ch31.html" title="Chapter 31. Intrinsic Attributes">intrinsic attribute</a> is the current list item
index (1..). If this attribute is used outside a list then it’s value
is the number of items in the most recently closed list. Useful for
displaying the number of items in a list.
</li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_bulleted_lists"></a>17.1. Bulleted Lists</h2></div></div></div><p>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:</p><pre class="literallayout">- List item.
* List item.
** List item.
*** List item.
**** List item.
***** List item.</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_numbered_lists"></a>17.2. Numbered Lists</h2></div></div></div><p>List item numbers are explicit or implicit.</p><p><strong>Explicit numbering. </strong>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 <span class="emphasis"><em>i</em></span>,
<span class="emphasis"><em>v</em></span> and <span class="emphasis"><em>x</em></span> roman numbers are are distinguishable from <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>v</em></span> and
<span class="emphasis"><em>x</em></span> alpha numbers. Examples:</p><pre class="literallayout">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.</pre><p><strong>Implicit numbering. </strong>List items begin one to five period characters, followed by some white
space then the item text. Examples:</p><pre class="literallayout">. 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.</pre><p>You can use the <span class="emphasis"><em>style</em></span> attribute (also the first positional
attribute) to specify an alternative numbering style. The numbered
list style can be one of the following values: <span class="emphasis"><em>arabic</em></span>, <span class="emphasis"><em>loweralpha</em></span>,
<span class="emphasis"><em>upperalpha</em></span>, <span class="emphasis"><em>lowerroman</em></span>, <span class="emphasis"><em>upperroman</em></span>.</p><p>Here are some examples of bulleted and numbered lists:</p><pre class="screen">- 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.</pre><p>Which render as:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
Praesent eget purus quis magna eleifend eleifend.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p class="simpara">
Fusce euismod commodo velit.
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem">
Fusce euismod commodo velit.
</li><li class="listitem">
Vivamus fringilla mi eu lacus.
</li><li class="listitem">
Donec eget arcu bibendum nunc consequat lobortis.
</li></ol></div></li><li class="listitem"><p class="simpara">
Vivamus fringilla mi eu lacus.
</p><div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem">
Fusce euismod commodo velit.
</li><li class="listitem">
Vivamus fringilla mi eu lacus.
</li></ol></div></li><li class="listitem">
Donec eget arcu bibendum nunc consequat lobortis.
</li><li class="listitem">
Nam fermentum mattis ante.
</li></ol></div></li><li class="listitem"><p class="simpara">
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p class="simpara">
Fusce euismod commodo velit.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: square; "><li class="listitem">
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
vel.
</li><li class="listitem">
Vivamus fringilla mi eu lacus.
</li></ul></div></li><li class="listitem">
Donec eget arcu bibendum nunc consequat lobortis.
</li></ul></div></li><li class="listitem"><p class="simpara">
Nulla porttitor vulputate libero.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
Fusce euismod commodo velit.
</li><li class="listitem"><p class="simpara">
Vivamus fringilla mi eu lacus.
</p><div class="orderedlist"><ol class="orderedlist" type="I"><li class="listitem">
Fusce euismod commodo velit.
</li><li class="listitem">
Vivamus fringilla mi eu lacus.
</li></ol></div></li><li class="listitem">
Donec eget arcu bibendum nunc consequat lobortis.
</li></ol></div></li></ul></div><p>A predefined <span class="emphasis"><em>compact</em></span> option is available to bulleted and numbered
lists — this translates to the DocBook <span class="emphasis"><em>spacing="compact"</em></span> lists
attribute which may or may not be processed by the DocBook toolchain.
Example:</p><pre class="literallayout">[options="compact"]
- Compact list item.
- Another compact list item.</pre><div class="tip" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/icons/tip.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>To apply the <span class="emphasis"><em>compact</em></span> option globally define a document-wide
<span class="emphasis"><em>compact-option</em></span> attribute, e.g. using the <code class="literal">-a compact-option</code>
command-line option.</p></td></tr></table></div><p>You can set the list start number using the <span class="emphasis"><em>start</em></span> attribute (works
for HTML outputs and DocBook outputs processed by DocBook XSL
Stylesheets). Example:</p><pre class="literallayout">[start=7]
. List item 7.
. List item 8.</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_labeled_lists"></a>17.3. Labeled Lists</h2></div></div></div><p>Labeled list items consist of one or more text labels followed by the
text of the list item.</p><p>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.</p><p>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.</p><p>Here are some examples:</p><pre class="screen">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.</pre><p>Which render as:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
In
, </span><span class="term">
Lorem
</span></dt><dd><p class="simpara">
Fusce euismod commodo velit.
</p><pre class="literallayout">Fusce euismod commodo velit.</pre></dd><dt><span class="term">
Ipsum
</span></dt><dd><p class="simpara">
Vivamus fringilla mi eu lacus.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Vivamus fringilla mi eu lacus.
</li><li class="listitem">
Donec eget arcu bibendum nunc consequat lobortis.
</li></ul></div></dd><dt><span class="term">
Dolor
</span></dt><dd><p class="simpara">
Donec eget arcu bibendum nunc consequat lobortis.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
Suspendisse
</span></dt><dd>
A massa id sem aliquam auctor.
</dd><dt><span class="term">
Morbi
</span></dt><dd>
Pretium nulla vel lorem.
</dd><dt><span class="term">
In
</span></dt><dd><p class="simpara">
Dictum mauris in urna.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
Vivamus
</span></dt><dd>
Fringilla mi eu lacus.
</dd><dt><span class="term">
Donec
</span></dt><dd>
Eget arcu bibendum nunc consequat lobortis.
</dd></dl></div></dd></dl></div></dd></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_horizontal_labeled_list_style"></a>17.3.1. Horizontal labeled list style</h3></div></div></div><p>The <span class="emphasis"><em>horizontal</em></span> 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:</p><pre class="screen">[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.</pre><p>Which render as:</p><div class="horizontal"><table class="horizontal" cellpadding="4px" style="border: none;"><colgroup><col /><col /></colgroup><tbody valign="top"><tr><td style="" valign="top">
<p>
<span class="strong"><strong>Lorem</strong></span>
</p>
</td><td style="" valign="top">
<p>
Fusce euismod commodo velit. Qui in magna commodo, est
labitur dolorum an. Est ne magna primis adolescens.
</p>
<pre class="literallayout">Fusce euismod commodo velit.</pre>
</td></tr><tr><td style="" valign="top">
<p>
<span class="strong"><strong>Ipsum</strong></span>
</p>
</td><td style="" valign="top">
<p>
Vivamus fringilla mi eu lacus.
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Vivamus fringilla mi eu lacus.
</li><li class="listitem">
Donec eget arcu bibendum nunc consequat lobortis.
</li></ul></div>
</td></tr><tr><td style="" valign="top">
<p>
<span class="strong"><strong>Dolor</strong></span>
</p>
</td><td style="" valign="top">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Vivamus fringilla mi eu lacus.
</li><li class="listitem">
Donec eget arcu bibendum nunc consequat lobortis.
</li></ul></div>
</td></tr></tbody></table></div><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Current PDF toolchains do not make a good job of determining
the relative column widths for horizontal labeled lists.
</li><li class="listitem">
Nested horizontal labeled lists will generate DocBook validation
errors because the <span class="emphasis"><em>DocBook XML V4.2</em></span> DTD does not permit nested
informal tables (although <a class="link" href="ch05.html#X13">DocBook XSL Stylesheets</a> and
<a class="link" href="ch05.html#X31">dblatex</a> process them correctly).
</li><li class="listitem">
The label width can be set as a percentage of the total width by
setting the <span class="emphasis"><em>width</em></span> attribute e.g. <code class="literal">width="10%"</code>
</li></ul></div></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_question_and_answer_lists"></a>17.4. Question and Answer Lists</h2></div></div></div><p>AsciiDoc comes pre-configured with a <span class="emphasis"><em>qanda</em></span> style labeled list for generating
DocBook question and answer (Q&A) lists. Example:</p><pre class="screen">[qanda]
Question one::
Answer one.
Question two::
Answer two.</pre><p>Renders:</p><div class="qandaset"><a id="idm1876"></a><table border="0" style="width: 100%;"><colgroup><col align="left" width="1%" /><col /></colgroup><tbody><tr class="question"><td align="left" valign="top"><a id="idm1877"></a><a id="idm1878"></a><p><strong>17.4.1.</strong></p></td><td align="left" valign="top"><p>
Question one
</p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
Answer one.
</p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm1882"></a><a id="idm1883"></a><p><strong>17.4.2.</strong></p></td><td align="left" valign="top"><p>
Question two
</p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
Answer two.
</p></td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_glossary_lists"></a>17.5. Glossary Lists</h2></div></div></div><p>AsciiDoc comes pre-configured with a <span class="emphasis"><em>glossary</em></span> style labeled list for
generating DocBook glossary lists. Example:</p><pre class="screen">[glossary]
A glossary term::
The corresponding definition.
A second glossary term::
The corresponding definition.</pre><p>For working examples see the <code class="literal">article.txt</code> and <code class="literal">book.txt</code> documents in
the AsciiDoc <code class="literal">./doc</code> distribution directory.</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>To generate valid DocBook output glossary lists must be located
in a section that uses the <span class="emphasis"><em>glossary</em></span> <a class="link" href="ch08.html#X93" title="8.4.1. Section markup templates">section markup template</a>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_bibliography_lists"></a>17.6. Bibliography Lists</h2></div></div></div><p>AsciiDoc comes with a predefined <span class="emphasis"><em>bibliography</em></span> bulleted list style
generating DocBook bibliography entries. Example:</p><pre class="screen">[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.</pre><p>The <code class="literal">[[[<reference>]]]</code> syntax is a bibliography entry anchor, it
generates an anchor named <code class="literal"><reference></code> and additionally displays
<code class="literal">[<reference>]</code> at the anchor position. For example <code class="literal">[[[taoup]]]</code>
generates an anchor named <code class="literal">taoup</code> that displays <code class="literal">[taoup]</code> at the
anchor position. Cite the reference from elsewhere your document using
<code class="literal"><<taoup>></code>, this displays a hyperlink (<code class="literal">[taoup]</code>) to the
corresponding bibliography entry anchor.</p><p>For working examples see the <code class="literal">article.txt</code> and <code class="literal">book.txt</code> documents in
the AsciiDoc <code class="literal">./doc</code> distribution directory.</p><div class="note" style="margin-left: 0; margin-right: 10%;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/icons/note.png" /></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>To generate valid DocBook output bibliography lists must be
located in a <a class="link" href="ch08.html#X93" title="8.4.1. Section markup templates">bibliography section</a>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X15"></a>17.7. List Item Continuation</h2></div></div></div><p>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 <span class="emphasis"><em>list continuation</em></span> (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).</p><p>Here are some examples of list item continuations: list item one
contains multiple continuations; list item two is continued with an
<a class="link" href="ch16.html#X29" title="16.10. Open Blocks">OpenBlock</a> containing multiple elements:</p><pre class="screen">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.
--</pre><p>Renders:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p class="simpara">
List item one.
</p><p class="simpara">List item one continued with a second paragraph followed by an
Indented block.</p><pre class="literallayout">$ ls *.sh
$ mv *.sh ~/tmp</pre><p class="simpara">List item continued with a third paragraph.</p></li><li class="listitem"><p class="simpara">
List item two continued with an open block.
</p><p class="simpara">This paragraph is part of the preceding list item.</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p class="simpara">
This list is nested and does not require explicit item continuation.
</p><p class="simpara">This paragraph is part of the preceding list item.</p></li><li class="listitem">
List item b.
</li></ol></div><p class="simpara">This paragraph belongs to item two of the outer list.</p></li></ol></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch16.html"><img src="images/icons/prev.png" alt="Prev" /></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch18.html"><img src="images/icons/next.png" alt="Next" /></a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/icons/home.png" alt="Home" /></a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
|
