Fri Oct 25 01:36:33 2013 comments

Lists

List types

  • Bulleted lists. Also known as itemized or unordered lists.

  • Numbered lists. Also called ordered lists.

  • Labeled lists. Sometimes called variable or definition lists.

  • Callout lists (a list of callout annotations).

List behavior

  • List item indentation is optional and does not determine nesting, indentation does however make the source more readable.

  • Another list or a literal paragraph immediately following a list item will be implicitly included in the list item; use list item continuation to explicitly append other block elements to a list item.

  • A comment block or a comment line block macro element will terminate a list — use inline comment lines to put comments inside lists.

  • The listindex intrinsic attribute 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.

Bulleted 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.

Numbered Lists

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:

  • Praesent eget purus quis magna eleifend eleifend.

    1. Fusce euismod commodo velit.

      1. Fusce euismod commodo velit.

      2. Vivamus fringilla mi eu lacus.

      3. Donec eget arcu bibendum nunc consequat lobortis.

    2. Vivamus fringilla mi eu lacus.

      1. Fusce euismod commodo velit.

      2. 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.

    1. Fusce euismod commodo velit.

    2. Vivamus fringilla mi eu lacus.

      1. Fusce euismod commodo velit.

      2. Vivamus fringilla mi eu lacus.

    3. Donec eget arcu bibendum nunc consequat lobortis.

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.

Tip

 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 Lists

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:

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.

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.

Note

  • 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%"

Question and Answer Lists

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:

  1. Question one

    Answer one.

  2. Question two

    Answer two.

Glossary Lists

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.

Note

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

Bibliography Lists

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.

Note

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

List Item Continuation

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:

  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.

    1. This list is nested and does not require explicit item continuation.

      This paragraph is part of the preceding list item.

    2. List item b.

    This paragraph belongs to item two of the outer list.

Footnotes

The shipped AsciiDoc configuration includes three footnote inline macros:

footnote:[<text>]

Generates a footnote with text <text>.

footnoteref:[<id>,<text>]

Generates a footnote with a reference ID <id> and text <text>.

footnoteref:[<id>]

Generates a reference to the footnote with ID <id>.

The footnote text can span multiple lines.

The xhtml11 and html5 backends render footnotes dynamically using JavaScript; html4 outputs do not use JavaScript and leave the footnotes inline; docbook footnotes are processed by the downstream DocBook toolchain.

Example footnotes:

A footnote footnote:[An example footnote.];
a second footnote with a reference ID footnoteref:[note2,Second footnote.];
finally a reference to the second footnote footnoteref:[note2].

Renders:

A footnote
[An example footnote.]
; a second footnote with a reference ID
[Second footnote.]
; finally a reference to the second footnote
[note2]
.

Indexes

The shipped AsciiDoc configuration includes the inline macros for generating DocBook index entries.

indexterm:[<primary>,<secondary>,<tertiary>]
(((<primary>,<secondary>,<tertiary>)))

This inline macro generates an index term (the <secondary> and <tertiary> positional attributes are optional). Example: indexterm:[Tigers,Big cats] (or, using the alternative syntax (((Tigers,Big cats))). Index terms that have secondary and tertiary entries also generate separate index terms for the secondary and tertiary entries. The index terms appear in the index, not the primary text flow.

indexterm2:[<primary>]
((<primary>))

This inline macro generates an index term that appears in both the index and the primary text flow. The <primary> should not be padded to the left or right with white space characters.

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

Note

 Index entries only really make sense if you are generating DocBook markup — DocBook conversion programs automatically generate an index at the point an Index section appears in source document.

Callouts

Callouts are a mechanism for annotating verbatim text (for example: source code, computer output and user input). Callout markers are placed inside the annotated text while the actual annotations are presented in a callout list after the annotated text. Here’s an example:

 .MS-DOS directory listing
 -----------------------------------------------------
 10/17/97   9:04         <DIR>    bin
 10/16/97  14:11         <DIR>    DOS            <1>
 10/16/97  14:40         <DIR>    Program Files
 10/16/97  14:46         <DIR>    TEMP
 10/17/97   9:04         <DIR>    tmp
 10/16/97  14:37         <DIR>    WINNT
 10/16/97  14:25             119  AUTOEXEC.BAT   <2>
  2/13/94   6:21          54,619  COMMAND.COM    <2>
 10/16/97  14:25             115  CONFIG.SYS     <2>
 11/16/97  17:17      61,865,984  pagefile.sys
  2/13/94   6:21           9,349  WINA20.386     <3>
 -----------------------------------------------------

 <1> This directory holds MS-DOS.
 <2> System startup code for DOS.
 <3> Some sort of Windows 3.1 hack.

Which renders:

MS-DOS directory listing

10/17/97   9:04         <DIR>    bin
10/16/97  14:11         <DIR>    DOS            <1>
10/16/97  14:40         <DIR>    Program Files
10/16/97  14:46         <DIR>    TEMP
10/17/97   9:04         <DIR>    tmp
10/16/97  14:37         <DIR>    WINNT
10/16/97  14:25             119  AUTOEXEC.BAT   <2>
 2/13/94   6:21          54,619  COMMAND.COM    <2>
10/16/97  14:25             115  CONFIG.SYS     <2>
11/16/97  17:17      61,865,984  pagefile.sys
 2/13/94   6:21           9,349  WINA20.386     <3>

  1. This directory holds MS-DOS.

  2. System startup code for DOS.

  3. Some sort of Windows 3.1 hack.

Explanation

  • The callout marks are whole numbers enclosed in angle brackets —  they refer to the correspondingly numbered item in the following callout list.

  • By default callout marks are confined to LiteralParagraphs, LiteralBlocks and ListingBlocks (although this is a configuration file option and can be changed).

  • Callout list item numbering is fairly relaxed — list items can start with <n>, n> or > where n is the optional list item number (in the latter case list items starting with a single > character are implicitly numbered starting at one).

  • Callout lists should not be nested.

  • Callout lists cannot be used within tables.

  • Callout lists start list items hard against the left margin.

  • If you want to present a number inside angle brackets you’ll need to escape it with a backslash to prevent it being interpreted as a callout mark.

Note

 Define the AsciiDoc icons attribute (for example using the -a icons command-line option) to display callout icons.

Implementation Notes

Callout marks are generated by the callout inline macro while callout lists are generated using the callout list definition. The callout macro and callout list are special in that they work together. The callout inline macro is not enabled by the normal macros substitutions option, instead it has its own callouts substitution option.

The following attributes are available during inline callout macro substitution:

{index}

The callout list item index inside the angle brackets.

{coid}

An identifier formatted like CO<listnumber>-<index> that uniquely identifies the callout mark. For example CO2-4 identifies the fourth callout mark in the second set of callout marks.

The {coids} attribute can be used during callout list item substitution — it is a space delimited list of callout IDs that refer to the explanatory list item.

Including callouts in included code

You can annotate working code examples with callouts — just remember to put the callouts inside source code comments. This example displays the test.py source file (containing a single callout) using the source (code highlighter) filter:

AsciiDoc source

 [source,python]
 -------------------------------------------
 \include::test.py[]
 -------------------------------------------

 <1> Print statement.

Included test.py source

print 'Hello World!'   # <1>
comments powered by Disqus