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:10 UTC
[42/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/kitchen-sink/docs/AsciiDoc.asciidoc
----------------------------------------------------------------------
diff --git a/webapp/app/components/ace-builds/kitchen-sink/docs/AsciiDoc.asciidoc b/webapp/app/components/ace-builds/kitchen-sink/docs/AsciiDoc.asciidoc
deleted file mode 100644
index 90b3418..0000000
--- a/webapp/app/components/ace-builds/kitchen-sink/docs/AsciiDoc.asciidoc
+++ /dev/null
@@ -1,6040 +0,0 @@
-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 directory holds
<TRUNCATED>