NAME
a2x - A toolchain manager for AsciiDoc (converts Asciidoc text files to
other file formats)
SYNOPSIS
a2x [OPTIONS] FILE
DESCRIPTION
A DocBook toolchain manager that translates an AsciiDoc text file FILE
to PDF, EPUB, DVI, PS, LaTeX, XHTML (single page or chunked), man page,
HTML Help or plain text formats using asciidoc(1) and other
applications (see REQUISITES section). FILE can also be a DocBook file
with an .xml extension.
OPTIONS
-a, --attribute=ATTRIBUTE
Set asciidoc(1) attribute value (shortcut for --asciidoc-opts="-a
ATTRIBUTE" option). This option may be specified more than once.
--asciidoc-opts=ASCIIDOC_OPTS
Additional asciidoc(1) options.
--conf-file=CONF_FILE
Load configuration file. See CONF FILES section.
-D, --destination-dir=PATH
Output directory. Defaults to source FILE directory.
-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).
-f, --format=FORMAT
Output formats: chunked, docbook, dvi, epub, htmlhelp, manpage, pdf
(default), ps, tex, text, xhtml.
-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.
--lynx
Use lynx(1) to generate text formatted output. The default behavior
is to use w3m(1).
-L, --no-xmllint
Do not check asciidoc 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-dir=PATH
If a relative image or CSS resource is not found relative to the
source FILE then search the PATH recursively. This option may be
specified more than once.
--stylesheet=PATH
A path (relative to destination HTML files) specifying the
docbook-xsl CSS stylesheet file. Defaults to docbook-xsl.css.
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.
--fop
Use FOP to generate PDFs. The default behavior is to use
dblatex(1). The --fop option is implicit if this option is used.
--fop-opts=FOP_OPTS
Additional fop(1) options. If this option is specified FOP is used
to generate PDFs.
--dblatex-opts=DBLATEX_OPTS
Additional dblatex(1) options.
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.
In addition to generating HTML files the xhtml, epub, chunked and
htmlhelp formats copy images and CSS stylesheet files referenced in the
generated HTML outputs from locations relative to the asciidoc input
FILE to the correct relative destination directory locations generating
required sub-directories if necessary. See also the --resource-dir
option.
EXAMPLES
a2x -f pdf doc/source-highlight-filter.txt
Generates doc/source-highlight-filter.pdf file.
a2x -f xhtml -D ../doc --icons -r ../images team.txt
Creates HTML file ../doc/team.html, uses admonition icons and
searches ../images for any missing resources.
a2x -f manpage doc/asciidoc.1.txt
Generate doc/asciidoc.1 manpage.
REQUISITES
a2x uses the following programs:
· Asciidoc: http://www.methods.co.nz/asciidoc/
· xsltproc: (all formats except text): http://xmlsoft.org/XSLT/
· DocBook XSL Stylesheets (all formats except text):
http://docbook.sourceforge.net/projects/xsl/
· dblatex (pdf, dvi, ps, tex formats):
http://dblatex.sourceforge.net/
· FOP (pdf format — alternative PDF file generator):
http://xmlgraphics.apache.org/fop/
· w3m (text format): http://w3m.sourceforge.net/index.en.html
· Lynx (text format — alternative text file generator):
http://lynx.isc.org/
See also the latest README file.
CONF FILES
A configuration file contains executable Python code that overrides the
global configuration parameters in a2x.py. Optional configuration files
are loaded in the following order:
1. a2x.conf from the AsciiDoc global configuration directory.
2. a2x.conf from the AsciiDoc $HOME/.asciidoc configuration
directory.
3. a2x.conf from the directory containing a2x.py.
4. The CONF_FILE specified in the --conf-file option.
BUGS
See the AsciiDoc distribution BUGS file.
AUTHOR
Written by Stuart Rackham, <srackham@gmail.com[1]>
RESOURCES
SourceForge: http://sourceforge.net/projects/asciidoc/
Main web site: http://www.methods.co.nz/asciidoc/
COPYING
Copyright (C) 2002-2009 Stuart Rackham. Free use of this software is
granted under the terms of the MIT license.
NOTES
1. srackham@gmail.com
mailto:srackham@gmail.com
01/15/2010