.\" ** You probably do not want to edit this file directly **
.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
.\" Instead of manually editing it, you probably should edit the DocBook XML
.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
.TH "A2X" "1" "10/21/2006" "" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
a2x \- convert Asciidoc text file to PDF, XHTML, HTML Help, ODF, manpage or plain text
.SH "SYNOPSIS"
\fIa2x\fR [OPTIONS] FILE
.SH "DESCRIPTION"
A DocBook toolchain wrapper script that translates an \fIAsciiDoc\fR text file \fIFILE\fR 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. Open Document Text files are generated using docbook2odf(1).
.SH "OPTIONS"
.TP
\-\-asciidoc\-opts=ASCIIDOC_OPTS
Additional
asciidoc(1)
options.
.TP
\-\-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.
.TP
\-D, \-\-destination\-dir=PATH
Output directory. Defaults to source FILE directory.
.TP
\-d, \-\-doctype=DOCTYPE
DocBook document type:
\fIarticle\fR,
\fImanpage\fR
or
\fIbook\fR. Default document type is
\fIarticle\fR.
.TP
\-f, \-\-format=FORMAT
Output format: chunked, htmlhelp, manpage, odt, pdf, text or xhtml.
.TP
\-h, \-\-help
Print command\-line syntax and program options to stdout.
.TP
\-\-icons
Use admonition or navigation icon images in output documents. The default behavior is to use text in place of icons.
.TP
\-\-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.
.TP
\-n, \-\-dry\-run
Don't do anything just print what would have been done.
.TP
\-\-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.
.TP
\-v, \-\-verbose
Print operational details to stderr. A second \-v option applies the verbose option to toolchain commands.
.TP
\-\-version
Print program version to stdout.
.TP
\-\-xsltproc\-opts=XSLTPROC_OPTS
Additional xsltproc(1) options.
.SH "OUTPUT FILES"
Output files are written to the directory specified by the \fI\-\-destination\-dir\fR option. If no \fI\-\-destination\-dir\fR option is set output files are written to the source FILE directory.
.sp
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.
.sp
Same named existing files are overwritten.
.sp
Intermediate output files are written to the source FILE directory and are not automatically deleted.
.sp
Intermediate DocBook XML files generated by \fIAsciiDoc\fR are only regenerated if out of date with respect to the \fIAsciiDoc\fR source FILE.
.sp
In addition to generating HTML files the xhtml, chunked and htmlhelp formats copy the DocBook XSL stylesheet plus admonition and navigation icons distributed with \fIAsciiDoc\fR 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.
.sp
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.
.SH "EXAMPLES"
.TP
a2x \-f pdf \-\-icons doc/quickstart.txt
Generates doc/quickstart.pdf with admonition icons.
.TP
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.
.SH "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):
.TP
Asciidoc
http://www.methods.co.nz/asciidoc/
.TP
xsltproc
http://xmlsoft.org/XSLT/
.TP
DocBook XSL Stylesheets
http://docbook.sourceforge.net/projects/xsl/
.TP
FOP (for PDF file generation)
http://xmlgraphics.apache.org/fop/
.TP
Lynx (for text file generation)
http://lynx.isc.org/
.TP
docbook2odf (for Open Document file generation)
http://open.comsultia.com/docbook2odf/
.PP
This version of a2x(1) has been tested on Ubuntu Linux 5.0.4 with the following toolchain components:
.TP 3
\(bu
bash 3.00.16.
.TP
\(bu
DocBook XSL Stylesheets 1.69.1 (with
\fIAsciiDoc\fR
drivers and patches).
.TP
\(bu
xsltproc (libxml 20617, libxslt 10112 and libexslt 810).
.TP
\(bu
FOP 0.20.5.
.TP
\(bu
lynx 2.8.5rel.1.
.TP
\(bu
docbook2odf 0.163.
.SH "BUGS"
.TP 3
\(bu
As of version 0.163 docbook2odf(1) only processes a subset of DocBook, skipping unimplemented elements. In particular only book type root elements are recognised so you may need to use the
a2x(1)\-\-doctype=book
option.
.TP
\(bu
See also the
\fIAsciiDoc\fR
distribution BUGS file.
.SH "AUTHOR"
Written by Stuart Rackham, <srackham@methods.co.nz>
.SH "RESOURCES"
SourceForge: http://sourceforge.net/projects/asciidoc/
.sp
Main web site: http://www.methods.co.nz/asciidoc/
.SH "COPYING"
Copyright (C) 2002\-2006 Stuart Rackham. Free use of this software is granted under the terms of the GNU General Public License (GPL).
.sp