alias asciidoc='asciidoc --unsafe'
Add this alias to your shell’s RC file:
alias asciidoc='asciidoc --unsafe'
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 Appendix G of the User Guide.
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:
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:
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:
[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:
: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:
:language: {basebackend@docbook:c++:cpp} [source] ----------------------------------------- class FooParser { public: virtual void startDocument() = 0; virtual void endDocument() = 0; }; -----------------------------------------
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:[]+
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.
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.
There are a number of programs available that generate presentation charts from textual specification, for example Pychart is a library for writing chart scripts in Python. Here’s an example from the Pychart documentation:
# # 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
|
|
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. |
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[]
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
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.
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:
AsciiDoc | Renders |
---|---|
\srackham@methods.co.nz <\srackham@methods.co.nz> \mailto:[\srackham@methods.co.nz] |
srackham@methods.co.nz
<srackham@methods.co.nz>
mailto:[srackham@methods.co.nz] |
\http://www.foo1.co.nz \\http://www.foobar.com[] \\http://www.foobar.com[Foobar Limited] |
http://www.foo1.co.nz
http://www.foobar.com[]
http://www.foobar.com[Foobar Limited] |
A C\++ Library for C++ \\``double-quotes'' \*\*F**ile Open\... |
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). |
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
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.
Yelp, the GNOME help viewer, does a creditable job of displaying DocBook files 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.
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.
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.
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 (using FOP) or HTML files, you can use line breaks. For example:
Consul *necessitatibus* per id, + consetetur, eu pro everti postulant + homero verear ea mea, qui.
Use the non-breaking space character entity reference   (see the next question). You could also use the predefined {nbsp} attribute reference.
Yes, just enter the reference in your document. For example β will print a Greek small beta character β
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
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).
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
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.
The longer, semantically correct, way is to override the [header] configuration file section in a document specific .conf file. For example if your document is mydoc.txt then a file called mydoc.conf in the document directory would be picked up automatically by asciidoc(1). Copy and paste the default docbook.conf file [header] to mydoc.conf and modify the author related markup:
[header] : <authorgroup>... :
Two colons or semicolons in a paragraph may be confused with a labeled list entry. Use the predefined {two_colons} and {two_semicolons} 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:: est labitur dolorum an. Est ne magna primis adolescens.
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.~:
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}
Since it’s set using an executable attribute you’ll also need to include the --unsafe option when you run asciidoc).
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[]
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).
<simpara> is really the same as <para> except it can’t contain block elements — this matches, more closely, the AsciiDoc paragraph semantics.
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:
[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*
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:
------------------------------------------------ include::blogpost_media_processing.txt[depth=1] ------------------------------------------------
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 dblatex documentation.
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 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]
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.