/usr/share/doc/asciidoc/userguide.html

<?xml version="1.0" encoding="UTF-8"?>
<!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="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.10" />
<title>AsciiDoc User Guide</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */

/* Default font. */
body {
  font-family: Georgia,serif;
}

/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
  font-family: Arial,Helvetica,sans-serif;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}
h5 {
  font-size: 1.0em;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

.monospaced, code, pre {
  font-family: "Courier New", Courier, monospace;
  font-size: inherit;
  color: navy;
  padding: 0;
  margin: 0;
}
pre {
  white-space: pre-wrap;
}

#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}

#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #888;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; vertical-align: text-bottom; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}

div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  #footer-badges { display: none; }
}

#toc {
  margin-bottom: 2.5em;
}

#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }

span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }

span.big { font-size: 2em; }
span.small { font-size: 0.6em; }

span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }

div.unbreakable { page-break-inside: avoid; }


/*
 * xhtml11 specific
 *
 * */

div.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


/*
 * html5 specific
 *
 * */

table.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
thead, p.tableblock.header {
  font-weight: bold;
  color: #527bbd;
}
p.tableblock {
  margin-top: 0;
}
table.tableblock {
  border-width: 3px;
  border-spacing: 0px;
  border-style: solid;
  border-color: #527bbd;
  border-collapse: collapse;
}
th.tableblock, td.tableblock {
  border-width: 1px;
  padding: 4px;
  border-style: solid;
  border-color: #527bbd;
}

table.tableblock.frame-topbot {
  border-left-style: hidden;
  border-right-style: hidden;
}
table.tableblock.frame-sides {
  border-top-style: hidden;
  border-bottom-style: hidden;
}
table.tableblock.frame-none {
  border-style: hidden;
}

th.tableblock.halign-left, td.tableblock.halign-left {
  text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
  text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
  text-align: right;
}

th.tableblock.valign-top, td.tableblock.valign-top {
  vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
  vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
  vertical-align: bottom;
}


/*
 * manpage specific
 *
 * */

body.manpage h1 {
  padding-top: 0.5em;
  padding-bottom: 0.5em;
  border-top: 2px solid silver;
  border-bottom: 2px solid silver;
}
body.manpage h2 {
  border-style: none;
}
body.manpage div.sectionbody {
  margin-left: 3em;
}

@media print {
  body.manpage div#toc { display: none; }
}


</style>
<script type="text/javascript">
/*<![CDATA[*/
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  if (!toc) {
    return;
  }

  // Delete existing TOC entries in case we're reloading the TOC.
  var tocEntriesToRemove = [];
  var i;
  for (i = 0; i < toc.childNodes.length; i++) {
    var entry = toc.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div'
     && entry.getAttribute("class")
     && entry.getAttribute("class").match(/^toclevel/))
      tocEntriesToRemove.push(entry);
  }
  for (i = 0; i < tocEntriesToRemove.length; i++) {
    toc.removeChild(tocEntriesToRemove[i]);
  }

  // Rebuild TOC entries.
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  // Delete existing footnote entries in case we're reloading the footnodes.
  var i;
  var noteholder = document.getElementById("footnotes");
  if (!noteholder) {
    return;
  }
  var entriesToRemove = [];
  for (i = 0; i < noteholder.childNodes.length; i++) {
    var entry = noteholder.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
      entriesToRemove.push(entry);
  }
  for (i = 0; i < entriesToRemove.length; i++) {
    noteholder.removeChild(entriesToRemove[i]);
  }

  // Rebuild footnote entries.
  var cont = document.getElementById("content");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      var note = spans[i].getAttribute("data-note");
      if (!note) {
        // Use [\s\S] in place of . so multi-line matches work.
        // Because JavaScript has no s (dotall) regex flag.
        note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
        spans[i].innerHTML =
          "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
        spans[i].setAttribute("data-note", note);
      }
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
},

install: function(toclevels) {
  var timerId;

  function reinstall() {
    asciidoc.footnotes();
    if (toclevels) {
      asciidoc.toc(toclevels);
    }
  }

  function reinstallAndRemoveTimer() {
    clearInterval(timerId);
    reinstall();
  }

  timerId = setInterval(reinstall, 500);
  if (document.addEventListener)
    document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
  else
    window.onload = reinstallAndRemoveTimer;
}

}
asciidoc.install(2);
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1>AsciiDoc User Guide</h1>
<span id="author">Stuart Rackham</span><br />
<span id="email"><code>&lt;<a href="mailto:srackham@gmail.com">srackham@gmail.com</a>&gt;</code></span><br />
<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="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&#8217;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&#8201;&#8212;&#8201;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="http://asciidoc.org/">http://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&#8201;&#8212;&#8201;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&#8201;&#8212;&#8201;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">
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="http://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="http://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="http://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-&lt;alias&gt;</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/&lt;backend&gt;</code> where <code>&lt;backend&gt;</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="http://www.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="http://live.gnome.org/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&#8201;&#8212;&#8201;it&#8217;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="/usr/share/asciidoc/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="http://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&#8217;s zero configuration
  required and no Java VM to install&#8201;&#8212;&#8201;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="http://docbook.sourceforge.net/projects/xsl/">DocBook XSL 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&#8201;&#8212;&#8201;  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="http://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="http://www.microsoft.com">http://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&#8217;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 &gt; 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 &gt; 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&#8201;&#8212;&#8201;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/&lt;theme&gt;/</code> (where <code>&lt;theme&gt;</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>&lt;theme&gt;.css</code> file replaces the default <code>asciidoc.css</code> CSS file.
</p>
</li>
<li>
<p>
The <code>&lt;theme&gt;.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&#8217;s an example AsciiDoc document header:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>Writing Documentation using AsciiDoc
====================================
Joe Bloggs &lt;jbloggs@mymail.com&gt;
v2.0, February 2003:
Rewritten for version 2 release.</code></pre>
</div></div>
<div class="paragraph"><p>The author information line contains the author&#8217;s name optionally
followed by the author&#8217;s email address. The author&#8217;s name is formatted
like:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>firstname[ [middlename ]lastname][ &lt;email&gt;]]</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 &lt;&gt; brackets.
Here a some examples of author information lines:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>Joe Bloggs &lt;jbloggs@mymail.com&gt;
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&#8217;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&lt;level&gt;</code> template is used
   (where <code>&lt;level&gt;</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&#8217;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> &#8230;) 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 may be
  deprecated in future releases and <strong>should be avoided</strong>, it&#8217;s sole
  purpose is to accommodate deficient downstream applications that
  cannot process non-ASCII ID attributes.
</p>
</li>
</ul></div>
<div class="paragraph"><p>Example: the title <em>Jim&#8217;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>&lt;title&gt;=&lt;template&gt;</code></pre>
</div></div>
<div class="paragraph"><p><code>&lt;title&gt;</code> is a Python regular expression and <code>&lt;template&gt;</code> is the name
of a configuration file markup template section. If the <code>&lt;title&gt;</code>
matches an AsciiDoc document section title then the backend output is
marked up using the <code>&lt;template&gt;</code> markup template (instead of the
default <code>sect&lt;level&gt;</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>&lt;template&gt;</code> is blank then any
existing entry with the same <code>&lt;title&gt;</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&amp;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>&lt;</code>, <code>&gt;</code>, and <code>&amp;</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">
&#8216;Single quoted text&#8217;
</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">
&#8220;Double quoted text&#8221;
</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>&lt;color&gt;</em> (text foreground color).
</p>
</li>
<li>
<p>
<em>&lt;color&gt;-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>&lt;color&gt;</em> can be any of the
<a href="http://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="/usr/share/asciidoc/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^&amp;#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>&#960;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>&lt;&lt;&lt;</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&#8217;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, -&gt; right arrow, &lt;- left arrow, =&gt; right
double arrow, &lt;= left double arrow.</code></pre>
</div></div>
<div class="paragraph"><p>Which are rendered as:</p></div>
<div class="paragraph"><p>&#169; copyright, &#8482; trademark, &#174; registered trademark,&#8201;&#8212;&#8201;em dash, &#8230; ellipsis, &#8594; right arrow, &#8592; left arrow, &#8658; right
double arrow, &#8656; 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>&amp;#x278a; &amp;#182;</code></pre>
</div></div>
<div class="paragraph"><p>renders:</p></div>
<div class="paragraph"><p>&#x278a; &#182;</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="/usr/share/asciidoc/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>&#8230;<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&#8217;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&#8217;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>&lt;&lt;chapter-titles,chapter titles&gt;&gt;</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&#8217;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&#8201;&#8212;&#8201;the attributes are made available to the
  block&#8217;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&#8217;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,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]']
_____________________________________________________________________
Sir, a woman's preaching is like a dog's walking on his hind legs. It
is not done well; but you are surprised to find it done at all.
_____________________________________________________________________</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>
</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="/usr/share/asciidoc/images/icons/note.png" alt="Note" />
</td>
<td class="content">Because <a href="#X64">lists</a> can be indented it&#8217;s possible for your
indented paragraph to be misinterpreted as a list&#8201;&#8212;&#8201;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 />
&#8212; 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 />
&#8212; 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="/usr/share/asciidoc/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="/usr/share/asciidoc/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="/usr/share/asciidoc/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&#8217;s an example:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>--------------------------------------
#include &lt;stdio.h&gt;

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 &lt;stdio.h&gt;

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&#8217;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&#8217;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="/usr/share/asciidoc/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&#8217;s an example:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>[subs="quotes"]
++++++++++++++++++++++++++++++++++++++
&lt;table border="1"&gt;&lt;tr&gt;
  &lt;td&gt;*Cell 1*&lt;/td&gt;
  &lt;td&gt;*Cell 2*&lt;/td&gt;
&lt;/tr&gt;&lt;/table&gt;
++++++++++++++++++++++++++++++++++++++</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&#8217;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&#8217;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 />
&#8212; 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="/usr/share/asciidoc/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&#8201;&#8212;&#8201;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&#8217;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&#8201;&#8212;&#8201;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="/usr/share/asciidoc/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="/usr/share/asciidoc/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&amp;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="/usr/share/asciidoc/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 &amp; Leonard Muellner.
  'DocBook - The Definitive Guide'. O'Reilly &amp; Associates. 1999.
  ISBN 1-56592-580-7.</code></pre>
</div></div>
<div class="paragraph"><p>The <code>[[[&lt;reference&gt;]]]</code> syntax is a bibliography entry anchor, it
generates an anchor named <code>&lt;reference&gt;</code> and additionally displays
<code>[&lt;reference&gt;]</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>&lt;&lt;taoup&gt;&gt;</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="/usr/share/asciidoc/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:[&lt;text&gt;]</code>
</dt>
<dd>
<p>
  Generates a footnote with text <code>&lt;text&gt;</code>.
</p>
</dd>
<dt class="hdlist1">
<code>footnoteref:[&lt;id&gt;,&lt;text&gt;]</code>
</dt>
<dd>
<p>
  Generates a footnote with a reference ID <code>&lt;id&gt;</code> and text <code>&lt;text&gt;</code>.
</p>
</dd>
<dt class="hdlist1">
<code>footnoteref:[&lt;id&gt;]</code>
</dt>
<dd>
<p>
  Generates a reference to the footnote with ID <code>&lt;id&gt;</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:[&lt;primary&gt;,&lt;secondary&gt;,&lt;tertiary&gt;]</code>
</dt>
<dt class="hdlist1">
<code>(((&lt;primary&gt;,&lt;secondary&gt;,&lt;tertiary&gt;)))</code>
</dt>
<dd>
<p>
    This inline macro generates an index term (the <code>&lt;secondary&gt;</code> and
    <code>&lt;tertiary&gt;</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:[&lt;primary&gt;]</code>
</dt>
<dt class="hdlist1">
<code>((&lt;primary&gt;))</code>
</dt>
<dd>
<p>
    This inline macro generates an index term that appears in both the
    index and the primary text flow.  The <code>&lt;primary&gt;</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="/usr/share/asciidoc/images/icons/note.png" alt="Note" />
</td>
<td class="content">Index entries only really make sense if you are generating
DocBook markup&#8201;&#8212;&#8201;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&#8217;s an
example:</p></div>
<div class="listingblock">
<div class="content">
<pre><code> .MS-DOS directory listing
 -----------------------------------------------------
 10/17/97   9:04         &lt;DIR&gt;    bin
 10/16/97  14:11         &lt;DIR&gt;    DOS            &lt;1&gt;
 10/16/97  14:40         &lt;DIR&gt;    Program Files
 10/16/97  14:46         &lt;DIR&gt;    TEMP
 10/17/97   9:04         &lt;DIR&gt;    tmp
 10/16/97  14:37         &lt;DIR&gt;    WINNT
 10/16/97  14:25             119  AUTOEXEC.BAT   &lt;2&gt;
  2/13/94   6:21          54,619  COMMAND.COM    &lt;2&gt;
 10/16/97  14:25             115  CONFIG.SYS     &lt;2&gt;
 11/16/97  17:17      61,865,984  pagefile.sys
  2/13/94   6:21           9,349  WINA20.386     &lt;3&gt;
 -----------------------------------------------------

 &lt;1&gt; This directory holds MS-DOS.
 &lt;2&gt; System startup code for DOS.
 &lt;3&gt; 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         &lt;DIR&gt;    bin
10/16/97  14:11         &lt;DIR&gt;    DOS            <img src="/usr/share/asciidoc/images/icons/callouts/1.png" alt="1" />
10/16/97  14:40         &lt;DIR&gt;    Program Files
10/16/97  14:46         &lt;DIR&gt;    TEMP
10/17/97   9:04         &lt;DIR&gt;    tmp
10/16/97  14:37         &lt;DIR&gt;    WINNT
10/16/97  14:25             119  AUTOEXEC.BAT   <img src="/usr/share/asciidoc/images/icons/callouts/2.png" alt="2" />
 2/13/94   6:21          54,619  COMMAND.COM    <img src="/usr/share/asciidoc/images/icons/callouts/2.png" alt="2" />
10/16/97  14:25             115  CONFIG.SYS     <img src="/usr/share/asciidoc/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="/usr/share/asciidoc/images/icons/callouts/3.png" alt="3" /></code></pre>
</div></div>
<div class="colist arabic"><table>
<tr><td><img src="/usr/share/asciidoc/images/icons/callouts/1.png" alt="1" /></td><td>
This directory holds MS-DOS.
</td></tr>
<tr><td><img src="/usr/share/asciidoc/images/icons/callouts/2.png" alt="2" /></td><td>
System startup code for DOS.
</td></tr>
<tr><td><img src="/usr/share/asciidoc/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&#8201;&#8212;&#8201;  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&#8201;&#8212;&#8201;list items can
  start with <code>&lt;n&gt;</code>, <code>n&gt;</code> or <code>&gt;</code> where <code>n</code> is the optional list item
  number (in the latter case list items starting with a single <code>&gt;</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&#8217;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="/usr/share/asciidoc/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&lt;listnumber&gt;-&lt;index&gt;</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&#8201;&#8212;&#8201;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&#8201;&#8212;&#8201;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[]
 -------------------------------------------

 &lt;1&gt; 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!'   # &lt;1&gt;</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>&lt;name&gt;:&lt;target&gt;[&lt;attrlist&gt;]</code> (for
inline macros) and <code>&lt;name&gt;::&lt;target&gt;[&lt;attrlist&gt;]</code> (for block
macros).  Here are some examples:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>http://www.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>&lt;name&gt;</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>&lt;target&gt;</code> cannot contain white space characters.
</p>
</li>
<li>
<p>
<code>&lt;attrlist&gt;</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>&lt;name&gt;</code>, <code>&lt;target&gt;</code> and <code>&lt;attrlist&gt;</code> the
  <code>&lt;passtext&gt;</code> and <code>&lt;subslist&gt;</code> named groups are available to
  <a href="#X77">passthrough macros</a>. A macro is a passthrough macro if the
  definition includes a <code>&lt;passtext&gt;</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&#8217;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>&lt;attrlist&gt;</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>http://www.docbook.org/[DocBook.org]
http://www.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="http://www.docbook.org/">DocBook.org</a></p></div>
<div class="paragraph"><p><a href="http://www.docbook.org/">http://www.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>&lt;target&gt;</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>[[&lt;id&gt;,&lt;xreflabel&gt;]]
anchor:&lt;id&gt;[&lt;xreflabel&gt;]</code></pre>
</div></div>
<div class="paragraph"><p>The <code>&lt;id&gt;</code> is a unique string that conforms to the output markup&#8217;s
anchor syntax. The optional <code>&lt;xreflabel&gt;</code> is the text to be displayed
by captionless <em>xref</em> macros that refer to this anchor. The optional
<code>&lt;xreflabel&gt;</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>&lt;&lt;&lt;id&gt;,&lt;caption&gt;&gt;&gt;
xref:&lt;id&gt;[&lt;caption&gt;]</code></pre>
</div></div>
<div class="paragraph"><p>The <code>&lt;id&gt;</code> refers to an anchor ID. The optional <code>&lt;caption&gt;</code> is the
link&#8217;s displayed text. Example:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>&lt;&lt;X21,attribute lists&gt;&gt;</code></pre>
</div></div>
<div class="paragraph"><p>If <code>&lt;caption&gt;</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>&lt;id&gt;</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&#8217;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 &lt;&lt;tiger_image&gt;&gt;.</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:&lt;target&gt;[&lt;caption&gt;]</code></pre>
</div></div>
<div class="paragraph"><p>The <em>link</em> macro generates relative URLs. The link macro <code>&lt;target&gt;</code> is
the target file name (relative to the file system location of the
referring document). The optional <code>&lt;caption&gt;</code> is the link&#8217;s displayed
text. If <code>&lt;caption&gt;</code> is not specified then <code>&lt;target&gt;</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>&lt;filename&gt;#&lt;id&gt;</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:&lt;target&gt;[&lt;attributes&gt;]</code></pre>
</div></div>
<div class="paragraph"><p>The contents of the image file <code>&lt;target&gt;</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>&lt;target&gt;</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="http://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 &#8220;tooltip&#8221; 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>&lt;name&gt;::&lt;target&gt;[&lt;attrlist&gt;]</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&#8201;&#8212;&#8201;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::&lt;target&gt;[&lt;attributes&gt;]</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&#8217;s
<a href="#X9">inline image macro</a> counterpart.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/usr/share/asciidoc/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="http://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="/usr/share/asciidoc/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&#8217;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&#8201;&#8212;&#8201;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&#8217;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>
If the he <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::&lt;attribute&gt;[]
:
endif::&lt;attribute&gt;[]</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::&lt;attribute&gt;[]
:
endif::&lt;attribute&gt;[]</code></pre>
</div></div>
<div class="paragraph"><p><code>&lt;attribute&gt;</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&#8217;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&#8217;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="/usr/share/asciidoc/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>&lt;subslist&gt;</code>.  The usual syntax is
<code>&lt;name&gt;:&lt;subslist&gt;[&lt;passtext&gt;]</code> (for inline macros) and
<code>&lt;name&gt;::&lt;subslist&gt;[&lt;passtext&gt;]</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:[&lt;q&gt;To be or not to be&lt;/q&gt;]
pass:attributes,quotes[&lt;u&gt;the '{author}'&lt;/u&gt;]</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&#8217;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`$+++ AsciiMathML 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>&lt;pattern&gt;=&lt;name&gt;[&lt;subslist]</code>
</dt>
<dd>
<p>
Inline macro definition.
</p>
</dd>
<dt class="hdlist1">
<code>&lt;pattern&gt;=#&lt;name&gt;[&lt;subslist]</code>
</dt>
<dd>
<p>
Block macro definition.
</p>
</dd>
<dt class="hdlist1">
<code>&lt;pattern&gt;=+&lt;name&gt;[&lt;subslist]</code>
</dt>
<dd>
<p>
System macro definition.
</p>
</dd>
<dt class="hdlist1">
<code>&lt;pattern&gt;</code>
</dt>
<dd>
<p>
Delete the existing macro with this <code>&lt;pattern&gt;</code>.
</p>
</dd>
</dl></div>
<div class="paragraph"><p><code>&lt;pattern&gt;</code> is a Python regular expression and <code>&lt;name&gt;</code> is the name of
a markup template. If <code>&lt;name&gt;</code> is omitted then it is the value of the
regular expression match group named <em>name</em>.  The optional
<code>[&lt;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>&lt;pattern&gt;</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&#8217;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>&lt;name&gt;-inlinemacro</code> or <code>&lt;name&gt;-blockmacro</code> (depending on the macro
  type).
</p>
</li>
<li>
<p>
Global and macro attribute list attributes are substituted in the
  macro&#8217;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>&lt;name&gt;::&lt;target&gt;[&lt;attrlist&gt;]</code> where:</p></div>
<div class="hdlist"><table>
<tr>
<td class="hdlist1">
<code>&lt;name&gt;</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>&lt;target&gt;</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>&lt;attrlist&gt;</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>++++
&lt;video poster="pics/video/gizmo.jpg" id="video" style="cursor: pointer;" &gt;
  &lt;source src="pics/video/gizmo.mp4" /&gt;
  &lt;source src="pics/video/gizmo.webm" type="video/webm" /&gt;
  &lt;source src="pics/video/gizmo.ogv" type="video/ogg" /&gt;
  Video not playing? &lt;a href="pics/video/gizmo.mp4"&gt;Download file&lt;/a&gt; instead.
&lt;/video&gt;

&lt;script type="text/javascript"&gt;
  var video = document.getElementById('video');
  video.addEventListener('click',function(){
    video.play();
  },false);
&lt;/script&gt;
++++</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&#8217;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&#8201;&#8212;&#8201;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="&gt;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&#8217;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,^,&gt;s",width="25%"]
|============================
|1 &gt;s|2 |3 |4
^|5 2.2+^.^|6 .3+&lt;.&gt;m|7
^|8
|9 2+&gt;|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&#8201;&#8212;&#8201;the table is treated
as a sequence of cells&#8201;&#8212;&#8201;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&lt;p,2*,4p,&gt;"</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>&#8230;<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&#8217;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&#8201;&#8212;&#8201;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>[&lt;multiplier&gt;*][&lt;align&gt;][&lt;width&gt;][&lt;style&gt;]</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>&lt;align&gt;</code> or <code>&lt;width&gt;</code> is not important.
</p>
</li>
<li>
<p>
Column <code>&lt;width&gt;</code> can be either an integer proportional value (1&#8230;)
  or a percentage (1%&#8230;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>&lt;align&gt;</em> column alignment specifier is formatted like:
</p>
<div class="literalblock">
<div class="content">
<pre><code>[&lt;horizontal&gt;][.&lt;vertical&gt;]</code></pre>
</div></div>
<div class="paragraph"><p>Where <code>&lt;horizontal&gt;</code> and <code>&lt;vertical&gt;</code> are one of the following
characters: <code>&lt;</code>, <code>^</code> or <code>&gt;</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>&lt;multiplier&gt;</code> can be used to specify repeated columns e.g.
  <code>cols="4*&lt;"</code> specifies four left-justified columns. The default
  multiplier value is 1.
</p>
</li>
<li>
<p>
The <code>&lt;style&gt;</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>[&lt;span&gt;*|+][&lt;align&gt;][&lt;style&gt;]</code></pre>
</div></div>
<div class="ulist"><ul>
<li>
<p>
<em>&lt;span&gt;</em> specifies horizontal and vertical cell spans (<em>+</em> operator) or
  the number of times the cell is replicated (<em>*</em> operator). <em>&lt;span&gt;</em>
  is formatted like:
</p>
<div class="literalblock">
<div class="content">
<pre><code>[&lt;colspan&gt;][.&lt;rowspan&gt;]</code></pre>
</div></div>
<div class="paragraph"><p>Where <code>&lt;colspan&gt;</code> and <code>&lt;rowspan&gt;</code> are integers specifying the number of
columns and rows to span.</p></div>
</li>
<li>
<p>
<code>&lt;align&gt;</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>&lt;style&gt;</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&#8217;s attribute list) or on a per column
basis (by specifying the style in the table&#8217;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&#8230;).
</p>
</dd>
<dt class="hdlist1">
colend
</dt>
<dd>
<p>
The number of the rightmost column occupied by the cell (1&#8230;).
</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&#8230;).
</p>
</dd>
<dt class="hdlist1">
morerows
</dt>
<dd>
<p>
Number of additional rows the cell should span (0&#8230;).
</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&#8201;&#8212;&#8201;if your DocBook generated
tables don&#8217;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="/usr/share/asciidoc/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&#8217;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="http://www.docbook.org/tdg5/en/html/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="http://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="http://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="http://www.maths.nottingham.ac.uk/personal/drw/lm.html">original
LaTeXMathML</a> by Douglas Woodall.  <em>LaTeXMathML</em> is derived from
ASCIIMathML and is for users who are more familiar with or prefer
using LaTeX math formulas (it recognizes a subset of LaTeX Math, the
differences are documented on the <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="http://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="/usr/share/asciidoc/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="_asciimathml">25.4. ASCIIMathML</h3>
<div class="paragraph"><p><a href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html">ASCIIMathML</a>
formulas can be included in XHTML documents generated using the
<em>xhtml11</em> and <em>html5</em> backends. To enable ASCIIMathML 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="http://asciidoc.org/">AsciiDoc website</a> or the
distributed <code>doc/asciimathml.txt</code> file.</p></div>
</div>
<div class="sect2">
<h3 id="_mathml">25.5. MathML</h3>
<div class="paragraph"><p><a href="http://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="/usr/share/asciidoc/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="/usr/share/asciidoc/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&#8217;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="/usr/share/asciidoc/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&#8230;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>&lt;tagname&gt;=&lt;starttag&gt;|&lt;endtag&gt;</code>. For example:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>emphasis=&lt;em&gt;|&lt;/em&gt;</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>&lt;special_character&gt;=&lt;translated_characters&gt;</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>&lt;</code> character to be replaced by <code>&amp;lt;</code>.</p></div>
<div class="literalblock">
<div class="content">
<pre><code>&lt;=&amp;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=&lt;em&gt;|&lt;/em&gt;</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&#8217;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]
&lt;strong&gt;{words}&lt;/strong&gt;</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&#160;[word2&#8230;]</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>&lt;find_pattern&gt;=&lt;replacement_text&gt;</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&#8217;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&#8217;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/&lt;backend&gt;</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/&lt;filter&gt;</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>&lt;backend&gt;.conf</code> and <code>&lt;backend&gt;-&lt;doctype&gt;.conf</code> files
  from locations 6.  If a backend plugin is not found then try
  locations 1, 2 and 3 for <code>&lt;backend&gt;.conf</code> and
  <code>&lt;backend&gt;-&lt;doctype&gt;.conf</code> backend configuration files.
</p>
</li>
<li>
<p>
Filter conf files from locations 7.
</p>
</li>
<li>
<p>
<code>lang-&lt;lang&gt;.conf</code> from locations 1, 2, 3.
</p>
</li>
<li>
<p>
<code>asciidoc.conf</code> from location 4.
</p>
</li>
<li>
<p>
<code>&lt;backend&gt;.conf</code> and <code>&lt;backend&gt;-&lt;doctype&gt;.conf</code> from location 4.
</p>
</li>
<li>
<p>
Filter conf files from location 4.
</p>
</li>
<li>
<p>
<code>&lt;docfile&gt;.conf</code> and <code>&lt;docfile&gt;-&lt;backend&gt;.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>&lt;backend&gt;</code> and <code>&lt;doctype&gt;</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>&lt;infile&gt;</code> is the path name of the AsciiDoc input file without the
  file name extension.
</p>
</li>
<li>
<p>
<code>&lt;lang&gt;</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="/usr/share/asciidoc/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&#8217;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="/usr/share/asciidoc/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="/usr/share/asciidoc/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>:&lt;name&gt;: &lt;value&gt;</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>:&lt;name&gt;!:</code></pre>
</div></div>
<div class="ulist"><div class="title">AttributeEntry behavior</div><ul>
<li>
<p>
The attribute entry line begins with colon&#8201;&#8212;&#8201;no white space allowed
  in left margin.
</p>
</li>
<li>
<p>
AsciiDoc converts the <code>&lt;name&gt;</code> to a legal attribute name (lower
  case, alphanumeric, dash and underscore characters only&#8201;&#8212;&#8201;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>&lt;value&gt;</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>&lt;value&gt;</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>&lt;value&gt;</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 &lt;srackham@gmail.com&gt;
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>:&lt;section_name&gt;.[&lt;entry_name&gt;]: &lt;entry_value&gt;</code></pre>
</div></div>
<div class="paragraph"><p>Where <code>&lt;section_name&gt;</code> is the configuration section name,
<code>&lt;entry_name&gt;</code> is the name of the entry and <code>&lt;entry_value&gt;</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>&lt;entry_name&gt;</code> is omitted then the entire section is
  substituted with the <code>&lt;entry_value&gt;</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.: &lt;a href="#{1}"&gt;{2?{2}}&lt;/a&gt;</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&#8201;&#8212;&#8201;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&#8201;&#8212;&#8201;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.net/projects/asciidoc/
:homepage:  http://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&#8217;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>&amp;#44;</code>) and double-quote (<code>&amp;#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&amp;#44; &amp;#34;with an image&amp;#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>,&#8230;
</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>&lt;option&gt;-option</code> (where
  <code>&lt;option&gt;</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>{&lt;name&gt;}</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>{&lt;names&gt;=&lt;value&gt;}</code>
</dt>
<dd>
<p>
        <code>&lt;value&gt;</code> is substituted if the attribute <code>&lt;names&gt;</code> is
        undefined otherwise its value is substituted. <code>&lt;value&gt;</code> can
        contain simple attribute references.
</p>
</dd>
<dt class="hdlist1">
<code>{&lt;names&gt;?&lt;value&gt;}</code>
</dt>
<dd>
<p>
        <code>&lt;value&gt;</code> is substituted if the attribute <code>&lt;names&gt;</code> is defined
        otherwise an empty string is substituted.  <code>&lt;value&gt;</code> can
        contain simple attribute references.
</p>
</dd>
<dt class="hdlist1">
<code>{&lt;names&gt;!&lt;value&gt;}</code>
</dt>
<dd>
<p>
        <code>&lt;value&gt;</code> is substituted if the attribute <code>&lt;names&gt;</code> is
        undefined otherwise an empty string is substituted.  <code>&lt;value&gt;</code>
        can contain simple attribute references.
</p>
</dd>
<dt class="hdlist1">
<code>{&lt;names&gt;#&lt;value&gt;}</code>
</dt>
<dd>
<p>
        <code>&lt;value&gt;</code> is substituted if the attribute <code>&lt;names&gt;</code> is defined
        otherwise the undefined attribute entry causes the containing
        line to be dropped.  <code>&lt;value&gt;</code> can contain simple attribute
        references.
</p>
</dd>
<dt class="hdlist1">
<code>{&lt;names&gt;%&lt;value&gt;}</code>
</dt>
<dd>
<p>
        <code>&lt;value&gt;</code> is substituted if the attribute <code>&lt;names&gt;</code> is not
        defined otherwise the containing line is dropped.  <code>&lt;value&gt;</code>
        can contain simple attribute references.
</p>
</dd>
<dt class="hdlist1">
<code>{&lt;names&gt;@&lt;regexp&gt;:&lt;value1&gt;[:&lt;value2&gt;]}</code>
</dt>
<dd>
<p>
        <code>&lt;value1&gt;</code> is substituted if the value of attribute <code>&lt;names&gt;</code>
        matches the regular expression <code>&lt;regexp&gt;</code> otherwise <code>&lt;value2&gt;</code>
        is substituted. If attribute <code>&lt;names&gt;</code> is not defined the
        containing line is dropped. If <code>&lt;value2&gt;</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>{&lt;names&gt;$&lt;regexp&gt;:&lt;value1&gt;[:&lt;value2&gt;]}</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>{&lt;names&gt;$&lt;regexp&gt;:&lt;value&gt;}</code>
</dt>
<dd>
<p>
                Substitutes <code>&lt;value&gt;</code> if <code>&lt;names&gt;</code> matches <code>&lt;regexp&gt;</code>
                otherwise the result is undefined and the containing
                line is dropped.
</p>
</dd>
<dt class="hdlist1">
<code>{&lt;names&gt;$&lt;regexp&gt;::&lt;value&gt;}</code>
</dt>
<dd>
<p>
                Substitutes <code>&lt;value&gt;</code> if <code>&lt;names&gt;</code> does not match
                <code>&lt;regexp&gt;</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>&lt;names&gt;</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&#8217;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&#8217;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>&lt;value&gt;</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&#8201;&#8212;&#8201;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
  &#8220;DocBook 4.5 or XHTML 1.1 backend&#8221; otherwise it evaluates to
  &#8220;some other backend&#8221;:
</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>{&lt;action&gt;:&lt;arguments&gt;}</code>.</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
<code>{counter:&lt;attrname&gt;[:&lt;seed&gt;]}</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>&lt;seed&gt;</code> specifies the counter&#8217;s initial value;
          it can be a number or a single letter; defaults to <em>1</em>.
</p>
</li>
<li>
<p>
<code>&lt;seed&gt;</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:&lt;attrname&gt;[:&lt;seed&gt;]}</code>
</dt>
<dd>
<p>
        Same as <code>counter</code> except the it always returns a blank string.
</p>
</dd>
<dt class="hdlist1">
<code>{eval:&lt;expression&gt;}</code>
</dt>
<dd>
<p>
        Substitutes the result of the Python <code>&lt;expression&gt;</code>.
</p>
<div class="ulist"><ul>
<li>
<p>
If <code>&lt;expression&gt;</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>&lt;expression&gt;</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:&lt;command&gt;}</code>
</dt>
<dd>
<p>
        Passthrough version of <code>{eval:&lt;expression&gt;}</code>&#8201;&#8212;&#8201;the generated
        output is written directly to the output without any further
        substitutions.
</p>
</dd>
<dt class="hdlist1">
<code>{include:&lt;filename&gt;}</code>
</dt>
<dd>
<p>
        Substitutes contents of the file named <code>&lt;filename&gt;</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:&lt;attrname&gt;[!][:&lt;value&gt;]}</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>&lt;value&gt;</code> is omitted the attribute is set to a blank
          string.
</p>
</li>
<li>
<p>
<code>&lt;value&gt;</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:&lt;attrname&gt;[!][:&lt;value&gt;]}</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:&lt;command&gt;}</code>
</dt>
<dd>
<p>
        Substitutes the stdout generated by the execution of the shell
        <code>&lt;command&gt;</code>.
</p>
</dd>
<dt class="hdlist1">
<code>{sys2:&lt;command&gt;}</code>
</dt>
<dd>
<p>
        Substitutes the stdout and stderr generated by the execution
        of the shell <code>&lt;command&gt;</code>.
</p>
</dd>
<dt class="hdlist1">
<code>{sys3:&lt;command&gt;}</code>
</dt>
<dd>
<p>
        Passthrough version of <code>{sys:&lt;command&gt;}</code>&#8201;&#8212;&#8201;the generated
        output is written directly to the output without any further
        substitutions.
</p>
</dd>
<dt class="hdlist1">
<code>{template:&lt;template&gt;}</code>
</dt>
<dd>
<p>
        Substitutes the contents of the configuration file section
        named <code>&lt;template&gt;</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&#8217;s the list of
predefined intrinsic attributes:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>{amp}                 ampersand (&amp;) 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-&lt;backend&gt;}   empty string ''
{&lt;backend&gt;-&lt;doctype&gt;} empty string ''
{backend}             document backend specified by `-b` option
{backend-confdir}     the directory containing the &lt;backend&gt;.conf file
{backslash}           backslash character
{basebackend-&lt;base&gt;}  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-&lt;doctype&gt;}   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-&lt;fileext&gt;}  empty string ''
{filetype}            output file name file extension
{firstname}           author first name (from document header)
{gt}                  greater than (&gt;) 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 (&lt;) 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="/usr/share/asciidoc/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&#8217;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="http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks">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&#8217;s behavior. Here&#8217;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&#8201;&#8212;&#8201;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>&lt;option&gt;-option</code> (where <code>&lt;option&gt;</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&#8217;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">
&lt;stylename&gt;-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&#8217;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&lt;text&gt;\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&#8217;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&#8217;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&#8217;s markup template and
   written to the output file.
</p>
</li>
</ol></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/usr/share/asciidoc/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>&lt;name&gt;</code> of the <code>[listtags-&lt;name&gt;]</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 &#8220;mixed in&#8221; 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&#8217;s nothing special about the filters, they&#8217;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&#8201;&#8212;&#8201;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="/usr/share/asciidoc/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&#8217;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&#8217;s own sub-directory
with the same name as the filter&#8217;s style definition. For example the
music filter&#8217;s style name is <em>music</em> so it&#8217;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="/usr/share/asciidoc/images/icons/note.png" alt="Note" />
</td>
<td class="content">The purpose of this toy filter is to demonstrate how to write a
filter&#8201;&#8212;&#8201;it&#8217;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="http://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="http://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="http://asciidoc.org/music-filter.html">music filter</a> is included in the
distribution <code>./filters/</code> directory. It translates music in
<a href="http://lilypond.org/">LilyPond</a> or <a href="http://abcnotation.org.uk/">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="http://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="http://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="http://www.graphviz.org/">Graphviz</a>
filter for AsciiDoc.  Graphviz generates diagrams from a textual
specification. Gouichi Iisaka&#8217;s Graphviz filter is included in the
AsciiDoc distribution. Here are some
<a href="http://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/&lt;filter&gt;</code> where <code>&lt;filter&gt;</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="http://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-&lt;lang&gt;.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&#8217;t need to specify the whole help
topic name on the command-line, just enough letters to ensure it&#8217;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="/usr/share/asciidoc/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&#8217;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&#8217;t have to
  enter them manually.
</p>
</li>
<li>
<p>
The Vim website (<a href="http://www.vim.org">http://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 &lt;Leader&gt;r gq}

" Delete trailing white space and Dos-returns and to expand tabs to spaces.
nnoremap &lt;Leader&gt;t :set et&lt;CR&gt;:retab!&lt;CR&gt;:%s/[\r \t]\+$//&lt;CR&gt;

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*&lt;\\d\\+&gt;\\s\\+\\\\|^\\s*[a-zA-Z.]\\.\\s\\+\\\\|^\\s*[ivxIVX]\\+\\.\\s\\+
        \ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:&gt;</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&#8201;&#8212;&#8201;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&#8217;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 &#8220;closing block delimiter expected&#8221; 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;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&#8217;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&#8217;t want non-title document header lines (for example, Author
  and Revision lines) in the included files&#8201;&#8212;&#8201;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&#8201;&#8212;&#8201;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 -
&lt;div class="paragraph"&gt;&lt;p&gt;Hello &lt;strong&gt;World!&lt;/strong&gt;&lt;/p&gt;&lt;/div&gt;</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 Dave Raggett&#8217;s <a href="http://tidy.sourceforge.net/">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 &gt;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&#8217;ve ever tried to send someone an HTML document that includes
stylesheets and images you&#8217;ll know that it&#8217;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="http://asciidoc.org/article-standalone.html">http://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&#8217;s source has one
major problem: unless your configuration files are the same as the
creator&#8217;s you won&#8217;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 &gt; 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)]

+++++++++++++++++++++++++++++++
&lt;glossary&gt;
  &lt;title&gt;Glossary&lt;/title&gt;
  &lt;glossdiv&gt;
  ...
  &lt;/glossdiv&gt;
&lt;/glossary&gt;
+++++++++++++++++++++++++++++++
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&#8217;s DTD, if the DTD is not installed in your system&#8217;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="http://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&#8201;&#8212;&#8201;if they do you&#8217;ll need to escape the
  matched text with backslashes.
</p>
</li>
<li>
<p>
The index entry inline macro syntax has changed&#8201;&#8212;&#8201;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&#8201;&#8212;&#8201;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="/usr/share/asciidoc/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::&lt;filename&gt;[]</code> and <code>include1::&lt;filename&gt;[]</code> block macro
  files must reside inside the parent file&#8217;s directory.
</p>
</li>
<li>
<p>
<code>{include:&lt;filename&gt;}</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="/usr/share/asciidoc/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&#8217;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&#8217;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&#8217;s <code>lang-en.conf</code>
  file).
</p>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/usr/share/asciidoc/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-&lt;lang&gt;.conf</code> where <code>&lt;lang&gt;</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>The AsciiDoc distribution directory contains a Vim syntax highlighter
for AsciiDoc (<code>./vim/syntax/asciidoc.vim</code>), you can find the latest
version in the online
<a href="https://code.google.com/p/asciidoc/source/browse/">AsciiDoc
repository</a>.</p></div>
<div class="paragraph"><p>Install the highlighter by copying <code>asciidoc.vim</code> to your
<code>$HOME/.vim/syntax</code> directory (create it if it doesn&#8217;t already exist).</p></div>
<div class="paragraph"><p>To enable syntax highlighing:</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>&lt;&lt;&lt;</code> and the after text by
    a line containing <code>&gt;&gt;&gt;</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>&lt;blockname&gt; block close
&lt;blockname&gt; block open
&lt;subs&gt;
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 &lt;level&gt;
subs (all inline substitutions)
table</code></pre>
</div></div>
<div class="paragraph"><p>Where:</p></div>
<div class="ulist"><ul>
<li>
<p>
<code>&lt;level&gt;</code> is section level number <em>0&#8230;4</em>.
</p>
</li>
<li>
<p>
<code>&lt;blockname&gt;</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>&lt;subs&gt;</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&gt;&amp;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="/usr/share/asciidoc/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="http://archivist.incutio.com/viewlist/css-discuss/13291">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>&lt;filename&gt;-docinfo.&lt;ext&gt;</code>
</p>
</dd>
<dt class="hdlist1">
docinfo1
</dt>
<dd>
<p>
Include <code>docinfo.&lt;ext&gt;</code>
</p>
</dd>
<dt class="hdlist1">
docinfo2
</dt>
<dd>
<p>
Include <code>docinfo.&lt;ext&gt;</code> and <code>&lt;filename&gt;-docinfo.&lt;ext&gt;</code>
</p>
</dd>
</dl></div>
<div class="paragraph"><p>Where <code>&lt;filename&gt;</code> is the file name (sans extension) of the AsciiDoc
input file and <code>&lt;ext&gt;</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>&lt;hr&gt;</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&#8201;&#8212;&#8201;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&#8217;t display the "Last updated" and "Revision number" fields in the
  footer of the document
</p>
</li>
<li>
<p>
revdate : The "Last updated" field&#8217;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&#8217;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="/usr/share/asciidoc/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 &#169; 2002-2011 Stuart Rackham.</p></div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
</div>
</body>
</html>
asciidoc-doc 8.6.10-2 / usr / share / doc / asciidoc / userguide.html
