A2X(1)                                                     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 xhtml,
           chunked, htmlhelp formats.

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

       Lynx (for text file generation)

           http://lynx.isc.org/
       See also the latest README file.


BUGS
       o   The odt output format is undocumented and
           experimental.

       o   See also 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-2008 Stuart Rackham. Free use of this
       software is granted under the terms of the GNU General
       Public License (GPL).


REFERENCES
        1. srackham@gmail.com
           mailto:srackham@gmail.com



                            07/04/2008                     A2X(1)