You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kylin.apache.org by li...@apache.org on 2015/03/03 11:00:15 UTC
[47/52] [abbrv] [partial] incubator-kylin git commit: update
ace-builds to new version
http://git-wip-us.apache.org/repos/asf/incubator-kylin/blob/99a418c0/webapp/app/components/ace-builds/demo/kitchen-sink/docs/asciidoc.asciidoc
----------------------------------------------------------------------
diff --git a/webapp/app/components/ace-builds/demo/kitchen-sink/docs/asciidoc.asciidoc b/webapp/app/components/ace-builds/demo/kitchen-sink/docs/asciidoc.asciidoc
new file mode 100644
index 0000000..8cddab5
--- /dev/null
+++ b/webapp/app/components/ace-builds/demo/kitchen-sink/docs/asciidoc.asciidoc
@@ -0,0 +1,6040 @@
+AsciiDoc User Guide
+===================
+Stuart Rackham <sr...@gmail.com>
+:Author Initials: SJR
+:toc:
+:icons:
+:numbered:
+:website: http://www.methods.co.nz/asciidoc/
+
+AsciiDoc is a text document format for writing notes, documentation,
+articles, books, ebooks, slideshows, web pages, blogs and UNIX man
+pages. AsciiDoc files can be translated to many formats including
+HTML, PDF, EPUB, man page. 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.
+
+.This document
+**********************************************************************
+This is an overly large document, it probably needs to be refactored
+into a Tutorial, 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 `doc` directory.
+**********************************************************************
+
+
+Introduction
+------------
+AsciiDoc is a plain text human readable/writable document format that
+can be translated to DocBook or 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 or
+use the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI,
+LaTeX, PostScript, man page, HTML and text formats.
+
+The AsciiDoc format is a useful presentation format in its own right:
+AsciiDoc markup is simple, intuitive and as such is easily proofed and
+edited.
+
+AsciiDoc is light weight: it consists of a single Python script and a
+bunch of configuration files. Apart from asciidoc(1) and a Python
+interpreter, no other programs are required to convert AsciiDoc text
+files to DocBook or HTML. See <<X11,Example AsciiDoc Documents>>
+below.
+
+Text markup conventions tend to be a matter of (often 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 also create configuration files to translate AsciiDoc
+documents to almost any SGML/XML markup.
+
+asciidoc(1) comes with a set of configuration files to translate
+AsciiDoc articles, books and man pages to HTML or DocBook backend
+formats.
+
+.My AsciiDoc Itch
+**********************************************************************
+DocBook has emerged as the de facto standard Open Source documentation
+format. But DocBook is a complex language, the markup is difficult to
+read and even more difficult to write directly -- I found I was
+spending more time typing markup tags, consulting reference manuals
+and fixing syntax errors, than I was writing the documentation.
+**********************************************************************
+
+
+[[X6]]
+Getting Started
+---------------
+Installing AsciiDoc
+~~~~~~~~~~~~~~~~~~~
+See the `README` and `INSTALL` files for install prerequisites and
+procedures. Packagers take a look at <<X38,Packager Notes>>.
+
+[[X11]]
+Example AsciiDoc Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+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 {website}. Press the 'Page Source' sidebar menu item to view
+ corresponding AsciiDoc source.
+- Read the `*.txt` source files in the distribution `./doc` directory
+ along with the corresponding HTML and DocBook XML files.
+
+
+AsciiDoc Document Types
+-----------------------
+There are three types of AsciiDoc documents: article, book and
+manpage. All document types share the same AsciiDoc format with some
+minor variations. If you are familiar with DocBook you will have
+noticed that AsciiDoc document types correspond to the same-named
+DocBook document types.
+
+Use the asciidoc(1) `-d` (`--doctype`) option to specify the AsciiDoc
+document type -- the default document type is 'article'.
+
+By convention the `.txt` file extension is used for AsciiDoc document
+source files.
+
+article
+~~~~~~~
+Used for short documents, articles and general documentation. See the
+AsciiDoc distribution `./doc/article.txt` example.
+
+AsciiDoc defines standard DocBook article frontmatter and backmatter
+<<X93,section markup templates>> (appendix, abstract, bibliography,
+glossary, index).
+
+book
+~~~~
+Books share the same format as articles, with the following
+differences:
+
+- The part titles in multi-part books are <<X17,top level titles>>
+ (same level as book title).
+- Some sections are book specific e.g. preface and colophon.
+
+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 defines standard DocBook book frontmatter and backmatter
+<<X93,section markup templates>> (appendix, dedication, preface,
+bibliography, glossary, index, colophon).
+
+.Example book documents
+Book::
+ The `./doc/book.txt` file in the AsciiDoc distribution.
+
+Multi-part book::
+ The `./doc/book-multi.txt` file in the AsciiDoc distribution.
+
+manpage
+~~~~~~~
+Used to generate roff format UNIX manual pages. AsciiDoc manpage
+documents observe special header title and section naming conventions
+-- see the <<X1,Manpage Documents>> section for details.
+
+AsciiDoc defines the 'synopsis' <<X93,section markup template>> to
+generate the DocBook `refsynopsisdiv` section.
+
+See also the asciidoc(1) man page source (`./doc/asciidoc.1.txt`) from
+the AsciiDoc distribution.
+
+
+[[X5]]
+AsciiDoc Backends
+-----------------
+The asciidoc(1) command translates an AsciiDoc formatted file to the
+backend format specified by the `-b` (`--backend`) command-line
+option. asciidoc(1) itself has little intrinsic knowledge of backend
+formats, all translation rules are contained in customizable cascading
+configuration files. Backend specific attributes are listed in the
+<<X88,Backend Attributes>> section.
+
+docbook45::
+ Outputs DocBook XML 4.5 markup.
+
+html4::
+ This backend generates plain HTML 4.01 Transitional markup.
+
+xhtml11::
+ This backend generates XHTML 1.1 markup styled with CSS2. Output
+ files have an `.html` extension.
+
+html5::
+ This backend generates HTML 5 markup, apart from the inclusion of
+ <<X98,audio and video block macros>> it is functionally identical to
+ the 'xhtml11' backend.
+
+slidy::
+ Use this backend to generate self-contained
+ http://www.w3.org/Talks/Tools/Slidy2/[Slidy] HTML slideshows for
+ your web browser from AsciiDoc documents. The Slidy backend is
+ documented in the distribution `doc/slidy.txt` file and
+ {website}slidy.html[online].
+
+wordpress::
+ A minor variant of the 'html4' backend to support
+ http://srackham.wordpress.com/blogpost1/[blogpost].
+
+latex::
+ Experimental LaTeX backend.
+
+Backend Aliases
+~~~~~~~~~~~~~~~
+Backend aliases are alternative names for AsciiDoc backends. AsciiDoc
+comes with two backend aliases: 'html' (aliased to 'xhtml11') and
+'docbook' (aliased to 'docbook45').
+
+You can assign (or reassign) backend aliases by setting an AsciiDoc
+attribute named like `backend-alias-<alias>` to an AsciiDoc backend
+name. For example, the following backend alias attribute definitions
+appear in the `[attributes]` section of the global `asciidoc.conf`
+configuration file:
+
+ backend-alias-html=xhtml11
+ backend-alias-docbook=docbook45
+
+[[X100]]
+Backend Plugins
+~~~~~~~~~~~~~~~
+The asciidoc(1) `--backend` option is also used to install and manage
+backend <<X101,plugins>>.
+
+- A backend plugin is used just like the built-in backends.
+- Backend plugins <<X27,take precedence>> over built-in backends with
+ the same name.
+- You can use the `{asciidoc-confdir}` <<X60, intrinsic attribute>> to
+ refer to the built-in backend configuration file location from
+ backend plugin configuration files.
+- You can use the `{backend-confdir}` <<X60, intrinsic attribute>> to
+ refer to the backend plugin configuration file location.
+- By default backends plugins are installed in
+ `$HOME/.asciidoc/backends/<backend>` where `<backend>` is the
+ backend name.
+
+
+DocBook
+-------
+AsciiDoc generates 'article', 'book' and 'refentry'
+http://www.docbook.org/[DocBook] documents (corresponding to the
+AsciiDoc 'article', 'book' and 'manpage' document types).
+
+Most Linux distributions come with conversion tools (collectively
+called a toolchain) for <<X12,converting DocBook files>> to
+presentation formats such as Postscript, HTML, PDF, EPUB, DVI,
+PostScript, LaTeX, roff (the native man page format), HTMLHelp,
+JavaHelp and text. There are also programs that allow you to view
+DocBook files directly, for example http://live.gnome.org/Yelp[Yelp]
+(the GNOME help viewer).
+
+[[X12]]
+Converting DocBook to other file formats
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+DocBook files are validated, parsed and translated various
+presentation file formats using a combination of applications
+collectively called a DocBook 'tool chain'. The 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, EPUB, DVI, PostScript, LaTeX).
+
+A wide range of user output format requirements coupled with a choice
+of available tools and stylesheets results in many valid tool chain
+combinations.
+
+[[X43]]
+a2x Toolchain Wrapper
+~~~~~~~~~~~~~~~~~~~~~
+One of the biggest hurdles for new users is installing, configuring
+and using a DocBook XML toolchain. `a2x(1)` can help -- it's a
+toolchain wrapper command that will generate XHTML (chunked and
+unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text
+file outputs from an AsciiDoc text file. `a2x(1)` does all the grunt
+work associated with generating and sequencing the toolchain commands
+and managing intermediate and output files. `a2x(1)` also optionally
+deploys admonition and navigation icons and a CSS stylesheet. See the
+`a2x(1)` man page for more details. In addition to `asciidoc(1)` you
+also need <<X40,xsltproc(1)>>, <<X13,DocBook XSL Stylesheets>> and
+optionally: <<X31,dblatex>> or <<X14,FOP>> (to generate PDF);
+`w3m(1)` or `lynx(1)` (to generate text).
+
+The following examples generate `doc/source-highlight-filter.pdf` from
+the AsciiDoc `doc/source-highlight-filter.txt` source file. The first
+example uses `dblatex(1)` (the default PDF generator) the second
+example forces FOP to be used:
+
+ $ a2x -f pdf doc/source-highlight-filter.txt
+ $ a2x -f pdf --fop doc/source-highlight-filter.txt
+
+See the `a2x(1)` man page for details.
+
+TIP: Use the `--verbose` command-line option to view executed
+toolchain commands.
+
+HTML generation
+~~~~~~~~~~~~~~~
+AsciiDoc produces nicely styled HTML directly without requiring a
+DocBook toolchain but there are also advantages in going the DocBook
+route:
+
+- HTML from DocBook can optionally include automatically generated
+ indexes, tables of contents, footnotes, lists of figures and tables.
+- DocBook toolchains can also (optionally) generate separate (chunked)
+ linked HTML pages for each document section.
+- Toolchain processing performs link and document validity checks.
+- If the DocBook 'lang' attribute is set then things like table of
+ contents, figure and table captions and admonition captions will be
+ output in the specified language (setting the AsciiDoc 'lang'
+ attribute sets the DocBook 'lang' attribute).
+
+On the other hand, HTML output directly from AsciiDoc is much faster,
+is easily customized and can be used in situations where there is no
+suitable DocBook toolchain (for example, see the {website}[AsciiDoc
+website]).
+
+PDF generation
+~~~~~~~~~~~~~~
+There are two commonly used tools to generate PDFs from DocBook,
+<<X31,dblatex>> and <<X14,FOP>>.
+
+.dblatex or FOP?
+- 'dblatex' is easier to install, there's zero configuration
+ required and no Java VM to install -- it just works out of the box.
+- 'dblatex' source code highlighting and numbering is superb.
+- 'dblatex' is easier to use as it converts DocBook directly to PDF
+ whereas before using 'FOP' you have to convert DocBook to XML-FO
+ using <<X13,DocBook XSL Stylesheets>>.
+- 'FOP' is more feature complete (for example, callouts are processed
+ inside literal layouts) and arguably produces nicer looking output.
+
+HTML Help generation
+~~~~~~~~~~~~~~~~~~~~
+. Convert DocBook XML documents to HTML Help compiler source files
+ using <<X13,DocBook XSL Stylesheets>> and <<X40,xsltproc(1)>>.
+. Convert the HTML Help source (`.hhp` and `.html`) files to HTML Help
+ (`.chm`) files using the <<X67,Microsoft HTML Help Compiler>>.
+
+Toolchain components summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+AsciiDoc::
+ Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files.
+
+[[X13]]http://docbook.sourceforge.net/projects/xsl/[DocBook XSL Stylesheets]::
+ These are a set of XSL stylesheets containing rules for converting
+ DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.
+ The stylesheets are used in conjunction with an XML parser such as
+ <<X40,xsltproc(1)>>.
+
+[[X40]]http://www.xmlsoft.org[xsltproc]::
+ An XML parser for applying XSLT stylesheets (in our case the
+ <<X13,DocBook XSL Stylesheets>>) to XML documents.
+
+[[X31]]http://dblatex.sourceforge.net/[dblatex]::
+ Generates PDF, DVI, PostScript and LaTeX formats directly from
+ DocBook source via the intermediate LaTeX typesetting language --
+ uses <<X13,DocBook XSL Stylesheets>>, <<X40,xsltproc(1)>> and
+ `latex(1)`.
+
+[[X14]]http://xml.apache.org/fop/[FOP]::
+ The Apache Formatting Objects Processor converts XSL-FO (`.fo`)
+ files to PDF files. The XSL-FO files are generated from DocBook
+ source files using <<X13,DocBook XSL Stylesheets>> and
+ <<X40,xsltproc(1)>>.
+
+[[X67]]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 dblatex configuration files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The AsciiDoc distribution `./dblatex` directory contains
+`asciidoc-dblatex.xsl` (customized XSL parameter settings) and
+`asciidoc-dblatex.sty` (customized LaTeX settings). These are examples
+of optional <<X31,dblatex>> output customization and are used by
+<<X43,a2x(1)>>.
+
+AsciiDoc DocBook XSL Stylesheets drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You will have noticed that the distributed HTML and HTML Help
+documentation files (for example `./doc/asciidoc.html`) are not the
+plain outputs produced using the default 'DocBook XSL Stylesheets'
+configuration. This is because they have been processed using
+customized DocBook XSL Stylesheets along with (in the case of HTML
+outputs) the custom `./stylesheets/docbook-xsl.css` CSS stylesheet.
+
+You'll find the customized DocBook XSL drivers along with additional
+documentation in the distribution `./docbook-xsl` directory. The
+examples that follow are executed from the distribution documentation
+(`./doc`) directory. These drivers are also used by <<X43,a2x(1)>>.
+
+`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 ../docbook-xsl/chunked.xsl asciidoc.xml
+
+`epub.xsl`::
+ Used by <<X43,a2x(1)>> to generate EPUB formatted documents.
+
+`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 ../docbook-xsl/fo.xsl article.xml > article.fo
+ $ fop article.fo article.pdf
+
+`htmlhelp.xsl`::
+ Generate Microsoft HTML Help source files for the MS HTML Help
+ Compiler in the `./doc/htmlhelp` directory. This example is run on
+ MS Windows from a Cygwin shell prompt:
+
+ $ python ../asciidoc.py -b docbook asciidoc.txt
+ $ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
+ $ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
+
+`manpage.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 ../docbook-xsl/manpage.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 ../docbook-xsl/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`.
+
+
+Generating Plain Text Files
+---------------------------
+AsciiDoc does not have a text backend (for most purposes AsciiDoc
+source text is fine), however you can convert AsciiDoc text files to
+formatted text using the AsciiDoc <<X43,a2x(1)>> toolchain wrapper
+utility.
+
+
+[[X35]]
+HTML5 and XHTML 1.1
+-------------------
+The 'xhtml11' and 'html5' backends embed or link CSS and JavaScript
+files in their outputs, there is also a <<X99,themes>> plugin
+framework.
+
+- If the AsciiDoc 'linkcss' attribute is defined then CSS and
+ JavaScript files are linked to the output document, otherwise they
+ are embedded (the default behavior).
+- The default locations for CSS and JavaScript files can be changed by
+ setting the AsciiDoc 'stylesdir' and 'scriptsdir' attributes
+ respectively.
+- The default locations for embedded and linked files differ and are
+ calculated at different times -- embedded files are loaded when
+ asciidoc(1) generates the output document, linked files are loaded
+ by the browser when the user views the output document.
+- Embedded files are automatically inserted in the output files but
+ you need to manually copy linked CSS and Javascript files from
+ AsciiDoc <<X27,configuration directories>> to the correct location
+ relative to the output document.
+
+.Stylesheet file locations
+[cols="3*",frame="topbot",options="header"]
+|====================================================================
+|'stylesdir' attribute
+|Linked location ('linkcss' attribute defined)
+|Embedded location ('linkcss' attribute undefined)
+
+|Undefined (default).
+|Same directory as the output document.
+|`stylesheets` subdirectory in the AsciiDoc configuration directory
+(the directory containing the backend conf file).
+
+|Absolute or relative directory name.
+|Absolute or relative to the output document.
+|Absolute or relative to the AsciiDoc configuration directory (the
+directory containing the backend conf file).
+
+|====================================================================
+
+.JavaScript file locations
+[cols="3*",frame="topbot",options="header"]
+|====================================================================
+|'scriptsdir' attribute
+|Linked location ('linkcss' attribute defined)
+|Embedded location ('linkcss' attribute undefined)
+
+|Undefined (default).
+|Same directory as the output document.
+|`javascripts` subdirectory in the AsciiDoc configuration directory
+(the directory containing the backend conf file).
+
+|Absolute or relative directory name.
+|Absolute or relative to the output document.
+|Absolute or relative to the AsciiDoc configuration directory (the
+directory containing the backend conf file).
+
+|====================================================================
+
+[[X99]]
+Themes
+~~~~~~
+The AsciiDoc 'theme' attribute is used to select an alternative CSS
+stylesheet and to optionally include additional JavaScript code.
+
+- Theme files reside in an AsciiDoc <<X27,configuration directory>>
+ named `themes/<theme>/` (where `<theme>` is the the theme name set
+ by the 'theme' attribute). asciidoc(1) sets the 'themedir' attribute
+ to the theme directory path name.
+- The 'theme' attribute can also be set using the asciidoc(1)
+ `--theme` option, the `--theme` option can also be used to manage
+ theme <<X101,plugins>>.
+- AsciiDoc ships with two themes: 'flask' and 'volnitsky'.
+- The `<theme>.css` file replaces the default `asciidoc.css` CSS file.
+- The `<theme>.js` file is included in addition to the default
+ `asciidoc.js` JavaScript file.
+- If the <<X66,data-uri>> attribute is defined then icons are loaded
+ from the theme `icons` sub-directory if it exists (i.e. the
+ 'iconsdir' attribute is set to theme `icons` sub-directory path).
+- Embedded theme files are automatically inserted in the output files
+ but you need to manually copy linked CSS and Javascript files to the
+ location of the output documents.
+- Linked CSS and JavaScript theme files are linked to the same linked
+ locations as <<X35,other CSS and JavaScript files>>.
+
+For example, the command-line option `--theme foo` (or `--attribute
+theme=foo`) will cause asciidoc(1) to search <<"X27","configuration
+file locations 1, 2 and 3">> for a sub-directory called `themes/foo`
+containing the stylesheet `foo.css` and optionally a JavaScript file
+name `foo.js`.
+
+
+Document Structure
+------------------
+An AsciiDoc document consists of a series of <<X8,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.
+
+Block Elements
+~~~~~~~~~~~~~~
+Block elements consist of one or more lines of text and may contain
+other block elements.
+
+The AsciiDoc block structure can be informally summarized as follows
+footnote:[This is a rough structural guide, not a rigorous syntax
+definition]:
+
+ Document ::= (Header?,Preamble?,Section*)
+ Header ::= (Title,(AuthorInfo,RevisionInfo?)?)
+ AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
+ RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?)
+ Preamble ::= (SectionBody)
+ Section ::= (Title,SectionBody?,(Section)*)
+ SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+
+ Block ::= (Paragraph|DelimitedBlock|List|Table)
+ List ::= (BulletedList|NumberedList|LabeledList|CalloutList)
+ BulletedList ::= (ListItem)+
+ NumberedList ::= (ListItem)+
+ CalloutList ::= (ListItem)+
+ LabeledList ::= (ListEntry)+
+ ListEntry ::= (ListLabel,ListItem)
+ ListLabel ::= (ListTerm+)
+ ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)
+
+Where:
+
+- '?' implies zero or one occurrence, '+' implies one or more
+ occurrences, '*' implies zero or more occurrences.
+- All block elements are separated by line boundaries.
+- `BlockId`, `AttributeEntry` and `AttributeList` block elements (not
+ shown) can occur almost anywhere.
+- There are a number of document type and backend specific
+ restrictions imposed on the block syntax.
+- The following elements cannot contain blank lines: Header, Title,
+ Paragraph, ItemText.
+- A ListParagraph is a Paragraph with its 'listelement' option set.
+- A ListContinuation is a <<X15,list continuation element>>.
+
+[[X95]]
+Header
+~~~~~~
+The Header contains document meta-data, typically title plus optional
+authorship and revision information:
+
+- The Header is optional, but if it is used it must start with a
+ document <<X17,title>>.
+- Optional Author and Revision information immediately follows the
+ header title.
+- The document header must be separated from the remainder of the
+ document by one or more blank lines and cannot contain blank lines.
+- The header can include comments.
+- The header can include <<X18,attribute entries>>, typically
+ 'doctype', 'lang', 'encoding', 'icons', 'data-uri', 'toc',
+ 'numbered'.
+- Header attributes are overridden by command-line attributes.
+- If the header contains non-UTF-8 characters then the 'encoding' must
+ precede the header (either in the document or on the command-line).
+
+Here's an example AsciiDoc document header:
+
+ Writing Documentation using AsciiDoc
+ ====================================
+ Joe Bloggs <jb...@mymail.com>
+ v2.0, February 2003:
+ Rewritten for version 2 release.
+
+The author information line contains the author's name optionally
+followed by the author's email address. The author's name is formatted
+like:
+
+ firstname[ [middlename ]lastname][ <email>]]
+
+i.e. a first name followed by optional middle and last names followed
+by an email address in that order. Multi-word first, middle and last
+names can be entered using the underscore as a word separator. The
+email address comes last and must be enclosed in angle <> brackets.
+Here a some examples of author information lines:
+
+ Joe Bloggs <jb...@mymail.com>
+ Joe Bloggs
+ Vincent Willem van_Gogh
+
+If the author line does not match the above specification then the
+entire author line is treated as the first name.
+
+The optional revision information line follows the author information
+line. The revision information can be one of two formats:
+
+. An optional document revision number followed by an optional
+ revision date followed by an optional revision remark:
++
+--
+ * If the revision number is specified it must be followed by a
+ comma.
+ * The revision number must contain at least one numeric character.
+ * Any non-numeric characters preceding the first numeric character
+ will be dropped.
+ * If a revision remark is specified it must be preceded by a colon.
+ The revision remark extends from the colon up to the next blank
+ line, attribute entry or comment and is subject to normal text
+ substitutions.
+ * If a revision number or remark has been set but the revision date
+ has not been set then the revision date is set to the value of the
+ 'docdate' attribute.
+
+Examples:
+
+ v2.0, February 2003
+ February 2003
+ v2.0,
+ v2.0, February 2003: Rewritten for version 2 release.
+ February 2003: Rewritten for version 2 release.
+ v2.0,: Rewritten for version 2 release.
+ :Rewritten for version 2 release.
+--
+
+. The revision information line can also be an RCS/CVS/SVN $Id$
+ marker:
++
+--
+ * AsciiDoc extracts the 'revnumber', 'revdate', and 'author'
+ attributes from the $Id$ revision marker and displays them in the
+ document header.
+ * If an $Id$ revision marker is used the header author line can be
+ omitted.
+
+Example:
+
+ $Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $
+--
+
+You can override or set header parameters by passing 'revnumber',
+'revremark', 'revdate', 'email', 'author', 'authorinitials',
+'firstname' and 'lastname' attributes using the asciidoc(1) `-a`
+(`--attribute`) command-line option. For example:
+
+ $ asciidoc -a revdate=2004/07/27 article.txt
+
+Attribute entries can also be added to the header for substitution in
+the header template with <<X18,Attribute Entry>> elements.
+
+The 'title' element in HTML outputs is set to the AsciiDoc document
+title, you can set it to a different value by including a 'title'
+attribute entry in the document header.
+
+[[X87]]
+Additional document header information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+AsciiDoc has two mechanisms for optionally including additional
+meta-data in the header of the output document:
+
+'docinfo' configuration file sections::
+If a <<X7,configuration file>> section named 'docinfo' has been loaded
+then it will be included in the document header. Typically the
+'docinfo' section name will be prefixed with a '+' character so that it
+is appended to (rather than replace) other 'docinfo' sections.
+
+'docinfo' files::
+Two docinfo files are recognized: one named `docinfo` and a second
+named like the AsciiDoc source file with a `-docinfo` suffix. For
+example, if the source document is called `mydoc.txt` then the
+document information files would be `docinfo.xml` and
+`mydoc-docinfo.xml` (for DocBook outputs) and `docinfo.html` and
+`mydoc-docinfo.html` (for HTML outputs). The <<X97,docinfo, docinfo1
+and docinfo2>> attributes control which docinfo files are included in
+the output files.
+
+The contents docinfo templates and files is dependent on the type of
+output:
+
+HTML::
+ Valid 'head' child elements. Typically 'style' and 'script' elements
+ for CSS and JavaScript inclusion.
+
+DocBook::
+ Valid 'articleinfo' or 'bookinfo' child elements. DocBook defines
+ numerous elements for document meta-data, for example: copyrights,
+ document history and authorship information. See the DocBook
+ `./doc/article-docinfo.xml` example that comes with the AsciiDoc
+ distribution. The rendering of meta-data elements (or not) is
+ DocBook processor dependent.
+
+
+[[X86]]
+Preamble
+~~~~~~~~
+The Preamble is an optional untitled section body between the document
+Header and the first Section title.
+
+Sections
+~~~~~~~~
+In addition to the document title (level 0), AsciiDoc supports four
+section levels: 1 (top) to 4 (bottom). Section levels are delimited
+by section <<X17,titles>>. Sections are translated using
+configuration file <<X93,section markup templates>>. AsciiDoc
+generates the following <<X60,intrinsic attributes>> specifically for
+use in section markup templates:
+
+level::
+The `level` attribute is the section level number, it is normally just
+the <<X17,title>> level number (1..4). However, if the `leveloffset`
+attribute is defined it will be added to the `level` attribute. The
+`leveloffset` attribute is useful for <<X90,combining documents>>.
+
+sectnum::
+The `-n` (`--section-numbers`) command-line option generates the
+`sectnum` (section number) attribute. The `sectnum` attribute is used
+for section numbers in HTML outputs (DocBook section numbering are
+handled automatically by the DocBook toolchain commands).
+
+[[X93]]
+Section markup templates
+^^^^^^^^^^^^^^^^^^^^^^^^
+Section markup templates specify output markup and are defined in
+AsciiDoc configuration files. Section markup template names are
+derived as follows (in order of precedence):
+
+1. From the title's first positional attribute or 'template'
+ attribute. For example, the following three section titles are
+ functionally equivalent:
++
+.....................................................................
+[[terms]]
+[glossary]
+List of Terms
+-------------
+
+["glossary",id="terms"]
+List of Terms
+-------------
+
+[template="glossary",id="terms"]
+List of Terms
+-------------
+.....................................................................
+
+2. When the title text matches a configuration file
+ <<X16,`[specialsections]`>> entry.
+3. If neither of the above the default `sect<level>` template is used
+ (where `<level>` is a number from 1 to 4).
+
+In addition to the normal section template names ('sect1', 'sect2',
+'sect3', 'sect4') AsciiDoc has the following templates for
+frontmatter, backmatter and other special sections: 'abstract',
+'preface', 'colophon', 'dedication', 'glossary', 'bibliography',
+'synopsis', 'appendix', 'index'. These special section templates
+generate the corresponding Docbook elements; for HTML outputs they
+default to the 'sect1' section template.
+
+Section IDs
+^^^^^^^^^^^
+If no explicit section ID is specified an ID will be synthesised from
+the section title. The primary purpose of this feature is to ensure
+persistence of table of contents links (permalinks): the missing
+section IDs are generated dynamically by the JavaScript TOC generator
+*after* the page is loaded. If you link to a dynamically generated TOC
+address the page will load but the browser will ignore the (as yet
+ungenerated) section ID.
+
+The IDs are generated by the following algorithm:
+
+- Replace all non-alphanumeric title characters with underscores.
+- Strip leading or trailing underscores.
+- Convert to lowercase.
+- Prepend the `idprefix` attribute (so there's no possibility of name
+ clashes with existing document IDs). Prepend an underscore if the
+ `idprefix` attribute is not defined.
+- A numbered suffix (`_2`, `_3` ...) is added if a same named
+ auto-generated section ID exists.
+- If the `ascii-ids` attribute is defined then non-ASCII characters
+ are replaced with ASCII equivalents. This attribute may be
+ deprecated in future releases and *should be avoided*, it's sole
+ purpose is to accommodate deficient downstream applications that
+ cannot process non-ASCII ID attributes.
+
+Example: the title 'Jim's House' would generate the ID `_jim_s_house`.
+
+Section ID synthesis can be disabled by undefining the `sectids`
+attribute.
+
+[[X16]]
+Special Section Titles
+^^^^^^^^^^^^^^^^^^^^^^
+AsciiDoc has a mechanism for mapping predefined section titles
+auto-magically to specific markup templates. For example a title
+'Appendix A: Code Reference' will automatically use the 'appendix'
+<<X93,section markup template>>. The mappings from title to template
+name are specified in `[specialsections]` sections in the Asciidoc
+language configuration files (`lang-*.conf`). Section entries are
+formatted like:
+
+ <title>=<template>
+
+`<title>` is a Python regular expression and `<template>` is the name
+of a configuration file markup template section. If the `<title>`
+matches an AsciiDoc document section title then the backend output is
+marked up using the `<template>` markup template (instead of the
+default `sect<level>` section template). The `{title}` attribute value
+is set to the value of the matched regular expression group named
+'title', if there is no 'title' group `{title}` defaults to the whole
+of the AsciiDoc section title. If `<template>` is blank then any
+existing entry with the same `<title>` will be deleted.
+
+.Special section titles vs. explicit template names
+*********************************************************************
+AsciiDoc has two mechanisms for specifying non-default section markup
+templates: you can specify the template name explicitly (using the
+'template' attribute) or indirectly (using 'special section titles').
+Specifying a <<X93,section template>> attribute explicitly is
+preferred. Auto-magical 'special section titles' have the following
+drawbacks:
+
+- They are non-obvious, you have to know the exact matching
+ title for each special section on a language by language basis.
+- Section titles are predefined and can only be customised with a
+ configuration change.
+- The implementation is complicated by multiple languages: every
+ special section title has to be defined for each language (in each
+ of the `lang-*.conf` files).
+
+Specifying special section template names explicitly does add more
+noise to the source document (the 'template' attribute declaration),
+but the intention is obvious and the syntax is consistent with other
+AsciiDoc elements c.f. bibliographic, Q&A and glossary lists.
+
+Special section titles have been deprecated but are retained for
+backward compatibility.
+
+*********************************************************************
+
+Inline Elements
+~~~~~~~~~~~~~~~
+<<X34,Inline document elements>> are used to format text and to
+perform 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 `&` characters).
+ See `[specialcharacters]` configuration file sections.
+
+Quotes::
+ Elements 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.
+
+Attribute references::
+ Document attribute names enclosed in braces are replaced by
+ the corresponding attribute value.
+
+Inline Macros::
+ Inline macros are replaced by the contents of parametrized
+ 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 its constituent elements
+ translated to the output file.
+3. The configuration file `[footer]` template 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): (section)
+Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys,
+AttributeLists, BlockTitles, Paragraphs.
+
+The default paragraph definition `[paradef-default]` is 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. Attributes
+6. Inline Macros
+7. Replacements2
+
+The substitutions and substitution order performed on
+Title, Paragraph and DelimitedBlock elements is determined by
+configuration file parameters.
+
+
+Text Formatting
+---------------
+[[X51]]
+Quoted Text
+~~~~~~~~~~~
+Words and phrases can be formatted by enclosing inline text with
+quote characters:
+
+_Emphasized text_::
+ Word phrases \'enclosed in single quote characters' (acute
+ accents) or \_underline characters_ are emphasized.
+
+*Strong text*::
+ Word phrases \*enclosed in asterisk characters* are rendered
+ in a strong font (usually bold).
+
+[[X81]]+Monospaced text+::
+ Word phrases \+enclosed in plus characters+ are rendered in a
+ monospaced font. Word phrases \`enclosed in backtick
+ characters` (grave accents) are also rendered in a monospaced
+ font but in this case the enclosed text is rendered literally
+ and is not subject to further expansion (see <<X80,inline
+ literal passthrough>>).
+
+`Single quoted text'::
+ Phrases enclosed with a \`single grave accent to the left and
+ a single acute accent to the right' are rendered in single
+ quotation marks.
+
+``Double quoted text''::
+ Phrases enclosed with \\``two grave accents to the left and
+ two acute accents to the right'' are rendered in quotation
+ marks.
+
+#Unquoted text#::
+ Placing \#hashes around text# does nothing, it is a mechanism
+ to allow inline attributes to be applied to otherwise
+ unformatted text.
+
+New quote types can be defined by editing asciidoc(1) configuration
+files. See the <<X7,Configuration Files>> section for details.
+
+.Quoted text behavior
+- 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). In the case
+ of ambiguity between escaped and non-escaped text you will need to
+ escape both leading and trailing quotes, in the case of
+ multi-character quotes you may even need to escape individual
+ characters.
+
+[[X96]]
+Quoted text attributes
+^^^^^^^^^^^^^^^^^^^^^^
+Quoted text can be prefixed with an <<X21,attribute list>>. The first
+positional attribute ('role' attribute) is translated by AsciiDoc to
+an HTML 'span' element 'class' attribute or a DocBook 'phrase' element
+'role' attribute.
+
+DocBook XSL Stylesheets translate DocBook 'phrase' elements with
+'role' attributes to corresponding HTML 'span' elements with the same
+'class' attributes; CSS can then be used
+http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
+generated HTML]. Thus CSS styling can be applied to both DocBook and
+AsciiDoc generated HTML outputs. You can also specify multiple class
+names separated by spaces.
+
+CSS rules for text color, text background color, text size and text
+decorators are included in the distributed AsciiDoc CSS files and are
+used in conjunction with AsciiDoc 'xhtml11', 'html5' and 'docbook'
+outputs. The CSS class names are:
+
+- '<color>' (text foreground color).
+- '<color>-background' (text background color).
+- 'big' and 'small' (text size).
+- 'underline', 'overline' and 'line-through' (strike through) text
+ decorators.
+
+Where '<color>' can be any of the
+http://en.wikipedia.org/wiki/Web_colors#HTML_color_names[sixteen HTML
+color names]. Examples:
+
+ [red]#Obvious# and [big red yellow-background]*very obvious*.
+
+ [underline]#Underline text#, [overline]#overline text# and
+ [blue line-through]*bold blue and line-through*.
+
+is rendered as:
+
+[red]#Obvious# and [big red yellow-background]*very obvious*.
+
+[underline]#Underline text#, [overline]#overline text# and
+[bold blue line-through]*bold blue and line-through*.
+
+NOTE: Color and text decorator attributes are rendered for XHTML and
+HTML 5 outputs using CSS stylesheets. The mechanism to implement
+color and text decorator attributes is provided for DocBook toolchains
+via the DocBook 'phrase' element 'role' attribute, but the actual
+rendering is toolchain specific and is not part of the AsciiDoc
+distribution.
+
+[[X52]]
+Constrained and Unconstrained Quotes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There are actually two types of quotes:
+
+Constrained quotes
+++++++++++++++++++
+Quoted must be bounded by white space or commonly adjoining
+punctuation characters. These are the most commonly used type of
+quote.
+
+Unconstrained quotes
+++++++++++++++++++++
+Unconstrained quotes have no boundary constraints and can be placed
+anywhere within inline text. For consistency and to make them easier
+to remember unconstrained quotes are double-ups of the `_`, `*`, `+`
+and `#` constrained quotes:
+
+ __unconstrained emphasized text__
+ **unconstrained strong text**
+ ++unconstrained monospaced text++
+ ##unconstrained unquoted text##
+
+The following example emboldens the letter F:
+
+ **F**ile Open...
+
+Superscripts and Subscripts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Put \^carets on either^ side of the text to be superscripted, put
+\~tildes on either side~ of text to be subscripted. For example, the
+following line:
+
+ e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
+ and ~some sub text~
+
+Is rendered like:
+
+e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
+and ~some sub text~
+
+Superscripts and subscripts are implemented as <<X52,unconstrained
+quotes>> and they can be escaped with a leading backslash and prefixed
+with with an attribute list.
+
+Line Breaks
+~~~~~~~~~~~
+A plus character preceded by at least one space character at the end
+of a non-blank line forces a line break. It generates a line break
+(`br`) tag for HTML outputs and a custom XML `asciidoc-br` processing
+instruction for DocBook outputs. The `asciidoc-br` processing
+instruction is handled by <<X43,a2x(1)>>.
+
+Page Breaks
+~~~~~~~~~~~
+A line of three or more less-than (`<<<`) characters will generate a
+hard page break in DocBook and printed HTML outputs. It uses the CSS
+`page-break-after` property for HTML outputs and a custom XML
+`asciidoc-pagebreak` processing instruction for DocBook outputs. The
+`asciidoc-pagebreak` processing instruction is handled by
+<<X43,a2x(1)>>. Hard page breaks are sometimes handy but as a general
+rule you should let your page processor generate page breaks for you.
+
+Rulers
+~~~~~~
+A line of three or more apostrophe characters will generate a ruler
+line. It generates a ruler (`hr`) tag for HTML outputs and a custom
+XML `asciidoc-hr` processing instruction for DocBook outputs. The
+`asciidoc-hr` processing instruction is handled by <<X43,a2x(1)>>.
+
+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 in included files by
+setting a 'tabsize' attribute in the `include` macro's attribute list.
+For example:
+
+ include::addendum.txt[tabsize=2]
+
+The tab size can also be set using the attribute command-line option,
+for example `--attribute tabsize=4`
+
+Replacements
+~~~~~~~~~~~~
+The following replacements are defined in the default AsciiDoc
+configuration:
+
+ (C) copyright, (TM) trademark, (R) registered trademark,
+ -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
+ double arrow, <= left double arrow.
+
+Which are rendered as:
+
+(C) copyright, (TM) trademark, (R) registered trademark,
+-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
+double arrow, <= left double arrow.
+
+You can also include arbitrary entity references in the AsciiDoc
+source. Examples:
+
+ ➊ ¶
+
+renders:
+
+➊ ¶
+
+To render a replacement literally escape it with a leading back-slash.
+
+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.
+
+
+[[X17]]
+Titles
+------
+Document and section titles can be in either of two formats:
+
+Two line titles
+~~~~~~~~~~~~~~~
+A two line title consists of a title line, starting hard against the
+left margin, and an underline. Section underlines consist a repeated
+character pairs spanning the width of the preceding title (give or
+take up to two 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
+ ~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[X46]]
+One line titles
+~~~~~~~~~~~~~~~
+One line titles consist of a single line delimited on either side by
+one or more equals characters (the number of equals characters
+corresponds to the section level minus one). Here are some examples:
+
+ = Document Title (level 0) =
+ == Section title (level 1) ==
+ === Section title (level 2) ===
+ ==== Section title (level 3) ====
+ ===== Section title (level 4) =====
+
+[NOTE]
+=====================================================================
+- One or more spaces must fall between the title and the delimiters.
+- The trailing title delimiter is optional.
+- The one-line title syntax can be changed by editing the
+ configuration file `[titles]` section `sect0`...`sect4` entries.
+=====================================================================
+
+Floating titles
+~~~~~~~~~~~~~~~
+Setting the title's first positional attribute or 'style' attribute to
+'float' generates a free-floating title. A free-floating title is
+rendered just like a normal section title but is not formally
+associated with a text body and is not part of the regular section
+hierarchy so the normal ordering rules do not apply. Floating titles
+can also be used in contexts where section titles are illegal: for
+example sidebar and admonition blocks. Example:
+
+ [float]
+ The second day
+ ~~~~~~~~~~~~~~
+
+Floating titles do not appear in a document's table of contents.
+
+
+[[X42]]
+Block Titles
+------------
+A 'BlockTitle' element is a single line beginning with a period
+followed by the title text. A BlockTitle is applied to the immediately
+following Paragraph, DelimitedBlock, List, Table or BlockMacro. For
+example:
+
+........................
+.Notes
+- Note 1.
+- Note 2.
+........................
+
+is rendered as:
+
+.Notes
+- Note 1.
+- Note 2.
+
+
+[[X41]]
+BlockId Element
+---------------
+A 'BlockId' is a single line block element containing a unique
+identifier enclosed in double square brackets. It is used to assign an
+identifier to the ensuing block element. For example:
+
+ [[chapter-titles]]
+ Chapter titles can be ...
+
+The preceding example identifies the ensuing paragraph so it can be
+referenced from other locations, for example with
+`<<chapter-titles,chapter titles>>`.
+
+'BlockId' elements can be applied to Title, Paragraph, List,
+DelimitedBlock, Table and BlockMacro elements. The BlockId element
+sets the `{id}` attribute for substitution in the subsequent block's
+markup template. If a second positional argument is supplied it sets
+the `{reftext}` attribute which is used to set the DocBook `xreflabel`
+attribute.
+
+The 'BlockId' element has the same syntax and serves the same function
+to the <<X30,anchor inline macro>>.
+
+[[X79]]
+AttributeList Element
+---------------------
+An 'AttributeList' block element is an <<X21,attribute list>> on a
+line by itself:
+
+- 'AttributeList' attributes are only applied to the immediately
+ following block element -- the attributes are made available to the
+ block's markup template.
+- Multiple contiguous 'AttributeList' elements are additively combined
+ in the order they appear..
+- The first positional attribute in the list is often used to specify
+ the ensuing element's <<X23,style>>.
+
+Attribute value substitution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+By default, only substitutions that take place inside attribute list
+values are attribute references, this is because not all attributes
+are destined to be marked up and rendered as text (for example the
+table 'cols' attribute). To perform normal inline text substitutions
+(special characters, quotes, macros, replacements) on an attribute
+value you need to enclose it in single quotes. In the following quote
+block the second attribute value in the AttributeList is quoted to
+ensure the 'http' macro is expanded to a hyperlink.
+
+---------------------------------------------------------------------
+[quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]']
+_____________________________________________________________________
+Sir, a woman's preaching is like a dog's walking on his hind legs. It
+is not done well; but you are surprised to find it done at all.
+_____________________________________________________________________
+---------------------------------------------------------------------
+
+Common attributes
+~~~~~~~~~~~~~~~~~
+Most block elements support the following attributes:
+
+[cols="1e,1,5a",frame="topbot",options="header"]
+|====================================================================
+|Name |Backends |Description
+
+|id |html4, html5, xhtml11, docbook |
+Unique identifier typically serve as link targets.
+Can also be set by the 'BlockId' element.
+
+|role |html4, html5, xhtml11, docbook |
+Role contains a string used to classify or subclassify an element and
+can be applied to AsciiDoc block elements. The AsciiDoc 'role'
+attribute is translated to the 'role' attribute in DocBook outputs and
+is included in the 'class' attribute in HTML outputs, in this respect
+it behaves like the <<X96,quoted text role attribute>>.
+
+DocBook XSL Stylesheets translate DocBook 'role' attributes to HTML
+'class' attributes; CSS can then be used
+http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
+generated HTML].
+
+|reftext |docbook |
+'reftext' is used to set the DocBook 'xreflabel' attribute.
+The 'reftext' attribute can an also be set by the 'BlockId' element.
+
+|====================================================================
+
+
+Paragraphs
+----------
+Paragraphs are blocks of text terminated by a blank line, the end of
+file, or the start of a delimited block or a list. There are three
+paragraph syntaxes: normal, indented (literal) and admonition which
+are rendered, by default, with the corresponding paragraph style.
+
+Each syntax has a default style, but you can explicitly apply any
+paragraph style to any paragraph syntax. You can also apply
+<<X104,delimited block>> styles to single paragraphs.
+
+The built-in paragraph styles are: 'normal', 'literal', 'verse',
+'quote', 'listing', 'TIP', 'NOTE', 'IMPORTANT', 'WARNING', 'CAUTION',
+'abstract', 'partintro', 'comment', 'example', 'sidebar', 'source',
+'music', 'latex', 'graphviz'.
+
+normal paragraph syntax
+~~~~~~~~~~~~~~~~~~~~~~~
+Normal paragraph syntax 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 default processing expectation is that
+of a normal paragraph of text.
+
+[[X85]]
+literal paragraph syntax
+~~~~~~~~~~~~~~~~~~~~~~~~
+Literal paragraphs are rendered verbatim in a monospaced font without
+any distinguishing background or border. By default there is no text
+formatting or substitutions within Literal paragraphs apart from
+Special Characters and Callouts.
+
+The 'literal' style is applied implicitly to indented paragraphs i.e.
+where the first line of the paragraph is indented by one or more space
+or tab characters. For example:
+
+---------------------------------------------------------------------
+ Consul *necessitatibus* per id,
+ consetetur, eu pro everti postulant
+ homero verear ea mea, qui.
+---------------------------------------------------------------------
+
+Renders:
+
+ Consul *necessitatibus* per id,
+ consetetur, eu pro everti postulant
+ homero verear ea mea, qui.
+
+NOTE: Because <<X64,lists>> can be indented it's possible for your
+indented paragraph to be misinterpreted as a list -- in situations
+like this apply the 'literal' style to a normal paragraph.
+
+Instead of using a paragraph indent you could apply the 'literal'
+style explicitly, for example:
+
+---------------------------------------------------------------------
+[literal]
+Consul *necessitatibus* per id,
+consetetur, eu pro everti postulant
+homero verear ea mea, qui.
+---------------------------------------------------------------------
+
+Renders:
+
+[literal]
+Consul *necessitatibus* per id,
+consetetur, eu pro everti postulant
+homero verear ea mea, qui.
+
+[[X94]]
+quote and verse paragraph styles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The optional 'attribution' and 'citetitle' attributes (positional
+attributes 2 and 3) specify the author and source respectively.
+
+The 'verse' style retains the line breaks, for example:
+
+---------------------------------------------------------------------
+[verse, William Blake, from Auguries of Innocence]
+To see a world in a grain of sand,
+And a heaven in a wild flower,
+Hold infinity in the palm of your hand,
+And eternity in an hour.
+---------------------------------------------------------------------
+
+Which is rendered as:
+
+[verse, William Blake, from Auguries of Innocence]
+To see a world in a grain of sand,
+And a heaven in a wild flower,
+Hold infinity in the palm of your hand,
+And eternity in an hour.
+
+The 'quote' style flows the text at left and right margins, for
+example:
+
+---------------------------------------------------------------------
+[quote, 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:
+
+[quote, 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.
+
+[[X28]]
+Admonition Paragraphs
+~~~~~~~~~~~~~~~~~~~~~
+'TIP', 'NOTE', 'IMPORTANT', 'WARNING' and 'CAUTION' admonishment
+paragraph styles are generated by placing `NOTE:`, `TIP:`,
+`IMPORTANT:`, `WARNING:` or `CAUTION:` as the first word of the
+paragraph. For example:
+
+ NOTE: This is an example note.
+
+Alternatively, you can specify the paragraph admonition style
+explicitly using an <<X79,AttributeList element>>. For example:
+
+ [NOTE]
+ This is an example note.
+
+Renders:
+
+NOTE: This is an example note.
+
+TIP: If your admonition requires more than a single paragraph use an
+<<X22,admonition block>> instead.
+
+[[X47]]
+Admonition Icons and Captions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+NOTE: Admonition customization with `icons`, `iconsdir`, `icon` and
+`caption` attributes does not apply when generating DocBook output. If
+you are going the DocBook route then the <<X43,a2x(1)>> `--no-icons`
+and `--icons-dir` options can be used to set the appropriate XSL
+Stylesheets parameters.
+
+By default the asciidoc(1) HTML backends generate text captions
+instead of admonition icon image links. To generate links to icon
+images define the <<X45,`icons`>> attribute, for example using the `-a
+icons` command-line option.
+
+The <<X44,`iconsdir`>> attribute sets the location of linked icon
+images.
+
+You can override the default icon image using the `icon` attribute to
+specify the path of the linked image. For example:
+
+ [icon="./images/icons/wink.png"]
+ NOTE: What lovely war.
+
+Use the `caption` attribute to customize the admonition captions (not
+applicable to `docbook` backend). The following example suppresses the
+icon image and customizes the caption of a 'NOTE' admonition
+(undefining the `icons` attribute with `icons=None` is only necessary
+if <<X45,admonition icons>> have been enabled):
+
+ [icons=None, caption="My Special Note"]
+ NOTE: This is my special note.
+
+This subsection also applies to <<X22,Admonition Blocks>>.
+
+
+[[X104]]
+Delimited Blocks
+----------------
+Delimited blocks are blocks of text enveloped by leading and trailing
+delimiter lines (normally a series of four or more repeated
+characters). The behavior of Delimited Blocks is specified by entries
+in configuration file `[blockdef-*]` sections.
+
+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: //////////////////////////
+ PassthroughBlock: ++++++++++++++++++++++++++
+ ListingBlock: --------------------------
+ LiteralBlock: ..........................
+ SidebarBlock: **************************
+ QuoteBlock: __________________________
+ ExampleBlock: ==========================
+ OpenBlock: --
+
+.Default DelimitedBlock substitutions
+[cols="2e,7*^",frame="topbot",options="header,autowidth"]
+|=====================================================
+| |Attributes |Callouts |Macros | Quotes |Replacements
+|Special chars |Special words
+
+|PassthroughBlock |Yes |No |Yes |No |No |No |No
+|ListingBlock |No |Yes |No |No |No |Yes |No
+|LiteralBlock |No |Yes |No |No |No |Yes |No
+|SidebarBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
+|QuoteBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
+|ExampleBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
+|OpenBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
+|=====================================================
+
+Listing Blocks
+~~~~~~~~~~~~~~
+'ListingBlocks' are rendered verbatim in a monospaced font, they
+retain line and whitespace formatting and are often distinguished by a
+background or border. There is no text formatting or substitutions
+within Listing blocks apart from Special Characters and Callouts.
+Listing blocks are often used for computer output and file listings.
+
+Here's an example:
+
+[listing]
+......................................
+--------------------------------------
+#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);
+}
+--------------------------------------
+
+By convention <<X59,filter blocks>> use the listing block syntax and
+are implemented as distinct listing block styles.
+
+[[X65]]
+Literal Blocks
+~~~~~~~~~~~~~~
+'LiteralBlocks' are rendered just like <<X85,literal paragraphs>>.
+Example:
+
+---------------------------------------------------------------------
+...................................
+Consul *necessitatibus* per id,
+consetetur, eu pro everti postulant
+homero verear ea mea, qui.
+...................................
+---------------------------------------------------------------------
+
+Renders:
+...................................
+Consul *necessitatibus* per id,
+consetetur, eu pro everti postulant
+homero verear ea mea, qui.
+...................................
+
+If the 'listing' style is applied to a LiteralBlock it will be
+rendered as a ListingBlock (this is handy if you have a listing
+containing a ListingBlock).
+
+Sidebar Blocks
+~~~~~~~~~~~~~~
+A sidebar is a short piece of text presented outside the narrative
+flow of the main text. The sidebar is normally presented inside a
+bordered box to set it apart from the main text.
+
+The sidebar body is treated like a normal section body.
+
+Here's an example:
+
+---------------------------------------------------------------------
+.An Example Sidebar
+************************************************
+Any AsciiDoc SectionBody element (apart from
+SidebarBlocks) can be placed inside a sidebar.
+************************************************
+---------------------------------------------------------------------
+
+Which will be rendered like:
+
+.An Example Sidebar
+************************************************
+Any AsciiDoc SectionBody element (apart from
+SidebarBlocks) can be placed inside a sidebar.
+************************************************
+
+[[X26]]
+Comment Blocks
+~~~~~~~~~~~~~~
+The contents of 'CommentBlocks' are not processed; they are useful for
+annotations and for excluding new or outdated content that you don't
+want displayed. CommentBlocks are never written to output files.
+Example:
+
+---------------------------------------------------------------------
+//////////////////////////////////////////
+CommentBlock contents are not processed by
+asciidoc(1).
+//////////////////////////////////////////
+---------------------------------------------------------------------
+
+See also <<X25,Comment Lines>>.
+
+NOTE: System macros are executed inside comment blocks.
+
+[[X76]]
+Passthrough Blocks
+~~~~~~~~~~~~~~~~~~
+By default the block contents is subject only to 'attributes' and
+'macros' substitutions (use an explicit 'subs' attribute to apply
+different substitutions). PassthroughBlock content will often be
+backend specific. Here's an example:
+
+---------------------------------------------------------------------
+[subs="quotes"]
+++++++++++++++++++++++++++++++++++++++
+<table border="1"><tr>
+ <td>*Cell 1*</td>
+ <td>*Cell 2*</td>
+</tr></table>
+++++++++++++++++++++++++++++++++++++++
+---------------------------------------------------------------------
+
+The following styles can be applied to passthrough blocks:
+
+pass::
+ No substitutions are performed. This is equivalent to `subs="none"`.
+
+asciimath, latexmath::
+ By default no substitutions are performed, the contents are rendered
+ as <<X78,mathematical formulas>>.
+
+Quote Blocks
+~~~~~~~~~~~~
+'QuoteBlocks' are used for quoted passages of text. There are two
+styles: 'quote' and 'verse'. The style behavior is identical to
+<<X94,quote and verse paragraphs>> except that blocks can contain
+multiple paragraphs and, in the case of the 'quote' style, other
+section elements. The first positional attribute sets the style, if
+no attributes are specified the 'quote' style is used. The optional
+'attribution' and 'citetitle' attributes (positional attributes 2 and
+3) specify the quote's author and source. For example:
+
+---------------------------------------------------------------------
+[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]
+____________________________________________________________________
+As he spoke there was the sharp sound of horses' hoofs and
+grating wheels against the curb, followed by a sharp pull at the
+bell. Holmes whistled.
+
+"A pair, by the sound," said he. "Yes," he continued, glancing
+out of the window. "A nice little brougham and a pair of
+beauties. A hundred and fifty guineas apiece. There's money in
+this case, Watson, if there is nothing else."
+____________________________________________________________________
+---------------------------------------------------------------------
+
+Which is rendered as:
+
+[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]
+____________________________________________________________________
+As he spoke there was the sharp sound of horses' hoofs and
+grating wheels against the curb, followed by a sharp pull at the
+bell. Holmes whistled.
+
+"A pair, by the sound," said he. "Yes," he continued, glancing
+out of the window. "A nice little brougham and a pair of
+beauties. A hundred and fifty guineas apiece. There's money in
+this case, Watson, if there is nothing else."
+____________________________________________________________________
+
+[[X48]]
+Example Blocks
+~~~~~~~~~~~~~~
+'ExampleBlocks' encapsulate the DocBook Example element and are used
+for, well, examples. Example blocks can be titled by preceding them
+with a 'BlockTitle'. DocBook toolchains will normally automatically
+number examples and generate a 'List of Examples' backmatter section.
+
+Example blocks are delimited by lines of equals characters and can
+contain any block elements apart from Titles, BlockTitles and
+Sidebars) inside an example block. For example:
+
+---------------------------------------------------------------------
+.An example
+=====================================================================
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+adolescens.
+=====================================================================
+---------------------------------------------------------------------
+
+Renders:
+
+.An example
+=====================================================================
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+adolescens.
+=====================================================================
+
+A title prefix that can be inserted with the `caption` attribute
+(HTML backends). For example:
+
+---------------------------------------------------------------------
+[caption="Example 1: "]
+.An example with a custom caption
+=====================================================================
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+adolescens.
+=====================================================================
+---------------------------------------------------------------------
+
+[[X22]]
+Admonition Blocks
+~~~~~~~~~~~~~~~~~
+The 'ExampleBlock' definition includes a set of admonition
+<<X23,styles>> ('NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION') for
+generating admonition blocks (admonitions containing more than a
+<<X28,single paragraph>>). Just precede the 'ExampleBlock' with an
+attribute list specifying the admonition style name. For example:
+
+---------------------------------------------------------------------
+[NOTE]
+.A NOTE admonition block
+=====================================================================
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+adolescens.
+
+. Fusce euismod commodo velit.
+. Vivamus fringilla mi eu lacus.
+ .. Fusce euismod commodo velit.
+ .. Vivamus fringilla mi eu lacus.
+. Donec eget arcu bibendum
+ nunc consequat lobortis.
+=====================================================================
+---------------------------------------------------------------------
+
+Renders:
+
+[NOTE]
+.A NOTE admonition block
+=====================================================================
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+adolescens.
+
+. Fusce euismod commodo velit.
+. Vivamus fringilla mi eu lacus.
+ .. Fusce euismod commodo velit.
+ .. Vivamus fringilla mi eu lacus.
+. Donec eget arcu bibendum
+ nunc consequat lobortis.
+=====================================================================
+
+See also <<X47,Admonition Icons and Captions>>.
+
+[[X29]]
+Open Blocks
+~~~~~~~~~~~
+Open blocks are special:
+
+- The open block delimiter is line containing two hyphen characters
+ (instead of four or more repeated characters).
+
+- They can be used to group block elements for <<X15,List item
+ continuation>>.
+
+- Open blocks can be styled to behave like any other type of delimited
+ block. The following built-in styles can be applied to open
+ blocks: 'literal', 'verse', 'quote', 'listing', 'TIP', 'NOTE',
+ 'IMPORTANT', 'WARNING', 'CAUTION', 'abstract', 'partintro',
+ 'comment', 'example', 'sidebar', 'source', 'music', 'latex',
+ 'graphviz'. For example, the following open block and listing block
+ are functionally identical:
+
+ [listing]
+ --
+ Lorum ipsum ...
+ --
+
+ ---------------
+ Lorum ipsum ...
+ ---------------
+
+- An unstyled open block groups section elements but otherwise does
+ nothing.
+
+Open blocks are used to generate document abstracts and book part
+introductions:
+
+- Apply the 'abstract' style to generate an abstract, for example:
+
+ [abstract]
+ --
+ In this paper we will ...
+ --
+
+. Apply the 'partintro' style to generate a book part introduction for
+ a multi-part book, for example:
+
+ [partintro]
+ .Optional part introduction title
+ --
+ Optional part introduction goes here.
+ --
+
+
+[[X64]]
+Lists
+-----
+.List types
+- Bulleted lists. Also known as itemized or unordered lists.
+- Numbered lists. Also called ordered lists.
+- Labeled lists. Sometimes called variable or definition lists.
+- Callout lists (a list of callout annotations).
+
+.List behavior
+- List item indentation is optional and does not determine nesting,
+ indentation does however make the source more readable.
+- Another list or a literal paragraph immediately following a list
+ item will be implicitly included in the list item; use <<X15, list
+ item continuation>> to explicitly append other block elements to a
+ list item.
+- A comment block or a comment line block macro element will terminate
+ a list -- use inline comment lines to put comments inside lists.
+- The `listindex` <<X60,intrinsic attribute>> is the current list item
+ index (1..). If this attribute is used outside a list then it's value
+ is the number of items in the most recently closed list. Useful for
+ displaying the number of items in a list.
+
+Bulleted Lists
+~~~~~~~~~~~~~~
+Bulleted list items start with a single dash or one to five asterisks
+followed by some white space then some text. Bulleted list syntaxes
+are:
+
+...................
+- List item.
+* List item.
+** List item.
+*** List item.
+**** List item.
+***** List item.
+...................
+
+Numbered Lists
+~~~~~~~~~~~~~~
+List item numbers are explicit or implicit.
+
+.Explicit numbering
+List items begin with a number followed by some white space then the
+item text. The numbers can be decimal (arabic), roman (upper or lower
+case) or alpha (upper or lower case). Decimal and alpha numbers are
+terminated with a period, roman numbers are terminated with a closing
+parenthesis. The different terminators are necessary to ensure 'i',
+'v' and 'x' roman numbers are are distinguishable from 'x', 'v' and
+'x' alpha numbers. Examples:
+
+.....................................................................
+1. Arabic (decimal) numbered list item.
+a. Lower case alpha (letter) numbered list item.
+F. Upper case alpha (letter) numbered list item.
+iii) Lower case roman numbered list item.
+IX) Upper case roman numbered list item.
+.....................................................................
+
+.Implicit numbering
+List items begin one to five period characters, followed by some white
+space then the item text. Examples:
+
+.....................................................................
+. Arabic (decimal) numbered list item.
+.. Lower case alpha (letter) numbered list item.
+... Lower case roman numbered list item.
+.... Upper case alpha (letter) numbered list item.
+..... Upper case roman numbered list item.
+.....................................................................
+
+You can use the 'style' attribute (also the first positional
+attribute) to specify an alternative numbering style. The numbered
+list style can be one of the following values: 'arabic', 'loweralpha',
+'upperalpha', 'lowerroman', 'upperroman'.
+
+Here are some examples of bulleted and numbered lists:
+
+---------------------------------------------------------------------
+- Praesent eget purus quis magna eleifend eleifend.
+ 1. Fusce euismod commodo velit.
+ a. Fusce euismod commodo velit.
+ b. Vivamus fringilla mi eu lacus.
+ c. Donec eget arcu bibendum nunc consequat lobortis.
+ 2. Vivamus fringilla mi eu lacus.
+ i) Fusce euismod commodo velit.
+ ii) Vivamus fringilla mi eu lacus.
+ 3. Donec eget arcu bibendum nunc consequat lobortis.
+ 4. Nam fermentum mattis ante.
+- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+ * Fusce euismod commodo velit.
+ ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+ adolescens. Sit munere ponderum dignissim et. Minim luptatum et
+ vel.
+ ** Vivamus fringilla mi eu lacus.
+ * Donec eget arcu bibendum nunc consequat lobortis.
+- Nulla porttitor vulputate libero.
+ . Fusce euismod commodo velit.
+ . Vivamus fringilla mi eu lacus.
+[upperroman]
+ .. Fusce euismod commodo velit.
+ .. Vivamus fringilla mi eu lacus.
+ . Donec eget arcu bibendum nunc consequat lobortis.
+---------------------------------------------------------------------
+
+Which render as:
+
+- Praesent eget purus quis magna eleifend eleifend.
+ 1. Fusce euismod commodo velit.
+ a. Fusce euismod commodo velit.
+ b. Vivamus fringilla mi eu lacus.
+ c. Donec eget arcu bibendum nunc consequat lobortis.
+ 2. Vivamus fringilla mi eu lacus.
+ i) Fusce euismod commodo velit.
+ ii) Vivamus fringilla mi eu lacus.
+ 3. Donec eget arcu bibendum nunc consequat lobortis.
+ 4. Nam fermentum mattis ante.
+- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+ * Fusce euismod commodo velit.
+ ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+ adolescens. Sit munere ponderum dignissim et. Minim luptatum et
+ vel.
+ ** Vivamus fringilla mi eu lacus.
+ * Donec eget arcu bibendum nunc consequat lobortis.
+- Nulla porttitor vulputate libero.
+ . Fusce euismod commodo velit.
+ . Vivamus fringilla mi eu lacus.
+[upperroman]
+ .. Fusce euismod commodo velit.
+ .. Vivamus fringilla mi eu lacus.
+ . Donec eget arcu bibendum nunc consequat lobortis.
+
+A predefined 'compact' option is available to bulleted and numbered
+lists -- this translates to the DocBook 'spacing="compact"' lists
+attribute which may or may not be processed by the DocBook toolchain.
+Example:
+
+ [options="compact"]
+ - Compact list item.
+ - Another compact list item.
+
+TIP: To apply the 'compact' option globally define a document-wide
+'compact-option' attribute, e.g. using the `-a compact-option`
+command-line option.
+
+You can set the list start number using the 'start' attribute (works
+for HTML outputs and DocBook outputs processed by DocBook XSL
+Stylesheets). Example:
+
+ [start=7]
+ . List item 7.
+ . List item 8.
+
+Labeled Lists
+~~~~~~~~~~~~~
+Labeled list items consist of one or more text labels followed by the
+text of the list item.
+
+An item label begins a line with an alphanumeric character hard
+against the left margin and ends with two, three or four colons or two
+semi-colons. A list item can have multiple labels, one per line.
+
+The list item text consists of one or more lines of text starting
+after the last label (either on the same line or a new line) and can
+be followed by nested List or ListParagraph elements. Item text can be
+optionally indented.
+
+Here are some examples:
+
+---------------------------------------------------------------------
+In::
+Lorem::
+ Fusce euismod commodo velit.
+
+ Fusce euismod commodo velit.
+
+Ipsum:: Vivamus fringilla mi eu lacus.
+ * Vivamus fringilla mi eu lacus.
+ * Donec eget arcu bibendum nunc consequat lobortis.
+Dolor::
+ Donec eget arcu bibendum nunc consequat lobortis.
+ Suspendisse;;
+ A massa id sem aliquam auctor.
+ Morbi;;
+ Pretium nulla vel lorem.
+ In;;
+ Dictum mauris in urna.
+ Vivamus::: Fringilla mi eu lacus.
+ Donec::: Eget arcu bibendum nunc consequat lobortis.
+---------------------------------------------------------------------
+
+Which render as:
+
+In::
+Lorem::
+ Fusce euismod commodo velit.
+
+ Fusce euismod commodo velit.
+
+Ipsum:: Vivamus fringilla mi eu lacus.
+ * Vivamus fringilla mi eu lacus.
+ * Donec eget arcu bibendum nunc consequat lobortis.
+Dolor::
+ Donec eget arcu bibendum nunc consequat lobortis.
+ Suspendisse;;
+ A massa id sem aliquam auctor.
+ Morbi;;
+ Pretium nulla vel lorem.
+ In;;
+ Dictum mauris in urna.
+ Vivamus::: Fringilla mi eu lacus.
+ Donec::: Eget arcu bibendum nunc consequat lobortis.
+
+Horizontal labeled list style
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The 'horizontal' labeled list style (also the first positional
+attribute) places the list text side-by-side with the label instead of
+under the label. Here is an example:
+
+---------------------------------------------------------------------
+[horizontal]
+*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
+labitur dolorum an. Est ne magna primis adolescens.
+
+ Fusce euismod commodo velit.
+
+*Ipsum*:: Vivamus fringilla mi eu lacus.
+- Vivamus fringilla mi eu lacus.
+- Donec eget arcu bibendum nunc consequat lobortis.
+
+*Dolor*::
+ - Vivamus fringilla mi eu lacus.
+ - Donec eget arcu bibendum nunc consequat lobortis.
+
+---------------------------------------------------------------------
+
+Which render as:
+
+[horizontal]
+*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
+labitur dolorum an. Est ne magna primis adolescens.
+
+ Fusce euismod commodo velit.
+
+*Ipsum*:: Vivamus fringilla mi eu lacus.
+- Vivamus fringilla mi eu lacus.
+- Donec eget arcu bibendum nunc consequat lobortis.
+
+*Dolor*::
+ - Vivamus fringilla mi eu lacus.
+ - Donec eget arcu bibendum nunc consequat lobortis.
+
+[NOTE]
+=====================================================================
+- Current PDF toolchains do not make a good job of determining
+ the relative column widths for horizontal labeled lists.
+- Nested horizontal labeled lists will generate DocBook validation
+ errors because the 'DocBook XML V4.2' DTD does not permit nested
+ informal tables (although <<X13,DocBook XSL Stylesheets>> and
+ <<X31,dblatex>> process them correctly).
+- The label width can be set as a percentage of the total width by
+ setting the 'width' attribute e.g. `width="10%"`
+=====================================================================
+
+Question and Answer Lists
+~~~~~~~~~~~~~~~~~~~~~~~~~
+AsciiDoc comes pre-configured with a 'qanda' style labeled list for generating
+DocBook question and answer (Q&A) lists. Example:
+
+---------------------------------------------------------------------
+[qanda]
+Question one::
+ Answer one.
+Question two::
+ Answer two.
+---------------------------------------------------------------------
+
+Renders:
+
+[qanda]
+Question one::
+ Answer one.
+Question two::
+ Answer two.
+
+Glossary Lists
+~~~~~~~~~~~~~~
+AsciiDoc comes pre-configured with a 'glossary' style labeled list for
+generating DocBook glossary lists. Example:
+
+---------------------------------------------------------------------
+[glossary]
+A glossary term::
+ The corresponding definition.
+A second glossary term::
+ The corresponding definition.
+---------------------------------------------------------------------
+
+For working examples see the `article.txt` and `book.txt` documents in
+the AsciiDoc `./doc` distribution directory.
+
+NOTE: To generate valid DocBook output glossary lists must be located
+in a section that uses the 'glossary' <<X93,section markup template>>.
+
+Bibliography Lists
+~~~~~~~~~~~~~~~~~~
+AsciiDoc comes with a predefined 'bibliography' bulleted list style
+generating DocBook bibliography entries. Example:
+
+---------------------------------------------------------------------
+[bibliography]
+.Optional list title
+- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
+ Programming'. Addison-Wesley. ISBN 0-13-142901-9.
+- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
+ 'DocBook - The Definitive Guide'. O'Reilly & Associates.
+ 1999. ISBN 1-56592-580-7.
+---------------------------------------------------------------------
+
+The `[[[<reference>]]]` syntax is a bibliography entry anchor, it
+generates an anchor named `<reference>` and additionally displays
+`[<reference>]` at the anchor position. For example `[[[taoup]]]`
+generates an anchor named `taoup` that displays `[taoup]` at the
+anchor position. Cite the reference from elsewhere your document using
+`<<taoup>>`, this displays a hyperlink (`[taoup]`) to the
+corresponding bibliography entry anchor.
+
+For working examples see the `article.txt` and `book.txt` documents in
+the AsciiDoc `./doc` distribution directory.
+
+NOTE: To generate valid DocBook output bibliography lists must be
+located in a <<X93,bibliography section>>.
+
+[[X15]]
+List Item Continuation
+~~~~~~~~~~~~~~~~~~~~~~
+Another list or a literal paragraph immediately following a list item
+is implicitly appended to the list item; to append other block
+elements to a list item you need to explicitly join them to the list
+item with a 'list continuation' (a separator line containing a single
+plus character). Multiple block elements can be appended to a list
+item using list continuations (provided they are legal list item
+children in the backend markup).
+
+Here are some examples of list item continuations: list item one
+contains multiple continuations; list item two is continued with an
+<<X29,OpenBlock>> containing multiple elements:
+
+---------------------------------------------------------------------
+1. List item one.
++
+List item one continued with a second paragraph followed by an
+Indented block.
++
+.................
+$ ls *.sh
+$ mv *.sh ~/tmp
+.................
++
+List item continued with a third paragraph.
+
+2. List item two continued with an open block.
++
+--
+This paragraph is part of the preceding list item.
+
+a. This list is nested and does not require explicit item continuation.
++
+This paragraph is part of the preceding list item.
+
+b. List item b.
+
+This paragraph belongs to item two of the outer list.
+--
+---------------------------------------------------------------------
+
+Renders:
+
+1. List item one.
++
+List item one continued with a second paragraph followed by an
+Indented block.
++
+.................
+$ ls *.sh
+$ mv *.sh ~/tmp
+.................
++
+List item continued with a third paragraph.
+
+2. List item two continued with an open block.
++
+--
+This paragraph is part of the preceding list item.
+
+a. This list is nested and does not require explicit item continuation.
++
+This paragraph is part of the preceding list item.
+
+b. List item b.
+
+This paragraph belongs to item two of the outer list.
+--
+
+
+[[X92]]
+Footnotes
+---------
+The shipped AsciiDoc configuration includes three footnote inline
+macros:
+
+`footnote:[<text>]`::
+ Generates a footnote with text `<text>`.
+
+`footnoteref:[<id>,<text>]`::
+ Generates a footnote with a reference ID `<id>` and text `<text>`.
+
+`footnoteref:[<id>]`::
+ Generates a reference to the footnote with ID `<id>`.
+
+The footnote text can span multiple lines.
+
+The 'xhtml11' and 'html5' backends render footnotes dynamically using
+JavaScript; 'html4' outputs do not use JavaScript and leave the
+footnotes inline; 'docbook' footnotes are processed by the downstream
+DocBook toolchain.
+
+Example footnotes:
+
+ A footnote footnote:[An example footnote.];
+ a second footnote with a reference ID footnoteref:[note2,Second footnote.];
+ finally a reference to the second footnote footnoteref:[note2].
+
+Renders:
+
+A footnote footnote:[An example footnote.];
+a second footnote with a reference ID footnoteref:[note2,Second footnote.];
+finally a reference to the second footnote footnoteref:[note2].
+
+
+Indexes
+-------
+The shipped AsciiDoc configuration includes the inline macros for
+generating DocBook index entries.
+
+`indexterm:[<primary>,<secondary>,<tertiary>]`::
+`(((<primary>,<secondary>,<tertiary>)))`::
+ This inline macro generates an index term (the `<secondary>` and
+ `<tertiary>` positional attributes are optional). Example:
+ `indexterm:[Tigers,Big cats]` (or, using the alternative syntax
+ `(((Tigers,Big cats)))`. Index terms that have secondary and
+ tertiary entries also generate separate index terms for the
+ secondary and tertiary entries. The index terms appear in the
+ index, not the primary text flow.
+
+`indexterm2:[<primary>]`::
+`((<primary>))`::
+ This inline macro generates an index term that appears in both the
+ index and the primary text flow. The `<primary>` should not be
+ padded to the left or right with white space characters.
+
+For working examples see the `article.txt` and `book.txt` documents in
+the AsciiDoc `./doc` distribution directory.
+
+NOTE: Index entries only really make sense if you are generating
+DocBook markup -- DocBook conversion programs automatically generate
+an index at the point an 'Index' section appears in source document.
+
+
+[[X105]]
+Callouts
+--------
+Callouts are a mechanism for annotating verbatim text (for example:
+source code, computer output and user input). Callout markers are
+placed inside the annotated text while the actual annotations are
+presented in a callout list after the annotated text. Here's an
+example:
+
+---------------------------------------------------------------------
+ .MS-DOS directory listing
+ -----------------------------------------------------
+ 10/17/97 9:04 <DIR> bin
+ 10/16/97 14:11 <DIR> DOS \<1>
+ 10/16/97 14:40 <DIR> Program Files
+ 10/16/97 14:46 <DIR> TEMP
+ 10/17/97 9:04 <DIR> tmp
+ 10/16/97 14:37 <DIR> WINNT
+ 10/16/97 14:25 119 AUTOEXEC.BAT \<2>
+ 2/13/94 6:21 54,619 COMMAND.COM \<2>
+ 10/16/97 14:25 115 CONFIG.SYS \<2>
+ 11/16/97 17:17 61,865,984 pagefile.sys
+ 2/13/94 6:21 9,349 WINA20.386 \<3>
+ -----------------------------------------------------
+
+ \<1> This directory holds MS-DOS.
+ \<2> System startup code for DOS.
+ \<3> Some sort of Windows 3.1 hack.
+---------------------------------------------------------------------
+
+Which renders:
+
+.MS-DOS directory listing
+-----------------------------------------------------
+10/17/97 9:04 <DIR> bin
+10/16/97 14:11 <DIR> DOS <1>
+10/16/97 14:40 <DIR> Program Files
+10/16/97 14:46 <DIR> TEMP
+10/17/97 9:04 <DIR> tmp
+10/16/97 14:37 <DIR> WINNT
+10/16/97 14:25 119 AUTOEXEC.BAT <2>
+ 2/13/94 6:21 54,619 COMMAND.COM <2>
+10/16/97 14:25 115 CONFIG.SYS <2>
+11/16/97 17:17 61,865,984 pagefile.sys
+ 2/13/94 6:21 9,349 WINA20.386 <3>
+-----------------------------------------------------
+
+<1> This
<TRUNCATED>