AsciiDoc User Guide
===================
Stuart Rackham <srackham@methods.co.nz>
v5.1.1, September 2004


AsciiDoc is a text document format for writing short documents,
articles, books and UNIX man pages. AsciiDoc files can be translated
to HTML (with or without stylesheets), DocBook and LinuxDoc markup
using the asciidoc(1) command.  AsciiDoc is highly configurable: both
the AsciiDoc source file syntax and the backend output markups (which
can be almost any type of SGML/XML markup) can be customized and
extended by the user.


Introduction
------------
**********************************************************************
This is a large rambling document, it really needs to be factored into
a Tutorial, FAQ, Quick Reference and Formal Reference.

If you're new to AsciiDoc read this section and the
<<X6,Getting Started>> section and take a look at the example AsciiDoc
`*.txt` source files in the distribution `examples` and `doc`
directories.

Much of the remainder of this document details AsciiDoc customization,
something that you don't need to know about to start creating
documents.

**********************************************************************

Plain text is the most universal electronic document format, no matter
what computing environment you use, you can always read and write
plain text documentation. But for many applications plain text is not
a viable presentation format.  HTML, PDF and roff (roff is used for
man pages) are the most widely used Unix presentation formats and
DocBook is rapidly becoming the most popular Unix documentation source
format (DocBook is easily translated to HTML, PDF and many other
presentation formats).

AsciiDoc is a plain text human readable/writable document format that
can be translated directly to DocBook and HTML using the asciidoc(1)
command. You can then either use asciidoc(1) generated HTML directly
or run asciidoc(1) DocBook output through your favorite DocBook
toolchain to produce PDF, HTML, RTF and even HTML Help presentation
formats.

The AsciiDoc format is a useful presentation format in it's own right:
AsciiDoc files are unencumbered by markup and is easily viewed,
proofed and edited.

AsciiDoc is light weight: it consists of a single Python script and a
bunch of configuration files. Apart asciidoc(1) and a Python
interpreter no other programs are required to convert AsciiDoc text
files to DocBook, HTML and LinuxDoc. See
<<X11,Example AsciiDoc Documents>> below.

You write an AsciiDoc document the same way you would write a normal
text document, there are no markup tags or weird notations. Built-in
AsciiDoc formatting rules have been kept to a minimum and are fairly
obvious.

Text markup conventions tend to be a matter of strong personal
preference: if the default syntax is not to your liking you can define
your own by editing the text based asciidoc(1) configuration files.
You can create other backend formats to translate AsciiDoc documents
to almost any SGML/XML markup.

asciidoc(1) comes with a set of configuration files to translate
AsciiDoc files to HTML (articles, books, man pages), DocBook
(articles, books, man pages) or LinuxDoc (articles).

.My AsciiDoc Itch
**********************************************************************
DocBook has emerged as the defacto standard Open Source documentation
format. But DocBook is a complex language, the marked up text is
difficult to read and even more difficult to write directly, and I
found I was spending far to much time consulting reference manuals and
fixing syntax errors than actually writing the documentation.

**********************************************************************


Getting Started [[X6]]
----------------------
AsciiDoc is written in Python so you need a Python interpreter
(version 2.1 or later) to execute asciidoc(1). Python is installed
by the default configurations of most FreeBSD and Linux distributions.
You can download Python from the official Python website
http://www.python.org[].

- If you haven't already done so download the latest AsciiDoc
  distribution tarball from
  http://www.methods.co.nz/asciidoc/downloads.html[].

- Extract the distribution tarball (this example assumes the tarball
  is in you home directory and the `~/bin` directory exists):

  $ cd ~/bin
  $ tar -xzf ~/asciidoc-5.1.1.tar.gz

The tarball contains the executable `asciidoc.py` script,
configuration files, examples and documentation.

Test out asciidoc by changing to the AsciiDoc directory and converting
the User Guide document to HTML:

  $ ./asciidoc.py -b html doc/asciidoc.txt   # Plain HTML
  $ ./asciidoc.py -b css doc/asciidoc.txt    # HTML with CSS stylesheets

I use `.txt` file extensions for AsciiDoc files.

If you want to avoid having to explicitly specify the location of
asciidoc every time you run it you'll need to make sure that asciidoc
can be found in your search path, you can do this by putting a
symbolic link to asciidoc in a directory in your search path. For
example (assuming `~/bin` is in `$PATH`):

  $ ln -s ~/bin/asciidoc-5.1.1/asciidoc.py ~/bin/asciidoc

You can now execute asciidoc(1) by typing `asciidoc`.

Example AsciiDoc Documents [[X11]]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Examples of AsciiDoc markup are scattered throughout this document but
the best way to quickly get a feel for AsciiDoc is to view the
AsciiDoc web site and/or distributed examples:

- Take a look at the linked examples on the AsciiDoc web site home
  page http://www.methods.co.nz/asciidoc/[]. The web site itself was
  composed using AsciiDoc (press the 'Page Source' button to view
  corresponding AsciiDoc source).
- Read the `*.txt` AsciiDoc documentation source files in conjunction
  with the resulting HTML files (in the AsciiDoc distribution `./doc`
  directory).


AsciiDoc Backends [[X5]]
------------------------
The asciidoc(1) command translates an AsciiDoc formatted file to the
backend format specified by the `-b` command-line option. asciidoc(1)
itself has no intrinsic knowledge of backend formats, all translation
rules are contained in user customizable cascading configuration
files.

AsciiDoc ships with the following predefined backend output formats:

docbook
~~~~~~~
AsciiDoc generates DocBook article, book and refentry documents
(corresponding to the asciidoc(1) 'article', 'book' and 'manpage'
document types).

As of version 4.2 the `-b docbook` command-line option switched from
outputting DocBook SGML to the newer DocBook XML. You can still
produce DocBook SGML using the `-b docbook-sgml` command-line option.

The DocBook DTD restricts the allowable AsciiDoc syntax:

- The AsciiDoc 'Preamble' element is output as a DocBook book
  'Preface' when processed as a 'book' document type.


linuxdoc
~~~~~~~~
The LinuxDoc DTD restricts the allowable AsciiDoc syntax:

- Only article document types are allowed.
- The Abstract section can consist only of a single paragraph.
- An AsciiDoc Preamble is not allowed.
- The LinuxDoc output format does not support multiple variable list
  terms per list item. LinuxDoc conversion programs generally output
  all the terms anyway but, in any case, you will get a warning.
- Don't apply character formatting to the `link` macro caption,
  LinuxDoc does not allow hypertext link text to be formatted.

html
~~~~
The asciidoc(1) `-b html` command-line option produces plain unstyled
HTML that can be displayed and printed from any HTML browser.

As of version 4.2 the asciidoc(1) `-b html` command-line option
produces XHTML 1.0 markup. You can still produce HTML 4 markup using
the `-b html-4` command-line option.

css
~~~
The asciidoc(1) `-b css` command-line option produces XHTML 1.0
conforming output styled with linked CSS2 stylesheets. 

The example stylesheets (`main.css`, `article.css` and `manpage.css`)
style both screen and printed outputs and are located in the
`./stylesheets/` directory.

The example stylesheets can be customized to restyle your document's
appearance.

Browser CSS support varies from browser to browser. The examples work
well on IE5,6, Mozilla 1.1 and up, Opera 7  and Konqueror 3.01 but have
not been tested on other browsers. All browsers have their quirks.
When it comes to implementing CSS, of those tested I found Mozilla to
be the most conformant.

css-embedded
~~~~~~~~~~~~
The asciidoc(1) `-b css-embedded` command-line option produces XHTML
1.0 conformant output styled with embedded CSS2 stylesheets.  Similar
to the 'css' backend but translated files do not rely on external
stylesheets.

Converting to other Presentation Formats
----------------------------------------
DocBook and LinuxDoc documents define the structure of a document but
are not designed to be viewed directly. FreeBSD and Linux operating
systems contain tools for converting DocBook and LinuxDoc files to
presentation formats such as Postscript, HTML, PDF, DVI, roff (the
native man page format), HTMLHelp, JavaHelp and text.

DocBook Conversion
~~~~~~~~~~~~~~~~~~
.DocBook Tool Chains
**********************************************************************
DocBook files are validated, parsed and translated by a combination of
applications which together comprise a DocBook 'tool chain'. The core
function of a tool chain is to read the DocBook markup produced by
AsciiDoc and transform it to a presentation format (for example HTML,
PDF, HTML Help) using a set of rules (defined in an associated
stylesheets).

Because there is a choice of available tools and stylesheets and a
wide range of user output requirements there are many possible valid
tool chain combinations.

Assembling a working DocBook tool chain requires a fairly detailed
understanding of how each of the tools works together.  Popular Linux
distributions come with both toolchains and toolchain wrapper scripts.

Wrapper scripts tie together the various toolchain commands and
simplify the underlying complexity. Recent Redhat/Fedora distributions
have shipped fully configured toolchains along with both the
`xmlto(1)` and the `jw(1)` toolchain wrappers (which process DocBook
XML and DocBook SGML documents using XSL and DSSSL stylesheets
respectively).  `xmlto(1)` and related tools are standard Cygwin
packages and are recommended for Microsoft Windows users.

Immediately below you'll find examples using toolchain wrapper scripts
-- explicit use of DocBook toolchain commands can be found in the
<<X12,Processing DocBook Files>> section.

**********************************************************************

Most of the examples below use the `xmlto(1)` command because it's
easy to use and is available on UNIX and Windows (Cygwin). The
drawback is that, out of the box, the generated HTML and PDF are very
plain. To generate HTML and PDF styled like the distributed AsciiDoc
documentation the <<X12,Processing DocBook Files>> section.

The default `xmlto(1)` outputs are quite plain (compared to the
distributed AsciiDoc HTML and PDF documentation files), the
<<X12,Processing DocBook Files>> section explains how you can
generate nicely styled output using custom 'DocBook XSL Stylesheets'
drivers.

If you do use `jw(1)` don't forget to specify the `docbook-sgml`
backend, not the `docbook` backend.
 
The `xmlto(1)` command is a shell script for sequencing and managing
the execution of `xsltproc(1)`, `DocBook XSL Stylesheets`,
`xmllint(1)` and friends).  `xmlto(1)` can convert DocBook source to
the following formats: dvi, fo, html, htmlhelp, html-nochunks,
javahelp, man, pdf, ps, txt, xhtml, xhtml-nochunks.

To convert the `asciidoc.txt` AsciiDoc User Guide to PDF format:

  $ asciidoc -b docbook asciidoc.txt
  $ xmlto pdf asciidoc.xml

To convert the `asciidoc.1.txt` AsciiDoc manpage document to native
man page `groff(1)` man macro package format:

  $ asciidoc -d manpage -b docbook asciidoc.1.txt
  $ xmlto man asciidoc.1.xml

To view the man page file as it would be displayed by the man(1)
command:

  $ groff -mandoc -Tascii asciidoc.1 | less

To print a high quality man page to a postscript printer:

  $ groff -mandoc -Tps asciidoc.1 | lpr

You can also produce HTML from DocBook files:

  $ asciidoc -b docbook asciidoc.txt
  $ xmlto html-nochunks asciidoc.xml      # Single HTML file.
  $ xmlto html -o html-dir asciidoc.xml   # Chunked HTML file.

.Why Generate HTML via DocBook?
**********************************************************************
AsciiDoc produces nicely styled HTML directly without requiring a
DocBook toolchain so why would you want generate it via DocBook?  The
main advantage is that HTML from DocBook includes automatically
generated indexes, tables of contents, lists of figures and tables.
DocBook toolchains can also (optionally) generate separate (chunked)
linked HTML pages for each document section.

Plain and CSS styled HTML output directly from AsciiDoc is still very
useful though, for example:

- Generating Websites.
- Documents that don't require front and back matter.
- Situations where there is no suitable DocBook toolchain.

**********************************************************************

LinuxDoc Conversion
~~~~~~~~~~~~~~~~~~~
LinuxDoc is an SGML documentation markup language originally created
by Matt Welsh to write Linux documentation. LinuxDoc does a good job
of marking up small and medium sized text based documents. Its
strength is its simplicity and ease of use.

There are a number of Open Source applications available to convert
the LinuxDoc SGML markup to various presentation formats, here are a
couple of examples:

Create a single HTML file with a detailed table of contents using the
linuxdoc(1) command that comes with the Linuxdoc-Tools package.

  $ linuxdoc -B html -s 0 -T 2 asciidoc.sgml

Generate a set of linked HTML files using the sgmlfmt(1) from the
FreeBSD sgmlformat package:

  $ sgmlfmt -f html asciidoc.sgml

Create a PDF file using the sgmlfmt(1) from the FreeBSD sgmlformat
package:

  $ sgmlfmt -f ps asciidoc.sgml
  $ ps2pdf asciidoc.ps

Generating Plain Text Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~
AsciiDoc does not have a text backend but you can convert docbook to
text using the `xmlto(1)` or `jw(1)` commands.

WARNING: By default both `jw(1)` and `xmlto(1)` commands create files
with a `.txt` extension when generating text files. This will
overwrite your AsciiDoc `*.txt` source files (use the `-o`
command-line option to output to an alternative directory).

You can also use the `lynx(1)` web browser to convert AsciiDoc
generated HTML to text.  You'll find an `asciidoc2text.sh` shell
script included in the AsciiDoc distribution `examples/asciidoc2text`
directory which, together with the `asciidoc2text.conf` configuration
file, automates text file generation with a single command. For
example:

  $ ./examples/asciidoc2text/asciidoc2text.sh test.txt >test.text


AsciiDoc Document Types
-----------------------
There are three types of AsciiDoc documents: manpage, article and
book. Apart from a few document type specific restrictions all
document types share the same AsciiDoc format.

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

book
~~~~
Books share the same format as articles; in addition there is the
option to add level 0 sections to divide a book into multiple parts.

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 all the standard DocBook frontmatter and
backmatter sections (dedication, preface, bibliography, glossary,
index, colophon) plus footnotes and index entries.

.Examples:
Book::
        The `book.txt` file in the AsciiDoc distribution `./doc`
        directory.

Multi-part book::
        The `book-multi.txt` file in the AsciiDoc distribution `./doc`
        directory.

manpage
~~~~~~~
Used to generate UNIX manual pages.  AsciiDoc manpage documents
observe header title and section naming conventions, in other respects
they are just normal AsciiDoc documents (see also the
<<X1,manpage Documents>> section).

For an example see the `asciidoc.1.txt` in the AsciiDoc distribution
`./doc` directory.


Document Structure
------------------
An AsciiDoc document consists of a series of block elements starting
with an optional document Header, followed by an optional Preamble,
followed by zero or more document Sections.

Almost any combination of zero or more elements constitutes a valid
AsciiDoc document: documents can range from a single sentence to a
multi-part book.

Header
~~~~~~
The first line of the document contains the optional document title
followed by an underline of equals '=' characters.

Immediately following the title underline (no intervening blank lines)
are optional author and revision lines.

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:

- A an alphanumeric document revision number followed by a date. The
  revision number and date must be separated by a comma. The optional
  revision number must start with a numeric digit. Any non-numeric
  revision number prefix will be skipped.
- An RCS $Id$ marker

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

No Comment blocks are allowed within the header.

Here's an example AsciiDoc document header:

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


Preamble
~~~~~~~~
The Preamble is an optional untitled section body between the document
Header and the first Section title. The Preamble should only be
included in 'article' documents.


Sections
~~~~~~~~
AsciiDoc supports five section levels which corresponding to document
levels 0 to 4 (although only book documents are allowed to contain
level 0 sections). Section levels are delineated by the section title
underlines.

A section consists of a section title followed by an optional section
body.

The section title consists of two lines: 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
  ~~~~~~~~~~~~~~~~~~~~~~~~

Sections are translated using configuration file substitution
sections. To determine which substitution section to use AsciiDoc
first searches for section titles in the `[specialsections]`
configuration entries, if not found it looks for the name
`sect<level>`.

The `\{sectnum}` predefined glossary entry can be used to write
section numbers (only useful for HTML outputs).  Use the `-n`
command-line option to auto-number HTML documents.

Special Sections
^^^^^^^^^^^^^^^^
In addition to nested sections documents generally have frontmatter
and backmatter sections with special semantic significance, for
example: preface, bibliography, table of contents, index.

AsciiDoc configuration files can have a `[specialsections]` section
which specifies special section titles and the corresponding backend
markup.

`[specialsections]` entries are formatted like:

  <pattern>=<name>

`<pattern>` is a Python regular expression and `<name>` is the name of
a substitution section. If the `<pattern>` matches an AsciiDoc
document section title then the backend output is marked up using the
`<name>` substitution section. If the named group 'title' is present
in the pattern then the matched value replaces `\{title}` substitution
references, if there is no 'title' named group the whole of the
section title is used.

The special section names in the default `[specialsections]` section
are:

  Preface                    (book documents only)
  Abstract                   (article documents only)
  Dedication                 (book documents only)
  Glossary
  Bibliography|References
  Colophon                   (book documents only)
  Index
  Appendix [A-Z][:.] <title>
  
Section Arguments
^^^^^^^^^^^^^^^^^
The section title line can optionally end with title augments
enclosed in pairs of square brackets (see
<<"X2","DelimitedBlock, Table and Macro Arguments">>).
The distributed configuration files use the first positional argument
`\{1}` as a hypertext link target ID.  For example:

  Getting Started [[X2]]
  ----------------------

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

The AsciiDoc block structure can be summarized as follows:

  Document      ::= (Header?,Preamble?,Section*)
  Header        ::= (Title,(AuthorLine,RevisionLine?)?)
  AuthorLine    ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
  RevisionLine  ::= (Revision?,Date)
  Title         ::= (TitleName,Underline)
  Preamble      ::= (SimpleSection)
  Section       ::= (Title,SimpleSection?,(Section)*)
  SimpleSection ::= ((BlockTitle?,
                    (Paragraph|DelimitedBlock|List|Table|BlockMacro))+)
  List          ::= (SimpleList|VariableList)
  SimpleList    ::= (ListItem)+
  VariableList  ::= (ItemTerm+,ListItem)+
  ListItem      ::= (ItemText,(List|ListParagraph)*)
  Table         ::= (Ruler,Arguments?,TableHeader?,TableBody,TableFooter?)
  TableHeader   ::= (TableRow+,TableUnderline)
  TableFooter   ::= (TableRow+,TableUnderline)
  TableBody     ::= (TableRow+,TableUnderline)
  TableRow      ::= (TableData+)

- '?' implies zero or one occurrence, '+' implies one or more
  occurrences, '*' implies zero or more occurrences.
- All block elements are separated by line boundaries.
- The manpage document must have a Header followed immediately by NAME
  and SYNOPSIS sections.
- A ListParagraph is a Paragraph with it's 'listelement' option set.
- The following elements cannot contain blank lines: Header, Title,
  Paragraph, ItemText.
- Line continuation using a trailing backslash character is available
  in Paragraphs, ListItems and Tables (useful for long quoted text or
  inline macros).

Inline Elements
~~~~~~~~~~~~~~~
Inline document elements occur within block elements; inline elements
can begin and end anywhere within a line but cannot span multiple
lines.

Inline 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:

Special characters::
	These character sequences escape special characters used by
	the backend markup (typically "<", ">", and "&"). See
	`[specialcharacters]` configuration file sections.

Quotes::
	Characters that markup words and phrases; usually for
	character formatting. See `[quotes]` configuration file
	sections.

Special Words::
	Word or word phrase patterns singled out for markup without
	the need for further annotation.  See `[specialwords]`
	configuration file sections.

Replacements::
	Each Replacement defines a word or word phrase pattern to
	search for along with corresponding replacement text. See
	`[replacements]` configuration file sections.

Glossary References::
	Glossary entry names enclosed in curly brackets are replaced
	by a corresponding glossary entry value.

Inline Macros::
	Inline macros are replaced by the contents of parameterized
	configuration file sections.


Document Processing
-------------------
The AsciiDoc source document is read and processed as follows:

1. The document 'Header' is parsed, header parameter values are
   substituted into the configuration file `[header]` template section
   which is then written to the output file.
2. Each document 'Section' is processed and it's constituent elements
   parsed and translated to the output file.
3. The configuration file `[footer]` section is substituted and
   written to the output file.

When a block element is encountered asciidoc(1) determines the type of
block by checking in the following order (first to last): BlockTitles,
(section) Titles, BlockMacros, Lists, DelimitedBlocks, Tables,
Paragraphs.

The default paragraph definition `[paradef-default]` is always the
last element to be checked.

Knowing the parsing order will help you devise unambiguous macro, list
and block syntax rules.

Inline substitutions within block elements are performed in the
following default order:

1. Special characters
2. Quotes
3. Special words
4. Replacements
5. Glossary references
6. Inline Macros

The default substitutions and substitution order is overridden by the
`presubs` and `postsubs` options in Paragraph and DelimitedBlock
definitions and by the `subs` option in List definitions.


BlockTitles
-----------
A BlockTitle element is a single line beginning with a period followed
by a title. The title is applied to the next Paragraph,
DelimitedBlock, List, Table or BlockMacro.For example:

........................
  .NOTES:
  - Note 1.
  - Note 2.
........................

is rendered as:

.NOTES:
- Note 1.
- Note 2.


Paragraphs
----------
Paragraphs are terminated by a blank line, the end of file, or the
start of a DelimitedBlock.

Paragraph types are defined in configuration file `[paradef*]`
sections.  AsciiDoc ships with the following predefined paragraph
types:

Default Paragraph
~~~~~~~~~~~~~~~~~
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.

Indented Paragraph
~~~~~~~~~~~~~~~~~~
An Indented paragraph (`[paradef-indented]`) consists of one or more
lines of text, where the first line begins with one or more or space
or tab characters. Indented paragraphs retain line and whitespace
formatting and are rendered in a monospaced font usually without any
distinguishing background or border.  There is no text formatting or
substitutions within Indented paragraphs apart from Special Characters
and Callouts.  For example:

  $ rm -f /tmp/*.txt

Admonition Paragraphs
~~~~~~~~~~~~~~~~~~~~~
'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.

Outputs:

NOTE: This is an example note.

Paragraph Definitions
~~~~~~~~~~~~~~~~~~~~~
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.*)
section=paragraph
--------------------------------------------------------------------

The Default paragraph definition has a couple of special properties:

1. It must exist and be defined in a configuration file section named
   `[paradef-default]`.
2. Irrespective of its position in the configuration files the default
   paragraph definition is always processed last.

Available paragraph definition entries:

delimiter::
	A Python regular expression that matches the first line of a
	paragraph. This expression must contain the named group 'text'
	which matches the text on the first line.  Paragraphs are
	terminated by a blank line, the end of file, or the start of a
	DelimitedBlock.

section::
	The name of the configuration file section that will envelope
	the translated paragraph contents. The pipe | character in the
	section body is substituted for the paragraph text.

options::
	The only allowable option is 'listelement'.  The 'listelement'
	option specifies that paragraphs of this type can be included
	in list items.

presubs, postsubs::
	A comma separated list of the substitutions that are performed
	on the block contents. Allowed values: 'specialcharacters',
	'quotes', 'specialwords', 'replacements', 'macros',
	'glossary'.  If a 'filter' has been specified the 'presubs'
	and 'postsubs' substitutions are performed before and after
	the filter is run respectively.  The substitutions are
	processed in the order in which they are listed and can appear
	more than once.

filter::
	This optional entry specifies an executable shell command for
	processing paragraph text.  The filter command can contain
	references to glossary entries (enclosed in curly brackets)
	which are substituted prior to filter execution.

.Paragraph processing proceeds as follows:
1. The paragraph text is aligned to the left margin.
2. Optional 'presubs' inline substitutions are performed on the
   paragraph text.
3. If a filter command is specified it is executed and the paragraph
   text piped to it's standard input; the filter output replaces the
   paragraph text.
4. Optional 'postsubs' inline substitutions are performed on the
   paragraph text.
5. The paragraph text is enveloped by the paragraph 'section' and
   written to the output file.


Text Formatting
---------------
Quoted Text
~~~~~~~~~~~
Words and phrases can be formatted by enclosing the text with
predefined quoting characters:

'Emphasized text'::
	Word phrases \'enclosed in single quote characters' (acute
	accents) are emphasized.

*Strong text*::
	Word phrases \*enclosed in asterisk characters* are rendered
	in a strong font (usually bold).

`Monospaced text`::
	Word phrases \`enclosed in backtick characters` (grave
	accents) are rendered in a monospaced font.

Quoting characters can be changed and new quoting markup syntax
defined by editing asciidoc(1) configuration files.  See the
<<X7,Configuration Files>> section for details.

.NOTES:
- Quoted text must be flanked by non-word characters.
- Quoted formatting cannot span line boundaries unless you use
  backslash line continuation (be careful when reformatting
  paragraphs).
- Quoting cannot be overlapped.
- Different quoting types can be nested.
- To suppress quoted text formatting place a backslash character
  immediately in front of the leading quote character(s). If escaped
  and non-escaped quotes of the same type are nested you will have to
  escape closing quotes to disambiguate them.
- Document and section titles are not subject to quoted formatting.
- The appearance of quoted text can be customized by editing the
  corresponding configuration file tag definitions.  (although in the
  case of 'css' backends it probably makes more sense to edit the CSS
  stylesheets).

Superscripts and Subscripts
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Put carets either side of the text to be superscripted, put tildes
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^{amp}#960;i^+1 = 0. H~2~O and x^10^. 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.

Line Breaks
~~~~~~~~~~~
A plus character (preceded by at least one space character) at the end
of a line forces a line break. This is only useful when outputting
HTML (`<br/>` tag). Line breaks are ignored when outputting to DocBook
since it has no line break element. The break is implemented as a
'Replacements' substitution.

Tabs
~~~~
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 by the 'include' macro
'tabsize' argument. The tab size can also be set using the `-g`
command-line option, for example `-g tabsize=4`

Replacements
~~~~~~~~~~~~
The following replacements are defined in the default AsciiDoc
configuration:

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

Is rendered as:

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

The <<X7,Configuration Files>> section explains how to configure your
own replacements.

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

The <<X7,Configuration Files>> section explains how to add and replace
special words.


Lists
-----
Asciidoc supports simple (bulleted and ordered) lists and variable
(definition) lists.

Here's an example of nested lists and paragraphs:

.........................................
1. List item 1
   leading text
   a. Nested list item 1
   b. Nested list item 2

2. List item 2
   leading text.

   List item 2 indented paragraph 1

   -  Nested list item 1
   -  Nested list item 2

      Nested list item 2 indented paragraph 1

      Nested list item 2 indented paragraph 2

3. List item 3
   leading text.
.........................................

Outputs:

1. List item 1
   leading text
   a. Nested list item 1
   b. Nested list item 2

2. List item 2
   leading text.

   List item 2 indented paragraph 1

   -  Nested list item 1
   -  Nested list item 2

      Nested list item 2 indented paragraph 1

      Nested list item 2 indented paragraph 2

3. List item 3
   leading text.

.List properties:
- A nested list must be a different type to its parent so that
  asciidoc(1) can distinguish between the start of a nested list and
  another list item.
- By default lists can only be nested two deep; this can be increased
  by defining new list definitions.
- In addition to nested lists a list item can include ListParagraphs;
  these are paragraphs with the paragraph definition 'listelement'
  option.

AsciiDoc comes with a pre-defined SimpleList for generating
bibliography entries (which must be in a glossary section to generate
valid DocBook output). 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. 199.
    ISBN 1-56592-580-7.
......................................................

Simple Lists
~~~~~~~~~~~~
Bulleted list items start with a dash followed by a space or tab
character. For example:

....................
  - Item 1
  - Item 2
  - Item 3
....................

'Alternative syntax': lead off with an asterisk. The alternative
syntax is primarily to allow nested lists of the same type.

Ordered list items start with an optional number followed by a period
followed by a space or tab character. For example:

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

'Alternative syntax': start with a period or lower case letter
followed by a period, followed by a space or tab character.

NOTE: It is not necessary to number or letter ordered lists, this is
handled automatically by the programs that render the HTML, DocBook or
LinuxDoc outputs.

Variable Lists
~~~~~~~~~~~~~~
Variable list items consist of one or more terms followed by a
definition.

A term is a single line of text starting with an alphanumeric
character hard against the left margin and ending with a double colon
'::'.

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

......................................................
  HTML, PDF::
	Commonly used document formats.

  Page::
	Common term for an HTML document. See web page.
......................................................

Is rendered as:

HTML, PDF::
      Commonly used document formats.

Page::
      Common term for an HTML document. See web page.

'Alternative syntax': append a double semicolon, in place of the
double colon, to the list item definition. The alternative syntax is
primarily to allow nested lists of the same type.

AsciiDoc comes pre-configured with variable lists for generating
question and answer (Q&A) lists and glossary entries. Examples:

......................................................
  Question one??
	  Answer one.
  Question two??
	  Answer two.

  A glossary term:-
	  The corresponding definition.
  A second glossary term:-
	  The corresponding definition.
......................................................

NOTE: Glossary entries must be in a glossary section to generate valid
DocBook output.

List Definitions
~~~~~~~~~~~~~~~~
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 definition sections are characterized by the following entries:

type::
	This is either 'simple' or 'variable'.
delimiter::
	A Python regular expression that matches the first line of a
	list element entry. This expression must contain the named
	group 'text' which matches the text in the first line.
subs::
	A comma separated list of the substitutions that are performed
	on list item text and terms. Allowed values:
	'specialcharacters', 'quotes', 'specialwords', 'replacements',
	'macros', 'glossary', 'default', 'none'.
listtag::
	The name of the tag that envelopes the List.
itemtag::
	The name of the tag that envelopes the ListItem.
texttag::
	The name of the tag that envelopes the text of first block
	element in a list item.
entrytag::
	The name of the tag that envelopes a variable list entry
	(ListTerms plus ListItem).
termtag::
	The name of the tag that envelopes a variable list term.

The tag entries map the AsciiDoc list structure to an SGML/XML markup;
see the shipped AsciiDoc `.conf` files for examples.


Delimited Blocks
----------------
Delimited blocks are blocks of text enveloped by leading and trailing
delimiter lines (normally a series of three or more repeated
characters). The behavior of Delimited Blocks is specified by entries
in configuration file `[blockdef*]` sections.

If the block definition specifies the 'argsline' option arguments can
be specified in the line immediately following the leading delimiter
line (see also the <<"X2","DelimitedBlock, Table and Macro Arguments">>
sub-section.  Alternatively, arguments can be embedded in the
delimiter line.

Predefined Delimited 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:  //////////////////////////
  CustomBlock:   ++++++++++++++++++++++++++
  IndentedBlock: ..........................
  SidebarBlock:  **************************
  VerbatimBlock: --------------------------
  QuoteBlock:    __________________________

.Default DelimitedBlock substitutions
`-------------.---------.---------.---------.---------.---------
	      Custom    Verbatim  Indented  Sidebar   Quote
----------------------------------------------------------------
Callouts        No        Yes       Yes      No        No
Glossary        Yes       No        No       Yes       Yes
Inline Macros   Yes       No        No       Yes       Yes
Quotes          No        No        No       Yes       Yes
Replacements    No        No        No       Yes       Yes
Special chars   No        Yes       Yes      Yes       Yes
Special words   No        No        No       Yes       Yes
----------------------------------------------------------------

Verbatim Blocks
~~~~~~~~~~~~~~~
VerbatimBlocks 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
Verbatim blocks apart from Special Characters and Callouts. Verbatim
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);
}
--------------------------------------

Indented Blocks
~~~~~~~~~~~~~~~
IndentedBlocks behave just like IndentedParagraphs except they have
leading and trailing delimiter lines and you don't have to indent the
contents.

IndentedBlocks can be used to resolve indented list ambiguity. If the
following example was not delimited it would be processed as a list:

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

SidebarBlocks
~~~~~~~~~~~~~
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 SimpleSection element (apart from
  SidebarBlocks) can be placed inside a sidebar.
  ************************************************

Which will be rendered like:

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

Sidebar elements are not supported by the LinuxDoc format and sidebar
text appears as part of the main document flow.

Comment Blocks
~~~~~~~~~~~~~~
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).
  //////////////////////////////////////////

Custom Blocks
~~~~~~~~~~~~~
CustomBlock text is written to the output after glossary and inline
macro substitution.  CustomBlock content will generally be backend
specific. Here's an example:

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

Quote Blocks
~~~~~~~~~~~~
QuoteBlocks are used for quoted passages of text. 'attribution' and
'citetitle' named arguments specify the author and source of the quote
(they are equivalent to positional arguments 1 and 2 respectively).
Both arguments are optional and the block body is treated like a
simple section body . 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:
____________________________________________________________________
[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.
____________________________________________________________________

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

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

Block Definitions
~~~~~~~~~~~~~~~~~
As an example, here is the default configuration file VerbatimBlock
definition:

------------------------------
[blockdef-verbatim]
delimiter=^-{3,}(\[(?P<args>.*)\])?-*$
section=verbatimblock
presubs=specialcharacters
------------------------------

delimiter::
	A Python regular expression that matches the leading and
	trailing block underlines. In the above example a line starting
	with at least three tilde characters.
section::
	The name of the configuration file section that
	will envelope the block contents. The pipe | character is
	substituted for the block contents.
options::
	Allowed values are 'section', 'skip' and 'argsline'. If the
	'section' option is set the block contents are processed as a
	SimpleSection body. The 'skip' option causes the block to be
	treated as a comment (see 'CommentBlocks').  'presubs',
	'postsubs' and 'filter' entries are not used when 'section' or
	'skip' options are set. If the 'argsline' option is specified
	then an optional arguments line can be included after the
	leading delimiter.

presubs, postsubs::
	A comma separated list of the substitutions that are performed
	on the block contents. Allowed values: 'specialcharacters',
	'quotes', 'specialwords', 'replacements', 'macros',
	'glossary', 'default', 'none'.  If a 'filter' has been
	specified the 'presubs' and 'postsubs' substitutions are
	performed before and after the filter is run respectively.
	The substitutions are processed in the order in which they are
	listed and can appear more than once.
filter::
	This optional entry specifies an executable shell command for
	processing block content. The filter command can contain
	references to glossary entries and block arguments.

DelimitedBlock processing proceeds as follows:

1. Optional 'presubs' substitutions are performed on the block
   contents.
2. If a filter is specified it is executed and the block's contents
   piped to its standard input. The filter output replaces the block
   contents.
3. Optional 'postsubs' substitutions are performed on the block
   contents.
4. The block contents is enveloped by the block 'section' and written
   to the output file.

TIP: Glossary reference expansion is performed on the block filter
command before it is executed, this is useful for passing block
arguments to the filter.


Footnotes
---------
The shipped AsciiDoc configuration includes the `\footnote:[<text>]`
inline macro for generating footnotes. Example:

    footnote:[An example footnote.]

.NOTES:
- Footnotes are primarily useful when generating DocBook output --
  DocBook conversion programs render footnote outside the primary text
  flow.
- Use the line continuation backslash for long footnotes.

TIP: Place `footnote` macro references on separate lines, this makes
the AsciiDoc source easier to read and helps emphasize that they do
not appear in the primary text flow.


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

\indexterm:[<primary>,<secondary>,<tertiary>]::
\++<primary>,<secondary>,<tertiary>++::
    This inline macro generates an index term (the <secondary> and
    <tertiary> arguments are optional). For 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.

Here are some index entry examples taken from the example article and
book documents in the AsciiDoc `./doc` distribution directory.

    And now for something completely different: +monkeys+, lions and
    tigers (Bengal and Siberian) using the alternative syntax index
    entries.
    ++Big cats,Lions++
    ++Big cats,Tigers,Bengal Tiger++
    ++Big cats,Tigers,Siberian Tiger++
    Note that multi-entry terms generate separate index entries.

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
(see the `book.txt` example document in the distribution `./doc`
directory).

TIP: Place `indexterm` macro references on separate lines, this makes
the AsciiDoc source easier to read and helps emphasize that they do
not appear in the primary text flow.


Callouts
--------
Callouts are a mechanism for annotating verbatim text (source code,
computer output and user input for example). 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 like:

.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 that
  refer to an item index in the following callout list.
- By default callout marks are confined to IndentedParagraphs,
  IndentedBlocks and VerbatimBlocks (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 -- 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.

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 included in 'macros'
substitutions -- it has it's own 'callouts' substitution option.

The following glossary entries are available during callout inline
macro substitution:

`\{caption}`::
  The callout list item index inside the angle brackets.
`\{calloutid}`::
  An identifier formatted like `CO<listnumber>-<calloutindex>` that
  uniquely identifies the callout mark. For example `CO2-4` identifies
  the fourth callout mark in the second set of callout marks.

The `\{calloutids}` glossary reference can be used during callout list
item substitution -- it is a space character delimited list of callout
mark IDs that refer to the list item.


Tables
------
Tables are the most complex AsciiDoc element and this section is quite
long. The <<X3,Example Tables>> section will get you started.

TIP: AsciiDoc generates nice HTML tables, but the current crop of
commonly deployed DocBook stylesheets render tables with varying
degrees of success. Use tables only when necessary, it's surprising
how seldom they're actually needed.

NOTE: Asciidoc 'csv' format tables require Python 2.3 or later.

Example Tables [[X3]]
~~~~~~~~~~~~~~~~~~~~~
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:

- Backtick (`) -- align left.
- Single quote (') -- align right.
- Period (.) -- align center.

Simple table:

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

Output:

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

Table with title, header and footer:

  .An example table
  '---------.--------------
  Column 1   Column 2
  -------------------------
  1          Item 1
  2	     Item 2
  3	     Item 3
  -------------------------
  6	    Three items
  -------------------------

Output:

.An example table
`-----------.--------------
Column 1     Column 2
---------------------------
1            Item 1
2	     Item 2
3	     Item 3
---------------------------
6	    Three items
---------------------------

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

  ````~15
  1,2,3,4
  a,b,c,d
  A,B,C,D
  ~~~~~~~~

Output:


````~15
1,2,3,4
a,b,c,d
A,B,C,D
~~~~~~~~

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

  .15`20`25`20`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  ID,Customer Name,Contact Name,Customer Address,Phone
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  include::customers.csv[]
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Output:

.15`20`25`20`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ID,Customer Name,Contact Name,Customer Address,Phone
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"AROUT","Around the Horn","Thomas Hardy","120 Hanover Sq.
London","(171) 555-7788"
"BERGS","Berglunds snabbkop","Christina Berglund","Berguvsvagen  8
Lulea","0921-12 34 65"
"BLAUS","Blauer See Delikatessen","Hanna Moos","Forsterstr. 57
Mannheim","0621-08460"
"BLONP","Blondel pere et fils","Frederique Citeaux","24, place Kleber
Strasbourg","88.60.15.31"
"BOLID","Bolido Comidas preparadas","Martin Sommer","C/ Araquil, 67
Madrid","(91) 555 22 82"
"BONAP","Bon app","Laurence Lebihan","12, rue des Bouchers
Marseille","91.24.45.40"
"BOTTM","Bottom-Dollar Markets","Elizabeth Lincoln","23 Tsawassen Blvd.
Tsawassen","(604) 555-4729"
"BSBEV","B's Beverages","Victoria Ashworth","Fauntleroy Circus
London","(171) 555-1212"
"CACTU","Cactus Comidas para llevar","Patricio Simpson","Cerrito 333
Buenos Aires","(1) 135-5555"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AsciiDoc Table Block Elements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This sub-section details the AsciiDoc source file table format.

  Table  ::= (Ruler,Arguments?,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
^^^^^
The first line of the table is called the 'Ruler'. The Ruler specifies
which configuration file table definition to use, column widths,
column alignments and the overall table width.

There are two ruler formats:

Character ruler::
	The column widths are specified by the number of table fill
	characters between column stop characters.
Numeric ruler::
  	The column widths are specified numerically. If a column width
	is omitted the previous width is used. In the degenerate case
	of no widths being specified columns are allocated equal
	widths.

The ruler format can be summarized as:

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

- The 'ruler' starts with a column stop character (designating the
  start of the first column).
- Column stop characters specify the start and alignment of each
  column:
  * Backtick (`) -- align left.
  * Single quote (') -- align right.
  * Period (.) -- align center.
- In the case of 'fixed' format tables the ruler column widths specify
  source row data column boundaries.
- The optional 'tablewidth' is a number representing the size of the
  output table relative to the 'pagewidth'. If 'tablewidth' is less
  than one then it is interpreted as a fraction of the page width; if
  it is greater than one then it is interpreted as a percentage of
  the page width. If 'tablewidth' is not specified then the table
  occupies the full 'pagewidth' (numeric rulers) or the relative width
  of the ruler compared to the 'textwidth' (character rulers).

Arguments
^^^^^^^^^
Optional table arguments can be specified in the line immediately
following the Ruler line (see the
<<"X2","DelimitedBlock, Table and Macro Arguments">> sub-section).

Arbitrary arguments are substituted into table tags and sections. The
following named arguments can be used to override table definition and
ruler parameters: 'format', 'tablewidth', 'subs'.

DSV separator::
	The default DSV table form colon separator can be changed
	using the 'separator' argument. For example:
	`[separator="|"]`.

Borderless tables::
	Table borders can be suppressed using the 'noborders' table
	argument.  For example: `[options="noborders"]`.

Underline
^^^^^^^^^
A table 'Underline' consists of a line of three or more 'fillchar'
characters which are end delimiters for table header, footer and body
sections.

Substitution References
^^^^^^^^^^^^^^^^^^^^^^^
The following predefined glossary substitution references are
available inside table tag and section templates.

cols::
      	The number of columns in the table.
colalign::
	Column alignment assumes one of three values ('left', 'right'
	or 'center'). The value is determined by the
	corresponding ruler column stop character (only valid inside
	'colspec' tags).
colwidth::
      	The output column widths are calculated integers (only valid
	inside 'colspec' tags).
format::
	The table definition 'format' value (can be overridden with
	named table argument).
subs::
	The table definition 'subs' value (can be overridden with
	named table argument).
tablewidth::
      	The ruler 'tablewidth' value (can be overridden with named
	table argument).
pagewidth::
	The 'pagewidth' miscellaneous configuration option.
pageunits::
	The 'pageunits' miscellaneous configuration option.
	
The 'colwidth' value is calculated as (`N` is the ruler column width
number and `M` is the sum of the ruler column widths):

  ( N / M ) * pagewidth

If the ruler 'tablewidth' was specified the column width is multiplied
again by this value.

There is one exception: character rulers that have no 'pagewidth'
specified. In this case the 'colwidth' value is calculated as (where
`N` is the column character width measured on the table ruler):

  ( N / textwidth ) * pagewidth

Row and Data Elements
^^^^^^^^^^^^^^^^^^^^^
Each table row consists of a line of text containing the same number
of 'Data' items as there are columns in the table,

Lines ending in a backslash character are continued on the next line.

Each 'Data' item is an AsciiDoc substitutable string. The substitutions
performed are specified by the 'subs' table definition entry. Data
cannot contain AsciiDoc block elements.

The format of the row is determined by the table definition 'format'
value:

fixed::
      Row data items are assigned by chopping the row up at ruler
      column width boundaries.
csv::
      Data items are assigned the parsed CSV (Comma Separated Values)
      data.
dsv::
      The DSV (Delimiter Separated Values) format is a common UNIX
      tabular text file format.
      - The separator character is a colon (although this can be set
	to any letter using the 'separator' table argument).
      - Common C-style backslash escapes are supported.
      - Blank lines are skipped.

Table Configuration File Definitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Read on if you want to modify existing table behavior or create your
own table definitions.

A table definition consists of two configuration file sections:

1. A tabledef-* section defining both output markup (backend) and
   source parameters (non-backend).
2. A table template section (a template for the the table backend
   markup).

The easiest way to get a feel for how it all fits together is to take
a look at the distributed AsciiDoc table definitions.

Backend independent table definition entries (in `asciidoc.conf`);

-----------------------------------------------------------------------
[tabledef-default]
fillchar=-
format=fixed

[tabledef-csv]
fillchar=~
format=csv

[tabledef-dsv]
fillchar=_
format=dsv
-----------------------------------------------------------------------

HTML backend specific table definition entries (in `html.conf`):

-----------------------------------------------------------------------
[options]
# Screen width in pixels.
pagewidth=800
pageunits=

[tabledef-default]
section=table		
bodyrow=<tr>|</tr>
headdata=<th align="{colalign}" width="{colwidth}{pageunits}">|</th>
footdata=<td align="{colalign}" width="{colwidth}{pageunits}"><strong>|</strong></td>
bodydata=<td align="{colalign}" width="{colwidth}{pageunits}" valign="top">|</td>

[table]
<p><b>Table:</b> {title}</p>
<table rules="groups" border frame="hsides" cellspacing="0" cellpadding="4">
{headrows#}<thead>
{headrows}
{headrows#}</thead>
{footrows#}<tfoot>
{footrows}
{footrows#}</tfoot>
<tbody>
{bodyrows}
</tbody>
</table>
-----------------------------------------------------------------------

DocBook backend specific table definition entries (in `docbook.conf`):

-----------------------------------------------------------------------
[options]
# Printable page width in pts.
pagewidth=380
pageunits=pt

[tabledef-default]
section=table		
colspec=<colspec colwidth="{colwidth}{pageunits}" align="{colalign}">
bodyrow=<row>|</row>
bodydata=<entry>|</entry>

[table]
<{title?table}{title!informaltable} pgwide="0" frame="topbot">
<title>{title}</title>
<tgroup cols="{cols}">
{colspecs}
{headrows#}<thead>
{headrows}
{headrows#}</thead>
{footrows#}<tfoot>
{footrows}
{footrows#}</tfoot>
<tbody>
{bodyrows}
</tbody>
</tgroup>
</{title?table}{title!informaltable}>
-----------------------------------------------------------------------

Backend independent tabledef section entries are:

fillchar::
	A single character that fills source table ruler and underline
	lines.
subs::
	A list of AsciiDoc substitution options specifying the
	substitutions, and substitution order, performed on table data
	items. If undefined defaults to the default AsciiDoc
	substitutions.
format::
	The source row data format ('fixed', 'csv' or 'dsv').

Backend specific tabledef section entries are:

section::
	The name of the table template section.
comspec::
	The table 'comspec' tag definition.
headrow, footrow, bodyrow::
	Table header, footer and body row tag definitions. 'headrow'
	and 'footrow' table definition entries default to row if
	undefined.
headdata, footdata, bodydata::
	Table header, footer and body data tag definitions. 'headdata'
	and 'footdata' table definition entries default to data if
	undefined.

Section specific substitution references:

comspecs::
	Expands to N substituted 'comspec' tags where N is the number
	of columns.
headrows, footrows, bodyrows::
	These references expand to sets of substituted header, footer
	and body rows as defined by the corresponding row and data tag
	definitions.

[[X4]] In addition tables are affected by the following `[miscellaneous]`
configuration file entries:

textwidth::
	The page width (in characters) of the source text. This
	setting is compared to the the table ruler width when
	calculating the relative size of character ruler tables on the
	output page.
pagewidth::
	This integer value is the printable width of the output media.
	Used to calculate 'colwidth' and 'tablewidth' substitution
	values.
pageunits::
	The units of width in output markup width attribute values.

.NOTES:
- The output markup generation is specifically designed to work with
  the HTML and CALS (DocBook) table models, but should be adaptable to
  most XML table schema.
- Table definitions can be "mixed in" from multiple cascading
  configuration files.
- New table definitions inherit the default table definition
  ('tabledef-default') so you only need to override those conf file
  entries that require modification.


Macros
------
Macros are a mechanism for substituting parameterized sections of text
into output documents and for performing specific actions.

There are three types of macros: 'Inline', 'Block' and 'Builtin'.
Macro types are distinguished by their context.

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

`<pattern>=<name>`::
	Inline macro definition.
`<pattern>=#<name>`::
	Block macro definition.
`<pattern>=+<name>`::
	Builtin macro definition.
`<pattern>`::
	Undefine (delete) an existing macro with this `<pattern>`.

`<pattern>` is a Python regular expression and `<name>` is the name of
a substitution section. If `<name>` is omitted then it is the value of
the named group 'name' in `<pattern>`.

Here's what happens during macro substitution:

- Each contextually relevant macro 'pattern' from the `[macros]`
  section is matched against the input source line.
- If a match is found the text to be substituted is loaded from a
  configuration file substitution section named like
  `<name>-inlinemacro` or `<name>-blockmacro` (depending on the
  context).  If the macro definition does not explicitly specify the
  macro name then it is determined by the value of the macro pattern's
  matched 'name' group.
- AsciiDoc glossary references and macro arguments in the substitution
  section are substituted.
- The substituted section replaces the macro reference in the output
  document.

.NOTES:
- Builtin macros don't have configuration file substitution sections.
- The task performed by a Builtin macro is hardwired into the
  asciidoc(1) program; you can customize the syntax but you cannot
  change the Builtin macro name or it's behavior.

Inline Macros
~~~~~~~~~~~~~
Inline macros are replaced by a configuration file substitution
section. Inline Macros occur in an inline element context. Predefined
Inline macros include URL, image and link macros.

The default Inline macro syntax is:

  <name>:<target>[<arguments>]

- `<name>` is the macro name. It can only contain letters, digits or
  dash characters and cannot start with a dash.
- The optional `<target>` cannot contain white space characters (see
  the note below).
- `<arguments>` is an optional list of macro arguments.  See the
  <<"X2","DelimitedBlock, Table and Macro Arguments">> sub-section.
- The square brackets are mandatory even if arguments are omitted.
- Macro references can be escaped by prefixing a backslash character.
- Inline macro calls cannot span multiple lines. 

NOTE: If the `<target>` is a URL, space characters should be replaced
by `%20`. For example `large%20image.png`.

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 add square [] brackets containing an optional
caption immediately following the URL. If no text is inside the
brackets the URL itself is displayed.

Here are some examples:

  http://www.methods.co.nz/asciidoc/[The AsciiDoc home page]
  mailto:srackham@methods.co.nz[email Stuart Rackham]
  mailto:srackham@methods.co.nz[]

Which are rendered like:

http://www.methods.co.nz/asciidoc/[The AsciiDoc home page]

mailto:srackham@methods.co.nz[email Stuart Rackham]

mailto:srackham@methods.co.nz[]

Internal Cross References
^^^^^^^^^^^^^^^^^^^^^^^^^
Two AsciiDoc inline macros are provided for creating hypertext links
within an AsciiDoc document. You can use either the standard macro
syntax or the (preferred) alternative.

anchor
++++++
Used to specify hypertext link targets:

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

The `<id>` is a unique identifier that must begin with a letter. The
optional `<xreflabel>` is the text to be displayed by 'xref' macros
with no captions that refer to this anchor. The `<xreflabel>` is only
really useful when generating DocBook output. Example:

  [[X1]]

If you need to output something enclose in double square brackets you
can suppress anchor generation by preceding the double bracket with a
backslash character.

xref
++++
Creates a hypertext link to a document anchor.

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

The `<id>` refers to an existing anchor `<id>`. The optional
`<caption>` is the link's displayed text. If `<caption>` is not
specified then the `<id>`, enclosed in square brackets, is displayed.
Example:

  <<X1,the first section>>

If you need to output something enclose in double angle brackets you
can suppress anchor generation by preceding the double bracket with a
backslash character.

Linking to External Documents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Hypertext links to external local files are specified using the 'link'
inline macro.

  link:<target>[<caption>]

The 'link' macro generates relative URLs. The link macro `<target>` is
the target file name (relative to the file system location of the
referring document). The optional `<caption>` is the link's displayed
text. If `<caption>` is not specified then `<target>` is displayed.
Example:

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

You can use the `<filename>#<id>` syntax to refer to an anchor within
a target document but this usually only makes sense when linking HTML
documents.

Images can be linked using the `image` macro (see the next section).

Images [[X9]]
^^^^^^^^^^^^^
Images are inserted into the output document using the 'image'
macro. The inline syntax is:

  image:<target>[<arguments>]

The contents of the image file `<target>` is displayed. To display the
image it's file format must be supported by the target backend
application. HTML and DocBook applications normally support PNG or JPG
files.

Image elements are not supported by the LinuxDoc format and the
alternative text in macro argument 1 (if specified) is displayed
instead.

`<target>` file name paths are relative to the location of the
referring document.

.Image Macro Arguments
- The optional first positional macro argument specifies the
  alternative text which is displayed if the output application is
  unable to process the image file. For example:

  image:images/logo.png[Company Logo]

- The optional `width` and `height` named arguments scale the image
  size and can be used in any combination. The following example
  scales the previous example to a height of 32 pixels:

  image:images/logo.png["Company Logo",height=32]

- The optional `link` named argument is used to link the image to
  an external document. The following example links a screenshot
  thumbnail to a full size version:

  image:screen-thumbnail.png[height=32,link="screen.png"]

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

- They occur in a block context.
- The default syntax is `<name>::<target>[<arguments>]` (two colons, not
  one).
- Substitution section names end in `-blockmacro` instead of
  `-inlinemacro`.

A Block macro reference must be contained in a single line which must
be followed by a blank line.

Images
^^^^^^
Images are inserted into the output document using the 'image'
macro. The syntax is:

  image::<target>[<arguments>]

In all respects, apart from context, the use of the block `image`
macro is exactly the same as it's <<X9,inline counterpart>>.

The image can be titled by preceded the `image` macro with a
'BlockTitle'.

For example:

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

Builtin Macros
~~~~~~~~~~~~~~
Builtin macros perform a predefined task that is hardwired into the
asciidoc(1) program. The syntax is identical to Block macros.

Include File Macros
^^^^^^^^^^^^^^^^^^^
These Builtin macros include the contents of a named file in the
source document; it's as if the included file was part of the parent
document.

There are two include macros: `include` which allows nested include
macros and `include1` which does not allow nested includes.

Example:

  include::chapter1.txt[tabsize=4]
  
This includes file `chapter1.txt` which is located in the same
directory as the source document. `chapter1.txt` is processed exactly
as if its text were part of the parent document except that tabs are
expanded to 4 characters.

Example:

  +++++++
  include1::table6.html[]
  +++++++

Since it is enclosed in a CustomBlock the text from `table6.html` is
included and written to the output without any further processing.

.NOTES:
- If the included file name is specified with a relative path then the
  path is relative to the location of the referring document file.
- Include macros can appear inside configuration files.
- Files included from within DelimitedBlocks are read to completion to
  avoid false end-of-block underline termination.
- File inclusion is limited to a depth of 5 to catch recursion
  loops.
- Glossary references are expanded inside the include `target`; if a
  glossary reference is undefined then the included file is silently
  skipped.
- The 'tabsize' named macro argument sets the 'tabsize' value for tab
  expansion in the included file.

Conditional Inclusion Macros
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Lines of text in the source document can be selectively included or
excluded from processing using the conditional inclusion Builtin
macros. There are two forms of conditional inclusion macro usage:

- The first includes enclosed document text between the `ifdef` and
  `endif` macros if the glossary entry is defined:

  ifdef::glossary-ref[]
  :
  endif::glossary-ref[]

- The second includes enclosed document text between the `ifndef` and
  `endif` macros if the glossary entry is not defined:

  ifndef::glossary-ref[]
  :
  endif::glossary-ref[]

In both cases `glossary-ref` is optional in the trailing `endif`
macro.

Check out the `*.conf` configuration files in the asciidoc(1) program
directory for examples.

TIP: Conditional inclusion macros are evaluated when the file is read;
since configuration files are read before the document is processed be
careful not to use glossary references that are created from document
content.


DelimitedBlock, Table and Macro Arguments [[X2]]
------------------------------------------------
Arguments provide a mechanism for passing arbitrary glossary
substitutions to DelimitedBlocks, Tables and Macros. Arguments are
specified as a comma separated list of zero or more positional
arguments followed by zero or more named arguments. The entire
arguments list is enclosed in square brackets.

- Table arguments are specified in the line immediately following the
  ruler line.
- DelimitedBlock arguments are specified in the line immediately
  following the leading delimiter line but will only be processed if:
  1. The DelimitedBlock definition includes the 'argsline' in the
     'options' entry.
  2. The block delimiter line does not contain embedded arguments.
- Table and DelimitedBlock argument lines observe backslash line
  continuation.
- Positional arguments become glossary references `\{1}`,`\{2}` ...
- The entire entire arguments list is glossary reference `\{0}`.
- In the absence of named arguments, positional argument values do not
  need to be quoted unless they contain commas.
- Arguments take precedence over existing glossary entries.
- Quoted argument values have the same syntax and semantics as Python
  string literals.
- The named `options` argument is processed as a comma separated list
  of arguments with zero length string values. For example
  `[options="opt1,opt2,opt3"]` is equivalent to
  `[opt1="",opt2="",opt2=""]`.


Examples:

[]::
  No arguments, no glossary entries created.
  
[Hello, World!]::
  `\{0}` = `"Hello, World!"`, +
  `\{1}` = `"Hello"`, +
  `\{2}` = `"World!"`
  
[backcolor="#0e0e0e", format="csv", options="noborders,wide"]::
  `\{0}` = `backcolor="#0e0e0e",format="csv"`, +
  `\{backcolor}` = `"#0e0e0e"`, +
  `\{format}` = `"csv"`, +
  `\{options}` = `"noborders,wide"`, +
  `\{noborders}` = `""`, +
  `\{wide}` = `""`


manpage Documents [[X1]]
------------------------
Sooner or later, if you program for a UNIX environment, you're going
to have to write a man page.

By observing a couple of additional conventions you can compose
AsciiDoc files that will translate to a DocBook refentry (man page)
document.  The resulting DocBook file can then be translated to the
native roff man page format (or any other format) using programs such
as `xmlto(1)`.

For example, the `asciidoc.1.txt` file in the AsciiDoc distribution
`./doc` directory was used to generate both
`asciidoc.1.css-embedded.html` HTML file and (via the `jw(1)` command)
the `asciidoc.1` roff formatted `asciidoc(1)` man page.

To find out more about man pages view the `man(7)` manpage
(`man 7 man` command).


Document Heading
~~~~~~~~~~~~~~~~
The 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 NAME Section
~~~~~~~~~~~~~~~~
The first manpage section is mandatory and must be called 'NAME' and
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 either side. For example:

  printf, fprintf, sprintf - print formatted output

The SYNOPSIS Section
~~~~~~~~~~~~~~~~~~~~
The second manpage section is mandatory and must be called 'SYNOPSIS'.


Configuration Files [[X7]]
--------------------------
asciidoc(1) is an extremely 'soft' application: it's behavior is
largely controlled by a set of cascading, text based, configuration
files.  Both the AsciiDoc source file syntax and the backend output
formats are determined by configuration file entries.

Configuration File Format
~~~~~~~~~~~~~~~~~~~~~~~~~
All 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.

- Section names consist of one or more alphanumeric, underscore or
  dash characters and cannot begin or end with a dash.
- Lines starting with a hash character "#" are treated as comments and
  ignored.

Sections are either Special Sections or Substitution Sections.

Same named sections and section entries override sections and section
entries from previously loaded configuration files (this is sometimes
referred to as 'cascading').  Consequently, downstream configuration
files need only contain those sections or section entries that need to
be overridden.

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(1) program directory along
with generated backend output and the backend markup spec.

Substitution Sections
~~~~~~~~~~~~~~~~~~~~~
Substitution sections contain backend markup templates that are used
to translate Paragraphs, Macros, DelimitedBlocks, Special Words,
document headers, footers and sections.  Since the text is normally
backend dependent you'll find these sections in the backend specific
configuration files.

A substitution section body contains:
- Backend markup
- Glossary references
- Macro, Table and DelimitedBlock argument references
- Text placeholder

Glossary and argument references are enclosed in curly brackets {},
for example \{target}, and are replaced with the corresponding values
extracted from the AsciiDoc source document or environment.

A text placeholder is a single | character and is used as a
placeholder for encapsulated document text.  Use the `\{brvbar}`
glossary reference if you need a literal | character.

An important property of substitution section bodies is that lines
containing undefined glossary references and macro parameters are not
written to the output file. For example if the AsciiDoc source file
does not contain the optional header date then any section body lines
containing \{date} would be skipped. This property can be used to
selectively exclude lines from section bodies.
See also the <<X8,Calculated Glossary Entries>> sub-section.

Special Sections
~~~~~~~~~~~~~~~~
AsciiDoc reserves the following predefined, or Special, section names
for specific purposes:

miscellaneous::
	Configuration options that don't belong anywhere else.
glossary::
	A dictionary of named substitution values.
specialcharacters::
	Special characters reserved by the backend markup.
tags::
	Markup tag definitions used by AsciiDoc markup mechanisms.
quotes::
	Definitions for inline character formatting quoting.
specialwords::
	Lists of words and phrases singled out for special markup.
replacements::
	Find and replace substitution definitions.
specialsections::
	Define custom section markup for document sections with
	special names.
macros::
	Macro syntax definitions.
titles:
	Section and block title parameters.
paradef*::
	Paragraph element definitions.
blockdef*::
	DelimitedBlock element definitions.
listdef*::
	List element definitions.
tabledef*::
	Table element definitions.

Each line of text in a Special section is a 'section entry'. Section
entries can take the following forms:

'name=value'::
	The entry value is set to 'value'.
'name='::
	The entry value is set to a zero length string.
'name'::
	The entry is undefined (deleted from the configuration).

.NOTES:
- All equals characters inside the `name` must be escaped with a
  backslash character.
- `name` and `value` are stripped of leading and trailing white space.
- Glossary entry names, tag entry names and section names consist of
  one or more alphanumeric, underscore or dash characters. Names
  cannot begin or end with a dash.

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 -g '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 with the
	'include' macro 'tabsize' argument.
textwidth, pagewidth, pageunits::
	These global table related options are documented in the
	<<X4,Table Configuration File Definitions>> sub-section.

NOTE: `[miscellaneous]` configuration file entries can be set using
the asciidoc(1) `-g` command-line option and perform the usual
glossary substitutions.

Titles
^^^^^^
underlines::
	A comma separated list of document Header and Section
	underline *quoted* character pairs starting with the Header
	underline and ending with Section level 4 underline. The
	default setting is:

	underlines="==","--","~~","^^","++"

subs::
	A comma separated list of substitutions that are performed on
	document Header and Section titles. The default value for this
	entry is
	'specialcharacters,quotes,replacements,glossary,macros'.

blocktitle::
	The format of the BlockTitle lines is set by this entry.
	entry in the `[titles]` section of a configuration file.  The
	entry value is a Python regular expression containing the
	named group 'title'. The 'title' group's matching value is
	used as the following element's title.

Tags
^^^^
The `[tags]` section contains AsciiDoc tag definitions (one per
line). Tags are used to translate AsciiDoc inline document elements to
backend document markup.

An AsciiDoc tag definition is formatted like `tagname=starttag|endtag`
and defines the (backend specific) markup for the corresponding
AsciiDoc element. For example:

  emphasis=<em>|</em>

In this example asciidoc(1) replaces the | character with the
emphasized text from the AsciiDoc input file and writes the result to
the output file.

Use the \{brvbar} glossary reference if you need to include a | pipe
character inside tag text.

Glossary Section
^^^^^^^^^^^^^^^^
The optional `[glossary]` section contains glossary entries.  When the
source document is processed glossary references (glossary names
enclosed in curly brackets) are replaced by the corresponding glossary
entry 'value'.

If the glossary `value` requires leading or trailing spaces then the
text should be enclosed in quotation (") characters.

To undefine (delete) a glossary entry insert a name only entry in a
downstream configuration file or use the asciidoc(1) `-g ^name`
command-line option (the glossary entry name is prefixed with a ^
character to delete it).

Special Characters
^^^^^^^^^^^^^^^^^^
The `[specialcharacters]` section specifies how to translate each of
the characters reserved by the backend markup. Each translation is
specified on a single line formatted like:

  special_character=translated_characters

Special characters are normally confined to those that resolve
markup ambiguity (in the case of SGML/XML markups the ampersand, less
than and greater than characters). For example:

  <=&lt;

If you need to output these special characters use the predefined
glossary entries. For example the character entity reference for the
small greek letter mu can be written with `\{amp}#956;` (Unicode
character set encoding).

Quoted Text
^^^^^^^^^^^
The `[quotes]` section defines the text formatting markup characters
that are used to envelope words and word phrases. Each section entry
value has a corresponding tag entry from the `[tags]` section. The
entry name defines the one (or more) characters that quote the text. In this
example a double underscore defines underlined HTML markup:

  [quotes]
  __=underline

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

You can specify the left and right quote strings separately by
separating them with a | character, for example:

  [quotes]
  ((|))=gui

If you set the tag to `none` then a blank string will be substituted
for the quoted text which has the effect of dropping the quote from
the output document.

Special Words
^^^^^^^^^^^^^
The `[specialwords]` section is used to single out words and phrases
that you want to consistently highlight in some way throughout your
document without having to repeatedly specify the markup. The name of
each entry corresponds to a substitution section and the entry value
consists of a list of words and phrases to be highlighted. For
example:

  [specialwords]
  strongwords=NOTE: TODO:

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

The examples specifies that any occurrence of `NOTE:` or `TODO:`
should appear in a bold font.

Words and word phrases are treated as Python regular expressions: for
example, the word `^NOTE:` would only match `NOTE:` if appeared at
the start of a line.

AsciiDoc comes with three built-in Special Word types:
'emphasizedwords', 'monospacedwords' and 'strongwords'. Each type has
a corresponding substitution section. Edit the configuration files to
customize existing Special Words and to add new ones.

.NOTES:
- Word list entries must be separated by space characters.
- Word list entries with embedded spaces should be enclosed in quotation (")
  characters.
- A `[specialwords]` section entry of the form `name=list` adds words
  in 'list' to existing `name` entries.
- A `[specialwords]` section entry of the form `name` undefines
  (deletes) all existing `name` words.
- Since word list entries are processed as Python regular expressions
  you need to be careful to escape regular expression special
  characters.
- By default Special Words are substituted before Inline macros, this
  may lead to undesirable consequences. For example the special word
  `foobar` would be expanded inside the macro call
  `\http://www.foobar.com[]`.  A possible solution is to emphasize
  whole words only using the `\bfoobar\b` regular expression.

Replacements [[X10]]
^^^^^^^^^^^^^^^^^^^^
`[replacements]` configuration file entries specify find and replace
text formatted like:

  find_pattern=replacement_text
  
The find text can be a Python regular expression; the replace text can
contain Python regular expression group references.

Use Replacement shortcuts for often used macro references, for
example:

  \.NEW\.=image:smallnew.gif[New!]

.NOTES:
- If the find or replace text has leading or trailing spaces then the
  text should be enclosed in quotation (") characters.
- Since the find text is processed as a regular expression you need
  to be careful to escape regular expression special characters.

Configuration File Names and Locations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuration files have a `.conf` file name extension; they are
loaded implicitly (based on predefined names) or explicitly (using the
asciidoc(1) `-f` command-line option).

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

1. The asciidoc(1) program directory.
2. The `.asciidoc` directory in the user's home directory (if it
   exists).
3. The AsciiDoc source file directory.

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

1. `asciidoc.conf`
2. `<backend>.conf`
3. `<backend>-<doctype>.conf`

Where `<backend>` and `<doctype>` are values specified by the
asciidoc(1) `-b` and `-d` 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 `-b html` option
is used then asciidoc(1) will look for `mydoc.conf` and
`mydoc-html.conf` in that order.

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

The user can explicitly specify any number of additional configuration
files using the asciidoc(1) `-f` 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 -b html -f extra.conf mydoc.txt

Configuration files (those that exist) will be processed in the
following order:

1. First default global configuration files from the asciidoc program
   directory are loaded:

   asciidoc.conf
   html.conf
   html-article.conf

2. Then, from the users home `~/.asciidoc` directory.  This is were
   you put customization specific to  your own asciidoc documents:

   asciidoc.conf
   html.conf
   html-article.conf

3. Next from the source document project directory (the first three
   apply to all documents in the directory, the last two are specific
   to the mydoc.txt document):

   asciidoc.conf
   html.conf
   html-article.conf
   mydoc.conf
   mydoc-html.conf

4. Finally the file specified by the `-f` command-line option is
   loaded:

   extra.conf

TIP: Use the asciidoc(1) `-v` command-line option to see which
configuration files are loaded and the order of they are loaded.


Using the Glossary
------------------
A glossary reference is enclosed in curly brackets. AsciiDoc replaces
the glossary reference with a corresponding text value. If no
substitutable text is defined then the line containing the glossary
reference is dropped and is not written to the output file.

Glossary references occur in both AsciiDoc documents and configuration
files.

The text value that is substituted for a glossary reference comes from
one of four places:

Configuration file glossary entries::
	These are the entries that are read from the `[glossary]`
	sections of configuration files.
	
Builtin glossary entries::
	The text for the glossary references created automatically
	from the AsciiDoc document header and environment parameters.

Command-line glossary entries::
	These are defined using the asciidoc(1) `-g` command-line
	option.

Calculated glossary references::
	Calculated glossary references contain the glossary name and
	an expression used to calculate the substituted text.

.NOTES:
- You can suppress glossary reference expansion by placing a backslash
  character immediately preceding the glossary name.
- By default glossary references are not expanded in
  IndentedParagraphs, VerbatimBlocks or IndentedBlocks.
- If a glossary entry is defined more than once then precedence is
  determined as follows: command-line glossary entries have the
  highest precedence, next are configuration file glossary entries and
  finally Builtin glossary entries. Within each of these divisions the
  last processed entry takes precedence.
- To include a closing curly bracket } inside a glossary reference
  escape it with a backslash character.
- Macro, Table and DelimitedBlock argument references have the same
  syntax as glossary references (both are enclosed in curly brackets).
- During macro expansion arguments take precedence over glossary
  entries.

Plain Glossary References
~~~~~~~~~~~~~~~~~~~~~~~~~
Plain glossary references take the form `\{<name>}`. If the glossary
`<name>` entry is defined its text value is substituted otherwise the
line containing the reference is dropped from the output. 

Builtin Glossary Entries
~~~~~~~~~~~~~~~~~~~~~~~~
Here's the list of predefined glossary entries.

  {asciidoc-version}	the version of asciidoc(1)
  {asciidoc-dir}	the asciidoc(1) application directory
  {user-dir}		the ~/.asciidoc directory (if it exists)
  {authorinitials}	author initials (from document header)
  {author}		author's full name (from document header)
  {date}		document date (from document header)
  {doctitle}		document title (from document header)
  {email}		author's email address (from document header)
  {firstname}		author first name (from document header)
  {lastname}		author last name (from document header)
  {localdate}		the current date
  {localtime}		the current time
  {manname}		manpage name (defined in NAME section)
  {manpurpose}		manpage (defined in NAME section)
  {mantitle}		manpage title (from document header)
  {manvolnum}		manpage volume number (1..8) (from document header)
  {middlename}		author middle name (from document header)
  {revision}		document revision number (from document header)
  {title}               section title (defined titled element substitution
                        sections)
  {sectnum}             section number (defined in section titles
                        substitution sections)
  {amp}         	ampersand (&) character
  {lt}                  less than (<) character
  {gt}                  greater than (>) character
  {brvbar}		broken vertical bar (|) character
  {empty}		empty string ''
  {infile}		input file name
  {outfile}		output file name
  {doctype}		document type specified by `-d` option
  {filetype}		output file name file extension
  {backend}		document backend specified by `-b` option
  {backend-<backend>}	empty string ''
  {<backend>-<doctype>}	empty string ''
  {doctype-<doctype>}	empty string ''
  {filetype-<fileext>}	empty string ''
  {basebackend}		html, css, docbook or linuxdoc
  {basebackend-<base>}	empty string ''

The entries that translate to blank strings are designed to be used
for conditional line inclusion (remember that if an undefined glossary
entry is referenced then the containing line will be dropped from the
output). You can also use the `ifdef`, `ifndef` and `endif` Builtin
macros in conjunction with glossary names for conditional inclusion.

Calculated Glossary References[[X8]]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These take the following forms:

`\{<name>=<value>}`::
	`<value>` is substituted if the glossary `<name>` entry is
	undefined otherwise the glossary value is substituted.
	`<value>` can contain glossary references of the form
	`\{<name>}`.

`\{<name>?<value>}`::
	`<value>` is substituted if the glossary `<name>` entry is
	defined otherwise an empty string is substituted.
	`<value>` can contain glossary references of the form
	`\{<name>}`.

`\{<name>!<value>}`::
	`<value>` is substituted if the glossary `<name>` entry is
	undefined otherwise an empty string is substituted.
	`<value>` can contain glossary references of the form
	`\{<name>}`.

`\{<name>#<value>}`::
	`<value>` is substituted if the glossary `<name>` entry is
	defined otherwise the undefined glossary entry causes the
	containing line to be dropped.  `<value>` can contain glossary
	references of the form `\{<name>}`.

`\{<name>%<value>}`::
	`<value>` is substituted if the glossary `<name>` entry is not
	defined otherwise the containing line is dropped.  `<value>`
	can contain glossary references of the form `\{<name>}`.

`\{eval:<expression>}`::
	Substitutes the result of the Python `<expression>`. If
	`<expression>` evaluates to None the line containing the
	reference is dropped from the output file.  `<expression>` can
	contain (other types of) glossary references.

`\{sys:<command>}`::
	Substitutes the stdout generated by the execution of the shell
	`<command>`.  `<command>` can contain (other types of)
	glossary references.

`\{sys2:<command>}`::
	Substitutes the stdout and stderr generated by the execution
	of the shell `<command>`.  `<command>` can contain (other
	types of) glossary references.

.NOTES:
- Closing brace characters (}) inside `<value>`, `<expression>` or
  `<command>` literal text must be escaped with a backslash.


Filters
-------
Filters are optional external shell commands used to process Paragraph
and DelimitedBlock content; they are specified in configuration file
Paragraph and DelimitedBlock definitions.

There's nothing special about the filters, they're just standard UNIX
filters: they read text from the standard input, process it, and write
it to the standard output.

Glossary and argument reference substitution is performed on the
filter command prior to execution and can be used to pass parameters
from the AsciiDoc source document to the filter.

NOTE: Filter functionality is currently only available on POSIX
platforms (this includes Cygwin).

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

- First it looks in the user's `$HOME/.asciidoc/filters` directory.
- Then it looks in the asciidoc(1) `./filters` subdirectory.
- Finally it relies on the executing shell to search the environment
  search path (`$PATH`).

Filter Configuration Files
~~~~~~~~~~~~~~~~~~~~~~~~~~
Since filters are normally part of new Paragraph or DelimitedBlock
definitions they are usually accompanied by a configuration file.

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

Code Filter
~~~~~~~~~~~
AsciiDoc comes with a simple minded `code-filter` for highlighting
source code keywords and comments. You can find the `code-filter` in
the AsciiDoc distribution `./filters` subdirectory.

Here's an example:

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

.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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See also the AsciiDoc distribution `./filters/code-filter-readme.txt`
file for instructions).


Tips and Tricks
---------------
Troubleshooting
~~~~~~~~~~~~~~~
- The asciidoc(1) `-v` verbose command-line option displays the order
  of configuration file loading and warns of potential configuration
  file problems.
- Not all valid AsciiDoc documents produce valid backend markup. Read
  the <<X5,AsciiDoc Backends>> section if AsciiDoc output is rejected
  as non-conformant by a backend processor.
  
Gotchas
~~~~~~~
Misinterpreted text formatting::
    If characters in your text are incorrectly interpreted as
    formatting instructions you can suppress formatting by placing a
    backslash character immediately in front of the leading quote
    character(s).  For example in the following line the backslash
    prevents text between the two asterisks from being output in a
    strong (bold) font:

    Add `\*.cs` files and `*.resx` files.

Overlapping text formatting::
    Overlapping text formatting will generate illegal overlapping
    markup tags which will result in downstream XML parsing errors.
    Here's an example:

    Some *strong markup 'that overlaps* emphasized markup'.

Escaping inside DSV table data::
    Delimiter separated text uses C style backslash escape sequences.
    If you want to enter a backslash (for example, to escape AsciiDoc
    text formatting or an inline macro) you need to escape it by
    entering two backslashes.

Multi-line text formatting and macro references::
    Quoted text markup, glossary references and macro references
    cannot be split across multiple lines. Line continuation using a
    trailing backslash character can be used inside Paragraphs,
    ListItems and Tables (useful for long quoted text or inline macro
    references).

Special characters in glossary values::
    Special character substitution precedes glossary reference
    substitution so if glossary values contain special characters you
    may, depending on the substitution context, need to substitute the
    special characters first. For example:

    $ asciidoc -g 'companyname=Bill &amp; Ben' -b html mydoc.txt

Macro arguments::
    - By default macro substitution occurs last, this can lead to
      unexpected results if preceding substitutions modify the macro
      arguments.
    - If named arguments are used then positional argument values must
      be quoted (see also the
      <<"X2","DelimitedBlock, Table and Macro Arguments">>
      sub-section). For example:

      ["Desktop screenshot",width=32]

Ambiguous underlines::
    A DelimitedBlock can immediately follow paragraph without an
    intervening blank line, but be careful, a single line paragraph
    underline may be misinterpreted as a section title underline
    resulting in a "closing block delimiter expected" error.

CSS rule ambiguity::
    One liner embedded CSS rules of the form
    `selector \{property: value}` will be interpreted as a glossary
    references unless a space is inserted after the opening brace.

Combining Separate Documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You have a number of stand-alone AsciiDoc documents that you want to
process as a single document. 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.

. Push the standard title underlines down one level by defining a new
  level 0 underline in a custom configuration file. For example
  `combined.conf`:
  
  [titles] underlines="__","==","--","~~","^^"

. Create a top level wrapper document. For example `combined.txt`:

  Combined Document Title
  _______________________

  include::document1.txt[]

  include::document2.txt[]

  include::document3.txt[]
  
. Process the wrapper document. For example:

  $ asciidoc -b html -f combined.conf combined.txt

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

.NOTES:
- The combined document title uses the newly defined level 0 underline
  (underscore characters).
- Put a blank line between the `include` macro lines to ensure the
  title of the included document is not seen as part of the last
  paragraph of the previous document.
- You won't want document Headers (Author and Revision lines) in the
  included files -- conditionally exclude them if they are necessary
  for stand-alone processing.

Processing Document Sections Separately
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.

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

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

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

Badges in HTML Page Footers
~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the `badges.conf` file in the AsciiDoc distribution `examples\`
directory.

Pretty Printing AsciiDoc Output
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the indentation and layout of the asciidoc(1) output is not to your
liking you can:

1. Change the indentation and layout of the configuration file content
   substitution sections. The `\{empty}` glossary entry is useful for
   outputting trailing blank lines in substitution sections.

2. Or use Dave Raggett's excellent 'HTML Tidy' program to tidy
   asciidoc(1) output. Examples:

   $ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml >mydoc.xml
   $ asciidoc -b css-embedded -o - mydoc.txt | tidy -indent >mydoc.html

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

The Mozilla Web browser also does a good job of displaying XML content
in a collapsible outline format.

Supporting Minor DocBook DTD Variations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The distribution `docbook-sgml.conf` file illustrates how to support
minor DTD variations.

Shipping Stand-alone AsciiDoc Source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Reproducing presentation documents from some else's source has one
major problem: unless your configuration files are the same creator's
you won't get the same output.

The solution is to create a single backend specific composite
configuration file using the asciidoc(1) `-c` 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. This example creates a composite HTML configuration
file for `mydoc.txt`:

  $ asciidoc -c -b html mydoc.txt > mydoc-html.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 -e -b html mydoc.txt

The `-e` option excludes the use of any existing implicit
configuration files, ensuring that only entries from the
`mydoc-html.conf` configuration are used.

Inserting Blank Space
~~~~~~~~~~~~~~~~~~~~~
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.

Vim Commands for Formatting AsciiDoc
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 various AsciiDoc SimpleLists (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.

Indent Paragraphs
^^^^^^^^^^^^^^^^^
Indent whole paragraphs by indenting the fist line with the desired
indent and then executing the `gq}` command.


Processing DocBook Files [[X12]]
--------------------------------
For reasons outlined previously documents with an article or book type
structure will usually be processed using AsciiDoc's DocBook output.
The distributed AsciiDoc User Guide plus the example article and book
template documents have been generated in this way.

The toolchain processing steps are:

. Convert AsciiDoc (`\*.txt`) documents to DocBook XML (`*.xml`) using
  AsciiDoc.
. Convert DocBook XML documents to HTML, XSL-FO or HTML Help source
  files using DocBook XSL Stylesheets and an XML parser.
. Convert the XSL-FO file to PDF using FOP and the HTML Help source
  files to an HTML Help (`*.chm`) file using the Microsoft HTML Help
  Compiler.

Toolchain Components
~~~~~~~~~~~~~~~~~~~~
Here are the commands and packages we use to generate the AsciiDoc
HTML, PDF and HTML Help documentation files:

AsciiDoc::
    Converts AsciiDoc (`\*.txt`) files to DocBook XML (`*.xml`) files.

DocBook XSL Stylesheets::
    This package contains a set of XSL stylesheets for converting
    DocBook XML documents to HTML, XSL-FO and HTML Help source (see
    the <<X13,DocBook XSL Stylesheets section>>.

xsltproc::
    `xsltproc`  is  a command line XML parser for applying XSLT
    stylesheets (in our case the DocBook XSL Stylesheets) to XML
    documents. It is part of libxslt, the XSLT C library for GNOME
    (see http://www.xmlsoft.org[]).

FOP::
    The Apache Formatting Objects Processor converts XSL-FO (`*.fo`)
    files to PDF files (see the <<X14,FOP section>>.

Microsoft Help Compiler::
    The Microsoft HTML Help Compiler (`hhc.exe`) is a command-line
    tool that converts HTML Help source files to a single HTML Help
    (`*.chm`) file. It runs on MS Windows platforms and can be
    downloaded from http://www.microsoft.com[].

AsciiDoc XSL Drivers
~~~~~~~~~~~~~~~~~~~~
You will have noticed that the distributed PDF, HTML and HTML Help
documentation files (for example `./doc/asciidoc.html`) are not the
disappointingly plain outputs produced using the default DocBook XSL
Stylesheets configuration.  This is because they have been processed
using customized DocBook XSL Stylesheet drivers.  

You'll find these DocBook XSL drivers in the distribution `./doc`
directory. The examples which follow are executed from the
distribution `./doc` directory:

`common.xsl`::
    Shared driver parameters.  This file is not used directly but is
    included in all the following drivers.

`chunked.xsl`::
    Generate chunked XHTML (separate HTML pages for each document
    section) in the `./doc/chunked` directory. For example:

    $ python ../asciidoc.py -b docbook asciidoc.txt
    $ xsltproc --nonet chunked.xsl asciidoc.xml

`fo.xsl`::
    Generate XSL Formatting Object (`*.fo`) files for subsequent PDF
    file generation using FOP. For example:

    $ python ../asciidoc.py -b docbook article.txt
    $ xsltproc --nonet fo.xsl article.xml > article.fo
    $ fop.sh article.fo article.pdf

`htmlhelp.xsl`::
    Generate Microsoft HTML Help source files for the MS HTML Help
    Compiler in the `./doc/htmlhelp` directory. See the article at
    http://www.codeproject.com/winhelp/docbook_howto.asp[].  This
    example is run on MS Windows from a Cygwin shell prompt:

    $ python ../asciidoc.py -b docbook asciidoc.txt
    $ xsltproc --nonet htmlhelp.xsl asciidoc.xml
    $ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
    $ mv htmlhelp.chm asciidoc.chm

`manpages.xsl`::
    Generate a `roff(1)` format UNIX man page from a DocBook XML
    'refentry' document. This example generates an `asciidoc.1` man
    page file:

    $ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
    $ xsltproc --nonet manpages.xsl asciidoc.1.xml

`xhtml.xsl`::
    Convert a DocBook XML file to a single XHTML file. For example:

    $ python ../asciidoc.py -b docbook asciidoc.txt
    $ xsltproc --nonet xhtml.xsl asciidoc.xml > asciidoc.html

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


DocBook XSL Stylesheets [[X13]]
-------------------------------
The 'DocBook XSL Stylesheets' package contains a set of XSL
stylesheets for converting DocBook XML documents to HTML, XSL-FO and
HTML Help source (see http//docbook.sourceforge.net/project/xsl/[]).
It is used in conjunction with an XML parser such as `xsltproc`.

Installing DocBook XSL Stylesheets on Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These instructions were carried out on Fedora Core 1 and may differ on
other Linux distributions.

Extract the distribution and set it as the default DocBook XSL Stylesheets with a symbolic link:

  $ su
  # cd /usr/share/sgml/docbook
  # tar -xzf ~srackham/tmp/docbook-xsl-1.66.1.tar.gz
  # rm xsl-stylesheets
  # ln -s docbook-xsl-1.66.1 xsl-stylesheets
 
NOTE: The assumption is made that you have an up to date version of
`libxslt` (which includes the `xsltproc(1)` command) from
http://xmlsoft.org/XSLT/[]. To check enter `xsltproc{nbsp}--version`
at the command prompt.

.Don't hardwire file locations into XSLT drivers
*********************************************************************
There's no need to have elements like this in your XSLT drivers:

  <xsl:import href="C:/bin/docbook-xsl-1.65.1/xhtml/docbook.xsl"/>

It makes them machine and release dependent. It's much better to add
rewrite statements to your machine's XML catalog. This allows you to
use generic URL stylesheet locations, for example:

  <xsl:import href=
  http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>

Here are the relevant rewrite statements from the `/etc/xml/catalog`
file on a Fedora Linux workstation (the catalog location may differ on
other Linux distributions):

  <rewriteSystem systemIdStartString=
  "http://docbook.sourceforge.net/release/xsl/current"
  rewritePrefix=
  "file:///usr/share/sgml/docbook/docbook-xsl-1.66.1"/>

  <rewriteURI uriStartString=
  "http://docbook.sourceforge.net/release/xsl/current"
  rewritePrefix=
  "file:///usr/share/sgml/docbook/docbook-xsl-1.66.1"/>

*********************************************************************

FOP [[X14]]
-----------
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). More the FOP home page is
at http://xml.apache.org/fop/[].

Reasons to us FOP:

. You can produce PDF on both Windows and POSIX platforms.
. The PDF quality is on a par with that produced by `jw(1)`.
. PDF files are about half the size of those produced by `jw(1)` and
  friends.
. Processes images, table of contents and  images and inserts PDF
  Bookmarks and active hypertext links.
. Uses DocBook XML (no need to produce DocBook SGML).

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.

Installing FOP on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~
. Download latest FOP distribution from http://xml.apache.org/fop/[].
. Unzip to `C:\bin`.
. Edit the distribution `fop.bat` file and put it in the search
  `PATH`:

  set LOCAL_FOP_HOME=C:\bin\fop-0.20.5\

. Download the JIMI image processing library from
  http://java.sun.com/products/jimi/[].
. Extract the `JimiProClasses.jar` library from the JIMI distribution
  and copy to the FOP `./lib` directory.
. Edit the distribution `fop.bat` file again and add the JIMI library
  to `LOCALCLASSPATH`:

  set LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\JimiProClasses.jar
  
. You should now be able to run FOP from a DOS prompt -- execute
  it without arguments to get a list of command options:

  > fop.bat

Installing FOP on Linux
~~~~~~~~~~~~~~~~~~~~~~~
Here's how I installed FOP on Fedora Core 1:

. Download latest FOP distribution from http://xml.apache.org/fop/[].
. Install the FOP distribution:

  $ su
  # cd /usr/local/lib
  # unzip ~srackham/tmp/fop-0.20.5-bin.zip
  # cp /usr/local/lib/fop-0.20.5/fop.sh /usr/local/bin
  # chmod +x /usr/local/bin/fop.sh

. Edit the FOP start script `fop.sh` adding this line to the start of
  the script:

  FOP_HOME=/usr/local/lib/fop-0.20.5

. Download the JIMI image processing library from
  http://java.sun.com/products/jimi/[].
. Extract the `JimiProClasses.jar` library from the JIMI distribution
  and copy to the FOP `lib` directory.

  # cp ~srackham/tmp/JimiProClasses.jar /usr/local/lib/fop-0.20.5/lib/
 
. You should now be able to run FOP from a DOS prompt -- execute
  it without arguments to get a list of command options:

  $ fop.sh

Installing Java on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~
First check that Java is not already installed:

. Open a DOS 'Command Prompt' window.
. Enter this command:

  java -version

You should see something like this:

  java version "1.4.2_01"
  Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06)
  Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode)

If you don't Java is not installed and you need to:

. Download the Java Runtime (JRE) for Windows from
  http://java.sun.com[].
. Install using the instructions on the download page.

Installing Java on Linux
~~~~~~~~~~~~~~~~~~~~~~~~
Check Java is not already installed by entering the following command:

  $ java -version

You should see something like this:

  java version "1.4.2_01"
  Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06)
  Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode)

If you don't Java is not installed and you need to download the Sun
Java Runtime (JRE) for Linux from http://java.sun.com[].

Here's how I installed the RPM version of the JRE on Fedora Core 1:

  $ ./j2re-1_4_2_05-linux-i586-rpm.bin
  $ su
  # rpm -vih j2re-1_4_2_05-linux-i586.rpm
  # vi /etc/profile.d/java.sh
  # chmod +x /etc/profile.d/java.sh
  ^D
  $ . /etc/profile.d/java.sh
  $ java -version
  java version "1.4.2_05"
  Java(TM) 2 Runtime Environment, Standard Edition (build
  1.4.2_05-b04)
  Java HotSpot(TM) Client VM (build 1.4.2_05-b04, mixed mode)
  $

The following two lines are entered into the `/etc/profile.d/java.sh`
file:

  export PATH=$PATH:/usr/java/j2re1.4.2_05/bin/
  export JAVA_HOME=/usr/java/j2re1.4.2_05


XML and Character Sets
----------------------
The default XML character set `UTF-8` is used when AsciiDoc generates
DocBook files (but you can change it by changing the `xmldecl`
glossary entry in the `docbook.conf` file or by composing your own
configuration file `[header]` section).

If you're familiar with HTML there are many predefined character
entities that you will have taken for granted -- for example the
non-breaking space character `&nbsp;`. XML has only five predefined
named character entities: `&amp;`, `&lt;`, `&gt;`, `&quot;` and
`&apos;`. Any others (for example `&nbsp;`) have to be either defined
or included.

TIP: If you get an 'undefined entity' error when processing DocBook
files you'll may find that you've used and HTML character entity
that's not been included. An easy (although inelegant) fix is to use
the character's character code instead of it's symbolic name (for
example use `&#160;` instead of `&nbsp;`).

If your system has been configured with an XML catalog you may find a
number of entity sets are already automatically included -- if you're
using Fedora Linux take a look at the global `/etc/xml/catalog` file.

PDF Fonts
~~~~~~~~~
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.
