diff options
Diffstat (limited to 'asciidoc.html')
| -rw-r--r-- | asciidoc.html | 9799 |
1 files changed, 0 insertions, 9799 deletions
diff --git a/asciidoc.html b/asciidoc.html deleted file mode 100644 index fe51895..0000000 --- a/asciidoc.html +++ /dev/null @@ -1,9799 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
- "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<meta name="generator" content="AsciiDoc 10.0.0a2" />
-<title>AsciiDoc User Guide</title>
-<link rel="stylesheet" href="./asciidoc.css" type="text/css" />
-<link rel="stylesheet" href="./layout2.css" type="text/css" />
-<script type="text/javascript" src="./asciidoc.js"></script>
-<script type="text/javascript">
-/*<![CDATA[*/
-asciidoc.install(2);
-/*]]>*/
-</script>
-</head>
-<body style="max-width:70em">
-<div id="layout-menu-box">
-<div id="layout-menu">
- <div>»<a href="index.html">Home</a></div>
- <div>»<a href="userguide.html">User Guide</a></div>
- <div>»<a href="INSTALL.html">Installation</a></div>
- <div>»<a href="faq.html">FAQ</a></div>
- <div>»<a href="manpage.html">asciidoc(1)</a></div>
- <div>»<a href="a2x.1.html">a2x(1)</a></div>
- <div>»<a href="asciidocapi.html">API</a></div>
- <div>»<a href="plugins.html">Plugins</a></div>
- <div>»<a href="http://powerman.name/doc/asciidoc">Cheatsheet</a></div>
- <div>»<a href="testasciidoc.html">Tests</a></div>
- <div>»<a href="CHANGELOG.html">ChangeLog</a></div>
- <div>»<a href="support.html">Support</a></div>
- <div id="page-source">»<a href="asciidoc.txt">Page Source</a></div>
-</div>
-</div>
-<div id="layout-content-box">
-<div id="layout-banner">
- <div id="layout-title">AsciiDoc</div>
- <div id="layout-description">Text based document generation</div>
-</div>
-<div id="layout-content">
-<div id="header">
-<h1>AsciiDoc User Guide</h1>
-<span id="author">AsciiDoc.py Team</span><br />
-<span id="revision">version 9.1.0,</span>
-08 February 2021
-<div id="toc">
- <div id="toctitle">Table of Contents</div>
- <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
-</div>
-</div>
-<div id="content">
-<div id="preamble">
-<div class="sectionbody">
-<div class="paragraph"><p>AsciiDoc is a text document format for writing notes, documentation,
-articles, books, ebooks, slideshows, web pages, blogs and UNIX man
-pages. AsciiDoc files can be translated to many formats including
-HTML, PDF, EPUB, man page. AsciiDoc is highly configurable: both the
-AsciiDoc source file syntax and the backend output markups (which can
-be almost any type of SGML/XML markup) can be customized and extended
-by the user.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/warning.png" alt="Warning" />
-</td>
-<td class="content">This user guide is for AsciiDoc.py, which is a legacy processor for
-this syntax, handling an older rendition of AsciiDoc. As such, this
-will not properly handle the
-<a href="https://projects.eclipse.org/projects/technology.asciidoc">current AsciiDoc specification</a>.
-It is suggested that unless you specifically require the AsciiDoc.py
-toolchain, you should find a processor that handles the modern
-AsciiDoc syntax.</td>
-</tr></table>
-</div>
-<div class="sidebarblock">
-<div class="content">
-<div class="title">This document</div>
-<div class="paragraph"><p>This is an overly large document, it probably needs to be refactored
-into a Tutorial, Quick Reference and Formal Reference.</p></div>
-<div class="paragraph"><p>If you’re new to AsciiDoc read this section and the <a href="#X6">Getting Started</a> section and take a look at the example AsciiDoc (<code>*.txt</code>)
-source files in the distribution <code>doc</code> directory.</p></div>
-</div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_introduction">1. Introduction</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>AsciiDoc is a plain text human readable/writable document format that
-can be translated to DocBook or HTML using the <code>asciidoc(1)</code> command.
-You can then either use <code>asciidoc(1)</code> generated HTML directly or run
-<code>asciidoc(1)</code> DocBook output through your favorite DocBook toolchain or
-use the AsciiDoc <code>a2x(1)</code> toolchain wrapper to produce PDF, EPUB, DVI,
-LaTeX, PostScript, man page, HTML and text formats.</p></div>
-<div class="paragraph"><p>The AsciiDoc format is a useful presentation format in its own right:
-AsciiDoc markup is simple, intuitive and as such is easily proofed and
-edited.</p></div>
-<div class="paragraph"><p>AsciiDoc is light weight: it consists of a single Python script and a
-bunch of configuration files. Apart from <code>asciidoc(1)</code> and a Python
-interpreter, no other programs are required to convert AsciiDoc text
-files to DocBook or HTML. See <a href="#X11">Example AsciiDoc Documents</a>
-below.</p></div>
-<div class="paragraph"><p>Text markup conventions tend to be a matter of (often strong) personal
-preference: if the default syntax is not to your liking you can define
-your own by editing the text based <code>asciidoc(1)</code> configuration files.
-You can also create configuration files to translate AsciiDoc
-documents to almost any SGML/XML markup.</p></div>
-<div class="paragraph"><p><code>asciidoc(1)</code> comes with a set of configuration files to translate
-AsciiDoc articles, books and man pages to HTML or DocBook backend
-formats.</p></div>
-<div class="sidebarblock">
-<div class="content">
-<div class="title">My AsciiDoc Itch</div>
-<div class="paragraph"><p>DocBook has emerged as the de facto standard Open Source documentation
-format. But DocBook is a complex language, the markup is difficult to
-read and even more difficult to write directly — I found I was
-spending more time typing markup tags, consulting reference manuals
-and fixing syntax errors, than I was writing the documentation.</p></div>
-</div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X6">2. Getting Started</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_installing_asciidoc">2.1. Installing AsciiDoc</h3>
-<div class="paragraph"><p>See the <code>README</code> and <code>INSTALL</code> files for install prerequisites and
-procedures. Packagers take a look at <a href="#X38">Packager Notes</a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="X11">2.2. Example AsciiDoc Documents</h3>
-<div class="paragraph"><p>The best way to quickly get a feel for AsciiDoc is to view the
-AsciiDoc web site and/or distributed examples:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Take a look at the linked examples on the AsciiDoc web site home
- page <a href="https://asciidoc.org/">https://asciidoc.org/</a>. Press the <em>Page Source</em> sidebar menu item to view
- corresponding AsciiDoc source.
-</p>
-</li>
-<li>
-<p>
-Read the <code>*.txt</code> source files in the distribution <code>./doc</code> directory
- along with the corresponding HTML and DocBook XML files.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_asciidoc_document_types">3. AsciiDoc Document Types</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>There are three types of AsciiDoc documents: article, book and
-manpage. All document types share the same AsciiDoc format with some
-minor variations. If you are familiar with DocBook you will have
-noticed that AsciiDoc document types correspond to the same-named
-DocBook document types.</p></div>
-<div class="paragraph"><p>Use the <code>asciidoc(1)</code> <code>-d</code> (<code>--doctype</code>) option to specify the AsciiDoc
-document type — the default document type is <em>article</em>.</p></div>
-<div class="paragraph"><p>By convention the <code>.txt</code> file extension is used for AsciiDoc document
-source files.</p></div>
-<div class="sect2">
-<h3 id="_article">3.1. article</h3>
-<div class="paragraph"><p>Used for short documents, articles and general documentation. See the
-AsciiDoc distribution <code>./doc/article.txt</code> example.</p></div>
-<div class="paragraph"><p>AsciiDoc defines standard DocBook article frontmatter and backmatter
-<a href="#X93">section markup templates</a> (appendix, abstract, bibliography,
-glossary, index).</p></div>
-</div>
-<div class="sect2">
-<h3 id="_book">3.2. book</h3>
-<div class="paragraph"><p>Books share the same format as articles, with the following
-differences:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The part titles in multi-part books are <a href="#X17">top level titles</a>
- (same level as book title).
-</p>
-</li>
-<li>
-<p>
-Some sections are book specific e.g. preface and colophon.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Book documents will normally be used to produce DocBook output since
-DocBook processors can automatically generate footnotes, table of
-contents, list of tables, list of figures, list of examples and
-indexes.</p></div>
-<div class="paragraph"><p>AsciiDoc defines standard DocBook book frontmatter and backmatter
-<a href="#X93">section markup templates</a> (appendix, dedication, preface,
-bibliography, glossary, index, colophon).</p></div>
-<div class="dlist"><div class="title">Example book documents</div><dl>
-<dt class="hdlist1">
-Book
-</dt>
-<dd>
-<p>
- The <code>./doc/book.txt</code> file in the AsciiDoc distribution.
-</p>
-</dd>
-<dt class="hdlist1">
-Multi-part book
-</dt>
-<dd>
-<p>
- The <code>./doc/book-multi.txt</code> file in the AsciiDoc distribution.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_manpage">3.3. manpage</h3>
-<div class="paragraph"><p>Used to generate roff format UNIX manual pages. AsciiDoc manpage
-documents observe special header title and section naming conventions — see the <a href="#X1">Manpage Documents</a> section for details.</p></div>
-<div class="paragraph"><p>AsciiDoc defines the <em>synopsis</em> <a href="#X93">section markup template</a> to
-generate the DocBook <code>refsynopsisdiv</code> section.</p></div>
-<div class="paragraph"><p>See also the <code>asciidoc(1)</code> man page source (<code>./doc/asciidoc.1.txt</code>) from
-the AsciiDoc distribution.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X5">4. AsciiDoc Backends</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>asciidoc(1)</code> command translates an AsciiDoc formatted file to the
-backend format specified by the <code>-b</code> (<code>--backend</code>) command-line
-option. <code>asciidoc(1)</code> itself has little intrinsic knowledge of backend
-formats, all translation rules are contained in customizable cascading
-configuration files. Backend specific attributes are listed in the
-<a href="#X88">Backend Attributes</a> section.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-docbook45
-</dt>
-<dd>
-<p>
- Outputs DocBook XML 4.5 markup.
-</p>
-</dd>
-<dt class="hdlist1">
-docbook5
-</dt>
-<dd>
-<p>
- Outputs DocBook XML 5.0 markup.
-</p>
-</dd>
-<dt class="hdlist1">
-html4
-</dt>
-<dd>
-<p>
- This backend generates plain HTML 4.01 Transitional markup.
-</p>
-</dd>
-<dt class="hdlist1">
-xhtml11
-</dt>
-<dd>
-<p>
- This backend generates XHTML 1.1 markup styled with CSS2. Output
- files have an <code>.html</code> extension.
-</p>
-</dd>
-<dt class="hdlist1">
-html5
-</dt>
-<dd>
-<p>
- This backend generates HTML 5 markup, apart from the inclusion of
- <a href="#X98">audio and video block macros</a> it is functionally identical to
- the <em>xhtml11</em> backend.
-</p>
-</dd>
-<dt class="hdlist1">
-slidy
-</dt>
-<dd>
-<p>
- Use this backend to generate self-contained
- <a href="https://www.w3.org/Talks/Tools/Slidy2">Slidy</a> HTML slideshows for
- your web browser from AsciiDoc documents. The Slidy backend is
- documented in the distribution <code>doc/slidy.txt</code> file and
- <a href="https://asciidoc.org/slidy.html">online</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-wordpress
-</dt>
-<dd>
-<p>
- A minor variant of the <em>html4</em> backend to support
- <a href="https://srackham.wordpress.com/blogpost1/">blogpost</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-latex
-</dt>
-<dd>
-<p>
- Experimental LaTeX backend.
-</p>
-</dd>
-</dl></div>
-<div class="sect2">
-<h3 id="_backend_aliases">4.1. Backend Aliases</h3>
-<div class="paragraph"><p>Backend aliases are alternative names for AsciiDoc backends. AsciiDoc
-comes with two backend aliases: <em>html</em> (aliased to <em>xhtml11</em>) and
-<em>docbook</em> (aliased to <em>docbook45</em>).</p></div>
-<div class="paragraph"><p>You can assign (or reassign) backend aliases by setting an AsciiDoc
-attribute named like <code>backend-alias-<alias></code> to an AsciiDoc backend
-name. For example, the following backend alias attribute definitions
-appear in the <code>[attributes]</code> section of the global <code>asciidoc.conf</code>
-configuration file:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>backend-alias-html=xhtml11
-backend-alias-docbook=docbook45</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="X100">4.2. Backend Plugins</h3>
-<div class="paragraph"><p>The <code>asciidoc(1)</code> <code>--backend</code> option is also used to install and manage
-backend <a href="#X101">plugins</a>.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A backend plugin is used just like the built-in backends.
-</p>
-</li>
-<li>
-<p>
-Backend plugins <a href="#X27">take precedence</a> over built-in backends with
- the same name.
-</p>
-</li>
-<li>
-<p>
-You can use the <code>{asciidoc-confdir}</code> <a href="#X60">intrinsic attribute</a> to
- refer to the built-in backend configuration file location from
- backend plugin configuration files.
-</p>
-</li>
-<li>
-<p>
-You can use the <code>{backend-confdir}</code> <a href="#X60">intrinsic attribute</a> to
- refer to the backend plugin configuration file location.
-</p>
-</li>
-<li>
-<p>
-By default backends plugins are installed in
- <code>$HOME/.asciidoc/backends/<backend></code> where <code><backend></code> is the
- backend name.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_docbook">5. DocBook</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>AsciiDoc generates <em>article</em>, <em>book</em> and <em>refentry</em>
-<a href="https://docbook.org/">DocBook</a> documents (corresponding to the
-AsciiDoc <em>article</em>, <em>book</em> and <em>manpage</em> document types).</p></div>
-<div class="paragraph"><p>Most Linux distributions come with conversion tools (collectively
-called a toolchain) for <a href="#X12">converting DocBook files</a> to
-presentation formats such as Postscript, HTML, PDF, EPUB, DVI,
-PostScript, LaTeX, roff (the native man page format), HTMLHelp,
-JavaHelp and text. There are also programs that allow you to view
-DocBook files directly, for example
-<a href="https://wiki.gnome.org/action/show/Apps/Yelp">Yelp</a> (the GNOME help
-viewer).</p></div>
-<div class="sect2">
-<h3 id="X12">5.1. Converting DocBook to other file formats</h3>
-<div class="paragraph"><p>DocBook files are validated, parsed and translated various
-presentation file formats using a combination of applications
-collectively called a DocBook <em>tool chain</em>. 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).</p></div>
-<div class="paragraph"><p>A wide range of user output format requirements coupled with a choice
-of available tools and stylesheets results in many valid tool chain
-combinations.</p></div>
-</div>
-<div class="sect2">
-<h3 id="X43">5.2. a2x Toolchain Wrapper</h3>
-<div class="paragraph"><p>One of the biggest hurdles for new users is installing, configuring
-and using a DocBook XML toolchain. <code>a2x(1)</code> 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. <code>a2x(1)</code> does all the grunt
-work associated with generating and sequencing the toolchain commands
-and managing intermediate and output files. <code>a2x(1)</code> also optionally
-deploys admonition and navigation icons and a CSS stylesheet. See the
-<code>a2x(1)</code> man page for more details. In addition to <code>asciidoc(1)</code> you
-also need <a href="#X40">xsltproc(1)</a>, <a href="#X13">DocBook XSL Stylesheets</a> and
-optionally: <a href="#X31">dblatex</a> or <a href="#X14">FOP</a> (to generate PDF);
-<code>w3m(1)</code> or <code>lynx(1)</code> (to generate text).</p></div>
-<div class="paragraph"><p>The following examples generate <code>doc/source-highlight-filter.pdf</code> from
-the AsciiDoc <code>doc/source-highlight-filter.txt</code> source file. The first
-example uses <code>dblatex(1)</code> (the default PDF generator) the second
-example forces FOP to be used:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ a2x -f pdf doc/source-highlight-filter.txt
-$ a2x -f pdf --fop doc/source-highlight-filter.txt</code></pre>
-</div></div>
-<div class="paragraph"><p>See the <code>a2x(1)</code> man page for details.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/tip.png" alt="Tip" />
-</td>
-<td class="content">Use the <code>--verbose</code> command-line option to view executed
-toolchain commands.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_html_generation">5.3. HTML generation</h3>
-<div class="paragraph"><p>AsciiDoc produces nicely styled HTML directly without requiring a
-DocBook toolchain but there are also advantages in going the DocBook
-route:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-HTML from DocBook can optionally include automatically generated
- indexes, tables of contents, footnotes, lists of figures and tables.
-</p>
-</li>
-<li>
-<p>
-DocBook toolchains can also (optionally) generate separate (chunked)
- linked HTML pages for each document section.
-</p>
-</li>
-<li>
-<p>
-Toolchain processing performs link and document validity checks.
-</p>
-</li>
-<li>
-<p>
-If the DocBook <em>lang</em> 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 <em>lang</em>
- attribute sets the DocBook <em>lang</em> attribute).
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>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 <a href="https://asciidoc.org/">AsciiDoc
-website</a>).</p></div>
-</div>
-<div class="sect2">
-<h3 id="_pdf_generation">5.4. PDF generation</h3>
-<div class="paragraph"><p>There are two commonly used tools to generate PDFs from DocBook,
-<a href="#X31">dblatex</a> and <a href="#X14">FOP</a>.</p></div>
-<div class="ulist"><div class="title">dblatex or FOP?</div><ul>
-<li>
-<p>
-<em>dblatex</em> is easier to install, there’s zero configuration
- required and no Java VM to install — it just works out of the box.
-</p>
-</li>
-<li>
-<p>
-<em>dblatex</em> source code highlighting and numbering is superb.
-</p>
-</li>
-<li>
-<p>
-<em>dblatex</em> is easier to use as it converts DocBook directly to PDF
- whereas before using <em>FOP</em> you have to convert DocBook to XML-FO
- using <a href="#X13">DocBook XSL Stylesheets</a>.
-</p>
-</li>
-<li>
-<p>
-<em>FOP</em> is more feature complete (for example, callouts are processed
- inside literal layouts) and arguably produces nicer looking output.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="_html_help_generation">5.5. HTML Help generation</h3>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Convert DocBook XML documents to HTML Help compiler source files
- using <a href="#X13">DocBook XSL Stylesheets</a> and <a href="#X40">xsltproc(1)</a>.
-</p>
-</li>
-<li>
-<p>
-Convert the HTML Help source (<code>.hhp</code> and <code>.html</code>) files to HTML Help
- (<code>.chm</code>) files using the <a href="#X67">Microsoft HTML Help Compiler</a>.
-</p>
-</li>
-</ol></div>
-</div>
-<div class="sect2">
-<h3 id="_toolchain_components_summary">5.6. Toolchain components summary</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-AsciiDoc
-</dt>
-<dd>
-<p>
- Converts AsciiDoc (<code>.txt</code>) files to DocBook XML (<code>.xml</code>) files.
-</p>
-</dd>
-<dt class="hdlist1">
-<a id="X13"></a><a href="https://github.com/docbook/xslt10-stylesheets">DocBook XSLT Stylesheets</a>
-</dt>
-<dd>
-<p>
- 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
- <a href="#X40">xsltproc(1)</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-<a id="X40"></a><a href="http://www.xmlsoft.org">xsltproc</a>
-</dt>
-<dd>
-<p>
- An XML parser for applying XSLT stylesheets (in our case the
- <a href="#X13">DocBook XSL Stylesheets</a>) to XML documents.
-</p>
-</dd>
-<dt class="hdlist1">
-<a id="X31"></a><a href="http://dblatex.sourceforge.net/">dblatex</a>
-</dt>
-<dd>
-<p>
- Generates PDF, DVI, PostScript and LaTeX formats directly from
- DocBook source via the intermediate LaTeX typesetting language —  uses <a href="#X13">DocBook XSL Stylesheets</a>, <a href="#X40">xsltproc(1)</a> and
- <code>latex(1)</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-<a id="X14"></a><a href="https://xmlgraphics.apache.org/fop/">FOP</a>
-</dt>
-<dd>
-<p>
- The Apache Formatting Objects Processor converts XSL-FO (<code>.fo</code>)
- files to PDF files. The XSL-FO files are generated from DocBook
- source files using <a href="#X13">DocBook XSL Stylesheets</a> and
- <a href="#X40">xsltproc(1)</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-<a id="X67"></a>Microsoft Help Compiler
-</dt>
-<dd>
-<p>
- The Microsoft HTML Help Compiler (<code>hhc.exe</code>) is a command-line tool
- that converts HTML Help source files to a single HTML Help (<code>.chm</code>)
- file. It runs on MS Windows platforms and can be downloaded from
- <a href="https://www.microsoft.com/">https://www.microsoft.com/</a>.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_asciidoc_dblatex_configuration_files">5.7. AsciiDoc dblatex configuration files</h3>
-<div class="paragraph"><p>The AsciiDoc distribution <code>./dblatex</code> directory contains
-<code>asciidoc-dblatex.xsl</code> (customized XSL parameter settings) and
-<code>asciidoc-dblatex.sty</code> (customized LaTeX settings). These are examples
-of optional <a href="#X31">dblatex</a> output customization and are used by
-<a href="#X43"><code>a2x(1)</code></a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_asciidoc_docbook_xsl_stylesheets_drivers">5.8. AsciiDoc DocBook XSL Stylesheets drivers</h3>
-<div class="paragraph"><p>You will have noticed that the distributed HTML and HTML Help
-documentation files (for example <code>./doc/asciidoc.html</code>) are not the
-plain outputs produced using the default <em>DocBook XSL Stylesheets</em>
-configuration. This is because they have been processed using
-customized DocBook XSL Stylesheets along with (in the case of HTML
-outputs) the custom <code>./stylesheets/docbook-xsl.css</code> CSS stylesheet.</p></div>
-<div class="paragraph"><p>You’ll find the customized DocBook XSL drivers along with additional
-documentation in the distribution <code>./docbook-xsl</code> directory. The
-examples that follow are executed from the distribution documentation
-(<code>./doc</code>) directory. These drivers are also used by <a href="#X43"><code>a2x(1)</code></a>.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>common.xsl</code>
-</dt>
-<dd>
-<p>
- Shared driver parameters. This file is not used directly but is
- included in all the following drivers.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>chunked.xsl</code>
-</dt>
-<dd>
-<p>
- Generate chunked XHTML (separate HTML pages for each document
- section) in the <code>./doc/chunked</code> directory. For example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ python ../asciidoc.py -b docbook asciidoc.txt
-$ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-<code>epub.xsl</code>
-</dt>
-<dd>
-<p>
- Used by <a href="#X43"><code>a2x(1)</code></a> to generate EPUB formatted documents.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>fo.xsl</code>
-</dt>
-<dd>
-<p>
- Generate XSL Formatting Object (<code>.fo</code>) files for subsequent PDF
- file generation using FOP. For example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ python ../asciidoc.py -b docbook article.txt
-$ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
-$ fop article.fo article.pdf</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-<code>htmlhelp.xsl</code>
-</dt>
-<dd>
-<p>
- Generate Microsoft HTML Help source files for the MS HTML Help
- Compiler in the <code>./doc/htmlhelp</code> directory. This example is run on
- MS Windows from a Cygwin shell prompt:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ 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</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-<code>manpage.xsl</code>
-</dt>
-<dd>
-<p>
- Generate a <code>roff(1)</code> format UNIX man page from a DocBook XML
- <em>refentry</em> document. This example generates an <code>asciidoc.1</code> man
- page file:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
-$ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-<code>xhtml.xsl</code>
-</dt>
-<dd>
-<p>
- Convert a DocBook XML file to a single XHTML file. For example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ python ../asciidoc.py -b docbook asciidoc.txt
-$ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html</code></pre>
-</div></div>
-</dd>
-</dl></div>
-<div class="paragraph"><p>If you want to see how the complete documentation set is processed
-take a look at the A-A-P script <code>./doc/main.aap</code>.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_plain_text_files">6. Generating Plain Text Files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>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 <a href="#X43"><code>a2x(1)</code></a> toolchain wrapper
-utility.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X35">7. HTML5 and XHTML 1.1</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <em>xhtml11</em> and <em>html5</em> backends embed or link CSS and JavaScript
-files in their outputs, there is also a <a href="#X99">themes</a> plugin
-framework.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-If the AsciiDoc <em>linkcss</em> attribute is defined then CSS and
- JavaScript files are linked to the output document, otherwise they
- are embedded (the default behavior).
-</p>
-</li>
-<li>
-<p>
-The default locations for CSS and JavaScript files can be changed by
- setting the AsciiDoc <em>stylesdir</em> and <em>scriptsdir</em> attributes
- respectively.
-</p>
-</li>
-<li>
-<p>
-The default locations for embedded and linked files differ and are
- calculated at different times — embedded files are loaded when
- <code>asciidoc(1)</code> generates the output document, linked files are loaded
- by the browser when the user views the output document.
-</p>
-</li>
-<li>
-<p>
-Embedded files are automatically inserted in the output files but
- you need to manually copy linked CSS and Javascript files from
- AsciiDoc <a href="#X27">configuration directories</a> to the correct location
- relative to the output document.
-</p>
-</li>
-</ul></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="hsides"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 1. Stylesheet file locations</caption>
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-<thead>
-<tr>
-<th align="left" valign="top"><em>stylesdir</em> attribute</th>
-<th align="left" valign="top">Linked location (<em>linkcss</em> attribute defined)</th>
-<th align="left" valign="top">Embedded location (<em>linkcss</em> attribute undefined)</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">Undefined (default).</p></td>
-<td align="left" valign="top"><p class="table">Same directory as the output document.</p></td>
-<td align="left" valign="top"><p class="table"><code>stylesheets</code> subdirectory in the AsciiDoc configuration directory
-(the directory containing the backend conf file).</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">Absolute or relative directory name.</p></td>
-<td align="left" valign="top"><p class="table">Absolute or relative to the output document.</p></td>
-<td align="left" valign="top"><p class="table">Absolute or relative to the AsciiDoc configuration directory (the
-directory containing the backend conf file).</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="hsides"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 2. JavaScript file locations</caption>
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-<thead>
-<tr>
-<th align="left" valign="top"><em>scriptsdir</em> attribute</th>
-<th align="left" valign="top">Linked location (<em>linkcss</em> attribute defined)</th>
-<th align="left" valign="top">Embedded location (<em>linkcss</em> attribute undefined)</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">Undefined (default).</p></td>
-<td align="left" valign="top"><p class="table">Same directory as the output document.</p></td>
-<td align="left" valign="top"><p class="table"><code>javascripts</code> subdirectory in the AsciiDoc configuration directory
-(the directory containing the backend conf file).</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">Absolute or relative directory name.</p></td>
-<td align="left" valign="top"><p class="table">Absolute or relative to the output document.</p></td>
-<td align="left" valign="top"><p class="table">Absolute or relative to the AsciiDoc configuration directory (the
-directory containing the backend conf file).</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="sect2">
-<h3 id="X99">7.1. Themes</h3>
-<div class="paragraph"><p>The AsciiDoc <em>theme</em> attribute is used to select an alternative CSS
-stylesheet and to optionally include additional JavaScript code.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Theme files reside in an AsciiDoc <a href="#X27">configuration directory</a>
- named <code>themes/<theme>/</code> (where <code><theme></code> is the the theme name set
- by the <em>theme</em> attribute). <code>asciidoc(1)</code> sets the <em>themedir</em> attribute
- to the theme directory path name.
-</p>
-</li>
-<li>
-<p>
-The <em>theme</em> attribute can also be set using the <code>asciidoc(1)</code>
- <code>--theme</code> option, the <code>--theme</code> option can also be used to manage
- theme <a href="#X101">plugins</a>.
-</p>
-</li>
-<li>
-<p>
-AsciiDoc ships with two themes: <em>flask</em> and <em>volnitsky</em>.
-</p>
-</li>
-<li>
-<p>
-The <code><theme>.css</code> file replaces the default <code>asciidoc.css</code> CSS file.
-</p>
-</li>
-<li>
-<p>
-The <code><theme>.js</code> file is included in addition to the default
- <code>asciidoc.js</code> JavaScript file.
-</p>
-</li>
-<li>
-<p>
-If the <a href="#X66">data-uri</a> attribute is defined then icons are loaded
- from the theme <code>icons</code> sub-directory if it exists (i.e. the
- <em>iconsdir</em> attribute is set to theme <code>icons</code> sub-directory path).
-</p>
-</li>
-<li>
-<p>
-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.
-</p>
-</li>
-<li>
-<p>
-Linked CSS and JavaScript theme files are linked to the same linked
- locations as <a href="#X35">other CSS and JavaScript files</a>.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>For example, the command-line option <code>--theme foo</code> (or <code>--attribute
-theme=foo</code>) will cause <code>asciidoc(1)</code> to search <a href="#X27">configuration file locations 1</a> for a sub-directory called <code>themes/foo</code>
-containing the stylesheet <code>foo.css</code> and optionally a JavaScript file
-name <code>foo.js</code>.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_document_structure">8. Document Structure</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An AsciiDoc document consists of a series of <a href="#X8">block elements</a>
-starting with an optional document Header, followed by an optional
-Preamble, followed by zero or more document Sections.</p></div>
-<div class="paragraph"><p>Almost any combination of zero or more elements constitutes a valid
-AsciiDoc document: documents can range from a single sentence to a
-multi-part book.</p></div>
-<div class="sect2">
-<h3 id="_block_elements">8.1. Block Elements</h3>
-<div class="paragraph"><p>Block elements consist of one or more lines of text and may contain
-other block elements.</p></div>
-<div class="paragraph"><p>The AsciiDoc block structure can be informally summarized as follows
-<span class="footnote"><br />[This is a rough structural guide, not a rigorous syntax
-definition]<br /></span>:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Document ::= (Header?,Preamble?,Section*)
-Header ::= (Title,(AuthorInfo,RevisionInfo?)?)
-AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
-RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?)
-Preamble ::= (SectionBody)
-Section ::= (Title,SectionBody?,(Section)*)
-SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+
-Block ::= (Paragraph|DelimitedBlock|List|Table)
-List ::= (BulletedList|NumberedList|LabeledList|CalloutList)
-BulletedList ::= (ListItem)+
-NumberedList ::= (ListItem)+
-CalloutList ::= (ListItem)+
-LabeledList ::= (ListEntry)+
-ListEntry ::= (ListLabel,ListItem)
-ListLabel ::= (ListTerm+)
-ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)</code></pre>
-</div></div>
-<div class="paragraph"><p>Where:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<em>?</em> implies zero or one occurrence, <em>+</em> implies one or more
- occurrences, <em>*</em> implies zero or more occurrences.
-</p>
-</li>
-<li>
-<p>
-All block elements are separated by line boundaries.
-</p>
-</li>
-<li>
-<p>
-<code>BlockId</code>, <code>AttributeEntry</code> and <code>AttributeList</code> block elements (not
- shown) can occur almost anywhere.
-</p>
-</li>
-<li>
-<p>
-There are a number of document type and backend specific
- restrictions imposed on the block syntax.
-</p>
-</li>
-<li>
-<p>
-The following elements cannot contain blank lines: Header, Title,
- Paragraph, ItemText.
-</p>
-</li>
-<li>
-<p>
-A ListParagraph is a Paragraph with its <em>listelement</em> option set.
-</p>
-</li>
-<li>
-<p>
-A ListContinuation is a <a href="#X15">list continuation element</a>.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="X95">8.2. Header</h3>
-<div class="paragraph"><p>The Header contains document meta-data, typically title plus optional
-authorship and revision information:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The Header is optional, but if it is used it must start with a
- document <a href="#X17">title</a>.
-</p>
-</li>
-<li>
-<p>
-Optional Author and Revision information immediately follows the
- header title.
-</p>
-</li>
-<li>
-<p>
-The document header must be separated from the remainder of the
- document by one or more blank lines and cannot contain blank lines.
-</p>
-</li>
-<li>
-<p>
-The header can include comments.
-</p>
-</li>
-<li>
-<p>
-The header can include <a href="#X18">attribute entries</a>, typically
- <em>doctype</em>, <em>lang</em>, <em>encoding</em>, <em>icons</em>, <em>data-uri</em>, <em>toc</em>,
- <em>numbered</em>.
-</p>
-</li>
-<li>
-<p>
-Header attributes are overridden by command-line attributes.
-</p>
-</li>
-<li>
-<p>
-If the header contains non-UTF-8 characters then the <em>encoding</em> must
- precede the header (either in the document or on the command-line).
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Here’s an example AsciiDoc document header:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Writing Documentation using AsciiDoc
-====================================
-Joe Bloggs <jbloggs@mymail.com>
-v2.0, February 2003:
-Rewritten for version 2 release.</code></pre>
-</div></div>
-<div class="paragraph"><p>The author information line contains the author’s name optionally
-followed by the author’s email address. The author’s name is formatted
-like:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>firstname[ [middlename ]lastname][ <email>]]</code></pre>
-</div></div>
-<div class="paragraph"><p>i.e. a first name followed by optional middle and last names followed
-by an email address in that order. Multi-word first, middle and last
-names can be entered using the underscore as a word separator. The
-email address comes last and must be enclosed in angle <> brackets.
-Here a some examples of author information lines:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Joe Bloggs <jbloggs@mymail.com>
-Joe Bloggs
-Vincent Willem van_Gogh</code></pre>
-</div></div>
-<div class="paragraph"><p>If the author line does not match the above specification then the
-entire author line is treated as the first name.</p></div>
-<div class="paragraph"><p>The optional revision information line follows the author information
-line. The revision information can be one of two formats:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-An optional document revision number followed by an optional
- revision date followed by an optional revision remark:
-</p>
-<div class="openblock">
-<div class="content">
-<div class="ulist"><ul>
-<li>
-<p>
-If the revision number is specified it must be followed by a
- comma.
-</p>
-</li>
-<li>
-<p>
-The revision number must contain at least one numeric character.
-</p>
-</li>
-<li>
-<p>
-Any non-numeric characters preceding the first numeric character
- will be dropped.
-</p>
-</li>
-<li>
-<p>
-If a revision remark is specified it must be preceded by a colon.
- The revision remark extends from the colon up to the next blank
- line, attribute entry or comment and is subject to normal text
- substitutions.
-</p>
-</li>
-<li>
-<p>
-If a revision number or remark has been set but the revision date
- has not been set then the revision date is set to the value of the
- <em>docdate</em> attribute.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Examples:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>v2.0, February 2003
-February 2003
-v2.0,
-v2.0, February 2003: Rewritten for version 2 release.
-February 2003: Rewritten for version 2 release.
-v2.0,: Rewritten for version 2 release.
-:Rewritten for version 2 release.</code></pre>
-</div></div>
-</div></div>
-</li>
-<li>
-<p>
-The revision information line can also be an RCS/CVS/SVN $Id$
- marker:
-</p>
-<div class="openblock">
-<div class="content">
-<div class="ulist"><ul>
-<li>
-<p>
-AsciiDoc extracts the <em>revnumber</em>, <em>revdate</em>, and <em>author</em>
- attributes from the $Id$ revision marker and displays them in the
- document header.
-</p>
-</li>
-<li>
-<p>
-If an $Id$ revision marker is used the header author line can be
- omitted.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $</code></pre>
-</div></div>
-</div></div>
-</li>
-</ol></div>
-<div class="paragraph"><p>You can override or set header parameters by passing <em>revnumber</em>,
-<em>revremark</em>, <em>revdate</em>, <em>email</em>, <em>author</em>, <em>authorinitials</em>,
-<em>firstname</em> and <em>lastname</em> attributes using the <code>asciidoc(1)</code> <code>-a</code>
-(<code>--attribute</code>) command-line option. For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a revdate=2004/07/27 article.txt</code></pre>
-</div></div>
-<div class="paragraph"><p>Attribute entries can also be added to the header for substitution in
-the header template with <a href="#X18">Attribute Entry</a> elements.</p></div>
-<div class="paragraph"><p>The <em>title</em> element in HTML outputs is set to the AsciiDoc document
-title, you can set it to a different value by including a <em>title</em>
-attribute entry in the document header.</p></div>
-<div class="sect3">
-<h4 id="X87">8.2.1. Additional document header information</h4>
-<div class="paragraph"><p>AsciiDoc has two mechanisms for optionally including additional
-meta-data in the header of the output document:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<em>docinfo</em> configuration file sections
-</dt>
-<dd>
-<p>
-If a <a href="#X7">configuration file</a> section named <em>docinfo</em> has been loaded
-then it will be included in the document header. Typically the
-<em>docinfo</em> section name will be prefixed with a <em>+</em> character so that it
-is appended to (rather than replace) other <em>docinfo</em> sections.
-</p>
-</dd>
-<dt class="hdlist1">
-<em>docinfo</em> files
-</dt>
-<dd>
-<p>
-Two docinfo files are recognized: one named <code>docinfo</code> and a second
-named like the AsciiDoc source file with a <code>-docinfo</code> suffix. For
-example, if the source document is called <code>mydoc.txt</code> then the
-document information files would be <code>docinfo.xml</code> and
-<code>mydoc-docinfo.xml</code> (for DocBook outputs) and <code>docinfo.html</code> and
-<code>mydoc-docinfo.html</code> (for HTML outputs). The <a href="#X97">docinfo</a> attributes control which docinfo files are included in
-the output files.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The contents docinfo templates and files is dependent on the type of
-output:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-HTML
-</dt>
-<dd>
-<p>
- Valid <em>head</em> child elements. Typically <em>style</em> and <em>script</em> elements
- for CSS and JavaScript inclusion.
-</p>
-</dd>
-<dt class="hdlist1">
-DocBook
-</dt>
-<dd>
-<p>
- Valid <em>articleinfo</em> or <em>bookinfo</em> child elements. DocBook defines
- numerous elements for document meta-data, for example: copyrights,
- document history and authorship information. See the DocBook
- <code>./doc/article-docinfo.xml</code> example that comes with the AsciiDoc
- distribution. The rendering of meta-data elements (or not) is
- DocBook processor dependent.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="X86">8.3. Preamble</h3>
-<div class="paragraph"><p>The Preamble is an optional untitled section body between the document
-Header and the first Section title.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sections">8.4. Sections</h3>
-<div class="paragraph"><p>In addition to the document title (level 0), AsciiDoc supports four
-section levels: 1 (top) to 4 (bottom). Section levels are delimited
-by section <a href="#X17">titles</a>. Sections are translated using
-configuration file <a href="#X93">section markup templates</a>. AsciiDoc
-generates the following <a href="#X60">intrinsic attributes</a> specifically for
-use in section markup templates:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-level
-</dt>
-<dd>
-<p>
-The <code>level</code> attribute is the section level number, it is normally just
-the <a href="#X17">title</a> level number (1..4). However, if the <code>leveloffset</code>
-attribute is defined it will be added to the <code>level</code> attribute. The
-<code>leveloffset</code> attribute is useful for <a href="#X90">combining documents</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-sectnum
-</dt>
-<dd>
-<p>
-The <code>-n</code> (<code>--section-numbers</code>) command-line option generates the
-<code>sectnum</code> (section number) attribute. The <code>sectnum</code> attribute is used
-for section numbers in HTML outputs (DocBook section numbering are
-handled automatically by the DocBook toolchain commands).
-</p>
-</dd>
-</dl></div>
-<div class="sect3">
-<h4 id="X93">8.4.1. Section markup templates</h4>
-<div class="paragraph"><p>Section markup templates specify output markup and are defined in
-AsciiDoc configuration files. Section markup template names are
-derived as follows (in order of precedence):</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-From the title’s first positional attribute or <em>template</em>
- attribute. For example, the following three section titles are
- functionally equivalent:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>[[terms]]
-[glossary]
-List of Terms
--------------
-
-["glossary",id="terms"]
-List of Terms
--------------
-
-[template="glossary",id="terms"]
-List of Terms
--------------</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-When the title text matches a configuration file
- <a href="#X16"><code>[specialsections]</code></a> entry.
-</p>
-</li>
-<li>
-<p>
-If neither of the above the default <code>sect<level></code> template is used
- (where <code><level></code> is a number from 1 to 4).
-</p>
-</li>
-</ol></div>
-<div class="paragraph"><p>In addition to the normal section template names (<em>sect1</em>, <em>sect2</em>,
-<em>sect3</em>, <em>sect4</em>) AsciiDoc has the following templates for
-frontmatter, backmatter and other special sections: <em>abstract</em>,
-<em>preface</em>, <em>colophon</em>, <em>dedication</em>, <em>glossary</em>, <em>bibliography</em>,
-<em>synopsis</em>, <em>appendix</em>, <em>index</em>. These special section templates
-generate the corresponding Docbook elements; for HTML outputs they
-default to the <em>sect1</em> section template.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_section_ids">8.4.2. Section IDs</h4>
-<div class="paragraph"><p>If no explicit section ID is specified an ID will be synthesised from
-the section title. The primary purpose of this feature is to ensure
-persistence of table of contents links (permalinks): the missing
-section IDs are generated dynamically by the JavaScript TOC generator
-<strong>after</strong> the page is loaded. If you link to a dynamically generated TOC
-address the page will load but the browser will ignore the (as yet
-ungenerated) section ID.</p></div>
-<div class="paragraph"><p>The IDs are generated by the following algorithm:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Replace all non-alphanumeric title characters with underscores.
-</p>
-</li>
-<li>
-<p>
-Strip leading or trailing underscores.
-</p>
-</li>
-<li>
-<p>
-Convert to lowercase.
-</p>
-</li>
-<li>
-<p>
-Prepend the <code>idprefix</code> attribute (so there’s no possibility of name
- clashes with existing document IDs). Prepend an underscore if the
- <code>idprefix</code> attribute is not defined.
-</p>
-</li>
-<li>
-<p>
-A numbered suffix (<code>_2</code>, <code>_3</code> …) is added if a same named
- auto-generated section ID exists.
-</p>
-</li>
-<li>
-<p>
-If the <code>ascii-ids</code> attribute is defined then non-ASCII characters
- are replaced with ASCII equivalents. This attribute should be
- <strong>should be avoided</strong> if possible as its sole purpose is to accommodate
- deficient downstream applications that cannot process non-ASCII ID
- attributes. If available, it will use the
- <a href="https://pypi.org/project/trans/">trans python module</a>, otherwise it
- will fallback to using NFKD algorithm, which cannot handle all
- unicode characters. For example, <em>Wstęp żółtej łąki</em> will be
- translated to <em>Wstep zoltej laki</em> under trans and <em>Wstep zotej aki</em>
- under NFKD.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Example: the title <em>Jim’s House</em> would generate the ID <code>_jim_s_house</code>.</p></div>
-<div class="paragraph"><p>Section ID synthesis can be disabled by undefining the <code>sectids</code>
-attribute.</p></div>
-</div>
-<div class="sect3">
-<h4 id="X16">8.4.3. Special Section Titles</h4>
-<div class="paragraph"><p>AsciiDoc has a mechanism for mapping predefined section titles
-auto-magically to specific markup templates. For example a title
-<em>Appendix A: Code Reference</em> will automatically use the <em>appendix</em>
-<a href="#X93">section markup template</a>. The mappings from title to template
-name are specified in <code>[specialsections]</code> sections in the Asciidoc
-language configuration files (<code>lang-*.conf</code>). Section entries are
-formatted like:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code><title>=<template></code></pre>
-</div></div>
-<div class="paragraph"><p><code><title></code> is a Python regular expression and <code><template></code> is the name
-of a configuration file markup template section. If the <code><title></code>
-matches an AsciiDoc document section title then the backend output is
-marked up using the <code><template></code> markup template (instead of the
-default <code>sect<level></code> section template). The <code>{title}</code> attribute value
-is set to the value of the matched regular expression group named
-<em>title</em>, if there is no <em>title</em> group <code>{title}</code> defaults to the whole
-of the AsciiDoc section title. If <code><template></code> is blank then any
-existing entry with the same <code><title></code> will be deleted.</p></div>
-<div class="sidebarblock">
-<div class="content">
-<div class="title">Special section titles vs. explicit template names</div>
-<div class="paragraph"><p>AsciiDoc has two mechanisms for specifying non-default section markup
-templates: you can specify the template name explicitly (using the
-<em>template</em> attribute) or indirectly (using <em>special section titles</em>).
-Specifying a <a href="#X93">section template</a> attribute explicitly is
-preferred. Auto-magical <em>special section titles</em> have the following
-drawbacks:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-They are non-obvious, you have to know the exact matching
- title for each special section on a language by language basis.
-</p>
-</li>
-<li>
-<p>
-Section titles are predefined and can only be customised with a
- configuration change.
-</p>
-</li>
-<li>
-<p>
-The implementation is complicated by multiple languages: every
- special section title has to be defined for each language (in each
- of the <code>lang-*.conf</code> files).
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Specifying special section template names explicitly does add more
-noise to the source document (the <em>template</em> attribute declaration),
-but the intention is obvious and the syntax is consistent with other
-AsciiDoc elements c.f. bibliographic, Q&A and glossary lists.</p></div>
-<div class="paragraph"><p>Special section titles have been deprecated but are retained for
-backward compatibility.</p></div>
-</div></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_inline_elements">8.5. Inline Elements</h3>
-<div class="paragraph"><p><a href="#X34">Inline document elements</a> are used to format text and to
-perform various types of text substitution. Inline elements and inline
-element syntax is defined in the <code>asciidoc(1)</code> configuration files.</p></div>
-<div class="paragraph"><p>Here is a list of AsciiDoc inline elements in the (default) order in
-which they are processed:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Special characters
-</dt>
-<dd>
-<p>
- These character sequences escape special characters used by
- the backend markup (typically <code><</code>, <code>></code>, and <code>&</code> characters).
- See <code>[specialcharacters]</code> configuration file sections.
-</p>
-</dd>
-<dt class="hdlist1">
-Quotes
-</dt>
-<dd>
-<p>
- Elements that markup words and phrases; usually for character
- formatting. See <code>[quotes]</code> configuration file sections.
-</p>
-</dd>
-<dt class="hdlist1">
-Special Words
-</dt>
-<dd>
-<p>
- Word or word phrase patterns singled out for markup without
- the need for further annotation. See <code>[specialwords]</code>
- configuration file sections.
-</p>
-</dd>
-<dt class="hdlist1">
-Replacements
-</dt>
-<dd>
-<p>
- Each replacement defines a word or word phrase pattern to
- search for along with corresponding replacement text. See
- <code>[replacements]</code> configuration file sections.
-</p>
-</dd>
-<dt class="hdlist1">
-Attribute references
-</dt>
-<dd>
-<p>
- Document attribute names enclosed in braces are replaced by
- the corresponding attribute value.
-</p>
-</dd>
-<dt class="hdlist1">
-Inline Macros
-</dt>
-<dd>
-<p>
- Inline macros are replaced by the contents of parametrized
- configuration file sections.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_document_processing">9. Document Processing</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The AsciiDoc source document is read and processed as follows:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-The document <em>Header</em> is parsed, header parameter values are
- substituted into the configuration file <code>[header]</code> template section
- which is then written to the output file.
-</p>
-</li>
-<li>
-<p>
-Each document <em>Section</em> is processed and its constituent elements
- translated to the output file.
-</p>
-</li>
-<li>
-<p>
-The configuration file <code>[footer]</code> template section is substituted
- and written to the output file.
-</p>
-</li>
-</ol></div>
-<div class="paragraph"><p>When a block element is encountered <code>asciidoc(1)</code> determines the type of
-block by checking in the following order (first to last): (section)
-Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys,
-AttributeLists, BlockTitles, Paragraphs.</p></div>
-<div class="paragraph"><p>The default paragraph definition <code>[paradef-default]</code> is last element
-to be checked.</p></div>
-<div class="paragraph"><p>Knowing the parsing order will help you devise unambiguous macro, list
-and block syntax rules.</p></div>
-<div class="paragraph"><p>Inline substitutions within block elements are performed in the
-following default order:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Special characters
-</p>
-</li>
-<li>
-<p>
-Quotes
-</p>
-</li>
-<li>
-<p>
-Special words
-</p>
-</li>
-<li>
-<p>
-Replacements
-</p>
-</li>
-<li>
-<p>
-Attributes
-</p>
-</li>
-<li>
-<p>
-Inline Macros
-</p>
-</li>
-<li>
-<p>
-Replacements2
-</p>
-</li>
-</ol></div>
-<div class="paragraph"><p>The substitutions and substitution order performed on
-Title, Paragraph and DelimitedBlock elements is determined by
-configuration file parameters.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_text_formatting">10. Text Formatting</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="X51">10.1. Quoted Text</h3>
-<div class="paragraph"><p>Words and phrases can be formatted by enclosing inline text with
-quote characters:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<em>Emphasized text</em>
-</dt>
-<dd>
-<p>
- Word phrases 'enclosed in single quote characters' (acute
- accents) or _underline characters_ are emphasized.
-</p>
-</dd>
-<dt class="hdlist1">
-<strong>Strong text</strong>
-</dt>
-<dd>
-<p>
- Word phrases *enclosed in asterisk characters* are rendered
- in a strong font (usually bold).
-</p>
-</dd>
-<dt class="hdlist1">
-<a id="X81"></a><code>Monospaced text</code>
-</dt>
-<dd>
-<p>
- Word phrases +enclosed in plus characters+ are rendered in a
- monospaced font. Word phrases `enclosed in backtick
- characters` (grave accents) are also rendered in a monospaced
- font but in this case the enclosed text is rendered literally
- and is not subject to further expansion (see <a href="#X80">inline literal passthrough</a>).
-</p>
-</dd>
-<dt class="hdlist1">
-‘Single quoted text’
-</dt>
-<dd>
-<p>
- Phrases enclosed with a `single grave accent to the left and
- a single acute accent to the right' are rendered in single
- quotation marks.
-</p>
-</dd>
-<dt class="hdlist1">
-“Double quoted text”
-</dt>
-<dd>
-<p>
- Phrases enclosed with ``two grave accents to the left and
- two acute accents to the right'' are rendered in quotation
- marks.
-</p>
-</dd>
-<dt class="hdlist1">
-Unquoted text
-</dt>
-<dd>
-<p>
- Placing #hashes around text# does nothing, it is a mechanism
- to allow inline attributes to be applied to otherwise
- unformatted text.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>New quote types can be defined by editing <code>asciidoc(1)</code> configuration
-files. See the <a href="#X7">Configuration Files</a> section for details.</p></div>
-<div class="ulist"><div class="title">Quoted text behavior</div><ul>
-<li>
-<p>
-Quoting cannot be overlapped.
-</p>
-</li>
-<li>
-<p>
-Different quoting types can be nested.
-</p>
-</li>
-<li>
-<p>
-To suppress quoted text formatting place a backslash character
- immediately in front of the leading quote character(s). In the case
- of ambiguity between escaped and non-escaped text you will need to
- escape both leading and trailing quotes, in the case of
- multi-character quotes you may even need to escape individual
- characters.
-</p>
-</li>
-</ul></div>
-<div class="sect3">
-<h4 id="X96">10.1.1. Quoted text attributes</h4>
-<div class="paragraph"><p>Quoted text can be prefixed with an <a href="#X21">attribute list</a>. The first
-positional attribute (<em>role</em> attribute) is translated by AsciiDoc to
-an HTML <em>span</em> element <em>class</em> attribute or a DocBook <em>phrase</em> element
-<em>role</em> attribute.</p></div>
-<div class="paragraph"><p>DocBook XSL Stylesheets translate DocBook <em>phrase</em> elements with
-<em>role</em> attributes to corresponding HTML <em>span</em> elements with the same
-<em>class</em> attributes; CSS can then be used
-<a href="http://www.sagehill.net/docbookxsl/UsingCSS.html">to style the
-generated HTML</a>. Thus CSS styling can be applied to both DocBook and
-AsciiDoc generated HTML outputs. You can also specify multiple class
-names separated by spaces.</p></div>
-<div class="paragraph"><p>CSS rules for text color, text background color, text size and text
-decorators are included in the distributed AsciiDoc CSS files and are
-used in conjunction with AsciiDoc <em>xhtml11</em>, <em>html5</em> and <em>docbook</em>
-outputs. The CSS class names are:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<em><color></em> (text foreground color).
-</p>
-</li>
-<li>
-<p>
-<em><color>-background</em> (text background color).
-</p>
-</li>
-<li>
-<p>
-<em>big</em> and <em>small</em> (text size).
-</p>
-</li>
-<li>
-<p>
-<em>underline</em>, <em>overline</em> and <em>line-through</em> (strike through) text
- decorators.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Where <em><color></em> can be any of the
-<a href="https://en.wikipedia.org/wiki/Web_colors#HTML_color_names">sixteen HTML
-color names</a>. Examples:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[red]#Obvious# and [big red yellow-background]*very obvious*.</code></pre>
-</div></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[underline]#Underline text#, [overline]#overline text# and
-[blue line-through]*bold blue and line-through*.</code></pre>
-</div></div>
-<div class="paragraph"><p>is rendered as:</p></div>
-<div class="paragraph"><p><span class="red">Obvious</span> and <strong><span class="big red yellow-background">very obvious</span></strong>.</p></div>
-<div class="paragraph"><p><span class="underline">Underline text</span>, <span class="overline">overline text</span> and
-<strong><span class="bold blue line-through">bold blue and line-through</span></strong>.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">Color and text decorator attributes are rendered for XHTML and
-HTML 5 outputs using CSS stylesheets. The mechanism to implement
-color and text decorator attributes is provided for DocBook toolchains
-via the DocBook <em>phrase</em> element <em>role</em> attribute, but the actual
-rendering is toolchain specific and is not part of the AsciiDoc
-distribution.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect3">
-<h4 id="X52">10.1.2. Constrained and Unconstrained Quotes</h4>
-<div class="paragraph"><p>There are actually two types of quotes:</p></div>
-<div class="sect4">
-<h5 id="_constrained_quotes">Constrained quotes</h5>
-<div class="paragraph"><p>Quoted must be bounded by white space or commonly adjoining
-punctuation characters. These are the most commonly used type of
-quote.</p></div>
-</div>
-<div class="sect4">
-<h5 id="_unconstrained_quotes">Unconstrained quotes</h5>
-<div class="paragraph"><p>Unconstrained quotes have no boundary constraints and can be placed
-anywhere within inline text. For consistency and to make them easier
-to remember unconstrained quotes are double-ups of the <code>_</code>, <code>*</code>, <code>+</code>
-and <code>#</code> constrained quotes:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>__unconstrained emphasized text__
-**unconstrained strong text**
-++unconstrained monospaced text++
-##unconstrained unquoted text##</code></pre>
-</div></div>
-<div class="paragraph"><p>The following example emboldens the letter F:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>**F**ile Open...</code></pre>
-</div></div>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_superscripts_and_subscripts">10.2. Superscripts and Subscripts</h3>
-<div class="paragraph"><p>Put ^carets on either^ side of the text to be superscripted, put
-~tildes on either side~ of text to be subscripted. For example, the
-following line:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>e^&#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
-and ~some sub text~</code></pre>
-</div></div>
-<div class="paragraph"><p>Is rendered like:</p></div>
-<div class="paragraph"><p>e<sup>πi</sup>+1 = 0. H<sub>2</sub>O and x<sup>10</sup>. Some <sup>super text</sup>
-and <sub>some sub text</sub></p></div>
-<div class="paragraph"><p>Superscripts and subscripts are implemented as <a href="#X52">unconstrained quotes</a> and they can be escaped with a leading backslash and prefixed
-with with an attribute list.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_line_breaks">10.3. Line Breaks</h3>
-<div class="paragraph"><p>A plus character preceded by at least one space character at the end
-of a non-blank line forces a line break. It generates a line break
-(<code>br</code>) tag for HTML outputs and a custom XML <code>asciidoc-br</code> processing
-instruction for DocBook outputs. The <code>asciidoc-br</code> processing
-instruction is handled by <a href="#X43"><code>a2x(1)</code></a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_page_breaks">10.4. Page Breaks</h3>
-<div class="paragraph"><p>A line of three or more less-than (<code><<<</code>) characters will generate a
-hard page break in DocBook and printed HTML outputs. It uses the CSS
-<code>page-break-after</code> property for HTML outputs and a custom XML
-<code>asciidoc-pagebreak</code> processing instruction for DocBook outputs. The
-<code>asciidoc-pagebreak</code> processing instruction is handled by
-<a href="#X43"><code>a2x(1)</code></a>. Hard page breaks are sometimes handy but as a general
-rule you should let your page processor generate page breaks for you.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_rulers">10.5. Rulers</h3>
-<div class="paragraph"><p>A line of three or more apostrophe characters will generate a ruler
-line. It generates a ruler (<code>hr</code>) tag for HTML outputs and a custom
-XML <code>asciidoc-hr</code> processing instruction for DocBook outputs. The
-<code>asciidoc-hr</code> processing instruction is handled by <a href="#X43"><code>a2x(1)</code></a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_tabs">10.6. Tabs</h3>
-<div class="paragraph"><p>By default tab characters input files will translated to 8 spaces. Tab
-expansion is set with the <em>tabsize</em> entry in the configuration file
-<code>[miscellaneous]</code> section and can be overridden in included files by
-setting a <em>tabsize</em> attribute in the <code>include</code> macro’s attribute list.
-For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>include::addendum.txt[tabsize=2]</code></pre>
-</div></div>
-<div class="paragraph"><p>The tab size can also be set using the attribute command-line option,
-for example <code>--attribute tabsize=4</code></p></div>
-</div>
-<div class="sect2">
-<h3 id="_replacements">10.7. Replacements</h3>
-<div class="paragraph"><p>The following replacements are defined in the default AsciiDoc
-configuration:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>(C) copyright, (TM) trademark, (R) registered trademark,
--- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
-double arrow, <= left double arrow.</code></pre>
-</div></div>
-<div class="paragraph"><p>Which are rendered as:</p></div>
-<div class="paragraph"><p>© copyright, ™ trademark, ® registered trademark, — em dash, … ellipsis, → right arrow, ← left arrow, ⇒ right
-double arrow, ⇐ left double arrow.</p></div>
-<div class="paragraph"><p>You can also include arbitrary entity references in the AsciiDoc
-source. Examples:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>&#x278a; &#182;</code></pre>
-</div></div>
-<div class="paragraph"><p>renders:</p></div>
-<div class="paragraph"><p>➊ ¶</p></div>
-<div class="paragraph"><p>To render a replacement literally escape it with a leading back-slash.</p></div>
-<div class="paragraph"><p>The <a href="#X7">Configuration Files</a> section explains how to configure your
-own replacements.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_special_words">10.8. Special Words</h3>
-<div class="paragraph"><p>Words defined in <code>[specialwords]</code> configuration file sections are
-automatically marked up without having to be explicitly notated.</p></div>
-<div class="paragraph"><p>The <a href="#X7">Configuration Files</a> section explains how to add and replace
-special words.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X17">11. Titles</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Document and section titles can be in either of two formats:</p></div>
-<div class="sect2">
-<h3 id="_two_line_titles">11.1. Two line titles</h3>
-<div class="paragraph"><p>A two line title consists of a title line, starting hard against the
-left margin, and an underline. Section underlines consist a repeated
-character pairs spanning the width of the preceding title (give or
-take up to two characters):</p></div>
-<div class="paragraph"><p>The default title underlines for each of the document levels are:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Level 0 (top level): ======================
-Level 1: ----------------------
-Level 2: ~~~~~~~~~~~~~~~~~~~~~~
-Level 3: ^^^^^^^^^^^^^^^^^^^^^^
-Level 4 (bottom level): ++++++++++++++++++++++</code></pre>
-</div></div>
-<div class="paragraph"><p>Examples:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Level One Section Title
------------------------</code></pre>
-</div></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Level 2 Subsection Title
-~~~~~~~~~~~~~~~~~~~~~~~~</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="X46">11.2. One line titles</h3>
-<div class="paragraph"><p>One line titles consist of a single line delimited on either side by
-one or more equals characters (the number of equals characters
-corresponds to the section level minus one). Here are some examples:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>= Document Title (level 0) =
-== Section title (level 1) ==
-=== Section title (level 2) ===
-==== Section title (level 3) ====
-===== Section title (level 4) =====</code></pre>
-</div></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">
-<div class="ulist"><ul>
-<li>
-<p>
-One or more spaces must fall between the title and the delimiters.
-</p>
-</li>
-<li>
-<p>
-The trailing title delimiter is optional.
-</p>
-</li>
-<li>
-<p>
-The one-line title syntax can be changed by editing the
- configuration file <code>[titles]</code> section <code>sect0</code>…<code>sect4</code> entries.
-</p>
-</li>
-</ul></div>
-</td>
-</tr></table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_floating_titles">11.3. Floating titles</h3>
-<div class="paragraph"><p>Setting the title’s first positional attribute or <em>style</em> attribute to
-<em>float</em> generates a free-floating title. A free-floating title is
-rendered just like a normal section title but is not formally
-associated with a text body and is not part of the regular section
-hierarchy so the normal ordering rules do not apply. Floating titles
-can also be used in contexts where section titles are illegal: for
-example sidebar and admonition blocks. Example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[float]
-The second day
-~~~~~~~~~~~~~~</code></pre>
-</div></div>
-<div class="paragraph"><p>Floating titles do not appear in a document’s table of contents.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X42">12. Block Titles</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <em>BlockTitle</em> element is a single line beginning with a period
-followed by the title text. A BlockTitle is applied to the immediately
-following Paragraph, DelimitedBlock, List, Table or BlockMacro. For
-example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>.Notes
-- Note 1.
-- Note 2.</code></pre>
-</div></div>
-<div class="paragraph"><p>is rendered as:</p></div>
-<div class="ulist"><div class="title">Notes</div><ul>
-<li>
-<p>
-Note 1.
-</p>
-</li>
-<li>
-<p>
-Note 2.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X41">13. BlockId Element</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <em>BlockId</em> is a single line block element containing a unique
-identifier enclosed in double square brackets. It is used to assign an
-identifier to the ensuing block element. For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[[chapter-titles]]
-Chapter titles can be ...</code></pre>
-</div></div>
-<div class="paragraph"><p>The preceding example identifies the ensuing paragraph so it can be
-referenced from other locations, for example with
-<code><<chapter-titles,chapter titles>></code>.</p></div>
-<div class="paragraph"><p><em>BlockId</em> elements can be applied to Title, Paragraph, List,
-DelimitedBlock, Table and BlockMacro elements. The BlockId element
-sets the <code>{id}</code> attribute for substitution in the subsequent block’s
-markup template. If a second positional argument is supplied it sets
-the <code>{reftext}</code> attribute which is used to set the DocBook <code>xreflabel</code>
-attribute.</p></div>
-<div class="paragraph"><p>The <em>BlockId</em> element has the same syntax and serves the same function
-to the <a href="#X30">anchor inline macro</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X79">14. AttributeList Element</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <em>AttributeList</em> block element is an <a href="#X21">attribute list</a> on a
-line by itself:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<em>AttributeList</em> attributes are only applied to the immediately
- following block element — the attributes are made available to the
- block’s markup template.
-</p>
-</li>
-<li>
-<p>
-Multiple contiguous <em>AttributeList</em> elements are additively combined
- in the order they appear.
-</p>
-</li>
-<li>
-<p>
-The first positional attribute in the list is often used to specify
- the ensuing element’s <a href="#X23">style</a>.
-</p>
-</li>
-</ul></div>
-<div class="sect2">
-<h3 id="_attribute_value_substitution">14.1. Attribute value substitution</h3>
-<div class="paragraph"><p>By default, only substitutions that take place inside attribute list
-values are attribute references, this is because not all attributes
-are destined to be marked up and rendered as text (for example the
-table <em>cols</em> attribute). To perform normal inline text substitutions
-(special characters, quotes, macros, replacements) on an attribute
-value you need to enclose it in single quotes. In the following quote
-block the second attribute value in the AttributeList is quoted to
-ensure the <em>http</em> macro is expanded to a hyperlink.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[quote,'https://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]']
-_____________________________________________________________________
-Sir, a woman's preaching is like a dog's walking on his hind legs. It
-is not done well; but you are surprised to find it done at all.
-_____________________________________________________________________</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_common_attributes">14.2. Common attributes</h3>
-<div class="paragraph"><p>Most block elements support the following attributes:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="hsides"
-cellspacing="0" cellpadding="4">
-<col width="14%" />
-<col width="14%" />
-<col width="71%" />
-<thead>
-<tr>
-<th align="left" valign="top">Name </th>
-<th align="left" valign="top">Backends </th>
-<th align="left" valign="top">Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table"><em>id</em></p></td>
-<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Unique identifier typically serve as link targets.
-Can also be set by the <em>BlockId</em> element.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>role</em></p></td>
-<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Role contains a string used to classify or subclassify an element and
-can be applied to AsciiDoc block elements. The AsciiDoc <em>role</em>
-attribute is translated to the <em>role</em> attribute in DocBook outputs and
-is included in the <em>class</em> attribute in HTML outputs, in this respect
-it behaves like the <a href="#X96">quoted text role attribute</a>.</p></div>
-<div class="paragraph"><p>DocBook XSL Stylesheets translate DocBook <em>role</em> attributes to HTML
-<em>class</em> attributes; CSS can then be used
-<a href="http://www.sagehill.net/docbookxsl/UsingCSS.html">to style the
-generated HTML</a>.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>reftext</em></p></td>
-<td align="left" valign="top"><p class="table">docbook</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p><em>reftext</em> is used to set the DocBook <em>xreflabel</em> attribute.
-The <em>reftext</em> attribute can an also be set by the <em>BlockId</em> element.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>floatstyle</em></p></td>
-<td align="left" valign="top"><p class="table">docbook</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p><em>floatstyle</em> is used to specify the floatstyle attribute for the
-titled table, example, image and equation blocks. This is useful when
-used in conjuction with the dblatex toolchain. A typical example
-would be to specify the value as <em>floatstyle="[htbp]"</em>.</p></div></div></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_paragraphs">15. Paragraphs</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Paragraphs are blocks of text terminated by a blank line, the end of
-file, or the start of a delimited block or a list. There are three
-paragraph syntaxes: normal, indented (literal) and admonition which
-are rendered, by default, with the corresponding paragraph style.</p></div>
-<div class="paragraph"><p>Each syntax has a default style, but you can explicitly apply any
-paragraph style to any paragraph syntax. You can also apply
-<a href="#X104">delimited block</a> styles to single paragraphs.</p></div>
-<div class="paragraph"><p>The built-in paragraph styles are: <em>normal</em>, <em>literal</em>, <em>verse</em>,
-<em>quote</em>, <em>listing</em>, <em>TIP</em>, <em>NOTE</em>, <em>IMPORTANT</em>, <em>WARNING</em>, <em>CAUTION</em>,
-<em>abstract</em>, <em>partintro</em>, <em>comment</em>, <em>example</em>, <em>sidebar</em>, <em>source</em>,
-<em>music</em>, <em>latex</em>, <em>graphviz</em>.</p></div>
-<div class="sect2">
-<h3 id="_normal_paragraph_syntax">15.1. normal paragraph syntax</h3>
-<div class="paragraph"><p>Normal paragraph syntax consists of one or more non-blank lines of
-text. The first line must start hard against the left margin (no
-intervening white space). The default processing expectation is that
-of a normal paragraph of text.</p></div>
-</div>
-<div class="sect2">
-<h3 id="X85">15.2. literal paragraph syntax</h3>
-<div class="paragraph"><p>Literal paragraphs are rendered verbatim in a monospaced font without
-any distinguishing background or border. By default there is no text
-formatting or substitutions within Literal paragraphs apart from
-Special Characters and Callouts.</p></div>
-<div class="paragraph"><p>The <em>literal</em> style is applied implicitly to indented paragraphs i.e.
-where the first line of the paragraph is indented by one or more space
-or tab characters. For example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code> Consul *necessitatibus* per id,
- consetetur, eu pro everti postulant
- homero verear ea mea, qui.</code></pre>
-</div></div>
-<div class="paragraph"><p>Renders:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Consul *necessitatibus* per id,
-consetetur, eu pro everti postulant
-homero verear ea mea, qui.</code></pre>
-</div></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">Because <a href="#X64">lists</a> can be indented it’s possible for your
-indented paragraph to be misinterpreted as a list — in situations
-like this apply the <em>literal</em> style to a normal paragraph.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>Instead of using a paragraph indent you could apply the <em>literal</em>
-style explicitly, for example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[literal]
-Consul *necessitatibus* per id,
-consetetur, eu pro everti postulant
-homero verear ea mea, qui.</code></pre>
-</div></div>
-<div class="paragraph"><p>Renders:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Consul *necessitatibus* per id,
-consetetur, eu pro everti postulant
-homero verear ea mea, qui.</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="X94">15.3. quote and verse paragraph styles</h3>
-<div class="paragraph"><p>The optional <em>attribution</em> and <em>citetitle</em> attributes (positional
-attributes 2 and 3) specify the author and source respectively.</p></div>
-<div class="paragraph"><p>The <em>verse</em> style retains the line breaks, for example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[verse, William Blake, from Auguries of Innocence]
-To see a world in a grain of sand,
-And a heaven in a wild flower,
-Hold infinity in the palm of your hand,
-And eternity in an hour.</code></pre>
-</div></div>
-<div class="paragraph"><p>Which is rendered as:</p></div>
-<div class="verseblock">
-<pre class="content">To see a world in a grain of sand,
-And a heaven in a wild flower,
-Hold infinity in the palm of your hand,
-And eternity in an hour.</pre>
-<div class="attribution">
-<em>from Auguries of Innocence</em><br />
-— William Blake
-</div></div>
-<div class="paragraph"><p>The <em>quote</em> style flows the text at left and right margins, for
-example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[quote, Bertrand Russell, The World of Mathematics (1956)]
-A good notation has subtlety and suggestiveness which at times makes
-it almost seem like a live teacher.</code></pre>
-</div></div>
-<div class="paragraph"><p>Which is rendered as:</p></div>
-<div class="quoteblock">
-<div class="content">A good notation has subtlety and suggestiveness which at times makes
-it almost seem like a live teacher.</div>
-<div class="attribution">
-<em>The World of Mathematics (1956)</em><br />
-— Bertrand Russell
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="X28">15.4. Admonition Paragraphs</h3>
-<div class="paragraph"><p><em>TIP</em>, <em>NOTE</em>, <em>IMPORTANT</em>, <em>WARNING</em> and <em>CAUTION</em> admonishment
-paragraph styles are generated by placing <code>NOTE:</code>, <code>TIP:</code>,
-<code>IMPORTANT:</code>, <code>WARNING:</code> or <code>CAUTION:</code> as the first word of the
-paragraph. For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>NOTE: This is an example note.</code></pre>
-</div></div>
-<div class="paragraph"><p>Alternatively, you can specify the paragraph admonition style
-explicitly using an <a href="#X79">AttributeList element</a>. For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[NOTE]
-This is an example note.</code></pre>
-</div></div>
-<div class="paragraph"><p>Renders:</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">This is an example note.</td>
-</tr></table>
-</div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/tip.png" alt="Tip" />
-</td>
-<td class="content">If your admonition requires more than a single paragraph use an
-<a href="#X22">admonition block</a> instead.</td>
-</tr></table>
-</div>
-<div class="sect3">
-<h4 id="X47">15.4.1. Admonition Icons and Captions</h4>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">Admonition customization with <code>icons</code>, <code>iconsdir</code>, <code>icon</code> and
-<code>caption</code> attributes does not apply when generating DocBook output. If
-you are going the DocBook route then the <a href="#X43"><code>a2x(1)</code></a> <code>--no-icons</code>
-and <code>--icons-dir</code> options can be used to set the appropriate XSL
-Stylesheets parameters.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>By default the <code>asciidoc(1)</code> HTML backends generate text captions
-instead of admonition icon image links. To generate links to icon
-images define the <a href="#X45"><code>icons</code></a> attribute, for example using the <code>-a
-icons</code> command-line option.</p></div>
-<div class="paragraph"><p>The <a href="#X44"><code>iconsdir</code></a> attribute sets the location of linked icon
-images.</p></div>
-<div class="paragraph"><p>You can override the default icon image using the <code>icon</code> attribute to
-specify the path of the linked image. For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[icon="./images/icons/wink.png"]
-NOTE: What lovely war.</code></pre>
-</div></div>
-<div class="paragraph"><p>Use the <code>caption</code> attribute to customize the admonition captions (not
-applicable to <code>docbook</code> backend). The following example suppresses the
-icon image and customizes the caption of a <em>NOTE</em> admonition
-(undefining the <code>icons</code> attribute with <code>icons=None</code> is only necessary
-if <a href="#X45">admonition icons</a> have been enabled):</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[icons=None, caption="My Special Note"]
-NOTE: This is my special note.</code></pre>
-</div></div>
-<div class="paragraph"><p>This subsection also applies to <a href="#X22">Admonition Blocks</a>.</p></div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X104">16. Delimited Blocks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Delimited blocks are blocks of text enveloped by leading and trailing
-delimiter lines (normally a series of four or more repeated
-characters). The behavior of Delimited Blocks is specified by entries
-in configuration file <code>[blockdef-*]</code> sections.</p></div>
-<div class="sect2">
-<h3 id="_predefined_delimited_blocks">16.1. Predefined Delimited Blocks</h3>
-<div class="paragraph"><p>AsciiDoc ships with a number of predefined DelimitedBlocks (see the
-<code>asciidoc.conf</code> configuration file in the <code>asciidoc(1)</code> program
-directory):</p></div>
-<div class="paragraph"><p>Predefined delimited block underlines:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>CommentBlock: //////////////////////////
-PassthroughBlock: ++++++++++++++++++++++++++
-ListingBlock: --------------------------
-LiteralBlock: ..........................
-SidebarBlock: **************************
-QuoteBlock: __________________________
-ExampleBlock: ==========================
-OpenBlock: --</code></pre>
-</div></div>
-<div class="tableblock">
-<table rules="all"
-frame="hsides"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 3. Default DelimitedBlock substitutions</caption>
-<col />
-<col />
-<col />
-<col />
-<col />
-<col />
-<col />
-<col />
-<thead>
-<tr>
-<th align="left" valign="top"> </th>
-<th align="center" valign="top">Attributes </th>
-<th align="center" valign="top">Callouts </th>
-<th align="center" valign="top">Macros </th>
-<th align="center" valign="top"> Quotes </th>
-<th align="center" valign="top">Replacements</th>
-<th align="center" valign="top">Special chars </th>
-<th align="center" valign="top">Special words</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table"><em>PassthroughBlock</em></p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>ListingBlock</em></p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>LiteralBlock</em></p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>SidebarBlock</em></p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>QuoteBlock</em></p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>ExampleBlock</em></p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>OpenBlock</em></p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">No</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-<td align="center" valign="top"><p class="table">Yes</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_listing_blocks">16.2. Listing Blocks</h3>
-<div class="paragraph"><p><em>ListingBlocks</em> are rendered verbatim in a monospaced font, they
-retain line and whitespace formatting and are often distinguished by a
-background or border. There is no text formatting or substitutions
-within Listing blocks apart from Special Characters and Callouts.
-Listing blocks are often used for computer output and file listings.</p></div>
-<div class="paragraph"><p>Here’s an example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>--------------------------------------
-#include <stdio.h>
-
-int main() {
- printf("Hello World!\n");
- exit(0);
-}
---------------------------------------</code></pre>
-</div></div>
-<div class="paragraph"><p>Which will be rendered like:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>#include <stdio.h>
-
-int main() {
- printf("Hello World!\n");
- exit(0);
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>By convention <a href="#X59">filter blocks</a> use the listing block syntax and
-are implemented as distinct listing block styles.</p></div>
-</div>
-<div class="sect2">
-<h3 id="X65">16.3. Literal Blocks</h3>
-<div class="paragraph"><p><em>LiteralBlocks</em> are rendered just like <a href="#X85">literal paragraphs</a>.
-Example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>...................................
-Consul *necessitatibus* per id,
-consetetur, eu pro everti postulant
-homero verear ea mea, qui.
-...................................</code></pre>
-</div></div>
-<div class="paragraph"><p>Renders:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Consul *necessitatibus* per id,
-consetetur, eu pro everti postulant
-homero verear ea mea, qui.</code></pre>
-</div></div>
-<div class="paragraph"><p>If the <em>listing</em> style is applied to a LiteralBlock it will be
-rendered as a ListingBlock (this is handy if you have a listing
-containing a ListingBlock).</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sidebar_blocks">16.4. Sidebar Blocks</h3>
-<div class="paragraph"><p>A sidebar is a short piece of text presented outside the narrative
-flow of the main text. The sidebar is normally presented inside a
-bordered box to set it apart from the main text.</p></div>
-<div class="paragraph"><p>The sidebar body is treated like a normal section body.</p></div>
-<div class="paragraph"><p>Here’s an example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>.An Example Sidebar
-************************************************
-Any AsciiDoc SectionBody element (apart from
-SidebarBlocks) can be placed inside a sidebar.
-************************************************</code></pre>
-</div></div>
-<div class="paragraph"><p>Which will be rendered like:</p></div>
-<div class="sidebarblock">
-<div class="content">
-<div class="title">An Example Sidebar</div>
-<div class="paragraph"><p>Any AsciiDoc SectionBody element (apart from
-SidebarBlocks) can be placed inside a sidebar.</p></div>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="X26">16.5. Comment Blocks</h3>
-<div class="paragraph"><p>The contents of <em>CommentBlocks</em> are not processed; they are useful for
-annotations and for excluding new or outdated content that you don’t
-want displayed. CommentBlocks are never written to output files.
-Example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>//////////////////////////////////////////
-CommentBlock contents are not processed by
-asciidoc(1).
-//////////////////////////////////////////</code></pre>
-</div></div>
-<div class="paragraph"><p>See also <a href="#X25">Comment Lines</a>.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">System macros are executed inside comment blocks.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="X76">16.6. Passthrough Blocks</h3>
-<div class="paragraph"><p>By default the block contents is subject only to <em>attributes</em> and
-<em>macros</em> substitutions (use an explicit <em>subs</em> attribute to apply
-different substitutions). PassthroughBlock content will often be
-backend specific. Here’s an example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[subs="quotes"]
-++++++++++++++++++++++++++++++++++++++
-<table border="1"><tr>
- <td>*Cell 1*</td>
- <td>*Cell 2*</td>
-</tr></table>
-++++++++++++++++++++++++++++++++++++++</code></pre>
-</div></div>
-<div class="paragraph"><p>The following styles can be applied to passthrough blocks:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-pass
-</dt>
-<dd>
-<p>
- No substitutions are performed. This is equivalent to <code>subs="none"</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-asciimath, latexmath
-</dt>
-<dd>
-<p>
- By default no substitutions are performed, the contents are rendered
- as <a href="#X78">mathematical formulas</a>.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_quote_blocks">16.7. Quote Blocks</h3>
-<div class="paragraph"><p><em>QuoteBlocks</em> are used for quoted passages of text. There are two
-styles: <em>quote</em> and <em>verse</em>. The style behavior is identical to
-<a href="#X94">quote and verse paragraphs</a> except that blocks can contain
-multiple paragraphs and, in the case of the <em>quote</em> style, other
-section elements. The first positional attribute sets the style, if
-no attributes are specified the <em>quote</em> style is used. The optional
-<em>attribution</em> and <em>citetitle</em> attributes (positional attributes 2 and
-3) specify the quote’s author and source. For example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]
-____________________________________________________________________
-As he spoke there was the sharp sound of horses' hoofs and
-grating wheels against the curb, followed by a sharp pull at the
-bell. Holmes whistled.
-
-"A pair, by the sound," said he. "Yes," he continued, glancing
-out of the window. "A nice little brougham and a pair of
-beauties. A hundred and fifty guineas apiece. There's money in
-this case, Watson, if there is nothing else."
-____________________________________________________________________</code></pre>
-</div></div>
-<div class="paragraph"><p>Which is rendered as:</p></div>
-<div class="quoteblock">
-<div class="content">
-<div class="paragraph"><p>As he spoke there was the sharp sound of horses' hoofs and
-grating wheels against the curb, followed by a sharp pull at the
-bell. Holmes whistled.</p></div>
-<div class="paragraph"><p>"A pair, by the sound," said he. "Yes," he continued, glancing
-out of the window. "A nice little brougham and a pair of
-beauties. A hundred and fifty guineas apiece. There’s money in
-this case, Watson, if there is nothing else."</p></div>
-</div>
-<div class="attribution">
-<em>The Adventures of Sherlock Holmes</em><br />
-— Sir Arthur Conan Doyle
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="X48">16.8. Example Blocks</h3>
-<div class="paragraph"><p><em>ExampleBlocks</em> encapsulate the DocBook Example element and are used
-for, well, examples. Example blocks can be titled by preceding them
-with a <em>BlockTitle</em>. DocBook toolchains will normally automatically
-number examples and generate a <em>List of Examples</em> backmatter section.</p></div>
-<div class="paragraph"><p>Example blocks are delimited by lines of equals characters and can
-contain any block elements apart from Titles, BlockTitles and
-Sidebars) inside an example block. For example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>.An example
-=====================================================================
-Qui in magna commodo, est labitur dolorum an. Est ne magna primis
-adolescens.
-=====================================================================</code></pre>
-</div></div>
-<div class="paragraph"><p>Renders:</p></div>
-<div class="exampleblock">
-<div class="title">Example 1. An example</div>
-<div class="content">
-<div class="paragraph"><p>Qui in magna commodo, est labitur dolorum an. Est ne magna primis
-adolescens.</p></div>
-</div></div>
-<div class="paragraph"><p>A title prefix that can be inserted with the <code>caption</code> attribute
-(HTML backends). For example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[caption="Example 1: "]
-.An example with a custom caption
-=====================================================================
-Qui in magna commodo, est labitur dolorum an. Est ne magna primis
-adolescens.
-=====================================================================</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="X22">16.9. Admonition Blocks</h3>
-<div class="paragraph"><p>The <em>ExampleBlock</em> definition includes a set of admonition
-<a href="#X23">styles</a> (<em>NOTE</em>, <em>TIP</em>, <em>IMPORTANT</em>, <em>WARNING</em>, <em>CAUTION</em>) for
-generating admonition blocks (admonitions containing more than a
-<a href="#X28">single paragraph</a>). Just precede the <em>ExampleBlock</em> with an
-attribute list specifying the admonition style name. For example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[NOTE]
-.A NOTE admonition block
-=====================================================================
-Qui in magna commodo, est labitur dolorum an. Est ne magna primis
-adolescens.
-
-. Fusce euismod commodo velit.
-. Vivamus fringilla mi eu lacus.
- .. Fusce euismod commodo velit.
- .. Vivamus fringilla mi eu lacus.
-. Donec eget arcu bibendum
- nunc consequat lobortis.
-=====================================================================</code></pre>
-</div></div>
-<div class="paragraph"><p>Renders:</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">
-<div class="title">A NOTE admonition block</div>
-<div class="paragraph"><p>Qui in magna commodo, est labitur dolorum an. Est ne magna primis
-adolescens.</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Fusce euismod commodo velit.
-</p>
-</li>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-<div class="olist loweralpha"><ol class="loweralpha">
-<li>
-<p>
-Fusce euismod commodo velit.
-</p>
-</li>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-</li>
-</ol></div>
-</li>
-<li>
-<p>
-Donec eget arcu bibendum
- nunc consequat lobortis.
-</p>
-</li>
-</ol></div>
-</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>See also <a href="#X47">Admonition Icons and Captions</a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="X29">16.10. Open Blocks</h3>
-<div class="paragraph"><p>Open blocks are special:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The open block delimiter is line containing two hyphen characters
- (instead of four or more repeated characters).
-</p>
-</li>
-<li>
-<p>
-They can be used to group block elements for <a href="#X15">List item continuation</a>.
-</p>
-</li>
-<li>
-<p>
-Open blocks can be styled to behave like any other type of delimited
- block. The following built-in styles can be applied to open
- blocks: <em>literal</em>, <em>verse</em>, <em>quote</em>, <em>listing</em>, <em>TIP</em>, <em>NOTE</em>,
- <em>IMPORTANT</em>, <em>WARNING</em>, <em>CAUTION</em>, <em>abstract</em>, <em>partintro</em>,
- <em>comment</em>, <em>example</em>, <em>sidebar</em>, <em>source</em>, <em>music</em>, <em>latex</em>,
- <em>graphviz</em>. For example, the following open block and listing block
- are functionally identical:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>[listing]
---
-Lorum ipsum ...
---</code></pre>
-</div></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>---------------
-Lorum ipsum ...
----------------</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-An unstyled open block groups section elements but otherwise does
- nothing.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Open blocks are used to generate document abstracts and book part
-introductions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Apply the <em>abstract</em> style to generate an abstract, for example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>[abstract]
---
-In this paper we will ...
---</code></pre>
-</div></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Apply the <em>partintro</em> style to generate a book part introduction for
- a multi-part book, for example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>[partintro]
-.Optional part introduction title
---
-Optional part introduction goes here.
---</code></pre>
-</div></div>
-</li>
-</ol></div>
-</li>
-</ul></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X64">17. Lists</h2>
-<div class="sectionbody">
-<div class="ulist"><div class="title">List types</div><ul>
-<li>
-<p>
-Bulleted lists. Also known as itemized or unordered lists.
-</p>
-</li>
-<li>
-<p>
-Numbered lists. Also called ordered lists.
-</p>
-</li>
-<li>
-<p>
-Labeled lists. Sometimes called variable or definition lists.
-</p>
-</li>
-<li>
-<p>
-Callout lists (a list of callout annotations).
-</p>
-</li>
-</ul></div>
-<div class="ulist"><div class="title">List behavior</div><ul>
-<li>
-<p>
-List item indentation is optional and does not determine nesting,
- indentation does however make the source more readable.
-</p>
-</li>
-<li>
-<p>
-Another list or a literal paragraph immediately following a list
- item will be implicitly included in the list item; use <a href="#X15">list item continuation</a> to explicitly append other block elements to a
- list item.
-</p>
-</li>
-<li>
-<p>
-A comment block or a comment line block macro element will terminate
- a list — use inline comment lines to put comments inside lists.
-</p>
-</li>
-<li>
-<p>
-The <code>listindex</code> <a href="#X60">intrinsic attribute</a> is the current list item
- index (1..). If this attribute is used outside a list then it’s value
- is the number of items in the most recently closed list. Useful for
- displaying the number of items in a list.
-</p>
-</li>
-</ul></div>
-<div class="sect2">
-<h3 id="_bulleted_lists">17.1. Bulleted Lists</h3>
-<div class="paragraph"><p>Bulleted list items start with a single dash or one to five asterisks
-followed by some white space then some text. Bulleted list syntaxes
-are:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>- List item.
-* List item.
-** List item.
-*** List item.
-**** List item.
-***** List item.</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_numbered_lists">17.2. Numbered Lists</h3>
-<div class="paragraph"><p>List item numbers are explicit or implicit.</p></div>
-<div class="paragraph"><div class="title">Explicit numbering</div><p>List items begin with a number followed by some white space then the
-item text. The numbers can be decimal (arabic), roman (upper or lower
-case) or alpha (upper or lower case). Decimal and alpha numbers are
-terminated with a period, roman numbers are terminated with a closing
-parenthesis. The different terminators are necessary to ensure <em>i</em>,
-<em>v</em> and <em>x</em> roman numbers are are distinguishable from <em>x</em>, <em>v</em> and
-<em>x</em> alpha numbers. Examples:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>1. Arabic (decimal) numbered list item.
-a. Lower case alpha (letter) numbered list item.
-F. Upper case alpha (letter) numbered list item.
-iii) Lower case roman numbered list item.
-IX) Upper case roman numbered list item.</code></pre>
-</div></div>
-<div class="paragraph"><div class="title">Implicit numbering</div><p>List items begin one to five period characters, followed by some white
-space then the item text. Examples:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>. Arabic (decimal) numbered list item.
-.. Lower case alpha (letter) numbered list item.
-... Lower case roman numbered list item.
-.... Upper case alpha (letter) numbered list item.
-..... Upper case roman numbered list item.</code></pre>
-</div></div>
-<div class="paragraph"><p>You can use the <em>style</em> attribute (also the first positional
-attribute) to specify an alternative numbering style. The numbered
-list style can be one of the following values: <em>arabic</em>, <em>loweralpha</em>,
-<em>upperalpha</em>, <em>lowerroman</em>, <em>upperroman</em>.</p></div>
-<div class="paragraph"><p>Here are some examples of bulleted and numbered lists:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>- Praesent eget purus quis magna eleifend eleifend.
- 1. Fusce euismod commodo velit.
- a. Fusce euismod commodo velit.
- b. Vivamus fringilla mi eu lacus.
- c. Donec eget arcu bibendum nunc consequat lobortis.
- 2. Vivamus fringilla mi eu lacus.
- i) Fusce euismod commodo velit.
- ii) Vivamus fringilla mi eu lacus.
- 3. Donec eget arcu bibendum nunc consequat lobortis.
- 4. Nam fermentum mattis ante.
-- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
- * Fusce euismod commodo velit.
- ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
- adolescens. Sit munere ponderum dignissim et. Minim luptatum et
- vel.
- ** Vivamus fringilla mi eu lacus.
- * Donec eget arcu bibendum nunc consequat lobortis.
-- Nulla porttitor vulputate libero.
- . Fusce euismod commodo velit.
- . Vivamus fringilla mi eu lacus.
-[upperroman]
- .. Fusce euismod commodo velit.
- .. Vivamus fringilla mi eu lacus.
- . Donec eget arcu bibendum nunc consequat lobortis.</code></pre>
-</div></div>
-<div class="paragraph"><p>Which render as:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Praesent eget purus quis magna eleifend eleifend.
-</p>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Fusce euismod commodo velit.
-</p>
-<div class="olist loweralpha"><ol class="loweralpha">
-<li>
-<p>
-Fusce euismod commodo velit.
-</p>
-</li>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-</li>
-<li>
-<p>
-Donec eget arcu bibendum nunc consequat lobortis.
-</p>
-</li>
-</ol></div>
-</li>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-<div class="olist lowerroman"><ol class="lowerroman">
-<li>
-<p>
-Fusce euismod commodo velit.
-</p>
-</li>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-</li>
-</ol></div>
-</li>
-<li>
-<p>
-Donec eget arcu bibendum nunc consequat lobortis.
-</p>
-</li>
-<li>
-<p>
-Nam fermentum mattis ante.
-</p>
-</li>
-</ol></div>
-</li>
-<li>
-<p>
-Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-Fusce euismod commodo velit.
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-Qui in magna commodo, est labitur dolorum an. Est ne magna primis
- adolescens. Sit munere ponderum dignissim et. Minim luptatum et
- vel.
-</p>
-</li>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
-Donec eget arcu bibendum nunc consequat lobortis.
-</p>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
-Nulla porttitor vulputate libero.
-</p>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Fusce euismod commodo velit.
-</p>
-</li>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-<div class="olist upperroman"><ol class="upperroman">
-<li>
-<p>
-Fusce euismod commodo velit.
-</p>
-</li>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-</li>
-</ol></div>
-</li>
-<li>
-<p>
-Donec eget arcu bibendum nunc consequat lobortis.
-</p>
-</li>
-</ol></div>
-</li>
-</ul></div>
-<div class="paragraph"><p>A predefined <em>compact</em> option is available to bulleted and numbered
-lists — this translates to the DocBook <em>spacing="compact"</em> lists
-attribute which may or may not be processed by the DocBook toolchain.
-Example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[options="compact"]
-- Compact list item.
-- Another compact list item.</code></pre>
-</div></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/tip.png" alt="Tip" />
-</td>
-<td class="content">To apply the <em>compact</em> option globally define a document-wide
-<em>compact-option</em> attribute, e.g. using the <code>-a compact-option</code>
-command-line option.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>You can set the list start number using the <em>start</em> attribute (works
-for HTML outputs and DocBook outputs processed by DocBook XSL
-Stylesheets). Example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[start=7]
-. List item 7.
-. List item 8.</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_labeled_lists">17.3. Labeled Lists</h3>
-<div class="paragraph"><p>Labeled list items consist of one or more text labels followed by the
-text of the list item.</p></div>
-<div class="paragraph"><p>An item label begins a line with an alphanumeric character hard
-against the left margin and ends with two, three or four colons or two
-semi-colons. A list item can have multiple labels, one per line.</p></div>
-<div class="paragraph"><p>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.</p></div>
-<div class="paragraph"><p>Here are some examples:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>In::
-Lorem::
- Fusce euismod commodo velit.
-
- Fusce euismod commodo velit.
-
-Ipsum:: Vivamus fringilla mi eu lacus.
- * Vivamus fringilla mi eu lacus.
- * Donec eget arcu bibendum nunc consequat lobortis.
-Dolor::
- Donec eget arcu bibendum nunc consequat lobortis.
- Suspendisse;;
- A massa id sem aliquam auctor.
- Morbi;;
- Pretium nulla vel lorem.
- In;;
- Dictum mauris in urna.
- Vivamus::: Fringilla mi eu lacus.
- Donec::: Eget arcu bibendum nunc consequat lobortis.</code></pre>
-</div></div>
-<div class="paragraph"><p>Which render as:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-In
-</dt>
-<dt class="hdlist1">
-Lorem
-</dt>
-<dd>
-<p>
- Fusce euismod commodo velit.
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>Fusce euismod commodo velit.</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-Ipsum
-</dt>
-<dd>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-</li>
-<li>
-<p>
-Donec eget arcu bibendum nunc consequat lobortis.
-</p>
-</li>
-</ul></div>
-</dd>
-<dt class="hdlist1">
-Dolor
-</dt>
-<dd>
-<p>
- Donec eget arcu bibendum nunc consequat lobortis.
-</p>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Suspendisse
-</dt>
-<dd>
-<p>
- A massa id sem aliquam auctor.
-</p>
-</dd>
-<dt class="hdlist1">
-Morbi
-</dt>
-<dd>
-<p>
- Pretium nulla vel lorem.
-</p>
-</dd>
-<dt class="hdlist1">
-In
-</dt>
-<dd>
-<p>
- Dictum mauris in urna.
-</p>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Vivamus
-</dt>
-<dd>
-<p>
-Fringilla mi eu lacus.
-</p>
-</dd>
-<dt class="hdlist1">
-Donec
-</dt>
-<dd>
-<p>
-Eget arcu bibendum nunc consequat lobortis.
-</p>
-</dd>
-</dl></div>
-</dd>
-</dl></div>
-</dd>
-</dl></div>
-<div class="sect3">
-<h4 id="_horizontal_labeled_list_style">17.3.1. Horizontal labeled list style</h4>
-<div class="paragraph"><p>The <em>horizontal</em> labeled list style (also the first positional
-attribute) places the list text side-by-side with the label instead of
-under the label. Here is an example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[horizontal]
-*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
-labitur dolorum an. Est ne magna primis adolescens.
-
- Fusce euismod commodo velit.
-
-*Ipsum*:: Vivamus fringilla mi eu lacus.
-- Vivamus fringilla mi eu lacus.
-- Donec eget arcu bibendum nunc consequat lobortis.
-
-*Dolor*::
- - Vivamus fringilla mi eu lacus.
- - Donec eget arcu bibendum nunc consequat lobortis.</code></pre>
-</div></div>
-<div class="paragraph"><p>Which render as:</p></div>
-<div class="hdlist"><table>
-<tr>
-<td class="hdlist1">
-<strong>Lorem</strong>
-<br />
-</td>
-<td class="hdlist2">
-<p style="margin-top: 0;">
-Fusce euismod commodo velit. Qui in magna commodo, est
-labitur dolorum an. Est ne magna primis adolescens.
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>Fusce euismod commodo velit.</code></pre>
-</div></div>
-</td>
-</tr>
-<tr>
-<td class="hdlist1">
-<strong>Ipsum</strong>
-<br />
-</td>
-<td class="hdlist2">
-<p style="margin-top: 0;">
-Vivamus fringilla mi eu lacus.
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-</li>
-<li>
-<p>
-Donec eget arcu bibendum nunc consequat lobortis.
-</p>
-</li>
-</ul></div>
-</td>
-</tr>
-<tr>
-<td class="hdlist1">
-<strong>Dolor</strong>
-<br />
-</td>
-<td class="hdlist2">
-<div class="ulist"><ul>
-<li>
-<p>
-Vivamus fringilla mi eu lacus.
-</p>
-</li>
-<li>
-<p>
-Donec eget arcu bibendum nunc consequat lobortis.
-</p>
-</li>
-</ul></div>
-</td>
-</tr>
-</table></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">
-<div class="ulist"><ul>
-<li>
-<p>
-Current PDF toolchains do not make a good job of determining
- the relative column widths for horizontal labeled lists.
-</p>
-</li>
-<li>
-<p>
-Nested horizontal labeled lists will generate DocBook validation
- errors because the <em>DocBook XML V4.2</em> DTD does not permit nested
- informal tables (although <a href="#X13">DocBook XSL Stylesheets</a> and
- <a href="#X31">dblatex</a> process them correctly).
-</p>
-</li>
-<li>
-<p>
-The label width can be set as a percentage of the total width by
- setting the <em>width</em> attribute e.g. <code>width="10%"</code>
-</p>
-</li>
-</ul></div>
-</td>
-</tr></table>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_question_and_answer_lists">17.4. Question and Answer Lists</h3>
-<div class="paragraph"><p>AsciiDoc comes pre-configured with a <em>qanda</em> style labeled list for generating
-DocBook question and answer (Q&A) lists. Example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[qanda]
-Question one::
- Answer one.
-Question two::
- Answer two.</code></pre>
-</div></div>
-<div class="paragraph"><p>Renders:</p></div>
-<div class="qlist qanda"><ol>
-<li>
-<p><em>
-Question one
-</em></p>
-<p>
- Answer one.
-</p>
-</li>
-<li>
-<p><em>
-Question two
-</em></p>
-<p>
- Answer two.
-</p>
-</li>
-</ol></div>
-</div>
-<div class="sect2">
-<h3 id="_glossary_lists">17.5. Glossary Lists</h3>
-<div class="paragraph"><p>AsciiDoc comes pre-configured with a <em>glossary</em> style labeled list for
-generating DocBook glossary lists. Example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[glossary]
-A glossary term::
- The corresponding definition.
-A second glossary term::
- The corresponding definition.</code></pre>
-</div></div>
-<div class="paragraph"><p>For working examples see the <code>article.txt</code> and <code>book.txt</code> documents in
-the AsciiDoc <code>./doc</code> distribution directory.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">To generate valid DocBook output glossary lists must be located
-in a section that uses the <em>glossary</em> <a href="#X93">section markup template</a>.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_bibliography_lists">17.6. Bibliography Lists</h3>
-<div class="paragraph"><p>AsciiDoc comes with a predefined <em>bibliography</em> bulleted list style
-generating DocBook bibliography entries. Example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[bibliography]
-.Optional list title
-- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
- Programming'. Addison-Wesley. ISBN 0-13-142901-9.
-- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
- 'DocBook - The Definitive Guide'. O'Reilly & Associates. 1999.
- ISBN 1-56592-580-7.</code></pre>
-</div></div>
-<div class="paragraph"><p>The <code>[[[<reference>]]]</code> syntax is a bibliography entry anchor, it
-generates an anchor named <code><reference></code> and additionally displays
-<code>[<reference>]</code> at the anchor position. For example <code>[[[taoup]]]</code>
-generates an anchor named <code>taoup</code> that displays <code>[taoup]</code> at the
-anchor position. Cite the reference from elsewhere your document using
-<code><<taoup>></code>, this displays a hyperlink (<code>[taoup]</code>) to the
-corresponding bibliography entry anchor.</p></div>
-<div class="paragraph"><p>For working examples see the <code>article.txt</code> and <code>book.txt</code> documents in
-the AsciiDoc <code>./doc</code> distribution directory.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">To generate valid DocBook output bibliography lists must be
-located in a <a href="#X93">bibliography section</a>.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="X15">17.7. List Item Continuation</h3>
-<div class="paragraph"><p>Another list or a literal paragraph immediately following a list item
-is implicitly appended to the list item; to append other block
-elements to a list item you need to explicitly join them to the list
-item with a <em>list continuation</em> (a separator line containing a single
-plus character). Multiple block elements can be appended to a list
-item using list continuations (provided they are legal list item
-children in the backend markup).</p></div>
-<div class="paragraph"><p>Here are some examples of list item continuations: list item one
-contains multiple continuations; list item two is continued with an
-<a href="#X29">OpenBlock</a> containing multiple elements:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>1. List item one.
-+
-List item one continued with a second paragraph followed by an
-Indented block.
-+
-.................
-$ ls *.sh
-$ mv *.sh ~/tmp
-.................
-+
-List item continued with a third paragraph.
-
-2. List item two continued with an open block.
-+
---
-This paragraph is part of the preceding list item.
-
-a. This list is nested and does not require explicit item continuation.
-+
-This paragraph is part of the preceding list item.
-
-b. List item b.
-
-This paragraph belongs to item two of the outer list.
---</code></pre>
-</div></div>
-<div class="paragraph"><p>Renders:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-List item one.
-</p>
-<div class="paragraph"><p>List item one continued with a second paragraph followed by an
-Indented block.</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ ls *.sh
-$ mv *.sh ~/tmp</code></pre>
-</div></div>
-<div class="paragraph"><p>List item continued with a third paragraph.</p></div>
-</li>
-<li>
-<p>
-List item two continued with an open block.
-</p>
-<div class="openblock">
-<div class="content">
-<div class="paragraph"><p>This paragraph is part of the preceding list item.</p></div>
-<div class="olist loweralpha"><ol class="loweralpha">
-<li>
-<p>
-This list is nested and does not require explicit item continuation.
-</p>
-<div class="paragraph"><p>This paragraph is part of the preceding list item.</p></div>
-</li>
-<li>
-<p>
-List item b.
-</p>
-</li>
-</ol></div>
-<div class="paragraph"><p>This paragraph belongs to item two of the outer list.</p></div>
-</div></div>
-</li>
-</ol></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X92">18. Footnotes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The shipped AsciiDoc configuration includes three footnote inline
-macros:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>footnote:[<text>]</code>
-</dt>
-<dd>
-<p>
- Generates a footnote with text <code><text></code>.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>footnoteref:[<id>,<text>]</code>
-</dt>
-<dd>
-<p>
- Generates a footnote with a reference ID <code><id></code> and text <code><text></code>.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>footnoteref:[<id>]</code>
-</dt>
-<dd>
-<p>
- Generates a reference to the footnote with ID <code><id></code>.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The footnote text can span multiple lines.</p></div>
-<div class="paragraph"><p>The <em>xhtml11</em> and <em>html5</em> backends render footnotes dynamically using
-JavaScript; <em>html4</em> outputs do not use JavaScript and leave the
-footnotes inline; <em>docbook</em> footnotes are processed by the downstream
-DocBook toolchain.</p></div>
-<div class="paragraph"><p>Example footnotes:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>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].</code></pre>
-</div></div>
-<div class="paragraph"><p>Renders:</p></div>
-<div class="paragraph"><p>A footnote <span class="footnote"><br />[An example footnote.]<br /></span>;
-a second footnote with a reference ID <span class="footnote" id="_footnote_note2"><br />[Second footnote.]<br /></span>;
-finally a reference to the second footnote <span class="footnoteref"><br /><a href="#_footnote_note2">[note2]</a><br /></span>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_indexes">19. Indexes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The shipped AsciiDoc configuration includes the inline macros for
-generating DocBook index entries.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>indexterm:[<primary>,<secondary>,<tertiary>]</code>
-</dt>
-<dt class="hdlist1">
-<code>(((<primary>,<secondary>,<tertiary>)))</code>
-</dt>
-<dd>
-<p>
- This inline macro generates an index term (the <code><secondary></code> and
- <code><tertiary></code> positional attributes are optional). Example:
- <code>indexterm:[Tigers,Big cats]</code> (or, using the alternative syntax
- <code>(((Tigers,Big cats)))</code>. Index terms that have secondary and
- tertiary entries also generate separate index terms for the
- secondary and tertiary entries. The index terms appear in the
- index, not the primary text flow.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>indexterm2:[<primary>]</code>
-</dt>
-<dt class="hdlist1">
-<code>((<primary>))</code>
-</dt>
-<dd>
-<p>
- This inline macro generates an index term that appears in both the
- index and the primary text flow. The <code><primary></code> should not be
- padded to the left or right with white space characters.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>For working examples see the <code>article.txt</code> and <code>book.txt</code> documents in
-the AsciiDoc <code>./doc</code> distribution directory.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">Index entries only really make sense if you are generating
-DocBook markup — DocBook conversion programs automatically generate
-an index at the point an <em>Index</em> section appears in source document.</td>
-</tr></table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X105">20. Callouts</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Callouts are a mechanism for annotating verbatim text (for example:
-source code, computer output and user input). Callout markers are
-placed inside the annotated text while the actual annotations are
-presented in a callout list after the annotated text. Here’s an
-example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code> .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.</code></pre>
-</div></div>
-<div class="paragraph"><p>Which renders:</p></div>
-<div class="listingblock">
-<div class="title">MS-DOS directory listing</div>
-<div class="content">
-<pre><code>10/17/97 9:04 <DIR> bin
-10/16/97 14:11 <DIR> DOS <img src="./images/icons/callouts/1.png" alt="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 <img src="./images/icons/callouts/2.png" alt="2" />
- 2/13/94 6:21 54,619 COMMAND.COM <img src="./images/icons/callouts/2.png" alt="2" />
-10/16/97 14:25 115 CONFIG.SYS <img src="./images/icons/callouts/2.png" alt="2" />
-11/16/97 17:17 61,865,984 pagefile.sys
- 2/13/94 6:21 9,349 WINA20.386 <img src="./images/icons/callouts/3.png" alt="3" /></code></pre>
-</div></div>
-<div class="colist arabic"><table>
-<tr><td><img src="./images/icons/callouts/1.png" alt="1" /></td><td>
-This directory holds MS-DOS.
-</td></tr>
-<tr><td><img src="./images/icons/callouts/2.png" alt="2" /></td><td>
-System startup code for DOS.
-</td></tr>
-<tr><td><img src="./images/icons/callouts/3.png" alt="3" /></td><td>
-Some sort of Windows 3.1 hack.
-</td></tr>
-</table></div>
-<div class="ulist"><div class="title">Explanation</div><ul>
-<li>
-<p>
-The callout marks are whole numbers enclosed in angle brackets —  they refer to the correspondingly numbered item in the following
- callout list.
-</p>
-</li>
-<li>
-<p>
-By default callout marks are confined to <em>LiteralParagraphs</em>,
- <em>LiteralBlocks</em> and <em>ListingBlocks</em> (although this is a
- configuration file option and can be changed).
-</p>
-</li>
-<li>
-<p>
-Callout list item numbering is fairly relaxed — list items can
- start with <code><n></code>, <code>n></code> or <code>></code> where <code>n</code> is the optional list item
- number (in the latter case list items starting with a single <code>></code>
- character are implicitly numbered starting at one).
-</p>
-</li>
-<li>
-<p>
-Callout lists should not be nested.
-</p>
-</li>
-<li>
-<p>
-Callout lists cannot be used within tables.
-</p>
-</li>
-<li>
-<p>
-Callout lists start list items hard against the left margin.
-</p>
-</li>
-<li>
-<p>
-If you want to present a number inside angle brackets you’ll need to
- escape it with a backslash to prevent it being interpreted as a
- callout mark.
-</p>
-</li>
-</ul></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">Define the AsciiDoc <em>icons</em> attribute (for example using the <code>-a
-icons</code> command-line option) to display callout icons.</td>
-</tr></table>
-</div>
-<div class="sect2">
-<h3 id="_implementation_notes">20.1. Implementation Notes</h3>
-<div class="paragraph"><p>Callout marks are generated by the <em>callout</em> inline macro while
-callout lists are generated using the <em>callout</em> list definition. The
-<em>callout</em> macro and <em>callout</em> list are special in that they work
-together. The <em>callout</em> inline macro is not enabled by the normal
-<em>macros</em> substitutions option, instead it has its own <em>callouts</em>
-substitution option.</p></div>
-<div class="paragraph"><p>The following attributes are available during inline callout macro
-substitution:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>{index}</code>
-</dt>
-<dd>
-<p>
- The callout list item index inside the angle brackets.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{coid}</code>
-</dt>
-<dd>
-<p>
- An identifier formatted like <code>CO<listnumber>-<index></code> that
- uniquely identifies the callout mark. For example <code>CO2-4</code>
- identifies the fourth callout mark in the second set of callout
- marks.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The <code>{coids}</code> attribute can be used during callout list item
-substitution — it is a space delimited list of callout IDs that refer
-to the explanatory list item.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_including_callouts_in_included_code">20.2. Including callouts in included code</h3>
-<div class="paragraph"><p>You can annotate working code examples with callouts — just remember
-to put the callouts inside source code comments. This example displays
-the <code>test.py</code> source file (containing a single callout) using the
-<em>source</em> (code highlighter) filter:</p></div>
-<div class="listingblock">
-<div class="title">AsciiDoc source</div>
-<div class="content">
-<pre><code> [source,python]
- -------------------------------------------
- \include::test.py[]
- -------------------------------------------
-
- <1> Print statement.</code></pre>
-</div></div>
-<div class="listingblock">
-<div class="title">Included <code>test.py</code> source</div>
-<div class="content">
-<pre><code>print 'Hello World!' # <1></code></pre>
-</div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_macros">21. Macros</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Macros are a mechanism for substituting parametrized text into output
-documents.</p></div>
-<div class="paragraph"><p>Macros have a <em>name</em>, a single <em>target</em> argument and an <em>attribute
-list</em>. The usual syntax is <code><name>:<target>[<attrlist>]</code> (for
-inline macros) and <code><name>::<target>[<attrlist>]</code> (for block
-macros). Here are some examples:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>https://docbook.org/[DocBook.org]
-include::chapt1.txt[tabsize=2]
-mailto:srackham@gmail.com[]</code></pre>
-</div></div>
-<div class="ulist"><div class="title">Macro behavior</div><ul>
-<li>
-<p>
-<code><name></code> is the macro name. It can only contain letters, digits or
- dash characters and cannot start with a dash.
-</p>
-</li>
-<li>
-<p>
-The optional <code><target></code> cannot contain white space characters.
-</p>
-</li>
-<li>
-<p>
-<code><attrlist></code> is a <a href="#X21">list of attributes</a> enclosed in square
- brackets.
-</p>
-</li>
-<li>
-<p>
-<code>]</code> characters inside attribute lists must be escaped with a
- backslash.
-</p>
-</li>
-<li>
-<p>
-Expansion of macro references can normally be escaped by prefixing a
- backslash character (see the AsciiDoc <em>FAQ</em> for examples of
- exceptions to this rule).
-</p>
-</li>
-<li>
-<p>
-Attribute references in block macros are expanded.
-</p>
-</li>
-<li>
-<p>
-The substitutions performed prior to Inline macro macro expansion
- are determined by the inline context.
-</p>
-</li>
-<li>
-<p>
-Macros are processed in the order they appear in the configuration
- file(s).
-</p>
-</li>
-<li>
-<p>
-Calls to inline macros can be nested inside different inline macros
- (an inline macro call cannot contain a nested call to itself).
-</p>
-</li>
-<li>
-<p>
-In addition to <code><name></code>, <code><target></code> and <code><attrlist></code> the
- <code><passtext></code> and <code><subslist></code> named groups are available to
- <a href="#X77">passthrough macros</a>. A macro is a passthrough macro if the
- definition includes a <code><passtext></code> named group.
-</p>
-</li>
-</ul></div>
-<div class="sect2">
-<h3 id="_inline_macros">21.1. Inline Macros</h3>
-<div class="paragraph"><p>Inline Macros occur in an inline element context. Predefined Inline
-macros include <em>URLs</em>, <em>image</em> and <em>link</em> macros.</p></div>
-<div class="sect3">
-<h4 id="_urls">21.1.1. URLs</h4>
-<div class="paragraph"><p><em>http</em>, <em>https</em>, <em>ftp</em>, <em>file</em>, <em>mailto</em> and <em>callto</em> URLs are
-rendered using predefined inline macros.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-If you don’t need a custom link caption you can enter the <em>http</em>,
- <em>https</em>, <em>ftp</em>, <em>file</em> URLs and email addresses without any special
- macro syntax.
-</p>
-</li>
-<li>
-<p>
-If the <code><attrlist></code> is empty the URL is displayed.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Here are some examples:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>https://docbook.org/[DocBook.org]
-https://docbook.org/
-mailto:joe.bloggs@foobar.com[email Joe Bloggs]
-joe.bloggs@foobar.com</code></pre>
-</div></div>
-<div class="paragraph"><p>Which are rendered:</p></div>
-<div class="paragraph"><p><a href="https://docbook.org/">DocBook.org</a></p></div>
-<div class="paragraph"><p><a href="https://docbook.org/">https://docbook.org/</a></p></div>
-<div class="paragraph"><p><a href="mailto:joe.bloggs@foobar.com">email Joe Bloggs</a></p></div>
-<div class="paragraph"><p><a href="mailto:joe.bloggs@foobar.com">joe.bloggs@foobar.com</a></p></div>
-<div class="paragraph"><p>If the <code><target></code> necessitates space characters use <code>%20</code>, for example
-<code>large%20image.png</code>.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_internal_cross_references">21.1.2. Internal Cross References</h4>
-<div class="paragraph"><p>Two AsciiDoc inline macros are provided for creating hypertext links
-within an AsciiDoc document. You can use either the standard macro
-syntax or the (preferred) alternative.</p></div>
-<div class="sect4">
-<h5 id="X30">anchor</h5>
-<div class="paragraph"><p>Used to specify hypertext link targets:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[[<id>,<xreflabel>]]
-anchor:<id>[<xreflabel>]</code></pre>
-</div></div>
-<div class="paragraph"><p>The <code><id></code> is a unique string that conforms to the output markup’s
-anchor syntax. The optional <code><xreflabel></code> is the text to be displayed
-by captionless <em>xref</em> macros that refer to this anchor. The optional
-<code><xreflabel></code> is only really useful when generating DocBook output.
-Example anchor:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[[X1]]</code></pre>
-</div></div>
-<div class="paragraph"><p>You may have noticed that the syntax of this inline element is the
-same as that of the <a href="#X41">BlockId block element</a>, this is no
-coincidence since they are functionally equivalent.</p></div>
-</div>
-<div class="sect4">
-<h5 id="_xref">xref</h5>
-<div class="paragraph"><p>Creates a hypertext link to a document anchor.</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code><<<id>,<caption>>>
-xref:<id>[<caption>]</code></pre>
-</div></div>
-<div class="paragraph"><p>The <code><id></code> refers to an anchor ID. The optional <code><caption></code> is the
-link’s displayed text. Example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code><<X21,attribute lists>></code></pre>
-</div></div>
-<div class="paragraph"><p>If <code><caption></code> is not specified then the displayed text is
-auto-generated:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The AsciiDoc <em>xhtml11</em> and <em>html5</em> backends display the <code><id></code>
- enclosed in square brackets.
-</p>
-</li>
-<li>
-<p>
-If DocBook is produced the DocBook toolchain is responsible for the
- displayed text which will normally be the referenced figure, table
- or section title number followed by the element’s title text.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Here is an example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[[tiger_image]]
-.Tyger tyger
-image::tiger.png[]
-
-This can be seen in <<tiger_image>>.</code></pre>
-</div></div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_linking_to_local_documents">21.1.3. Linking to Local Documents</h4>
-<div class="paragraph"><p>Hypertext links to files on the local file system are specified using
-the <em>link</em> inline macro.</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>link:<target>[<caption>]</code></pre>
-</div></div>
-<div class="paragraph"><p>The <em>link</em> macro generates relative URLs. The link macro <code><target></code> is
-the target file name (relative to the file system location of the
-referring document). The optional <code><caption></code> is the link’s displayed
-text. If <code><caption></code> is not specified then <code><target></code> is displayed.
-Example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>link:downloads/foo.zip[download foo.zip]</code></pre>
-</div></div>
-<div class="paragraph"><p>You can use the <code><filename>#<id></code> syntax to refer to an anchor within
-a target document but this usually only makes sense when targeting
-HTML documents.</p></div>
-</div>
-<div class="sect3">
-<h4 id="X9">21.1.4. Images</h4>
-<div class="paragraph"><p>Inline images are inserted into the output document using the <em>image</em>
-macro. The inline syntax is:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>image:<target>[<attributes>]</code></pre>
-</div></div>
-<div class="paragraph"><p>The contents of the image file <code><target></code> is displayed. To display the
-image its file format must be supported by the target backend
-application. HTML and DocBook applications normally support PNG or JPG
-files.</p></div>
-<div class="paragraph"><p><code><target></code> file name paths are relative to the location of the
-referring document.</p></div>
-<div class="ulist" id="X55"><div class="title">Image macro attributes</div><ul>
-<li>
-<p>
-The optional <em>alt</em> attribute is also the first positional attribute,
- it specifies alternative text which is displayed if the output
- application is unable to display the image file (see also
- <a href="https://htmlhelp.com/feature/art3.htm">Use of ALT texts in IMGs</a>). For
- example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>image:images/logo.png[Company Logo]</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-The optional <em>title</em> attribute provides a title for the image. The
- <a href="#X49">block image macro</a> renders the title alongside the image.
- The inline image macro displays the title as a popup “tooltip” in
- visual browsers (AsciiDoc HTML outputs only).
-</p>
-</li>
-<li>
-<p>
-The optional <code>width</code> and <code>height</code> attributes scale the image size
- and can be used in any combination. The units are pixels. The
- following example scales the previous example to a height of 32
- pixels:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>image:images/logo.png["Company Logo",height=32]</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-The optional <code>link</code> attribute is used to link the image to an
- external document. The following example links a screenshot
- thumbnail to a full size version:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>image:screen-thumbnail.png[height=32,link="screen.png"]</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-The optional <code>scaledwidth</code> attribute is only used in DocBook block
- images (specifically for PDF documents). The following example
- scales the images to 75% of the available print width:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>image::images/logo.png[scaledwidth="75%",alt="Company Logo"]</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-The image <code>scale</code> attribute sets the DocBook <code>imagedata</code> element
- <code>scale</code> attribute.
-</p>
-</li>
-<li>
-<p>
-The optional <code>align</code> attribute aligns block macro images
- horizontally. Allowed values are <code>center</code>, <code>left</code> and <code>right</code>. For
- example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>image::images/tiger.png["Tiger image",align="left"]</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-The optional <code>float</code> attribute floats the image <code>left</code> or <code>right</code> on
- the page (works with HTML outputs only, has no effect on DocBook
- outputs). <code>float</code> and <code>align</code> attributes are mutually exclusive.
- Use the <code>unfloat::[]</code> block macro to stop floating.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_comment_lines">21.1.5. Comment Lines</h4>
-<div class="paragraph"><p>See <a href="#X25">comment block macro</a>.</p></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_block_macros">21.2. Block Macros</h3>
-<div class="paragraph"><p>A Block macro reference must be contained in a single line separated
-either side by a blank line or a block delimiter.</p></div>
-<div class="paragraph"><p>Block macros behave just like Inline macros, with the following
-differences:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-They occur in a block context.
-</p>
-</li>
-<li>
-<p>
-The default syntax is <code><name>::<target>[<attrlist>]</code> (two
- colons, not one).
-</p>
-</li>
-<li>
-<p>
-Markup template section names end in <code>-blockmacro</code> instead of
- <code>-inlinemacro</code>.
-</p>
-</li>
-</ul></div>
-<div class="sect3">
-<h4 id="_block_identifier">21.2.1. Block Identifier</h4>
-<div class="paragraph"><p>The Block Identifier macro sets the <code>id</code> attribute and has the same
-syntax as the <a href="#X30">anchor inline macro</a> since it performs
-essentially the same function — block templates use the <code>id</code>
-attribute as a block element ID. For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[[X30]]</code></pre>
-</div></div>
-<div class="paragraph"><p>This is equivalent to the <code>[id="X30"]</code> <a href="#X79">AttributeList element</a>).</p></div>
-</div>
-<div class="sect3">
-<h4 id="X49">21.2.2. Images</h4>
-<div class="paragraph"><p>The <em>image</em> block macro is used to display images in a block context.
-The syntax is:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>image::<target>[<attributes>]</code></pre>
-</div></div>
-<div class="paragraph"><p>The block <code>image</code> macro has the same <a href="#X55">macro attributes</a> as it’s
-<a href="#X9">inline image macro</a> counterpart.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/warning.png" alt="Warning" />
-</td>
-<td class="content">Unlike the inline <code>image</code> macro, the entire block <code>image</code> macro
-must be on a single line.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>Block images can be titled by preceding the <em>image</em> macro with a
-<em>BlockTitle</em>. DocBook toolchains normally number titled block images
-and optionally list them in an automatically generated <em>List of
-Figures</em> backmatter section.</p></div>
-<div class="paragraph"><p>This example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>.Main circuit board
-image::images/layout.png[J14P main circuit board]</code></pre>
-</div></div>
-<div class="paragraph"><p>is equivalent to:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>image::images/layout.png["J14P main circuit board", title="Main circuit board"]</code></pre>
-</div></div>
-<div class="paragraph"><p>A title prefix that can be inserted with the <code>caption</code> attribute
-(HTML backends). For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>.Main circuit board
-[caption="Figure 2: "]
-image::images/layout.png[J14P main circuit board]</code></pre>
-</div></div>
-<div class="sidebarblock" id="X66">
-<div class="content">
-<div class="title">Embedding images in XHTML documents</div>
-<div class="paragraph"><p>If you define the <code>data-uri</code> attribute then images will be embedded in
-XHTML outputs using the
-<a href="https://en.wikipedia.org/wiki/Data_URI_scheme">data URI scheme</a>. You
-can use the <em>data-uri</em> attribute with the <em>xhtml11</em> and <em>html5</em>
-backends to produce single-file XHTML documents with embedded images
-and CSS, for example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a data-uri mydocument.txt</code></pre>
-</div></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">
-<div class="ulist"><ul>
-<li>
-<p>
-All current popular browsers support data URIs, although versions
- of Internet Explorer prior to version 8 do not.
-</p>
-</li>
-<li>
-<p>
-Some browsers limit the size of data URIs.
-</p>
-</li>
-</ul></div>
-</td>
-</tr></table>
-</div>
-</div></div>
-</div>
-<div class="sect3">
-<h4 id="X25">21.2.3. Comment Lines</h4>
-<div class="paragraph"><p>Single lines starting with two forward slashes hard up against the
-left margin are treated as comments. Comment lines do not appear in
-the output unless the <em>showcomments</em> attribute is defined. Comment
-lines have been implemented as both block and inline macros so a
-comment line can appear as a stand-alone block or within block elements
-that support inline macro expansion. Example comment line:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>// This is a comment.</code></pre>
-</div></div>
-<div class="paragraph"><p>If the <em>showcomments</em> attribute is defined comment lines are written
-to the output:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-In DocBook the comment lines are enclosed by the <em>remark</em> element
- (which may or may not be rendered by your toolchain).
-</p>
-</li>
-<li>
-<p>
-The <em>showcomments</em> attribute does not expose <a href="#X26">Comment Blocks</a>.
- Comment Blocks are never passed to the output.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_system_macros">21.3. System Macros</h3>
-<div class="paragraph"><p>System macros are block macros that perform a predefined task and are
-hardwired into the <code>asciidoc(1)</code> program.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-You can escape system macros with a leading backslash character
- (as you can with other macros).
-</p>
-</li>
-<li>
-<p>
-The syntax and tasks performed by system macros is built into
- <code>asciidoc(1)</code> so they don’t appear in configuration files. You can
- however customize the syntax by adding entries to a configuration
- file <code>[macros]</code> section.
-</p>
-</li>
-</ul></div>
-<div class="sect3">
-<h4 id="X63">21.3.1. Include Macros</h4>
-<div class="paragraph"><p>The <code>include</code> and <code>include1</code> system macros to include the contents of
-a named file into the source document.</p></div>
-<div class="paragraph"><p>The <code>include</code> macro includes a file as if it were part of the parent
-document — tabs are expanded and system macros processed. The
-contents of <code>include1</code> files are not subject to tab expansion or
-system macro processing nor are attribute or lower priority
-substitutions performed. The <code>include1</code> macro’s intended use is to
-include verbatim embedded CSS or scripts into configuration file
-headers. Example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>include::chapter1.txt[tabsize=4]</code></pre>
-</div></div>
-<div class="ulist"><div class="title">Include macro behavior</div><ul>
-<li>
-<p>
-If the included file name is specified with a relative path then the
- path is relative to the location of the referring document.
-</p>
-</li>
-<li>
-<p>
-Include macros can appear inside configuration files.
-</p>
-</li>
-<li>
-<p>
-Files included from within <em>DelimitedBlocks</em> are read to completion
- to avoid false end-of-block underline termination.
-</p>
-</li>
-<li>
-<p>
-Attribute references are expanded inside the include <em>target</em>; if an
- attribute is undefined then the included file is silently skipped.
-</p>
-</li>
-<li>
-<p>
-The <em>tabsize</em> macro attribute sets the number of space characters to
- be used for tab expansion in the included file (not applicable to
- <code>include1</code> macro).
-</p>
-</li>
-<li>
-<p>
-The <em>depth</em> macro attribute sets the maximum permitted number of
- subsequent nested includes (not applicable to <code>include1</code> macro which
- does not process nested includes). Setting <em>depth</em> to <em>1</em> disables
- nesting inside the included file. By default, nesting is limited to
- a depth of ten.
-</p>
-</li>
-<li>
-<p>
-The <code>lines</code> macro attribute can be used to include specific lines of
- the file. You can specify a range of pages by using <code>..</code> between
- the two numbers, for example <code>1..10</code> would include the first 10
- lines. You can include multiple ranges or invdividual pages by using
- a comma or semi-colon, for example <code>1..10,45,50..60</code>.
-</p>
-</li>
-<li>
-<p>
-If the <em>warnings</em> attribute is set to <em>False</em> (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
- <em>warnings</em> are enabled.
-</p>
-</li>
-<li>
-<p>
-Internally the <code>include1</code> macro is translated to the <code>include1</code>
- system attribute which means it must be evaluated in a region where
- attribute substitution is enabled. To inhibit nested substitution in
- included files it is preferable to use the <code>include</code> macro and set
- the attribute <code>depth=1</code>.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_conditional_inclusion_macros">21.3.2. Conditional Inclusion Macros</h4>
-<div class="paragraph"><p>Lines of text in the source document can be selectively included or
-excluded from processing based on the existence (or not) of a document
-attribute.</p></div>
-<div class="paragraph"><p>Document text between the <code>ifdef</code> and <code>endif</code> macros is included if a
-document attribute is defined:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>ifdef::<attribute>[]
-:
-endif::<attribute>[]</code></pre>
-</div></div>
-<div class="paragraph"><p>Document text between the <code>ifndef</code> and <code>endif</code> macros is not included
-if a document attribute is defined:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>ifndef::<attribute>[]
-:
-endif::<attribute>[]</code></pre>
-</div></div>
-<div class="paragraph"><p><code><attribute></code> is an attribute name which is optional in the trailing
-<code>endif</code> macro.</p></div>
-<div class="paragraph"><p>If you only want to process a single line of text then the text can be
-put inside the square brackets and the <code>endif</code> macro omitted, for
-example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>ifdef::revnumber[Version number 42]</code></pre>
-</div></div>
-<div class="paragraph"><p>Is equivalent to:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>ifdef::revnumber[]
-Version number 42
-endif::revnumber[]</code></pre>
-</div></div>
-<div class="paragraph"><p><em>ifdef</em> and <em>ifndef</em> macros also accept multiple attribute names:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Multiple <em>,</em> separated attribute names evaluate to defined if one
- or more of the attributes is defined, otherwise it’s value is
- undefined.
-</p>
-</li>
-<li>
-<p>
-Multiple <em>+</em> separated attribute names evaluate to defined if all
- of the attributes is defined, otherwise it’s value is undefined.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Document text between the <code>ifeval</code> and <code>endif</code> macros is included if
-the Python expression inside the square brackets is true. Example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>ifeval::[{rs458}==2]
-:
-endif::[]</code></pre>
-</div></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Document attribute references are expanded before the expression is
- evaluated.
-</p>
-</li>
-<li>
-<p>
-If an attribute reference is undefined then the expression is
- considered false.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Take a look at the <code>*.conf</code> configuration files in the AsciiDoc
-distribution for examples of conditional inclusion macro usage.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_executable_system_macros">21.3.3. Executable system macros</h4>
-<div class="paragraph"><p>The <em>eval</em>, <em>sys</em> and <em>sys2</em> block macros exhibit the same behavior as
-their same named <a href="#X24">system attribute references</a>. The difference
-is that system macros occur in a block macro context whereas system
-attributes are confined to inline contexts where attribute
-substitution is enabled.</p></div>
-<div class="paragraph"><p>The following example displays a long directory listing inside a
-literal block:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>------------------
-sys::[ls -l *.txt]
-------------------</code></pre>
-</div></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">There are no block macro versions of the <em>eval3</em> and <em>sys3</em>
-system attributes.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_template_system_macro">21.3.4. Template System Macro</h4>
-<div class="paragraph"><p>The <code>template</code> block macro allows the inclusion of one configuration
-file template section within another. The following example includes
-the <code>[admonitionblock]</code> section in the <code>[admonitionparagraph]</code>
-section:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[admonitionparagraph]
-template::[admonitionblock]</code></pre>
-</div></div>
-<div class="ulist"><div class="title">Template macro behavior</div><ul>
-<li>
-<p>
-The <code>template::[]</code> macro is useful for factoring configuration file
- markup.
-</p>
-</li>
-<li>
-<p>
-<code>template::[]</code> macros cannot be nested.
-</p>
-</li>
-<li>
-<p>
-<code>template::[]</code> macro expansion is applied after all configuration
- files have been read.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="X77">21.4. Passthrough macros</h3>
-<div class="paragraph"><p>Passthrough macros are analogous to <a href="#X76">passthrough blocks</a> 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 <code><subslist></code>. The usual syntax is
-<code><name>:<subslist>[<passtext>]</code> (for inline macros) and
-<code><name>::<subslist>[<passtext>]</code> (for block macros). Passthroughs, by
-definition, take precedence over all other text substitutions.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-pass
-</dt>
-<dd>
-<p>
- Inline and block. Passes text unmodified (apart from explicitly
- specified substitutions). Examples:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>pass:[<q>To be or not to be</q>]
-pass:attributes,quotes[<u>the '{author}'</u>]</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-asciimath, latexmath
-</dt>
-<dd>
-<p>
- Inline and block. Passes text unmodified. Used for
- <a href="#X78">mathematical formulas</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-+++
-</dt>
-<dd>
-<p>
- Inline and block. The triple-plus passthrough is functionally
- identical to the <em>pass</em> macro but you don’t have to escape <code>]</code>
- characters and you can prefix with quoted attributes in the inline
- version. Example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMath formula</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-$$
-</dt>
-<dd>
-<p>
- Inline and block. The double-dollar passthrough is functionally
- identical to the triple-plus passthrough with one exception: special
- characters are escaped. Example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$$`[[a,b],[c,d]]((n),(k))`$$</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-<a id="X80"></a>`
-</dt>
-<dd>
-<p>
- Text quoted with single backtick characters constitutes an <em>inline
- literal</em> passthrough. The enclosed text is rendered in a monospaced
- font and is only subject to special character substitution. This
- makes sense since monospace text is usually intended to be rendered
- literally and often contains characters that would otherwise have to
- be escaped. If you need monospaced text containing inline
- substitutions use a <a href="#X81">plus character instead of a backtick</a>.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_macro_definitions">21.5. Macro Definitions</h3>
-<div class="paragraph"><p>Each entry in the configuration <code>[macros]</code> section is a macro
-definition which can take one of the following forms:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code><pattern>=<name>[<subslist]</code>
-</dt>
-<dd>
-<p>
-Inline macro definition.
-</p>
-</dd>
-<dt class="hdlist1">
-<code><pattern>=#<name>[<subslist]</code>
-</dt>
-<dd>
-<p>
-Block macro definition.
-</p>
-</dd>
-<dt class="hdlist1">
-<code><pattern>=+<name>[<subslist]</code>
-</dt>
-<dd>
-<p>
-System macro definition.
-</p>
-</dd>
-<dt class="hdlist1">
-<code><pattern></code>
-</dt>
-<dd>
-<p>
-Delete the existing macro with this <code><pattern></code>.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p><code><pattern></code> is a Python regular expression and <code><name></code> is the name of
-a markup template. If <code><name></code> is omitted then it is the value of the
-regular expression match group named <em>name</em>. The optional
-<code>[<subslist]</code> is a comma-separated list of substitution names enclosed
-in <code>[]</code> brackets, it sets the default substitutions for passthrough
-text, if omitted then no passthrough substitutions are performed.</p></div>
-<div class="paragraph"><div class="title">Pattern named groups</div><p>The following named groups can be used in macro <code><pattern></code> regular
-expressions and are available as markup template attributes:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-name
-</dt>
-<dd>
-<p>
- The macro name.
-</p>
-</dd>
-<dt class="hdlist1">
-target
-</dt>
-<dd>
-<p>
- The macro target.
-</p>
-</dd>
-<dt class="hdlist1">
-attrlist
-</dt>
-<dd>
-<p>
- The macro attribute list.
-</p>
-</dd>
-<dt class="hdlist1">
-passtext
-</dt>
-<dd>
-<p>
- Contents of this group are passed unmodified to the output subject
- only to <em>subslist</em> substitutions.
-</p>
-</dd>
-<dt class="hdlist1">
-subslist
-</dt>
-<dd>
-<p>
- Processed as a comma-separated list of substitution names for
- <em>passtext</em> substitution, overrides the the macro definition
- <em>subslist</em>.
-</p>
-</dd>
-</dl></div>
-<div class="ulist"><div class="title">Here’s what happens during macro substitution</div><ul>
-<li>
-<p>
-Each contextually relevant macro <em>pattern</em> from the <code>[macros]</code>
- section is matched against the input source line.
-</p>
-</li>
-<li>
-<p>
-If a match is found the text to be substituted is loaded from a
- configuration markup template section named like
- <code><name>-inlinemacro</code> or <code><name>-blockmacro</code> (depending on the macro
- type).
-</p>
-</li>
-<li>
-<p>
-Global and macro attribute list attributes are substituted in the
- macro’s markup template.
-</p>
-</li>
-<li>
-<p>
-The substituted template replaces the macro reference in the output
- document.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X98">22. HTML 5 audio and video block macros</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <em>html5</em> backend <em>audio</em> and <em>video</em> block macros generate the HTML
-5 <em>audio</em> and <em>video</em> elements respectively. They follow the usual
-AsciiDoc block macro syntax <code><name>::<target>[<attrlist>]</code> where:</p></div>
-<div class="hdlist"><table>
-<tr>
-<td class="hdlist1">
-<code><name></code>
-<br />
-</td>
-<td class="hdlist2">
-<p style="margin-top: 0;">
-<em>audio</em> or <em>video</em>.
-</p>
-</td>
-</tr>
-<tr>
-<td class="hdlist1">
-<code><target></code>
-<br />
-</td>
-<td class="hdlist2">
-<p style="margin-top: 0;">
-The URL or file name of the video or audio file.
-</p>
-</td>
-</tr>
-<tr>
-<td class="hdlist1">
-<code><attrlist></code>
-<br />
-</td>
-<td class="hdlist2">
-<p style="margin-top: 0;">
-A list of named attributes (see below).
-</p>
-</td>
-</tr>
-</table></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="hsides"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 4. Audio macro attributes</caption>
-<col width="16%" />
-<col width="83%" />
-<thead>
-<tr>
-<th align="left" valign="top">Name </th>
-<th align="left" valign="top"> Value</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">options</p></td>
-<td align="left" valign="top"><p class="table">A comma separated list of one or more of the following items:
-<em>autoplay</em>, <em>loop</em> which correspond to the same-named HTML 5 <em>audio</em>
-element boolean attributes. By default the player <em>controls</em> are
-enabled, include the <em>nocontrols</em> option value to hide them.</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="hsides"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 5. Video macro attributes</caption>
-<col width="16%" />
-<col width="83%" />
-<thead>
-<tr>
-<th align="left" valign="top">Name </th>
-<th align="left" valign="top"> Value</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">height</p></td>
-<td align="left" valign="top"><p class="table">The height of the player in pixels.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">width</p></td>
-<td align="left" valign="top"><p class="table">The width of the player in pixels.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">poster</p></td>
-<td align="left" valign="top"><p class="table">The URL or file name of an image representing the video.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">options</p></td>
-<td align="left" valign="top"><p class="table">A comma separated list of one or more of the following items:
-<em>autoplay</em>, <em>loop</em> and <em>nocontrols</em>. The <em>autoplay</em> and <em>loop</em> options
-correspond to the same-named HTML 5 <em>video</em> element boolean
-attributes. By default the player <em>controls</em> are enabled, include the
-<em>nocontrols</em> option value to hide them.</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>Examples:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>audio::images/example.ogg[]
-
-video::gizmo.ogv[width=200,options="nocontrols,autoplay"]
-
-.Example video
-video::gizmo.ogv[]
-
-video::http://www.808.dk/pics/video/gizmo.ogv[]</code></pre>
-</div></div>
-<div class="paragraph"><p>If your needs are more complex put raw HTML 5 in a markup block, for
-example (from <a href="http://www.808.dk/?code-html-5-video">http://www.808.dk/?code-html-5-video</a>):</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>++++
-<video poster="pics/video/gizmo.jpg" id="video" style="cursor: pointer;" >
- <source src="pics/video/gizmo.mp4" />
- <source src="pics/video/gizmo.webm" type="video/webm" />
- <source src="pics/video/gizmo.ogv" type="video/ogg" />
- Video not playing? <a href="pics/video/gizmo.mp4">Download file</a> instead.
-</video>
-
-<script type="text/javascript">
- var video = document.getElementById('video');
- video.addEventListener('click',function(){
- video.play();
- },false);
-</script>
-++++</code></pre>
-</div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_tables">23. Tables</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The AsciiDoc table syntax looks and behaves like other delimited block
-types and supports standard <a href="#X73">block configuration entries</a>.
-Formatting is easy to read and, just as importantly, easy to enter.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Cells and columns can be formatted using built-in customizable styles.
-</p>
-</li>
-<li>
-<p>
-Horizontal and vertical cell alignment can be set on columns and
- cell.
-</p>
-</li>
-<li>
-<p>
-Horizontal and vertical cell spanning is supported.
-</p>
-</li>
-</ul></div>
-<div class="sidebarblock">
-<div class="content">
-<div class="title">Use tables sparingly</div>
-<div class="paragraph"><p>When technical users first start creating documents, tables (complete
-with column spanning and table nesting) are often considered very
-important. The reality is that tables are seldom used, even in
-technical documentation.</p></div>
-<div class="paragraph"><p>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) or spanned cells. This is no accident, like figures, tables
-are outside the normal document flow — tables are for consulting not
-for reading.</p></div>
-<div class="paragraph"><p>Tables are designed for, and should normally only be used for,
-displaying column oriented tabular data.</p></div>
-</div></div>
-<div class="sect2">
-<h3 id="_example_tables">23.1. Example tables</h3>
-<div class="tableblock">
-<table rules="all"
-width="15%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 6. Simple table</caption>
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">1</p></td>
-<td align="left" valign="top"><p class="table">2</p></td>
-<td align="left" valign="top"><p class="table">A</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">3</p></td>
-<td align="left" valign="top"><p class="table">4</p></td>
-<td align="left" valign="top"><p class="table">B</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">5</p></td>
-<td align="left" valign="top"><p class="table">6</p></td>
-<td align="left" valign="top"><p class="table">C</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="listingblock">
-<div class="title">AsciiDoc source</div>
-<div class="content">
-<pre><code>[width="15%"]
-|=======
-|1 |2 |A
-|3 |4 |B
-|5 |6 |C
-|=======</code></pre>
-</div></div>
-<div class="tableblock">
-<table rules="all"
-width="50%"
-frame="hsides"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 7. Columns formatted with strong, monospaced and emphasis styles</caption>
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-<thead>
-<tr>
-<th align="right" valign="top"> </th>
-<th colspan="2" align="center" valign="top">Columns 2 and 3</th>
-</tr>
-</thead>
-<tfoot>
-<tr>
-<td align="right" valign="top"><p class="table"><strong>footer 1</strong></p></td>
-<td align="center" valign="top"><p class="table"><code>footer 2</code></p></td>
-<td align="left" valign="top"><p class="table"><em>footer 3</em></p></td>
-</tr>
-</tfoot>
-<tbody>
-<tr>
-<td align="right" valign="top"><p class="table"><strong>1</strong></p></td>
-<td align="center" valign="top"><p class="table"><code>Item 1</code></p></td>
-<td align="left" valign="top"><p class="table"><em>Item 1</em></p></td>
-</tr>
-<tr>
-<td align="right" valign="top"><p class="table"><strong>2</strong></p></td>
-<td align="center" valign="top"><p class="table"><code>Item 2</code></p></td>
-<td align="left" valign="top"><p class="table"><em>Item 2</em></p></td>
-</tr>
-<tr>
-<td align="right" valign="top"><p class="table"><strong>3</strong></p></td>
-<td align="center" valign="top"><p class="table"><code>Item 3</code></p></td>
-<td align="left" valign="top"><p class="table"><em>Item 3</em></p></td>
-</tr>
-<tr>
-<td align="right" valign="top"><p class="table"><strong>4</strong></p></td>
-<td align="center" valign="top"><p class="table"><code>Item 4</code></p></td>
-<td align="left" valign="top"><p class="table"><em>Item 4</em></p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="listingblock">
-<div class="title">AsciiDoc source</div>
-<div class="content">
-<pre><code>.An example table
-[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"]
-|==========================
-| 2+|Columns 2 and 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
-|==========================</code></pre>
-</div></div>
-<div class="tableblock">
-<table rules="all"
-width="80%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 8. Horizontal and vertical source data</caption>
-<col width="17%" />
-<col width="11%" />
-<col width="11%" />
-<col width="58%" />
-<thead>
-<tr>
-<th align="left" valign="top">Date </th>
-<th align="center" valign="top">Duration </th>
-<th align="center" valign="top">Avg HR </th>
-<th align="left" valign="top">Notes</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">22-Aug-08</p></td>
-<td align="center" valign="top"><p class="table">10:24</p></td>
-<td align="center" valign="top"><p class="table">157</p></td>
-<td align="left" valign="top"><p class="table">Worked out MSHR (max sustainable heart rate) by going hard
-for this interval.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">22-Aug-08</p></td>
-<td align="center" valign="top"><p class="table">23:03</p></td>
-<td align="center" valign="top"><p class="table">152</p></td>
-<td align="left" valign="top"><p class="table">Back-to-back with previous interval.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">24-Aug-08</p></td>
-<td align="center" valign="top"><p class="table">40:00</p></td>
-<td align="center" valign="top"><p class="table">145</p></td>
-<td align="left" valign="top"><p class="table">Moderately hard interspersed with 3x 3min intervals (2min
-hard + 1min really hard taking the HR up to 160).</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>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.</p></div>
-<div class="listingblock">
-<div class="title">AsciiDoc source</div>
-<div class="content">
-<pre><code>.Windtrainer workouts
-[width="80%",cols="3,^2,^2,10",options="header"]
-|=========================================================
-|Date |Duration |Avg HR |Notes
-
-|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).
-
-|=========================================================</code></pre>
-</div></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 9. A table with externally sourced CSV data</caption>
-<col width="11%" />
-<col width="22%" />
-<col width="22%" />
-<col width="22%" />
-<col width="22%" />
-<thead>
-<tr>
-<th align="center" valign="top">ID</th>
-<th align="left" valign="top">Customer Name</th>
-<th align="left" valign="top">Contact Name</th>
-<th align="left" valign="top">Customer Address</th>
-<th align="left" valign="top">Phone</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="center" valign="top"><p class="table">AROUT</p></td>
-<td align="left" valign="top"><p class="table">Around the Horn</p></td>
-<td align="left" valign="top"><p class="table">Thomas Hardy</p></td>
-<td align="left" valign="top"><p class="table">120 Hanover Sq.
-London</p></td>
-<td align="left" valign="top"><p class="table">(171) 555-7788</p></td>
-</tr>
-<tr>
-<td align="center" valign="top"><p class="table">BERGS</p></td>
-<td align="left" valign="top"><p class="table">Berglunds snabbkop</p></td>
-<td align="left" valign="top"><p class="table">Christina Berglund</p></td>
-<td align="left" valign="top"><p class="table">Berguvsvagen 8
-Lulea</p></td>
-<td align="left" valign="top"><p class="table">0921-12 34 65</p></td>
-</tr>
-<tr>
-<td align="center" valign="top"><p class="table">BLAUS</p></td>
-<td align="left" valign="top"><p class="table">Blauer See Delikatessen</p></td>
-<td align="left" valign="top"><p class="table">Hanna Moos</p></td>
-<td align="left" valign="top"><p class="table">Forsterstr. 57
-Mannheim</p></td>
-<td align="left" valign="top"><p class="table">0621-08460</p></td>
-</tr>
-<tr>
-<td align="center" valign="top"><p class="table">BLONP</p></td>
-<td align="left" valign="top"><p class="table">Blondel pere et fils</p></td>
-<td align="left" valign="top"><p class="table">Frederique Citeaux</p></td>
-<td align="left" valign="top"><p class="table">24, place Kleber
-Strasbourg</p></td>
-<td align="left" valign="top"><p class="table">88.60.15.31</p></td>
-</tr>
-<tr>
-<td align="center" valign="top"><p class="table">BOLID</p></td>
-<td align="left" valign="top"><p class="table">Bolido Comidas preparadas</p></td>
-<td align="left" valign="top"><p class="table">Martin Sommer</p></td>
-<td align="left" valign="top"><p class="table">C/ Araquil, 67
-Madrid</p></td>
-<td align="left" valign="top"><p class="table">(91) 555 22 82</p></td>
-</tr>
-<tr>
-<td align="center" valign="top"><p class="table">BONAP</p></td>
-<td align="left" valign="top"><p class="table">Bon app'</p></td>
-<td align="left" valign="top"><p class="table">Laurence Lebihan</p></td>
-<td align="left" valign="top"><p class="table">12, rue des Bouchers
-Marseille</p></td>
-<td align="left" valign="top"><p class="table">91.24.45.40</p></td>
-</tr>
-<tr>
-<td align="center" valign="top"><p class="table">BOTTM</p></td>
-<td align="left" valign="top"><p class="table">Bottom-Dollar Markets</p></td>
-<td align="left" valign="top"><p class="table">Elizabeth Lincoln</p></td>
-<td align="left" valign="top"><p class="table">23 Tsawassen Blvd.
-Tsawassen</p></td>
-<td align="left" valign="top"><p class="table">(604) 555-4729</p></td>
-</tr>
-<tr>
-<td align="center" valign="top"><p class="table">BSBEV</p></td>
-<td align="left" valign="top"><p class="table">B’s Beverages</p></td>
-<td align="left" valign="top"><p class="table">Victoria Ashworth</p></td>
-<td align="left" valign="top"><p class="table">Fauntleroy Circus
-London</p></td>
-<td align="left" valign="top"><p class="table">(171) 555-1212</p></td>
-</tr>
-<tr>
-<td align="center" valign="top"><p class="table">CACTU</p></td>
-<td align="left" valign="top"><p class="table">Cactus Comidas para llevar</p></td>
-<td align="left" valign="top"><p class="table">Patricio Simpson</p></td>
-<td align="left" valign="top"><p class="table">Cerrito 333
-Buenos Aires</p></td>
-<td align="left" valign="top"><p class="table">(1) 135-5555</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="listingblock">
-<div class="title">AsciiDoc source</div>
-<div class="content">
-<pre><code>[format="csv",cols="^1,4*2",options="header"]
-|===================================================
-ID,Customer Name,Contact Name,Customer Address,Phone
-include::customers.csv[]
-|===================================================</code></pre>
-</div></div>
-<div class="tableblock">
-<table rules="all"
-width="25%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 10. Cell spans, alignments and styles</caption>
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table"><em>1</em></p></td>
-<td align="right" valign="top"><p class="table"><strong>2</strong></p></td>
-<td align="center" valign="top"><p class="table">3</p></td>
-<td align="right" valign="top"><p class="table"><strong>4</strong></p></td>
-</tr>
-<tr>
-<td align="center" valign="top"><p class="table"><em>5</em></p></td>
-<td colspan="2" rowspan="2" align="center" valign="middle"><p class="table"><code>6</code></p></td>
-<td rowspan="3" align="left" valign="bottom"><p class="table"><code>7</code></p></td>
-</tr>
-<tr>
-<td align="center" valign="top"><p class="table"><em>8</em></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>9</em></p></td>
-<td colspan="2" align="right" valign="top"><p class="table"><code>10</code></p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="listingblock">
-<div class="title">AsciiDoc source</div>
-<div class="content">
-<pre><code>[cols="e,m,^,>s",width="25%"]
-|============================
-|1 >s|2 |3 |4
-^|5 2.2+^.^|6 .3+<.>m|7
-^|8
-|9 2+>|10
-|============================</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="X68">23.2. Table input data formats</h3>
-<div class="paragraph"><p>AsciiDoc table data can be <em>psv</em>, <em>dsv</em> or <em>csv</em> formatted. The
-default table format is <em>psv</em>.</p></div>
-<div class="paragraph"><p>AsciiDoc <em>psv</em> (<em>Prefix Separated Values</em>) and <em>dsv</em> (<em>Delimiter
-Separated Values</em>) formats are cell oriented — the table is treated
-as a sequence of cells — there are no explicit row separators.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<em>psv</em> prefixes each cell with a separator whereas <em>dsv</em> delimits
- cells with a separator.
-</p>
-</li>
-<li>
-<p>
-<em>psv</em> and <em>dsv</em> separators are Python regular expressions.
-</p>
-</li>
-<li>
-<p>
-The default <em>psv</em> separator contains <a href="#X84">cell specifier</a> related
- named regular expression groups.
-</p>
-</li>
-<li>
-<p>
-The default <em>dsv</em> separator is <code>:|\n</code> (a colon or a new line
- character).
-</p>
-</li>
-<li>
-<p>
-<em>psv</em> and <em>dsv</em> cell separators can be escaped by preceding them
- with a backslash character.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Here are four <em>psv</em> cells (the second item spans two columns; the
-last contains an escaped separator):</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>|One 2+|Two and three |A \| separator character</code></pre>
-</div></div>
-<div class="paragraph"><p><em>csv</em> is the quasi-standard row oriented <em>Comma Separated Values
-(CSV)</em> format commonly used to import and export spreadsheet and
-database data.</p></div>
-</div>
-<div class="sect2">
-<h3 id="X69">23.3. Table attributes</h3>
-<div class="paragraph"><p>Tables can be customized by the following attributes:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-format
-</dt>
-<dd>
-<p>
-<em>psv</em> (default), <em>dsv</em> or <em>csv</em> (See <a href="#X68">Table Data Formats</a>).
-</p>
-</dd>
-<dt class="hdlist1">
-separator
-</dt>
-<dd>
-<p>
-The cell separator. A Python regular expression (<em>psv</em> and <em>dsv</em>
-formats) or a single character (<em>csv</em> format).
-</p>
-</dd>
-<dt class="hdlist1">
-frame
-</dt>
-<dd>
-<p>
-Defines the table border and can take the following values: <em>topbot</em>
-(top and bottom), <em>all</em> (all sides), <em>none</em> and <em>sides</em> (left and
-right sides). The default value is <em>all</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-grid
-</dt>
-<dd>
-<p>
-Defines which ruler lines are drawn between table rows and columns.
-The <em>grid</em> attribute value can be any of the following values: <em>none</em>,
-<em>cols</em>, <em>rows</em> and <em>all</em>. The default value is <em>all</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-align
-</dt>
-<dd>
-<p>
-Use the <em>align</em> attribute to horizontally align the table on the
-page (works with HTML outputs only, has no effect on DocBook outputs).
-The following values are valid: <em>left</em>, <em>right</em>, and <em>center</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-float
-</dt>
-<dd>
-<p>
-Use the <em>float</em> attribute to float the table <em>left</em> or <em>right</em> on the
-page (works with HTML outputs only, has no effect on DocBook outputs).
-Floating only makes sense in conjunction with a table <em>width</em>
-attribute value of less than 100% (otherwise the table will take up
-all the available space). <em>float</em> and <em>align</em> attributes are mutually
-exclusive. Use the <code>unfloat::[]</code> block macro to stop floating.
-</p>
-</dd>
-<dt class="hdlist1">
-halign
-</dt>
-<dd>
-<p>
-Use the <em>halign</em> attribute to horizontally align all cells in a table.
-The following values are valid: <em>left</em>, <em>right</em>, and <em>center</em>
-(defaults to <em>left</em>). Overridden by <a href="#X70">Column specifiers</a> and
-<a href="#X84">Cell specifiers</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-valign
-</dt>
-<dd>
-<p>
-Use the <em>valign</em> attribute to vertically align all cells in a table.
-The following values are valid: <em>top</em>, <em>bottom</em>, and <em>middle</em>
-(defaults to <em>top</em>). Overridden by <a href="#X70">Column specifiers</a> and
-<a href="#X84">Cell specifiers</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-options
-</dt>
-<dd>
-<p>
-The <em>options</em> attribute can contain comma separated values, for
-example: <em>header</em>, <em>footer</em>. By default header and footer rows are
-omitted. See <a href="#X74">attribute options</a> for a complete list of
-available table options.
-</p>
-</dd>
-<dt class="hdlist1">
-cols
-</dt>
-<dd>
-<p>
-The <em>cols</em> attribute is a comma separated list of <a href="#X70">column specifiers</a>. For example <code>cols="2<p,2*,4p,>"</code>.
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-If <em>cols</em> is present it must specify all columns.
-</p>
-</li>
-<li>
-<p>
-If the <em>cols</em> attribute is not specified the number of columns is
- calculated as the number of data items in the <strong>first line</strong> of the
- table.
-</p>
-</li>
-<li>
-<p>
-The degenerate form for the <em>cols</em> attribute is an integer
- specifying the number of columns e.g. <code>cols=4</code>.
-</p>
-</li>
-</ul></div>
-</dd>
-<dt class="hdlist1">
-width
-</dt>
-<dd>
-<p>
-The <em>width</em> attribute is expressed as a percentage value
-(<em>"1%"</em>…<em>"99%"</em>). The width specifies the table width relative to
-the available width. HTML backends use this value to set the table
-width attribute. It’s a bit more complicated with DocBook, see the
-<a href="#X89">DocBook table widths</a> sidebar.
-</p>
-</dd>
-<dt class="hdlist1">
-filter
-</dt>
-<dd>
-<p>
-The <em>filter</em> attribute defines an external shell command that is
-invoked for each cell. The built-in <em>asciidoc</em> table style is
-implemented using a filter.
-</p>
-</dd>
-</dl></div>
-<div class="sidebarblock" id="X89">
-<div class="content">
-<div class="title">DocBook table widths</div>
-<div class="paragraph"><p>The AsciiDoc docbook backend generates CALS tables. CALS tables do not
-support a table width attribute — table width can only be controlled
-by specifying absolute column widths.</p></div>
-<div class="paragraph"><p>Specifying absolute column widths is not media independent because
-different presentation media have different physical dimensions. To
-get round this limitation both
-<a href="http://www.sagehill.net/docbookxsl/Tables.html#TableWidth">DocBook XSL
-Stylesheets</a> and
-<a href="http://dblatex.sourceforge.net/doc/manual/ch03s05.html#sec-table-width">dblatex</a>
-have implemented table width processing instructions for setting the
-table width as a percentage of the available width. AsciiDoc emits
-these processing instructions if the <em>width</em> attribute is set along
-with proportional column widths (the AsciiDoc docbook backend
-<em>pageunits</em> attribute defaults to <em>*</em>).</p></div>
-<div class="paragraph"><p>To generate DocBook tables with absolute column widths set the
-<em>pageunits</em> attribute to a CALS absolute unit such as <em>pt</em> and set the
-<em>pagewidth</em> attribute to match the width of the presentation media.</p></div>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="X70">23.4. Column Specifiers</h3>
-<div class="paragraph"><p>Column specifiers define how columns are rendered and appear in the
-table <a href="#X69">cols attribute</a>. A column specifier consists of an
-optional column multiplier followed by optional alignment, width and
-style values and is formatted like:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[<multiplier>*][<align>][<width>][<style>]</code></pre>
-</div></div>
-<div class="ulist"><ul>
-<li>
-<p>
-All components are optional. The multiplier must be first and the
- style last. The order of <code><align></code> or <code><width></code> is not important.
-</p>
-</li>
-<li>
-<p>
-Column <code><width></code> 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
- <a href="#X72">markup attributes</a> which are available in both percentage and
- absolute units).
-</p>
-</li>
-<li>
-<p>
-The <em><align></em> column alignment specifier is formatted like:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>[<horizontal>][.<vertical>]</code></pre>
-</div></div>
-<div class="paragraph"><p>Where <code><horizontal></code> and <code><vertical></code> are one of the following
-characters: <code><</code>, <code>^</code> or <code>></code> which represent <em>left</em>, <em>center</em> and
-<em>right</em> horizontal alignment or <em>top</em>, <em>middle</em> and <em>bottom</em> vertical
-alignment respectively.</p></div>
-</li>
-<li>
-<p>
-A <code><multiplier></code> can be used to specify repeated columns e.g.
- <code>cols="4*<"</code> specifies four left-justified columns. The default
- multiplier value is 1.
-</p>
-</li>
-<li>
-<p>
-The <code><style></code> name specifies a <a href="#X71">table style</a> to used to markup
- column cells (you can use the full style names if you wish but the
- first letter is normally sufficient).
-</p>
-</li>
-<li>
-<p>
-Column specific styles are not applied to header rows.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="X84">23.5. Cell Specifiers</h3>
-<div class="paragraph"><p>Cell specifiers allow individual cells in <em>psv</em> formatted tables to be
-spanned, multiplied, aligned and styled. Cell specifiers prefix <em>psv</em>
-<code>|</code> delimiters and are formatted like:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[<span>*|+][<align>][<style>]</code></pre>
-</div></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<em><span></em> specifies horizontal and vertical cell spans (<em>+</em> operator) or
- the number of times the cell is replicated (<em>*</em> operator). <em><span></em>
- is formatted like:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>[<colspan>][.<rowspan>]</code></pre>
-</div></div>
-<div class="paragraph"><p>Where <code><colspan></code> and <code><rowspan></code> are integers specifying the number of
-columns and rows to span.</p></div>
-</li>
-<li>
-<p>
-<code><align></code> specifies horizontal and vertical cell alignment an is the
- same as in <a href="#X70">column specifiers</a>.
-</p>
-</li>
-<li>
-<p>
-A <code><style></code> value is the first letter of <a href="#X71">table style</a> name.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>For example, the following <em>psv</em> formatted cell will span two columns
-and the text will be centered and emphasized:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>`2+^e| Cell text`</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="X71">23.6. Table styles</h3>
-<div class="paragraph"><p>Table styles can be applied to the entire table (by setting the
-<em>style</em> attribute in the table’s attribute list) or on a per column
-basis (by specifying the style in the table’s <a href="#X69">cols attribute</a>).
-Table data can be formatted using the following predefined styles:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-default
-</dt>
-<dd>
-<p>
-The default style: AsciiDoc inline text formatting; blank lines are
-treated as paragraph breaks.
-</p>
-</dd>
-<dt class="hdlist1">
-emphasis
-</dt>
-<dd>
-<p>
-Like default but all text is emphasised.
-</p>
-</dd>
-<dt class="hdlist1">
-monospaced
-</dt>
-<dd>
-<p>
-Like default but all text is in a monospaced font.
-</p>
-</dd>
-<dt class="hdlist1">
-strong
-</dt>
-<dd>
-<p>
-Like default but all text is bold.
-</p>
-</dd>
-<dt class="hdlist1">
-header
-</dt>
-<dd>
-<p>
-Apply the same style as the table header. Normally used to create a
-vertical header in the first column.
-</p>
-</dd>
-<dt class="hdlist1">
-asciidoc
-</dt>
-<dd>
-<p>
-With this style table cells can contain any of the AsciiDoc elements
-that are allowed inside document sections. This style runs <code>asciidoc(1)</code>
-as a filter to process cell contents. See also <a href="#X83">Docbook table limitations</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-literal
-</dt>
-<dd>
-<p>
-No text formatting; monospaced font; all line breaks are retained
-(the same as the AsciiDoc <a href="#X65">LiteralBlock</a> element).
-</p>
-</dd>
-<dt class="hdlist1">
-verse
-</dt>
-<dd>
-<p>
-All line breaks are retained (just like the AsciiDoc <a href="#X94">verse paragraph style</a>).
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="X72">23.7. Markup attributes</h3>
-<div class="paragraph"><p>AsciiDoc makes a number of attributes available to table markup
-templates and tags. Column specific attributes are available when
-substituting the <em>colspec</em> cell data tags.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-pageunits
-</dt>
-<dd>
-<p>
-DocBook backend only. Specifies table column absolute width units.
-Defaults to <em>*</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-pagewidth
-</dt>
-<dd>
-<p>
-DocBook backend only. The nominal output page width in <em>pageunit</em>
-units. Used to calculate CALS tables absolute column and table
-widths. Defaults to <em>425</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-tableabswidth
-</dt>
-<dd>
-<p>
-Integer value calculated from <em>width</em> and <em>pagewidth</em> attributes.
-In <em>pageunit</em> units.
-</p>
-</dd>
-<dt class="hdlist1">
-tablepcwidth
-</dt>
-<dd>
-<p>
-Table width expressed as a percentage of the available width. Integer
-value (0..100).
-</p>
-</dd>
-<dt class="hdlist1">
-colabswidth
-</dt>
-<dd>
-<p>
-Integer value calculated from <em>cols</em> column width, <em>width</em> and
-<em>pagewidth</em> attributes. In <em>pageunit</em> units.
-</p>
-</dd>
-<dt class="hdlist1">
-colpcwidth
-</dt>
-<dd>
-<p>
-Column width expressed as a percentage of the table width. Integer
-value (0..100).
-</p>
-</dd>
-<dt class="hdlist1">
-colcount
-</dt>
-<dd>
-<p>
-Total number of table columns.
-</p>
-</dd>
-<dt class="hdlist1">
-rowcount
-</dt>
-<dd>
-<p>
-Total number of table rows.
-</p>
-</dd>
-<dt class="hdlist1">
-halign
-</dt>
-<dd>
-<p>
-Horizontal cell content alignment: <em>left</em>, <em>right</em> or <em>center</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-valign
-</dt>
-<dd>
-<p>
-Vertical cell content alignment: <em>top</em>, <em>bottom</em> or <em>middle</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-colnumber, colstart
-</dt>
-<dd>
-<p>
-The number of the leftmost column occupied by the cell (1…).
-</p>
-</dd>
-<dt class="hdlist1">
-colend
-</dt>
-<dd>
-<p>
-The number of the rightmost column occupied by the cell (1…).
-</p>
-</dd>
-<dt class="hdlist1">
-colspan
-</dt>
-<dd>
-<p>
-Number of columns the cell should span.
-</p>
-</dd>
-<dt class="hdlist1">
-rowspan
-</dt>
-<dd>
-<p>
-Number of rows the cell should span (1…).
-</p>
-</dd>
-<dt class="hdlist1">
-morerows
-</dt>
-<dd>
-<p>
-Number of additional rows the cell should span (0…).
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_nested_tables">23.8. Nested tables</h3>
-<div class="paragraph"><p>An alternative <em>psv</em> separator character <em>!</em> can be used (instead of
-<em>|</em>) in nested tables. This allows a single level of table nesting.
-Columns containing nested tables must use the <em>asciidoc</em> style. An
-example can be found in <code>./examples/website/newtables.txt</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="X83">23.9. DocBook table limitations</h3>
-<div class="paragraph"><p>Fully implementing tables is not trivial, some DocBook toolchains do
-better than others. AsciiDoc HTML table outputs are rendered
-correctly in all the popular browsers — if your DocBook generated
-tables don’t look right compare them with the output generated by the
-AsciiDoc <em>xhtml11</em> backend or try a different DocBook toolchain. Here
-is a list of things to be aware of:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Although nested tables are not legal in DocBook 4 the FOP and
- dblatex toolchains will process them correctly. If you use <code>a2x(1)</code>
- you will need to include the <code>--no-xmllint</code> option to suppress
- DocBook validation errors.
-</p>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">In theory you can nest DocBook 4 tables one level using the
-<em>entrytbl</em> element, but not all toolchains process <em>entrytbl</em>.</td>
-</tr></table>
-</div>
-</li>
-<li>
-<p>
-DocBook only allows a subset of block elements inside table cells so
- not all AsciiDoc elements produce valid DocBook inside table cells.
- If you get validation errors running <code>a2x(1)</code> try the <code>--no-xmllint</code>
- option, toolchains will often process nested block elements such as
- sidebar blocks and floating titles correctly even though, strictly
- speaking, they are not legal.
-</p>
-</li>
-<li>
-<p>
-Text formatting in cells using the <em>monospaced</em> table style will
- raise validation errors because the DocBook <em>literal</em> element was
- not designed to support formatted text (using the <em>literal</em> element
- is a kludge on the part of AsciiDoc as there is no easy way to set
- the font style in DocBook.
-</p>
-</li>
-<li>
-<p>
-Cell alignments are ignored for <em>verse</em>, <em>literal</em> or <em>asciidoc</em>
- table styles.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X1">24. Manpage Documents</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Sooner or later, if you program in a UNIX environment, you’re going
-to have to write a man page.</p></div>
-<div class="paragraph"><p>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 <code>a2x(1)</code> command. The
-following example generates a roff formatted manpage file called
-<code>asciidoc.1</code> (<code>a2x(1)</code> uses <code>asciidoc(1)</code> to convert <code>asciidoc.1.txt</code> to
-DocBook which it then converts to roff using DocBook XSL Stylesheets):</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>a2x --doctype manpage --format manpage asciidoc.1.txt</code></pre>
-</div></div>
-<div class="sidebarblock">
-<div class="content">
-<div class="title">Viewing and printing manpage files</div>
-<div class="paragraph"><p>Use the <code>man(1)</code> command to view the manpage file:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ man -l asciidoc.1</code></pre>
-</div></div>
-<div class="paragraph"><p>To print a high quality man page to a postscript printer:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ man -l -Tps asciidoc.1 | lpr</code></pre>
-</div></div>
-<div class="paragraph"><p>You could also create a PDF version of the man page by converting
-PostScript to PDF using <code>ps2pdf(1)</code>:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ man -l -Tps asciidoc.1 | ps2pdf - asciidoc.1.pdf</code></pre>
-</div></div>
-<div class="paragraph"><p>The <code>ps2pdf(1)</code> command is included in the Ghostscript distribution.</p></div>
-</div></div>
-<div class="paragraph"><p>To find out more about man pages view the <code>man(7)</code> manpage
-(<code>man 7 man</code> and <code>man man-pages</code> commands).</p></div>
-<div class="sect2">
-<h3 id="_document_header">24.1. Document Header</h3>
-<div class="paragraph"><p>A manpage document Header is mandatory. The title line contains the
-man page name followed immediately by the manual section number in
-brackets, for example <em>ASCIIDOC(1)</em>. The title name should not contain
-white space and the manual section number is a single digit optionally
-followed by a single character.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_the_name_section">24.2. The NAME Section</h3>
-<div class="paragraph"><p>The first manpage section is mandatory, must be titled <em>NAME</em> and must
-contain a single paragraph (usually a single line) consisting of a
-list of one or more comma separated command name(s) separated from the
-command purpose by a dash character. The dash must have at least one
-white space character on either side. For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>printf, fprintf, sprintf - print formatted output</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_the_synopsis_section">24.3. The SYNOPSIS Section</h3>
-<div class="paragraph"><p>The second manpage section is mandatory and must be titled <em>SYNOPSIS</em>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_refmiscinfo_attributes">24.4. refmiscinfo attributes</h3>
-<div class="paragraph"><p>In addition to the automatically created man page <a href="#X60">intrinsic attributes</a> you can assign DocBook
-<a href="https://tdg.docbook.org/tdg/4.5/refmiscinfo.html">refmiscinfo</a>
-element <em>source</em>, <em>version</em> and <em>manual</em> values using AsciiDoc
-<code>{mansource}</code>, <code>{manversion}</code> and <code>{manmanual}</code> attributes
-respectively. This example is from the AsciiDoc header of a man page
-source file:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>:man source: AsciiDoc
-:man version: {revnumber}
-:man manual: AsciiDoc Manual</code></pre>
-</div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X78">25. Mathematical Formulas</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <em>asciimath</em> and <em>latexmath</em> <a href="#X76">passthrough blocks</a> along with
-the <em>asciimath</em> and <em>latexmath</em> <a href="#X77">passthrough macros</a> provide a
-(backend dependent) mechanism for rendering mathematical formulas. You
-can use the following math markups:</p></div>
-<div class="sect2">
-<h3 id="_latex_math">25.1. LaTeX Math</h3>
-<div class="paragraph"><p><a href="ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf">LaTeX
-math</a> can be included in documents that are processed by
-<a href="#X31">dblatex(1)</a>. Example inline formula:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]</code></pre>
-</div></div>
-<div class="paragraph"><p>For more examples see the <a href="https://asciidoc.org/">AsciiDoc website</a> or the
-distributed <code>doc/latexmath.txt</code> file.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_mathjax">25.2. MathJax</h3>
-<div class="paragraph"><p><a href="https://www.mathjax.org/">MathJax</a> allows LaTeX Math style formulas to be included
-in XHTML documents generated via the AsciiDoc <em>xhtml11</em> and <em>html5</em> backends.
-This route overcomes several restrictions of the MathML-based approaches,
-notably, restricted support of MathML by many mainstream browsers. To enable
-<em>MathJax</em> support you must define the <em>mathjax</em> attribute, for example using the
-<code>-a mathjax</code> command-line option. Equations are specified as explained above
-using the <em>latexmath</em> passthrough blocks. By default, rendering of equations
-with <em>MathJax</em> requires a working internet connection and will thus not work if
-you are offline (but it can be configured differently).</p></div>
-</div>
-<div class="sect2">
-<h3 id="_latexmathml">25.3. LaTeXMathML</h3>
-<div class="paragraph"><p><em>LaTeXMathML</em> allows LaTeX Math style formulas to be included in XHTML
-documents generated using the AsciiDoc <em>xhtml11</em> and <em>html5</em> backends.
-AsciiDoc uses the
-<a href="https://www.maths.nottingham.ac.uk/plp/pmadw/lm.html">original
-LaTeXMathML</a> by Douglas Woodall. <em>LaTeXMathML</em> is derived from
-ASCIIMath 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 <em>LaTeXMathML</em> web page). To enable
-LaTeXMathML support you must define the <em>latexmath</em> attribute, for
-example using the <code>-a latexmath</code> command-line option. Example inline
-formula:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$]</code></pre>
-</div></div>
-<div class="paragraph"><p>For more examples see the <a href="https://asciidoc.org/">AsciiDoc website</a> or the
-distributed <code>doc/latexmathml.txt</code> file.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">The <em>latexmath</em> macro used to include <em>LaTeX Math</em> in DocBook
-outputs is not the same as the <em>latexmath</em> macro used to include
-<em>LaTeX MathML</em> in XHTML outputs. <em>LaTeX Math</em> applies to DocBook
-outputs that are processed by <a href="#X31">dblatex</a> and is normally used to
-generate PDF files. <em>LaTeXMathML</em> is very much a subset of <em>LaTeX
-Math</em> and applies to XHTML documents. This remark does not
-apply to <em>MathJax</em> which does not use any of the <em>latexmath</em> macros
-(but only requires the <em>latexmath</em> passthrough blocks for identification
-of the equations).</td>
-</tr></table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_asciimath">25.4. ASCIIMath</h3>
-<div class="paragraph"><p><a href="http://asciimath.org/">ASCIIMath</a> formulas can be included in XHTML
-documents generated using the <em>xhtml11</em> and <em>html5</em> backends. To enable
-ASCIIMath support you must define the <em>asciimath</em> attribute, for
-example using the <code>-a asciimath</code> command-line option. Example inline
-formula:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>asciimath:[`x/x={(1,if x!=0),(text{undefined},if x=0):}`]</code></pre>
-</div></div>
-<div class="paragraph"><p>For more examples see the <a href="https://asciidoc.org/">AsciiDoc website</a> or the
-distributed <code>doc/asciimath.txt</code> file.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_mathml">25.5. MathML</h3>
-<div class="paragraph"><p><a href="https://www.w3.org/Math/">MathML</a> 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.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X7">26. Configuration Files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>AsciiDoc source file syntax and output file markup is largely
-controlled by a set of cascading, text based, configuration files. At
-runtime The AsciiDoc default configuration files are combined with
-optional user and document specific configuration files.</p></div>
-<div class="sect2">
-<h3 id="_configuration_file_format">26.1. Configuration File Format</h3>
-<div class="paragraph"><p>Configuration files contain named sections. Each section begins with a
-section name in square brackets []. The section body consists of the
-lines of text between adjacent section headings.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Section names consist of one or more alphanumeric, underscore or
- dash characters and cannot begin or end with a dash.
-</p>
-</li>
-<li>
-<p>
-Lines starting with a <em>#</em> character are treated as comments and
- ignored.
-</p>
-</li>
-<li>
-<p>
-If the section name is prefixed with a <em>+</em> character then the
- section contents is appended to the contents of an already existing
- same-named section.
-</p>
-</li>
-<li>
-<p>
-Otherwise same-named sections and section entries override
- previously loaded sections and section entries (this is sometimes
- referred to as <em>cascading</em>). Consequently, downstream configuration
- files need only contain those sections and section entries that need
- to be overridden.
-</p>
-</li>
-</ul></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/tip.png" alt="Tip" />
-</td>
-<td class="content">When creating custom configuration files you only need to include
-the sections and entries that differ from the default configuration.</td>
-</tr></table>
-</div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/tip.png" alt="Tip" />
-</td>
-<td class="content">The best way to learn about configuration files is to read the
-default configuration files in the AsciiDoc distribution in
-conjunction with <code>asciidoc(1)</code> output files. You can view configuration
-file load sequence by turning on the <code>asciidoc(1)</code> <code>-v</code> (<code>--verbose</code>)
-command-line option.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>AsciiDoc reserves the following section names for specific purposes:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-miscellaneous
-</dt>
-<dd>
-<p>
- Configuration options that don’t belong anywhere else.
-</p>
-</dd>
-<dt class="hdlist1">
-attributes
-</dt>
-<dd>
-<p>
- Attribute name/value entries.
-</p>
-</dd>
-<dt class="hdlist1">
-specialcharacters
-</dt>
-<dd>
-<p>
- Special characters reserved by the backend markup.
-</p>
-</dd>
-<dt class="hdlist1">
-tags
-</dt>
-<dd>
-<p>
- Backend markup tags.
-</p>
-</dd>
-<dt class="hdlist1">
-quotes
-</dt>
-<dd>
-<p>
- Definitions for quoted inline character formatting.
-</p>
-</dd>
-<dt class="hdlist1">
-specialwords
-</dt>
-<dd>
-<p>
- Lists of words and phrases singled out for special markup.
-</p>
-</dd>
-<dt class="hdlist1">
-replacements, replacements2, replacements3
-</dt>
-<dd>
-<p>
- Find and replace substitution definitions.
-</p>
-</dd>
-<dt class="hdlist1">
-specialsections
-</dt>
-<dd>
-<p>
- Used to single out special section names for specific markup.
-</p>
-</dd>
-<dt class="hdlist1">
-macros
-</dt>
-<dd>
-<p>
- Macro syntax definitions.
-</p>
-</dd>
-<dt class="hdlist1">
-titles
-</dt>
-<dd>
-<p>
- Heading, section and block title definitions.
-</p>
-</dd>
-<dt class="hdlist1">
-paradef-*
-</dt>
-<dd>
-<p>
- Paragraph element definitions.
-</p>
-</dd>
-<dt class="hdlist1">
-blockdef-*
-</dt>
-<dd>
-<p>
- DelimitedBlock element definitions.
-</p>
-</dd>
-<dt class="hdlist1">
-listdef-*
-</dt>
-<dd>
-<p>
- List element definitions.
-</p>
-</dd>
-<dt class="hdlist1">
-listtags-*
-</dt>
-<dd>
-<p>
- List element tag definitions.
-</p>
-</dd>
-<dt class="hdlist1">
-tabledef-*
-</dt>
-<dd>
-<p>
- Table element definitions.
-</p>
-</dd>
-<dt class="hdlist1">
-tabletags-*
-</dt>
-<dd>
-<p>
- Table element tag definitions.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Each line of text in these sections is a <em>section entry</em>. Section
-entries share the following syntax:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-name=value
-</dt>
-<dd>
-<p>
- The entry value is set to value.
-</p>
-</dd>
-<dt class="hdlist1">
-name=
-</dt>
-<dd>
-<p>
- The entry value is set to a zero length string.
-</p>
-</dd>
-<dt class="hdlist1">
-name!
-</dt>
-<dd>
-<p>
- The entry is undefined (deleted from the configuration). This
- syntax only applies to <em>attributes</em> and <em>miscellaneous</em>
- sections.
-</p>
-</dd>
-</dl></div>
-<div class="ulist"><div class="title">Section entry behavior</div><ul>
-<li>
-<p>
-All equals characters inside the <code>name</code> must be escaped with a
- backslash character.
-</p>
-</li>
-<li>
-<p>
-<code>name</code> and <code>value</code> are stripped of leading and trailing white space.
-</p>
-</li>
-<li>
-<p>
-Attribute names, tag entry names and markup template section names
- consist of one or more alphanumeric, underscore or dash characters.
- Names should not begin or end with a dash.
-</p>
-</li>
-<li>
-<p>
-A blank configuration file section (one without any entries) deletes
- any preceding section with the same name (applies to non-markup
- template sections).
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="_miscellaneous_section">26.2. Miscellaneous section</h3>
-<div class="paragraph"><p>The optional <code>[miscellaneous]</code> section specifies the following
-<code>name=value</code> options:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-newline
-</dt>
-<dd>
-<p>
- Output file line termination characters. Can include any
- valid Python string escape sequences. The default value is
- <code>\r\n</code> (carriage return, line feed). Should not be quoted or
- contain explicit spaces (use <code>\x20</code> instead). For example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a 'newline=\n' -b docbook mydoc.txt</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-outfilesuffix
-</dt>
-<dd>
-<p>
- The default extension for the output file, for example
- <code>outfilesuffix=.html</code>. Defaults to backend name.
-</p>
-</dd>
-<dt class="hdlist1">
-tabsize
-</dt>
-<dd>
-<p>
- The number of spaces to expand tab characters, for example
- <code>tabsize=4</code>. Defaults to 8. A <em>tabsize</em> of zero suppresses tab
- expansion (useful when piping included files through block
- filters). Included files can override this option using the
- <em>tabsize</em> attribute.
-</p>
-</dd>
-<dt class="hdlist1">
-pagewidth, pageunits
-</dt>
-<dd>
-<p>
- These global table related options are documented in the
- <a href="#X4">Table Configuration File Definitions</a> sub-section.
-</p>
-</dd>
-</dl></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content"><code>[miscellaneous]</code> configuration file entries can be set using
-the <code>asciidoc(1)</code> <code>-a</code> (<code>--attribute</code>) command-line option.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_titles_section">26.3. Titles section</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-sectiontitle
-</dt>
-<dd>
-<p>
- Two line section title pattern. The entry value is a Python
- regular expression containing the named group <em>title</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-underlines
-</dt>
-<dd>
-<p>
- A comma separated list of document and section title underline
- character pairs starting with the section level 0 and ending
- with section level 4 underline. The default setting is:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>underlines="==","--","~~","^^","++"</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-sect0…sect4
-</dt>
-<dd>
-<p>
- One line section title patterns. The entry value is a Python
- regular expression containing the named group <em>title</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-blocktitle
-</dt>
-<dd>
-<p>
- <a href="#X42">BlockTitle element</a> pattern. The entry value is a
- Python regular expression containing the named group <em>title</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-subs
-</dt>
-<dd>
-<p>
- A comma separated list of substitutions that are performed on
- the document header and section titles. Defaults to <em>normal</em>
- substitution.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_tags_section">26.4. Tags section</h3>
-<div class="paragraph"><p>The <code>[tags]</code> section contains backend tag definitions (one per
-line). Tags are used to translate AsciiDoc elements to backend
-markup.</p></div>
-<div class="paragraph"><p>An AsciiDoc tag definition is formatted like
-<code><tagname>=<starttag>|<endtag></code>. For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>emphasis=<em>|</em></code></pre>
-</div></div>
-<div class="paragraph"><p>In this example <code>asciidoc(1)</code> replaces the | character with the
-emphasized text from the AsciiDoc input file and writes the result to
-the output file.</p></div>
-<div class="paragraph"><p>Use the <code>{brvbar}</code> attribute reference if you need to include a | pipe
-character inside tag text.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_attributes_section">26.5. Attributes section</h3>
-<div class="paragraph"><p>The optional <code>[attributes]</code> section contains predefined attributes.</p></div>
-<div class="paragraph"><p>If the attribute value requires leading or trailing spaces then the
-text text should be enclosed in quotation mark (") characters.</p></div>
-<div class="paragraph"><p>To delete a attribute insert a <code>name!</code> entry in a downstream
-configuration file or use the <code>asciidoc(1)</code> <code>--attribute name!</code>
-command-line option (an attribute name suffixed with a <code>!</code> character
-deletes the attribute)</p></div>
-</div>
-<div class="sect2">
-<h3 id="_special_characters_section">26.6. Special Characters section</h3>
-<div class="paragraph"><p>The <code>[specialcharacters]</code> section specifies how to escape characters
-reserved by the backend markup. Each translation is specified on a
-single line formatted like:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code><special_character>=<translated_characters></code></pre>
-</div></div>
-<div class="paragraph"><p>Special characters are normally confined to those that resolve
-markup ambiguity (in the case of HTML and XML markups the ampersand,
-less than and greater than characters). The following example causes
-all occurrences of the <code><</code> character to be replaced by <code>&lt;</code>.</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code><=&lt;</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_quoted_text_section">26.7. Quoted Text section</h3>
-<div class="paragraph"><p>Quoting is used primarily for text formatting. The <code>[quotes]</code> section
-defines AsciiDoc quoting characters and their corresponding backend
-markup tags. Each section entry value is the name of a of a <code>[tags]</code>
-section entry. The entry name is the character (or characters) that
-quote the text. The following examples are taken from AsciiDoc
-configuration files:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[quotes]
-_=emphasis</code></pre>
-</div></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[tags]
-emphasis=<em>|</em></code></pre>
-</div></div>
-<div class="paragraph"><p>You can specify the left and right quote strings separately by
-separating them with a | character, for example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>``|''=quoted</code></pre>
-</div></div>
-<div class="paragraph"><p>Omitting the tag will disable quoting, for example, if you don’t want
-superscripts or subscripts put the following in a custom configuration
-file or edit the global <code>asciidoc.conf</code> configuration file:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[quotes]
-^=
-~=</code></pre>
-</div></div>
-<div class="paragraph"><p><a href="#X52">Unconstrained quotes</a> are differentiated from constrained
-quotes by prefixing the tag name with a hash character, for example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>__=#emphasis</code></pre>
-</div></div>
-<div class="ulist"><div class="title">Quoted text behavior</div><ul>
-<li>
-<p>
-Quote characters must be non-alphanumeric.
-</p>
-</li>
-<li>
-<p>
-To minimize quoting ambiguity try not to use the same quote
- characters in different quote types.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="_special_words_section">26.8. Special Words section</h3>
-<div class="paragraph"><p>The <code>[specialwords]</code> 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
-each entry corresponds to a markup template section and the entry
-value consists of a list of words and phrases to be marked up. For
-example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[specialwords]
-strongwords=NOTE IMPORTANT</code></pre>
-</div></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[strongwords]
-<strong>{words}</strong></code></pre>
-</div></div>
-<div class="paragraph"><p>The examples specifies that any occurrence of <code>NOTE</code> or <code>IMPORTANT</code>
-should appear in a bold font.</p></div>
-<div class="paragraph"><p>Words and word phrases are treated as Python regular expressions: for
-example, the word <code>^NOTE</code> would only match <code>NOTE</code> if appeared at
-the start of a line.</p></div>
-<div class="paragraph"><p>AsciiDoc comes with three built-in Special Word types:
-<em>emphasizedwords</em>, <em>monospacedwords</em> and <em>strongwords</em>, each has a
-corresponding (backend specific) markup template section. Edit the
-configuration files to customize existing Special Words and to add new
-ones.</p></div>
-<div class="ulist"><div class="title">Special word behavior</div><ul>
-<li>
-<p>
-Word list entries must be separated by space characters.
-</p>
-</li>
-<li>
-<p>
-Word list entries with embedded spaces should be enclosed in quotation (")
- characters.
-</p>
-</li>
-<li>
-<p>
-A <code>[specialwords]</code> section entry of the form
- <code>name=word1 [word2…]</code> adds words to existing <code>name</code> entries.
-</p>
-</li>
-<li>
-<p>
-A <code>[specialwords]</code> section entry of the form <code>name</code> undefines
- (deletes) all existing <code>name</code> words.
-</p>
-</li>
-<li>
-<p>
-Since word list entries are processed as Python regular expressions
- you need to be careful to escape regular expression special
- characters.
-</p>
-</li>
-<li>
-<p>
-By default Special Words are substituted before Inline Macros, this
- may lead to undesirable consequences. For example the special word
- <code>foobar</code> would be expanded inside the macro call
- <code>http://www.foobar.com[]</code>. A possible solution is to emphasize
- whole words only by defining the word using regular expression
- characters, for example <code>\bfoobar\b</code>.
-</p>
-</li>
-<li>
-<p>
-If the first matched character of a special word is a backslash then
- the remaining characters are output without markup i.e. the
- backslash can be used to escape special word markup. For example
- the special word <code>\\?\b[Tt]en\b</code> will mark up the words <code>Ten</code> and
- <code>ten</code> only if they are not preceded by a backslash.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="X10">26.9. Replacements section</h3>
-<div class="paragraph"><p><code>[replacements]</code>, <code>[replacements2]</code> and <code>[replacements3]</code>
-configuration file entries specify find and replace text and are
-formatted like:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code><find_pattern>=<replacement_text></code></pre>
-</div></div>
-<div class="paragraph"><p>The find text can be a Python regular expression; the replace text can
-contain Python regular expression group references.</p></div>
-<div class="paragraph"><p>Use Replacement shortcuts for often used macro references, for
-example (the second replacement allows us to backslash escape the
-macro name):</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>NEW!=image:./images/smallnew.png[New!]
-\\NEW!=NEW!</code></pre>
-</div></div>
-<div class="paragraph"><p>The only difference between the three replacement types is how they
-are applied. By default <em>replacements</em> and <em>replacements2</em> are applied
-in <a href="#X102">normal</a> substitution contexts whereas <em>replacements3</em> needs
-to be configured explicitly and should only be used in backend
-configuration files.</p></div>
-<div class="ulist"><div class="title">Replacement behavior</div><ul>
-<li>
-<p>
-The built-in replacements can be escaped with a backslash.
-</p>
-</li>
-<li>
-<p>
-If the find or replace text has leading or trailing spaces then the
- text should be enclosed in quotation (") characters.
-</p>
-</li>
-<li>
-<p>
-Since the find text is processed as a regular expression you need to
- be careful to escape regular expression special characters.
-</p>
-</li>
-<li>
-<p>
-Replacements are performed in the same order they appear in the
- configuration file replacements section.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="_markup_template_sections">26.10. Markup Template Sections</h3>
-<div class="paragraph"><p>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 <em>name=value</em>
-entries. A markup template section body can contain:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Attribute references
-</p>
-</li>
-<li>
-<p>
-System macro calls.
-</p>
-</li>
-<li>
-<p>
-A document content placeholder
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The document content placeholder is a single | character and is
-replaced by text from the source element. Use the <code>{brvbar}</code>
-attribute reference if you need a literal | character in the template.</p></div>
-</div>
-<div class="sect2">
-<h3 id="X27">26.11. Configuration file names, precedence and locations</h3>
-<div class="paragraph"><p>Configuration files have a <code>.conf</code> file name extension; they are
-loaded from the following locations:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-The directory containing the asciidoc executable.
-</p>
-</li>
-<li>
-<p>
-If there is no <code>asciidoc.conf</code> file in the directory containing the
- asciidoc executable then load from the global configuration
- directory (normally <code>/etc/asciidoc</code> or <code>/usr/local/etc/asciidoc</code>)
- i.e. the global configuration files directory is skipped if
- AsciiDoc configuration files are installed in the same directory as
- the asciidoc executable. This allows both a system wide copy and
- multiple local copies of AsciiDoc to coexist on the same host PC.
-</p>
-</li>
-<li>
-<p>
-The user’s <code>$HOME/.asciidoc</code> directory (if it exists).
-</p>
-</li>
-<li>
-<p>
-The directory containing the AsciiDoc source file.
-</p>
-</li>
-<li>
-<p>
-Explicit configuration files specified using:
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-The <code>conf-files</code> attribute (one or more file names separated by a
- <code>|</code> character). These files are loaded in the order they are
- specified and prior to files specified using the <code>--conf-file</code>
- command-line option.
-</p>
-</li>
-<li>
-<p>
-The <code>asciidoc(1)</code> <code>--conf-file</code>) command-line option. The
- <code>--conf-file</code> option can be specified multiple times, in which
- case configuration files will be processed in the same order they
- appear on the command-line.
-</p>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
-<a href="#X100">Backend plugin</a> configuration files are loaded from
- subdirectories named like <code>backends/<backend></code> in locations 1, 2
- and 3.
-</p>
-</li>
-<li>
-<p>
-<a href="#X59">Filter</a> configuration files are loaded from subdirectories
- named like <code>filters/<filter></code> in locations 1, 2 and 3.
-</p>
-</li>
-</ol></div>
-<div class="paragraph"><p>Configuration files from the above locations are loaded in the
-following order:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The <code>[attributes]</code> section only from:
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>asciidoc.conf</code> in location 3
-</p>
-</li>
-<li>
-<p>
-Files from location 5.
-</p>
-<div class="paragraph"><p>This first pass makes locally set attributes available in the global
-<code>asciidoc.conf</code> file.</p></div>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
-<code>asciidoc.conf</code> from locations 1, 2, 3.
-</p>
-</li>
-<li>
-<p>
-<em>attributes</em>, <em>titles</em> and <em>specialcharacters</em> sections from the
- <code>asciidoc.conf</code> in location 4.
-</p>
-</li>
-<li>
-<p>
-The document header is parsed at this point and we can assume the
- <em>backend</em> and <em>doctype</em> have now been defined.
-</p>
-</li>
-<li>
-<p>
-Backend plugin <code><backend>.conf</code> and <code><backend>-<doctype>.conf</code> files
- from locations 6. If a backend plugin is not found then try
- locations 1, 2 and 3 for <code><backend>.conf</code> and
- <code><backend>-<doctype>.conf</code> backend configuration files.
-</p>
-</li>
-<li>
-<p>
-Filter conf files from locations 7.
-</p>
-</li>
-<li>
-<p>
-<code>lang-<lang>.conf</code> from locations 1, 2, 3.
-</p>
-</li>
-<li>
-<p>
-<code>asciidoc.conf</code> from location 4.
-</p>
-</li>
-<li>
-<p>
-<code><backend>.conf</code> and <code><backend>-<doctype>.conf</code> from location 4.
-</p>
-</li>
-<li>
-<p>
-Filter conf files from location 4.
-</p>
-</li>
-<li>
-<p>
-<code><docfile>.conf</code> and <code><docfile>-<backend>.conf</code> from location 4.
-</p>
-</li>
-<li>
-<p>
-Configuration files from location 5.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Where:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code><backend></code> and <code><doctype></code> are values specified by the <code>asciidoc(1)</code>
- <code>-b</code> (<code>--backend</code>) and <code>-d</code> (<code>--doctype</code>) command-line options.
-</p>
-</li>
-<li>
-<p>
-<code><infile></code> is the path name of the AsciiDoc input file without the
- file name extension.
-</p>
-</li>
-<li>
-<p>
-<code><lang></code> is a two letter country code set by the the AsciiDoc <em>lang</em>
- attribute.
-</p>
-</li>
-</ul></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">
-<div class="paragraph"><p>The backend and language global configuration files are loaded <strong>after</strong>
-the header has been parsed. This means that you can set most
-attributes in the document header. Here’s an example header:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Life's Mysteries
-================
-:author: Hu Nose
-:doctype: book
-:toc:
-:icons:
-:data-uri:
-:lang: en
-:encoding: iso-8859-1</code></pre>
-</div></div>
-<div class="paragraph"><p>Attributes set in the document header take precedence over
-configuration file attributes.</p></div>
-</td>
-</tr></table>
-</div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/tip.png" alt="Tip" />
-</td>
-<td class="content">Use the <code>asciidoc(1)</code> <code>-v</code> (<code>--verbose</code>) command-line option to see
-which configuration files are loaded and the order in which they are
-loaded.</td>
-</tr></table>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_document_attributes">27. Document Attributes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A document attribute is comprised of a <em>name</em> and a textual <em>value</em>
-and is used for textual substitution in AsciiDoc documents and
-configuration files. An attribute reference (an attribute name
-enclosed in braces) is replaced by the corresponding attribute
-value. Attribute names are case insensitive and can only contain
-alphanumeric, dash and underscore characters.</p></div>
-<div class="paragraph"><p>There are four sources of document attributes (from highest to lowest
-precedence):</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Command-line attributes.
-</p>
-</li>
-<li>
-<p>
-AttributeEntry, AttributeList, Macro and BlockId elements.
-</p>
-</li>
-<li>
-<p>
-Configuration file <code>[attributes]</code> sections.
-</p>
-</li>
-<li>
-<p>
-Intrinsic attributes.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Within each of these divisions the last processed entry takes
-precedence.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">If an attribute is not defined then the line containing the
-attribute reference is dropped. This property is used extensively in
-AsciiDoc configuration files to facilitate conditional markup
-generation.</td>
-</tr></table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X18">28. Attribute Entries</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>AttributeEntry</code> block element allows document attributes to be
-assigned within an AsciiDoc document. Attribute entries are added to
-the global document attributes dictionary. The attribute name/value
-syntax is a single line like:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>:<name>: <value></code></pre>
-</div></div>
-<div class="paragraph"><p>For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>:Author Initials: JB</code></pre>
-</div></div>
-<div class="paragraph"><p>This will set an attribute reference <code>{authorinitials}</code> to the value
-<em>JB</em> in the current document.</p></div>
-<div class="paragraph"><p>To delete (undefine) an attribute use the following syntax:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>:<name>!:</code></pre>
-</div></div>
-<div class="ulist"><div class="title">AttributeEntry behavior</div><ul>
-<li>
-<p>
-The attribute entry line begins with colon — no white space allowed
- in left margin.
-</p>
-</li>
-<li>
-<p>
-AsciiDoc converts the <code><name></code> to a legal attribute name (lower
- case, alphanumeric, dash and underscore characters only — all other
- characters deleted). This allows more human friendly text to be
- used.
-</p>
-</li>
-<li>
-<p>
-Leading and trailing white space is stripped from the <code><value></code>.
-</p>
-</li>
-<li>
-<p>
-Lines ending in a space followed by a plus character are continued
- to the next line, for example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>:description: AsciiDoc is a text document format for writing notes, +
- documentation, articles, books, slideshows, web pages +
- and man pages.</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-If the <code><value></code> is blank then the corresponding attribute value is
- set to an empty string.
-</p>
-</li>
-<li>
-<p>
-Attribute references contained in the entry <code><value></code> will be
- expanded.
-</p>
-</li>
-<li>
-<p>
-By default AttributeEntry values are substituted for
- <code>specialcharacters</code> and <code>attributes</code> (see above), if you want to
- change or disable AttributeEntry substitution use the <a href="#X77">pass:[] inline macro</a> syntax.
-</p>
-</li>
-<li>
-<p>
-Attribute entries in the document Header are available for header
- markup template substitution.
-</p>
-</li>
-<li>
-<p>
-Attribute elements override configuration file and intrinsic
- attributes but do not override command-line attributes.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Here are some more attribute entry examples:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>AsciiDoc User Manual
-====================
-:author: Stuart Rackham
-:email: srackham@gmail.com
-:revdate: April 23, 2004
-:revnumber: 5.1.1</code></pre>
-</div></div>
-<div class="paragraph"><p>Which creates these attributes:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>{author}, {firstname}, {lastname}, {authorinitials}, {email},
-{revdate}, {revnumber}</code></pre>
-</div></div>
-<div class="paragraph"><p>The previous example is equivalent to this <a href="#X95">document header</a>:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>AsciiDoc User Manual
-====================
-Stuart Rackham <srackham@gmail.com>
-5.1.1, April 23, 2004</code></pre>
-</div></div>
-<div class="sect2">
-<h3 id="_setting_configuration_entries">28.1. Setting configuration entries</h3>
-<div class="paragraph"><p>A variant of the Attribute Entry syntax allows configuration file
-section entries and markup template sections to be set from within an
-AsciiDoc document:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>:<section_name>.[<entry_name>]: <entry_value></code></pre>
-</div></div>
-<div class="paragraph"><p>Where <code><section_name></code> is the configuration section name,
-<code><entry_name></code> is the name of the entry and <code><entry_value></code> is the
-optional entry value. This example sets the default labeled list
-style to <em>horizontal</em>:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>:listdef-labeled.style: horizontal</code></pre>
-</div></div>
-<div class="paragraph"><p>It is exactly equivalent to a configuration file containing:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[listdef-labeled]
-style=horizontal</code></pre>
-</div></div>
-<div class="ulist"><ul>
-<li>
-<p>
-If the <code><entry_name></code> is omitted then the entire section is
- substituted with the <code><entry_value></code>. This feature should only be
- used to set markup template sections. The following example sets the
- <em>xref2</em> inline macro markup template:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>:xref2-inlinemacro.: <a href="#{1}">{2?{2}}</a></code></pre>
-</div></div>
-</li>
-<li>
-<p>
-No substitution is performed on configuration file attribute entries
- and they cannot be undefined.
-</p>
-</li>
-<li>
-<p>
-This feature can only be used in attribute entries — configuration
- attributes cannot be set using the <code>asciidoc(1)</code> command <code>--attribute</code>
- option.
-</p>
-</li>
-</ul></div>
-<div class="sidebarblock" id="X62">
-<div class="content">
-<div class="title">Attribute entries promote clarity and eliminate repetition</div>
-<div class="paragraph"><p>URLs and file names in AsciiDoc macros are often quite long — they
-break paragraph flow and readability suffers. The problem is
-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:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>:1: http://freshmeat.sourceforge.net/projects/asciidoc/
-:homepage: https://asciidoc.org[AsciiDoc home page]
-:new: image:./images/smallnew.png[]
-:footnote1: footnote:[A meaningless latin term]</code></pre>
-</div></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>Using previously defined attributes: See the {1}[Freshmeat summary]
-or the {homepage} for something new {new}. Lorem ispum {footnote1}.</code></pre>
-</div></div>
-<div class="ulist"><div class="title">Note</div><ul>
-<li>
-<p>
-The attribute entry definition must precede it’s usage.
-</p>
-</li>
-<li>
-<p>
-You are not limited to URLs or file names, entire macro calls or
- arbitrary lines of text can be abbreviated.
-</p>
-</li>
-<li>
-<p>
-Shared attributes entries could be grouped into a separate file and
- <a href="#X63">included</a> in multiple documents.
-</p>
-</li>
-</ul></div>
-</div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X21">29. Attribute Lists</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-An attribute list is a comma separated list of attribute values.
-</p>
-</li>
-<li>
-<p>
-The entire list is enclosed in square brackets.
-</p>
-</li>
-<li>
-<p>
-Attribute lists are used to pass parameters to macros, blocks (using
- the <a href="#X79">AttributeList element</a>) and inline quotes.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The list consists of zero or more positional attribute values followed
-by zero or more named attribute values. Here are three examples: a
-single unquoted positional attribute; three unquoted positional
-attribute values; one positional attribute followed by two named
-attributes; the unquoted attribute value in the final example contains
-comma (<code>&#44;</code>) and double-quote (<code>&#34;</code>) character entities:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>[Hello]
-[quote, Bertrand Russell, The World of Mathematics (1956)]
-["22 times", backcolor="#0e0e0e", options="noborders,wide"]
-[A footnote&#44; &#34;with an image&#34; image:smallnew.png[]]</code></pre>
-</div></div>
-<div class="ulist"><div class="title">Attribute list behavior</div><ul>
-<li>
-<p>
-If one or more attribute values contains a comma the all string
- values must be quoted (enclosed in double quotation mark
- characters).
-</p>
-</li>
-<li>
-<p>
-If the list contains any named or quoted attributes then all string
- attribute values must be quoted.
-</p>
-</li>
-<li>
-<p>
-To include a double quotation mark (") character in a quoted
- attribute value the the quotation mark must be escaped with a
- backslash.
-</p>
-</li>
-<li>
-<p>
-List attributes take precedence over existing attributes.
-</p>
-</li>
-<li>
-<p>
-List attributes can only be referenced in configuration file markup
- templates and tags, they are not available elsewhere in the
- document.
-</p>
-</li>
-<li>
-<p>
-Setting a named attribute to <code>None</code> undefines the attribute.
-</p>
-</li>
-<li>
-<p>
-Positional attributes are referred to as <code>{1}</code>,<code>{2}</code>,<code>{3}</code>,…
-</p>
-</li>
-<li>
-<p>
-Attribute <code>{0}</code> refers to the entire list (excluding the enclosing
- square brackets).
-</p>
-</li>
-<li>
-<p>
-Named attribute names cannot contain dash characters.
-</p>
-</li>
-</ul></div>
-<div class="sect2">
-<h3 id="X75">29.1. Options attribute</h3>
-<div class="paragraph"><p>If the attribute list contains an attribute named <code>options</code> it is
-processed as a comma separated list of option names:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Each name generates an attribute named like <code><option>-option</code> (where
- <code><option></code> is the option name) with an empty string value. For
- example <code>[options="opt1,opt2,opt3"]</code> is equivalent to setting the
- following three attributes
- <code>[opt1-option="",opt2-option="",opt2-option=""]</code>.
-</p>
-</li>
-<li>
-<p>
-If you define a an option attribute globally (for example with an
- <a href="#X18">attribute entry</a>) then it will apply to all elements in the
- document.
-</p>
-</li>
-<li>
-<p>
-AsciiDoc implements a number of predefined options which are listed
- in the <a href="#X74">Attribute Options appendix</a>.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="_macro_attribute_lists">29.2. Macro Attribute lists</h3>
-<div class="paragraph"><p>Macros calls are suffixed with an attribute list. The list may be
-empty but it cannot be omitted. List entries are used to pass
-attribute values to macro markup templates.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_attribute_references">30. Attribute References</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An attribute reference is an attribute name (possibly followed by an
-additional parameters) enclosed in curly braces. When an attribute
-reference is encountered it is evaluated and replaced by its
-corresponding text value. If the attribute is undefined the line
-containing the attribute is dropped.</p></div>
-<div class="paragraph"><p>There are three types of attribute reference: <em>Simple</em>, <em>Conditional</em>
-and <em>System</em>.</p></div>
-<div class="ulist"><div class="title">Attribute reference evaluation</div><ul>
-<li>
-<p>
-You can suppress attribute reference expansion by placing a
- backslash character immediately in front of the opening brace
- character.
-</p>
-</li>
-<li>
-<p>
-By default attribute references are not expanded in
- <em>LiteralParagraphs</em>, <em>ListingBlocks</em> or <em>LiteralBlocks</em>.
-</p>
-</li>
-<li>
-<p>
-Attribute substitution proceeds line by line in reverse line order.
-</p>
-</li>
-<li>
-<p>
-Attribute reference evaluation is performed in the following order:
- <em>Simple</em> then <em>Conditional</em> and finally <em>System</em>.
-</p>
-</li>
-</ul></div>
-<div class="sect2">
-<h3 id="_simple_attributes_references">30.1. Simple Attributes References</h3>
-<div class="paragraph"><p>Simple attribute references take the form <code>{<name>}</code>. If the
-attribute name is defined its text value is substituted otherwise the
-line containing the reference is dropped from the output.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_conditional_attribute_references">30.2. Conditional Attribute References</h3>
-<div class="paragraph"><p>Additional parameters are used in conjunction with attribute names to
-calculate a substitution value. Conditional attribute references take
-the following forms:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>{<names>=<value>}</code>
-</dt>
-<dd>
-<p>
- <code><value></code> is substituted if the attribute <code><names></code> is
- undefined otherwise its value is substituted. <code><value></code> can
- contain simple attribute references.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{<names>?<value>}</code>
-</dt>
-<dd>
-<p>
- <code><value></code> is substituted if the attribute <code><names></code> is defined
- otherwise an empty string is substituted. <code><value></code> can
- contain simple attribute references.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{<names>!<value>}</code>
-</dt>
-<dd>
-<p>
- <code><value></code> is substituted if the attribute <code><names></code> is
- undefined otherwise an empty string is substituted. <code><value></code>
- can contain simple attribute references.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{<names>#<value>}</code>
-</dt>
-<dd>
-<p>
- <code><value></code> is substituted if the attribute <code><names></code> is defined
- otherwise the undefined attribute entry causes the containing
- line to be dropped. <code><value></code> can contain simple attribute
- references.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{<names>%<value>}</code>
-</dt>
-<dd>
-<p>
- <code><value></code> is substituted if the attribute <code><names></code> is not
- defined otherwise the containing line is dropped. <code><value></code>
- can contain simple attribute references.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{<names>@<regexp>:<value1>[:<value2>]}</code>
-</dt>
-<dd>
-<p>
- <code><value1></code> is substituted if the value of attribute <code><names></code>
- matches the regular expression <code><regexp></code> otherwise <code><value2></code>
- is substituted. If attribute <code><names></code> is not defined the
- containing line is dropped. If <code><value2></code> is omitted an empty
- string is assumed. The values and the regular expression can
- contain simple attribute references. To embed colons in the
- values or the regular expression escape them with backslashes.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{<names>$<regexp>:<value1>[:<value2>]}</code>
-</dt>
-<dd>
-<p>
- Same behavior as the previous ternary attribute except for
- the following cases:
-</p>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>{<names>$<regexp>:<value>}</code>
-</dt>
-<dd>
-<p>
- Substitutes <code><value></code> if <code><names></code> matches <code><regexp></code>
- otherwise the result is undefined and the containing
- line is dropped.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{<names>$<regexp>::<value>}</code>
-</dt>
-<dd>
-<p>
- Substitutes <code><value></code> if <code><names></code> does not match
- <code><regexp></code> otherwise the result is undefined and the
- containing line is dropped.
-</p>
-</dd>
-</dl></div>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The attribute <code><names></code> parameter normally consists of a single
-attribute name but it can be any one of the following:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A single attribute name which evaluates to the attributes value.
-</p>
-</li>
-<li>
-<p>
-Multiple <em>,</em> separated attribute names which evaluates to an empty
- string if one or more of the attributes is defined, otherwise it’s
- value is undefined.
-</p>
-</li>
-<li>
-<p>
-Multiple <em>+</em> separated attribute names which evaluates to an empty
- string if all of the attributes are defined, otherwise it’s value is
- undefined.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Conditional attributes with single attribute names are evaluated first
-so they can be used inside the multi-attribute conditional <code><value></code>.</p></div>
-<div class="sect3">
-<h4 id="_conditional_attribute_examples">30.2.1. Conditional attribute examples</h4>
-<div class="paragraph"><p>Conditional attributes are mainly used in AsciiDoc configuration
-files — see the distribution <code>.conf</code> files for examples.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Attribute equality test
-</dt>
-<dd>
-<p>
- If <code>{backend}</code> is <em>docbook45</em> or <em>xhtml11</em> the example evaluates to
- “DocBook 4.5 or XHTML 1.1 backend” otherwise it evaluates to
- “some other backend”:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>{backend@docbook45|xhtml11:DocBook 4.5 or XHTML 1.1 backend:some other backend}</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-Attribute value map
-</dt>
-<dd>
-<p>
- This example maps the <code>frame</code> attribute values [<code>topbot</code>, <code>all</code>,
- <code>none</code>, <code>sides</code>] to [<code>hsides</code>, <code>border</code>, <code>void</code>, <code>vsides</code>]:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>{frame@topbot:hsides}{frame@all:border}{frame@none:void}{frame@sides:vsides}</code></pre>
-</div></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="X24">30.3. System Attribute References</h3>
-<div class="paragraph"><p>System attribute references generate the attribute text value by
-executing a predefined action that is parametrized by one or more
-arguments. The syntax is <code>{<action>:<arguments>}</code>.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>{counter:<attrname>[:<seed>]}</code>
-</dt>
-<dd>
-<p>
- Increments the document attribute (if the attribute is
- undefined it is set to <code>1</code>). Returns the new attribute value.
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-Counters generate global (document wide) attributes.
-</p>
-</li>
-<li>
-<p>
-The optional <code><seed></code> specifies the counter’s initial value;
- it can be a number or a single letter; defaults to <em>1</em>.
-</p>
-</li>
-<li>
-<p>
-<code><seed></code> can contain simple and conditional attribute
- references.
-</p>
-</li>
-<li>
-<p>
-The <em>counter</em> system attribute will not be executed if the
- containing line is dropped by the prior evaluation of an
- undefined attribute.
-</p>
-</li>
-</ul></div>
-</dd>
-<dt class="hdlist1">
-<code>{counter2:<attrname>[:<seed>]}</code>
-</dt>
-<dd>
-<p>
- Same as <code>counter</code> except the it always returns a blank string.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{eval:<expression>}</code>
-</dt>
-<dd>
-<p>
- Substitutes the result of the Python <code><expression></code>.
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-If <code><expression></code> evaluates to <code>None</code> or <code>False</code> the
- reference is deemed undefined and the line containing the
- reference is dropped from the output.
-</p>
-</li>
-<li>
-<p>
-If the expression evaluates to <code>True</code> the attribute
- evaluates to an empty string.
-</p>
-</li>
-<li>
-<p>
-<code><expression></code> can contain simple and conditional attribute
- references.
-</p>
-</li>
-<li>
-<p>
-The <em>eval</em> system attribute can be nested inside other
- system attributes.
-</p>
-</li>
-</ul></div>
-</dd>
-<dt class="hdlist1">
-<code>{eval3:<command>}</code>
-</dt>
-<dd>
-<p>
- Passthrough version of <code>{eval:<expression>}</code> — the generated
- output is written directly to the output without any further
- substitutions.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{include:<filename>}</code>
-</dt>
-<dd>
-<p>
- Substitutes contents of the file named <code><filename></code>.
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-The included file is read at the time of attribute
- substitution.
-</p>
-</li>
-<li>
-<p>
-If the file does not exist a warning is emitted and the line
- containing the reference is dropped from the output file.
-</p>
-</li>
-<li>
-<p>
-Tabs are expanded based on the current <em>tabsize</em> attribute
- value.
-</p>
-</li>
-</ul></div>
-</dd>
-<dt class="hdlist1">
-<code>{set:<attrname>[!][:<value>]}</code>
-</dt>
-<dd>
-<p>
- Sets or unsets document attribute. Normally only used in
- configuration file markup templates (use
- <a href="#X18">AttributeEntries</a> in AsciiDoc documents).
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-If the attribute name is followed by an exclamation mark
- the attribute becomes undefined.
-</p>
-</li>
-<li>
-<p>
-If <code><value></code> is omitted the attribute is set to a blank
- string.
-</p>
-</li>
-<li>
-<p>
-<code><value></code> can contain simple and conditional attribute
- references.
-</p>
-</li>
-<li>
-<p>
-Returns a blank string unless the attribute is undefined in
- which case the return value is undefined and the enclosing
- line will be dropped.
-</p>
-</li>
-</ul></div>
-</dd>
-<dt class="hdlist1">
-<code>{set2:<attrname>[!][:<value>]}</code>
-</dt>
-<dd>
-<p>
- Same as <code>set</code> except that the attribute scope is local to the
- template.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{sys:<command>}</code>
-</dt>
-<dd>
-<p>
- Substitutes the stdout generated by the execution of the shell
- <code><command></code>.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{sys2:<command>}</code>
-</dt>
-<dd>
-<p>
- Substitutes the stdout and stderr generated by the execution
- of the shell <code><command></code>.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{sys3:<command>}</code>
-</dt>
-<dd>
-<p>
- Passthrough version of <code>{sys:<command>}</code> — the generated
- output is written directly to the output without any further
- substitutions.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>{template:<template>}</code>
-</dt>
-<dd>
-<p>
- Substitutes the contents of the configuration file section
- named <code><template></code>. Attribute references contained in the
- template are substituted.
-</p>
-</dd>
-</dl></div>
-<div class="ulist"><div class="title">System reference behavior</div><ul>
-<li>
-<p>
-System attribute arguments can contain non-system attribute
- references.
-</p>
-</li>
-<li>
-<p>
-Closing brace characters inside system attribute arguments must be
- escaped with a backslash.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X60">31. Intrinsic Attributes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Intrinsic attributes are simple attributes that are created
-automatically from: AsciiDoc document header parameters; <code>asciidoc(1)</code>
-command-line arguments; attributes defined in the default
-configuration files; the execution context. Here’s the list of
-predefined intrinsic attributes:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>{amp} ampersand (&) character entity
-{asciidoc-args} used to pass inherited arguments to asciidoc filters
-{asciidoc-confdir} the asciidoc(1) global configuration directory
-{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,
-{authorinitials} author initials (from document header)
-{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 (note 9)
-{docdir} document input directory name (note 5)
-{docfile} document file name (note 5)
-{docname} document file name without extension (note 6)
-{doctime} document last modified time (note 9)
-{doctitle} document title (from document header)
-{doctype-<doctype>} empty string ''
-{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)
-{gt} greater than (>) character entity
-{id} running block id generated by BlockId elements
-{indir} input file directory name (note 2,5)
-{infile} input file name (note 2,5)
-{lastname} author last name (from document header)
-{ldquo} Left double quote character (note 7)
-{level} title level 1..4 (in section titles)
-{listindex} the list index (1..) of the most recent list item
-{localdate} the current date (note 9)
-{localtime} the current time (note 9)
-{lsquo} Left single quote character (note 7)
-{lt} less than (<) character entity
-{manname} manpage name (defined in NAME section)
-{manpurpose} manpage (defined in NAME section)
-{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 character entity
-{notitle} do not display the document title
-{outdir} document output directory name (note 2)
-{outfile} output file name (note 2)
-{plus} plus character
-{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
-{two-semicolons} two semicolon characters
-{user-dir} the ~/.asciidoc directory (if it exists)
-{verbose} defined as '' if --verbose command option specified
-{wj} word-joiner
-{zwsp} zero-width space character entity</code></pre>
-</div></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Intrinsic attributes are global so avoid defining custom attributes
- with the same names.
-</p>
-</li>
-<li>
-<p>
-<code>{outfile}</code>, <code>{outdir}</code>, <code>{infile}</code>, <code>{indir}</code> attributes are
- effectively read-only (you can set them but it won’t affect the
- input or output file paths).
-</p>
-</li>
-<li>
-<p>
-See also the <a href="#X88">Backend Attributes</a> section for attributes
- that relate to AsciiDoc XHTML file generation.
-</p>
-</li>
-<li>
-<p>
-The entries that translate to blank strings are designed to be used
- for conditional text inclusion. You can also use the <code>ifdef</code>,
- <code>ifndef</code> and <code>endif</code> System macros for conditional inclusion.
- <span class="footnote"><br />[Conditional inclusion using <code>ifdef</code> and <code>ifndef</code> macros
- differs from attribute conditional inclusion in that the former
- occurs when the file is read while the latter occurs when the
- contents are written.]<br /></span>
-</p>
-</li>
-<li>
-<p>
-<code>{docfile}</code> and <code>{docdir}</code> refer to root document specified on the
- <code>asciidoc(1)</code> command-line; <code>{infile}</code> and <code>{indir}</code> refer to the
- current input file which may be the root document or an included
- file. When the input is being read from the standard input
- (<code>stdin</code>) these attributes are undefined.
-</p>
-</li>
-<li>
-<p>
-If the input file is the standard input and the output file is not
- the standard output then <code>{docname}</code> is the output file name sans
- file extension.
-</p>
-</li>
-<li>
-<p>
-See
- <a href="https://en.wikipedia.org/wiki/Quotation_mark#Summary_table">non-English
- usage of quotation marks</a>.
-</p>
-</li>
-<li>
-<p>
-The <code>{blockname}</code> attribute identifies the style of the current
- block. It applies to delimited blocks, lists and tables. Here is a
- list of <code>{blockname}</code> values (does not include filters or custom
- block and style names):
-</p>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-delimited blocks
-</dt>
-<dd>
-<p>
-comment, sidebar, open, pass, literal, verse,
- listing, quote, example, note, tip, important, caution, warning,
- abstract, partintro
-</p>
-</dd>
-<dt class="hdlist1">
-lists
-</dt>
-<dd>
-<p>
-arabic, loweralpha, upperalpha, lowerroman, upperroman,
- labeled, labeled3, labeled4, qanda, horizontal, bibliography,
- glossary
-</p>
-</dd>
-<dt class="hdlist1">
-tables
-</dt>
-<dd>
-<p>
-table
-</p>
-</dd>
-</dl></div>
-</li>
-<li>
-<p>
-If the <code>SOURCE_DATE_EPOCH</code> environment variable is set to a UNIX
- timestamp, then the <code>{docdate}</code>, <code>{doctime}</code>, <code>{localdate}</code>, and
- <code>{localtime}</code> attributes are computed in the UTC time zone, with any
- timestamps newer than <code>SOURCE_DATE_EPOCH</code> replaced by
- <code>SOURCE_DATE_EPOCH</code>. (This helps software using AsciiDoc to build
- reproducibly.)
-</p>
-</li>
-</ol></div>
-</td>
-</tr></table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X73">32. Block Element Definitions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The syntax and behavior of Paragraph, DelimitedBlock, List and Table
-block elements is determined by block definitions contained in
-<a href="#X7">AsciiDoc configuration file</a> sections.</p></div>
-<div class="paragraph"><p>Each definition consists of a section title followed by one or more
-section entries. Each entry defines a block parameter controlling some
-aspect of the block’s behavior. Here’s an example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[blockdef-listing]
-delimiter=^-{4,}$
-template=listingblock
-presubs=specialcharacters,callouts</code></pre>
-</div></div>
-<div class="paragraph"><p>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
-<a href="#X27">loading configuration files</a>.</p></div>
-<div class="paragraph"><p>AsciiDoc Paragraph, DelimitedBlock, List and Table block elements
-share a common subset of configuration file parameters:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-delimiter
-</dt>
-<dd>
-<p>
- A Python regular expression that matches the first line of a block
- element — in the case of DelimitedBlocks and Tables it also matches
- the last line.
-</p>
-</dd>
-<dt class="hdlist1">
-template
-</dt>
-<dd>
-<p>
- The name of the configuration file markup template section that will
- envelope the block contents. The pipe (<em>|</em>) character is substituted
- for the block contents. List elements use a set of (list specific)
- tag parameters instead of a single template. The template name can
- contain attribute references allowing dynamic template selection a
- the time of template substitution.
-</p>
-</dd>
-<dt class="hdlist1">
-options
-</dt>
-<dd>
-<p>
- 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 <code><option>-option</code> (where <code><option></code> is the option name).
- See <a href="#X74">attribute options</a> for a complete list of available
- options.
-</p>
-</dd>
-<dt class="hdlist1">
-subs, presubs, postsubs
-</dt>
-<dd>
-<div class="ulist"><ul>
-<li>
-<p>
-<em>presubs</em> and <em>postsubs</em> are lists of comma separated substitutions that are
- performed on the block contents. <em>presubs</em> is applied first,
- <em>postsubs</em> (if specified) second.
-</p>
-</li>
-<li>
-<p>
-<em>subs</em> is an alias for <em>presubs</em>.
-</p>
-</li>
-<li>
-<p>
-If a <em>filter</em> is allowed (Paragraphs, DelimitedBlocks and Tables)
- and has been specified then <em>presubs</em> and <em>postsubs</em> substitutions
- are performed before and after the filter is run respectively.
-</p>
-</li>
-<li>
-<p>
-Allowed values: <em>specialcharacters</em>, <em>quotes</em>, <em>specialwords</em>,
- <em>replacements</em>, <em>macros</em>, <em>attributes</em>, <em>callouts</em>.
-</p>
-</li>
-<li>
-<p>
-<a id="X102"></a>The following composite values are also allowed:
-</p>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<em>none</em>
-</dt>
-<dd>
-<p>
- No substitutions.
-</p>
-</dd>
-<dt class="hdlist1">
-<em>normal</em>
-</dt>
-<dd>
-<p>
- The following substitutions in the following order:
- <em>specialcharacters</em>, <em>quotes</em>, <em>attributes</em>, <em>specialwords</em>,
- <em>replacements</em>, <em>macros</em>, <em>replacements2</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-<em>verbatim</em>
-</dt>
-<dd>
-<p>
- The following substitutions in the following order:
- <em>specialcharacters</em> and <em>callouts</em>.
-</p>
-</dd>
-</dl></div>
-</li>
-<li>
-<p>
-<em>normal</em> and <em>verbatim</em> substitutions can be redefined by with
- <code>subsnormal</code> and <code>subsverbatim</code> entries in a configuration file
- <code>[miscellaneous]</code> section.
-</p>
-</li>
-<li>
-<p>
-The substitutions are processed in the order in which they are
- listed and can appear more than once.
-</p>
-</li>
-</ul></div>
-</dd>
-<dt class="hdlist1">
-filter
-</dt>
-<dd>
-<p>
- This optional entry specifies an executable shell command for
- processing block content (Paragraphs, DelimitedBlocks and Tables).
- The filter command can contain attribute references.
-</p>
-</dd>
-<dt class="hdlist1">
-posattrs
-</dt>
-<dd>
-<p>
- Optional comma separated list of positional attribute names. This
- list maps positional attributes (in the block’s <a href="#X21">attribute list</a>) to named block attributes. The following example, from the
- QuoteBlock definition, maps the first and section positional
- attributes:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>posattrs=attribution,citetitle</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-style
-</dt>
-<dd>
-<p>
- This optional parameter specifies the default style name.
-</p>
-</dd>
-<dt class="hdlist1">
-<stylename>-style
-</dt>
-<dd>
-<p>
- Optional style definition (see <a href="#X23">Styles</a> below).
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The following block parameters behave like document attributes and can
-be set in block attribute lists and style definitions: <em>template</em>,
-<em>options</em>, <em>subs</em>, <em>presubs</em>, <em>postsubs</em>, <em>filter</em>.</p></div>
-<div class="sect2">
-<h3 id="X23">32.1. Styles</h3>
-<div class="paragraph"><p>A style is a set of block parameter bundled as a single named
-parameter. The following example defines a style named <em>verbatim</em>:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>verbatim-style=template="literalblock",subs="verbatim"</code></pre>
-</div></div>
-<div class="paragraph"><p>If a block’s <a href="#X21">attribute list</a> contains a <em>style</em> attribute then
-the corresponding style parameters are be merged into the default
-block definition parameters.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-All style parameter names must be suffixed with <code>-style</code> and the
- style parameter value is in the form of a list of <a href="#X21">named attributes</a>.
-</p>
-</li>
-<li>
-<p>
-The <em>template</em> style parameter is mandatory, other parameters can be
- omitted in which case they inherit their values from the default
- block definition parameters.
-</p>
-</li>
-<li>
-<p>
-Multi-item style parameters (<em>subs</em>,<em>presubs</em>,<em>postsubs</em>,<em>posattrs</em>)
- must be specified using Python tuple syntax (rather than a simple
- list of values as they in separate entries) e.g.
- <code>postsubs=("callouts",)</code> not <code>postsubs="callouts"</code>.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="_paragraphs_2">32.2. Paragraphs</h3>
-<div class="paragraph"><p>Paragraph translation is controlled by <code>[paradef-*]</code> configuration
-file section entries. Users can define new types of paragraphs and
-modify the behavior of existing types by editing AsciiDoc
-configuration files.</p></div>
-<div class="paragraph"><p>Here is the shipped Default paragraph definition:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[paradef-default]
-delimiter=(?P<text>\S.*)
-template=paragraph</code></pre>
-</div></div>
-<div class="paragraph"><p>The normal paragraph definition has a couple of special properties:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-It must exist and be defined in a configuration file section named
- <code>[paradef-default]</code>.
-</p>
-</li>
-<li>
-<p>
-Irrespective of its position in the configuration files default
- paragraph document matches are attempted only after trying all
- other paragraph types.
-</p>
-</li>
-</ol></div>
-<div class="paragraph"><p>Paragraph specific block parameter notes:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-delimiter
-</dt>
-<dd>
-<p>
- This regular expression must contain the named group <em>text</em> which
- matches the text on the first line. Paragraphs are terminated by a
- blank line, the end of file, or the start of a DelimitedBlock.
-</p>
-</dd>
-<dt class="hdlist1">
-options
-</dt>
-<dd>
-<p>
- The <em>listelement</em> option specifies that paragraphs of this type will
- automatically be considered part of immediately preceding list
- items. The <em>skip</em> option causes the paragraph to be treated as a
- comment (see <a href="#X26">CommentBlocks</a>).
-</p>
-</dd>
-</dl></div>
-<div class="olist arabic"><div class="title">Paragraph processing proceeds as follows:</div><ol class="arabic">
-<li>
-<p>
-The paragraph text is aligned to the left margin.
-</p>
-</li>
-<li>
-<p>
-Optional <em>presubs</em> inline substitutions are performed on the
- paragraph text.
-</p>
-</li>
-<li>
-<p>
-If a filter command is specified it is executed and the paragraph
- text piped to its standard input; the filter output replaces the
- paragraph text.
-</p>
-</li>
-<li>
-<p>
-Optional <em>postsubs</em> inline substitutions are performed on the
- paragraph text.
-</p>
-</li>
-<li>
-<p>
-The paragraph text is enveloped by the paragraph’s markup template
- and written to the output file.
-</p>
-</li>
-</ol></div>
-</div>
-<div class="sect2">
-<h3 id="_delimited_blocks">32.3. Delimited Blocks</h3>
-<div class="paragraph"><p>DelimitedBlock <em>options</em> values are:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-sectionbody
-</dt>
-<dd>
-<p>
- The block contents are processed as a SectionBody.
-</p>
-</dd>
-<dt class="hdlist1">
-skip
-</dt>
-<dd>
-<p>
- The block is treated as a comment (see <a href="#X26">CommentBlocks</a>).
- Preceding <a href="#X21">attribute lists</a> and <a href="#X42">block titles</a> are not
- consumed.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p><em>presubs</em>, <em>postsubs</em> and <em>filter</em> entries are ignored when
-<em>sectionbody</em> or <em>skip</em> options are set.</p></div>
-<div class="paragraph"><p>DelimitedBlock processing proceeds as follows:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Optional <em>presubs</em> substitutions are performed on the block
- contents.
-</p>
-</li>
-<li>
-<p>
-If a filter is specified it is executed and the block’s contents
- piped to its standard input. The filter output replaces the block
- contents.
-</p>
-</li>
-<li>
-<p>
-Optional <em>postsubs</em> substitutions are performed on the block
- contents.
-</p>
-</li>
-<li>
-<p>
-The block contents is enveloped by the block’s markup template and
- written to the output file.
-</p>
-</li>
-</ol></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/tip.png" alt="Tip" />
-</td>
-<td class="content">Attribute expansion is performed on the block filter command
-before it is executed, this is useful for passing arguments to the
-filter.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_lists">32.4. Lists</h3>
-<div class="paragraph"><p>List behavior and syntax is determined by <code>[listdef-*]</code> configuration
-file sections. The user can change existing list behavior and add new
-list types by editing configuration files.</p></div>
-<div class="paragraph"><p>List specific block definition notes:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-type
-</dt>
-<dd>
-<p>
- This is either <em>bulleted</em>,<em>numbered</em>,<em>labeled</em> or <em>callout</em>.
-</p>
-</dd>
-<dt class="hdlist1">
-delimiter
-</dt>
-<dd>
-<p>
- A Python regular expression that matches the first line of a
- list element entry. This expression can contain the named groups
- <em>text</em> (bulleted groups), <em>index</em> and <em>text</em> (numbered lists),
- <em>label</em> and <em>text</em> (labeled lists).
-</p>
-</dd>
-<dt class="hdlist1">
-tags
-</dt>
-<dd>
-<p>
- The <code><name></code> of the <code>[listtags-<name>]</code> configuration file section
- containing list markup tag definitions. The tag entries (<em>list</em>,
- <em>entry</em>, <em>label</em>, <em>term</em>, <em>text</em>) map the AsciiDoc list structure to
- backend markup; see the <em>listtags</em> sections in the AsciiDoc
- distributed backend <code>.conf</code> configuration files for examples.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_tables_2">32.5. Tables</h3>
-<div class="paragraph"><p>Table behavior and syntax is determined by <code>[tabledef-*]</code> and
-<code>[tabletags-*]</code> configuration file sections. The user can change
-existing table behavior and add new table types by editing
-configuration files. The following <code>[tabledef-*]</code> section entries
-generate table output markup elements:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-colspec
-</dt>
-<dd>
-<p>
- The table <em>colspec</em> tag definition.
-</p>
-</dd>
-<dt class="hdlist1">
-headrow, footrow, bodyrow
-</dt>
-<dd>
-<p>
- Table header, footer and body row tag definitions. <em>headrow</em> and
- <em>footrow</em> table definition entries default to <em>bodyrow</em> if
- they are undefined.
-</p>
-</dd>
-<dt class="hdlist1">
-headdata, footdata, bodydata
-</dt>
-<dd>
-<p>
- Table header, footer and body data tag definitions. <em>headdata</em> and
- <em>footdata</em> table definition entries default to <em>bodydata</em> if they
- are undefined.
-</p>
-</dd>
-<dt class="hdlist1">
-paragraph
-</dt>
-<dd>
-<p>
- If the <em>paragraph</em> tag is specified then blank lines in the cell
- data are treated as paragraph delimiters and marked up using this
- tag.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph" id="X4"><p>Table behavior is also influenced by the following <code>[miscellaneous]</code>
-configuration file entries:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-pagewidth
-</dt>
-<dd>
-<p>
- This integer value is the printable width of the output media. See
- <a href="#X69">table attributes</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-pageunits
-</dt>
-<dd>
-<p>
- The units of width in output markup width attribute values.
-</p>
-</dd>
-</dl></div>
-<div class="ulist"><div class="title">Table definition behavior</div><ul>
-<li>
-<p>
-The output markup generation is specifically designed to work with
- the HTML and CALS (DocBook) table models, but should be adaptable to
- most XML table schema.
-</p>
-</li>
-<li>
-<p>
-Table definitions can be “mixed in” from multiple cascading
- configuration files.
-</p>
-</li>
-<li>
-<p>
-New table definitions inherit the default table and table tags
- definitions (<code>[tabledef-default]</code> and <code>[tabletags-default]</code>) so you
- only need to override those conf file entries that require
- modification.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X59">33. Filters</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>AsciiDoc filters allow external commands to process AsciiDoc
-<em>Paragraphs</em>, <em>DelimitedBlocks</em> and <em>Table</em> content. Filters are
-primarily an extension mechanism for generating specialized outputs.
-Filters are implemented using external commands which are specified in
-configuration file definitions.</p></div>
-<div class="paragraph"><p>There’s nothing special about the filters, they’re just standard UNIX
-filters: they read text from the standard input, process it, and write
-to the standard output.</p></div>
-<div class="paragraph"><p>The <code>asciidoc(1)</code> command <code>--filter</code> option can be used to install and
-remove filters. The same option is used to unconditionally load a
-filter.</p></div>
-<div class="paragraph"><p>Attribute substitution is performed on the filter command prior to
-execution — attributes can be used to pass parameters from the
-AsciiDoc source document to the filter.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/warning.png" alt="Warning" />
-</td>
-<td class="content">Filters sometimes included executable code. Before installing
-a filter you should verify that it is from a trusted source.</td>
-</tr></table>
-</div>
-<div class="sect2">
-<h3 id="_filter_search_paths">33.1. Filter Search Paths</h3>
-<div class="paragraph"><p>If the filter command does not specify a directory path then
-<code>asciidoc(1)</code> recursively searches for the executable filter command:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-First it looks in the user’s <code>$HOME/.asciidoc/filters</code> directory.
-</p>
-</li>
-<li>
-<p>
-Next the global filters directory (usually <code>/etc/asciidoc/filters</code>
- or <code>/usr/local/etc/asciidoc</code>) directory is searched.
-</p>
-</li>
-<li>
-<p>
-Then it looks in the <code>asciidoc(1)</code> <code>./filters</code> directory.
-</p>
-</li>
-<li>
-<p>
-Finally it relies on the executing shell to search the environment
- search path (<code>$PATH</code>).
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Standard practice is to install each filter in it’s own sub-directory
-with the same name as the filter’s style definition. For example the
-music filter’s style name is <em>music</em> so it’s configuration and filter
-files are stored in the <code>filters/music</code> directory.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_filter_configuration_files">33.2. Filter Configuration Files</h3>
-<div class="paragraph"><p>Filters are normally accompanied by a configuration file containing a
-Paragraph or DelimitedBlock definition along with corresponding markup
-templates.</p></div>
-<div class="paragraph"><p>While it is possible to create new <em>Paragraph</em> or <em>DelimitedBlock</em>
-definitions the preferred way to implement a filter is to add a
-<a href="#X23">style</a> to the existing Paragraph and ListingBlock definitions
-(all filters shipped with AsciiDoc use this technique). The filter is
-applied to the paragraph or delimited block by preceding it with an
-attribute list: the first positional attribute is the style name,
-remaining attributes are normally filter specific parameters.</p></div>
-<div class="paragraph"><p><code>asciidoc(1)</code> auto-loads all <code>.conf</code> files found in the filter search
-paths unless the container directory also contains a file named
-<code>__noautoload__</code> (see previous section). The <code>__noautoload__</code> feature
-is used for filters that will be loaded manually using the <code>--filter</code>
-option.</p></div>
-</div>
-<div class="sect2">
-<h3 id="X56">33.3. Example Filter</h3>
-<div class="paragraph"><p>AsciiDoc comes with a toy filter for highlighting source code keywords
-and comments. See also the <code>./filters/code/code-filter-readme.txt</code>
-file.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">The purpose of this toy filter is to demonstrate how to write a
-filter — 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 <a href="https://asciidoc.org/source-highlight-filter.html">source code highlighter
-filter</a>.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_built_in_filters">33.4. Built-in filters</h3>
-<div class="paragraph"><p>The AsciiDoc distribution includes <em>source</em>, <em>music</em>, <em>latex</em> and
-<em>graphviz</em> filters, details are on the
-<a href="https://asciidoc.org/index.html#_filters">AsciiDoc website</a>.</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="hsides"
-cellspacing="0" cellpadding="4">
-<caption class="title">Table 11. Built-in filters list</caption>
-<col width="16%" />
-<col width="83%" />
-<thead>
-<tr>
-<th align="left" valign="top">Filter name </th>
-<th align="left" valign="top">Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table"><em>music</em></p></td>
-<td align="left" valign="top"><p class="table">A <a href="https://asciidoc.org/music-filter.html">music filter</a> is included in the
-distribution <code>./filters/</code> directory. It translates music in
-<a href="https://lilypond.org/">LilyPond</a> or <a href="https://abcnotation.com/">ABC</a>
-notation to standard classical notation.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>source</em></p></td>
-<td align="left" valign="top"><p class="table">A <a href="https://asciidoc.org/source-highlight-filter.html">source code highlight filter</a>
-is included in the distribution <code>./filters/</code> directory.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>latex</em></p></td>
-<td align="left" valign="top"><p class="table">The <a href="https://asciidoc.org/latex-filter.html">AsciiDoc LaTeX filter</a> translates
-LaTeX source to an image that is automatically inserted into the
-AsciiDoc output documents.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>graphviz</em></p></td>
-<td align="left" valign="top"><p class="table">Gouichi Iisaka has written a <a href="https://www.graphviz.org/">Graphviz</a>
-filter for AsciiDoc. Graphviz generates diagrams from a textual
-specification. Gouichi Iisaka’s Graphviz filter is included in the
-AsciiDoc distribution. Here are some
-<a href="https://asciidoc.org/asciidoc-graphviz-sample.html">AsciiDoc Graphviz examples</a>.</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="X58">33.5. Filter plugins</h3>
-<div class="paragraph"><p>Filter <a href="#X101">plugins</a> are a mechanism for distributing AsciiDoc
-filters. A filter plugin is a Zip file containing the files that
-constitute a filter. The <code>asciidoc(1)</code> <code>--filter</code> option is used to
-load and manage filer <a href="#X101">plugins</a>.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Filter plugins <a href="#X27">take precedence</a> over built-in filters with
- the same name.
-</p>
-</li>
-<li>
-<p>
-By default filter plugins are installed in
- <code>$HOME/.asciidoc/filters/<filter></code> where <code><filter></code> is the filter
- name.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X101">34. Plugins</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The AsciiDoc plugin architecture is an extension mechanism that allows
-additional <a href="#X100">backends</a>, <a href="#X58">filters</a> and <a href="#X99">themes</a> to be
-added to AsciiDoc.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A plugin is a Zip file containing an AsciiDoc backend, filter or
- theme (configuration files, stylesheets, scripts, images).
-</p>
-</li>
-<li>
-<p>
-The <code>asciidoc(1)</code> <code>--backend</code>, <code>--filter</code> and <code>--theme</code> command-line
- options are used to load and manage plugins. Each of these options
- responds to the plugin management <em>install</em>, <em>list</em>, <em>remove</em> and
- <em>build</em> commands.
-</p>
-</li>
-<li>
-<p>
-The plugin management command names are reserved and cannot be used
- for filter, backend or theme names.
-</p>
-</li>
-<li>
-<p>
-The plugin Zip file name always begins with the backend, filter or
- theme name.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Plugin commands and conventions are documented in the <code>asciidoc(1)</code> man
-page. You can find lists of plugins on the
-<a href="https://asciidoc.org/plugins.html">AsciiDoc website</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X36">35. Help Commands</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>asciidoc(1)</code> command has a <code>--help</code> option which prints help topics
-to stdout. The default topic summarizes <code>asciidoc(1)</code> usage:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc --help</code></pre>
-</div></div>
-<div class="paragraph"><p>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:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc --help manpage
-$ asciidoc -h m # Short version of previous example.
-$ asciidoc --help syntax
-$ asciidoc -h s # Short version of previous example.</code></pre>
-</div></div>
-<div class="sect2">
-<h3 id="_customizing_help">35.1. Customizing Help</h3>
-<div class="paragraph"><p>To change, delete or add your own help topics edit a help
-configuration file. The help file name <code>help-<lang>.conf</code> is based on
-the setting of the <code>lang</code> attribute, it defaults to <code>help.conf</code>
-(English). The <a href="#X27">help file location</a> will depend on whether you
-want the topics to apply to all users or just the current user.</p></div>
-<div class="paragraph"><p>The help topic files have the same named section format as other
-<a href="#X7">configuration files</a>. The <code>help.conf</code> files are stored in the
-same locations and loaded in the same order as other configuration
-files.</p></div>
-<div class="paragraph"><p>When the <code>--help</code> 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 <code>default</code> is used. You don’t need to specify the whole help
-topic name on the command-line, just enough letters to ensure it’s not
-ambiguous. If a matching help file section is not found a list of
-available topics is printed.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_tips_and_tricks">36. Tips and Tricks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_know_your_editor">36.1. Know Your Editor</h3>
-<div class="paragraph"><p>Writing AsciiDoc documents will be a whole lot more pleasant if you
-know your favorite text editor. Learn how to indent and reformat text
-blocks, paragraphs, lists and sentences. <a href="#X20">Tips for <em>vim</em> users</a>
-follow.</p></div>
-</div>
-<div class="sect2">
-<h3 id="X20">36.2. Vim Commands for Formatting AsciiDoc</h3>
-<div class="sect3">
-<h4 id="_text_wrap_paragraphs">36.2.1. Text Wrap Paragraphs</h4>
-<div class="paragraph"><p>Use the vim <code>:gq</code> command to reformat paragraphs. Setting the
-<em>textwidth</em> sets the right text wrap margin; for example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>:set textwidth=70</code></pre>
-</div></div>
-<div class="paragraph"><p>To reformat a paragraph:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Position the cursor at the start of the paragraph.
-</p>
-</li>
-<li>
-<p>
-Type <code>gq}</code>.
-</p>
-</li>
-</ol></div>
-<div class="paragraph"><p>Execute <code>:help gq</code> command to read about the vim gq command.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/tip.png" alt="Tip" />
-</td>
-<td class="content">
-<div class="ulist"><ul>
-<li>
-<p>
-Assign the <code>gq}</code> command to the Q key with the <code>nnoremap Q gq}</code>
- command or put it in your <code>~/.vimrc</code> file to so it’s always
- available (see the <a href="#X61">Example <code>~/.vimrc</code> file</a>).
-</p>
-</li>
-<li>
-<p>
-Put <code>set</code> commands in your <code>~/.vimrc</code> file so you don’t have to
- enter them manually.
-</p>
-</li>
-<li>
-<p>
-The Vim website (<a href="https://www.vim.org/">https://www.vim.org/</a>) has a wealth of resources,
- including scripts for automated spell checking and ASCII Art
- drawing.
-</p>
-</li>
-</ul></div>
-</td>
-</tr></table>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_format_lists">36.2.2. Format Lists</h4>
-<div class="paragraph"><p>The <code>gq</code> command can also be used to format bulleted, numbered and
-callout lists. First you need to set the <code>comments</code>, <code>formatoptions</code>
-and <code>formatlistpat</code> (see the <a href="#X61">Example <code>~/.vimrc</code> file</a>).</p></div>
-<div class="paragraph"><p>Now you can format simple lists that use dash, asterisk, period and
-plus bullets along with numbered ordered lists:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Position the cursor at the start of the list.
-</p>
-</li>
-<li>
-<p>
-Type <code>gq}</code>.
-</p>
-</li>
-</ol></div>
-</div>
-<div class="sect3">
-<h4 id="_indent_paragraphs">36.2.3. Indent Paragraphs</h4>
-<div class="paragraph"><p>Indent whole paragraphs by indenting the fist line with the desired
-indent and then executing the <code>gq}</code> command.</p></div>
-</div>
-<div class="sect3">
-<h4 id="X61">36.2.4. Example <code>~/.vimrc</code> File</h4>
-<div class="listingblock">
-<div class="content">
-<pre><code>" Use bold bright fonts.
-set background=dark
-
-" Show tabs and trailing characters.
-"set listchars=tab:»·,trail:·,eol:¬
-set listchars=tab:»·,trail:·
-set list
-
-" Reformat paragraphs and list.
-nnoremap <Leader>r gq}
-
-" Delete trailing white space and Dos-returns and to expand tabs to spaces.
-nnoremap <Leader>t :set et<CR>:retab!<CR>:%s/[\r \t]\+$//<CR>
-
-autocmd BufRead,BufNewFile *.txt,*.asciidoc,README,TODO,CHANGELOG,NOTES,ABOUT
- \ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2 filetype=asciidoc
- \ textwidth=70 wrap formatoptions=tcqn
- \ formatlistpat=^\\s*\\d\\+\\.\\s\\+\\\\|^\\s*<\\d\\+>\\s\\+\\\\|^\\s*[a-zA-Z.]\\.\\s\\+\\\\|^\\s*[ivxIVX]\\+\\.\\s\\+
- \ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:></code></pre>
-</div></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_troubleshooting">36.3. Troubleshooting</h3>
-<div class="paragraph"><p>AsciiDoc diagnostic features are detailed in the <a href="#X82">Diagnostics appendix</a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gotchas">36.4. Gotchas</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Incorrect character encoding
-</dt>
-<dd>
-<p>
- If you get an error message like <code>'UTF-8' codec can't decode ...</code>
- then you source file contains invalid UTF-8 characters — set the
- AsciiDoc <a href="#X54">encoding attribute</a> for the correct character set
- (typically ISO-8859-1 (Latin-1) for European languages).
-</p>
-</dd>
-<dt class="hdlist1">
-Invalid output
-</dt>
-<dd>
-<p>
- AsciiDoc attempts to validate the input AsciiDoc source but makes
- no attempt to validate the output markup, it leaves that to
- external tools such as <code>xmllint(1)</code> (integrated into <code>a2x(1)</code>).
- Backend validation cannot be hardcoded into AsciiDoc because
- backends are dynamically configured. The following example
- generates valid HTML but invalid DocBook (the DocBook <code>literal</code>
- element cannot contain an <code>emphasis</code> element):
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>+monospaced text with an _emphasized_ word+</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-Misinterpreted text formatting
-</dt>
-<dd>
-<p>
- You can suppress markup expansion by placing a backslash character
- immediately in front of the element. The following example
- suppresses inline monospaced formatting:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>\+1 for C++.</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-Overlapping text formatting
-</dt>
-<dd>
-<p>
- Overlapping text formatting will generate illegal overlapping
- markup tags which will result in downstream XML parsing errors.
- Here’s an example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>Some *strong markup _that overlaps* emphasized markup_.</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-Ambiguous underlines
-</dt>
-<dd>
-<p>
- A DelimitedBlock can immediately follow a paragraph without an
- intervening blank line, but be careful, a single line paragraph
- underline may be misinterpreted as a section title underline
- resulting in a “closing block delimiter expected” error.
-</p>
-</dd>
-<dt class="hdlist1">
-Ambiguous ordered list items
-</dt>
-<dd>
-<p>
- Lines beginning with numbers at the end of sentences will be
- interpreted as ordered list items. The following example
- (incorrectly) begins a new list with item number 1999:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>He was last sighted in
-1999. Since then things have moved on.</code></pre>
-</div></div>
-<div class="paragraph"><p>The <em>list item out of sequence</em> warning makes it unlikely that this
-problem will go unnoticed.</p></div>
-</dd>
-<dt class="hdlist1">
-Special characters in attribute values
-</dt>
-<dd>
-<p>
- Special character substitution precedes attribute substitution so
- if attribute values contain special characters you may, depending
- on the substitution context, need to escape the special characters
- yourself. For example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a 'orgname=Bill &amp; Ben Inc.' mydoc.txt</code></pre>
-</div></div>
-</dd>
-<dt class="hdlist1">
-Attribute lists
-</dt>
-<dd>
-<p>
- If any named attribute entries are present then all string
- attribute values must be quoted. For example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>["Desktop screenshot",width=32]</code></pre>
-</div></div>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="X90">36.5. Combining separate documents</h3>
-<div class="paragraph"><p>You have a number of stand-alone AsciiDoc documents that you want to
-process as a single document. Simply processing them with a series of
-<code>include</code> macros won’t work because the documents contain (level 0)
-document titles. The solution is to create a top level wrapper
-document and use the <code>leveloffset</code> attribute to push them all down one
-level. For example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>Combined Document Title
-=======================
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::document1.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-A Top Level Section
--------------------
-Lorum ipsum.
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::document2.txt[]
-
-include::document3.txt[]</code></pre>
-</div></div>
-<div class="paragraph"><p>The document titles in the included documents will now be processed as
-level 1 section titles, level 1 sections as level 2 sections and so
-on.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Put a blank line between the <code>include</code> macro lines to ensure the
- title of the included document is not seen as part of the last
- paragraph of the previous document.
-</p>
-</li>
-<li>
-<p>
-You won’t want non-title document header lines (for example, Author
- and Revision lines) in the included files — conditionally exclude
- them if they are necessary for stand-alone processing.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="_processing_document_sections_separately">36.6. Processing document sections separately</h3>
-<div class="paragraph"><p>You have divided your AsciiDoc document into separate files (one per
-top level section) which are combined and processed with the following
-top level document:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>Combined Document Title
-=======================
-Joe Bloggs
-v1.0, 12-Aug-03
-
-include::section1.txt[]
-
-include::section2.txt[]
-
-include::section3.txt[]</code></pre>
-</div></div>
-<div class="paragraph"><p>You also want to process the section files as separate documents.
-This is easy because <code>asciidoc(1)</code> will quite happily process
-<code>section1.txt</code>, <code>section2.txt</code> and <code>section3.txt</code> separately — the
-resulting output documents contain the section but have no document
-title.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_processing_document_snippets">36.7. Processing document snippets</h3>
-<div class="paragraph"><p>Use the <code>-s</code> (<code>--no-header-footer</code>) command-line option to suppress
-header and footer output, this is useful if the processed output is to
-be included in another file. For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -sb docbook section1.txt</code></pre>
-</div></div>
-<div class="paragraph"><p><code>asciidoc(1)</code> can be used as a filter, so you can pipe chunks of text
-through it. For example:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ echo 'Hello *World!*' | asciidoc -s -
-<div class="paragraph"><p>Hello <strong>World!</strong></p></div></code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_badges_in_html_page_footers">36.8. Badges in HTML page footers</h3>
-<div class="paragraph"><p>See the <code>[footer]</code> section in the AsciiDoc distribution <code>xhtml11.conf</code>
-configuration file.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_pretty_printing_asciidoc_output">36.9. Pretty printing AsciiDoc output</h3>
-<div class="paragraph"><p>If the indentation and layout of the <code>asciidoc(1)</code> output is not to your
-liking you can:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Change the indentation and layout of configuration file markup
- template sections. The <code>{empty}</code> attribute is useful for outputting
- trailing blank lines in markup templates.
-</p>
-</li>
-<li>
-<p>
-Use <a href="https://www.html-tidy.org/">HTML Tidy</a> program to tidy
- <code>asciidoc(1)</code> output. Example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml >mydoc.xml</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-Use the <code>xmllint(1)</code> format option. Example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ xmllint --format mydoc.xml</code></pre>
-</div></div>
-</li>
-</ol></div>
-</div>
-<div class="sect2">
-<h3 id="_supporting_minor_docbook_dtd_variations">36.10. Supporting minor DocBook DTD variations</h3>
-<div class="paragraph"><p>The conditional inclusion of DocBook SGML markup at the end of the
-distribution <code>docbook45.conf</code> file illustrates how to support minor
-DTD variations. The included sections override corresponding entries
-from preceding sections.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_creating_stand_alone_html_documents">36.11. Creating stand-alone HTML documents</h3>
-<div class="paragraph"><p>If you’ve ever tried to send someone an HTML document that includes
-stylesheets and images you’ll know that it’s not as straight-forward
-as exchanging a single file. AsciiDoc has options to create
-stand-alone documents containing embedded images, stylesheets and
-scripts. The following AsciiDoc command creates a single file
-containing <a href="#X66">embedded images</a>, CSS stylesheets, and JavaScript
-(for table of contents and footnotes):</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt</code></pre>
-</div></div>
-<div class="paragraph"><p>You can view the HTML file here: <a href="https://asciidoc.org/article-standalone.html">https://asciidoc.org/article-standalone.html</a></p></div>
-</div>
-<div class="sect2">
-<h3 id="_shipping_stand_alone_asciidoc_source">36.12. Shipping stand-alone AsciiDoc source</h3>
-<div class="paragraph"><p>Reproducing presentation documents from someone else’s source has one
-major problem: unless your configuration files are the same as the
-creator’s you won’t get the same output.</p></div>
-<div class="paragraph"><p>The solution is to create a single backend specific configuration file
-using the <code>asciidoc(1)</code> <code>-c</code> (<code>--dump-conf</code>) command-line option. You
-then ship this file along with the AsciiDoc source document plus the
-<code>asciidoc.py</code> script. The only end user requirement is that they have
-Python installed (and that they consider you a trusted source). This
-example creates a composite HTML configuration file for <code>mydoc.txt</code>:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -cb xhtml11 mydoc.txt > mydoc-xhtml11.conf</code></pre>
-</div></div>
-<div class="paragraph"><p>Ship <code>mydoc.txt</code>, <code>mydoc-html.conf</code>, and <code>asciidoc.py</code>. With
-these three files (and a Python interpreter) the recipient can
-regenerate the HMTL output:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ ./asciidoc.py -eb xhtml11 mydoc.txt</code></pre>
-</div></div>
-<div class="paragraph"><p>The <code>-e</code> (<code>--no-conf</code>) option excludes the use of implicit
-configuration files, ensuring that only entries from the
-<code>mydoc-html.conf</code> configuration are used.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_inserting_blank_space">36.13. Inserting blank space</h3>
-<div class="paragraph"><p>Adjust your style sheets to add the correct separation between block
-elements. Inserting blank paragraphs containing a single non-breaking
-space character <code>{nbsp}</code> works but is an ad hoc solution compared
-to using style sheets.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_closing_open_sections">36.14. Closing open sections</h3>
-<div class="paragraph"><p>You can close off section tags up to level <code>N</code> by calling the
-<code>eval::[Section.setlevel(N)]</code> 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):</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>ifdef::basebackend-docbook[]
-
-eval::[Section.setlevel(0)]
-
-+++++++++++++++++++++++++++++++
-<glossary>
- <title>Glossary</title>
- <glossdiv>
- ...
- </glossdiv>
-</glossary>
-+++++++++++++++++++++++++++++++
-endif::basebackend-docbook[]</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_validating_output_files">36.15. Validating output files</h3>
-<div class="paragraph"><p>Use <code>xmllint(1)</code> to check the AsciiDoc generated markup is both well
-formed and valid. Here are some examples:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ xmllint --nonet --noout --valid docbook-file.xml
-$ xmllint --nonet --noout --valid xhtml11-file.html
-$ xmllint --nonet --noout --valid --html html4-file.html</code></pre>
-</div></div>
-<div class="paragraph"><p>The <code>--valid</code> option checks the file is valid against the document
-type’s DTD, if the DTD is not installed in your system’s catalog then
-it will be fetched from its Internet location. If you omit the
-<code>--valid</code> option the document will only be checked that it is well
-formed.</p></div>
-<div class="paragraph"><p>The online <a href="https://validator.w3.org/#validate_by_uri+with_options">W3C
-Markup Validation Service</a> is the defacto standard when it comes to
-validating HTML (it validates all HTML standards including HTML5).</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_glossary">Glossary</h2>
-<div class="sectionbody">
-<div class="dlist glossary"><dl>
-<dt>
-<a id="X8"></a> Block element
-</dt>
-<dd>
-<p>
- An AsciiDoc block element is a document entity composed of one or
- more whole lines of text.
-</p>
-</dd>
-<dt>
-<a id="X34"></a> Inline element
-</dt>
-<dd>
-<p>
- AsciiDoc inline elements occur within block element textual
- content, they perform formatting and substitution tasks.
-</p>
-</dd>
-<dt>
-Formal element
-</dt>
-<dd>
-<p>
- 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.
-</p>
-</dd>
-<dt>
-Verbatim element
-</dt>
-<dd>
-<p>
- The word verbatim indicates that white space and line breaks in
- the source document are to be preserved in the output document.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_migration_notes">Appendix A: Migration Notes</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="X53">Version 7 to version 8</h3>
-<div class="ulist"><ul>
-<li>
-<p>
-A new set of quotes has been introduced which may match inline text
- in existing documents — if they do you’ll need to escape the
- matched text with backslashes.
-</p>
-</li>
-<li>
-<p>
-The index entry inline macro syntax has changed — if your documents
- include indexes you may need to edit them.
-</p>
-</li>
-<li>
-<p>
-Replaced <code>a2x(1)</code> <code>--no-icons</code> and <code>--no-copy</code> options with their
- negated equivalents: <code>--icons</code> and <code>--copy</code> respectively. The
- default behavior has also changed — the use of icons and copying of
- icon and CSS files must be specified explicitly with the <code>--icons</code>
- and <code>--copy</code> options.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The rationale for the changes can be found in the AsciiDoc
-<code>CHANGELOG</code>.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">If you want to disable unconstrained quotes, the new alternative
-constrained quotes syntax and the new index entry syntax then you can
-define the attribute <code>asciidoc7compatible</code> (for example by using the
-<code>-a asciidoc7compatible</code> command-line option).</td>
-</tr></table>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X38">Appendix B: Packager Notes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Read the <code>README</code> and <code>INSTALL</code> files (in the distribution root
-directory) for install prerequisites and procedures. The distribution
-<code>Makefile.in</code> (used by <code>configure</code> to generate the <code>Makefile</code>) is the
-canonical installation procedure.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X39">Appendix C: AsciiDoc Safe Mode</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>AsciiDoc <em>safe mode</em> skips potentially dangerous scripted sections in
-AsciiDoc source files by inhibiting the execution of arbitrary code or
-the inclusion of arbitrary files.</p></div>
-<div class="paragraph"><p>The safe mode is disabled by default, it can be enabled with the
-<code>asciidoc(1)</code> <code>--safe</code> command-line option.</p></div>
-<div class="ulist"><div class="title">Safe mode constraints</div><ul>
-<li>
-<p>
-<code>eval</code>, <code>sys</code> and <code>sys2</code> executable attributes and block macros are
- not executed.
-</p>
-</li>
-<li>
-<p>
-<code>include::<filename>[]</code> and <code>include1::<filename>[]</code> block macro
- files must reside inside the parent file’s directory.
-</p>
-</li>
-<li>
-<p>
-<code>{include:<filename>}</code> executable attribute files must reside
- inside the source document directory.
-</p>
-</li>
-<li>
-<p>
-Passthrough Blocks are dropped.
-</p>
-</li>
-</ul></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/warning.png" alt="Warning" />
-</td>
-<td class="content">
-<div class="paragraph"><p>The safe mode is not designed to protect against unsafe AsciiDoc
-configuration files. Be especially careful when:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Implementing filters.
-</p>
-</li>
-<li>
-<p>
-Implementing elements that don’t escape special characters.
-</p>
-</li>
-<li>
-<p>
-Accepting configuration files from untrusted sources.
-</p>
-</li>
-</ol></div>
-</td>
-</tr></table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_asciidoc_with_non_english_languages">Appendix D: Using AsciiDoc with non-English Languages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>AsciiDoc can process UTF-8 character sets but there are some things
-you need to be aware of:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-If you are generating output documents using a DocBook toolchain
- then you should set the AsciiDoc <code>lang</code> attribute to the appropriate
- language (it defaults to <code>en</code> (English)). This will ensure things
- like table of contents, figure and table captions and admonition
- captions are output in the specified language. For example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ a2x -a lang=es doc/article.txt</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-If you are outputting HTML directly from <code>asciidoc(1)</code> you’ll
- need to set the various <code>*_caption</code> attributes to match your target
- language (see the list of captions and titles in the <code>[attributes]</code>
- section of the distribution <code>lang-*.conf</code> files). The easiest way is
- to create a language <code>.conf</code> file (see the AsciiDoc’s <code>lang-en.conf</code>
- file).
-</p>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">You still use the <em>NOTE</em>, <em>CAUTION</em>, <em>TIP</em>, <em>WARNING</em>,
-<em>IMPORTANT</em> captions in the AsciiDoc source, they get translated in
-the HTML output file.</td>
-</tr></table>
-</div>
-</li>
-<li>
-<p>
-<code>asciidoc(1)</code> automatically loads configuration files named like
- <code>lang-<lang>.conf</code> where <code><lang></code> is a two letter language code that
- matches the current AsciiDoc <code>lang</code> attribute. See also
- <a href="#X27">Configuration File Names and Locations</a>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_vim_syntax_highlighter">Appendix E: Vim Syntax Highlighter</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Syntax highlighting is incredibly useful, in addition to making
-reading AsciiDoc documents much easier syntax highlighting also helps
-you catch AsciiDoc syntax errors as you write your documents.</p></div>
-<div class="paragraph"><p>If you use the Vim editor, it comes with an
-<a href="https://github.com/vim/vim/blob/master/runtime/syntax/asciidoc.vim">AsciiDoc
-syntax highlighter pre-included</a>. By default, it will activate for
-files that use the .asciidoc or .adoc file extensions.</p></div>
-<div class="paragraph"><p>Alternatively, to enable syntax highlighting for the current document or
-other extensions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Put a Vim <em>autocmd</em> in your Vim configuration file (see the
- <a href="#X61">example vimrc file</a>).
-</p>
-</li>
-<li>
-<p>
-or execute the Vim command <code>:set syntax=asciidoc</code>.
-</p>
-</li>
-<li>
-<p>
-or add the following line to the end of you AsciiDoc source files:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>// vim: set syntax=asciidoc:</code></pre>
-</div></div>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X74">Appendix F: Attribute Options</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Here is the list of predefined <a href="#X75">attribute list options</a>:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="hsides"
-cellspacing="0" cellpadding="4">
-<col width="18%" />
-<col width="18%" />
-<col width="18%" />
-<col width="45%" />
-<thead>
-<tr>
-<th align="left" valign="top">Option</th>
-<th align="left" valign="top">Backends</th>
-<th align="left" valign="top">AsciiDoc Elements</th>
-<th align="left" valign="top">Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table"><em>autowidth</em></p></td>
-<td align="left" valign="top"><p class="table">xhtml11, html5, html4</p></td>
-<td align="left" valign="top"><p class="table">table</p></td>
-<td align="left" valign="top"><p class="table">The column widths are determined by the browser, not the AsciiDoc
-<em>cols</em> attribute. If there is no <em>width</em> attribute the table width is
-also left up to the browser.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>unbreakable</em></p></td>
-<td align="left" valign="top"><p class="table">xhtml11, html5</p></td>
-<td align="left" valign="top"><p class="table">block elements</p></td>
-<td align="left" valign="top"><p class="table"><em>unbreakable</em> attempts to keep the block element together on a single
-printed page c.f. the <em>breakable</em> and <em>unbreakable</em> docbook (XSL/FO)
-options below.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>breakable, unbreakable</em></p></td>
-<td align="left" valign="top"><p class="table">docbook (XSL/FO)</p></td>
-<td align="left" valign="top"><p class="table">table, example, block image</p></td>
-<td align="left" valign="top"><p class="table">The <em>breakable</em> options allows block elements to break across page
-boundaries; <em>unbreakable</em> attempts to keep the block element together
-on a single page. If neither option is specified the default XSL
-stylesheet behavior prevails.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>compact</em></p></td>
-<td align="left" valign="top"><p class="table">docbook, xhtml11, html5</p></td>
-<td align="left" valign="top"><p class="table">bulleted list, numbered list</p></td>
-<td align="left" valign="top"><p class="table">Minimizes vertical space in the list</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>footer</em></p></td>
-<td align="left" valign="top"><p class="table">docbook, xhtml11, html5, html4</p></td>
-<td align="left" valign="top"><p class="table">table</p></td>
-<td align="left" valign="top"><p class="table">The last row of the table is rendered as a footer.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>header</em></p></td>
-<td align="left" valign="top"><p class="table">docbook, xhtml11, html5, html4</p></td>
-<td align="left" valign="top"><p class="table">table</p></td>
-<td align="left" valign="top"><p class="table">The first row of the table is rendered as a header.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>pgwide</em></p></td>
-<td align="left" valign="top"><p class="table">docbook (XSL/FO)</p></td>
-<td align="left" valign="top"><p class="table">table, block image, horizontal labeled list</p></td>
-<td align="left" valign="top"><p class="table">Specifies that the element should be rendered across the full text
-width of the page irrespective of the current indentation.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>strong</em></p></td>
-<td align="left" valign="top"><p class="table">xhtml11, html5, html4</p></td>
-<td align="left" valign="top"><p class="table">labeled lists</p></td>
-<td align="left" valign="top"><p class="table">Emboldens label text.</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X82">Appendix G: Diagnostics</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>asciidoc(1)</code> <code>--verbose</code> command-line option prints additional
-information to stderr: files processed, filters processed, warnings,
-system attribute evaluation.</p></div>
-<div class="paragraph"><p>A special attribute named <em>trace</em> enables the output of
-element-by-element diagnostic messages detailing output markup
-generation to stderr. The <em>trace</em> attribute can be set on the
-command-line or from within the document using <a href="#X18">Attribute Entries</a> (the latter allows tracing to be confined to specific
-portions of the document).</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Trace messages print the source file name and line number and the
- trace name followed by related markup.
-</p>
-</li>
-<li>
-<p>
-<em>trace names</em> are normally the names of AsciiDoc elements (see the
- list below).
-</p>
-</li>
-<li>
-<p>
-The trace message is only printed if the <em>trace</em> attribute value
- matches the start of a <em>trace name</em>. The <em>trace</em> attribute value can
- be any Python regular expression. If a trace value is not specified
- all trace messages will be printed (this can result in large amounts
- of output if applied to the whole document).
-</p>
-</li>
-<li>
-<p>
-In the case of inline substitutions:
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-The text before and after the substitution is printed; the before
- text is preceded by a line containing <code><<<</code> and the after text by
- a line containing <code>>>></code>.
-</p>
-</li>
-<li>
-<p>
-The <em>subs</em> trace value is an alias for all inline substitutions.
-</p>
-</li>
-</ul></div>
-</li>
-</ul></div>
-<div class="literalblock">
-<div class="title">Trace names</div>
-<div class="content">
-<pre><code><blockname> block close
-<blockname> block open
-<subs>
-dropped line (a line containing an undefined attribute reference).
-floating title
-footer
-header
-list close
-list entry close
-list entry open
-list item close
-list item open
-list label close
-list label open
-list open
-macro block (a block macro)
-name (man page NAME section)
-paragraph
-preamble close
-preamble open
-push blockname
-pop blockname
-section close
-section open: level <level>
-subs (all inline substitutions)
-table</code></pre>
-</div></div>
-<div class="paragraph"><p>Where:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code><level></code> is section level number <em>0…4</em>.
-</p>
-</li>
-<li>
-<p>
-<code><blockname></code> is a delimited block name: <em>comment</em>, <em>sidebar</em>,
- <em>open</em>, <em>pass</em>, <em>listing</em>, <em>literal</em>, <em>quote</em>, <em>example</em>.
-</p>
-</li>
-<li>
-<p>
-<code><subs></code> is an inline substitution type:
- <em>specialcharacters</em>,<em>quotes</em>,<em>specialwords</em>, <em>replacements</em>,
- <em>attributes</em>,<em>macros</em>,<em>callouts</em>, <em>replacements2</em>, <em>replacements3</em>.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Command-line examples:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Trace the entire document.
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a trace mydoc.txt</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-Trace messages whose names start with <code>quotes</code> or <code>macros</code>:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a 'trace=quotes|macros' mydoc.txt</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-Print the first line of each trace message:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a trace mydoc.txt 2>&1 | grep ^TRACE:</code></pre>
-</div></div>
-</li>
-</ol></div>
-<div class="paragraph"><p>Attribute Entry examples:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Begin printing all trace messages:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>:trace:</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-Print only matched trace messages:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>:trace: quotes|macros</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-Turn trace messages off:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>:trace!:</code></pre>
-</div></div>
-</li>
-</ol></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="X88">Appendix H: Backend Attributes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This table contains a list of optional attributes that influence the
-generated outputs.</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="hsides"
-cellspacing="0" cellpadding="4">
-<col width="14%" />
-<col width="14%" />
-<col width="71%" />
-<thead>
-<tr>
-<th align="left" valign="top">Name </th>
-<th align="left" valign="top">Backends </th>
-<th align="left" valign="top">Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table"><em>badges</em></p></td>
-<td align="left" valign="top"><p class="table">xhtml11, html5</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Link badges (<em>XHTML 1.1</em> and <em>CSS</em>) in document footers. By default
-badges are omitted (<em>badges</em> is undefined).</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">The path names of images, icons and scripts are relative path
-names to the output document not the source document.</td>
-</tr></table>
-</div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>data-uri</em></p></td>
-<td align="left" valign="top"><p class="table">xhtml11, html5</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Embed images using the <a href="#X66">data: uri scheme</a>.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>css-signature</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Set a <em>CSS signature</em> for the document (sets the <em>id</em> attribute of the
-HTML <em>body</em> element). CSS signatures provide a mechanism that allows
-users to personalize the document appearance. The term <em>CSS signature</em>
-was <a href="https://juicystudio.com/article/css-selectors.php">coined by
-Eric Meyer</a>.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>disable-javascript</em></p></td>
-<td align="left" valign="top"><p class="table">xhtml11, html5</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>If the <code>disable-javascript</code> attribute is defined the <code>asciidoc.js</code>
-JavaScript is not embedded or linked to the output document. By
-default AsciiDoc automatically embeds or links the <code>asciidoc.js</code>
-JavaScript to the output document. The script dynamically generates
-<a href="#X91">table of contents</a> and <a href="#X92">footnotes</a>.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em><a id="X97"></a> docinfo, docinfo1, docinfo2</em></p></td>
-<td align="left" valign="top"><p class="table">All backends</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>These three attributes control which <a href="#X87">document information files</a> will be included in the the header of the output file:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-docinfo
-</dt>
-<dd>
-<p>
-Include <code><filename>-docinfo.<ext></code>
-</p>
-</dd>
-<dt class="hdlist1">
-docinfo1
-</dt>
-<dd>
-<p>
-Include <code>docinfo.<ext></code>
-</p>
-</dd>
-<dt class="hdlist1">
-docinfo2
-</dt>
-<dd>
-<p>
-Include <code>docinfo.<ext></code> and <code><filename>-docinfo.<ext></code>
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Where <code><filename></code> is the file name (sans extension) of the AsciiDoc
-input file and <code><ext></code> is <code>.html</code> for HTML outputs or <code>.xml</code> for
-DocBook outputs. If the input file is the standard input then the
-output file name is used. The following example will include the
-<code>mydoc-docinfo.xml</code> docinfo file in the DocBook <code>mydoc.xml</code> output
-file:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a docinfo -b docbook mydoc.txt</code></pre>
-</div></div>
-<div class="paragraph"><p>This next example will include <code>docinfo.html</code> and <code>mydoc-docinfo.html</code>
-docinfo files in the HTML output file:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a docinfo2 -b html4 mydoc.txt</code></pre>
-</div></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em><a id="X54"></a>encoding</em></p></td>
-<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Set the input and output document character set encoding. For example
-the <code>--attribute encoding=ISO-8859-1</code> command-line option will set the
-character set encoding to <code>ISO-8859-1</code>.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The default encoding is UTF-8.
-</p>
-</li>
-<li>
-<p>
-This attribute specifies the character set in the output document.
-</p>
-</li>
-<li>
-<p>
-The encoding name must correspond to a Python codec name or alias.
-</p>
-</li>
-<li>
-<p>
-The <em>encoding</em> attribute can be set using an AttributeEntry inside
- the document header. For example:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>:encoding: ISO-8859-1</code></pre>
-</div></div>
-</li>
-</ul></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>hr</em></p></td>
-<td align="left" valign="top"><p class="table">html4</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Defines the <em>html4</em> inter-section horizontal ruler element. By default
-<em>html4</em> top level sections are separated by a horizontal ruler
-element, undefine this attribute or set it to an empty string if you
-do not want them. The default <em>html4</em> backend value for the <em>hr</em>
-attribute is <code><hr></code>.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em><a id="X45"></a>icons</em></p></td>
-<td align="left" valign="top"><p class="table">xhtml11, html5</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Link admonition paragraph and admonition block icon images and badge
-images. By default <em>icons</em> is undefined and text is used in place of
-icon images.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em><a id="X44"></a>iconsdir</em></p></td>
-<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>The name of the directory containing linked admonition icons,
-navigation icons and the <code>callouts</code> sub-directory (the <code>callouts</code>
-sub-directory contains <a href="#X105">callout</a> number images). <em>iconsdir</em>
-defaults to <code>./images/icons</code>. If admonition icons are embedded using
-the <a href="#X66">data-uri</a> scheme then the <em>iconsdir</em> attribute defaults to
-the location of the icons installed in the AsciiDoc configuration
-directory.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>imagesdir</em></p></td>
-<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>If this attribute is defined it is prepended to the target image file
-name paths in inline and block image macros.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>keywords, description, title</em></p></td>
-<td align="left" valign="top"><p class="table">html4, html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>The <em>keywords</em> and <em>description</em> attributes set the correspondingly
-named HTML meta tag contents; the <em>title</em> attribute sets the HTML
-title tag contents. Their principle use is for SEO (Search Engine
-Optimisation). All three are optional, but if they are used they must
-appear in the document header (or on the command-line). If <em>title</em> is
-not specified the AsciiDoc document title is used.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>linkcss</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Link CSS stylesheets and JavaScripts. By default <em>linkcss</em> is
-undefined in which case stylesheets and scripts are automatically
-embedded in the output document.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em><a id="X103"></a>max-width</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Set the document maximum display width (sets the <em>body</em> element CSS
-<em>max-width</em> property).</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>numbered</em></p></td>
-<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook (XSL Stylesheets)</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Adds section numbers to section titles. The <em>docbook</em> backend ignores
-<em>numbered</em> attribute entries after the document header.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>plaintext</em></p></td>
-<td align="left" valign="top"><p class="table">All backends</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>If this global attribute is defined all inline substitutions are
-suppressed and block indents are retained. This option is useful when
-dealing with large amounts of imported plain text.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>quirks</em></p></td>
-<td align="left" valign="top"><p class="table">xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Include the <code>xhtml11-quirks.conf</code> configuration file and
-<code>xhtml11-quirks.css</code> <a href="#X35">stylesheet</a> to work around IE6 browser
-incompatibilities. This feature is deprecated and its use is
-discouraged — documents are still viewable in IE6 without it.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>revremark</em></p></td>
-<td align="left" valign="top"><p class="table">docbook</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>A short summary of changes in this document revision. Must be defined
-prior to the first document section. The document also needs to be
-dated to output this attribute.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>footer-style</em></p></td>
-<td align="left" valign="top"><p class="table">html4, html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Changes the "Last updated" field in the footer of the document or removes this
-field and the revision number (in the footer only).<br />
-Can take 3 values:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-none : Don’t display the "Last updated" and "Revision number" fields in the
- footer of the document
-</p>
-</li>
-<li>
-<p>
-revdate : The "Last updated" field’s date in the footer will be the revision
- date specified in the document (<code>revdate</code> attribute)
-</p>
-</li>
-<li>
-<p>
-default (or any other value) : The "Last updated" field’s date in the footer
- will be the date of the input file modification
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This attribute can be set, for example, using <code>:footer-style: revdate</code> in the
-header of the file or using the <code>--attribute footer-style=revdate</code> command-line
-option.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>scriptsdir</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>The name of the directory containing linked JavaScripts.
-See <a href="#X35">HTML stylesheets and JavaScript locations</a>.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>sgml</em></p></td>
-<td align="left" valign="top"><p class="table">docbook45</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>The <code>--backend=docbook45</code> command-line option produces DocBook 4.5
-XML. You can produce the older DocBook SGML format using the
-<code>--attribute sgml</code> command-line option.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>stylesdir</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>The name of the directory containing linked or embedded
-<a href="#X35">stylesheets</a>.
-See <a href="#X35">HTML stylesheets and JavaScript locations</a>.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>stylesheet</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>The file name of an optional additional CSS <a href="#X35">stylesheet</a>.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>theme</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Use alternative stylesheet (see <a href="#X35">Stylesheets</a>).</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em><a id="X91"></a>toc</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11, docbook (XSL Stylesheets)</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Adds a table of contents to the start of an article or book document.
-The <code>toc</code> attribute can be specified using the <code>--attribute toc</code>
-command-line option or a <code>:toc:</code> attribute entry in the document
-header. The <em>toc</em> attribute is defined by default when the <em>docbook</em>
-backend is used. To disable table of contents generation undefine the
-<em>toc</em> attribute by putting a <code>:toc!:</code> attribute entry in the document
-header or from the command-line with an <code>--attribute toc!</code> option.</p></div>
-<div class="paragraph"><p><strong>xhtml11 and html5 backends</strong></p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-JavaScript needs to be enabled in your browser.
-</p>
-</li>
-<li>
-<p>
-The following example generates a numbered table of contents using a
- JavaScript embedded in the <code>mydoc.html</code> output document:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a toc -a numbered mydoc.txt</code></pre>
-</div></div>
-</li>
-</ul></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>toc2</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Adds a scrollable table of contents in the left hand margin of an
-article or book document. Use the <em>max-width</em> attribute to change the
-content width. In all other respects behaves the same as the <em>toc</em>
-attribute.</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>toc-placement</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>When set to <em>auto</em> (the default value) <code>asciidoc(1)</code> will place the
-table of contents in the document header. When <em>toc-placement</em> is set
-to <em>manual</em> the TOC can be positioned anywhere in the document by
-placing the <code>toc::[]</code> block macro at the point you want the TOC to
-appear.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<img src="./images/icons/note.png" alt="Note" />
-</td>
-<td class="content">If you use <em>toc-placement</em> then you also have to define the
-<a href="#X91">toc</a> attribute.</td>
-</tr></table>
-</div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>toc-title</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Sets the table of contents title (defaults to <em>Table of Contents</em>).</p></div></div></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table"><em>toclevels</em></p></td>
-<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
-<td align="left" valign="top"><div><div class="paragraph"><p>Sets the number of title levels (1..4) reported in the table of
-contents (see the <em>toc</em> attribute above). Defaults to 2 and must be
-used with the <em>toc</em> attribute. Example usage:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>$ asciidoc -a toc -a toclevels=3 doc/asciidoc.txt</code></pre>
-</div></div></div></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_license">Appendix I: License</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>AsciiDoc is free software; you can redistribute it and/or modify it
-under the terms of the <em>GNU General Public License version 2</em> (GPLv2)
-as published by the Free Software Foundation.</p></div>
-<div class="paragraph"><p>AsciiDoc is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-General Public License version 2 for more details.</p></div>
-<div class="paragraph"><p>Copyright © 2002-2013 Stuart Rackham.</p></div>
-<div class="paragraph"><p>Copyright © 2013-2020 AsciiDoc Contributors.</p></div>
-</div>
-</div>
-</div>
-<div id="footnotes"><hr /></div>
-<div id="footer">
-<div id="footer-text">
-Version 9.1.0<br />
-Last updated 2021-09-19 06:36:59 UTC<br />
-AsciiDoc is a trademark of the Eclipse Foundation, Inc.
-</div>
-<div id="footer-badges">
-<a href="https://validator.w3.org/check?uri=referer">
- <img style="border:0;width:88px;height:31px"
- src="https://www.w3.org/Icons/valid-xhtml11-blue"
- alt="Valid XHTML 1.1" height="31" width="88" />
-</a>
-<a href="https://jigsaw.w3.org/css-validator/">
- <img style="border:0;width:88px;height:31px"
- src="https://jigsaw.w3.org/css-validator/images/vcss-blue"
- alt="Valid CSS!" />
-</a>
-</div>
-</div>
-</div>
-</div>
-</body>
-</html>
|