1A2X(1) A2X(1)
2
6 a2x - convert Asciidoc text file to PDF, XHTML, HTML Help, ODF, manpage
7 or plain text
8
10 a2x [OPTIONS] FILE
11
13 A DocBook toolchain wrapper script that translates an AsciiDoc text
14 file FILE to PDF, XHTML (single page or chunked), man page, HTML Help
15 or plain text formats. PDF, XHTML, man page and HTML Help formats are
16 are generated using the asciidoc(1)/xsltproc(1)/DocBook XSL Stylesheets
17 toolchain. Plain text is produced by passing asciidoc(1) generated HTML
18 through lynx(1). The htmlhelp format option generates .hhp, .hhc and
19 .html files suitable for compilation to an HTML Help .chm file. Open
20 Document Text files are generated using docbook2odf(1).
21
23 --asciidoc-opts=ASCIIDOC_OPTS
24 Additional asciidoc(1) options.
25 --copy Copy distributed docbook-xsl CSS stylesheet and the copying of
27 distributed admonition and navigation icons to their respective
28 destinations. Applies to xhtml, chunked, htmlhelp formats. The
29 default behavior is to suppress copying.
30 -D, --destination-dir=PATH
32 Output directory. Defaults to source FILE directory.
33 -d, --doctype=DOCTYPE
35 DocBook document type: article, manpage or book. Default
36 document type is article.
37 -f, --format=FORMAT
39 Output format: chunked, htmlhelp, manpage, odt, pdf, text or
40 xhtml.
41 -h, --help
43 Print command-line syntax and program options to stdout.
44 --icons
46 Use admonition or navigation icon images in output documents.
47 The default behavior is to use text in place of icons.
48 --icons-dir=PATH
50 A path (relative to destination HTML files) containing
51 admonition and navigation icons. Defaults to ./images/icons/.
52 Applies to xhtml, chunked, htmlhelp formats.
53 -n, --dry-run
55 Don't do anything just print what would have been done.
56 --stylesheet=PATH
58 A path (relative to destination HTML files) specifying the
59 docbook-xsl CSS stylesheet file. Defaults to ./docbook-xsl.css.
60 Applies to xhtml, chunked, htmlhelp formats.
61 -v, --verbose
63 Print operational details to stderr. A second -v option applies
64 the verbose option to toolchain commands.
65 --version
67 Print program version to stdout.
68 --xsltproc-opts=XSLTPROC_OPTS
70 Additional xsltproc(1) options.
71
73 Output files are written to the directory specified by the
74 --destination-dir option. If no --destination-dir option is set output
75 files are written to the source FILE directory.
76 Output files have the same name as the source FILE but with an
78 appropriate file name extension: .html for xhtml; .hhp for htmlhelp;
79 .pdf for pdf; .text for text. By convention manpages have no .man
80 extension (man page section number only). Chunked HTML directory names
81 have a .chunked extension; chunked HTML Help directory names have a
82 .htmlhelp extension.
83 Same named existing files are overwritten.
85 Intermediate output files are written to the source FILE directory and
87 are not automatically deleted.
88 Intermediate DocBook XML files generated by AsciiDoc are only
90 regenerated if out of date with respect to the AsciiDoc source FILE.
91 In addition to generating HTML files the xhtml, chunked and htmlhelp
93 formats copy the DocBook XSL stylesheet plus admonition and navigation
94 icons distributed with AsciiDoc to their respective destination
95 locations. Existing stylesheets and icons are only copied if they are
96 newer than the destination files or if the destination files are
97 missing.
98 The xhtml format generates a single XHTML output page. The chunked
100 format writes multiple per-section HTML pages to a chunked directory in
101 the destination directory. The chunked directory has the same name as
102 the source FILE name plus a .chunked extension.
103
105 a2x -f pdf --icons doc/quickstart.txt
106 Generates doc/quickstart.pdf with admonition icons.
107 a2x -f chunked -D ../webpages guide.txt
109 Creates chunked directory containing chunked HTML files. Also
110 copies docbook-xsl.css stylesheet to the directory plus
111 admonition and navigation icons to the directory.
112
114 This script runs under the bash(1) shell and requires the following
115 programs (which may or may not be prepackaged with your Linux
116 distribution):
117 Asciidoc
119 http://www.methods.co.nz/asciidoc/
120 xsltproc
122 http://xmlsoft.org/XSLT/
123 DocBook XSL Stylesheets
125 http://docbook.sourceforge.net/projects/xsl/
126 FOP (for PDF file generation)
128 http://xmlgraphics.apache.org/fop/
129 Lynx (for text file generation)
131 http://lynx.isc.org/
132 docbook2odf (for Open Document file generation)
134 http://open.comsultia.com/docbook2odf/
135 This version of a2x(1) has been tested on Ubuntu Linux 5.0.4 with the
137 following toolchain components:
138 · bash 3.00.16.
140 · DocBook XSL Stylesheets 1.69.1 (with AsciiDoc drivers and patches).
142 · xsltproc (libxml 20617, libxslt 10112 and libexslt 810).
144 · FOP 0.20.5.
146 · lynx 2.8.5rel.1.
148 · docbook2odf 0.163.
150
152 · As of version 0.163 docbook2odf(1) only processes a subset of
153 DocBook, skipping unimplemented elements. In particular only book
154 type root elements are recognised so you may need to use the
155 a2x(1)--doctype=book option.
156 · See also the AsciiDoc distribution BUGS file.
158
160 Written by Stuart Rackham, <srackham@methods.co.nz>
161
163 SourceForge: http://sourceforge.net/projects/asciidoc/
164 Main web site: http://www.methods.co.nz/asciidoc/
166
168 Copyright (C) 2002-2006 Stuart Rackham. Free use of this software is
169 granted under the terms of the GNU General Public License (GPL).
170 10/21/2006 A2X(1)