A2X(1) ====== 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 <>). '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 <>. *-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. [[X1]] 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. [[X2]] 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: . `a2x.conf` from the AsciiDoc global configuration directory. . `a2x.conf` from the AsciiDoc `$HOME/.asciidoc` configuration directory. . `a2x.conf` from the directory containing 'a2x.py'. . The 'CONF_FILE' specified in the '--conf-file' option. Here are the default configuration file option values: --------------------------------------------------------------------- # Optional environment variable dictionary passed to # executing programs. If set to None the existing # environment is used. ENV = None # External executables. ASCIIDOC = 'asciidoc' 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. ASCIIDOC_OPTS = '' DBLATEX_OPTS = '' FOP_OPTS = '' XSLTPROC_OPTS = '' --------------------------------------------------------------------- BUGS ---- See the AsciiDoc distribution BUGS file. AUTHOR ------ Written by Stuart Rackham, RESOURCES --------- SourceForge: http://sourceforge.net/projects/asciidoc/ Main web site: http://www.methods.co.nz/asciidoc/ COPYING ------- Copyright \(C) 2002-2010 Stuart Rackham. Free use of this software is granted under the terms of the MIT license.