A2X(1)A2X(1)NAMEa2x - convert Asciidoc text file to PDF, XHTML, HTML Help, manpage or
plain text
SYNOPSISa2x [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-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 and the copying of
distributed 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, htmlhelp, manpage, pdf, 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.
-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.
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.
EXAMPLESa2x-f pdf --icons doc/quickstart.txt
Generates doc/quickstart.pdf with admonition icons.
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.72.0 (with AsciiDoc drivers and patches).
· xsltproc (libxml 20627, libxslt 10120 and libexslt 813).
· FOP 0.20.5.
· lynx 2.8.5rel.1.
BUGS
· The odt output format is undocumented and experimental.
· See also the AsciiDoc distribution BUGS file.
AUTHOR
Written by Stuart Rackham, <srackham@methods.co.nz>
RESOURCES
SourceForge: http://sourceforge.net/projects/asciidoc/
Main web site: http://www.methods.co.nz/asciidoc/
COPYING
Copyright (C) 2002-2007 Stuart Rackham. Free use of this software is
granted under the terms of the GNU General Public License (GPL).
REFERENCES
1. srackham@methods.co.nz
mailto:srackham@methods.co.nz
11/10/2007 A2X(1)
