1A2X(1) A2X(1)
2
6 a2x - A toolchain manager for AsciiDoc (converts Asciidoc text files to
7 other file formats)
8
10 a2x [OPTIONS] SOURCE_FILE
11
13 A DocBook toolchain manager that translates an AsciiDoc text file
14 SOURCE_FILE to PDF, EPUB, DVI, PS, LaTeX, XHTML (single page or
15 chunked), man page, HTML Help or plain text formats using asciidoc(1)
16 and other applications (see REQUISITES section). SOURCE_FILE can also
17 be a DocBook file with an .xml extension.
18
20 -a, --attribute=ATTRIBUTE
21 Set asciidoc(1) attribute value (shortcut for --asciidoc-opts="-a
22 ATTRIBUTE" option). This option may be specified more than once.
23 --asciidoc-opts=ASCIIDOC_OPTS
25 Additional asciidoc(1) options. This option may be specified more
26 than once.
27 --conf-file=CONF_FILE
29 Load configuration file. See CONF FILES section.
30 -D, --destination-dir=DESTINATION_DIR
32 Output directory. Defaults to SOURCE_FILE directory. This option is
33 only applicable to HTML and manpage based output formats (chunked,
34 epub, htmlhelp, xhtml, manpage).
35 -d, --doctype=DOCTYPE
37 DocBook document type: article, manpage or book. Default document
38 type is article unless the format is manpage (in which case it
39 defaults to manpage).
40 -b, --backend=BACKEND
42 BACKEND is the name of an installed backend plugin. When this
43 option is specified a2x attempts to load a file name a2x-backend.py
44 from the BACKEND plugin directory. It then converts the SOURCE_FILE
45 to a BACKEND formatted output file using a global function defined
46 in a2x-backend.py called to_BACKEND.
47 -f, --format=FORMAT
49 Output formats: chunked, docbook, dvi, epub, htmlhelp, manpage, pdf
50 (default), ps, tex, text, xhtml. The AsciiDoc a2x-format attribute
51 value is set to FORMAT.
52 -h, --help
54 Print command-line syntax and program options to stdout.
55 --icons
57 Use admonition or navigation icon images in output documents. The
58 default behavior is to use text in place of icons.
59 --icons-dir=PATH
61 A path (relative to output files) containing admonition and
62 navigation icons. Defaults to images/icons. The --icons option is
63 implicit if this option is used.
64 -k, --keep-artifacts
66 Do not delete temporary build files.
67 --lynx
69 Use lynx(1) (actually: the text-based browser defined by the LYNX
70 config variable) when generating text formatted output. The default
71 behavior is to use w3m(1) (actually: the text-based browser defined
72 by the W3M config variable).
73 -L, --no-xmllint
75 Do not check asciidoc output with xmllint(1).
76 ---epubcheck
78 Check EPUB output with epubcheck(1).
79 -n, --dry-run
81 Do not do anything just print what would have been done.
82 -r, --resource=RESOURCE_SPEC
84 Specify a resource. This option may be specified more than once.
85 See the RESOURCES section for more details.
86 -m, --resource-manifest=FILE
88 FILE contains a list resources (one per line). Manifest FILE
89 entries are formatted just like --resource option arguments.
90 Environment variables and tilde home directories are allowed.
91 --stylesheet=STYLESHEET
93 A space delimited list of one or more CSS stylesheet file names
94 that are used to style HTML output generated by DocBook XSL
95 Stylesheets. Defaults to docbook-xsl.css. The stylesheets are
96 processed in list order. The stylesheets must reside in a valid
97 resource file location. Applies to HTML formats: xhtml, epub,
98 chunked, htmlhelp formats.
99 -v, --verbose
101 Print operational details to stderr. A second -v option applies the
102 verbose option to toolchain commands.
103 --version
105 Print program version to stdout.
106 --xsltproc-opts=XSLTPROC_OPTS
108 Additional xsltproc(1) options. This option may be specified more
109 than once.
110 --xsl-file=XSL_FILE
112 Override the built-in XSL stylesheet with the custom XSL stylesheet
113 XSL_FILE.
114 --fop
116 Use FOP to generate PDFs. The default behavior is to use
117 dblatex(1). The --fop option is implicit if the --fop-opts option
118 is used.
119 --fop-opts=FOP_OPTS
121 Additional fop(1) options. If this option is specified FOP is used
122 to generate PDFs. This option may be specified more than once.
123 --dblatex-opts=DBLATEX_OPTS
125 Additional dblatex(1) options. This option may be specified more
126 than once.
127 --backend-opts=BACKEND_OPTS
129 Options for the backend plugin specified by the --backend option.
130 This option may be specified more than once.
131 Options can also be set in the AsciiDoc source file. If SOURCE_FILE
133 contains a comment line beginning with // a2x: then the remainder of
134 the line will be treated as a2x command-line options. For example:
135 // a2x default options.
137 // a2x: -dbook --epubcheck
138 // Suppress revision history in dblatex outputs.
139 // a2x: --dblatex-opts "-P latex.output.revhistory=0"
140 · Options spanning multiple such comment lines will be concatenated.
142 · Zero or more white space characters can appear between the leading
144 // and a2x:.
145 · Command-line options take precedence over options set in the source
147 file.
148
150 Output files are written to the directory specified by the
151 --destination-dir option. If no --destination-dir option is set output
152 files are written to the SOURCE_FILE directory.
153 Output files have the same name as the SOURCE_FILE but with an
155 appropriate file name extension: .html for xhtml; .epub for epub; .hhp
156 for htmlhelp; .pdf for pdf; .text for text, .xml for docbook. By
157 convention manpages have no .man extension (man page section number
158 only). Chunked HTML directory names have a .chunked extension; chunked
159 HTML Help directory names have a .htmlhelp extension.
160 Same named existing files are overwritten.
162 In addition to generating HTML files the xhtml, epub, chunked and
164 htmlhelp formats ensure resource files are copied to their correct
165 destination directory locations.
166
168 Resources are files (typically CSS and images) that are required by
169 HTML based outputs (xhtml, epub, chunked, htmlhelp formats). a2x scans
170 the generated HTML files and builds a list of required CSS and image
171 files. Additional resource files can be specified explicitly using the
172 --resource option.
173 a2x searches for resource files in the following locations in the
175 following order:
176 1. The SOURCE_FILE directory.
178 2. Resource directories specified by the --resource option (searched
180 recursively).
181 3. Resource directories specified by the --resource-manifest option
183 (searched recursively in the order they appear in the manifest
184 file).
185 4. The stock images and stylesheets directories in the asciidoc(1)
187 configuration files directories (searched recursively).
188 5. The destination directory.
190 When a resource file is found it is copied to the correct relative
192 destination directory. Missing destination sub-directories are created
193 automatically.
194 There are two distinct mechanisms for specifying additional resources:
196 1. A resource directory which will be searched recursively for missing
198 resource files.
199 2. A resource file which will be copied to the output destination
201 directory.
202 Resources are specified with --resource option values which can be one
204 of the following formats:
205 <resource_dir>
207 <resource_file>[=<destination_file>]
208 .<ext>=<mimetype>
209 Where:
211 <resource_dir>
213 Specifies a directory (absolute or relative to the SOURCE_FILE)
214 which is searched recursively for missing resource files. To
215 eliminate ambiguity the <resource_dir> name should end with a
216 directory separator character.
217 <resource_file>
219 Specifies a resource file (absolute or relative to the SOURCE_FILE)
220 which will be copied to <destination_file>. If <destination_file>
221 is not specified then it is the same as the <resource_file>.
222 <destination_file>
224 Specifies the destination of the copied source file. The
225 <destination_file> path is relative to the destination directory
226 (absolute paths are not allowed). The location of the destination
227 directory depends on the output FORMAT (see the OUTPUT FILES
228 section for details):
229 chunked, htmlhelp
231 The chunked output directory.
232 epub
234 The archived OEBPS directory.
235 xhtml
237 The output DESTINATION_DIR.
238 .<ext>=<mimetype>
240 When adding resources to EPUB files the mimetype is inferred from
241 the <destination file> extension, if the mimetype cannot be guessed
242 an error occurs. The .<ext>=<mimetype> resource syntax can be used
243 to explicitly set mimetypes. <ext> is the file name extension,
244 <mimetype> is the corresponding MIME type.
245 Resource option examples:
247 --resource ../images/
249 --resource doc/README.txt=README.txt
250 --resource ~/images/tiger.png=images/tiger.png
251 --resource .ttf=application/x-font-ttf
252
254 a2x -f pdf doc/source-highlight-filter.txt
255 Generates doc/source-highlight-filter.pdf file.
256 a2x -f xhtml -D ../doc --icons -r ../images/ team.txt
258 Creates HTML file ../doc/team.html, uses admonition icons and
259 recursively searches the ../images/ directory for any missing
260 resources.
261 a2x -f manpage doc/asciidoc.1.txt
263 Generate doc/asciidoc.1 manpage.
264
266 a2x uses the following programs:
267 · Asciidoc: http://asciidoc.org/
269 · xsltproc: (all formats except text): http://xmlsoft.org/XSLT/
271 · DocBook XSL Stylesheets (all formats except text):
273 http://docbook.sourceforge.net/projects/xsl/
274 · dblatex (pdf, dvi, ps, tex formats):
276 http://dblatex.sourceforge.net/
277 · FOP (pdf format — alternative PDF file generator):
279 http://xmlgraphics.apache.org/fop/
280 · w3m (text format): http://w3m.sourceforge.net/index.en.html
282 · Lynx (text format — alternative text file generator):
284 http://lynx.isc.org/
285 · epubcheck (epub format — EPUB file validator):
287 http://code.google.com/p/epubcheck/
288 See also the latest README file.
290
292 A configuration file contains executable Python code that overrides the
293 global configuration parameters in a2x.py. Optional configuration files
294 are loaded in the following order:
295 1. a2x.conf from the directory containing the a2x.py executable.
297 2. a2x.conf from the AsciiDoc global configuration directory. Skip
299 this step if we are executing a locally installed (non system wide)
300 copy.
301 3. a2x.conf from the AsciiDoc $HOME/.asciidoc configuration directory.
303 4. The CONF_FILE specified in the --conf-file option.
305 Here are the default configuration file option values:
307 # Optional environment variable dictionary passed to
309 # executing programs. If set to None the existing
310 # environment is used.
311 ENV = None
312 # External executables.
314 ASCIIDOC = 'asciidoc'
315 XSLTPROC = 'xsltproc'
316 DBLATEX = 'dblatex' # pdf generation.
317 FOP = 'fop' # pdf generation (--fop option).
318 W3M = 'w3m' # primary text file generator.
319 LYNX = 'lynx' # alternate text file generator.
320 XMLLINT = 'xmllint' # Set to '' to disable.
321 EPUBCHECK = 'epubcheck' # Set to '' to disable.
322 # External executable default options.
323 ASCIIDOC_OPTS = ''
324 BACKEND_OPTS = ''
325 DBLATEX_OPTS = ''
326 FOP_OPTS = ''
327 LYNX_OPTS = '-dump'
328 W3M_OPTS = '-dump -cols 70 -T text/html -no-graph'
329 XSLTPROC_OPTS = ''
330 Note, that it is possible to redefine W3M and LYNX to use different
332 text-based browsers, e.g. links: http://links.twibright.com/ or elinks:
333 http://elinks.or.cz/. LYNX_OPTS and W3M_OPTS can be used to pass
334 options to the selected browser. If these are defined they override the
335 respective defaults listed above (so don’t forget to include the -dump
336 option in your definition: this is mandatory at least with w3m, lynx,
337 links, and elinks in order to send the formatted text to stdout).
338
340 See the AsciiDoc distribution BUGS file.
341
343 a2x was originally written by Stuart Rackham. Many people have
344 contributed to it.
345
347 SourceForge: http://sourceforge.net/projects/asciidoc/
348 Main web site: http://asciidoc.org/
350
352 asciidoc(1)
353
355 Copyright (C) 2002-2011 Stuart Rackham. Free use of this software is
356 granted under the terms of the MIT license.
357 05/13/2019 A2X(1)