a2x3

Introduction

a2x3 - you may read this as an abbreviation for asciidoc3 2 (to) extra formats using Python3 - enhances the possibilities of AsciiDoc3.
To say it in a few words: out of your plain text file asciidoc3 generates HTML-output (defaults to HTML5, XHTML is possible - HTML4, too, but deprecated). If you set the appropriate option, DocBook XML 4.5 or 5.1 output is an alternative. (We ignore at this point the two rarely used options slidy and latex. The latter is currently hardly applicable.)

empty

NEW: asciidoc3 produces PDF

Caution The up-to-date version of asciidoc3 can produce a PDF, too!

From now on it is possible to let asciidoc3 produce a PDF:
Previous versions: a2x3 -a icons -f pdf doc/test.txt
Today you type something like so:
asciidoc3 --pdf=fop -a icons -v doc/test.txt

empty

Note This way is a hack.

Please keep in mind, that you need an installed FOP/dblatex anyway and an executable a2x3 in the same directory. The implementation on Windows is not perfect, the appropriate setting of imagedir is tricky and sometimes confusing. And, you need (of course) additional programs like Apache FOP, xmllint … Read some more infos here. If you are stuck, go back to the a2x3 way …

empty

Target File Formats

a2x3 is a toolchain manager for AsciiDoc3 and converts AsciiDoc3 text files to other file formats:

  • PDF (probably most used)

  • EPUB

  • DVI

  • PS

  • LaTeX (currently tricky)

  • (Unix) man page

  • HTML Help

  • pure text.

Rationale

One of the biggest hurdles for new users is installing, configuring and using a DocBook XML toolchain. a2x3 can help — it’s a toolchain wrapper command that will generate XHTML (chunked and unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text file outputs from an AsciiDoc3 text file. a2x3 does all the grunt work associated with generating and sequencing the toolchain commands and managing intermediate and output files. a2x3 also optionally deploys admonition and navigation icons and a CSS stylesheet.

Examples

The following examples generate doc/source-highlight-filter.pdf from the AsciiDoc3 doc/source-highlight-filter.txt source file. The first example uses dblatex (the default PDF generator) the second example forces FOP to be used:

$ a2x3 -f pdf doc/source-highlight-filter.txt
$ a2x3 -f pdf --fop doc/source-highlight-filter.txt

Installation, Dependencies and Third Party Packages

a2x3 comes to you in different flavors analogue to asciidoc3. Recommended to use for the normal user (who just wants easy HTML output) is the package with an embedded Python interpreter included. So you do not need to care about your Python environment (Good News for Windows users …) But of course an option with Python is available. See page installation for the details.

asciidoc3 and a2x3 come with no dependencies to keep it as simple as possible.
If you want more than producing html-output (PDF, filter like Lilypond, Highlight, Pygments, Graphviz, w3m/lynx …) you’ll need the following packages:

In addition to asciidoc3 you also need xsltproc(1), DocBook XSL Stylesheets and optionally: dblatex or FOP (to generate PDF); w3m(1) or lynx(1) (to generate text).

empty

COPYING

Copyright © 2002-2011 Stuart Rackham - Python2
Copyright © 2018-2025 Berthold Gehrke
Free use of this software is granted under the terms of the GNU Affero General Public License (AGPLv3) or later.

empty

Note From now on you see the man page!

a2x3 Manpage

Herre you see the a2x3 man page for details.
a2x3 - A toolchain manager for AsciiDoc3 (converts AsciiDoc3 text files to other file formats)

SYNOPSIS

a2x3 [OPTIONS] SOURCE_FILE

DESCRIPTION

A DocBook toolchain manager that translates an AsciiDoc3 text file SOURCE_FILE to PDF, EPUB, DVI, PS, LaTeX, XHTML (single page or chunked), man page, HTML Help or plain text formats using asciidoc3(1) and other applications (see REQUISITES section). SOURCE_FILE can also be a DocBook file with an .xml extension.

OPTIONS

-a, --attribute=ATTRIBUTE

Set asciidoc3(1) attribute value (shortcut for --asciidoc3-opts="-a ATTRIBUTE" option). This option may be specified more than once.

--asciidoc3-opts=ASCIIDOC3_OPTS

Additional asciidoc3(1) options. This option may be specified more than once.

--conf-file=CONF_FILE

Load configuration file. See CONF FILES section.

-D, --destination-dir=DESTINATION_DIR

Output directory. Defaults to SOURCE_FILE directory. This option is only applicable to HTML based output formats (chunked, epub, htmlhelp, xhtml).

-d, --doctype=DOCTYPE

DocBook document type: article, manpage or book. Default document type is article unless the format is manpage (in which case it defaults to manpage).

-b, --backend=BACKEND

BACKEND is the name of an installed backend plugin. When this option is specified a2x3 attempts load a file name a2x3-backend.py from the BACKEND plugin directory. It then converts the SOURCE_FILE to a BACKEND formatted output file using a global function defined in a2x3-backend.py called to_BACKEND.

-f, --format=FORMAT

Output formats: chunked, docbook, dvi, epub, htmlhelp, manpage, pdf (default), ps, tex, text, xhtml. The AsciiDoc3 a2x3-format attribute value is set to FORMAT.

-h, --help

Print command-line syntax and program options to stdout.

--icons

Use admonition or navigation icon images in output documents. The default behavior is to use text in place of icons.

--icons-dir=PATH

A path (relative to output files) containing admonition and navigation icons. Defaults to images/icons. The --icons option is implicit if this option is used.

-k, --keep-artifacts

Do not delete temporary build files.

--lynx

Use lynx(1) to generate text formatted output. The default behavior is to use w3m(1).

-L, --no-xmllint

Do not check asciidoc3 output with xmllint(1).

---epubcheck

Check EPUB output with epubcheck(1).

-n, --dry-run

Do not do anything just print what would have been done.

-r, --resource=RESOURCE_SPEC

Specify a resource. This option may be specified more than once. See the RESOURCES section for more details.

-m, --resource-manifest=FILE

FILE contains a list resources (one per line). Manifest FILE entries are formatted just like --resource option arguments. Environment variables and tilde home directories are allowed.

--stylesheet=STYLESHEET

A space delimited list of one or more CSS stylesheet file names that are used to style HTML output generated by DocBook XSL Stylesheets. Defaults to docbook-xsl.css. The stylesheets are processed in list order. The stylesheets must reside in a valid resource file location. Applies to HTML formats: xhtml, epub, chunked, htmlhelp formats.

-v, --verbose

Print operational details to stderr. A second -v option applies the verbose option to toolchain commands.

--version

Print program version to stdout.

--xsltproc-opts=XSLTPROC_OPTS

Additional xsltproc(1) options. This option may be specified more than once.

--xsl-file=XSL_FILE

Override the built-in XSL stylesheet with the custom XSL stylesheet XSL_FILE.

--fop

Use FOP to generate PDFs. The default behavior is to use dblatex(1). The --fop option is implicit when using the --fop-opts option.

--fop-opts=FOP_OPTS

Additional fop(1) options. If this option is specified FOP is used to generate PDFs. This option may be specified more than once.

--dblatex-opts=DBLATEX_OPTS

Additional dblatex(1) options. This option may be specified more than once.

--backend-opts=BACKEND_OPTS

Options for the backend plugin specified by the --backend option. This option may be specified more than once.

Options can also be set in the AsciiDoc3 source file. If SOURCE_FILE contains a comment line beginning with // a2x3: (slash slash whitespace a2x3 colon) then the remainder of the line will be treated as a2x3 command-line options. For example:

a2x3 default options
// a2x3: -dbook --epubcheck
Suppress revision history in dblatex outputs.
// a2x3: --dblatex-opts "-P latex.output.revhistory=0"

  • Options spanning multiple such comment lines will be concatenated.

  • Zero or more white space characters can appear between the leading // and a2x3:.

  • Command-line options take precedence over options set in the source file.

OUTPUT FILES

Output files are written to the directory specified by the --destination-dir option. If no --destination-dir option is set output files are written to the SOURCE_FILE directory.

Output files have the same name as the SOURCE_FILE but with an appropriate file name extension: .html for xhtml; .epub for epub; .hhp for htmlhelp; .pdf for pdf; .text for text, .xml for docbook. By convention manpages have no .man extension (man page section number only). Chunked HTML directory names have a .chunked extension; chunked HTML Help directory names have a .htmlhelp extension.

Same named existing files are overwritten without notice!

In addition to generating HTML files the xhtml, epub, chunked and htmlhelp formats ensure resource files are copied to their correct destination directory locations.

RESOURCES

Resources are files (typically CSS and images) that are required by HTML based outputs (xhtml, epub, chunked, htmlhelp formats). a2x3 scans the generated HTML files and builds a list of required CSS and image files. Additional resource files can be specified explicitly using the --resource option.

a2x3 searches for resource files in the following locations in the following order:

  1. The SOURCE_FILE directory.

  2. Resource directories specified by the --resource option (searched recursively).

  3. Resource directories specified by the --resource-manifest option (searched recursively in the order they appear in the manifest file).

  4. The stock images and stylesheets directories in the asciidoc3(1) configuration files directories (searched recursively).

  5. The destination directory.

When a resource file is found it is copied to the correct relative destination directory. Missing destination sub-directories are created automatically.

There are two distinct mechanisms for specifying additional resources:

  1. A resource directory which will be searched recursively for missing resource files.

  2. A resource file which will be copied to the output destination directory.

Resources are specified with --resource option values which can be one of the following formats:

  • <resource_dir>

  • <resource_file>[=<destination_file>]

  • .<ext>=<mimetype>

Where:

<resource_dir>

Specifies a directory (absolute or relative to the SOURCE_FILE) which is searched recursively for missing resource files. To eliminate ambiguity the <resource_dir> name should end with a directory separator character.

<resource_file>

Specifies a resource file (absolute or relative to the SOURCE_FILE) which will be copied to <destination_file>. If <destination_file> is not specified then it is the same as the <resource_file>.

<destination_file>

Specifies the destination of the copied source file. The <destination_file> path is relative to the destination directory (absolute paths are not allowed). The location of the destination directory depends on the output FORMAT (see the OUTPUT FILES section for details):

chunked, htmlhelp

The chunked output directory.

epub

The archived OEBPS directory.

xhtml

The output DESTINATION_DIR.

.<ext>=<mimetype>

When adding resources to EPUB files the mimetype is inferred from the <destination file> extension, if the mimetype cannot be guessed an error occurs. The .<ext>=<mimetype> resource syntax can be used to explicitly set mimetypes. <ext> is the file name extension, <mimetype> is the corresponding MIME type.

Resource option examples:

--resource ../images/
--resource doc/README.txt=README.txt
--resource ~/images/tiger.png=images/tiger.png
--resource .ttf=application/x-font-ttf

EXAMPLES

a2x3 -f pdf doc/source-highlight-filter.txt

Generates doc/source-highlight-filter.pdf file.

a2x3 -f xhtml -D ../doc --icons -r ../images/ team.txt

Creates HTML file ../doc/team.html, uses admonition icons and recursively searches the ../images/ directory for any missing resources.

a2x3 -f manpage doc/asciidoc3.1.txt

Generate doc/asciidoc3.1 manpage.

REQUISITES

a2x3 uses the following programs: (see also Dependencies and other Packages above)

CONF FILES

A configuration file contains executable Python code that overrides the global configuration parameters in a2x3.py. Optional configuration files are loaded in the following order:

  1. a2x3.conf from the directory containing the a2x3.py executable.

  2. a2x3.conf from the AsciiDoc3 global configuration directory. Skip this step if we are executing a locally installed (non system wide) copy.

  3. a2x3.conf from the AsciiDoc3 $HOME/.asciidoc3 configuration directory.

  4. The CONF_FILE specified in the --conf-file option.

Here are the default configuration file option values as defined in a2x3.py:

# External executables.
ASCIIDOC3 = asciidoc3
XSLTPROC = xsltproc
DBLATEX = dblatex # pdf generation.
FOP = fop # pdf generation (--fop option).
W3M = w3m # text generation.
LYNX = lynx # text generation (if no w3m).
XMLLINT = xmllint # Set to ' to disable.
EPUBCHECK = 'epubcheck # Set to ' to disable.
# External executable default options.
ASCIIDOC3_OPTS = '
DBLATEX_OPTS = '
FOP_OPTS = '
XSLTPROC_OPTS = ''

To Top ↑