AsciiDoc Frequently Asked Questions
===================================


== 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 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 epansion:

  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 (`,`):

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

Similarly, you can embed double-quote characters in unquoted attribute
values using the `"` 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 schemas 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
  ----------


== Why don't tables generated by dblatex obey the width attribute?
Tables generated by dblatex will take 100% of the available space
unless you change the 'pageunits' micellaneous parameter to 'pt'.
Here's how:

- From the command-line with the `-a pageunits=pt` option
- Or by setting `pageunits=pt` in a configuration file
  `[miscellaneous]` section.
- Or by setting this AttributeEntry in your document:

  :miscellaneous.pageunits: pt

See the
http://www.methods.co.nz/asciidoc/userguide.html#X89[DocBook table
widths] sidebar in the 'AsciiDoc User Guide' for an explanation.


== 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).


== 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 PDF's 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 monspaced 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 with the 'indented' style add the
following line to the `xhtml11.css` stylesheet (or a custom
stylesheet).

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

Then 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.
---------------------------------------------------------------------

NOTE: This FAQ applies to XHTML output not DocBook. To achieve the
same results with DocBook you would need to 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 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%",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.

=== 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.

=== 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. Just
run it from the command-line, for example:

  $ yelp file://home/srackham/tmp/book.xml

Note that you have to supply the full path name in URI format, this
shell script makes interactive use easier:

-------------------------------
#!/bin/sh
if [ -z "$1" ]; then
    echo "usage: dbkview FILE"
    exit 1
fi
yelp "file://$(pwd)/$1"
-------------------------------

This tip was submitted by Lionel Orry.


== 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 supress 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).


== Why does AsciiDoc give me a ``malformed author'' error?

This is normally because there are more than three names (up to three
are expected: first name, middle name and last name). For example,
this author line would result in an error:

  Vincent Willem van Gogh

You can enter multi-word first, middle and last names in the author
line using the underscore as a word separator. For example:

  Vincent Willem van_Gogh

You could also resolve the problem by replacing the author line with
explicit attribute entries:

----------------------
:First name:  Vincent
:Middle name: Willem
:Last name:   Van Gogh
----------------------


== 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-%d-%Y` mydoc.txt

You could also set it by adding an Attribute Entry to your souce
document, for example:

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


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

The reason it's not in the distribution is that 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` in
the AsciiDoc distribution, it has all the commands used to build the
AsciiDoc documentation (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 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, for example:

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

See also the http://dblatex.sourceforge.net/[dblatex] documentation.


== 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.