A2X(1)
======


NAME
----
a2x - convert Asciidoc text file to PDF, XHTML, HTML Help, manpage or
plain text


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


DESCRIPTION
-----------
A DocBook toolchain wrapper script that translates an AsciiDoc text
file 'FILE' to PDF, DVI, PS, LaTeX, XHTML (single page or chunked),
man page, HTML Help or plain text formats. PDF, XHTML, man page and
HTML Help formats are are generated using the asciidoc(1),
xsltproc(1), DocBook XSL Stylesheets, dblatex (or FOP) toolchain.
Plain text is produced by passing asciidoc(1) generated HTML through
lynx(1). The htmlhelp format option generates .hhp, .hhc and .html
files suitable for compilation to an HTML Help .chm file.


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.  This option may be specified more
  than once.

*--copy*::
  Copy distributed docbook-xsl CSS stylesheet admonition and
  navigation icons to their respective destinations. Applies to
  'xhtml', 'chunked', 'htmlhelp' formats. The default behavior is to
  suppress copying.

*-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 format: 'chunked', 'dvi', 'htmlhelp', 'manpage', 'pdf', 'ps',
  'tex', 'text' or '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 destination HTML files) containing admonition
  and navigation icons. Defaults to './images/icons/'.
  Applies to 'xhtml', 'chunked', 'htmlhelp' formats.

*-L, --no-xmllint*::
  Don't check asciidoc output with 'xmllint(1)'.

*-n, --dry-run*::
  Don't do anything just print what would have been done.

*-s, --skip-asciidoc*::
  Skip asciidoc execution. This is useful for converting DocBook XML
  files not derived from AsciiDoc sources. Ignored if '--format=text'.

*--stylesheet*='PATH'::
  A path (relative to destination HTML files) specifying the
  docbook-xsl CSS stylesheet file. Defaults to './docbook-xsl.css'.
  Applies to 'xhtml', '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.

*--fop*::
  Use FOP to generate PDFs.

*--fop-opts*='FOP_OPTS'::
  Additional fop options.  This option may be specified more than
  once. If this option is specified FOP is used to generate PDFs.

*--dblatex-opts*='DBLATEX_OPTS'::
  Additional dblatex options.  This option may be specified more than once.


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'; .hhp for
'htmlhelp'; .pdf for 'pdf'; .text for 'text'. 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.

Intermediate output files are written to the source 'FILE' directory
and are not automatically deleted.

Intermediate DocBook XML files generated by AsciiDoc are only
regenerated if out of date with respect to the AsciiDoc source 'FILE'.

In addition to generating HTML files the 'xhtml', 'chunked' and
'htmlhelp' formats copy the DocBook XSL stylesheet plus admonition and
navigation icons distributed with AsciiDoc to their respective
destination locations. Existing stylesheets and icons are only copied
if they are newer than the destination files or if the destination
files are missing.

The 'xhtml' format generates a single XHTML output page.  The
'chunked' format writes multiple per-section HTML pages to a chunked
directory in the destination directory. The chunked directory has the
same name as the source 'FILE' name plus a .chunked extension.


EXAMPLES
--------
`a2x -f pdf doc/source-highlight-filter.txt`::
  Generates doc/source-highlight-filter.pdf file.

`a2x -f chunked -D ../webpages guide.txt`::
  Creates chunked directory `../webpages/guide.chunked` containing
  chunked HTML files. Also copies `docbook-xsl.css` stylesheet to the
  `../webpages/guide.chunked` directory plus admonition and navigation
  icons to the `../webpages/guide.chunked/images/icons` directory.


REQUISITES
----------
This script runs under the bash(1) shell and requires the following
programs (which may or may not be prepackaged with your Linux
distribution):

Asciidoc::
  http://www.methods.co.nz/asciidoc/

xsltproc::
  http://xmlsoft.org/XSLT/

DocBook XSL Stylesheets::
  http://docbook.sourceforge.net/projects/xsl/

dblatex (for PDF, DVI, PostScript and LaTeX file generation)::
  http://dblatex.sourceforge.net/

FOP (alternative PDF file generation)::
  http://xmlgraphics.apache.org/fop/

w3m (text file generation)::
  http://w3m.sourceforge.net/index.en.html

Lynx (used for text file generation if `w3m(1)` not installed)::
  http://lynx.isc.org/

See also the latest README file.


BUGS
----
- The odt output format is undocumented and experimental.
- See also 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-2009 Stuart Rackham. Free use of this software is
granted under the terms of the GNU General Public License (GPL).

