1A2X(1) A2X(1)
2
6 a2x - convert Asciidoc text file to PDF, XHTML, HTML Help, manpage or
7 plain text
8
10 a2x [OPTIONS] FILE
11
14 A DocBook toolchain wrapper script that translates an AsciiDoc text
15 file FILE to PDF, DVI, PS, LaTeX, XHTML (single page or chunked), man
16 page, HTML Help or plain text formats. PDF, XHTML, man page and HTML
17 Help formats are are generated using the asciidoc(1), xsltproc(1),
18 DocBook XSL Stylesheets, dblatex (or FOP) toolchain. Plain text is
19 produced by passing asciidoc(1) generated HTML through lynx(1). The
20 htmlhelp format option generates .hhp, .hhc and .html files suitable
21 for compilation to an HTML Help .chm file.
22
25 -a, --attribute=ATTRIBUTE
26 Set asciidoc(1) attribute value (shortcut for --asciidoc-opts="-a
27 ATTRIBUTE" option). This option may be specified more than once.
28 --asciidoc-opts=ASCIIDOC_OPTS
30 Additional asciidoc(1) options. This option may be specified more
31 than once.
32 --copy
34 Copy distributed docbook-xsl CSS stylesheet admonition and
35 navigation icons to their respective destinations. Applies to
36 xhtml, chunked, htmlhelp formats. The default behavior is to
37 suppress copying.
38 -D, --destination-dir=PATH
40 Output directory. Defaults to source FILE directory.
41 -d, --doctype=DOCTYPE
43 DocBook document type: article, manpage or book. Default document
44 type is article unless the format is manpage (in which case it
45 defaults to manpage).
46 -f, --format=FORMAT
48 Output format: chunked, dvi, htmlhelp, manpage, pdf, ps, tex, text
49 or xhtml.
50 -h, --help
52 Print command-line syntax and program options to stdout.
53 --icons
55 Use admonition or navigation icon images in output documents. The
56 default behavior is to use text in place of icons.
57 --icons-dir=PATH
59 A path (relative to destination HTML files) containing admonition
60 and navigation icons. Defaults to ./images/icons/. Applies to
61 xhtml, chunked, htmlhelp formats.
62 -L, --no-xmllint
64 Don’t check asciidoc output with xmllint(1).
65 -n, --dry-run
67 Don’t do anything just print what would have been done.
68 -s, --skip-asciidoc
70 Skip asciidoc execution. This is useful for converting DocBook XML
71 files not derived from AsciiDoc sources. Ignored if --format=text.
72 --stylesheet=PATH
74 A path (relative to destination HTML files) specifying the
75 docbook-xsl CSS stylesheet file. Defaults to ./docbook-xsl.css.
76 Applies to xhtml, chunked, htmlhelp formats.
77 -v, --verbose
79 Print operational details to stderr. A second -v option applies the
80 verbose option to toolchain commands.
81 --unsafe
83 Use the asciidoc(1) --unsafe option.
84 --version
86 Print program version to stdout.
87 --xsltproc-opts=XSLTPROC_OPTS
89 Additional xsltproc(1) options. This option may be specified more
90 than once.
91 --fop
93 Use FOP to generate PDFs.
94 --fop-opts=FOP_OPTS
96 Additional fop options. This option may be specified more than
97 once. If this option is specified FOP is used to generate PDFs.
98 --dblatex-opts=DBLATEX_OPTS
100 Additional dblatex options. This option may be specified more than
101 once.
102
104 Output files are written to the directory specified by the
105 --destination-dir option. If no --destination-dir option is set output
106 files are written to the source FILE directory.
107 Output files have the same name as the source FILE but with an
109 appropriate file name extension: .html for xhtml; .hhp for htmlhelp;
110 .pdf for pdf; .text for text. By convention manpages have no .man
111 extension (man page section number only). Chunked HTML directory names
112 have a .chunked extension; chunked HTML Help directory names have a
113 .htmlhelp extension.
114 Same named existing files are overwritten.
116 Intermediate output files are written to the source FILE directory and
118 are not automatically deleted.
119 Intermediate DocBook XML files generated by AsciiDoc are only
121 regenerated if out of date with respect to the AsciiDoc source FILE.
122 In addition to generating HTML files the xhtml, chunked and htmlhelp
124 formats copy the DocBook XSL stylesheet plus admonition and navigation
125 icons distributed with AsciiDoc to their respective destination
126 locations. Existing stylesheets and icons are only copied if they are
127 newer than the destination files or if the destination files are
128 missing.
129 The xhtml format generates a single XHTML output page. The chunked
131 format writes multiple per-section HTML pages to a chunked directory in
132 the destination directory. The chunked directory has the same name as
133 the source FILE name plus a .chunked extension.
134
137 a2x -f pdf doc/source-highlight-filter.txt
138 Generates doc/source-highlight-filter.pdf file.
139 a2x -f chunked -D ../webpages guide.txt
141 Creates chunked directory containing chunked HTML files. Also
142 copies docbook-xsl.css stylesheet to the directory plus admonition
143 and navigation icons to the directory.
144
146 This script runs under the bash(1) shell and requires the following
147 programs (which may or may not be prepackaged with your Linux
148 distribution):
149 Asciidoc
151 http://www.methods.co.nz/asciidoc/
153 xsltproc
155 http://xmlsoft.org/XSLT/
157 DocBook XSL Stylesheets
159 http://docbook.sourceforge.net/projects/xsl/
161 dblatex (for PDF, DVI, PostScript and LaTeX file generation)
163 http://dblatex.sourceforge.net/
165 FOP (alternative PDF file generation)
167 http://xmlgraphics.apache.org/fop/
169 w3m (text file generation)
171 http://w3m.sourceforge.net/index.en.html
173 Lynx (used for text file generation if w3m(1) not installed)
175 http://lynx.isc.org/
177 See also the latest README file.
178
181 · The odt output format is undocumented and experimental.
182 · See also the AsciiDoc distribution BUGS file.
184
186 Written by Stuart Rackham, <srackham@gmail.com>
187
190 SourceForge: http://sourceforge.net/projects/asciidoc/
191 Main web site: http://www.methods.co.nz/asciidoc/
193
196 Copyright (C) 2002-2009 Stuart Rackham. Free use of this software is
197 granted under the terms of the GNU General Public License (GPL).
198 05/26/2009 A2X(1)