A2X(1)
======
Stuart Rackham <srackham@methods.co.nz>


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, 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 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
-------
--asciidoc-opts=ASCIIDOC_OPTS::
  Additional asciidoc(1) options.

-d, --destination-dir=PATH::
  Output directory. Defaults to source FILE directory.

-f, --format=FORMAT::
  Output format: chunked, htmlhelp, manpage, pdf, text or xhtml.

-h, --help::
  Print command-line syntax and program options to stdout.

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

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

--no-copy::
  Suppress copying of distributed docbook-xsl stylesheet and the
  copying of distributed admonition and navigation icons to their
  respective destinations. The default behavior is to copy.  Applies
  to xhtml, chunked, htmlhelp formats.

--no-icons::
  Don't use admonition or navigation icon images in output documents.
  This option also suppresses copying of admonition and navigation
  icons (see also --no-copy).
  The default behavior is to use icons (although they may or may not
  be supported by the output format).

--stylesheet=PATH::
  A path (relative to destination HTML files) specifying the 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.


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/quickstart.txt::
  Generates doc/quickstart.pdf.

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/

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

Lynx (for text file generation)::
  http://lynx.isc.org/

This version of a2x(1) has been tested on Ubuntu Linux 5.0.4 with the
following toolchain components:

- bash 3.00.16.
- DocBook XSL Stylesheets 1.69.1 (with AsciiDoc drivers and patches).
- xsltproc (libxml 20617, libxslt 10112 and libexslt 810).
- FOP 0.20.5.
- lynx 2.8.5rel.1.


BUGS
----
- Does not work with Bash versions prior to version 3.
- See also the AsciiDoc distribution BUGS file.


AUTHOR
------
Written by Stuart Rackham, <mailto:srackham@methods.co.nz[]>


RESOURCES
---------
SourceForge: http://sourceforge.net/projects/asciidoc/[]

Main web site: http://www.methods.co.nz/asciidoc/[]


COPYING
-------
Copyright \(C) 2002-2006 Stuart Rackham. Free use of this software is
granted under the terms of the GNU General Public License (GPL).

