A2X(1)
======
:doctype: manpage


NAME
----
a2x - A toolchain manager for AsciiDoc (converts Asciidoc text files to other
      file formats)


SYNOPSIS
--------
*a2x* ['OPTIONS'] 'SOURCE_FILE'


DESCRIPTION
-----------
A DocBook toolchain manager that translates an AsciiDoc text file
'SOURCE_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 <<X1,REQUISITES section>>).
'SOURCE_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 <<X2,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*='PATH'::
  If 'PATH' refers to a directory recursively search it for required
  <<X3,resource files>>. If 'PATH' refers to a file add it to the list
  of required resource files. This option may be specified more than
  once.

*-m, --resource-manifest*='FILE'::
  'FILE' contains a list resources (one per line). Manifest 'FILE'
  entries are treated just like *--resource* option arguments.

*--stylesheet*='STYLESHEET'::
  The file name of the docbook-xsl CSS stylesheet file. Defaults to
  'docbook-xsl.css'.  The stylesheet must reside in a valid <<X3,
  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.

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

Options can also be set in the AsciiDoc source file. If 'SOURCE_FILE'
contains a comment line beginning with *// a2x:* then the remainder of
the line will be treated as 'a2x' command-line options. Options
spanning multiple such comment lines will be concatenated.  Zero or
more white space characters can appear between the leading *//* and
*a2x:*.  Command-line options take precedence over options set in the
source file. Example usage:

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


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 ensure <<X3,resource files>> are copied to
their correct destination directory locations.


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

'a2x' searches for resources in the following locations in the
following order:

. The 'SOURCE_FILE' directory.
. Directories specified by *--resource* and *--resource-manifest*
  options (recursively).
. The 'asciidoc(1)' `images` and `stylesheets` configuration file
  directories (recursively).
. The destination directory.

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


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/
- *epubcheck* (epub format -- EPUB file validator):
  http://code.google.com/p/epubcheck/

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 directory containing the 'a2x.py' executable.
. `a2x.conf` from the AsciiDoc global configuration directory.  Skip
  this step if we are executing a locally installed (non system wide)
  copy.
. `a2x.conf` from the AsciiDoc `$HOME/.asciidoc` configuration
  directory.
. 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, <srackham@gmail.com>


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.

