For consistency converted all DOS formatted configuration and text files (an

anachronism) to UNIX format.

1 files changed, 1133 insertions, 1133 deletions

diff --git a/doc/faq.txt b/doc/faq.txt
index 0ef38b6..4f7595b 100644
--- a/doc/faq.txt
+++ b/doc/faq.txt
@@ -1,1133 +1,1133 @@
-AsciiDoc Frequently Asked Questions

-===================================

-

-

-[NOTE]

-======

-- New FAQs are normally added at the top of this document.

-- The FAQ may be updated between AsciiDoc releases so some of the

-  newer FAQs may apply to the trunk and not the current release.

-======

-

-[[X5]]

-== How can I include embedded fonts in an EPUB document

-This is a two step process:

-

-1. Declare the font files and their use in your document's CSS

-   stylesheet. For example:

-+

-[listing]

-.........................................

-@font-face {

-  font-family : LiberationSerif-Regular;

-  font-weight : normal;

-  font-style: normal;

-  src : url(LiberationSerif-Regular.ttf);

-}

-

-body {

-  font-family: LiberationSerif-Regular, serif;

-}

-.........................................

-

-2. Declare the the font file as resource when you use `a2x(1)` to

-   compile the EPUB. For example:

-

-  a2x -f epub -d book --epubcheck --stylesheet epubtest.css --resource .ttf=application/x-font-ttf --resource LiberationSerif-Regular.ttf epubtest.txt

-

-[NOTE]

-======

-- Requires AsciiDoc 8.6.5 or better.

-- The True Type Font mimetype had to be declared explicitly with the

-  `--resource .ttf=application/x-font-ttf` option because it wasn't

-  registered on my Linux system.

-- In the above example the font file is in the same directory as the

-  AsciiDoc source file and is installed to the same relative location

-  in the EPUB archive OEBPS directory -- if your font file resides in

-  a different location you'll need to adjust the `--resource` option

-  accordingly (see the 'RESOURCES' section in the `a2x(1)` man page

-  for details).

-- The URL value of the CSS 'src' property is set to the destination

-  font file relative the the CSS file.

-- The `--resource` option allows you to inject any file (not just font

-  files) into the EPUB output document.

-- Using the CSS '@font-face' rule is a complex subject and is outside

-  the scope of the FAQ.

-- Many EPUB readers do not process embedded fonts.

-======

-

-

-== What's the difference between + quoted text and ` quoted monospaced text?

-`+` (plus) quoted text is implemented as an AsciiDoc 'quotes' whereas

-+`+ (grave accent or backtick) quoted text is implemented as an

-AsciiDoc 'inline literal' passthrough macro. The semantics are

-different:

-

-1. Inline passthrough macros are processed before any other inline

-   substitutions e.g. all of the following line will be processed as a

-   single inline passthrough and rendered as monospaced text (which is

-   not the intended result):

-+

---

-  `single quoted text' and `monospaced quoted text`

-

-This line works as expected:

-

-  `single quoted text' and +monospaced quoted text+

---

-

-2. Backtick quoted text is rendered literally i.e. no substitutions

-   are performed on the enclosed text.  Here are some examples that

-   would have to be escaped if plus quoting were used (<<X4,see

-   also>>):

-

-  The `++i` and `++j` auto-increments.

-  Paths `~/.vim` and `~/docs`.

-  The `__init__` method.

-  The `{id}` attribute.

-

-

-== Why is the generated HTML title element text invalid?

-Probably because your document title contains formatting that has

-generated HTML title markup. You can resolve this by explicitly

-defining the 'title' attribute in your document's header.

-

-

-== AsciiDoc sometimes generates invalid output markup, why?

-AsciiDoc is backend agnostic, the 'asciidoc' command has no knowledge

-of the syntax or structure of the backend format that it generates.

-Output document validation (syntactic and structural) should be

-performed separately by external validation tools. For example,

-AsciiDoc's 'a2x' toolchain command automatically performs validation

-checks using 'xmllint'.

-

-

-== The AsciiDoc toclevels attribute does not work with DocBook outputs, why?

-DocBook has no provision for specifying table of contents levels but

-you can set the TOC level further down the toolchain by passing the

-DocBook XSL Stylesheets

-http://docbook.sourceforge.net/release/xsl/current/doc/html/toc.section.depth.html[toc.section.depth]

-parameter to 'dblatex' (using the `--param` option) or 'xsltproc'

-(using the `--stringparam` option).  For example to show only chapter

-titles in the TOC of a 'book' document set 'toc.section.depth' to '0'.

-Increment the 'toc.section.depth' value to show more sub-section

-titles. If you are using 'a2x' you can set the options in the source

-file, for example:

-

-  // a2x: --xsltproc-opts "--stringparam toc.section.depth 0"

-  // a2x: --dblatex-opts "--param toc.section.depth=0"

-

-If the document is of type 'article' use the value '1' to show only

-top level section titles in the TOC, use the value '2' for two levels

-etc.

-

-

-== How can I include chapter and section tables of contents?

-DocBook outputs processed by DocBook XSL Stylesheets (either manually

-or via 'a2x') can generate additional separate section and chapter

-tables of contents using combinations of the

-http://www.sagehill.net/docbookxsl/TOCcontrol.html[TOC parameters].

-Here are some examples using combinations of the

-`generate.section.toc.level` and `toc.section.depth` DocBook XSL

-Stylesheets parameters:

-

-[cols="2*l,4",width="90%",frame="topbot",options="header"]

-|======================================================

-|generate.section.toc.level |toc.section.depth |

-|1 |

-|Single level book chapter TOCs or article section TOCs

-

-|1 | 3

-|Article section TOCs with two levels

-

-|1 | 2

-|Book chapter TOCs with two levels

-|======================================================

-

-

-== How can I customize the appearance of XHTML and EPUB documents generated by a2x?

-You can customize the appearance of an EPUB document with CSS.  See

-the link:publishing-ebooks-with-asciidoc.html[Sherlock Holmes eBook

-example] on the AsciiDoc website.

-

-

-== DocBook has many elements for document meta-data -- how can I use them from AsciiDoc?

-The 'docinfo', 'docinfo1' and 'docinfo2' attributes allow you include

-link:userguide.html#X97[document information files] containing DocBook

-XML into the header of the output file.

-

-

-== Do element titles automatically generate link captions?

-If you go the DocBook route then yes -- just omit the caption from the

-AsciiDoc 'xref' (`<<...>>`) macro. Both dblatex and DocBook XSL will

-use the target element's title text. Examples:

-

-[listing]

-..................................................................

-[[X1]]

-Section One

------------

-Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas

-ultrices justo porttitor augue. Vestibulum pretium. Donec porta

-

-See also <<X3>> (this link displays the text 'A titled paragraph').

-

-[id="X2",reftext="2nd section"]

-Section Two

------------

-See also <<X1>> (this link displays the text 'Section One').

-

-[[X3]]

-.A titled paragraph

-Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

-

-See also <<X2>> (this link displays the text '2nd section').

-..................................................................

-

-The AsciiDoc 'reftext' attribute has been used to explicitly set the

-link text to '2nd section' for 'Section Two'.

-

-

-== Can I define my own table styles?

-In addition to the built-in styles you can define your own. This

-example (for the 'xhtml11' backend) defines a table style called 'red'

-which sets the background cell color to red. First put the definition

-in a configuration file:

-

-[listing]

-.........................................

-[tabledef-default]

-red-style=tags="red"

-

-[tabletags-red]

-bodydata=<td style="background-color:red;">|</td>

-.........................................

-

-Now you can use the style name to style cells or columns (in this

-example we use an unambiguous shortened abbreviation 'r'):

-

-[listing]

-.........................................

-|==================================

-|Normal cell      r|Red cell

-|==================================

-.........................................

-

-

-== How can I add highlighted editorial comments to an AsciiDoc document?

-Both block and inline link:userguide.html#X25[comment lines] are

-displayed on the output if the 'showcomments' attribute is defined.

-Example:

-

-[listing]

-.........................................

-:showcomments:

-// A block comment line.

-

-Qui in magna commodo, est labitur dolorum an. Est ne magna primis

-// An inline comment line.

-adolescens.

-.........................................

-

-Is rendered as:

-

-:showcomments:

-// A block comment line.

-

-Qui in magna commodo, est labitur dolorum an. Est ne magna primis

-// An inline comment line.

-adolescens.

-

-NOTE: link:userguide.html#X26[Comment blocks] are never displayed.

-

-

-== What is the preferred file name extension for AsciiDoc files?

-The `.txt` http://en.wikipedia.org/wiki/Text_file[text file] extension

-is preferred, but it's just a convention and it's not enforced by the

-software.

-

-AsciiDoc source files are human readable

-http://en.wikipedia.org/wiki/Plain_text[plain text] files which is

-what the `.txt` extension is for. All text editors recognize and open

-files with a `.txt` extension. The `.txt` extension is universally

-recognized and unambiguous -- you are not left asking questions like

-``What on earth is this file with the funny extension?'', ``How do I

-open it?'' and ``Is it safe to open?''.

-

-

-== How can I generate numbered bibliographic entries?

-If your outputs are DocBook generated then adding the following inline

-macro to a custom configuration file will result in auto-incrementing

-bibliography entry numbers (instead of displaying the bibliographic

-identifiers):

-

-  [anchor3-inlinemacro]

-  <anchor id="{1}" xreflabel="[{counter:bibliography1}]"/>[{counter:bibliography2}]

-

-This FAQ submitted by Bela Hausmann.

-

-

-== How can I include lines of dashes inside a listing block?

-A line of four or more dashes will be mistaken for the ListingBlock

-terminator, one way round this problem is to use a LiteralBlock styled

-as a listing block. For example:

-

-  [listing]

-  ...........................

-  Lorum ipsum

-  -----------

-  ...........................

-

-

-== How can I customize PDF files generated by dblatex?

-

-There are a number of dblatex XSL parameters that can be used to

-customize PDF output. You can set them globally in the AsciiDoc

-`./dblatex/asciidoc-dblatex.xsl` configuration file or you can also

-pass them on the a2x(1) command-line. Here are some examples:

-

-The

-http://dblatex.sourceforge.net/doc/manual/latex.output.revhistory.html[latex.output.revhistory]

-parameter is used to suppress the revision history:

-

-  a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0" doc/article.txt

-

-The

-http://dblatex.sourceforge.net/doc/manual/doc.layout.html[doc.layout]

-parameter is used to include the cover page and document body (i.e. excludes

-table of contents and index), the

-http://dblatex.sourceforge.net/doc/manual/doc.publisher.show.html[doc.publisher.show]

-parameter is used to exclude the cover page logo:

-

-  a2x -f pdf --dblatex-opts " -P doc.layout=\"coverpage mainmatter\" -P doc.publisher.show=0" doc/article.txt

-

-See also the

-http://dblatex.sourceforge.net/doc/manual/sec-params.html[dblatex XSL

-parameter reference].

-

-

-== How can I add lists of figures and tables to PDFs created by dblatex?

-Set the

-http://dblatex.sourceforge.net/doc/sec-custom.html[doc.lot.show XSL

-parameter] -- you can set it using the dblatex `--param` command-line

-option, for example:

-

-  $ a2x --dblatex-opts="--param=doc.lot.show=figure,table" doc/article.txt

-

-

-== How can I stop the document title being displayed?

-You could simply omit the document title, but this will result in a

-blank 'title' element in HTML outputs. If you want the HTML 'title'

-element to contain the document title then define the 'notitle'

-attribute (this will just suppress displaying the title), for example:

-

-  My document title

-  =================

-  :no title:

-

-

-== Why am I having trouble getting nested macros to work?

-The following example expands the 'image' inline macro, but the

-expansion contains double-quote characters which confuses the ensuing

-'footnoteref' macro expansion:

-

-  footnoteref:["F1","A footnote, with an image image:smallnew.png[]"]

-

-The solution is to use unquoted attribute values, replacing embedded

-commas with the comma character entity (`&#44;`):

-

-  footnoteref:[F1,A footnote&#44; with an image image:smallnew.png[]]

-

-Similarly, you can embed double-quote characters in unquoted attribute

-values using the `&#34;` character entity.

-

-

-== Why am I getting DocBook validation errors?

-Not all valid AsciiDoc source generates valid DocBook, for example

-'special sections' (abstract, preface, colophon, dedication,

-bibliography, glossary, appendix, index, synopsis) have different

-DocBook schema's to normal document sections. For example, a paragraph

-is illegal in a bibliography.

-

-Don't forget if your document is a book you need to specify the

-asciidoc `-d book` command option, if you don't an article DocBook

-document will be generated, possibly containing book specific

-sections, resulting in validation errors.

-

-

-== How can I disable special section titles?

-For example, you want to use 'References' as a normal section name but

-AsciiDoc is auto-magically generating a DocBook 'bibliography'

-section. All you need to do is explicitly specify the section template

-name, for example:

-

-  [sect1]

-  References

-  ----------

-

-

-== How can I insert XML processing instructions into output documents?

-Use an inline or block passthrough macros. This example inserts

-`<?dblatex bgcolor="#cceeff"?>` into the DocBook output generated by

-AsciiDoc:

-

-  pass::[<?dblatex bgcolor="#cceeff"?>]

-

-NOTE: XML processing instructions are specific to the application that

-processes the XML (the previous `dblatex` processing instruction is

-recognized by `dblatex(1)` when it processes the DocBook XML generated

-by Asciidoc).

-

-

-[[X4]]

-== How do I prevent double-quoted text being mistaken for an inline literal?

-Mixing doubled-quoted text with inline literal passthroughs can

-produce undesired results, for example, all of the following line is

-interpreted as an inline literal passthrough:

-

-  ``XXX'' `YYY`

-

-In this case the solution is to use monospace quoting instead of the

-inline literal:

-

-  ``XXX'' +YYY+

-

-Use the +\pass:[]+ macro if it's necessary to suppress

-substitutions in the monospaced text, for example:

-

-  ``XXX'' +pass:[don't `quote` me]+

-

-

-== How can I generate a single HTML document file containing images and CSS styles?

-With the advent of Internet Explorer 8 all major web browsers now

-support the

-http://en.wikipedia.org/wiki/Data:_URI_scheme[data URI scheme] for

-embedded images. The AsciiDoc 'xhtml11' backend supports the data URI

-scheme for embedded images and by default it embeds the CSS

-stylesheet. For example the following command will generate a single

-`article.html` file containing embedded images, admonition icons and the CSS

-stylesheet:

-

-  $ asciidoc -a data-uri -a icons article.txt

-

-

-== Are there any tools to help me understand what's going on inside AsciiDoc?

-

-AsciiDoc has a built-in trace mechanism which is controlled by the

-'trace' attribute; there is also the `--verbose` command-line option.

-These features are detailed in

-http://www.methods.co.nz/asciidoc/userguide.html#X82[Appendix G of the

-User Guide].

-

-

-== One-liner ifdef::[]'s are disproportionately verbose can they shortened?

-

-This is the response to a question posted on the AsciiDoc discussion

-list, it illustrates a number of useful techniques. The question arose

-because the source highlight filter language identifier for the C++

-language is `c++` when generating PDFs via dblatex (LaTeX listings

-package) or `cpp` when generating HTML (GNU source-highlight).

-

-Using straight `ifdef::[]` block macros we have:

-

-[listing]

-.........................................

-\ifdef::basebackend-docbook[]

-[source,c++]

-\endif::basebackend-docbook[]

-\ifdef::basebackend-html[]

-[source,cpp]

-\endif::basebackend-html[]

------------------------------------------

-class FooParser {

-public:

-        virtual void startDocument() = 0;

-        virtual void endDocument() = 0;

-};

------------------------------------------

-.........................................

-

-

-This can be shortened using the short form of the `ifdef::[]` macro:

-

-[listing]

-.........................................

-\ifdef::basebackend-docbook[[source,c++]]

-\ifdef::basebackend-html[[source,cpp]]

------------------------------------------

-class FooParser {

-public:

-        virtual void startDocument() = 0;

-        virtual void endDocument() = 0;

-};

------------------------------------------

-.........................................

-

-

-Using a conditional attribute instead of the `ifdef::[]` macro is even

-shorter:

-

-[listing]

-.........................................

-[source,{basebackend@docbook:c++:cpp}]

------------------------------------------

-class FooParser {

-public:

-        virtual void startDocument() = 0;

-        virtual void endDocument() = 0;

-};

------------------------------------------

-.........................................

-

-

-If you have a number of listings it makes sense to factor the

-conditional attribute to a normal attribute:

-

-[listing]

-.........................................

-:cpp: {basebackend@docbook:c++:cpp}

-

-[source,{cpp}]

------------------------------------------

-class FooParser {

-public:

-        virtual void startDocument() = 0;

-        virtual void endDocument() = 0;

-};

------------------------------------------

-.........................................

-

-

-Even shorter, set the default source highlight filter `language`

-attribute so you don't have to specify it every time:

-

-[listing]

-.........................................

-:language: {basebackend@docbook:c++:cpp}

-

-[source]

------------------------------------------

-class FooParser {

-public:

-        virtual void startDocument() = 0;

-        virtual void endDocument() = 0;

-};

------------------------------------------

-.........................................

-

-

-== Some of my inline passthroughs are not passed through, why?

-

-Most likely the passthrough encloses another passthrough with a higher

-precedence. For example trying to render this +\pass:[]+ with this

-+\`\pass:[]`+ results in a blank string because the +\pass:[]+

-passthrough evaluates first, instead use monospaced quoting  and escape

-the passthrough i.e. ++ \+\\pass:[]+ ++

-

-

-== How can I place an anchor (link target) on a list item?

-

-You can't use a 'BlockId' block element inside a list but you can use

-the syntactically identical 'anchor' inline macro. For example:

-

----------------------

-one:: Item one.

-[[X2]]two:: Item two.

-three:: Item three.

----------------------

-

-This *will not* work:

-

----------------------

-one:: Item one.

-[[X2]]

-two:: Item two.

-three:: Item three.

----------------------

-

-

-== How can I stop lists from nesting?

-

-If you place two lists with different syntax hard up against each

-other then the second list will be nested in the first. If you don't

-want the second list to be nested separate them with a comment line

-block macro. For example:

-

--------------------

-1. List 1.

-2. List 1.

-

-//

-a. List 2.

-b. List 2.

--------------------

-

-

-== Is it possible to include charts in AsciiDoc documents?

-

-There are a number of programs available that generate presentation

-charts from textual specification, for example

-http://home.gna.org/pychart/[Pychart] is a library for writing chart

-scripts in Python. Here's an example from the 'Pychart' documentation:

-

-.barchart.py

----------------------------------------------------------------------

-#

-# Example bar chart (from Pychart documentation http://home.gna.org/pychart/).

-#

-from pychart import *

-theme.get_options()

-

-data = [(10, 20, 30, 5), (20, 65, 33, 5), (30, 55, 30, 5), (40, 45, 51, 7),

-        (50, 25, 27, 3), (60, 75, 30, 5), (70, 80, 42, 5), (80, 62, 32, 5),

-        (90, 42, 39, 5), (100, 32, 39, 4)]

-

-# The attribute y_coord=... tells that the Y axis values

-# should be taken from samples.

-# In this example, Y values will be [40,50,60,70,80].

-ar = area.T(y_coord = category_coord.T(data[3:8], 0),

-            x_grid_style=line_style.gray50_dash1,

-            x_grid_interval=20, x_range = (0,100),

-            x_axis=axis.X(label="X label"),

-            y_axis=axis.Y(label="Y label"),

-            bg_style = fill_style.gray90,

-            border_line_style = line_style.default,

-            legend = legend.T(loc=(80,10)))

-

-# Below call sets the default attributes for all bar plots.

-chart_object.set_defaults(bar_plot.T, direction="horizontal", data=data)

-

-# Attribute cluster=(0,3) tells that you are going to draw three bar

-# plots side by side.  The plot labeled "foo" will the leftmost (i.e.,

-# 0th out of 3).  Attribute hcol tells the column from which to

-# retrive sample values from.  It defaults to one.

-ar.add_plot(bar_plot.T(label="foo", cluster=(0,3)))

-ar.add_plot(bar_plot.T(label="bar", hcol=2, cluster=(1,3)))

-ar.add_plot(bar_plot.T(label="baz", hcol=3, cluster=(2,3)))

-ar.draw()

----------------------------------------------------------------------

-

-To execute the script and include the generated chart image in your

-document add the following lines to the AsciiDoc source:

-

----------------------------------------------------------------------

-// Generate chart image file.

-\sys2::[python "{indir}/barchart.py" --format=png --output="{outdir}/barchart.png" --scale=2]

-

-// Display chart image file.

-image::barchart.png[]

----------------------------------------------------------------------

-

-[NOTE]

-=====================================================================

-- The `barchart.py` script is located in the same directory as the

-  AsciiDoc source file (`{indir}`).

-- The generated chart image file (`barchart.png`) is written to the

-  same directory as the output file (`{outdir}`).

-=====================================================================

-

-== How can I render indented paragraphs?

-

-To unconditionally indent all paragraphs add the following line to the

-`xhtml11.css` stylesheet (or a custom stylesheet).

-

----------------------------------------------------------------------

-div.paragraph p {text-indent: 3em;}

----------------------------------------------------------------------

-

-This will restyle the entire document by indenting all paragraphs

-which is normally what you want to do (mixed paragraph styles produce

-ugly documents).

-

-To selectively indent paragraphs you could either create an 'indented'

-paragraph style from scratch or use the 'role' attribute.

-

-[float]

-==== Create an indented paragraph style

-Define an 'indented' paragraph style, for example, by putting this in

-a configuration file:

-

----------------------------------------------------------------------

-[paradef-default]

-indented-style=template="indentedparagraph"

-

-[indentedparagraph]

-<div class="paragraph"{id? id="{id}"} style="text-indent:3em;">{title?<div class="title">{title}</div>}<p>

-|

-</p></div>

----------------------------------------------------------------------

-

-Now apply the 'indented' style to normal paragraphs, for example:

-

----------------------------------------------------------------------

-[indented]

-Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas

-ultrices justo porttitor augue. Vestibulum pretium. Donec porta

-vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed

-lacinia. Vivamus at lectus.

----------------------------------------------------------------------

-

-[float]

-==== Use the role attribute

-Add the following line to the `xhtml11.css` stylesheet (or a custom

-stylesheet).

-

----------------------------------------------------------------------

-div.paragraph.indented p {text-indent: 3em;}

----------------------------------------------------------------------

-

-Apply the 'role' attribute to indented paragraphs, for example:

-

----------------------------------------------------------------------

-[role="indented"]

-Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas

-ultrices justo porttitor augue. Vestibulum pretium. Donec porta

-vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed

-lacinia. Vivamus at lectus.

----------------------------------------------------------------------

-

-NOTE: This FAQ applies to XHTML output not DocBook. To achieve the

-same results with DocBook use the 'role' attribute and customize the

-DocBook XSL stylesheets to indent paragraphs with the `simpara`

-element `role="indented"` attribute.

-

-

-== Is there a way to set default image height and width attributes?

-

-You can set the 'height' and 'width' attributes globally in your

-document with Attribute Entries or from the command-line using the

-`--attribute` option. In the following example images that don't

-explicitly set the 'height' and 'width' values will be 350 by 250

-pixels.

-

----------------------------------------------------------------------

-:height: 250

-:width: 350

-

-image:images/tiger.png[]

----------------------------------------------------------------------

-

-NOTE: Setting the global 'width' attribute will also set the default

-table width and you will need to explicitly set table widths.

-

-== How can I place a backslash character in front of an attribute reference without escaping the reference?

-

-Use the predefined `{backslash}` attribute reference instead of an

-actual backslash, for example if the `{projectname}` attribute has

-the value `foobar` then:

-

-  d:\data{backslash}{projectname}

-

-would be rendered as:

-

-  d:\data\foobar

-

-== How can I escape AsciiDoc markup?

-

-Most AsciiDoc inline elements can be suppressed by preceding them with

-a backslash character. These elements include:

-

-- Attribute references.

-- Text formatting.

-- Quoting,

-- Macros.

-- Replacements.

-- Special words.

-- Table cell separators.

-

-But there are exceptions -- see the next question.

-

-

-== Some elements can't be escaped with a single backslash

-

-There are a number of  exceptions to the usual single backslash rule

--- mostly relating to URL macros that  have two syntaxes or quoting

-ambiguity.  Here are some non-standard escape examples:

-

-[cols="l,v",width="40%",frame="topbot",options="header"]

-|========================================

-|AsciiDoc | Renders

-

-2*|

-\srackham@methods.co.nz

-<\srackham@methods.co.nz>

-\mailto:[\srackham@methods.co.nz]

-

-2*|

-\http://www.foo1.co.nz

-\\http://www.foobar.com[]

-\\http://www.foobar.com[Foobar Limited]

-

-2*|

-A C\++ Library for C++

-\\``double-quotes''

-\*\*F**ile Open\...

-|========================================

-

-The source of this problem is ambiguity across substitution types --

-the first match unescapes allowing the second to substitute. A

-work-around for difficult cases is to side-step the problem using the

-+\pass:[]+ passthrough inline macro.

-

-NOTE: Escaping is unnecessary inside 'inline literal passthroughs'

-(backtick quoted text).

-

-

-== How can I escape a list?

-Here's how to handle situations where the first line of a paragraph is

-mistaken for a list item.

-

-[float]

-==== Numbered and bulleted lists

-Precede the bullet or index of the first list item with an `{empty}`

-attribute, for example:

-

-  {empty}- Qui in magna commodo est labitur dolorum an.  Est ne magna

-  primis adolescens.

-

-The predefined `{empty}` attribute is replaced by an empty string and

-ensures the first line is not mistaken for a bulleted list item.

-

-[float]

-==== Labeled lists

-Two colons or semicolons in a paragraph may be confused with a labeled

-list entry. Use the predefined `{two-colons}` and `{two-semicolons}`

-attributes to suppress this behavior, for example:

-

-  Qui in magna commodo{two-colons} est labitur dolorum an. Est ne

-  magna primis adolescens.

-

-Will be rendered as:

-

-Qui in magna commodo{two-colons} est labitur dolorum an. Est ne

-magna primis adolescens.

-

-

-== How can I set default list and tables styles?

-

-You can set the element's 'style' entry in a global or custom

-configuration file.

-

-This example this will horizontally style all labeled lists that don't

-have an explicit style attribute:

-

-----------------------------------

-[listdef-labeled]

-style=horizontal

-

-[listdef-labeled2]

-style=horizontal

-----------------------------------

-

-This example will put a top and bottom border on all tables that don't

-already have an explicit style attribute:

-

-----------------------------------

-[tabledef-default]

-style=topbot

-topbot-style=frame="topbot"

-----------------------------------

-

-Alternatively you can set the configuration entries from inside your

-document, the above examples are equivalent to:

-

-----------------------------------

-:listdef-labeled.style: horizontal

-:listdef-labeled2.style: horizontal

-

-:tabledef-default.topbot-style: frame="topbot"

-:tabledef-default.style: topbot

-----------------------------------

-

-

-== Why do I get a filter non-zero exit code error?

-

-An error was returned when AsciiDoc tried to execute an external

-filter command. The most common reason for this is that the filter

-command could not be found by the command shell. To figure out what

-the problem is run AsciiDoc with the `--verbose` option to determine

-the command that is failing and then try to run the command manually

-from the command-line.

-

-

-== Are there any DocBook viewers?

-

-http://live.gnome.org/Yelp[Yelp], the GNOME help viewer, does a

-creditable job of displaying DocBook XML files directly.

-

-

-== Can you create ODF documents using AsciiDoc?

-

-The easiest and highest fidelity method I've seen is to generate

-HTML from AsciiDoc then paste it from your browser (we use Firefox)

-into OpenOffice Writer.

-

-- I found that that there is better fidelity pasting HTML generated by

-  the 'html4' backend instead of the default 'xhtml11' backend.

-- Don't paste AsciiDoc tables of contents, OpenOffice Writer (I was

-  using version 2.3) hangs when saving. This may be something to do

-  with the embedded JavaScript but I haven't looked closely at it, I

-  may even be wrong about this.

-

-This tip was contributed by Bernard Amade.

-

-

-== How can I suppress cell separators in included table data files?

-

-Use the `{include:}` system attribute instead of the `include::[]`

-macro (the former is not expanded until after the table data has been

-parsed into cells, whereas the latter is included before the table is

-processed.

-

-

-== How can I preserve paragraph line boundaries?

-

-Apply the The 'verse' paragraph style, the rendered text preserves

-line boundaries and is useful for lyrics and poems.  For example:

-

----------------------------------------------------------------------

-[verse]

-Consul *necessitatibus* per id,

-consetetur, eu pro everti postulant

-homero verear ea mea, qui.

----------------------------------------------------------------------

-

-Alternatively, if you are generating PDF files, you can use line

-breaks. For example:

-

----------------------------------------------------------------------

-Consul *necessitatibus* per id, +

-consetetur, eu pro everti postulant +

-homero verear ea mea, qui.

----------------------------------------------------------------------

-

-

-== How can I include non-breaking space characters?

-

-Use the non-breaking space character entity reference `&#160;` (see

-the next question). You could also use the predefined `{nbsp}`

-attribute reference.

-

-

-== Can I include HTML and XML character entity references in my document?

-

-Yes, just enter the reference in your document. For example `&#946;`

-will print a Greek small beta character &#946;

-

-

-[[X1]]

-== How do I include spaces in URLs?

-

-URL inline macro targets (addresses) cannot contain white space

-characters. If you need spaces encode them as `%20`. For example:

-

-  image:large%20image.png[]

-  http://www.foo.bar.com/an%20example%20document.html

-

-

-== How can I get AsciiDoc to assign the correct DocBook language attribute?

-

-Set the AsciiDoc 'lang' attribute to the appropriate language code.

-For example:

-

-  $ a2x -a lang=es doc/article.txt

-

-This will ensure that downstream DocBook processing will generate the

-correct language specific document headings (things like table of

-contents, revision history, figure and table captions, admonition

-captions).

-

-

-== How can I turn off table and image title numbering?

-For HTML outputs set the 'caption' attribute to an empty string,

-either globally:

-

--------------------------

-:caption:

--------------------------

-

-or on an element by element basis, for example:

-

--------------------------

-.Tiger

-[caption=""]

-image::images/tiger.png[]

--------------------------

-

-

-== How can I assign multiple author names?

-

-A quick way to do this is put both authors in a single first name, for

-example:

-

----------------------------------------

-My Document

-===========

-:Author: Bill_and_Ben_the_Flowerpot_Men

-:Author Initials: BB & BC

----------------------------------------

-

-asciidoc(1) replaces the underscores with spaces.

-

-If you are generating DocBook then a  more flexible approach is to

-create a 'docinfo' file containing a DocBook 'authorgroup' element

-(search the 'User Guide' for 'docinfo' for more details).

-

-

-== How can I selectively disable a quoted text substitution?

-

-Omitting the tag name will disable quoting. For example, if you don't

-want superscripts or subscripts then put the following in a custom

-configuration file or edit the global `asciidoc.conf` configuration

-file:

-

--------------------

-[quotes]

-^=

-~=

--------------------

-

-Alternatively you can set the configuration entries from within your

-document, the above examples are equivalent to:

-

--------------------

-:quotes.^:

-:quotes.~:

--------------------

-

-

-== How can I customize the \{localdate} format?

-

-The default format for the `{localdate}` attribute is the ISO 8601

-`yyyy-mm-dd` format. You can change this format by explicitly setting

-the `{localdate}` attribute. For example by setting it using the

-asciidoc(1) `-a` command-line option:

-

-  $ asciidoc -a localdate=`date +%d-%m-%Y` mydoc.txt

-

-You could also set it by adding an Attribute Entry to your source

-document, for example:

-

-  :localdate: {sys: date +%Y-%m-%d}

-

-

-== Why doesn't AsciiDoc support strike through text?

-

-DocBook does not have provision for strike through text and one of the

-AsciiDoc design goals is that AsciiDoc markup should strive to be

-applicable to all output formats.

-

-Strike through is normally used to mark deleted text -- a more

-comprehensive way to manage document revisions is to use a version

-control system such as Subversion. You can also use the AsciiDoc

-'CommentLines' and 'CommentBlocks' to retain revised text in the

-source document.

-

-If you really need strike through text for (X)HTML outputs then adding

-the following to a configuration file will allow you to quote strike

-through text with hyphen characters:

-

----------------------------------------------------------------------

- ifdef::basebackend-html[]

-

- [quotes]

- -=strikethrough

-

- [tags]

- strikethrough=<del>|</del>

-

- endif::basebackend-html[]

----------------------------------------------------------------------

-

-

-== Where can I find examples of commands used to build output documents?

-

-The User Guide has some. You could also look at `./doc/main.aap` and

-`./examples/website/main.aap` in the AsciiDoc distribution, they have

-all the commands used to build the AsciiDoc documentation and the

-AsciiDoc website (even if you don't use A-A-P you'll still find it

-useful).

-

-

-== Why have you used the DocBook <simpara> element instead of <para>?

-

-`<simpara>` is really the same as `<para>` except it can't contain

-block elements -- this matches, more closely, the AsciiDoc paragraph

-semantics.

-

-

-== How can I format text inside a listing block?

-

-By default only 'specialcharacters' and 'callouts' are substituted in

-listing blocks; you can add quotes substitutions by explicitly setting

-the block 'subs' attribute, for example:

-

-[listing]

-..........................................

-[subs="quotes"]

-------------------------------------------

-$ ls *-al*

-------------------------------------------

-..........................................

-

-The `-al` will rendered bold. Note that:

-

-- You would need to explicitly escape text you didn't want quoted.

-- Don't do this in source code listing blocks because it modifies the

-  source code which confuses the syntax highlighter.

-- This only works if your DocBook processor recognizes DocBook

-  `<emphasis>` elements inside `<screen>` elements.

-

-Alternative, if the lines are contiguous, you could use the 'literal'

-paragraph style:

-

-------------------------------------------

-["literal",subs="quotes"]

-$ ls *-al*

-------------------------------------------

-

-

-== Why doesn't the include1::[] macro work?

-

-Internally the `include1` macro is translated to the `include1` system

-attribute which means it must be evaluated in a region where attribute

-substitution is enabled. `include1` won't work, for example, in a

-ListingBlock (unless attribute substitution is enabled).  `include1`

-is intended for use in configuration files, use the `include` macro

-and set the attribute `depth=1` instead, for example:

-

-[listing]

-................................................

-------------------------------------------------

-\include::blogpost_media_processing.txt[depth=1]

-------------------------------------------------

-................................................

-

-

-== How can I make the mailto macro work with multiple email addresses?

-

-For the AsciiDoc 'mailto' macro to work with multiple email addresses

-(as per RFC2368) you need to URL encode the '@' characters (replace

-them with '%40'), if you don't the individual addresses will be

-rendered as separate links. You also need to <<X1,replace spaces with

-'%20'>>.

-

-For example, the following call won't work:

-

-  mailto:jb@foobar.com,jd@acme.co.nz?subject=New foofoo release[New foofoo release]

-

-Use this instead:

-

-  mailto:jb%40foobar.com,jd%40acme.co.nz?subject=New%20foofoo%20release[New foofoo release]

-

-

-== How can a replacement have a trailing backslash?

-Quote the entry name -- this nonsensical example replaces `x\` with

-`y`:

-

-  "x\\"=y

-

-If quoting were omitted the equals character (separating the

-entry name `x` from the value `y`) would be escaped.

-

-

+AsciiDoc Frequently Asked Questions
+===================================
+
+
+[NOTE]
+======
+- New FAQs are normally added at the top of this document.
+- The FAQ may be updated between AsciiDoc releases so some of the
+  newer FAQs may apply to the trunk and not the current release.
+======
+
+[[X5]]
+== How can I include embedded fonts in an EPUB document
+This is a two step process:
+
+1. Declare the font files and their use in your document's CSS
+   stylesheet. For example:
++
+[listing]
+.........................................
+@font-face {
+  font-family : LiberationSerif-Regular;
+  font-weight : normal;
+  font-style: normal;
+  src : url(LiberationSerif-Regular.ttf);
+}
+
+body {
+  font-family: LiberationSerif-Regular, serif;
+}
+.........................................
+
+2. Declare the the font file as resource when you use `a2x(1)` to
+   compile the EPUB. For example:
+
+  a2x -f epub -d book --epubcheck --stylesheet epubtest.css --resource .ttf=application/x-font-ttf --resource LiberationSerif-Regular.ttf epubtest.txt
+
+[NOTE]
+======
+- Requires AsciiDoc 8.6.5 or better.
+- The True Type Font mimetype had to be declared explicitly with the
+  `--resource .ttf=application/x-font-ttf` option because it wasn't
+  registered on my Linux system.
+- In the above example the font file is in the same directory as the
+  AsciiDoc source file and is installed to the same relative location
+  in the EPUB archive OEBPS directory -- if your font file resides in
+  a different location you'll need to adjust the `--resource` option
+  accordingly (see the 'RESOURCES' section in the `a2x(1)` man page
+  for details).
+- The URL value of the CSS 'src' property is set to the destination
+  font file relative the the CSS file.
+- The `--resource` option allows you to inject any file (not just font
+  files) into the EPUB output document.
+- Using the CSS '@font-face' rule is a complex subject and is outside
+  the scope of the FAQ.
+- Many EPUB readers do not process embedded fonts.
+======
+
+
+== What's the difference between + quoted text and ` quoted monospaced text?
+`+` (plus) quoted text is implemented as an AsciiDoc 'quotes' whereas
++`+ (grave accent or backtick) quoted text is implemented as an
+AsciiDoc 'inline literal' passthrough macro. The semantics are
+different:
+
+1. Inline passthrough macros are processed before any other inline
+   substitutions e.g. all of the following line will be processed as a
+   single inline passthrough and rendered as monospaced text (which is
+   not the intended result):
++
+--
+  `single quoted text' and `monospaced quoted text`
+
+This line works as expected:
+
+  `single quoted text' and +monospaced quoted text+
+--
+
+2. Backtick quoted text is rendered literally i.e. no substitutions
+   are performed on the enclosed text.  Here are some examples that
+   would have to be escaped if plus quoting were used (<<X4,see
+   also>>):
+
+  The `++i` and `++j` auto-increments.
+  Paths `~/.vim` and `~/docs`.
+  The `__init__` method.
+  The `{id}` attribute.
+
+
+== Why is the generated HTML title element text invalid?
+Probably because your document title contains formatting that has
+generated HTML title markup. You can resolve this by explicitly
+defining the 'title' attribute in your document's header.
+
+
+== AsciiDoc sometimes generates invalid output markup, why?
+AsciiDoc is backend agnostic, the 'asciidoc' command has no knowledge
+of the syntax or structure of the backend format that it generates.
+Output document validation (syntactic and structural) should be
+performed separately by external validation tools. For example,
+AsciiDoc's 'a2x' toolchain command automatically performs validation
+checks using 'xmllint'.
+
+
+== The AsciiDoc toclevels attribute does not work with DocBook outputs, why?
+DocBook has no provision for specifying table of contents levels but
+you can set the TOC level further down the toolchain by passing the
+DocBook XSL Stylesheets
+http://docbook.sourceforge.net/release/xsl/current/doc/html/toc.section.depth.html[toc.section.depth]
+parameter to 'dblatex' (using the `--param` option) or 'xsltproc'
+(using the `--stringparam` option).  For example to show only chapter
+titles in the TOC of a 'book' document set 'toc.section.depth' to '0'.
+Increment the 'toc.section.depth' value to show more sub-section
+titles. If you are using 'a2x' you can set the options in the source
+file, for example:
+
+  // a2x: --xsltproc-opts "--stringparam toc.section.depth 0"
+  // a2x: --dblatex-opts "--param toc.section.depth=0"
+
+If the document is of type 'article' use the value '1' to show only
+top level section titles in the TOC, use the value '2' for two levels
+etc.
+
+
+== How can I include chapter and section tables of contents?
+DocBook outputs processed by DocBook XSL Stylesheets (either manually
+or via 'a2x') can generate additional separate section and chapter
+tables of contents using combinations of the
+http://www.sagehill.net/docbookxsl/TOCcontrol.html[TOC parameters].
+Here are some examples using combinations of the
+`generate.section.toc.level` and `toc.section.depth` DocBook XSL
+Stylesheets parameters:
+
+[cols="2*l,4",width="90%",frame="topbot",options="header"]
+|======================================================
+|generate.section.toc.level |toc.section.depth |
+|1 |
+|Single level book chapter TOCs or article section TOCs
+
+|1 | 3
+|Article section TOCs with two levels
+
+|1 | 2
+|Book chapter TOCs with two levels
+|======================================================
+
+
+== How can I customize the appearance of XHTML and EPUB documents generated by a2x?
+You can customize the appearance of an EPUB document with CSS.  See
+the link:publishing-ebooks-with-asciidoc.html[Sherlock Holmes eBook
+example] on the AsciiDoc website.
+
+
+== DocBook has many elements for document meta-data -- how can I use them from AsciiDoc?
+The 'docinfo', 'docinfo1' and 'docinfo2' attributes allow you include
+link:userguide.html#X97[document information files] containing DocBook
+XML into the header of the output file.
+
+
+== Do element titles automatically generate link captions?
+If you go the DocBook route then yes -- just omit the caption from the
+AsciiDoc 'xref' (`<<...>>`) macro. Both dblatex and DocBook XSL will
+use the target element's title text. Examples:
+
+[listing]
+..................................................................
+[[X1]]
+Section One
+-----------
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
+ultrices justo porttitor augue. Vestibulum pretium. Donec porta
+
+See also <<X3>> (this link displays the text 'A titled paragraph').
+
+[id="X2",reftext="2nd section"]
+Section Two
+-----------
+See also <<X1>> (this link displays the text 'Section One').
+
+[[X3]]
+.A titled paragraph
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+
+See also <<X2>> (this link displays the text '2nd section').
+..................................................................
+
+The AsciiDoc 'reftext' attribute has been used to explicitly set the
+link text to '2nd section' for 'Section Two'.
+
+
+== Can I define my own table styles?
+In addition to the built-in styles you can define your own. This
+example (for the 'xhtml11' backend) defines a table style called 'red'
+which sets the background cell color to red. First put the definition
+in a configuration file:
+
+[listing]
+.........................................
+[tabledef-default]
+red-style=tags="red"
+
+[tabletags-red]
+bodydata=<td style="background-color:red;">|</td>
+.........................................
+
+Now you can use the style name to style cells or columns (in this
+example we use an unambiguous shortened abbreviation 'r'):
+
+[listing]
+.........................................
+|==================================
+|Normal cell      r|Red cell
+|==================================
+.........................................
+
+
+== How can I add highlighted editorial comments to an AsciiDoc document?
+Both block and inline link:userguide.html#X25[comment lines] are
+displayed on the output if the 'showcomments' attribute is defined.
+Example:
+
+[listing]
+.........................................
+:showcomments:
+// A block comment line.
+
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+// An inline comment line.
+adolescens.
+.........................................
+
+Is rendered as:
+
+:showcomments:
+// A block comment line.
+
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+// An inline comment line.
+adolescens.
+
+NOTE: link:userguide.html#X26[Comment blocks] are never displayed.
+
+
+== What is the preferred file name extension for AsciiDoc files?
+The `.txt` http://en.wikipedia.org/wiki/Text_file[text file] extension
+is preferred, but it's just a convention and it's not enforced by the
+software.
+
+AsciiDoc source files are human readable
+http://en.wikipedia.org/wiki/Plain_text[plain text] files which is
+what the `.txt` extension is for. All text editors recognize and open
+files with a `.txt` extension. The `.txt` extension is universally
+recognized and unambiguous -- you are not left asking questions like
+``What on earth is this file with the funny extension?'', ``How do I
+open it?'' and ``Is it safe to open?''.
+
+
+== How can I generate numbered bibliographic entries?
+If your outputs are DocBook generated then adding the following inline
+macro to a custom configuration file will result in auto-incrementing
+bibliography entry numbers (instead of displaying the bibliographic
+identifiers):
+
+  [anchor3-inlinemacro]
+  <anchor id="{1}" xreflabel="[{counter:bibliography1}]"/>[{counter:bibliography2}]
+
+This FAQ submitted by Bela Hausmann.
+
+
+== How can I include lines of dashes inside a listing block?
+A line of four or more dashes will be mistaken for the ListingBlock
+terminator, one way round this problem is to use a LiteralBlock styled
+as a listing block. For example:
+
+  [listing]
+  ...........................
+  Lorum ipsum
+  -----------
+  ...........................
+
+
+== How can I customize PDF files generated by dblatex?
+
+There are a number of dblatex XSL parameters that can be used to
+customize PDF output. You can set them globally in the AsciiDoc
+`./dblatex/asciidoc-dblatex.xsl` configuration file or you can also
+pass them on the a2x(1) command-line. Here are some examples:
+
+The
+http://dblatex.sourceforge.net/doc/manual/latex.output.revhistory.html[latex.output.revhistory]
+parameter is used to suppress the revision history:
+
+  a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0" doc/article.txt
+
+The
+http://dblatex.sourceforge.net/doc/manual/doc.layout.html[doc.layout]
+parameter is used to include the cover page and document body (i.e. excludes
+table of contents and index), the
+http://dblatex.sourceforge.net/doc/manual/doc.publisher.show.html[doc.publisher.show]
+parameter is used to exclude the cover page logo:
+
+  a2x -f pdf --dblatex-opts " -P doc.layout=\"coverpage mainmatter\" -P doc.publisher.show=0" doc/article.txt
+
+See also the
+http://dblatex.sourceforge.net/doc/manual/sec-params.html[dblatex XSL
+parameter reference].
+
+
+== How can I add lists of figures and tables to PDFs created by dblatex?
+Set the
+http://dblatex.sourceforge.net/doc/sec-custom.html[doc.lot.show XSL
+parameter] -- you can set it using the dblatex `--param` command-line
+option, for example:
+
+  $ a2x --dblatex-opts="--param=doc.lot.show=figure,table" doc/article.txt
+
+
+== How can I stop the document title being displayed?
+You could simply omit the document title, but this will result in a
+blank 'title' element in HTML outputs. If you want the HTML 'title'
+element to contain the document title then define the 'notitle'
+attribute (this will just suppress displaying the title), for example:
+
+  My document title
+  =================
+  :no title:
+
+
+== Why am I having trouble getting nested macros to work?
+The following example expands the 'image' inline macro, but the
+expansion contains double-quote characters which confuses the ensuing
+'footnoteref' macro expansion:
+
+  footnoteref:["F1","A footnote, with an image image:smallnew.png[]"]
+
+The solution is to use unquoted attribute values, replacing embedded
+commas with the comma character entity (`&#44;`):
+
+  footnoteref:[F1,A footnote&#44; with an image image:smallnew.png[]]
+
+Similarly, you can embed double-quote characters in unquoted attribute
+values using the `&#34;` character entity.
+
+
+== Why am I getting DocBook validation errors?
+Not all valid AsciiDoc source generates valid DocBook, for example
+'special sections' (abstract, preface, colophon, dedication,
+bibliography, glossary, appendix, index, synopsis) have different
+DocBook schema's to normal document sections. For example, a paragraph
+is illegal in a bibliography.
+
+Don't forget if your document is a book you need to specify the
+asciidoc `-d book` command option, if you don't an article DocBook
+document will be generated, possibly containing book specific
+sections, resulting in validation errors.
+
+
+== How can I disable special section titles?
+For example, you want to use 'References' as a normal section name but
+AsciiDoc is auto-magically generating a DocBook 'bibliography'
+section. All you need to do is explicitly specify the section template
+name, for example:
+
+  [sect1]
+  References
+  ----------
+
+
+== How can I insert XML processing instructions into output documents?
+Use an inline or block passthrough macros. This example inserts
+`<?dblatex bgcolor="#cceeff"?>` into the DocBook output generated by
+AsciiDoc:
+
+  pass::[<?dblatex bgcolor="#cceeff"?>]
+
+NOTE: XML processing instructions are specific to the application that
+processes the XML (the previous `dblatex` processing instruction is
+recognized by `dblatex(1)` when it processes the DocBook XML generated
+by Asciidoc).
+
+
+[[X4]]
+== How do I prevent double-quoted text being mistaken for an inline literal?
+Mixing doubled-quoted text with inline literal passthroughs can
+produce undesired results, for example, all of the following line is
+interpreted as an inline literal passthrough:
+
+  ``XXX'' `YYY`
+
+In this case the solution is to use monospace quoting instead of the
+inline literal:
+
+  ``XXX'' +YYY+
+
+Use the +\pass:[]+ macro if it's necessary to suppress
+substitutions in the monospaced text, for example:
+
+  ``XXX'' +pass:[don't `quote` me]+
+
+
+== How can I generate a single HTML document file containing images and CSS styles?
+With the advent of Internet Explorer 8 all major web browsers now
+support the
+http://en.wikipedia.org/wiki/Data:_URI_scheme[data URI scheme] for
+embedded images. The AsciiDoc 'xhtml11' backend supports the data URI
+scheme for embedded images and by default it embeds the CSS
+stylesheet. For example the following command will generate a single
+`article.html` file containing embedded images, admonition icons and the CSS
+stylesheet:
+
+  $ asciidoc -a data-uri -a icons article.txt
+
+
+== Are there any tools to help me understand what's going on inside AsciiDoc?
+
+AsciiDoc has a built-in trace mechanism which is controlled by the
+'trace' attribute; there is also the `--verbose` command-line option.
+These features are detailed in
+http://www.methods.co.nz/asciidoc/userguide.html#X82[Appendix G of the
+User Guide].
+
+
+== One-liner ifdef::[]'s are disproportionately verbose can they shortened?
+
+This is the response to a question posted on the AsciiDoc discussion
+list, it illustrates a number of useful techniques. The question arose
+because the source highlight filter language identifier for the C++
+language is `c++` when generating PDFs via dblatex (LaTeX listings
+package) or `cpp` when generating HTML (GNU source-highlight).
+
+Using straight `ifdef::[]` block macros we have:
+
+[listing]
+.........................................
+\ifdef::basebackend-docbook[]
+[source,c++]
+\endif::basebackend-docbook[]
+\ifdef::basebackend-html[]
+[source,cpp]
+\endif::basebackend-html[]
+-----------------------------------------
+class FooParser {
+public:
+        virtual void startDocument() = 0;
+        virtual void endDocument() = 0;
+};
+-----------------------------------------
+.........................................
+
+
+This can be shortened using the short form of the `ifdef::[]` macro:
+
+[listing]
+.........................................
+\ifdef::basebackend-docbook[[source,c++]]
+\ifdef::basebackend-html[[source,cpp]]
+-----------------------------------------
+class FooParser {
+public:
+        virtual void startDocument() = 0;
+        virtual void endDocument() = 0;
+};
+-----------------------------------------
+.........................................
+
+
+Using a conditional attribute instead of the `ifdef::[]` macro is even
+shorter:
+
+[listing]
+.........................................
+[source,{basebackend@docbook:c++:cpp}]
+-----------------------------------------
+class FooParser {
+public:
+        virtual void startDocument() = 0;
+        virtual void endDocument() = 0;
+};
+-----------------------------------------
+.........................................
+
+
+If you have a number of listings it makes sense to factor the
+conditional attribute to a normal attribute:
+
+[listing]
+.........................................
+:cpp: {basebackend@docbook:c++:cpp}
+
+[source,{cpp}]
+-----------------------------------------
+class FooParser {
+public:
+        virtual void startDocument() = 0;
+        virtual void endDocument() = 0;
+};
+-----------------------------------------
+.........................................
+
+
+Even shorter, set the default source highlight filter `language`
+attribute so you don't have to specify it every time:
+
+[listing]
+.........................................
+:language: {basebackend@docbook:c++:cpp}
+
+[source]
+-----------------------------------------
+class FooParser {
+public:
+        virtual void startDocument() = 0;
+        virtual void endDocument() = 0;
+};
+-----------------------------------------
+.........................................
+
+
+== Some of my inline passthroughs are not passed through, why?
+
+Most likely the passthrough encloses another passthrough with a higher
+precedence. For example trying to render this +\pass:[]+ with this
++\`\pass:[]`+ results in a blank string because the +\pass:[]+
+passthrough evaluates first, instead use monospaced quoting  and escape
+the passthrough i.e. ++ \+\\pass:[]+ ++
+
+
+== How can I place an anchor (link target) on a list item?
+
+You can't use a 'BlockId' block element inside a list but you can use
+the syntactically identical 'anchor' inline macro. For example:
+
+---------------------
+one:: Item one.
+[[X2]]two:: Item two.
+three:: Item three.
+---------------------
+
+This *will not* work:
+
+---------------------
+one:: Item one.
+[[X2]]
+two:: Item two.
+three:: Item three.
+---------------------
+
+
+== How can I stop lists from nesting?
+
+If you place two lists with different syntax hard up against each
+other then the second list will be nested in the first. If you don't
+want the second list to be nested separate them with a comment line
+block macro. For example:
+
+-------------------
+1. List 1.
+2. List 1.
+
+//
+a. List 2.
+b. List 2.
+-------------------
+
+
+== Is it possible to include charts in AsciiDoc documents?
+
+There are a number of programs available that generate presentation
+charts from textual specification, for example
+http://home.gna.org/pychart/[Pychart] is a library for writing chart
+scripts in Python. Here's an example from the 'Pychart' documentation:
+
+.barchart.py
+---------------------------------------------------------------------
+#
+# Example bar chart (from Pychart documentation http://home.gna.org/pychart/).
+#
+from pychart import *
+theme.get_options()
+
+data = [(10, 20, 30, 5), (20, 65, 33, 5), (30, 55, 30, 5), (40, 45, 51, 7),
+        (50, 25, 27, 3), (60, 75, 30, 5), (70, 80, 42, 5), (80, 62, 32, 5),
+        (90, 42, 39, 5), (100, 32, 39, 4)]
+
+# The attribute y_coord=... tells that the Y axis values
+# should be taken from samples.
+# In this example, Y values will be [40,50,60,70,80].
+ar = area.T(y_coord = category_coord.T(data[3:8], 0),
+            x_grid_style=line_style.gray50_dash1,
+            x_grid_interval=20, x_range = (0,100),
+            x_axis=axis.X(label="X label"),
+            y_axis=axis.Y(label="Y label"),
+            bg_style = fill_style.gray90,
+            border_line_style = line_style.default,
+            legend = legend.T(loc=(80,10)))
+
+# Below call sets the default attributes for all bar plots.
+chart_object.set_defaults(bar_plot.T, direction="horizontal", data=data)
+
+# Attribute cluster=(0,3) tells that you are going to draw three bar
+# plots side by side.  The plot labeled "foo" will the leftmost (i.e.,
+# 0th out of 3).  Attribute hcol tells the column from which to
+# retrive sample values from.  It defaults to one.
+ar.add_plot(bar_plot.T(label="foo", cluster=(0,3)))
+ar.add_plot(bar_plot.T(label="bar", hcol=2, cluster=(1,3)))
+ar.add_plot(bar_plot.T(label="baz", hcol=3, cluster=(2,3)))
+ar.draw()
+---------------------------------------------------------------------
+
+To execute the script and include the generated chart image in your
+document add the following lines to the AsciiDoc source:
+
+---------------------------------------------------------------------
+// Generate chart image file.
+\sys2::[python "{indir}/barchart.py" --format=png --output="{outdir}/barchart.png" --scale=2]
+
+// Display chart image file.
+image::barchart.png[]
+---------------------------------------------------------------------
+
+[NOTE]
+=====================================================================
+- The `barchart.py` script is located in the same directory as the
+  AsciiDoc source file (`{indir}`).
+- The generated chart image file (`barchart.png`) is written to the
+  same directory as the output file (`{outdir}`).
+=====================================================================
+
+== How can I render indented paragraphs?
+
+To unconditionally indent all paragraphs add the following line to the
+`xhtml11.css` stylesheet (or a custom stylesheet).
+
+---------------------------------------------------------------------
+div.paragraph p {text-indent: 3em;}
+---------------------------------------------------------------------
+
+This will restyle the entire document by indenting all paragraphs
+which is normally what you want to do (mixed paragraph styles produce
+ugly documents).
+
+To selectively indent paragraphs you could either create an 'indented'
+paragraph style from scratch or use the 'role' attribute.
+
+[float]
+==== Create an indented paragraph style
+Define an 'indented' paragraph style, for example, by putting this in
+a configuration file:
+
+---------------------------------------------------------------------
+[paradef-default]
+indented-style=template="indentedparagraph"
+
+[indentedparagraph]
+<div class="paragraph"{id? id="{id}"} style="text-indent:3em;">{title?<div class="title">{title}</div>}<p>
+|
+</p></div>
+---------------------------------------------------------------------
+
+Now apply the 'indented' style to normal paragraphs, for example:
+
+---------------------------------------------------------------------
+[indented]
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
+ultrices justo porttitor augue. Vestibulum pretium. Donec porta
+vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed
+lacinia. Vivamus at lectus.
+---------------------------------------------------------------------
+
+[float]
+==== Use the role attribute
+Add the following line to the `xhtml11.css` stylesheet (or a custom
+stylesheet).
+
+---------------------------------------------------------------------
+div.paragraph.indented p {text-indent: 3em;}
+---------------------------------------------------------------------
+
+Apply the 'role' attribute to indented paragraphs, for example:
+
+---------------------------------------------------------------------
+[role="indented"]
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
+ultrices justo porttitor augue. Vestibulum pretium. Donec porta
+vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed
+lacinia. Vivamus at lectus.
+---------------------------------------------------------------------
+
+NOTE: This FAQ applies to XHTML output not DocBook. To achieve the
+same results with DocBook use the 'role' attribute and customize the
+DocBook XSL stylesheets to indent paragraphs with the `simpara`
+element `role="indented"` attribute.
+
+
+== Is there a way to set default image height and width attributes?
+
+You can set the 'height' and 'width' attributes globally in your
+document with Attribute Entries or from the command-line using the
+`--attribute` option. In the following example images that don't
+explicitly set the 'height' and 'width' values will be 350 by 250
+pixels.
+
+---------------------------------------------------------------------
+:height: 250
+:width: 350
+
+image:images/tiger.png[]
+---------------------------------------------------------------------
+
+NOTE: Setting the global 'width' attribute will also set the default
+table width and you will need to explicitly set table widths.
+
+== How can I place a backslash character in front of an attribute reference without escaping the reference?
+
+Use the predefined `{backslash}` attribute reference instead of an
+actual backslash, for example if the `{projectname}` attribute has
+the value `foobar` then:
+
+  d:\data{backslash}{projectname}
+
+would be rendered as:
+
+  d:\data\foobar
+
+== How can I escape AsciiDoc markup?
+
+Most AsciiDoc inline elements can be suppressed by preceding them with
+a backslash character. These elements include:
+
+- Attribute references.
+- Text formatting.
+- Quoting,
+- Macros.
+- Replacements.
+- Special words.
+- Table cell separators.
+
+But there are exceptions -- see the next question.
+
+
+== Some elements can't be escaped with a single backslash
+
+There are a number of  exceptions to the usual single backslash rule
+-- mostly relating to URL macros that  have two syntaxes or quoting
+ambiguity.  Here are some non-standard escape examples:
+
+[cols="l,v",width="40%",frame="topbot",options="header"]
+|========================================
+|AsciiDoc | Renders
+
+2*|
+\srackham@methods.co.nz
+<\srackham@methods.co.nz>
+\mailto:[\srackham@methods.co.nz]
+
+2*|
+\http://www.foo1.co.nz
+\\http://www.foobar.com[]
+\\http://www.foobar.com[Foobar Limited]
+
+2*|
+A C\++ Library for C++
+\\``double-quotes''
+\*\*F**ile Open\...
+|========================================
+
+The source of this problem is ambiguity across substitution types --
+the first match unescapes allowing the second to substitute. A
+work-around for difficult cases is to side-step the problem using the
++\pass:[]+ passthrough inline macro.
+
+NOTE: Escaping is unnecessary inside 'inline literal passthroughs'
+(backtick quoted text).
+
+
+== How can I escape a list?
+Here's how to handle situations where the first line of a paragraph is
+mistaken for a list item.
+
+[float]
+==== Numbered and bulleted lists
+Precede the bullet or index of the first list item with an `{empty}`
+attribute, for example:
+
+  {empty}- Qui in magna commodo est labitur dolorum an.  Est ne magna
+  primis adolescens.
+
+The predefined `{empty}` attribute is replaced by an empty string and
+ensures the first line is not mistaken for a bulleted list item.
+
+[float]
+==== Labeled lists
+Two colons or semicolons in a paragraph may be confused with a labeled
+list entry. Use the predefined `{two-colons}` and `{two-semicolons}`
+attributes to suppress this behavior, for example:
+
+  Qui in magna commodo{two-colons} est labitur dolorum an. Est ne
+  magna primis adolescens.
+
+Will be rendered as:
+
+Qui in magna commodo{two-colons} est labitur dolorum an. Est ne
+magna primis adolescens.
+
+
+== How can I set default list and tables styles?
+
+You can set the element's 'style' entry in a global or custom
+configuration file.
+
+This example this will horizontally style all labeled lists that don't
+have an explicit style attribute:
+
+----------------------------------
+[listdef-labeled]
+style=horizontal
+
+[listdef-labeled2]
+style=horizontal
+----------------------------------
+
+This example will put a top and bottom border on all tables that don't
+already have an explicit style attribute:
+
+----------------------------------
+[tabledef-default]
+style=topbot
+topbot-style=frame="topbot"
+----------------------------------
+
+Alternatively you can set the configuration entries from inside your
+document, the above examples are equivalent to:
+
+----------------------------------
+:listdef-labeled.style: horizontal
+:listdef-labeled2.style: horizontal
+
+:tabledef-default.topbot-style: frame="topbot"
+:tabledef-default.style: topbot
+----------------------------------
+
+
+== Why do I get a filter non-zero exit code error?
+
+An error was returned when AsciiDoc tried to execute an external
+filter command. The most common reason for this is that the filter
+command could not be found by the command shell. To figure out what
+the problem is run AsciiDoc with the `--verbose` option to determine
+the command that is failing and then try to run the command manually
+from the command-line.
+
+
+== Are there any DocBook viewers?
+
+http://live.gnome.org/Yelp[Yelp], the GNOME help viewer, does a
+creditable job of displaying DocBook XML files directly.
+
+
+== Can you create ODF documents using AsciiDoc?
+
+The easiest and highest fidelity method I've seen is to generate
+HTML from AsciiDoc then paste it from your browser (we use Firefox)
+into OpenOffice Writer.
+
+- I found that that there is better fidelity pasting HTML generated by
+  the 'html4' backend instead of the default 'xhtml11' backend.
+- Don't paste AsciiDoc tables of contents, OpenOffice Writer (I was
+  using version 2.3) hangs when saving. This may be something to do
+  with the embedded JavaScript but I haven't looked closely at it, I
+  may even be wrong about this.
+
+This tip was contributed by Bernard Amade.
+
+
+== How can I suppress cell separators in included table data files?
+
+Use the `{include:}` system attribute instead of the `include::[]`
+macro (the former is not expanded until after the table data has been
+parsed into cells, whereas the latter is included before the table is
+processed.
+
+
+== How can I preserve paragraph line boundaries?
+
+Apply the The 'verse' paragraph style, the rendered text preserves
+line boundaries and is useful for lyrics and poems.  For example:
+
+---------------------------------------------------------------------
+[verse]
+Consul *necessitatibus* per id,
+consetetur, eu pro everti postulant
+homero verear ea mea, qui.
+---------------------------------------------------------------------
+
+Alternatively, if you are generating PDF files, you can use line
+breaks. For example:
+
+---------------------------------------------------------------------
+Consul *necessitatibus* per id, +
+consetetur, eu pro everti postulant +
+homero verear ea mea, qui.
+---------------------------------------------------------------------
+
+
+== How can I include non-breaking space characters?
+
+Use the non-breaking space character entity reference `&#160;` (see
+the next question). You could also use the predefined `{nbsp}`
+attribute reference.
+
+
+== Can I include HTML and XML character entity references in my document?
+
+Yes, just enter the reference in your document. For example `&#946;`
+will print a Greek small beta character &#946;
+
+
+[[X1]]
+== How do I include spaces in URLs?
+
+URL inline macro targets (addresses) cannot contain white space
+characters. If you need spaces encode them as `%20`. For example:
+
+  image:large%20image.png[]
+  http://www.foo.bar.com/an%20example%20document.html
+
+
+== How can I get AsciiDoc to assign the correct DocBook language attribute?
+
+Set the AsciiDoc 'lang' attribute to the appropriate language code.
+For example:
+
+  $ a2x -a lang=es doc/article.txt
+
+This will ensure that downstream DocBook processing will generate the
+correct language specific document headings (things like table of
+contents, revision history, figure and table captions, admonition
+captions).
+
+
+== How can I turn off table and image title numbering?
+For HTML outputs set the 'caption' attribute to an empty string,
+either globally:
+
+-------------------------
+:caption:
+-------------------------
+
+or on an element by element basis, for example:
+
+-------------------------
+.Tiger
+[caption=""]
+image::images/tiger.png[]
+-------------------------
+
+
+== How can I assign multiple author names?
+
+A quick way to do this is put both authors in a single first name, for
+example:
+
+---------------------------------------
+My Document
+===========
+:Author: Bill_and_Ben_the_Flowerpot_Men
+:Author Initials: BB & BC
+---------------------------------------
+
+asciidoc(1) replaces the underscores with spaces.
+
+If you are generating DocBook then a  more flexible approach is to
+create a 'docinfo' file containing a DocBook 'authorgroup' element
+(search the 'User Guide' for 'docinfo' for more details).
+
+
+== How can I selectively disable a quoted text substitution?
+
+Omitting the tag name will disable quoting. For example, if you don't
+want superscripts or subscripts then put the following in a custom
+configuration file or edit the global `asciidoc.conf` configuration
+file:
+
+-------------------
+[quotes]
+^=
+~=
+-------------------
+
+Alternatively you can set the configuration entries from within your
+document, the above examples are equivalent to:
+
+-------------------
+:quotes.^:
+:quotes.~:
+-------------------
+
+
+== How can I customize the \{localdate} format?
+
+The default format for the `{localdate}` attribute is the ISO 8601
+`yyyy-mm-dd` format. You can change this format by explicitly setting
+the `{localdate}` attribute. For example by setting it using the
+asciidoc(1) `-a` command-line option:
+
+  $ asciidoc -a localdate=`date +%d-%m-%Y` mydoc.txt
+
+You could also set it by adding an Attribute Entry to your source
+document, for example:
+
+  :localdate: {sys: date +%Y-%m-%d}
+
+
+== Why doesn't AsciiDoc support strike through text?
+
+DocBook does not have provision for strike through text and one of the
+AsciiDoc design goals is that AsciiDoc markup should strive to be
+applicable to all output formats.
+
+Strike through is normally used to mark deleted text -- a more
+comprehensive way to manage document revisions is to use a version
+control system such as Subversion. You can also use the AsciiDoc
+'CommentLines' and 'CommentBlocks' to retain revised text in the
+source document.
+
+If you really need strike through text for (X)HTML outputs then adding
+the following to a configuration file will allow you to quote strike
+through text with hyphen characters:
+
+---------------------------------------------------------------------
+ ifdef::basebackend-html[]
+
+ [quotes]
+ -=strikethrough
+
+ [tags]
+ strikethrough=<del>|</del>
+
+ endif::basebackend-html[]
+---------------------------------------------------------------------
+
+
+== Where can I find examples of commands used to build output documents?
+
+The User Guide has some. You could also look at `./doc/main.aap` and
+`./examples/website/main.aap` in the AsciiDoc distribution, they have
+all the commands used to build the AsciiDoc documentation and the
+AsciiDoc website (even if you don't use A-A-P you'll still find it
+useful).
+
+
+== Why have you used the DocBook <simpara> element instead of <para>?
+
+`<simpara>` is really the same as `<para>` except it can't contain
+block elements -- this matches, more closely, the AsciiDoc paragraph
+semantics.
+
+
+== How can I format text inside a listing block?
+
+By default only 'specialcharacters' and 'callouts' are substituted in
+listing blocks; you can add quotes substitutions by explicitly setting
+the block 'subs' attribute, for example:
+
+[listing]
+..........................................
+[subs="quotes"]
+------------------------------------------
+$ ls *-al*
+------------------------------------------
+..........................................
+
+The `-al` will rendered bold. Note that:
+
+- You would need to explicitly escape text you didn't want quoted.
+- Don't do this in source code listing blocks because it modifies the
+  source code which confuses the syntax highlighter.
+- This only works if your DocBook processor recognizes DocBook
+  `<emphasis>` elements inside `<screen>` elements.
+
+Alternative, if the lines are contiguous, you could use the 'literal'
+paragraph style:
+
+------------------------------------------
+["literal",subs="quotes"]
+$ ls *-al*
+------------------------------------------
+
+
+== Why doesn't the include1::[] macro work?
+
+Internally the `include1` macro is translated to the `include1` system
+attribute which means it must be evaluated in a region where attribute
+substitution is enabled. `include1` won't work, for example, in a
+ListingBlock (unless attribute substitution is enabled).  `include1`
+is intended for use in configuration files, use the `include` macro
+and set the attribute `depth=1` instead, for example:
+
+[listing]
+................................................
+------------------------------------------------
+\include::blogpost_media_processing.txt[depth=1]
+------------------------------------------------
+................................................
+
+
+== How can I make the mailto macro work with multiple email addresses?
+
+For the AsciiDoc 'mailto' macro to work with multiple email addresses
+(as per RFC2368) you need to URL encode the '@' characters (replace
+them with '%40'), if you don't the individual addresses will be
+rendered as separate links. You also need to <<X1,replace spaces with
+'%20'>>.
+
+For example, the following call won't work:
+
+  mailto:jb@foobar.com,jd@acme.co.nz?subject=New foofoo release[New foofoo release]
+
+Use this instead:
+
+  mailto:jb%40foobar.com,jd%40acme.co.nz?subject=New%20foofoo%20release[New foofoo release]
+
+
+== How can a replacement have a trailing backslash?
+Quote the entry name -- this nonsensical example replaces `x\` with
+`y`:
+
+  "x\\"=y
+
+If quoting were omitted the equals character (separating the
+entry name `x` from the value `y`) would be escaped.
+
+