FooBarWidget-mizuho 0.9.1 → 0.9.2

data/asciidoc/doc/asciidoc.txt

@@ -221,13 +221,19 @@ linkcss::
   which case stylesheets and scripts are automatically embedded in the
   output document.
 
+scriptsdir::
+  The name of the directory containing linked JavaScripts. Defaults to
+  `.` (the same directory as the linking document).
+
 stylesdir::
   The name of the directory containing linked stylesheets. Defaults to
   `.` (the same directory as the linking document).
 
-scriptsdir::
-  The name of the directory containing linked JavaScripts. Defaults to
-  `.` (the same directory as the linking document).
+stylesheet::
+  The file name of an optional additional CSS stylesheet. If you are
+  embedding the stylesheet specify the actual file name; if you are
+  linking CSS specify the file name relative to the directory
+  specified by the 'stylesdir' attribute.
 
 [[X45]]
 icons::
@@ -305,45 +311,20 @@ Default 'xhtml11' stylesheets:
     Stylesheet modifications to work around IE6 browser
     incompatibilities.
 
-Use the 'theme' attribute to select and alternative set of
-stylesheets. For example, the command-line option `-a theme=foo` will
-use stylesheets `foo.css`, `foo-manpage.css` and `foo-quirks.css`.
+Use the 'theme' attribute to select an alternative set of stylesheets.
+For example, the command-line option `-a theme=foo` will use
+stylesheets `foo.css`, `foo-manpage.css` and `foo-quirks.css` instead
+of the default stylesheets.
 
+Use the 'stylesheet' attribute to include an additional stylesheet in
+XHTML documents.  For example, the command-line option `-a
+stylesheet=newsletter.css` will use stylesheets `newsletter.css`.
 
 html4
 ~~~~~
 This backend generates plain (unstyled) HTML 4.01 Transitional markup.
 
 
-linuxdoc
-~~~~~~~~
-WARNING: The AsciiDoc linuxdoc backend is still distributed but is no
-longer being actively developed or tested with new AsciiDoc releases
-(the last supported release was AsciiDoc 6.0.3).
-
-- Tables are not supported.
-- Images are not supported.
-- Callouts are not supported.
-- Horizontal labeled lists are not supported.
-- Only article document types are allowed.
-- The Abstract section can consist only of a single paragraph.
-- An AsciiDoc Preamble is not allowed.
-- The LinuxDoc output format does not support multiple labels per
-  labeled list item although LinuxDoc conversion programs generally
-  output all the labels with a warning.
-- Don't apply character formatting to the `link` macro attributes,
-  LinuxDoc does not allow displayed link text to be formatted.
-
-The default output file name extension is `.sgml`.
-
-latex
-~~~~~
-An experimental LaTeX backend has been written for AsciiDoc by
-Benjamin Klum.  A tutorial `./doc/latex-backend.html` is included in
-the AsciiDoc distribution which can also be viewed at
-http://www.methods.co.nz/asciidoc/latex-backend.html.
-
-
 Document Structure
 ------------------
 An AsciiDoc document consists of a series of <<X8,block elements>>
@@ -375,13 +356,10 @@ definition] as follows:
   BulletedList  ::= (ListItem)+
   NumberedList  ::= (ListItem)+
   CalloutList   ::= (ListItem)+
-  LabeledList   ::= (ItemLabel+,ListItem)+
+  LabeledList   ::= (ListEntry)+
+  ListEntry     ::= (ListLabel,ListItem)
+  ListLabel     ::= (ListTerm+)
   ListItem      ::= (ItemText,(List|ListParagraph|ListContinuation)*)
-  Table         ::= (Ruler,TableHeader?,TableBody,TableFooter?)
-  TableHeader   ::= (TableRow+,TableUnderline)
-  TableFooter   ::= (TableRow+,TableUnderline)
-  TableBody     ::= (TableRow+,TableUnderline)
-  TableRow      ::= (TableData+)
 
 Where:
 
@@ -474,11 +452,12 @@ 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 an underscore.
+- Replace all non-alphanumeric title characters with underscores.
 - Strip leading or trailing underscores.
 - Convert to lowercase.
-- Prepend an underscore (so there's no possibility of name clashes
-  with existing document IDs).
+- 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.
 
@@ -591,8 +570,7 @@ following default order:
 4. Replacements
 5. Attributes
 6. Inline Macros
-7. Passthroughs
-8. Replacements2
+7. Replacements2
 
 The substitutions and substitution order performed on
 Title, Paragraph and DelimitedBlock elements is determined by
@@ -617,11 +595,18 @@ _Emphasized text_::
 
 +Monospaced text+::
         Word phrases \`enclosed in backtick characters` (grave
-        accents) or \+plus characters+ are rendered in a monospaced font.
+        accents) or \+plus characters+ are rendered in a monospaced
+        font.
+
+`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.
 
-``Quoted text''::
-        Phrases \``enclosed with two grave accents to the left and two
-        acute accents to the right\'' are rendered in 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
@@ -651,7 +636,7 @@ is a number which treated as em units. Here are some examples:
 New quotes can be defined by editing asciidoc(1) configuration files.
 See the <<X7,Configuration Files>> section for details.
 
-.Quoted text properties
+.Quoted text behavior
 - Quoting cannot be overlapped.
 - Different quoting types can be nested.
 - To suppress quoted text formatting place a backslash character
@@ -700,20 +685,6 @@ constrained quotes) -- here's how to escape the previous example:
 
 =====================================================================
 
-[[X50]]
-Inline Passthroughs
-~~~~~~~~~~~~~~~~~~~
-This special text quoting mechanism passes inline text to the output
-document without the usual substitutions. There are two flavors:
-
-\+\++Triple-plus passthrough\+\++::
-    No change is made to the quoted text, it is passed verbatim to the
-    output document.
-
-\$$Double-dollar passthrough$$::
-    Special characters are escaped but no other changes are made.
-    This passthrough can be prefixed with inline attributes.
-
 Superscripts and Subscripts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Put \^carets on either^ side of the text to be superscripted, put
@@ -732,29 +703,45 @@ Superscripts and subscripts are implemented as <<X52,unconstrained
 quotes>> so they can be escaped with a leading backslash and prefixed
 with with an attribute list.
 
-Line Breaks (HTML/XHTML)
-~~~~~~~~~~~~~~~~~~~~~~~~
+Line Breaks
+~~~~~~~~~~~
 A plus character preceded by at least one space character at the end
-of a line forces a line break. It generates an HTML line break
-(`<br />`) tag. Line breaks are ignored when outputting to DocBook
-since it has no line break element.
+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)>> if you use FOP.
 
-Rulers (HTML/XHTML)
-~~~~~~~~~~~~~~~~~~~
-A line of four or more apostrophe characters will generate an HTML
-ruler (`<hr />`) tag. Ignored when generating non-HTML output formats.
+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)>> if you use FOP. 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)>> if
+you use FOP.
 
 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 the 'include' block macro
-by setting a 'tabsize' attribute in the macro's attribute list. For example:
+`[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`
+for example `--attribute tabsize=4`
 
 Replacements
 ~~~~~~~~~~~~
@@ -771,6 +758,17 @@ Which are rendered as:
 -- 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:
+
+  &#x278a; &#182;
+
+renders:
+
+&#x278a; &#182;
+
+To render a replacement literally escape it with a leading back-slash.
+
 The <<X7,Configuration Files>> section explains how to configure your
 own replacements.
 
@@ -1023,17 +1021,17 @@ The <<X56,code>>, <<X57,source>> and <<X58,music>> filter blocks are
 detailed in the <<X59,Filters>> section.
 
 .Default DelimitedBlock substitutions
-`-------------.------------.---------.---------.---------.---------
-              Passthrough  Listing   Literal   Sidebar   Quote
--------------------------------------------------------------------
-Callouts        No          Yes       Yes       No        No
-Attributes      Yes         No        No        Yes       Yes
-Inline Macros   Yes         No        No        Yes       Yes
-Quotes          No          No        No        Yes       Yes
-Replacements    No          No        No        Yes       Yes
-Special chars   No          Yes       Yes       Yes       Yes
-Special words   No          No        No        Yes       Yes
--------------------------------------------------------------------
+[cols="2,5*^",options="header"]
+|==================================================================
+|              |Passthrough |Listing  |Literal  |Sidebar  |Quote
+|Callouts      |  No        | Yes     | Yes     | No      | No
+|Attributes    |  Yes       | No      | No      | Yes     | Yes
+|Inline Macros |  Yes       | No      | No      | Yes     | Yes
+|Quotes        |  No        | No      | No      | Yes     | Yes
+|Replacements  |  No        | No      | No      | Yes     | Yes
+|Special chars |  No        | Yes     | Yes     | Yes     | Yes
+|Special words |  No        | No      | No      | Yes     | Yes
+|==================================================================
 
 Listing Blocks
 ~~~~~~~~~~~~~~
@@ -1045,14 +1043,16 @@ often used for code and file listings.
 
 Here's an example:
 
-  --------------------------------------
-  #include <stdio.h>
+---------------------------------------
+ --------------------------------------
+ #include <stdio.h>
 
   int main() {
-      printf("Hello World!\n");
-      exit(0);
-  }
-  --------------------------------------
+     printf("Hello World!\n");
+     exit(0);
+ }
+ --------------------------------------
+---------------------------------------
 
 Which will be rendered like:
 
@@ -1130,11 +1130,12 @@ asciidoc(1).
 
 See also <<X25,Comment Lines>>.
 
+[[X76]]
 Passthrough Blocks
 ~~~~~~~~~~~~~~~~~~
-PassthroughBlocks are for backend specific markup, text is only
-subject to attribute and macro substitution.  PassthroughBlock content
-will generally be backend specific. Here's an example:
+By default the block contents is subject to attribute and macro
+substitution, no other markup is generated.  PassthroughBlock content
+will often be backend specific. Here's an example:
 
 ---------------------------------------------------------------------
 ++++++++++++++++++++++++++++++++++++++
@@ -1145,6 +1146,16 @@ will generally be backend specific. Here's an example:
 ++++++++++++++++++++++++++++++++++++++
 ---------------------------------------------------------------------
 
+Use and explicit 'subs' attribute to control substitution.  The
+following styles can be applied to passthrough blocks:
+
+pass::
+  By default no substitutions are performed.
+
+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
@@ -1222,9 +1233,8 @@ Qui in magna commodo, est labitur dolorum an. Est ne magna primis
 adolescens.
 =====================================================================
 
-The title prefix that is automatically inserted by asciidoc(1) can be
-customized with the `caption` attribute (`xhtml11` and `html4`
-backends). For example
+A title prefix that can be inserted with the `caption` attribute
+(`xhtml11` and `html4` backends). For example:
 
 ---------------------------------------------------------------------
 [caption="Example 1: "]
@@ -1289,20 +1299,22 @@ Lists
 - Callout lists (a list of callout annotations).
 
 .List behavior
-- Indentation is optional and does not determine nesting, indentation
-  does however make the source more readable.
+- List item indentation is optional and does not determine nesting,
+  indentation does however make the source more readable.
 - A nested list must use a different syntax from its parent so that
   asciidoc(1) can distinguish the start of a nested list.
 - By default lists of the same type can only be nested two deep; this
   could be increased by defining new list definitions.
 - In addition to nested lists a list item will include immediately
   following Literal paragraphs.
-- Use <<X15, List Item Continuation>> to include other block elements
-  in a list item.
+- Use <<X15, List Item Continuation>> to append other block elements
+  to a list item.
 - The `listindex` <<X60,intrinsic attribute>> is the current list item
   index (1..). If this attribute is not inside 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.
+- You need to use <<X15,list item continuation>> if a nested list is
+  accompanied by an <<X21,attribute list>>.
 
 Bulleted and Numbered Lists
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1373,28 +1385,43 @@ Which render as:
   3. Donec eget arcu bibendum nunc consequat lobortis.
   4. Nam fermentum mattis ante.
 
-Vertical Labeled Lists
-~~~~~~~~~~~~~~~~~~~~~~
+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.
+
+Labeled Lists
+~~~~~~~~~~~~~
 Labeled list items consist of one or more text labels followed the
 text of the list item.
 
 An item label begins a line with an alphanumeric character hard
 against the left margin and ends with a double colon `::` or
-semi-colon `;;`.
+semi-colon `;;`. A list item can have multiple labels, one per line.
 
-The list item text consists of one or more lines of text starting on
-the line immediately following the label and can be followed by nested
-List or ListParagraph elements. Item text can be optionally indented.
+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.
+Ipsum:: Vivamus fringilla mi eu lacus.
   * Vivamus fringilla mi eu lacus.
   * Donec eget arcu bibendum nunc consequat lobortis.
 Dolor::
@@ -1409,13 +1436,13 @@ Dolor::
 
 Which render as:
 
+In::
 Lorem::
   Fusce euismod commodo velit.
 
   Fusce euismod commodo velit.
 
-Ipsum::
-  Vivamus fringilla mi eu lacus.
+Ipsum:: Vivamus fringilla mi eu lacus.
   * Vivamus fringilla mi eu lacus.
   * Donec eget arcu bibendum nunc consequat lobortis.
 Dolor::
@@ -1427,18 +1454,13 @@ Dolor::
   In;;
     Dictum mauris in urna.
 
-Horizontal Labeled Lists
-~~~~~~~~~~~~~~~~~~~~~~~~
-Horizontal labeled lists differ from vertical labeled lists in that
-the label and the list item sit side-by-side as opposed to the item
-under the label. Item text must begin on the same line as the label
-although you can begin item text on the next line if you follow the
-label with a backslash.
-
-The following horizontal list example also illustrates the omission
-of optional indentation:
+Horizontal labeled list style
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The 'horizontal' labeled list style 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.
 
@@ -1448,7 +1470,7 @@ labitur dolorum an. Est ne magna primis adolescens.
 - Vivamus fringilla mi eu lacus.
 - Donec eget arcu bibendum nunc consequat lobortis.
 
-*Dolor*:: \
+*Dolor*::
   - Vivamus fringilla mi eu lacus.
   - Donec eget arcu bibendum nunc consequat lobortis.
 
@@ -1456,6 +1478,7 @@ labitur dolorum an. Est ne magna primis adolescens.
 
 Which render as:
 
+[horizontal]
 *Lorem*:: Fusce euismod commodo velit.  Qui in magna commodo, est
 labitur dolorum an. Est ne magna primis adolescens.
 
@@ -1465,50 +1488,54 @@ labitur dolorum an. Est ne magna primis adolescens.
 - Vivamus fringilla mi eu lacus.
 - Donec eget arcu bibendum nunc consequat lobortis.
 
-*Dolor*:: \
+*Dolor*::
   - Vivamus fringilla mi eu lacus.
   - Donec eget arcu bibendum nunc consequat lobortis.
 
-[WARNING]
+[NOTE]
 =====================================================================
-- Use vertical labeled lists in preference to horizontal labeled lists
-  -- current PDF toolchains do not make a good job of determining
-  the relative column widths.
-- If you are generating DocBook markup the horizontal labeled lists
+- Current PDF toolchains do not make a good job of determining
+  the relative column widths for horizontal labeled lists.
+- If you are generating DocBook markup then horizontal labeled lists
   should not be nested because the 'DocBook XML V4.2' DTD does not
   permit nested informal tables (although <<X13,DocBook XSL
-  Stylesheets>> process them correctly).
+  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 labeled list for generating
-DocBook question and answer (Q&A) lists (`??` label delimiter).
-Example:
+AsciiDoc comes pre-configured with a 'qanda' style labeled list for generating
+DocBook question and answer (Q&A) lists. Example:
 
 ---------------------------------------------------------------------
-Question one??
+[qanda]
+Question one::
         Answer one.
-Question two??
+Question two::
         Answer two.
 ---------------------------------------------------------------------
 
 Renders:
 
-Question one??
+[qanda]
+Question one::
         Answer one.
-Question two??
+Question two::
         Answer two.
 
 Glossary Lists
 ~~~~~~~~~~~~~~
-AsciiDoc comes pre-configured with a labeled list (`:-` label
-delimiter) for generating DocBook glossary lists. Example:
+AsciiDoc comes pre-configured with a 'glossary' style labeled list for
+generating DocBook glossary lists. Example:
 
 ---------------------------------------------------------------------
-A glossary term:-
+[glossary]
+A glossary term::
     The corresponding definition.
-A second glossary term:-
+A second glossary term::
     The corresponding definition.
 ---------------------------------------------------------------------
 
@@ -1520,13 +1547,14 @@ in a glossary section.
 
 Bibliography Lists
 ~~~~~~~~~~~~~~~~~~
-AsciiDoc comes with a predefined itemized list (`+` item bullet) for
-generating bibliography entries.  Example:
+AsciiDoc comes with a predefined 'bibliography' bulleted list style
+generating DocBook bibliography entries. Example:
 
 ---------------------------------------------------------------------
-+ [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
+[bibliography]
+- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
   Programming'. Addison-Wesley. ISBN 0-13-142901-9.
-+ [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
+- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
   'DocBook - The Definitive Guide'. O'Reilly & Associates.
   1999. ISBN 1-56592-580-7.
 ---------------------------------------------------------------------
@@ -1553,7 +1581,11 @@ implicitly included nested lists and Literal paragraphs) place a
 separator line containing a single plus character between the list
 item and the ensuing list continuation element.  Multiple block
 elements (excluding section Titles and BlockTitles) may be included in
-a list item using this technique.  For example:
+a list item using this technique.  Note that the continued items must
+be indented as they normally would be outside of the list.
+
+You also need to use list item continuation if a nested list is
+accompanied by an <<X21,attribute list>>.
 
 Here's an example of list item continuation:
 
@@ -1677,14 +1709,26 @@ This paragraph belongs to item 1.
 Footnotes
 ---------
 The shipped AsciiDoc configuration includes the `\footnote:[<text>]`
-inline macro for generating footnotes. The footnote text can span
-multiple lines. Example footnote:
+and `\footnoteref:[<id>,<text>]` inline macros for generating
+footnotes:
+
+- The `footnote` macro generates a footnote.
+- The `footnoteref` macro has two forms: if the text is supplied a
+  foot note with an ID is generated; if the text is omitted a
+  reference to the footnote with the specified ID is generated.
+- The footnote text can span multiple lines.
+
+Example footnote:
 
-  A footnote footnote:[An example footnote.]
+  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].
 
 Which renders:
 
-A footnote footnote:[An example footnote.]
+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].
 
 Footnotes are primarily useful when generating DocBook output --
 DocBook conversion programs render footnote outside the primary text
@@ -1729,30 +1773,30 @@ 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.
+ .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
@@ -1764,7 +1808,7 @@ Which renders:
 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.
@@ -1842,8 +1886,8 @@ Macros are a mechanism for substituting parametrized text into output
 documents.
 
 Macros have a 'name', a single 'target' argument and an 'attribute
-list'.  The default syntax is `<name>:<target>[<attributelist>]` (for
-inline macros) and `<name>::<target>[<attributelist>]` (for block
+list'.  The usual syntax is `<name>:<target>[<attrlist>]` (for
+inline macros) and `<name>::<target>[<attrlist>]` (for block
 macros).  Here are some examples:
 
   http://www.methods.co.nz/asciidoc/index.html[Asciidoc home page]
@@ -1854,19 +1898,24 @@ macros).  Here are some examples:
 - `<name>` is the macro name. It can only contain letters, digits or
   dash characters and cannot start with a dash.
 - The optional `<target>` cannot contain white space characters.
-- `<attributelist>` is a <<X21,list of attributes>> enclosed in square
+- `<attrlist>` is a <<X21,list of attributes>> enclosed in square
   brackets.
-- The attribute list is mandatory except for URLs and email addresses.
-- Expansion of non-system macro references can be escaped by
-  prefixing a backslash character.
-- Block macro attribute reference substitution is performed prior to
-  macro expansion.
+- `]` characters in attribute lists that are enclosed in `[]` brackets
+  must be escaped with a backslash.
+- Expansion of non-system macro references can normally be escaped by
+  prefixing a backslash character (see the AsciiDoc 'FAQ' for examples
+  of exceptions to this rule).
+- System macros cannot be escaped.
+- Attribute references in block macros are expanded.
 - The substitutions performed prior to Inline macro macro expansion
   are determined by the inline context.
 - Macros are processed in the order they appear in the configuration
   file(s).
 - Calls to inline macros can be nested inside different inline macros
   (an inline macro call cannot contain a nested call to itself).
+- In addition to `<name>`, `<target>` and `<attrlist>` the
+  `<passtext>` and `<subslist>` named groups are available to
+  <<X77,passthrough macros>>.
 
 Inline Macros
 ~~~~~~~~~~~~~
@@ -1881,7 +1930,7 @@ rendered using predefined inline macros.
 - If you don't need a customized the link caption you can enter the
   'http', 'https', 'ftp', 'file' URLs and email addresses without any
   special macro syntax.
-- If no caption text is specified the URL is displayed.
+- If the `<attrlist>` is empty the URL is displayed.
 
 Here are some examples:
 
@@ -2044,7 +2093,7 @@ Block macros behave just like Inline macros, with the following
 differences:
 
 - They occur in a block context.
-- The default syntax is `<name>::<target>[<attributelist>]` (two
+- The default syntax is `<name>::<target>[<attrlist>]` (two
   colons, not one).
 - Markup template section names end in `-blockmacro` instead of
   `-inlinemacro`.
@@ -2080,9 +2129,8 @@ For example:
   .Main circuit board
   image::images/layout.png[J14P main circuit board]
 
-`xhtml11` and `html4` backends precede the title with a `Figure :`
-prefix. You can customize this prefix with the `caption` attribute.
-For example:
+A title prefix that can be inserted with the `caption` attribute
+(`xhtml11` and `html4` backends). For example:
 
   .Main circuit board
   [caption="Figure 2:"]
@@ -2120,7 +2168,6 @@ paragraphs or delimited blocks. Example comment line:
 
 See also <<X26,Comment Blocks>>.
 
-
 System Macros
 ~~~~~~~~~~~~~
 System macros are block macros that perform a predefined task which is
@@ -2155,17 +2202,23 @@ Example:
 - If the included file name is specified with a relative path then the
   path is relative to the location of the referring document.
 - Include macros can appear inside configuration files.
-- Files included from within `DelimitedBlocks` are read to completion
+- Files included from within 'DelimitedBlocks' are read to completion
   to avoid false end-of-block underline termination.
-- File inclusion is limited to a depth of 5 to catch recursive loops.
-- Attribute references are expanded inside the include `target`; if an
+- Attribute references are expanded inside the include 'target'; if an
   attribute is undefined then the included file is silently skipped.
 - The 'tabsize' macro attribute sets the number of space characters to
-  be used for tab expansion in the included file.
+  be used for tab expansion in the included file (not applicable to
+  `include1` macro).
+- The 'depth' macro attribute sets the maximum permitted number of
+  subsequent nested includes (not applicable to `include1` macro which
+  does not process nested includes). Setting 'depth' to one disables
+  nesting inside the included file. By default, nesting is limited to
+  a depth of five.
 - Internally the `include1` macro is translated to the `include1`
   system attribute which means it must be evaluated in a region where
-  attribute substitution is enabled -- use the `include` macro
-  instead.
+  attribute substitution is enabled. To inhibit nested substitution in
+  included files it is preferable to use the `include` macro and set
+  the attribute `depth=1`.
 
 Conditional Inclusion Macros
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2255,30 +2308,91 @@ section:
   template::[admonitionblock]
 
 .Template macro behavior
-- The `\template::[]` macro is useful for factoring configuration file
+- The `template::[]` macro is useful for factoring configuration file
   markup.
-- `\template::[]` macros cannot be nested.
-- `\template::[]` macro expansion is applied to all sections
+- `template::[]` macros cannot be nested.
+- `template::[]` macro expansion is applied to all sections
   after all configuration files have been read.
 
 
+[[X77]]
+Passthrough macros
+~~~~~~~~~~~~~~~~~~
+Passthrough macros are analogous to <<X76,passthrough blocks>> and are
+used to pass text directly to the output. The substitution performed
+on the text is determined by the macro definition but can be overridden
+by the `<subslist>`.  The usual syntax is
+`<name>:<subslist>[<passtext>]` (for inline macros) and
+`<name>::<subslist>[<passtext>]` (for block macros).
+
+pass::
+  Inline and block. Passes text unmodified apart from explicitly
+  specified substitutions). Examples:
+
+  pass:[<q>To be or not to be</q>]
+  pass:attributes,quotes[<u>the '{author}'</u>]
+
+asciimath, latexmath::
+  Inline and block. Passes text unmodified.  Used for
+  <<X78,mathematical formulas>>.
+
+\+++::
+  Inline and block. The triple-plus passthrough is functionally
+  identical to the 'pass' macro but you don't have to escape `]`
+  characters and you can prefix with quoted attributes in the inline
+  version. Example:
+
+  Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMathML formula
+
+$$::
+  Inline and block. The double-dollar passthrough is functionally
+  identical with one exception: special characters are escaped.
+  Example:
+
+  $$`[[a,b],[c,d]]((n),(k))`$$
+
 Macro Definitions
 ~~~~~~~~~~~~~~~~~
 Each entry in the configuration `[macros]` section is a macro
 definition which can take one of the following forms:
 
-`<pattern>=<name>`::
+`<pattern>=<name>[<subslist]`::
         Inline macro definition.
-`<pattern>=#<name>`::
+`<pattern>=#<name>[<subslist]`::
         Block macro definition.
-`<pattern>=+<name>`::
+`<pattern>=+<name>[<subslist]`::
         System macro definition.
 `<pattern>`::
         Delete the existing macro with this `<pattern>`.
 
 `<pattern>` is a Python regular expression and `<name>` is the name of
 a markup template. If `<name>` is omitted then it is the value of the
-regular expression match group named 'name'.
+regular expression match group named 'name'.  The optional
+`[<subslist]` is a comma-separated list of substitution names enclosed
+in `[]` brackets, it sets the default substitutions for passthrough
+text.
+
+.Pattern named groups
+The following named groups can be used in macro `<pattern>` regular
+expressions and are available as markup template attributes:
+
+name::
+  The macro name.
+
+target::
+  The macro target.
+
+attrlist::
+  The macro attribute list.
+
+passtext::
+  Contents of this group are passed unmodified to the output subject
+  only to 'subslist' substitutions.
+
+subslist::
+  Processed as a comma-separated list of substitution names for
+  'passtext' substitution, overrides the the macro definition
+  'subslist'.
 
 .Here's what happens during macro substitution
 - Each contextually relevant macro 'pattern' from the `[macros]`
@@ -2295,294 +2409,352 @@ regular expression match group named 'name'.
 
 Tables
 ------
-Tables are the most complex AsciiDoc elements and this section is
-quite long. footnote:[The current table syntax is overly complicated
-and unwieldy to edit, hopefully a more usable syntax will appear in
-future versions of AsciiDoc.]
-
-NOTE: AsciiDoc generates nice HTML tables, but the current crop of
-DocBook toolchains render tables with varying degrees of success. Use
-tables only when really necessary.
+The AsciiDoc table syntax looks and behaves like other delimited block
+types and supports standard <<X73,block configuration entries>>.
+Formatting is easy to read and, just as importantly, easy to enter.
+There are a wide variety of built-in customizable styles.
 
-Example Tables
-~~~~~~~~~~~~~~
-The following annotated examples are all you'll need to start creating
-your own tables.
+- All table meta-data is contained specified in the table's attribute
+  list, not in the the table data.
+- There is no provision for cells to span multiple columns.
 
-The only non-obvious thing you'll need to remember are the column stop
-characters:
+.Use tables sparingly
+*********************************************************************
+When technical users first start creating documents, tables (complete
+with column spanning and table nesting) are often considered very
+important.  important must-have feature. The reality is that tables
+are seldom used, even in technical documentation.
 
-- Backtick (`) -- align left.
-- Single quote (') -- align right.
-- Period (.) -- align center.
+Try this exercise: thumb through your library of technical books,
+you'll be surprised just how seldom tables are actually used, even
+less seldom are tables containing block elements such as paragraphs or
+lists. This is no accident, like figures, tables are outside the
+normal document flow -- tables are for consulting not for reading.
 
-Simple table:
+Tables are designed for, and should normally only be used for,
+displaying column oriented tabular data.
 
----------------------------------------------------------------------
- `---`---
- 1   2
- 3   4
- 5   6
- --------
----------------------------------------------------------------------
+*********************************************************************
 
-Output:
+Example tables
+~~~~~~~~~~~~~~
+Simple table
+^^^^^^^^^^^^
 
-`---`---
-1   2
-3   4
-5   6
---------
+[width="15%"]
+|=======
+|1 |2 |A
+|3 |4 |B
+|5 |6 |C
+|=======
 
-Table with title, header and footer:
+AsciiDoc source:
 
 ---------------------------------------------------------------------
- .An example table
- [grid="all"]
- '---------.--------------
- Column 1   Column 2
- -------------------------
- 1          Item 1
- 2          Item 2
- 3          Item 3
- -------------------------
- 6          Three items
- -------------------------
+[width="15%"]
+|=======
+|1 |2 |A
+|3 |4 |B
+|5 |6 |C
+|=======
 ---------------------------------------------------------------------
 
-Output:
+Columns formatted with strong, monospaced and emphasis styles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .An example table
-[grid="all"]
-`-----------.--------------
-Column 1     Column 2
----------------------------
-1            Item 1
-2            Item 2
-3            Item 3
----------------------------
-6            Three items
----------------------------
-
-Four columns totaling 15% of the 'pagewidth', CSV data:
+[width="50%",cols=">s,^m,e",frame="none",options="header,footer"]
+|==========================
+|        |Column 2|Column 3
+|1       |Item 1  |Item 1
+|2       |Item 2  |Item 2
+|3       |Item 3  |Item 3
+|4       |Item 4  |Item 4
+|footer 1|footer 2|footer 3
+|==========================
+
+AsciiDoc source:
 
 ---------------------------------------------------------------------
-[frame="all"]
-````~15
-1,2,3,4
-a,b,c,d
-A,B,C,D
-~~~~~~~~
+.An example table
+[width="50%",cols=">s,^m,e",frame="none",options="header,footer"]
+|==========================
+|        |Column 2|Column 3
+|1       |Item 1  |Item 1
+|2       |Item 2  |Item 2
+|3       |Item 3  |Item 3
+|4       |Item 4  |Item 4
+|footer 1|footer 2|footer 3
+|==========================
 ---------------------------------------------------------------------
 
-Output:
+Horizontal and vertical source data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Short cells can be entered horizontally, longer cells vertically.  The
+default behavior is to strip leading and trailing blank lines within a
+cell. These characteristics aid readability and data entry.
 
-[frame="all"]
-````~15
-1,2,3,4
-a,b,c,d
-A,B,C,D
-~~~~~~~~
+.Windtrainer workouts
+[width="80%",cols="3,^2,^2,10",options="header"]
+|=========================================================
+|Date |Duration |Avg HR |Notes
 
-A table with a numeric ruler and externally sourced CSV data:
+|22-Aug-08 |10:24 | 157 |
+Worked out MSHR (max sustainable heart rate) by going hard
+for this interval.
+
+|22-Aug-08 |23:03 | 152 |
+Back-to-back with previous interval.
+
+|24-Aug-08 |40:00 | 145 |
+Moderately hard interspersed with 3x 3min intervals (2min
+hard + 1min really hard taking the HR up to 160).
+
+|=========================================================
+
+AsciiDoc source:
 
 ---------------------------------------------------------------------
- [frame="all", grid="all"]
- .15`20`25`20`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- ID,Customer Name,Contact Name,Customer Address,Phone
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- include::customers.csv[]
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------------------------------------
+.Windtrainer workouts
+[width="80%",cols="3,^2,^2,10",options="header"]
+|=========================================================
+|Date |Duration |Avg HR |Notes
 
-Renders:
+|22-Aug-08 |10:24 | 157 |
+Worked out MSHR (max sustainable heart rate) by going hard
+for this interval.
 
-[frame="all", grid="all"]
-.15`20`25`20`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-ID,Customer Name,Contact Name,Customer Address,Phone
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-include::customers.csv[]
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+|22-Aug-08 |23:03 | 152 |
+Back-to-back with previous interval.
 
-AsciiDoc Table Block Elements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This sub-section details the AsciiDoc table format.
-
-  Table  ::= (Ruler,Header?,Body,Footer?)
-  Header ::= (Row+,Underline)
-  Footer ::= (Row+,Underline)
-  Body   ::= (Row+,Underline)
-  Row    ::= (Data+)
-
-A table is terminated when the table underline is followed by a blank
-line or an end of file. Table underlines which separate table headers,
-bodies and footers should not be followed by a blank line.
-
-Ruler
-^^^^^
-The first line of the table is called the 'Ruler'. The Ruler specifies
-which configuration file table definition to use, column widths,
-column alignments and the overall table width.
-
-There are two ruler formats:
-
-Character ruler::
-        The column widths are determined by the number of table fill
-        characters between column stop characters.
-Numeric ruler::
-        The column widths are specified numerically. If a column width
-        is omitted the previous width is used. In the degenerate case
-        of no widths being specified columns are allocated equal
-        widths.
-
-The ruler format can be summarized as:
-
-  ruler ::= ((colstop,colwidth?,fillchar*)+, fillchar+, tablewidth?
-
-- The 'ruler' starts with a column stop character (designating the
-  start of the first column).
-- Column stop characters specify the start and alignment of each
-  column:
-  * Backtick (`) -- align left.
-  * Single quote (') -- align right.
-  * Period (.) -- align center.
-- In the case of 'fixed' format tables the ruler column widths specify
-  source row data column boundaries.
-- The optional 'tablewidth' is a number representing the size of the
-  output table relative to the 'pagewidth'. If 'tablewidth' is less
-  than one then it is interpreted as a fraction of the page width; if
-  it is greater than one then it is interpreted as a percentage of
-  the page width. If 'tablewidth' is not specified then the table
-  occupies the full 'pagewidth' (numeric rulers) or the relative width
-  of the ruler compared to the 'textwidth' (character rulers).
-
-Row and Data Elements
-^^^^^^^^^^^^^^^^^^^^^
-Each table row consists of a line of text containing the same number
-of 'Data' items as there are columns in the table,
+|24-Aug-08 |40:00 | 145 |
+Moderately hard interspersed with 3x 3min intervals (2min
+hard + 1min really hard taking the HR up to 160).
 
-Lines ending in a backslash character are continued on the next line.
+|=========================================================
+---------------------------------------------------------------------
 
-Each 'Data' item is an AsciiDoc substitutable string. The substitutions
-performed are specified by the 'subs' table definition entry. Data
-cannot contain AsciiDoc block elements.
+A table with externally sourced CSV data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The format of the row is determined by the table definition 'format'
-value:
+[format="csv",cols="^1,4*2",options="header"]
+|===================================================
+ID,Customer Name,Contact Name,Customer Address,Phone
+include::customers.csv[]
+|===================================================
 
-fixed::
-  Row data items are assigned by chopping the row up at ruler column
-  width boundaries.
+AsciiDoc source:
 
-csv::
-  Data items are assigned the parsed CSV (Comma Separated Values)
-  data.
+---------------------------------------------------------------------
+ [format="csv",cols="^1,4*2",options="header"]
+ |===================================================
+ ID,Customer Name,Contact Name,Customer Address,Phone
+ include::customers.csv[]
+ |===================================================
+---------------------------------------------------------------------
 
-dsv::
-  The DSV (Delimiter Separated Values) format is a common UNIX tabular
-  text file format.
-  - The separator character is a colon (although this can be set to
-    any letter using the 'separator' table attribute).
-  - Common C-style backslash escapes are supported.
-  - Blank lines are skipped.
 
-Underline
-^^^^^^^^^
-A table 'Underline' consists of a line of three or more 'fillchar'
-characters which are end delimiters for table header, footer and body
-sections.
+[[X68]]
+Table input data formats
+~~~~~~~~~~~~~~~~~~~~~~~~
+AsciiDoc table data can be 'psv', 'dsv' or 'csv' formatted.  The
+default AsciiDoc table format is 'psv'.
+
+'csv'  is the quasi-standard row oriented 'Comma Separated Values
+(CSV)' format commonly used to import and export spreadsheet and
+database data.
+
+AsciiDoc 'psv' ('Prefix Separated Values') and 'dsv' ('Delimiter
+Separated Values') formats are cell oriented -- the table is treated
+as a sequence of cells -- there are no mandatory row separators.
+
+- 'psv' prefixes each cell with a separator whereas 'dsv' delimits
+  cells with a separator, that really the only difference (apart from
+  different default separators).
+- 'psv' and 'dsv' separators are Python regular expressions.
+- The default 'psv' separator is `((?P<cellcount>\d+)\*)?\|` (a pipe
+  character with optional cell multiplier prefix); the default 'dsv'
+  separator is `:|\n` (a colon or a line break).
+- 'psv' and 'dsv' cell separators can be escaped by preceding them
+  with a backslash character.
+- The 'psv' format allows cells to be stacked vertically, this makes
+  it easy to enter large amounts of text per cell while still
+  retaining readability.
+
+Here are four 'psv' cells (the second item is multiplied by two; the
+last contains an escaped separator):
+
+  |One 2*|Two and three |A \| separator character
+
+[[X69]]
+Table attributes
+~~~~~~~~~~~~~~~~
+Individual tables are customized by an optional <<X21,AttributeList>>
+preceding the table. Specify attributes when you want to change the
+default table format:
 
-Attribute List
-^^^^^^^^^^^^^^
-The following optional table attributes can be specified in an
-<<X21,AttributeList>> preceding the table:
+format::
+'psv' (default), 'dsv' or 'csv' (See <<X68, Table Data Formats>>).
 
 separator::
-  The default DSV format colon separator can be changed using the
-  'separator' attribute. For example: `[separator="|"]`.
+The cell separator. A Python regular expression ('psv' and 'dsv'
+formats) or a single character ('csv' format).
 
 frame::
-  Defines the table border and can take the following values: 'topbot'
-  (top and bottom), 'all' (all sides), 'none' and 'sides' (left and
-  right sides). The default value is 'topbot'.
+Defines the table border and can take the following values: 'topbot'
+(top and bottom), 'all' (all sides), 'none' and 'sides' (left and
+right sides). The default value is 'all'.
 
 grid::
-  Defines which ruler lines are drawn between table rows and columns.
-  The 'grid' attribute value can be any of the following values:
-  'none', 'cols', 'rows' and 'all'. The default value is 'none'. For
-  example `[frame="all", grid="none"]`.
-
-format, tablewidth::
-  See <<X37,Markup Attributes>> below.
+Defines which ruler lines are drawn between table rows and columns.
+The 'grid' attribute value can be any of the following values: 'none',
+'cols', 'rows' and 'all'. The default value is 'all'.
 
-You can also use an AttributeList to override the following table
-definition and ruler parameters: 'format', 'subs', 'tablewidth'.
+valign::
+Use the 'valign' attribute to vertically align all cells in a table.
+The following values are valid: 'top', 'bottom', and 'middle'
+(defaults to 'top').
 
-[[X37]]
-Markup Attributes
-^^^^^^^^^^^^^^^^^
-The following attributes are automatically available inside table tag
-and markup templates.
+options::
+The 'options' attribute can contain the following comma separated
+values: 'header', 'footer'. By default header and footer rows are
+omitted.
 
 cols::
-  The number of columns in the table.
+The 'cols' attribute is a comma separated list of <<X70,column
+specifiers>>. For example `cols="2<p,2*,4p,>"`.
++
+- If 'cols' is present it must specify all columns.
+- If the 'cols' attribute is not specified the number of columns is
+  calculated as the number of data items in the *first line* of the
+  table.
+- The degenerate form for the 'cols' attribute is an integer
+  specifying the number of columns e.g. `cols=4`.
+
+width::
+The 'width' attribute is expressed as a percentage value
+('"1%"'...'"99%"'). The width specifies the table width relative to
+the available width. HTML outputs use this value directly. If width is
+specified DocBook uses the absolute widths (see calculated
+<<X72,markup attributes>> ), if no width is specified all of the
+available width is used.
 
-colalign::
-  Column alignment assumes one of three values ('left', 'right' or
-  'center'). The value is determined by the corresponding ruler column
-  stop character (only valid inside 'colspec', 'headdata', 'bodydata'
-  and 'footdata' tags).
+filter::
+The 'filter' attribute defines an external shell command that is
+invoked for each cell. The built-in 'asciidoc' table style is
+implemented using a filter.
 
-colwidth::
-  The output column widths are calculated integers (only valid inside
-  'colspec', 'headdata', 'bodydata' and 'footdata' tags).
+[[X70]]
+Column Specifiers
+~~~~~~~~~~~~~~~~~
+Column specifiers define how columns are presented and are used in the
+table <<X69,cols attribute>>.  A column specifier consists of an
+optional column multiplier followed by optional alignment, width and
+style values and is formatted like:
+
+  [<multiplier>*][<align>][<width>][<style>]
+
+- All components are optional. The multiplier must be first and the
+  style last. The order of 'align' or 'width' is not important.
+- Column '<width>' can be either an integer proportional value (1...)
+  or a percentage (1%...100%). The default value is 1. To ensure
+  portability across different backends, there is no provision for
+  absolute column widths (not to be confused with output column width
+  <<X72,markup attributes>> which are available in both percentage and
+  absolute units).
+- The column '<align>' character can be '<' (left), '^' (center) or
+  '>' (right). Cells are left aligned by default.
+- A '<multiplier>' can be used to specify repeated columns e.g.
+  `cols="4*<"` specifies four left-justified columns. Default value 1.
+- The '<style>' name specifies a <<X71,table style>> to used to markup
+  column cells (you can use the full style names if you wish but the
+  first letter is normally sufficient).
+- Column specific styles are not applied to 'header' row formatting.
+
+[[X71]]
+Table styles
+~~~~~~~~~~~~
+Table styles can be applied to the entire table (by setting the
+'style' attribute in the table's attribute list) or on a per column
+basis (by specifying the style in the table's <<X69,cols attribute>>).
+Tables come with the following predefined styles:
 
-colnumber::
-  The table column number starting at 1 (only valid inside 'colspec',
-  'headdata`, `bodydata` and `footdata` tags).
+default::
+The default style: AsciiDoc inline text formatting; blank lines are
+treated as paragraph breaks.
 
-format::
-  The table definition 'format' value (can be overridden with
-  attribute list entry).
+emphasis::
+Like default but all text is emphasised.
 
-tablewidth::
-  The ruler 'tablewidth' value (can be overridden with attribute list
-  entry).
+monospaced::
+Like default but all text is in a monospaced font.
 
-pagewidth::
-  The 'pagewidth' miscellaneous configuration option.
+strong::
+Like default but all text is bold.
+
+asciidoc::
+With this style table cells can contain any of the AsciiDoc elements
+that are allowed inside document sections. This style runs asciidoc(1)
+as a filter to process cell contents.
+
+literal::
+No text formatting; monospaced font; all line breaks are retained
+(like AsciiDoc 'LiteralBlock').
+
+verse::
+Text formatting; all line breaks are retained (c.f. AsciiDoc delimited
+block 'verse' style).
+
+[[X72]]
+Markup attributes
+~~~~~~~~~~~~~~~~~
+AsciiDoc makes a number of attributes available to table markup
+templates and tags. Both absolute and percentage width values are
+available. Column specific attributes are available when substituting
+the 'colspec' cell data tags.
 
 pageunits::
-  The 'pageunits' miscellaneous configuration option.
+Only used by DocBook, defaults to 'pt'.
 
-The 'colwidth' value is calculated as (`N` is the ruler column width
-number and `M` is the sum of the ruler column widths):
+pagewidth::
+The nominal output page width in 'pageunit' units. Used to calculate
+table and column widths.  Only used by DocBook, defaults to '425'.
 
-  ( N / M ) * pagewidth
+tableabswidth::
+Integer value calculated from 'width' and 'pagewidth' attributes.
+In 'pageunit' units.
 
-If the ruler 'tablewidth' was specified the column width is multiplied
-again by this value.
+tablepcwidth::
+Table width expressed as a percentage of the available width. Integer
+value (0..100).
 
-There is one exception: character rulers that have no 'pagewidth'
-specified. In this case the 'colwidth' value is calculated as (where
-`N` is the column character width measured on the table ruler):
+colalign::
+'left', 'right' or 'center'.
 
-  ( N / textwidth ) * pagewidth
+colabswidth::
+Integer value calculated from 'cols' column width, 'width' and
+'pagewidth' attributes.  In 'pageunit' units.
 
-The following attributes are available to the table markup template:
+colpcwidth::
+Column width expressed as a percentage of the table width. Integer
+value (0..100).
 
-comspecs::
-  Expands to N substituted 'comspec' tags where N is the number of
-  columns.
+colnumber::
+Integer value: '1' for column 1, '2' for column 2 ...
 
-headrows, footrows, bodyrows::
-  These references expand to sets of substituted header, footer and
-  body rows as defined by the corresponding row and data configuration
-  parameters.
+Nested tables
+~~~~~~~~~~~~~
+An alternative table syntax using a '!' character instead of a '|'
+character is provided to allow a single level of table nesting.
+Columns containing nested tables must use the 'asciidoc' style. An
+example can be found in `./examples/website/newtables.txt`.
 
-rows::
-  Experimental attribute (number of source lines in table) available
-  in table markup templates (used by experimental LaTeX backend).
+NOTE: When generating PDF nested tables using `a2x(1)` you will need
+to use the `--no-xmllint` option. This is because the nested tables
+are not legal in DocBook (you have to use the DocBook 4 'entrytbl'
+element). But both 'dblatex' (as of version 0.28) and 'FOP' (as of
+version 0.95beta) will process nested DocBook tables, but not
+'entrytbl' elements.
 
 
 [[X1]]
@@ -2661,6 +2833,89 @@ source file:
   :man manual:   AsciiDoc Manual
 
 
+[[X78]]
+Mathematical Formulas
+---------------------
+The 'asciimath' and 'latexmath' <<X77,passthrough macros>> along with
+'asciimath' and 'latexmath'  <<X76,passthrough blocks>> provide a
+(backend dependent) mechanism for rendering mathematical formulas. You
+can use the following math markups:
+
+NOTE: The 'latexmath' macro used to include 'LaTeX Math' in DocBook
+outputs is not the same as the 'latexmath' macro used to include
+'LaTeX MathML' in XHTML outputs.  'LaTeX Math' applies to DocBook
+outputs that are processed by <<X31,dblatex>> and is normally used to
+generate PDF files.  'LaTeXMathML' is very much a subset of 'LaTeX
+Math' and applies to XHTML documents.
+
+LaTeX Math
+~~~~~~~~~~
+ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf[LaTeX
+math] can be included in documents that are processed by
+<<X31,dblatex(1)>>.  Example inline formula:
+
+  latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]
+
+For more examples see the http://www.methods.co.nz/asciidoc/[AsciiDoc
+website] or the distributed `doc/latexmath.txt` file.
+
+ASCIIMathML
+~~~~~~~~~~~
+/////////////////////////////////////////////////////////////////////
+The older ASCIIMathML 1.47 version is used instead of version 2
+because:
+
+1. Version 2 doesn't work when embedded.
+2. Version 2 is much larger.
+/////////////////////////////////////////////////////////////////////
+
+http://www1.chapman.edu/~jipsen/mathml/asciimath.html[ASCIIMathML]
+formulas can be included in XHTML documents generated using the
+'xhtml11' backend. To enable ASCIIMathML support you must define the
+'asciimath' attribute, for example using the `-a asciimath`
+command-line option.  Example inline formula:
+
+  asciimath:[`x/x={(1,if x!=0),(text{undefined},if x=0):}`]
+
+For more examples see the http://www.methods.co.nz/asciidoc/[AsciiDoc
+website] or the distributed `doc/asciimathml.txt` file.
+
+LaTeXMathML
+~~~~~~~~~~~
+/////////////////////////////////////////////////////////////////////
+There is an http://math.etsu.edu/LaTeXMathML/[extended LaTeXMathML
+version] by Jeff Knisley, in addition to a JavaScript file it requires
+the inclusion of a CSS file.
+/////////////////////////////////////////////////////////////////////
+
+'LaTeXMathML' allows LaTeX Math style formulas to be included in XHTML
+documents generated using the AsciiDoc 'xhtml11' backend.  AsciiDoc
+uses the
+http://www.maths.nottingham.ac.uk/personal/drw/lm.html[original
+LaTeXMathML] by Douglas Woodall.  'LaTeXMathML' is derived from
+ASCIIMathML and is for users who are more familiar with or prefer
+using LaTeX math formulas (it recognizes a subset of LaTeX Math, the
+differences are documented on the 'LaTeXMathML' web page).  To enable
+LaTeXMathML support you must define the 'latexmath' attribute, for
+example using the `-a latexmath` command-line option.  Example inline
+formula:
+
+  latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$]
+
+For more examples see the http://www.methods.co.nz/asciidoc/[AsciiDoc
+website] or the distributed `doc/latexmathml.txt` file.
+
+There are more examples on the
+http://www.methods.co.nz/asciidoc/[AsciiDoc website].
+
+MathML
+~~~~~~
+http://www.w3.org/Math/[MathML] is a low level XML markup for
+mathematics. AsciiDoc has no macros for MathML but users familiar with
+this markup could use passthrough macros and passthrough blocks to
+include MathML in output documents.
+
+
 [[X7]]
 Configuration Files
 -------------------
@@ -2694,26 +2949,7 @@ conjunction with asciidoc(1) output files. You can view configuration
 file load sequence by turning on the asciidoc(1) `-v` (`--verbose`)
 command-line option.
 
-Markup Template Sections
-~~~~~~~~~~~~~~~~~~~~~~~~
-Markup template sections supply backend markup for translating
-AsciiDoc elements.  Since the text is normally backend dependent
-you'll find these sections in the backend specific configuration
-files. A markup template section body can contain:
-
-- Backend markup
-- Attribute references
-- System macro calls.
-- A document content placeholder
-
-The document content placeholder is a single | character and is
-replaced by text from the source element.  Use the `\{brvbar}`
-attribute reference if you need a literal | character in the template.
-
-Special Sections
-~~~~~~~~~~~~~~~~
-AsciiDoc reserves the following predefined special section names for
-specific purposes:
+AsciiDoc reserves the following section names for specific purposes:
 
 miscellaneous::
         Configuration options that don't belong anywhere else.
@@ -2735,24 +2971,30 @@ macros::
         Macro syntax definitions.
 titles::
         Heading, section and block title definitions.
-paradef*::
+paradef-*::
         Paragraph element definitions.
-blockdef*::
+blockdef-*::
         DelimitedBlock element definitions.
-listdef*::
+listdef-*::
         List element definitions.
-tabledef*::
+listtags-*::
+        List element tag definitions.
+tabledef-*::
         Table element definitions.
+tabletags-*::
+        Table element tag definitions.
 
-Each line of text in a special section is a 'section entry'. Section
+Each line of text in these sections is a 'section entry'. Section
 entries share the following syntax:
 
-'name=value'::
-        The entry value is set to 'value'.
-'name='::
+name=value::
+        The entry value is set to value.
+name=::
         The entry value is set to a zero length string.
-'name'::
-        The entry is undefined (deleted from the configuration).
+name!::
+        The entry is undefined (deleted from the configuration). This
+        syntax only applies to 'attributes' and 'miscellaneous'
+        sections.
 
 .Section entry behavior
 - All equals characters inside the `name` must be escaped with a
@@ -2766,8 +3008,8 @@ entries share the following syntax:
   template sections).
 
 
-Miscellaneous
-^^^^^^^^^^^^^
+Miscellaneous section
+~~~~~~~~~~~~~~~~~~~~~
 The optional `[miscellaneous]` section specifies the following
 `name=value` options:
 
@@ -2788,15 +3030,15 @@ tabsize::
         expansion (useful when piping included files through block
         filters). Included files can override this option using the
         'tabsize' attribute.
-textwidth, pagewidth, pageunits::
+pagewidth, pageunits::
         These global table related options are documented in the
         <<X4,Table Configuration File Definitions>> sub-section.
 
 NOTE: `[miscellaneous]` configuration file entries can be set using
 the asciidoc(1) `-a` (`--attribute`) command-line option.
 
-Titles
-^^^^^^
+Titles section
+~~~~~~~~~~~~~~
 sectiontitle::
         Two line section title pattern. The entry value is a Python
         regular expression containing the named group 'title'.
@@ -2821,8 +3063,8 @@ subs::
         the document header and section titles. Defaults to 'normal'
         substitution.
 
-Tags
-^^^^
+Tags section
+~~~~~~~~~~~~
 The `[tags]` section contains backend tag definitions (one per
 line). Tags are used to translate AsciiDoc elements to backend
 markup.
@@ -2839,20 +3081,20 @@ the output file.
 Use the `\{brvbar}` attribute reference if you need to include a | pipe
 character inside tag text.
 
-Attributes Section
-^^^^^^^^^^^^^^^^^^
+Attributes section
+~~~~~~~~~~~~~~~~~~
 The optional `[attributes]` section contains predefined attributes.
 
 If the attribute value requires leading or trailing spaces then the
-text text should be enclosed in double-quote (") characters.
+text text should be enclosed in quotation mark (") characters.
 
-To delete a attribute insert a name only entry in a downstream
+To delete a attribute insert a `name!` entry in a downstream
 configuration file or use the asciidoc(1) `--attribute name!`
-command-line option (the attribute name is suffixed with a ! character
-to delete it).
+command-line option (an attribute name suffixed with a `!` character
+deletes the attribute)
 
-Special Characters
-^^^^^^^^^^^^^^^^^^
+Special Characters section
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 The `[specialcharacters]` section specifies how to escape characters
 reserved by the backend markup. Each translation is specified on a
 single line formatted like:
@@ -2862,12 +3104,12 @@ single line formatted like:
 Special characters are normally confined to those that resolve
 markup ambiguity (in the case of SGML/XML markups the ampersand, less
 than and greater than characters).  The following example causes all
-occurrences of the `<` character to be replaced by `&lt;`.
+occurrences of the `<` character to be replaced by `\&lt;`.
 
   <=&lt;
 
-Quoted Text
-^^^^^^^^^^^
+Quoted Text section
+~~~~~~~~~~~~~~~~~~~
 Quoting is used primarily for text formatting.  The `[quotes]` section
 defines AsciiDoc quoting characters and their corresponding backend
 markup tags.  Each section entry value is the name of a of a `[tags]`
@@ -2904,8 +3146,8 @@ name with a hash character, for example:
 - To minimize quoting ambiguity try not to use the same quote
   characters in different quote types.
 
-Special Words
-^^^^^^^^^^^^^
+Special Words section
+~~~~~~~~~~~~~~~~~~~~~
 The `[specialwords]` section is used to single out words and phrases
 that you want to consistently format in some way throughout your
 document without having to repeatedly specify the markup. The name of
@@ -2956,8 +3198,8 @@ ones.
   `ten` only if they are not preceded by a backslash.
 
 [[X10]]
-Replacements
-^^^^^^^^^^^^
+Replacements section
+~~~~~~~~~~~~~~~~~~~~
 `[replacements]` and `[replacements2]` configuration file entries
 specify find and replace text and are formatted like:
 
@@ -2982,6 +3224,23 @@ macro name):
 - Replacements are performed in the same order they appear in the
   configuration file replacements section.
 
+Markup Template Sections
+~~~~~~~~~~~~~~~~~~~~~~~~
+Markup template sections supply backend markup for translating
+AsciiDoc elements.  Since the text is normally backend dependent
+you'll find these sections in the backend specific configuration
+files. Template sections differ from other sections in that they
+contain a single block of text instead of per line 'name=value'
+entries. A markup template section body can contain:
+
+- Attribute references
+- System macro calls.
+- A document content placeholder
+
+The document content placeholder is a single | character and is
+replaced by text from the source element.  Use the `\{brvbar}`
+attribute reference if you need a literal | character in the template.
+
 [[X27]]
 Configuration File Names and Locations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2993,7 +3252,8 @@ option).
 Implicit configuration files are loaded from the following directories
 in the following order:
 
-1. The `/etc/asciidoc` directory (if it exists).
+1. The global configuration directory (normally `/etc/asciidoc` or
+   `/usr/local/etc/asciidoc`) if it exists.
 2. The directory containing the asciidoc executable.
 3. The user's `$HOME/.asciidoc` directory (if it exists).
 4. The directory containing the AsciiDoc source file.
@@ -3111,7 +3371,7 @@ To delete (undefine) an attribute use the following syntax:
 
   :<name>!:
 
-.AttributeEntry properties
+.AttributeEntry behavior
 - The attribute entry line begins with colon -- no white space allowed
   in left margin.
 - AsciiDoc converts the `<name>` to a legal attribute name (lower
@@ -3120,9 +3380,9 @@ To delete (undefine) an attribute use the following syntax:
 - Leading and trailing white space is stripped from the `<value>`.
 - If the `<value>` is blank then the corresponding attribute value is
   set to an empty string.
-- Special characters in the entry `<value>` are substituted. To
-  include special characters use the predefined `\{gt}`, `\{lt}`,
-  `\{amp}` attribute references.
+- Special characters in the entry `<value>` are substituted. You can
+  enter special characters using character entity values, for example
+  `\&amp;`.
 - Attribute references contained in the entry `<value>` will be
   expanded.
 - By default AttributeEntry values are substituted for
@@ -3133,8 +3393,7 @@ To delete (undefine) an attribute use the following syntax:
   markup template substitution.
 - Attribute elements override configuration file and intrinsic
   attributes but do not override command-line attributes.
-
-Here's another example:
+Here are some more attribute entry examples:
 
 ---------------------------------------------------------------------
 AsciiDoc User Manual
@@ -3162,6 +3421,25 @@ the document's directory then it will be added verbatim to the DocBook
 header (see the `./doc/asciidoc-revhistory.xml` example that comes
 with the AsciiDoc distribution).].
 
+Setting configuration entries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A variant of the Attribute Entry syntax allows configuration file
+entries to be set from within an AsciiDoc document:
+
+  :<section_name>.<entry_name>: <entry_value>
+
+Where `<section_name>` is the configuration section name,
+`<entry_name>` is the name of the entry and `<entry_value>` is the
+optional entry value. This example sets the default labeled list style
+to 'horizontal':
+
+  :listdef-labeled.style: horizontal
+
+It is exactly equivalent to a configuration file containing:
+
+  [listdef-labeled]
+  style=horizontal
+
 [[X62]]
 .Attribute entries promote clarity and eliminate repetition
 *********************************************************************
@@ -3171,12 +3449,13 @@ compounded by redundancy if the same name is used repeatedly.
 Attribute entries can be used to make your documents easier to read
 and write, here are some examples:
 
-  :1:        http://freshmeat.net/projects/asciidoc/
-  :homepage: http://hg.sharesource.org/asciidoc/[AsciiDoc home page]
-  :new:      image:./images/smallnew.png[]
+  :1:         http://freshmeat.net/projects/asciidoc/
+  :homepage:  http://hg.sharesource.org/asciidoc/[AsciiDoc home page]
+  :new:       image:./images/smallnew.png[]
+  :footnote1: footnote:[A meaningless latin term]
 
   Using previously defined attributes: See the {1}[Freshmeat summary]
-  or the {homepage} for something new {new}.
+  or the {homepage} for something new {new}. Lorem ispum {footnote1}.
 
 .Note
 - The attribute entry definition must precede it's usage.
@@ -3193,20 +3472,29 @@ Attribute Lists
 ---------------
 An attribute list is a comma separated list of attribute values. The
 entire list is enclosed in square brackets.  Attribute lists are used
-to pass parameters to macros, blocks and inline quotes.
+to pass parameters to macros, blocks and inline quotes:
+
+- The list consists of zero or more positional attribute values
+  followed by zero or more named attribute values.
+- Attribute values are enclosed in quotation mark (") characters.
+- If the attribute list only contains positional attribute values and
+  the values contain no commas then quoting is unnecessary.
 
-The list consists of zero or more positional attribute values followed
-by zero or more named attribute values. Here are three examples:
+Here are three examples (a single unquoted positional attribute; three
+unquoted attribute values; one positional attribute followed by two
+named attributes):
 
   [Hello]
   [quote, Bertrand Russell, The World of Mathematics (1956)]
   ["22 times", backcolor="#0e0e0e", options="noborders,wide"]
 
-.Attribute list properties
+.Attribute list behavior
 - If one or more attribute values contains a comma the all values must
   be quoted (enclosed in quotation characters).
-- If the list contains any named attributes the all string attribute
-  values must be quoted.
+- If the list contains any named or quoted attributes then all string
+  attribute values must be quoted.
+- To include a quotation mark (") character in a quoted attribute
+  value the the quotation mark must be escaped with a backslash.
 - List attributes take precedence over existing attributes.
 - List attributes can only be referenced in configuration file markup
   templates and tags, they are not available inside the document.
@@ -3215,15 +3503,28 @@ by zero or more named attribute values. Here are three examples:
 - Positional attributes are referred to as `\{1}`,`\{2}`,`\{3}`,...
 - Attribute `\{0}` refers to the entire list (excluding the enclosing
   square brackets).
-- If an attribute named `options` is present it is processed as a
-  comma separated list of attributes with zero length string values.
-  For example `[options="opt1,opt2,opt3"]` is equivalent to
-  `[opt1="",opt2="",opt2=""]`.
 - Attribute lists are evaluated as a list of Python function
   arguments.  If this fails or any of the items do not evaluate to a
   string, a number or None then all list items are treated as string
   literals.
 
+[[X75]]
+Options attribute
+~~~~~~~~~~~~~~~~~
+If the attribute list contains an attribute named `options` it is
+processed as a comma separated list of option names:
+
+- Each name generates an attribute named like `<option>-option` (where
+  `<option>` is the option name) with an empty string value.  For
+  example `[options="opt1,opt2,opt3"]` is equivalent to setting the
+  following three attributes
+  `[opt1-option="",opt2-option="",opt2-option=""]`.
+- If you define a an option attribute globally (for example with an
+  <<X18,attribute entry>>) then it will apply to all elements in the
+  document.
+- AsciiDoc implements a number of predefined options which are listed
+  in the <<X74,Attribute Options appendix>>.
+
 Macro Attribute lists
 ~~~~~~~~~~~~~~~~~~~~~
 Macros calls are suffixed with an attribute list. The list may be
@@ -3232,10 +3533,10 @@ attribute values to macro markup templates.
 
 AttributeList Element
 ~~~~~~~~~~~~~~~~~~~~~
-An attribute list on a line by itself constitutes an 'AttributeList'
-block element, its function is to parametrize the following block
-element. The list attributes are passed to the next block element for
-markup template substitution.
+An <<X21,attribute list>> on a line by itself constitutes an
+'AttributeList' block element, its attributes apply to the following
+block element.  The list attributes are passed to the next block
+element for markup template substitution.
 
 
 Attribute References
@@ -3384,7 +3685,9 @@ command-line arguments, execution parameters along with attributes
 defined in the default configuration files.  Here's the list of
 predefined intrinsic attributes:
 
+  {amp}                 ampersand (&) character
   {asciidoc-dir}        the asciidoc(1) application directory
+  {asciidoc-file}       the full path name of the asciidoc(1) script
   {asciidoc-version}    the version of asciidoc(1)
   {author}              author's full name
   {authored}            empty string '' if {author} or {email} defined,
@@ -3392,6 +3695,7 @@ predefined intrinsic attributes:
   {backend-<backend>}   empty string ''
   {<backend>-<doctype>} empty string ''
   {backend}             document backend specified by `-b` option
+  {backslash}           backslash character
   {basebackend-<base>}  empty string ''
   {basebackend}         html or docbook
   {brvbar}              broken vertical bar (|) character
@@ -3402,6 +3706,7 @@ predefined intrinsic attributes:
   {doctype}             document type specified by `-d` option
   {email}               author's email address (from document header)
   {empty}               empty string ''
+  {encoding}            specifies input and output encoding
   {filetype-<fileext>}  empty string ''
   {filetype}            output file name file extension
   {firstname}           author first name (from document header)
@@ -3419,11 +3724,14 @@ predefined intrinsic attributes:
   {mantitle}            document title minus the manpage volume number
   {manvolnum}           manpage volume number (1..8) (from document header)
   {middlename}          author middle name (from document header)
+  {nbsp}                Non-breaking space entity
   {outdir}              document output directory name (note 1)
   {outfile}             output file name (note 1)
   {revision}            document revision number (from document header)
   {sectnum}             section number (in section titles)
   {title}               section title (in titled elements)
+  {two_colons}          Two colon characters.
+  {two_semicolons}      Two semicolon characters.
   {user-dir}            the ~/.asciidoc directory (if it exists)
   {verbose}             defined as '' if --verbose command option specified
 
@@ -3447,6 +3755,7 @@ predefined intrinsic attributes:
    contents are written.]
 
 
+[[X73]]
 Block Element Definitions
 -------------------------
 The syntax and behavior of Paragraph, DelimitedBlock, List and Table
@@ -3480,7 +3789,10 @@ template::
   parameters instead of a single template.
 
 options::
-  A comma delimited list of element specific option names.
+  A comma delimited list of element specific option names. In addition
+  to being used internally, options are available during markup tag
+  and template substitution as attributes with an empty string value
+  named like `<option>-option` (where `<option>` is the option name).
 
 subs, presubs, postsubs::
   * 'presubs' and 'postsubs' are lists of comma separated substitutions that are
@@ -3489,9 +3801,9 @@ subs, presubs, postsubs::
 
   * 'subs' is an alias for 'presubs'.
 
-  * If a 'filter' is allowed (Paragraphs and DelimitedBlocks) and has
-    been specified then 'presubs' and 'postsubs' substitutions are
-    performed before and after the filter is run respectively.
+  * If a 'filter' is allowed (Paragraphs, DelimitedBlocks and Tables)
+    and has been specified then 'presubs' and 'postsubs' substitutions
+    are performed before and after the filter is run respectively.
 
   * Allowed values: 'specialcharacters', 'quotes', 'specialwords',
     'replacements', 'macros', 'attributes', 'callouts'.
@@ -3503,7 +3815,7 @@ subs, presubs, postsubs::
     'normal';;
         The following substitutions:
         'specialcharacters','quotes','attributes','specialwords',
-        'replacements','macros','passthroughs'.
+        'replacements','macros'.
     'verbatim';;
         'specialcharacters' and 'callouts' substitutions.
 
@@ -3516,8 +3828,8 @@ subs, presubs, postsubs::
 
 filter::
   This optional entry specifies an executable shell command for
-  processing block content (Paragraphs and DelimitedBlocks). The
-  filter command can contain attribute references.
+  processing block content (Paragraphs, DelimitedBlocks and Tables).
+  The filter command can contain attribute references.
 
 posattrs::
   Optional comma separated list of positional attribute names. This
@@ -3545,7 +3857,7 @@ Styles
 A style is a set of block attributes bundled as a single named
 attribute. The following example defines a style named 'verbatim':
 
-  verbatim-style=template="literalblock",subs="verbatim",font="monospaced"
+  verbatim-style=template="literalblock",subs="verbatim"
 
 - All style parameter names must be suffixed with `-style` and the
   style parameter value is in the form of a list of <<X21,named
@@ -3586,9 +3898,9 @@ delimiter::
   blank line, the end of file, or the start of a DelimitedBlock.
 
 options::
-  The only allowable option is 'listelement'.  The 'listelement'
-  option specifies that paragraphs of this type will automatically be
-  considered part of immediately preceding list items.
+  The 'listelement' option specifies that paragraphs of this type will
+  automatically be considered part of immediately preceding list
+  items.
 
 .Paragraph processing proceeds as follows:
 1. The paragraph text is aligned to the left margin.
@@ -3604,19 +3916,16 @@ options::
 
 Delimited Blocks
 ~~~~~~~~~~~~~~~~
-DelimitedBlock specific block definition notes:
-
-options::
-  Allowed values are:
+DelimitedBlock 'options' values are:
 
-  'sectionbody';;
-      The block contents are processed as a SectionBody.
+sectionbody::
+    The block contents are processed as a SectionBody.
 
-  'skip';;
-      The block is treated as a comment (see 'CommentBlocks').
+skip::
+    The block is treated as a comment (see CommentBlocks).
 
-  'list';;
-      The block is a <<X29,list block>>.
+list::
+    The block is a <<X29,list block>>.
 
 'presubs', 'postsubs' and 'filter' entries are meaningless when
 'sectionbody', 'skip' or 'list' options are set.
@@ -3650,47 +3959,24 @@ type::
 
 delimiter::
   A Python regular expression that matches the first line of a
-  list element entry. This expression must contain the named
-  group 'text' which matches text in the first line.
-
-subs::
-  Substitutions that are performed on list item text and terms.
-
-listtag::
-  The name of the tag that envelopes the List.
-
-itemtag::
-  The name of the tag that envelopes the ListItem.
-
-texttag::
-  The name of the tag that envelopes the list item text.
-
-labeltag::
-  The name of the tag that envelopes a variable list label.
+  list element entry. This expression can contain the named groups
+  'text' (bulleted groups), 'index' and 'text' (numbered lists),
+  'label' and 'text' (labeled lists).
 
-entrytag::
-  The name of the tag that envelopes a labeled list entry.
-
-The tag entries map the AsciiDoc list structure to backend markup; see
-the AsciiDoc distribution `.conf` configuration files for examples.
+tags::
+  The `<name>` of the `[listtags-<name>]` configuration file section
+  containing list markup tag definitions.  The tag entries ('list',
+  'entry', 'label', 'term', 'text') map the AsciiDoc list structure to
+  backend markup; see the 'listtags' sections in the AsciiDoc
+  distributed backend `.conf` configuration files for examples.
 
 Tables
 ~~~~~~
-Table behavior and syntax is determined by `[tabledef*]` configuration
-file sections. The user can change existing list behavior and add new
-list types by editing configuration files.
-
-Table specific block definition notes:
-
-fillchar::
-  A single character that fills table ruler and underline
-  lines.
-
-subs::
-  Substitutions performed on table data items.
-
-format::
-  The source row data format ('fixed', 'csv' or 'dsv').
+Table behavior and syntax is determined by `[tabledef*]` and
+`[tabletags*]` configuration file sections. The user can change
+existing table behavior and add new table types by editing
+configuration files.  The following `[tabledef*]` section entries
+generate table output markup elements:
 
 comspec::
   The table 'comspec' tag definition.
@@ -3705,18 +3991,18 @@ headdata, footdata, bodydata::
   'footdata' table definition entries default to 'bodydata' if they
   are undefined.
 
+paragraph::
+  If the 'paragraph' tag is specified then blank lines in the cell
+  data are treated as paragraph delimiters and marked up using this
+  tag.
+
 [[X4]]
 Table behavior is also influenced by the following `[miscellaneous]`
 configuration file entries:
 
-textwidth::
-  The page width (in characters) of the source text. This setting is
-  compared to the table ruler width when calculating the relative
-  size of character ruler tables on the output page.
-
 pagewidth::
-  This integer value is the printable width of the output media.  Used
-  to calculate 'colwidth' and 'tablewidth' substitution values.
+  This integer value is the printable width of the output media. See
+  <<X69,table attributes>>.
 
 pageunits::
   The units of width in output markup width attribute values.
@@ -3727,9 +4013,10 @@ pageunits::
   most XML table schema.
 - Table definitions can be ``mixed in'' from multiple cascading
   configuration files.
-- New table definitions inherit the default table definition
-  ('[tabledef-default]') so you only need to override those conf file
-  entries that require modification when defining a new table type.
+- New table definitions inherit the default table and table tags
+  definitions (`[tabledef-default]` and `[tabletags-default]`) so you
+  only need to override those conf file entries that require
+  modification.
 
 
 [[X59]]
@@ -3751,9 +4038,6 @@ WARNING: Filters can potentially generate unsafe output. Before
 installing a filter you should verify that it can't be coerced into
 generating malicious output or exposing sensitive information.
 
-NOTE: Filter functionality is currently only available on POSIX
-platforms (this includes Cygwin).
-
 Filter Search Paths
 ~~~~~~~~~~~~~~~~~~~
 If the filter command does not specify a directory path then
@@ -3794,19 +4078,21 @@ it's much to simplistic to be passed off as a code syntax highlighter.
 If you want a full featured multi-language highlighter use the
 <<X57,Source Code Highlighter Filter>>.
 
-  .Code filter example
-  [code,python]
-  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  ''' A multi-line
-      comment.'''
-  def sub_word(mo):
-      ''' Single line comment.'''
-      word = mo.group('word')   # Inline comment
-      if word in keywords[language]:
-          return quote + word + quote
-      else:
-          return word
-  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------------------
+.Code filter example
+[code,python]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+''' A multi-line
+    comment.'''
+def sub_word(mo):
+    ''' Single line comment.'''
+    word = mo.group('word')   # Inline comment
+    if word in keywords[language]:
+        return quote + word + quote
+    else:
+        return word
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------------------
 
 Outputs:
 
@@ -3868,9 +4154,9 @@ associated with generating and sequencing the toolchain commands and
 managing intermediate and output files.  a2x(1) also optionally
 deploys admonition and navigation icons and a CSS stylesheet. See the
 `a2x(1)` man page for more details. All you need is
-<<X40,xsltproc(1)>>, <<X13,DocBook XSL Stylesheets>> and, optionally
-<<X31,dblatex>> or <<X14,FOP>> (if you want PDF), or `lynx(1)` (if you
-want text).
+<<X40,xsltproc(1)>>, <<X13,DocBook XSL Stylesheets>> and optionally:
+<<X31,dblatex>> or <<X14,FOP>> (if you want PDF); `w3m(1)` or
+`lynx(1)` (if you want text).
 
 The following examples generate `doc/source-highlight-filter.pdf` from
 the AsciiDoc `doc/source-highlight-filter.txt` source file. The first
@@ -3878,7 +4164,7 @@ 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-options="" doc/source-highlight-filter.txt
+  $ a2x -f pdf --fop doc/source-highlight-filter.txt
 
 See the `a2x(1)` man page for details.
 
@@ -4052,8 +4338,8 @@ composing your own configuration file `[header]` section).
 TIP: If you get an 'undefined entity' error when processing DocBook
 files you'll may find that you've used an undefined HTML character
 entity.  An easy (although inelegant) fix is to use the character's
-character code instead of its symbolic name (for example use `&#160;`
-instead of `&nbsp;`).
+character code instead of its symbolic name (for example use `\&#160;`
+instead of `\&nbsp;`).
 
 If your system has been configured with an XML catalog you may find a
 number of entity sets are already automatically included.
@@ -4070,7 +4356,7 @@ Non-standard fonts should be embedded in the distributed document.
 [[X36]]
 Help Commands
 -------------
-The asciidoc(1) command has a `\--help` option which prints help topics
+The asciidoc(1) command has a `--help` option which prints help topics
 to stdout. The default topic summarizes asciidoc(1) usage:
 
   $ asciidoc --help
@@ -4101,7 +4387,7 @@ The help topic files have the same named section format as other
 same locations and loaded in the same order as other configuration
 files.
 
-When the `\--help` command-line option is specified AsciiDoc loads the
+When the `--help` command-line option is specified AsciiDoc loads the
 appropriate help files and then prints the contents of the section
 whose name matches the help topic name.  If a topic name is not
 specified `default` is used. You don't need to specify the whole help
@@ -4141,9 +4427,9 @@ Execute `:help gq` command to read about the vim gq command.
 =====================================================================
 - Assign the `gq}` command to the Q key with the `nnoremap Q gq}`
   command or put it in your `\~/.vimrc` file to so it's always
-  available (see the <<X61, Example `\~/.vimrc` file>>).
-- Put `set` commands in your `\~/.vimrc` file so you don't have to
-  enter them manually <<X61, Example `\~/.vimrc` file>>).
+  available (see the <<X61, Example `~/.vimrc` file>>).
+- Put `set` commands in your `~/.vimrc` file so you don't have to
+  enter them manually.
 - The Vim website (http://www.vim.org) has a wealth of resources,
   including scripts for automated spell checking and ASCII Art
   drawing.
@@ -4152,9 +4438,9 @@ Execute `:help gq` command to read about the vim gq command.
 
 Format Lists
 ^^^^^^^^^^^^
-The `gq` command can also be used to format bulleted and numbered
-lists. First you need to set the `comments` and `formatoptions` (see
-the <<X61, Example `\~/.vimrc` file>>).
+The `gq` command can also be used to format bulleted, numbered and
+callout lists. First you need to set the `comments`, `formatoptions`
+and `formatlistpat` (see the <<X61, Example `~/.vimrc` file>>).
 
 Now you can format simple lists that use dash, asterisk, period and
 plus bullets along with numbered ordered lists:
@@ -4168,8 +4454,8 @@ Indent whole paragraphs by indenting the fist line with the desired
 indent and then executing the `gq}` command.
 
 [[X61]]
-Example `\~/.vimrc` File
-^^^^^^^^^^^^^^^^^^^^^^^^
+Example `~/.vimrc` File
+^^^^^^^^^^^^^^^^^^^^^^^
 ---------------------------------------------------------------------
 " Show tabs and trailing characters.
 set listchars=tab:»·,trail:·
@@ -4191,6 +4477,7 @@ nnoremap W :%s/[\r \t]\+$//<CR>:set et<CR>:retab!<CR>
 autocmd BufRead,BufNewFile *.txt,README,TODO,CHANGELOG,NOTES
         \ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2
         \ textwidth=70 wrap formatoptions=tcqn
+        \ formatlistpat=^\\s*<\\?\\d\\+[\\]:.)}\\t\ >]\\s*
         \ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:>
 ---------------------------------------------------------------------
 
@@ -4245,12 +4532,6 @@ Ambiguous ordered list items::
 The 'list item out of sequence' warning makes it unlikely that this
 problem will go unnoticed.
 
-Escaping inside DSV table data::
-    Delimiter separated text uses C style backslash escape sequences.
-    If you want to enter a backslash (for example, to escape AsciiDoc
-    text formatting or an inline macro) you need to escape it by
-    entering two backslashes.
-
 Special characters in attribute values::
     Special character substitution precedes attribute substitution so
     if attribute values contain special characters you may, depending
@@ -4427,7 +4708,7 @@ to using style sheets.
 Closing Open Sections
 ~~~~~~~~~~~~~~~~~~~~~
 You can close off section tags up to level `N` by calling the
-`\eval::[Section.setlevel(N)]` system macro. This is useful if you
+`eval::[Section.setlevel(N)]` system macro. This is useful if you
 want to include a section composed of raw markup. The following
 example includes a DocBook glossary division at the top section level
 (level 0):
@@ -4467,20 +4748,21 @@ formed.
 
 Glossary
 --------
-[[X8]] Block element:-
+[glossary]
+[[X8]] Block element::
     An AsciiDoc block element is a document entity composed of one or
     more whole lines of text.
 
-[[X34]] Inline element:-
+[[X34]] Inline element::
     AsciiDoc inline elements occur within block element textual
     content, they perform formatting and substitution tasks.
 
-Formal element:-
+Formal element::
     An AsciiDoc block element that has a BlockTitle. Formal elements
     are normally listed in front or back matter, for example lists of
     tables, examples and figures.
 
-Verbatim element:-
+Verbatim element::
     The word verbatim indicates that white space and line breaks in
     the source document are to be preserved in the output document.
 
@@ -4495,11 +4777,11 @@ Version 7 to version 8
   matched text with backslashes.
 - The index entry inline macro syntax has changed -- if your documents
   include indexes you may need to edit them.
-- Replaced a2x(1) `\--no-icons` and `\--no-copy` options with their
-  negated equivalents: `\--icons` and `\--copy` respectively. The
+- Replaced a2x(1) `--no-icons` and `--no-copy` options with their
+  negated equivalents: `--icons` and `--copy` respectively. The
   default behavior has also changed -- the use of icons and copying of
-  icon and CSS files must be specified explicitly with the `\--icons`
-  and `\--copy` options.
+  icon and CSS files must be specified explicitly with the `--icons`
+  and `--copy` options.
 
 The rationale for the changes can be found in the AsciiDoc
 `CHANGELOG`.
@@ -4509,78 +4791,13 @@ constrained quotes syntax and the new index entry syntax then you can
 define the attribute `asciidoc7compatible` (for example by using the
 `-a asciidoc7compatible` command-line option).
 
-[[X32]]
-Version 6 to version 7
-~~~~~~~~~~~~~~~~~~~~~~
-The changes that affect the most users relate to renamed and
-deprecated backends and command-line syntax:
-
-. The 'html' backend has been renamed 'html4'.
-. The 'xhtml' backend has been deprecated to 'xhtml-deprecated' (use
-  the new 'xhtml11' backend in preference).
-. The use of CSS specific `css` and `css-embedded` backends has been
-  dropped in favor of using attributes (see the table below and
-  <<X33,xhtml backend attributes>>).
-. Deprecated features that emitted warnings in prior versions are no
-  longer tolerated.
-. The command-line syntax for deleting (undefining) an attribute has
-  changed from `-a ^name` to `-a name!`.
-
-.Equivalent command-line syntax
-[grid="all"]
-```~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Version 6 (old),Version 7 (new),Version 7 (backward compatible)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--b html,-b html4,-b html4
--b css,-b xhtml11 -a linkcss -a icons,-b xhtml-deprecated -a css -a linkcss -a icons
--b css-embedded,-b xhtml11 -a icons,-b xhtml-deprecated -a css -a icons
--b xhtml,-b xhtml11,-b xhtml-deprecated
--b docbook-sgml,-b docbook -a sgml,-b docbook -a sgml
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you've customized version 6 distribution stylesheets then you'll
-need to either bring them in line with the new
-`./stylesheets/xhtml11*.css` class and id names or stick with the
-backward compatible `xhtml-deprecated` backend.
-
-Changes to configuration file syntax:
-
-. To undefine an attribute in the `[attributes]` section use `name!`
-  instead of `name` (`name` now sets that attribute to a blank
-  string).
-
-
 [[X38]]
 Appendix B: Packager Notes
 ---------------------------
 Read the `README` and `INSTALL` files (in the distribution root
-directory) for install prerequisites and procedures.
-
-The distribution `install.sh` shell script is the canonical
-installation procedure and is the definitive installation description.
-Here's a summary of the installation procedure:
-
-- Unpack entire distribution tarball to `/usr/share/asciidoc/`.
-- Move `asciidoc.py` to `/usr/bin/`; rename to `asciidoc`; if
-  necessary modify shebang line; ensure executable permissions are
-  set.
-- Move `a2x` to `/usr/bin/`; if necessary modify shebang line; ensure
-  executable permissions are set.
-- Move the `./*.conf` files to `/etc/asciidoc/`.
-- Move `./filters/{\*.conf,*.py}` to `/etc/asciidoc/filters/`.
-- Move `./docbook-xsl/*.xsl` to `/etc/asciidoc/docbook-xsl/`.
-- Move `./dblatex/*.{xsl,sty}` to `/etc/asciidoc/dblatex/`.
-- Copy `./stylesheets/*.css` to `/etc/asciidoc/stylesheets/`.
-- Copy `./javascripts/*.js` to `/etc/asciidoc/javascripts/`.
-- Copy `./images/icons/*` to `/etc/asciidoc/images/icons/`
-  (recursively including the `icons` subdirectory and its contents).
-- Compress the asciidoc(1) and ax2(1) man pages (`./doc/*.1`) with
-  gzip(1) and move them to `/usr/share/man/man1/`.
-- If Vim is installed then install Vim syntax and filetype detection
-  files.
-
-Leaving stylesheets and images in `/usr/share/asciidoc/` ensures the
-docs and example website are not broken.
+directory) for install prerequisites and procedures.  The distribution
+`Makefile.in` (used by `configure` to generate the `Makefile`) is the
+canonical installation procedure.
 
 
 [[X39]]
@@ -4646,43 +4863,7 @@ you need to be aware of:
   format.
 
 
-Appendix E: ASCIIMathML Support
--------------------------------
-http://www1.chapman.edu/~jipsen/mathml/asciimath.html[ASCIIMathML] is
-a clever JavaScript written by Peter Jipsen that transforms
-mathematical formulae written in plain text to standard mathematical
-notation on an HTML page.
-
-To enable ASCIIMathML support on the `xhtml11` backend include the `-a
-asciimath` command-line option. Here's what the `asciimath` attribute
-does:
-
-- Embeds the `ASCIIMathML.js` script in the output document (links it
-  if `-a linkcss` has been specified).
-- Escapes ASCIIMathML delimiters.
-
-When entering ASCIIMathML formulas you *must* enclose them inside
-<<X50,double-dollar passthroughs>> (this is necessary because
-ASCIIMathML characters clash with AsciiDoc formatting characters). The
-double-dollar passthrough has the bonus of also escaping special
-characters so the output document is valid XHTML. You can see an
-ASCIIMathML example at
-http://www.methods.co.nz/asciidoc/asciimath.html, the same example
-can be found in the AsciiDoc distribution `./doc` directory.
-
-[NOTE]
-=====================================================================
-- See the
-  http://www1.chapman.edu/~jipsen/mathml/asciimath.html[ASCIIMathML]
-  website for ASCIIMathML documentation and the latest version.
-- If you use Mozilla you need to install the
-  http://www.mozilla.org/projects/mathml/fonts/[required math fonts].
-- If you use Microsoft Internet Explorer 6 you need to install
-  http://www.dessci.com/en/products/mathplayer/[MathPlayer].
-=====================================================================
-
-
-Appendix F: Vim Syntax Highlighter
+Appendix E: Vim Syntax Highlighter
 ----------------------------------
 The AsciiDoc `./vim/` distribution directory contains Vim syntax
 highlighter and filetype detection scripts for AsciiDoc.  Syntax
@@ -4718,17 +4899,8 @@ around the problems:
   preceding blank lines, or putting a list continuation character
   (`+`) in the preceding blank line.
 
-- Nested text formatting is highlighted according to the outer format.
-
-- Most escaped inline elements will be highlighted.
-
-- Unterminated quotes are highlighted, for example `'tis` would be
-  seen as the start of emphasized text. As a damage control measure
-  quoted text and macro attribute list containing quoted text  always
-  terminate at a blank line. This problem is usually ameliorated by
-  the fact that characters such as `\~`, `+`, `^` and `_` will
-  normally occur inside monospaced quotes (unless they are used for
-  quoting), for example `~/projects`.
+- Nested quoted text formatting is highlighted according to the outer
+  format.
 
 - If a closing block delimiter is not preceded by a blank line it is
   sometimes mistaken for a title underline. A workaround is to insert
@@ -4737,9 +4909,6 @@ around the problems:
 - If a list block delimiter is mistaken for a title underline precede
   it with a blank line.
 
-- Tables are terminated by a blank line -- use a space character on
-  blank lines within your table.
-
 - Lines within a paragraph beginning with a period will be highlighted
   as block titles. For example:
 
@@ -4755,3 +4924,37 @@ that appear blank but contain white space characters -- setting your
 editor options so that white space characters are visible is a good
 idea.
 
+
+[[X74]]
+Appendix F: Attribute Options
+-----------------------------
+Here is the list of predefined <<X75,attribute list options>>:
+
+
+[cols="2,2,2,5",options="header"]
+|====================================================================
+|Option|Backends|AsciiDoc Elements|Description
+
+|compact |docbook, xhtml11 |bulleted list, numbered list|
+Minimizes vertical space in the list
+
+|strong |xhtml11,html4 |labeled lists|
+Emboldens label text.
+
+|footer |docbook, xhtml11, html4 |table|
+The last row of the table is rendered as a footer.
+
+|header |docbook, xhtml11, html4 |table|
+The first row of the table is rendered as a header.
+
+|breakable, unbreakable |docbook (XSL/FO) |table|
+The 'breakable' options allows the table to break across page
+boundaries (the default behavior); 'unbreakable' attempts to keep the
+table together on a single page. If neither option is specified the
+default XSL stylesheet behavior prevails.
+
+|pgwide |docbook (XSL/FO) |table, block image, horizontal labeled list|
+Specifies that the element should be rendered across the full text
+width of the page irrespective of the current indentation.
+
+|====================================================================