AsciiDoc User Guide

$ tar -xzf asciidoc-7.1.2.tar.gz

The tarball contains the executable asciidoc.py script, configuration files, examples and documentation. See also Packager Notes.

Test out asciidoc by changing to the AsciiDoc application directory and converting the User Guide document (./doc/asciidoc.txt) to XHTML (./doc/asciidoc.html):

$ ./asciidoc.py doc/asciidoc.txt

By convention .txt file extensions are used for AsciiDoc document files.

The best way to quickly get a feel for AsciiDoc is to view the AsciiDoc web site and/or distributed examples:

Used for short documents, articles and general documentation. See the AsciiDoc distribution ./doc/article.txt example.

Books share the same format as articles; in addition there is the option to add level 0 book part sections.

Book documents will normally be used to produce DocBook output since DocBook processors can automatically generate footnotes, table of contents, list of tables, list of figures, list of examples and indexes.

AsciiDoc markup supports standard DocBook frontmatter and backmatter special sections (dedication, preface, bibliography, glossary, index, colophon) plus footnotes and index entries.

Used to generate UNIX manual pages. AsciiDoc manpage documents observe special header title and section naming conventions — see the Manpage Documents section for details.

See also the asciidoc(1) man page source (./doc/asciidoc.1.txt) from the AsciiDoc distribution.

AsciiDoc generates the following DocBook document types: article, book and refentry (corresponding to the AsciiDoc article, book and manpage document types).

DocBook documents are not designed to be viewed directly. Most Linux distributions come with conversion tools (collectively called a toolchain) for converting DocBook files to presentation formats such as Postscript, HTML, PDF, DVI, roff (the native man page format), HTMLHelp, JavaHelp and text.

The default asciidoc(1) backend is xhtml11 which generates XHTML 1.1 markup styled with CSS2. Default output file have a .html extension. xhtml11 document generation is influenced by the following attributes (the default behavior is to generate XHTML with no section numbers, embedded CSS and no linked admonition icon images):

Stylesheets

AsciiDoc XHTML output is styled using CSS2 stylesheets from the distribution ./stylesheets/ directory.

Important

Browser CSS support varies from browser to browser. The shipped examples work well on IE6, Firefox 1.0 and up, Mozilla 1.7 and up, Opera 8 and Konqueror 3.4 but have not been tested on other browsers. All browsers have CSS quirks, but Microsoft's IE6 has so many omissions and errors that in order to separate clean CSS from the IE6 workarounds a separate xhtml11-quirks.css stylesheet is used. If you're not viewing your documents with IE6 then the quirks stylesheet can be omitted using the —attribute=quirks! command-line option.

Default xhtml11 stylesheets:

./stylesheets/xhtml11.css

The main stylesheet.

./stylesheets/xhtml11-manpage.css

Tweaks for manpage document type generation.

./stylesheets/xhtml11-quirks.css

Stylesheet modifications to work around IE6 browser incompatibilities.

Use the theme attribute to select and alternative set of stylesheets. For example, the command-line option -a theme=foo will use stylesheets foo.css, foo-manpage.css and foo-quirks.css.

This backend generates plain (unstyled) HTML 4.01 Transitional markup.

	Warning
	The AsciiDoc linuxdoc backend is still distributed but is no longer being actively developed or tested with new AsciiDoc releases (the last supported release was AsciiDoc 6.0.3).

The default output file name extension is .sgml.

Block elements consist of one or more lines of text and may contain other block elements.

The AsciiDoc block structure can be informally summarized ^[1] as follows:

Document      ::= (Header?,Preamble?,Section*)
Header        ::= (Title,(AuthorLine,RevisionLine?)?)
AuthorLine    ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
RevisionLine  ::= (Revision?,Date)
Preamble      ::= (SectionBody)
Section       ::= (Title,SectionBody?,(Section)*)
SectionBody   ::= ((BlockTitle?,Block)|BlockMacro)+
Block         ::= (Paragraph|DelimitedBlock|List|Table)
List          ::= (BulletedList|NumberedList|LabeledList|CalloutList)
BulletedList  ::= (ListItem)+
NumberedList  ::= (ListItem)+
CalloutList   ::= (ListItem)+
LabeledList   ::= (ItemLabel+,ListItem)+
ListItem      ::= (ItemText,(List|ListParagraph|ListContinuation)*)
Table         ::= (Ruler,TableHeader?,TableBody,TableFooter?)
TableHeader   ::= (TableRow+,TableUnderline)
TableFooter   ::= (TableRow+,TableUnderline)
TableBody     ::= (TableRow+,TableUnderline)
TableRow      ::= (TableData+)

Where:

The Header is optional but must start on the first line of the document and must begin with a document title. Optional Author and Revision lines immediately follow the title.

The author line contains the author's name optionally followed by the author's email address. The author's name consists of a first name followed by optional middle and last names separated by white space. The email address is last and must be enclosed in angle <> brackets. Author names cannot contain angle <> bracket characters.

The optional document header revision line should immediately follow the author line. The revision line can be one of two formats:

The document heading is separated from the remainder of the document by one or more blank lines.

Here's an example AsciiDoc document header:

Writing Documentation using AsciiDoc
====================================
Stuart Rackham <srackham@methods.co.nz>
v2.0, February 2003

You can override or set header parameters by passing revision, data, email, author, authorinitials, firstname and lastname attributes using the asciidoc(1) -a (—attribute) command-line option. For example:

$ asciidoc -a date=2004/07/27 article.txt

Attributes can also be added to the header for substitution in the header template with Attribute Entry elements.

The Preamble is an optional untitled section body between the document Header and the first Section title.

AsciiDoc supports five section levels 0 to 4 (although only book documents are allowed to contain level 0 sections). Section levels are delineated by the section titles.

Sections are translated using configuration file markup templates. To determine which configuration file template to use AsciiDoc first searches for special section titles in the [specialsections] configuration entries, if not found it uses the [sect<level>] template.

The -n (—section-numbers) command-line option auto-numbers HTML outputs (DocBook line numbering is handled automatically by the DocBook toolchain commands).

<pattern>=<name>

Preface                    (book documents only)
Abstract                   (article documents only)
Dedication                 (book documents only)
Glossary
Bibliography|References
Colophon                   (book documents only)
Index
Appendix [A-Z][:.] <title>

Inline document elements are used to markup character formatting and various types of text substitution. Inline elements and inline element syntax is defined in the asciidoc(1) configuration files.

Here is a list of AsciiDoc inline elements in the (default) order in which they are processed:

Words and phrases can be formatted by enclosing inline text with quote characters:

Quoted text can be prefixed with an attribute list. Currently the only use made of this feature is to allow the font color, background color and size to be specified (XHTML/HTML only, not DocBook) using the first three positional attribute arguments. The first argument is the text color; the second the background color; the third is the font size. Colors are valid CSS colors and the font size is a number which treated as em units. Here are some examples:

[red]##Red text##.
[,yellow]*bold text on a yellow background*.
[blue,#b0e0e6]`Monospaced blue text on a light blue background`
[,,2]##Double sized text##.

New quotes can be defined by editing asciidoc(1) configuration files. See the Configuration Files section for details.

This special text quoting mechanism passes inline text to the output document without the usual substitutions. There are two flavors:

Put carets on either side of the text to be superscripted, put tildes on either side of text to be subscripted. For example, the following line:

e^{amp}#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
and ~some sub text~

Is rendered like:

e^πi+1 = 0. H₂O and x¹⁰. Some ^{super text} and _{some sub text}

If you want to display caret (^) or tilde (~) characters you need to ensure only one per line otherwise they'll be misinterpreted as superscripting and subscripting.

Superscripts and subscripts are implemented as Replacements substitutions.

A plus character preceded by at least one space character at the end of a line forces a line break. It generates an HTML line break (<br />) tag. Line breaks are ignored when outputting to DocBook since it has no line break element.

A line of three or more apostrophe characters will generate an HTML ruler (<hr />) tag. Ignored when generating non-HTML output formats.

By default tab characters input files will translated to 8 spaces. Tab expansion is set with the tabsize entry in the configuration file [miscellaneous] section and can be overridden in the include block macro by setting a tabsize attribute in the macro's attribute list. For example:

include::addendum.txt[tabsize=2]

The tab size can also be set using the attribute command-line option, for example —attribute=tabsize=4

The following replacements are defined in the default AsciiDoc configuration:

(C) copyright, (TM) trademark, (R) registered trademark,
-- em dash, ... ellipsis.

Which are rendered as:

© copyright, ™ trademark, ® registered trademark, — em dash, … ellipsis.

The Configuration Files section explains how to configure your own replacements.

Words defined in [specialwords] configuration file sections are automatically marked up without having to be explicitly notated.

The Configuration Files section explains how to add and replace special words.

A two line title consists of a title line, starting hard against the left margin, and an underline. Section underlines consist a repeated character pairs spanning the width of the preceding title (give or take up to three characters):

The default title underlines for each of the document levels are:

Level 0 (top level):     ======================
Level 1:                 ----------------------
Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level):  ++++++++++++++++++++++

Examples:

Level One Section Title
-----------------------

Level 2 Subsection Title
~~~~~~~~~~~~~~~~~~~~~~~~

One line titles consist of a line starting with one or more equals characters (the number of equals corresponds the section level) followed by a space followed by the title text. Here are some examples:

= Document Title (level 0)
== Section title (level 1)
=== Section title (level 2)
==== Section title (level 3)
===== Section title (level 4)

The one-line title syntax can be changed by editing the configuration file [titles] section sect0…sect4 entries.

A Default paragraph ([paradef-default]) consists of one or more non-blank lines of text. The first line must start hard against the left margin (no intervening white space). The processing expectation of the default paragraph type is that of a normal paragraph of text.

The verse paragraph style is useful for lyrics and poems. For example:

[verse]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

Renders:

A Literal paragraph ([paradef-literal]) consists of one or more lines of text, where the first line is indented by one or more space or tab characters. Literal paragraphs are rendered verbatim in a monospaced font usually without any distinguishing background or border. There is no text formatting or substitutions within Literal paragraphs apart from Special Characters and Callouts. For example:

  Consul *necessitatibus* per id,
  consetetur, eu pro everti postulant
  homero verear ea mea, qui.

Renders:

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

Tip, Note, Important, Warning and Caution paragraph definitions support the corresponding DocBook admonishment elements — just write a normal paragraph but place NOTE:, TIP:, IMPORTANT:, WARNING: or CAUTION: as the first word of the paragraph. For example:

NOTE: This is an example note.

or the alternative syntax:

[NOTE]
This is an example note.

Renders:

	Note
	This is an example note.

	Tip
	If your admonition is more than a single paragraph use an admonition block instead.

Admonition Icons and Captions

	Note
	Admonition customization with icons, iconsdir, icon and caption attributes does not apply when generating DocBook output. If you are going the DocBook route then the a2x(1) —no-icons and —icons-dir options can be used to set the appropriate XSL Stylesheets parameters.

By default the asciidoc(1) xhtml11 and html4 backends generate text captions instead of icon image links. To generate links to icon images define the icons attribute, for example using the -a icons command-line option.

The iconsdir attribute sets the location of linked icon images.

You can override the default icon image using the icon attribute to specify the path of the linked image. For example:

[icon="./images/icons/wink.png"]
NOTE: What lovely war.

Use the caption attribute to customise the admonition captions (not applicable to docbook backend). The following example suppresses the icon image and customizes the caption of a NOTE admonition (undefining the icons attribute with icons=None is only necessary if admonition icons have been enabled):

[icons=None, caption="My Special Note"]
NOTE: This is my special note.

This subsection also applies to Admonition Blocks.

AsciiDoc ships with a number of predefined DelimitedBlocks (see the asciidoc.conf configuration file in the asciidoc(1) program directory):

Predefined delimited block underlines:

CommentBlock:     //////////////////////////
PassthroughBlock: ++++++++++++++++++++++++++
ListingBlock:     --------------------------
LiteralBlock:     ..........................
SidebarBlock:     **************************
QuoteBlock:       __________________________

ListingBlocks are rendered verbatim in a monospaced font, they retain line and whitespace formatting and often distinguished by a background or border. There is no text formatting or substitutions within Listing blocks apart from Special Characters and Callouts. Listing blocks are often used for code and file listings.

Here's an example:

--------------------------------------
#include <stdio.h>

int main() {
        printf("Hello World!\n");
        exit(0);
}
--------------------------------------

Which will be rendered like:

#include <stdio.h>

int main() {
        printf("Hello World!\n");
        exit(0);
}

LiteralBlocks behave just like LiteralParagraphs except you don't have to indent the contents.

LiteralBlocks can be used to resolve list ambiguity. If the following list was just indented it would be processed as an ordered list (not an indented paragraph):

....................
1. Item 1
2. Item 2
....................

Renders:

1. Item 1
2. Item 2

The literal block has a verse style (useful for lyrics and poems). For example:

[verse]
......................................
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

Qui in magna commodo, est labitur
dolorum an. Est ne *magna primis
adolescens*.
......................................

Renders:

A sidebar is a short piece of text presented outside the narrative flow of the main text. The sidebar is normally presented inside a bordered box to set it apart from the main text.

The sidebar body is treated like a normal section body.

Here's an example:

.An Example Sidebar
************************************************
Any AsciiDoc SectionBody element (apart from
SidebarBlocks) can be placed inside a sidebar.
************************************************

Which will be rendered like:

The contents of CommentBlocks are not processed; they are useful for annotations and for excluding new or outdated content that you don't want displayed. Here's and example:

//////////////////////////////////////////
CommentBlock contents are not processed by
asciidoc(1).
//////////////////////////////////////////

See also Comment Lines.

PassthroughBlocks are for backend specific markup, text is only subject to attribute and macro substitution. PassthroughBlock content will generally be backend specific. Here's an example:

++++++++++++++++++++++++++++++++++++++
<table border="1"><tr>
  <td>Cell 1</td>
  <td>Cell 2</td>
</tr></table>
++++++++++++++++++++++++++++++++++++++

QuoteBlocks are used for quoted passages of text. attribution and citetitle named attributes specify the author and source of the quote (they are equivalent to positional attribute list entries 1 and 2 respectively). Both attributes are optional and the block body is treated like a SectionBody. For example:

[Bertrand Russell, The World of Mathematics (1956)]
____________________________________________________________________
A good notation has subtlety and suggestiveness which at times makes
it almost seem like a live teacher.
____________________________________________________________________

Which is rendered as:

In this example unquoted positional attributes have been used, the following quoted positional and named attributes are equivalent (if the attribute list contained commas then quoting would have been mandatory):

["Bertrand Russell","The World of Mathematics (1956)"]
[attribution="Bertrand Russell",citetitle="The World of Mathematics (1956)"]

You can render poems and lyrics with a combination of Quote and Literal blocks. For example:

[William Blake,from Auguries of Innocence]
_____________________________________________________________________
[verse]
.....................................................................
To see a world in a grain of sand,
And a heaven in a wild flower,
Hold infinity in the palm of your hand,
And eternity in an hour.
.....................................................................
_____________________________________________________________________

Which is rendered as:

ExampleBlocks encapsulate the DocBook Example element and are used for, well, examples. Example blocks can be titled by preceding them with a BlockTitle. DocBook toolchains normally number examples and generate a List of Examples backmatter section.

Example blocks are delimited by lines of equals characters and you can put any block elements apart from Titles, BlockTitles and Sidebars) inside an example block. For example:

.An example
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
=====================================================================

Renders:

The title prefix that is automatically inserted by asciidoc(1) can be customized with the caption attribute (xhtml11 and html4 backends). For example

[caption="Example 1: "]
.An example with a custom caption
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
=====================================================================

The ExampleBlock definition includes a set of admonition styles (NOTE, TIP, IMPORTANT, WARNING, CAUTION) for generating admonition blocks (admonitions containing more than just a simple paragraph). Just precede the ExampleBlock with an attribute list containing the admonition style name. For example:

[NOTE]
.A NOTE block
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.

. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
  .. Fusce euismod commodo velit.
  .. Vivamus fringilla mi eu lacus.
. Donec eget arcu bibendum
  nunc consequat lobortis.
=====================================================================

Renders:

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

See also Admonition Icons and Captions.

Bulleted list items start with a dash or an asterisk followed by a space or tab character. Bulleted list syntaxes are:

- List item.
* List item.

Numbered list items start with an optional number or letter followed by a period followed by a space or tab character. List numbering is optional. Numbered list syntaxes are:

.  Integer numbered list item.
1. Integer numbered list item with optional numbering.
.. Lowercase letter numbered list item.
a. Lowercase letter numbered list item with optional numbering.

Here are some examples:

- 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.
    .. Fusce euismod commodo velit.
    .. Vivamus fringilla mi eu lacus.
  . Donec eget arcu bibendum nunc consequat lobortis.
- 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.
  3. Donec eget arcu bibendum nunc consequat lobortis.
  4. Nam fermentum mattis ante.

Which render as:

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

An item label begins a line with an alphanumeric character hard against the left margin and ends with a double colon :: or semi-colon ;;.

The list item text consists of one or more lines of text starting on the line immediately following the label and can be followed by nested List or ListParagraph elements. Item text can be optionally indented.

Here are some examples:

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.

Which render as:

Horizontal labeled lists differ from vertical labeled lists in that the label and the list item sit side-by-side as opposed to the item under the label. Item text must begin on the same line as the label.

Here are some examples:

*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*:: Donec eget arcu bibendum nunc consequat lobortis.
  Sit munere ponderum dignissim et. Minim luptatum et vel.

Which render as:

Fusce euismod commodo velit.

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

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:

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.

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.

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:

A List block is a special delimited block containing a list element.

The List Block is useful for:

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

b. List item b.

This paragraph belongs to list item b.
--
+
This paragraph belongs to item 1.

2. Item 2 of the outer list.

Renders:

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 it's own callouts substitution option.

The following attributes are available during inline callout macro substitution:

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.

Inline Macros occur in an inline element context. Predefined Inline macros include URLs, image and link macros.

URLs

Standard http, https, ftp, file and mailto URLs are rendered using predefined inline macros.

The default AsciiDoc inline macro syntax is very similar to a URL: all you need to do is append an attribute list containing an optional caption immediately following the URL. If no caption text is provided the URL itself is displayed.

Here are some examples:

http://www.methods.co.nz/asciidoc/[The AsciiDoc home page]
mailto:joe.bloggs@foobar.com[email Joe Bloggs]
mailto:joe.bloggs@foobar.com[]

Which are rendered:

The AsciiDoc home page

email Joe Bloggs

joe.bloggs@foobar.com

	Tip
	If the <target> necessitates space characters they should be replaced by %20. For example large%20image.png.

[[<id>,<xreflabel>]]
anchor:<id>[<xreflabel>]

[[X1]]

<<<id>,<caption>>>
xref:<id>[<caption>]

<<X21,attribute lists>>

link:<target>[<caption>]

link:downloads/foo.zip[download foo.zip]

image:<target>[<attributes>]

A Block macro reference must be contained in a single line separated either side by a blank line or a block delimiter.

Block macros behave just like Inline macros, with the following differences:

[[X30]]

image::<target>[<attributes>]

.Main circuit board
image::images/layout.png[J14P main circuit board]

.Main circuit board
[caption="Figure 2:"]
image::images/layout.png[J14P main circuit board]

// This is a comment.

System macros are block macros that perform a predefined task which is hardwired into the asciidoc(1) program.

 include::chapter1.txt[tabsize=4]

ifdef::<attribute>[]
:
endif::<attribute>[]

ifndef::<attribute>[]
:
endif::<attribute>[]

------------------
sys::[ls -l *.txt]
------------------

[admonitionparagraph]
template::[admonitionblock]

Each entry in the configuration [macros] section is a macro definition which can take one of the following forms:

<pattern> is a Python regular expression and <name> is the name of a markup template. If <name> is omitted then it is the value of the regular expression match group name.

The following annotated examples are all you'll need to start creating your own tables.

The only non-obvious thing you'll need to remember are the column stop characters:

Simple table:

 `---`---
 1   2
 3   4
 5   6
 --------

Output:

Table with title, header and footer:

 .An example table
 [grid="all"]
 '---------.--------------
 Column 1   Column 2
 -------------------------
 1          Item 1
 2          Item 2
 3          Item 3
 -------------------------
 6          Three items
 -------------------------

Output:

Four columns totaling 15% of the pagewidth, CSV data:

[frame="all"]
````~15
1,2,3,4
a,b,c,d
A,B,C,D
~~~~~~~~

Output:

A table with a numeric ruler and externally sourced CSV data:

 [frame="all", grid="all"]
 .15`20`25`20`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ID,Customer Name,Contact Name,Customer Address,Phone
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 include::customers.csv[]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Renders:

This sub-section details the AsciiDoc table format.

Table  ::= (Ruler,Header?,Body,Footer?)
Header ::= (Row+,Underline)
Footer ::= (Row+,Underline)
Body   ::= (Row+,Underline)
Row    ::= (Data+)

A table is terminated when the table underline is followed by a blank line or an end of file. Table underlines which separate table headers, bodies and footers should not be followed by a blank line.

ruler ::= ((colstop,(colwidth,fillchar+)?)+, fillchar+, tablewidth?

( N / M ) * pagewidth

( N / textwidth ) * pagewidth

A document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

The first manpage section is mandatory, must be titled NAME and must contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

printf, fprintf, sprintf - print formatted output

The second manpage section is mandatory and must be titled SYNOPSIS.

Configuration files contain named sections. Each section begins with a section name in square brackets []. The section body consists of the lines of text between adjacent section headings.

	Tip
	When creating custom configuration files you only need to include the sections and entries that differ from the default configuration.

	Tip
	The best way to learn about configuration files is to read the default configuration files in the AsciiDoc distribution in conjunction with asciidoc(1) output files. You can view configuration file load sequence by turning on the asciidoc(1) -v (—verbose) command-line option.

Markup template sections supply backend markup for translating AsciiDoc elements. Since the text is normally backend dependent you'll find these sections in the backend specific configuration files. A markup template section body can contain:

The document content placeholder is a single | character and is replaced by text from the source element. Use the {brvbar} attribute reference if you need a literal | character in the template.

AsciiDoc reserves the following predefined special section names for specific purposes:

Each line of text in a special section is a section entry. Section entries share the following syntax:

Miscellaneous

The optional [miscellaneous] section specifies the following name=value options:

newline

Output file line termination characters. Can include any valid Python string escape sequences. The default value is \r\n (carriage return, line feed). Should not be quoted or contain explicit spaces (use \x20 instead). For example:

$ asciidoc -a 'newline=\n' -b docbook mydoc.txt

outfilesuffix

The default extension for the output file, for example outfilesuffix=.html. Defaults to backend name.

tabsize

The number of spaces to expand tab characters, for example tabsize=4. Defaults to 8. A tabsize of zero suppresses tab expansion (useful when piping included files through block filters). Included files can override this option using the tabsize attribute.

textwidth, pagewidth, pageunits

These global table related options are documented in the Table Configuration File Definitions sub-section.

	Note
	[miscellaneous] configuration file entries can be set using the asciidoc(1) -a (—attribute) command-line option.

emphasis=<em>|</em>

special_character=translated_characters

<=&lt;

[quotes]
__=underline

[tags]
underline=<u>|</u>

[quotes]
((|))=gui

[specialwords]
strongwords=NOTE: IMPORTANT:

[strongwords]
<strong>{words}</strong>

find_pattern=replacement_text

#NEW#=image:./images/smallnew.png[New!]
\\#NEW#=#NEW#

Configuration files have a .conf file name extension; they are loaded implicitly (using predefined file names and locations) or explicitly (using the asciidoc(1) -f (—conf-file) command-line option).

Implicit configuration files are loaded from the following directories in the following order:

The following implicit configuration files from each of the above locations are loaded in the following order:

Where <backend> and <doctype> are values specified by the asciidoc(1) -b (—backend) and -d (—doctype) command-line options.

Finally, configuration files named like the source file will be automatically loaded if they are found in the source file directory. For example if the source file is mydoc.txt and the —backend=html4 option is used then asciidoc(1) will look for mydoc.conf and mydoc-html4.conf in that order.

Implicit configuration files that don't exist will be silently skipped.

The user can explicitly specify additional configuration files using the asciidoc(1) -f (—conf-file) command-line option. The -f option can be specified multiple times, in which case configuration files will be processed in the order they appear on the command-line.

For example, when we translate our AsciiDoc document mydoc.txt with:

$ asciidoc -f extra.conf mydoc.txt

Configuration files (if they exist) will be processed in the following order:

	Tip
	Use the asciidoc(1) -v (—verbose) command-line option to see which configuration files are loaded and the order in which they are loaded.

Macros calls are suffixed with an attribute list. The list may be empty but it cannot be omitted. List entries are used to pass attribute values to macro markup templates.

An attribute list on a line by itself constitutes an AttributeList block element, it's function is to parameterize the following block element. The list attributes are passed to the next block element for markup template substitution.

Simple attribute references take the form {<name>}. If the attribute name is defined its text value is substituted otherwise the line containing the reference is dropped from the output.

Additional parameters are used in conjunction with the attribute name to calculate a substitution value. Conditional attribute references take the following forms:

System attribute references generate the attribute text value by executing a predefined action that is parameterized by a single argument. The syntax is {<action>:<argument>}.

A style is a set of block attributes bundled as a single named attribute. The following example defines a style named verbatim:

verbatim-style=template="literalblock",subs="verbatim",font="monospaced"

All style parameter names must be suffixed with -style and the style parameter value is in the form of a list of named attributes.

Paragraph translation is controlled by [paradef*] configuration file section entries. Users can define new types of paragraphs and modify the behavior of existing types by editing AsciiDoc configuration files.

Here is the shipped Default paragraph definition:

[paradef-default]
delimiter=(?P<text>\S.*)
template=paragraph

The Default paragraph definition has a couple of special properties:

Paragraph specific block parameter notes:

DelimitedBlock specific block definition notes:

presubs, postsubs and filter entries are meaningless when sectionbody, skip or list options are set.

DelimitedBlock processing proceeds as follows:

	Tip
	Attribute expansion is performed on the block filter command before it is executed, this is useful for passing arguments to the filter.

List behavior and syntax is determined by [listdef*] configuration file sections. The user can change existing list behavior and add new list types by editing configuration files.

List specific block definition notes:

The tag entries map the AsciiDoc list structure to backend markup; see the AsciiDoc distribution .conf configuration files for examples.

Table behavior and syntax is determined by [tabledef*] configuration file sections. The user can change existing list behavior and add new list types by editing configuration files.

Table specific block definition notes:

Table behaviour is also influenced by the following [miscellaneous] configuration file entries:

If the filter command does not specify a directory path then asciidoc(1) searches for the command:

Since filters are normally accompanied by a configuration file containing an example filter Paragraph or filter DelimitedBlock definition.

asciidoc(1) auto-loads all .conf files found in the user's $HOME/.asciidoc/filters directory and the asciidoc(1) ./filters subdirectory.

AsciiDoc comes with a simple minded code-filter for highlighting source code keywords and comments. You'll find this example in the AsciiDoc distribution ./filters subdirectory (read the ./filters/code-filter-readme.txt file for instructions).

The following example highlights Python keywords in the block's content:

.Code filter example
[python]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
''' A multi-line
    comment.'''
def sub_word(mo):
    ''' Single line comment.'''
    word = mo.group('word')   # Inline comment
    if word in keywords[language]:
        return quote + word + quote
    else:
        return word
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Outputs:

''' A multi-line
    comment.'''
def sub_word(mo):
    ''' Single line comment.'''
    word = mo.group('word')     # Inline comment
    if word in keywords[language]:
        return quote + word + quote
    else:
        return word

	Note
	A full featured source code highlighter filter (source-highlight-filter.conf) using GNU source-highlight can be found in the AsciiDoc distribution ./examples/source-highlight-filter directory. GNU source-highlight generates nicely formatted source code for most common programming languages.

One of the biggest hurdles for new users seems to be using a DocBook XML toolchain. a2x(1) can help — it's toolchain wrapper command that will generate XHTML (chunked and unchunked), PDF, man page, HTML Help and text file outputs from an AsciiDoc text file. a2x(1) does all the grunt work associated with generating and sequencing the toolchain commands and managing intermediate and output files. a2x(1) also optionally deploys admonition and navigation icons and a CSS stylesheet. See the a2x(1) man page for more details. All you need is xsltproc(1), DocBook XSL Stylesheets and optionally FOP (if you want PDF) or lynx(1) (if you want text).

The following example generates doc/quickstart.pdf from the AsciiDoc doc/quickstart.txt source file:

$ a2x -f pdf doc/quickstart.txt

See the a2x(1) man page for details.

	Tip
	Use the —verbose command-line option to view executed toolchain commands.

You will have noticed that the distributed PDF, HTML and HTML Help documentation files (for example ./doc/asciidoc.html) are not the plain outputs produced using the default DocBook XSL Stylesheets configuration. This is because they have been processed using customized DocBook XSL Stylesheet drivers along with (in the case of HTML outputs) the custom ./stylesheets/docbook.css CSS stylesheet.

You'll find the customized DocBook XSL drivers along with additional documentation in the distribution ./docbook-xsl directory. The examples that follow are executed from the distribution documentation (./doc) directory.

If you want to see how the complete documentation set is processed take a look at the A-A-P script ./doc/main.aap.

XSL Stylesheets can be used to generate FO (Formatting Object) files, which in turn can be used to produce PDF files using the Apache Formatting Object Processor program (FOP). The FOP home page is at http://xml.apache.org/fop/.

As of version 0.20.5 installation and configuration of FOP is a manual process. You also need a working Java Runtime to run FOP. You'll find FOP and Java installation information in the appendices.

	Tip
	Once you've got FOP installed use the AsciiDoc a2x(1) toolchain wrapper to generate PDF files from AsciiDoc source.

The Adobe PDF Specification states that the following 14 fonts should be available to every PDF reader: Helvetica (normal, bold, italic, bold italic), Times (normal, bold, italic, bold italic), Courier (normal, bold, italic, bold italic), Symbol and ZapfDingbats. Non-standard fonts should be embedded in the distributed document.

To change, delete or add your own help topics edit a help.conf file. The file location will depend on whether you want the topics to apply to all users, to a single user or to a single project.

Help topics are stored help.conf text files. The help topic files have the same named section format as other configuration files. The help.conf files are stored in the same locations and loaded in the same order as other configuration files.

When the a --help command-line option is specified AsciiDoc loads the help.conf files and then prints the contents of the section whose name matches the help topic name. If a topic name is not specified default is used. If a matching help file section is not found a list of available topics is printed.

Writing AsciiDoc documents will be a whole lot more pleasant if you know your favorite text editor. Learn how to indent and reformat text blocks, paragraphs, lists and sentences. Tips for vim users follow.

The Vim text editor's gq command is great for reformatting and indenting AsciiDoc paragraphs and lists.

	Tip
	The Vim website (http://www.vim.org) has a wealth of resources, including scripts for automated spell checking and ASCII Art drawing.

Text Wrap Paragraphs

Use the vim :gq command to reformat paragraphs. Setting the textwidth sets the right text wrap margin; for example:

:set textwidth=70

To reformat a paragraph:

1. Position the cursor at the start of the paragraph.
2. Type gq}.

Execute :help gq command to read about the vim gq command.

	Tip
	Put set commands in your ~/.vimrc file so you don't have to enter them manually.

Format Lists

The :gq command can also be used to format bulleted and numbered lists. First you need to:

1. Set the textwidth right wrap margin.
2. Set the formatoptions n flag to enable numbered list reformatting (this flag also requires the autoindent option be set).
3. Add fb:*,fb:.,fb:+,fb:> to the comments option to assist the Vim :gq command reformat the AsciiDoc bulleted and numbered lists (in the example the C style comments middle part (mb:*) has been dropped to avoid ambiguity). Run the vim :help format-comments command for more about reformatting).

For example:

:set textwidth=70 formatoptions=tcqn autoindent
:set comments=s1:/*,ex:*/,://,b:#,:%,fb:-,fb:*,fb:.,fb:+,fb:>

Now you can format simple lists that use dash, asterisk, period and plus bullets along with numbered ordered lists:

1. Position the cursor at the start of the list.
2. Type gq}.

	Tip
	Assign the gq} command to the Q key with the :nnoremap Q gq} command or put it in your ~/.vimrc file to so it's always available.

Here's how I setup my .vimrc file:

nnoremap Q gq}

autocmd BufRead,BufNewFile *.txt,README,TODO,CHANGELOG,NOTES
        \ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2
        \ textwidth=70 wrap formatoptions=tcqn
        \ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:>

You have a number of stand-alone AsciiDoc documents that you want to process as a single document. Simply processing them with a series of include macros won't work, because instead of starting at level 1 the section levels of the combined document start at level 0 (the document title level).

The solution is to redefine the title underlines so that document and section titles are pushed down one level.

Actually the —conf-file option is unnecessary as asciidoc(1) automatically looks for a same-named .conf file.

You have divided your AsciiDoc document into separate files (one per top level section) which are combined and processed with the following top level document:

 Combined Document Title
 =======================
 Joe Bloggs
 v1.0, 12-Aug-03

 include::section1.txt[]

 include::section2.txt[]

 include::section3.txt[]

You also want to process the section files as separate documents. This is easy because asciidoc(1) will quite happily process section1.txt, section2.txt and section3.txt separately.

If you want to promote the section levels up one level, so the document is processed just like a stand-alone document, then pop the section underline definition up one level:

[titles]
underlines="--","~~","^^","++","__"

The last "__" underline is a dummy that won't actually be used but is necessary to legitimize the underline definition.

This is just the reverse of the technique used for combining separate documents explained in the previous section.

asciidoc(1) can be used as a filter, so you can pipe chunks of text through it. For example:

$ echo 'Hello *World!*' | asciidoc -s -
<p>Hello <strong>World!</strong></p>

The -s (—no-header-footer) command-line option suppresses header and footer output and is useful if the processed output is to be included in another file.

See the [footer] section in the AsciiDoc distribution xhtml11.conf configuration file.

If the indentation and layout of the asciidoc(1) output is not to your liking you can:

HTML Tidy can be downloaded from http://tidy.sourceforge.net/

The conditional inclusion of DocBook SGML markup at the end of the distribution docbook.conf file illustrates how to support minor DTD variations. The included sections override corresponding entries from preceding sections.

Reproducing presentation documents from some else's source has one major problem: unless your configuration files are the same as the creator's you won't get the same output.

The solution is to create a single backend specific configuration file using the asciidoc(1) -c (—dump-conf) command-line option. You then ship this file along with the AsciiDoc source document plus the asciidoc.py script. The only end user requirement is that they have Python installed (and of course that they consider you a trusted source). This example creates a composite HTML configuration file for mydoc.txt:

$ asciidoc -cb xhtml11 mydoc.txt > mydoc-xhtml11.conf

Ship mydoc.txt, mydoc-html.conf, and asciidoc.py. With these three files (and a Python interpreter) the recipient can regenerate the HMTL output:

$ ./asciidoc.py -eb xhtml11 mydoc.txt

The -e (—no-conf) option excludes the use of implicit configuration files, ensuring that only entries from the mydoc-html.conf configuration are used.

Adjust your style sheets to add the correct separation between block elements. Inserting blank paragraphs containing a single non-breaking space character {nbsp} works but is an ad hoc solution compared to using style sheets.

You can close off section tags up to level N by calling the eval::[Section.setlevel(N)] system macro. This is useful if you want to include a section composed of raw markup. The following example includes a DocBook glossary division at the top section level (level 0):

  ifdef::backend-docbook[]

  eval::[Section.setlevel(0)]

  +++++++++++++++++++++++++++++++
  <glossary>
    <title>Glossary</title>
    <glossdiv>
    ...
    </glossdiv>
  </glossary>
  +++++++++++++++++++++++++++++++
  endif::backend-docbook[]

Use xmllint(1) to check the AsciiDoc generated markup is both well formed and valid. Here are some examples:

$ xmllint --nonet --noout --valid docbook-file.xml
$ xmllint --nonet --noout --valid xhtml11-file.html
$ xmllint --nonet --noout --valid --html html4-file.html

The —valid option checks the file is valid against the document type's DTD, if the DTD is not installed in your system's catalog then it will be fetched from it's Internet location. If you omit the —valid option the document will only be checked that it is well formed.