mizuho 0.9.10 → 0.9.11

data/asciidoc/doc/asciidoc.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 1057 
+personal_ws-1.1 en 1078 
 mandoc
 colspecs
 API
@@ -41,6 +41,7 @@ vulputate
 Odio
 doctest
 comspecs
+MacDermid
 amet
 Oleksandr
 ExampleBlock
@@ -72,6 +73,7 @@ Potapov
 nisl
 Gao
 nullam
+LibreOffice
 Moolenaar
 Habitasse
 mimetypes
@@ -110,6 +112,7 @@ strongwords
 setlocal
 ListingBlock
 listingblock
+formalpara
 Posuere
 exe
 AuthorInfo
@@ -117,6 +120,7 @@ hhk
 vsides
 rewriteSystem
 taoup
+paracounter
 hhp
 listelement
 AttributeLists
@@ -177,6 +181,7 @@ systemIdStartString
 footnoteref
 joe
 velit
+truecolor
 p�re
 pere
 purus
@@ -188,6 +193,7 @@ filetype
 listnumber
 SourceForge
 groff
+McCurry
 mansource
 JRE
 verear
@@ -213,6 +219,7 @@ articleinfo
 auctor
 refname
 mim
+Paillotin
 Farhat
 uninstall
 localdate
@@ -291,6 +298,7 @@ AsciiMathML
 asciimathml
 conf
 RCS
+lowriter
 UnicodeDecodeError
 CalloutList
 SidebarBlocks
@@ -340,6 +348,7 @@ adolescens
 qui
 htmltoc
 SJR
+noautoload
 biggy
 pgwide
 RevisionDate
@@ -422,10 +431,12 @@ undefines
 Andr�s
 yellowback
 Quisque
+Fabrice
 htmlhelp
 HTMLHelp
 cellspacing
 Citeaux
+themedir
 srackham
 Lulea
 Lule�
@@ -483,6 +494,7 @@ xyz
 simpara
 lf
 defacto
+resized
 mb
 IndentedBlocks
 js
@@ -521,10 +533,12 @@ td
 px
 vivamus
 py
+Helleu
 getElementById
 addon
 th
 ru
+sp
 docname
 ifeval
 uk
@@ -534,6 +548,7 @@ autolabel
 LinuxDoc
 linuxdoc
 tt
+Hackett
 VM
 Fr�d�rique
 SidebarBlock
@@ -577,6 +592,7 @@ BlockTitle
 blocktitle
 blocktitles
 BlockTitles
+Iisaka
 tfoot
 Iisaka's
 misevaluations
@@ -760,8 +776,8 @@ pagebreak
 VariableList
 LiteralBlocks
 Donec
-dbook
 BLONP
+dbook
 asciimath
 interesset
 pellentesque
@@ -871,6 +887,7 @@ bodyrow
 navMap
 listtags
 mauris
+Wiers
 ListingBlocks
 TableUnderline
 bookinfo
@@ -936,6 +953,7 @@ RevisionInfo
 Berglunds
 egestas
 nabc
+autoloaded
 symlinked
 Sommer
 Klum
@@ -973,8 +991,10 @@ authorinitials
 JavaScripts
 javascripts
 undefining
+viewport
 leveloffset
 CustomBlock
+Kr�mer
 BufRead
 specialwords
 libexslt
@@ -1016,6 +1036,7 @@ Freshmeat
 dbhtml
 manversion
 TableBody
+Lo�c
 abc
 aliquam
 llevar

data/asciidoc/doc/asciidoc.txt

@@ -201,8 +201,27 @@ configuration file:
   backend-alias-html=xhtml11
   backend-alias-docbook=docbook45
 
+[[X100]]
+Backend Plugins
+~~~~~~~~~~~~~~~
+The asciidoc(1) `--backend` option is also used to install and manage
+backend <<X101,plugins>>.
+
+- A backend plugin is used just like the built-in backends.
+- Backend plugins <<X27,take precedence>> over built-in backends with
+  the same name.
+- You can use the `{asciidoc-confdir}` <<X60, intrinsic attribute>> to
+  refer to the built-in backend configuration file location from
+  backend plugin configuration files.
+- You can use the `{backend-confdir}` <<X60, intrinsic attribute>> to
+  refer to the backend plugin configuration file location.
+- By default backends plugins are installed in
+  `$HOME/.asciidoc/backends/<backend>` where `<backend>` is the
+  backend name.
+
+
 DocBook
-~~~~~~~
+-------
 AsciiDoc generates 'article', 'book' and 'refentry'
 http://www.docbook.org/[DocBook] documents (corresponding to the
 AsciiDoc 'article', 'book' and 'manpage' document types).
@@ -215,45 +234,225 @@ JavaHelp and text.  There are also programs that allow you to view
 DocBook files directly, for example http://live.gnome.org/Yelp[Yelp]
 (the GNOME help viewer).
 
-[[X35]]
-HTML Stylesheets
-~~~~~~~~~~~~~~~~
-The 'xhtml11' and 'html5' backends include or link CSS files into
-their outputs.  The CSS2 stylesheets are located in the distribution
-`./stylesheets/` directory.
+[[X12]]
+Converting DocBook to other file formats
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+DocBook files are validated, parsed and translated various
+presentation file formats using a combination of applications
+collectively called a DocBook 'tool chain'. The function of a tool
+chain is to read the DocBook markup (produced by AsciiDoc) and
+transform it to a presentation format (for example HTML, PDF, HTML
+Help, EPUB, DVI, PostScript, LaTeX).
+
+A wide range of user output format requirements coupled with a choice
+of available tools and stylesheets results in many valid tool chain
+combinations.
+
+[[X43]]
+a2x Toolchain Wrapper
+~~~~~~~~~~~~~~~~~~~~~
+One of the biggest hurdles for new users is installing, configuring
+and using a DocBook XML toolchain. `a2x(1)` can help -- it's a
+toolchain wrapper command that will generate XHTML (chunked and
+unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text
+file outputs from an AsciiDoc text file.  `a2x(1)` does all the grunt
+work associated with generating and sequencing the toolchain commands
+and managing intermediate and output files.  `a2x(1)` also optionally
+deploys admonition and navigation icons and a CSS stylesheet. See the
+`a2x(1)` man page for more details. In addition to `asciidoc(1)` you
+also need <<X40,xsltproc(1)>>, <<X13,DocBook XSL Stylesheets>> and
+optionally: <<X31,dblatex>> or <<X14,FOP>> (to generate PDF);
+`w3m(1)` or `lynx(1)` (to generate text).
 
-`./stylesheets/asciidoc.css`::
-    The main stylesheet.
+The following examples generate `doc/source-highlight-filter.pdf` from
+the AsciiDoc `doc/source-highlight-filter.txt` source file. The first
+example uses `dblatex(1)` (the default PDF generator) the second
+example forces FOP to be used:
 
-`./stylesheets/asciidoc-manpage.css`::
-    Tweaks for manpage document type generation.
+  $ a2x -f pdf doc/source-highlight-filter.txt
+  $ a2x -f pdf --fop doc/source-highlight-filter.txt
 
-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` instead of the default
-stylesheets.
+See the `a2x(1)` man page for details.
 
-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`.
+TIP: Use the `--verbose` command-line option to view executed
+toolchain commands.
 
-[[X99]]
-HTML Stylesheets and JavaScript file locations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-'xhtml11' and 'html5' backends use CSS stylesheets and JavaScripts.
-CSS and JavaScript files are either embedded in the output document
-(when it is generated by AsciiDoc) or linked to the output document
-(when it is viewed).
-
-- If the AsciiDoc 'linkcss' attribute is defined CSS and JavaScript
-  files are linked otherwise they are embedded (the default behavior).
+HTML generation
+~~~~~~~~~~~~~~~
+AsciiDoc produces nicely styled HTML directly without requiring a
+DocBook toolchain but there are also advantages in going the DocBook
+route:
+
+- HTML from DocBook can optionally include automatically generated
+  indexes, tables of contents, footnotes, lists of figures and tables.
+- DocBook toolchains can also (optionally) generate separate (chunked)
+  linked HTML pages for each document section.
+- Toolchain processing performs link and document validity checks.
+- If the DocBook 'lang' attribute is set then things like table of
+  contents, figure and table captions and admonition captions will be
+  output in the specified language (setting the AsciiDoc 'lang'
+  attribute sets the DocBook 'lang' attribute).
+
+On the other hand, HTML output directly from AsciiDoc is much faster,
+is easily customized and can be used in situations where there is no
+suitable DocBook toolchain (for example, see the {website}[AsciiDoc
+website]).
+
+PDF generation
+~~~~~~~~~~~~~~
+There are two commonly used tools to generate PDFs from DocBook,
+<<X31,dblatex>> and <<X14,FOP>>.
+
+.dblatex or FOP?
+- 'dblatex' is easier to install, there's zero configuration
+  required and no Java VM to install -- it just works out of the box.
+- 'dblatex' source code highlighting and numbering is superb.
+- 'dblatex' is easier to use as it converts DocBook directly to PDF
+  whereas before using 'FOP' you have to convert DocBook to XML-FO
+  using <<X13,DocBook XSL Stylesheets>>.
+- 'FOP' is more feature complete (for example, callouts are processed
+  inside literal layouts) and arguably produces nicer looking output.
+
+HTML Help generation
+~~~~~~~~~~~~~~~~~~~~
+. Convert DocBook XML documents to HTML Help compiler source files
+  using <<X13,DocBook XSL Stylesheets>> and <<X40,xsltproc(1)>>.
+. Convert the HTML Help source (`.hhp` and `.html`) files to HTML Help
+  (`.chm`) files using the <<X67,Microsoft HTML Help Compiler>>.
+
+Toolchain components summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+AsciiDoc::
+    Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files.
+
+[[X13]]http://docbook.sourceforge.net/projects/xsl/[DocBook XSL Stylesheets]::
+  These are a set of XSL stylesheets containing rules for converting
+  DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.
+  The stylesheets are used in conjunction with an XML parser such as
+  <<X40,xsltproc(1)>>.
+
+[[X40]]http://www.xmlsoft.org[xsltproc]::
+  An XML parser for applying XSLT stylesheets (in our case the
+  <<X13,DocBook XSL Stylesheets>>) to XML documents.
+
+[[X31]]http://dblatex.sourceforge.net/[dblatex]::
+  Generates PDF, DVI, PostScript and LaTeX formats directly from
+  DocBook source via the intermediate LaTeX typesetting language --
+  uses <<X13,DocBook XSL Stylesheets>>, <<X40,xsltproc(1)>> and
+  `latex(1)`.
+
+[[X14]]http://xml.apache.org/fop/[FOP]::
+  The Apache Formatting Objects Processor converts XSL-FO (`.fo`)
+  files to PDF files.  The XSL-FO files are generated from DocBook
+  source files using <<X13,DocBook XSL Stylesheets>> and
+  <<X40,xsltproc(1)>>.
+
+[[X67]]Microsoft Help Compiler::
+  The Microsoft HTML Help Compiler (`hhc.exe`) is a command-line tool
+  that converts HTML Help source files to a single HTML Help (`.chm`)
+  file. It runs on MS Windows platforms and can be downloaded from
+  http://www.microsoft.com.
+
+AsciiDoc dblatex configuration files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The AsciiDoc distribution `./dblatex` directory contains
+`asciidoc-dblatex.xsl` (customized XSL parameter settings) and
+`asciidoc-dblatex.sty` (customized LaTeX settings). These are examples
+of optional <<X31,dblatex>> output customization and are used by
+<<X43,a2x(1)>>.
+
+AsciiDoc DocBook XSL Stylesheets drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You will have noticed that the distributed HTML and HTML Help
+documentation files (for example `./doc/asciidoc.html`) are not the
+plain outputs produced using the default 'DocBook XSL Stylesheets'
+configuration.  This is because they have been processed using
+customized DocBook XSL Stylesheets along with (in the case of HTML
+outputs) the custom `./stylesheets/docbook-xsl.css` CSS stylesheet.
+
+You'll find the customized DocBook XSL drivers along with additional
+documentation in the distribution `./docbook-xsl` directory. The
+examples that follow are executed from the distribution documentation
+(`./doc`) directory. These drivers are also used by <<X43,a2x(1)>>.
+
+`common.xsl`::
+    Shared driver parameters.  This file is not used directly but is
+    included in all the following drivers.
+
+`chunked.xsl`::
+    Generate chunked XHTML (separate HTML pages for each document
+    section) in the `./doc/chunked` directory. For example:
+
+    $ python ../asciidoc.py -b docbook asciidoc.txt
+    $ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml
+
+`epub.xsl`::
+    Used by <<X43,a2x(1)>> to generate EPUB formatted documents.
+
+`fo.xsl`::
+    Generate XSL Formatting Object (`.fo`) files for subsequent PDF
+    file generation using FOP. For example:
+
+    $ python ../asciidoc.py -b docbook article.txt
+    $ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
+    $ fop article.fo article.pdf
+
+`htmlhelp.xsl`::
+    Generate Microsoft HTML Help source files for the MS HTML Help
+    Compiler in the `./doc/htmlhelp` directory. This example is run on
+    MS Windows from a Cygwin shell prompt:
+
+    $ python ../asciidoc.py -b docbook asciidoc.txt
+    $ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
+    $ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
+
+`manpage.xsl`::
+    Generate a `roff(1)` format UNIX man page from a DocBook XML
+    'refentry' document. This example generates an `asciidoc.1` man
+    page file:
+
+    $ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
+    $ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml
+
+`xhtml.xsl`::
+    Convert a DocBook XML file to a single XHTML file. For example:
+
+    $ python ../asciidoc.py -b docbook asciidoc.txt
+    $ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html
+
+If you want to see how the complete documentation set is processed
+take a look at the A-A-P script `./doc/main.aap`.
+
+
+Generating Plain Text Files
+---------------------------
+AsciiDoc does not have a text backend (for most purposes AsciiDoc
+source text is fine), however you can convert AsciiDoc text files to
+formatted text using the AsciiDoc <<X43,a2x(1)>> toolchain wrapper
+utility.
+
+
+[[X35]]
+HTML5 and XHTML 1.1
+-------------------
+The 'xhtml11' and 'html5' backends embed or link CSS and JavaScript
+files in their outputs, there is also a <<X99,themes>> plugin
+framework.
+
+- If the AsciiDoc 'linkcss' attribute is defined then CSS and
+  JavaScript files are linked to the output document, otherwise they
+  are embedded (the default behavior).
 - The default locations for CSS and JavaScript files can be changed by
   setting the AsciiDoc 'stylesdir' and 'scriptsdir' attributes
   respectively.
 - The default locations for embedded and linked files differ and are
-  calculated at different times -- embedded files are located when
-  AsciiDoc generates the output document, linked files are located
-  when the user views the output document.
+  calculated at different times -- embedded files are loaded when
+  asciidoc(1) generates the output document, linked files are loaded
+  by the browser when the user views the output document.
+- Embedded files are automatically inserted in the output files but
+  you need to manually copy linked CSS and Javascript files from
+  AsciiDoc <<X27,configuration directories>> to the correct location
+  relative to the output document.
 
 .Stylesheet file locations
 [cols="3*",frame="topbot",options="header"]
@@ -293,6 +492,38 @@ directory containing the backend conf file).
 
 |====================================================================
 
+[[X99]]
+Themes
+~~~~~~
+The AsciiDoc 'theme' attribute is used to select an alternative CSS
+stylesheet and to optionally include additional JavaScript code.
+
+- Theme files reside in an AsciiDoc <<X27,configuration directory>>
+  named `themes/<theme>/` (where `<theme>` is the the theme name set
+  by the 'theme' attribute). asciidoc(1) sets the 'themedir' attribute
+  to the theme directory path name.
+- The 'theme' attribute can also be set using the asciidoc(1)
+  `--theme` option, the `--theme` option can also be used to manage
+  theme <<X101,plugins>>.
+- AsciiDoc ships with two themes: 'flask' and 'volnitsky'.
+- The `<theme>.css` file replaces the default `asciidoc.css` CSS file.
+- The `<theme>.js` file is included in addition to the default
+  `asciidoc.js` JavaScript file.
+- If the <<X66,data-uri>> attribute is defined then icons are loaded
+  from the theme's `icons` sub-directory if it exists (i.e.  the
+  'iconsdir' attribute is set to that location).
+- Embedded theme files are automatically inserted in the output files
+  but you need to manually copy linked CSS and Javascript files to the
+  location of the output documents.
+- Linked CSS and JavaScript theme files are linked to the same linked
+  locations as <<X35,other CSS and JavaScript files>>.
+
+For example, the command-line option `--theme foo` (or `--attribute
+theme=foo`) will cause asciidoc(1) to search <<"X27","configuration
+file locations 1, 2 and 3">> for a sub-directory called `themes/foo`
+containing the stylesheet `foo.css` and optionally a JavaScript file
+name `foo.js`.
+
 
 Document Structure
 ------------------
@@ -454,20 +685,27 @@ attribute entry in the document header.
 [[X87]]
 Additional document header information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-'docinfo' files are a mechanism for optionally including additional
-meta-data in the header of the output document.
+AsciiDoc has two mechanisms for optionally including additional
+meta-data in the header of the output document:
+
+'docinfo' configuration file sections::
+If a <<X7,configuration file>> section named 'docinfo' has been loaded
+then it will be included in the document header. Typically the
+'docinfo' section name will be prefixed with a '+' character so that it
+is appended to (rather than replace) other 'docinfo' sections.
 
+'docinfo' files::
 Two docinfo files are recognized: one named `docinfo` and a second
 named like the AsciiDoc source file with a `-docinfo` suffix.  For
 example, if the source document is called `mydoc.txt` then the
 document information files would be `docinfo.xml` and
 `mydoc-docinfo.xml` (for DocBook outputs) and `docinfo.html` and
-`mydoc-docinfo.html` (for HTML outputs).
+`mydoc-docinfo.html` (for HTML outputs).  The <<X97,docinfo, docinfo1
+and docinfo2>> attributes control which docinfo files are included in
+the output files.
 
-The <<X97,docinfo, docinfo1 and docinfo2>> attributes control which
-docinfo files are included in the output files.
-
-The contents docinfo file is dependent on the type of output:
+The contents docinfo templates and files is dependent on the type of
+output:
 
 HTML::
   Valid 'head' child elements. Typically 'style' and 'script' elements
@@ -568,9 +806,13 @@ The IDs are generated by the following algorithm:
   `idprefix` attribute is not defined.
 - A numbered suffix (`_2`, `_3` ...) is added if a same named
   auto-generated section ID exists.
+- If the `ascii-ids` attribute is defined then non-ASCII characters
+  are replaced with ASCII equivalents. This attribute may be
+  deprecated in future releases and *should be avoided*, it's sole
+  purpose is to accommodate deficient downstream applications that
+  cannot process non-ASCII ID attributes.
 
-For example the title 'Jim's House' would generate the ID
-`_jim_s_house`.
+Example: the title 'Jim's House' would generate the ID `_jim_s_house`.
 
 Section ID synthesis can be disabled by undefining the `sectids`
 attribute.
@@ -787,7 +1029,7 @@ color names].  Examples:
   [red]#Obvious# and [big red yellow-background]*very obvious*.
 
   [underline]#Underline text#, [overline]#overline text# and
-  [bold blue line-through]*bold blue and line-through*.
+  [blue line-through]*bold blue and line-through*.
 
 is rendered as:
 
@@ -2519,6 +2761,10 @@ headers.  Example:
   does not process nested includes). Setting 'depth' to '1' disables
   nesting inside the included file. By default, nesting is limited to
   a depth of five.
+- If the he 'warnings' attribute is set to 'False' (or any other Python
+  literal that evaluates to boolean false) then no warning message is
+  printed if the included file does not exist. By default 'warnings'
+  are enabled.
 - 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. To inhibit nested substitution in
@@ -2571,7 +2817,7 @@ Is equivalent to:
 Document text between the `ifeval` and `endif` macros is included if
 the Python expression inside the square brackets is true. Example:
 
-  ifeval::[{rs458}==2]]
+  ifeval::[{rs458}==2]
   :
   endif::[]
 
@@ -2615,8 +2861,8 @@ section:
 - The `template::[]` macro is useful for factoring configuration file
   markup.
 - `template::[]` macros cannot be nested.
-- `template::[]` macro expansion is applied to all sections
-  after all configuration files have been read.
+- `template::[]` macro expansion is applied after all configuration
+  files have been read.
 
 
 [[X77]]
@@ -3282,15 +3528,15 @@ Manpage Documents
 Sooner or later, if you program in a UNIX environment, you're going
 to have to write a man page.
 
-By observing a couple of additional conventions you can compose
-AsciiDoc files that will generate DocBook refentry (man page)
-documents.  The resulting DocBook file can then be translated to the
-native roff man page format (or other formats).
+By observing a couple of additional conventions (detailed below) you
+can write AsciiDoc files that will generate HTML and PDF man pages
+plus the native manpage roff format.  The easiest way to generate roff
+manpages from AsciiDoc source is to use the a2x(1) command. The
+following example generates a roff formatted manpage file called
+`asciidoc.1` (a2x(1) uses asciidoc(1) to convert `asciidoc.1.txt` to
+DocBook which it then converts to roff using DocBook XSL Stylesheets):
 
-For example, the `asciidoc.1.txt` file in the AsciiDoc distribution
-`./doc` directory was used to generate both the
-`asciidoc.1.css-embedded.html` HTML file the `asciidoc.1` roff
-formatted `asciidoc(1)` man page.
+  a2x --doctype manpage --format manpage asciidoc.1.txt
 
 .Viewing and printing manpage files
 **********************************************************************
@@ -3447,13 +3693,16 @@ lines of text between adjacent section headings.
 
 - Section names consist of one or more alphanumeric, underscore or
   dash characters and cannot begin or end with a dash.
-- Lines starting with a hash character "#" are treated as comments and
+- Lines starting with a '#' character are treated as comments and
   ignored.
-- Same named sections and section entries override previously loaded
-  sections and section entries (this is sometimes referred to as
-  'cascading').  Consequently, downstream configuration files need
-  only contain those sections and section entries that need to be
-  overridden.
+- If the section name is prefixed with a '+' character then the
+  section contents is appended to the contents of an already existing
+  same-named section.
+- Otherwise same-named sections and section entries override
+  previously loaded sections and section entries (this is sometimes
+  referred to as 'cascading').  Consequently, downstream configuration
+  files need only contain those sections and section entries that need
+  to be overridden.
 
 TIP: When creating custom configuration files you only need to include
 the sections and entries that differ from the default configuration.
@@ -3478,7 +3727,7 @@ quotes::
         Definitions for quoted inline character formatting.
 specialwords::
         Lists of words and phrases singled out for special markup.
-replacements, replacements2::
+replacements, replacements2, replacements3::
         Find and replace substitution definitions.
 specialsections::
         Used to single out special section names for specific markup.
@@ -3715,8 +3964,9 @@ ones.
 [[X10]]
 Replacements section
 ~~~~~~~~~~~~~~~~~~~~
-`[replacements]` and `[replacements2]` configuration file entries
-specify find and replace text and are formatted like:
+`[replacements]`, `[replacements2]` and `[replacements3]`
+configuration file entries specify find and replace text and are
+formatted like:
 
   <find_pattern>=<replacement_text>
 
@@ -3730,6 +3980,12 @@ macro name):
   NEW!=image:./images/smallnew.png[New!]
   \\NEW!=NEW!
 
+The only difference between the three replacement types is how they
+are applied. By default 'replacements' and 'replacement2' are applied
+in <<X102,normal>> substitution contexts whereas 'replacements3' needs
+to be configured explicitly and should only be used in backend
+configuration files.
+
 .Replacement behavior
 - The built-in replacements can be escaped with a backslash.
 - If the find or replace text has leading or trailing spaces then the
@@ -3781,6 +4037,11 @@ loaded from the following locations:
      `--conf-file` option can be specified multiple times, in which
      case configuration files will be processed in the same order they
      appear on the command-line.
+6. <<X100,Backend plugin>> configuration files are loaded from
+   subdirectories named like `backends/<backend>` in locations 1, 2
+   and 3.
+7. <<X59,Filter>> configuration files are loaded from subdirectories
+   named like `filters/<filter>` in locations 1, 2 and 3.
 
 Configuration files from the above locations are loaded in the
 following order:
@@ -3797,13 +4058,14 @@ This first pass makes locally set attributes available in the global
   `asciidoc.conf` in location 4.
 - The document header is parsed at this point and we can assume the
   'backend' and 'doctype' have now been defined.
-- `<backend>.conf` and `<backend>-<doctype>.conf` from locations 1,
-  2,3.
-- Filter conf files from the `filters` directory in locations 1, 2, 3.
+- Backend plugin `<backend>.conf` and `<backend>-<doctype>.conf` files
+  from locations 6.  If a backend plugin is not found then try
+  locations 1, 2 and 3 for `<backend>.conf` and
+  `<backend>-<doctype>.conf` backend configuration files.
+- Filter conf files from locations 7.
 - `lang-<lang>.conf` from locations 1, 2, 3.
 - `asciidoc.conf` from location 4.
 - `<backend>.conf` and `<backend>-<doctype>.conf` from location 4.
-  2,3.
 - Filter conf files from location 4.
 - `<docfile>.conf` and `<docfile>-<backend>.conf` from location 4.
 - Configuration files from location 5.
@@ -4295,9 +4557,11 @@ predefined intrinsic attributes:
   {backend-<backend>}   empty string ''
   {<backend>-<doctype>} empty string ''
   {backend}             document backend specified by `-b` option
+  {backend-confdir}     the directory containing the <backend>.conf file
   {backslash}           backslash character
   {basebackend-<base>}  empty string ''
   {basebackend}         html or docbook
+  {blockname}           current block name (note 8).
   {brvbar}              broken vertical bar (|) character
   {docdate}             document last modified date
   {docdir}              document input directory name  (note 5)
@@ -4334,12 +4598,14 @@ predefined intrinsic attributes:
   {notitle}             do not display the document title
   {outdir}              document output directory name (note 2)
   {outfile}             output file name (note 2)
+  {python}              the full path name of the Python interpreter executable
   {rdquo}               Right double quote character (note 7)
   {reftext}             running block xreflabel generated by BlockId elements
   {revdate}             document revision date (from document header)
   {revnumber}           document revision number (from document header)
   {rsquo}               Right single quote character (note 7)
   {sectnum}             formatted section number (in section titles)
+  {sp}                  space character
   {showcomments}        send comment lines to the output
   {title}               section title (in titled elements)
   {two-colons}          Two colon characters
@@ -4375,6 +4641,20 @@ predefined intrinsic attributes:
 7. See
    http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks[non-English
    usage of quotation marks].
+8. The `{blockname}` attribute identifies the style of the current
+   block. It applies to delimited blocks, lists and tables. Here is a
+   list of `{blockname}` values (does not include filters or custom
+   block and style names):
+
+   delimited blocks:: comment, sidebar, open, pass, literal, verse,
+   listing, quote, example, note, tip, important, caution, warning,
+   abstract, partintro
+
+   lists:: arabic, loweralpha, upperalpha, lowerroman, upperroman,
+   labeled, labeled3, labeled4, qanda, horizontal, bibliography,
+   glossary
+
+   tables:: table
 
 ======
 
@@ -4397,6 +4677,12 @@ template=listingblock
 presubs=specialcharacters,callouts
 ---------------------------------------------------------------------
 
+Configuration file block definition sections are processed
+incrementally after each configuration file is loaded. Block
+definition section entries are merged into the block definition, this
+allows block parameters to be overridden and extended by later
+<<X27,loading configuration files>>.
+
 AsciiDoc Paragraph, DelimitedBlock, List and Table block elements
 share a common subset of configuration file parameters:
 
@@ -4435,16 +4721,17 @@ subs, presubs, postsubs::
   * Allowed values: 'specialcharacters', 'quotes', 'specialwords',
     'replacements', 'macros', 'attributes', 'callouts'.
 
-  * The following composite values are also allowed:
+  * [[X102]]The following composite values are also allowed:
 
     'none';;
         No substitutions.
     'normal';;
-        The following substitutions:
-        'specialcharacters','quotes','attributes','specialwords',
-        'replacements','macros'.
+        The following substitutions in the following order:
+        'specialcharacters', 'quotes', 'attributes', 'specialwords',
+        'replacements', 'macros', 'replacements2'.
     'verbatim';;
-        'specialcharacters' and 'callouts' substitutions.
+        The following substitutions in the following order:
+        'specialcharacters' and 'callouts'.
 
   * 'normal' and 'verbatim' substitutions can be redefined by with
     `subsnormal` and `subsverbatim` entries in a configuration file
@@ -4481,17 +4768,24 @@ be set in block attribute lists and style definitions: 'template',
 [[X23]]
 Styles
 ~~~~~~
-A style is a set of block attributes bundled as a single named
-attribute. The following example defines a style named 'verbatim':
+A style is a set of block parameter bundled as a single named
+parameter. The following example defines a style named 'verbatim':
 
   verbatim-style=template="literalblock",subs="verbatim"
 
+If a block's <<X21,attribute list>> contains a 'style' attribute then
+the corresponding style parameters are be merged into the default
+block definition parameters.
+
 - All style parameter names must be suffixed with `-style` and the
   style parameter value is in the form of a list of <<X21,named
   attributes>>.
-- Multi-item style attributes ('subs','presubs','postsubs','posattrs')
-  must be specified using Python tuple syntax rather than a simple
-  list of values as they in separate entries e.g.
+- The 'template' style parameter is mandatory, other parameters can be
+  omitted in which case they inherit their values from the default
+  block definition parameters.
+- Multi-item style parameters ('subs','presubs','postsubs','posattrs')
+  must be specified using Python tuple syntax (rather than a simple
+  list of values as they in separate entries) e.g.
   `postsubs=("callouts",)` not `postsubs="callouts"`.
 
 Paragraphs
@@ -4550,6 +4844,8 @@ sectionbody::
 
 skip::
     The block is treated as a comment (see <<X26,CommentBlocks>>).
+    Preceding <<X21,attribute lists>> and <<X42,block titles>> are not
+    consumed.
 
 'presubs', 'postsubs' and 'filter' entries are ignored when
 'sectionbody' or 'skip' options are set.
@@ -4657,7 +4953,8 @@ filters: they read text from the standard input, process it, and write
 to the standard output.
 
 The asciidoc(1) command `--filter` option can be used to install and
-remove filters.
+remove filters. The same option is used to unconditionally load a
+filter.
 
 Attribute substitution is performed on the filter command prior to
 execution -- attributes can be used to pass parameters from the
@@ -4698,7 +4995,10 @@ attribute list: the first positional attribute is the style name,
 remaining attributes are normally filter specific parameters.
 
 asciidoc(1) auto-loads all `.conf` files found in the filter search
-paths (see previous section).
+paths unless the container directory also contains a file named
+`__noautoload__` (see previous section). The `__noautoload__` feature
+is used for filters that will be loaded manually using the `--filter`
+option.
 
 [[X56]]
 Example Filter
@@ -4713,253 +5013,77 @@ highlighter.  If you want a full featured multi-language highlighter
 use the {website}source-highlight-filter.html[source code highlighter
 filter].
 
-[listing]
-.....................................................................
-.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:
-
-.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
-----------------------------------------------
-
 Built-in filters
 ~~~~~~~~~~~~~~~~
 The AsciiDoc distribution includes 'source', 'music', 'latex' and
 'graphviz' filters, details are on the
 {website}index.html#_filters[AsciiDoc website].
 
+[cols="1e,5",frame="topbot",options="header"]
+.Built-in filters list
+|====================================================================
+|Filter name |Description
+
+|music
+|A {website}music-filter.html[music filter] is included in the
+distribution `./filters/` directory. It translates music in
+http://lilypond.org/[LilyPond] or http://abcnotation.org.uk/[ABC]
+notation to standard classical notation.
+
+|source
+|A {website}source-highlight-filter.html[source code highlight filter]
+is included in the distribution `./filters/` directory.
+
+|latex
+|The {website}latex-filter.html[AsciiDoc LaTeX filter] translates
+LaTeX source to a PNG image that is automatically inserted into the
+AsciiDoc output documents.
+
+|graphviz
+|Gouichi Iisaka has written a http://www.graphviz.org/[Graphviz]
+filter for AsciiDoc.  Graphviz generates diagrams from a textual
+specification. Gouichi Iisaka's Graphviz filter is included in the
+AsciiDoc distribution. Here are some
+{website}asciidoc-graphviz-sample.html[AsciiDoc Graphviz examples].
+
+|====================================================================
+
 [[X58]]
 Filter plugins
 ~~~~~~~~~~~~~~
-Filter plugins are a simple mechanism for distributing AsciiDoc
+Filter <<X101,plugins>> are a mechanism for distributing AsciiDoc
 filters.  A filter plugin is a Zip file containing the files that
-constitute a filter. The asciidoc(1) `--filter` option implements
-commands to install, remove and list filter plugins.  Filter plugin
-commands and conventions are documented in the asciidoc(1) man page.
-You can find a list of filter plugins on the
-{website}filters.html[AsciiDoc website].
-
-
-[[X12]]
-Converting DocBook to other file formats
-----------------------------------------
-DocBook files are validated, parsed and translated various
-presentation file formats using a combination of applications
-collectively called a DocBook 'tool chain'. The function of a tool
-chain is to read the DocBook markup (produced by AsciiDoc) and
-transform it to a presentation format (for example HTML, PDF, HTML
-Help, EPUB, DVI, PostScript, LaTeX).
-
-A wide range of user output format requirements coupled with a choice
-of available tools and stylesheets results in many valid tool chain
-combinations.
-
-[[X43]]
-a2x Toolchain Wrapper
-~~~~~~~~~~~~~~~~~~~~~
-One of the biggest hurdles for new users is installing, configuring
-and using a DocBook XML toolchain. `a2x(1)` can help -- it's a
-toolchain wrapper command that will generate XHTML (chunked and
-unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text
-file outputs from an AsciiDoc text file.  `a2x(1)` does all the grunt
-work associated with generating and sequencing the toolchain commands
-and managing intermediate and output files.  `a2x(1)` also optionally
-deploys admonition and navigation icons and a CSS stylesheet. See the
-`a2x(1)` man page for more details. In addition to `asciidoc(1)` you
-also need <<X40,xsltproc(1)>>, <<X13,DocBook XSL Stylesheets>> and
-optionally: <<X31,dblatex>> or <<X14,FOP>> (to generate PDF);
-`w3m(1)` or `lynx(1)` (to generate text).
-
-The following examples generate `doc/source-highlight-filter.pdf` from
-the AsciiDoc `doc/source-highlight-filter.txt` source file. The first
-example uses `dblatex(1)` (the default PDF generator) the second
-example forces FOP to be used:
-
-  $ a2x -f pdf doc/source-highlight-filter.txt
-  $ a2x -f pdf --fop doc/source-highlight-filter.txt
-
-See the `a2x(1)` man page for details.
-
-TIP: Use the `--verbose` command-line option to view executed
-toolchain commands.
-
-HTML generation
-~~~~~~~~~~~~~~~
-AsciiDoc produces nicely styled HTML directly without requiring a
-DocBook toolchain but there are also advantages in going the DocBook
-route:
-
-- HTML from DocBook can optionally include automatically generated
-  indexes, tables of contents, footnotes, lists of figures and tables.
-- DocBook toolchains can also (optionally) generate separate (chunked)
-  linked HTML pages for each document section.
-- Toolchain processing performs link and document validity checks.
-- If the DocBook 'lang' attribute is set then things like table of
-  contents, figure and table captions and admonition captions will be
-  output in the specified language (setting the AsciiDoc 'lang'
-  attribute sets the DocBook 'lang' attribute).
-
-On the other hand, HTML output directly from AsciiDoc is much faster,
-is easily customized and can be used in situations where there is no
-suitable DocBook toolchain (for example, see the {website}[AsciiDoc
-website]).
-
-PDF generation
-~~~~~~~~~~~~~~
-There are two commonly used tools to generate PDFs from DocBook,
-<<X31,dblatex>> and <<X14,FOP>>.
-
-.dblatex or FOP?
-- 'dblatex' is easier to install, there's zero configuration
-  required and no Java VM to install -- it just works out of the box.
-- 'dblatex' source code highlighting and numbering is superb.
-- 'dblatex' is easier to use as it converts DocBook directly to PDF
-  whereas before using 'FOP' you have to convert DocBook to XML-FO
-  using <<X13,DocBook XSL Stylesheets>>.
-- 'FOP' is more feature complete (for example, callouts are processed
-  inside literal layouts) and arguably produces nicer looking output.
-
-HTML Help generation
-~~~~~~~~~~~~~~~~~~~~
-. Convert DocBook XML documents to HTML Help compiler source files
-  using <<X13,DocBook XSL Stylesheets>> and <<X40,xsltproc(1)>>.
-. Convert the HTML Help source (`.hhp` and `.html`) files to HTML Help
-  (`.chm`) files using the <<X67,Microsoft HTML Help Compiler>>.
-
-Toolchain components summary
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-AsciiDoc::
-    Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files.
-
-[[X13]]http://docbook.sourceforge.net/projects/xsl/[DocBook XSL Stylesheets]::
-  These are a set of XSL stylesheets containing rules for converting
-  DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.
-  The stylesheets are used in conjunction with an XML parser such as
-  <<X40,xsltproc(1)>>.
-
-[[X40]]http://www.xmlsoft.org[xsltproc]::
-  An XML parser for applying XSLT stylesheets (in our case the
-  <<X13,DocBook XSL Stylesheets>>) to XML documents.
-
-[[X31]]http://dblatex.sourceforge.net/[dblatex]::
-  Generates PDF, DVI, PostScript and LaTeX formats directly from
-  DocBook source via the intermediate LaTeX typesetting language --
-  uses <<X13,DocBook XSL Stylesheets>>, <<X40,xsltproc(1)>> and
-  `latex(1)`.
-
-[[X14]]http://xml.apache.org/fop/[FOP]::
-  The Apache Formatting Objects Processor converts XSL-FO (`.fo`)
-  files to PDF files.  The XSL-FO files are generated from DocBook
-  source files using <<X13,DocBook XSL Stylesheets>> and
-  <<X40,xsltproc(1)>>.
-
-[[X67]]Microsoft Help Compiler::
-  The Microsoft HTML Help Compiler (`hhc.exe`) is a command-line tool
-  that converts HTML Help source files to a single HTML Help (`.chm`)
-  file. It runs on MS Windows platforms and can be downloaded from
-  http://www.microsoft.com.
-
-AsciiDoc dblatex configuration files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The AsciiDoc distribution `./dblatex` directory contains
-`asciidoc-dblatex.xsl` (customized XSL parameter settings) and
-`asciidoc-dblatex.sty` (customized LaTeX settings). These are examples
-of optional <<X31,dblatex>> output customization and are used by
-<<X43,a2x(1)>>.
+constitute a filter.  The asciidoc(1) `--filter` option is used to
+load and manage filer <<X101,plugins>>.
 
-AsciiDoc DocBook XSL Stylesheets drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You will have noticed that the distributed HTML and HTML Help
-documentation files (for example `./doc/asciidoc.html`) are not the
-plain outputs produced using the default 'DocBook XSL Stylesheets'
-configuration.  This is because they have been processed using
-customized DocBook XSL Stylesheets along with (in the case of HTML
-outputs) the custom `./stylesheets/docbook-xsl.css` CSS stylesheet.
+- Filter plugins <<X27,take precedence>> over built-in filters with
+  the same name.
+- By default filter plugins are installed in
+  `$HOME/.asciidoc/filters/<filter>` where `<filter>` is the filter
+  name.
 
-You'll find the customized DocBook XSL drivers along with additional
-documentation in the distribution `./docbook-xsl` directory. The
-examples that follow are executed from the distribution documentation
-(`./doc`) directory. These drivers are also used by <<X43,a2x(1)>>.
 
-`common.xsl`::
-    Shared driver parameters.  This file is not used directly but is
-    included in all the following drivers.
-
-`chunked.xsl`::
-    Generate chunked XHTML (separate HTML pages for each document
-    section) in the `./doc/chunked` directory. For example:
-
-    $ python ../asciidoc.py -b docbook asciidoc.txt
-    $ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml
-
-`epub.xsl`::
-    Used by <<X43,a2x(1)>> to generate EPUB formatted documents.
-
-`fo.xsl`::
-    Generate XSL Formatting Object (`.fo`) files for subsequent PDF
-    file generation using FOP. For example:
-
-    $ python ../asciidoc.py -b docbook article.txt
-    $ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
-    $ fop article.fo article.pdf
-
-`htmlhelp.xsl`::
-    Generate Microsoft HTML Help source files for the MS HTML Help
-    Compiler in the `./doc/htmlhelp` directory. This example is run on
-    MS Windows from a Cygwin shell prompt:
-
-    $ python ../asciidoc.py -b docbook asciidoc.txt
-    $ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
-    $ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
-
-`manpage.xsl`::
-    Generate a `roff(1)` format UNIX man page from a DocBook XML
-    'refentry' document. This example generates an `asciidoc.1` man
-    page file:
-
-    $ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
-    $ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml
-
-`xhtml.xsl`::
-    Convert a DocBook XML file to a single XHTML file. For example:
-
-    $ python ../asciidoc.py -b docbook asciidoc.txt
-    $ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html
-
-If you want to see how the complete documentation set is processed
-take a look at the A-A-P script `./doc/main.aap`.
-
-
-Generating Plain Text Files
----------------------------
-AsciiDoc does not have a text backend (for most purposes AsciiDoc
-source text is fine), however you can convert AsciiDoc text files to
-formatted text using the AsciiDoc <<X43,a2x(1)>> toolchain wrapper
-utility.
+[[X101]]
+Plugins
+-------
+The AsciiDoc plugin architecture is an extension mechanism that allows
+additional <<X100,backends>>, <<X58,filters>> and <<X99,themes>> to be
+added to AsciiDoc.
+
+- A plugin is a Zip file containing an AsciiDoc backend, filter or
+  theme (configuration files, stylesheets, scripts, images).
+- The asciidoc(1) `--backend`, `--filter` and `--theme` command-line
+  options are used to load and manage plugins. Each of these options
+  responds to the plugin management 'install', 'list', 'remove' and
+  'build' commands.
+- The plugin management command names are reserved and cannot be used
+  for filter, backend or theme names.
+- The plugin Zip file name always begins with the backend, filter or
+  theme name.
+
+Plugin commands and conventions are documented in the asciidoc(1) man
+page.  You can find lists of plugins on the
+{website}plugins.html[AsciiDoc website].
 
 
 [[X36]]
@@ -4970,18 +5094,14 @@ to stdout. The default topic summarizes asciidoc(1) usage:
 
   $ asciidoc --help
 
-To print a list of help topics:
-
-  $ asciidoc --help=topics
-
 To print a help topic specify the topic name as a command argument.
 Help topic names can be shortened so long as they are not ambiguous.
 Examples:
 
-  $ asciidoc --help=manpage
-  $ asciidoc -hm              # Short version of previous example.
-  $ asciidoc --help=syntax
-  $ asciidoc -hs              # Short version of previous example.
+  $ asciidoc --help manpage
+  $ asciidoc -h m              # Short version of previous example.
+  $ asciidoc --help syntax
+  $ asciidoc -h s              # Short version of previous example.
 
 Customizing Help
 ~~~~~~~~~~~~~~~~
@@ -5544,6 +5664,11 @@ The column widths are determined by the browser, not the AsciiDoc
 'cols' attribute. If there is no 'width' attribute the table width is
 also left up to the browser.
 
+|unbreakable |xhtml11, html5 |block elements|
+'unbreakable' attempts to keep the block element together on a single
+printed page c.f. the 'breakable' and 'unbreakable' docbook (XSL/FO)
+options below.
+
 |breakable, unbreakable |docbook (XSL/FO) |table, example, block image|
 The 'breakable' options allows block elements to break across page
 boundaries; 'unbreakable' attempts to keep the block element together
@@ -5621,6 +5746,8 @@ name (man page NAME section)
 paragraph
 preamble close
 preamble open
+push blockname
+pop blockname
 section close
 section open: level <level>
 subs (all inline substitutions)
@@ -5634,7 +5761,7 @@ Where:
   'open', 'pass', 'listing', 'literal', 'quote', 'example'.
 - `<subs>` is an inline substitution type:
   'specialcharacters','quotes','specialwords', 'replacements',
-  'attributes','macros','callouts', 'replacements2'.
+  'attributes','macros','callouts', 'replacements2', 'replacements3'.
 
 Command-line examples:
 
@@ -5677,8 +5804,8 @@ generated outputs.
 |Name |Backends |Description
 
 |badges |xhtml11, html5 |
-Link badges ('XHTML 1.1', 'CSS' and 'Get Firefox!') in document
-footers. By default badges are omitted ('badges' is undefined).
+Link badges ('XHTML 1.1' and 'CSS') in document footers. By default
+badges are omitted ('badges' is undefined).
 
 NOTE: The path names of images, icons and scripts are relative path
 names to the output document not the source document.
@@ -5686,6 +5813,14 @@ names to the output document not the source document.
 |data-uri |xhtml11, html5 |
 Embed images using the <<X66,data: uri scheme>>.
 
+|css-signature |html5, xhtml11 |
+Set a 'CSS signature' for the document (sets the 'id' attribute of the
+HTML 'body' element). CSS signatures provide a mechanism that allows
+users to personalize the document appearance. The term 'CSS signature'
+was http://archivist.incutio.com/viewlist/css-discuss/13291[coined by
+Eric Meyer].
+
+
 |disable-javascript |xhtml11, html5 |
 If the `disable-javascript` attribute is defined the `asciidoc.js`
 JavaScript is not embedded or linked to the output document.  By
@@ -5755,7 +5890,7 @@ Link CSS stylesheets and JavaScripts. By default 'linkcss' is
 undefined in which case stylesheets and scripts are automatically
 embedded in the output document.
 
-|max-width |html5, xhtml11 |
+|[[X103]]max-width |html5, xhtml11 |
 Set the document maximum display width (sets the 'body' element CSS
 'max-width' property).
 
@@ -5771,7 +5906,7 @@ dealing with large amounts of imported plain text.
 |quirks |xhtml11 |
 Include the `xhtml11-quirks.conf` configuration file and
 `xhtml11-quirks.css` <<X35,stylesheet>> to work around IE6 browser
-incompatibilities. This feature is deprecated and it's use is
+incompatibilities. This feature is deprecated and its use is
 discouraged -- documents are still viewable in IE6 without it.
 
 |revremark |docbook |
@@ -5781,7 +5916,7 @@ dated to output this attribute.
 
 |scriptsdir |html5, xhtml11 |
 The name of the directory containing linked JavaScripts.
-See <<X99,HTML stylesheets and JavaScript locations>>.
+See <<X35,HTML stylesheets and JavaScript locations>>.
 
 |sgml |docbook45 |
 The `--backend=docbook45` command-line option produces DocBook 4.5
@@ -5791,13 +5926,13 @@ XML.  You can produce the older DocBook SGML format using the
 |stylesdir |html5, xhtml11 |
 The name of the directory containing linked or embedded
 <<X35,stylesheets>>.
-See <<X99,HTML stylesheets and JavaScript locations>>.
+See <<X35,HTML stylesheets and JavaScript locations>>.
 
 |stylesheet |html5, xhtml11 |
 The file name of an optional additional CSS <<X35,stylesheet>>.
 
 |theme |html5, xhtml11 |
-Use alternative stylesheets (see <<X35,Stylesheets>>).
+Use alternative stylesheet (see <<X35,Stylesheets>>).
 
 |[[X91]]toc |html5, xhtml11, docbook (XSL Stylesheets) |
 Adds a table of contents to the start of an article or book document.
@@ -5822,6 +5957,12 @@ article or book document. Use the 'max-width' attribute to change the
 content width. In all other respects behaves the same as the 'toc'
 attribute.
 
+|toc-placement |html5, xhtml11 |
+When set to 'auto' (the default value) asciidoc(1) will display the
+'Table of Contents' in the document header. When set to 'manual' the
+'Table of Contents' position is determined by the position of the
+`toc::[]` block macro.
+
 |toc-title |html5, xhtml11 |
 Sets the table of contents title (defaults to 'Table of Contents').