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.
33 -d, --doctype=DOCTYPE
35 DocBook document type: article, manpage or book. Default document
36 type is article unless the format is manpage (in which case it
37 defaults to manpage).
38 -b, --backend=BACKEND
40 BACKEND is the name of an installed backend plugin. When this
42 option is specified a2x attempts load a file name a2x-backend.py
43 from the BACKEND plugin directory It then converts the SOURCE_FILE
44 to a BACKEND formatted output file using a global function defined
45 in a2x-backend.py called to_BACKEND.
46 -f, --format=FORMAT
48 Output formats: chunked, docbook, dvi, epub, htmlhelp, manpage, pdf
49 (default), ps, tex, text, xhtml. The AsciiDoc a2x-format attribute
50 value is set to FORMAT.
51 -h, --help
53 Print command-line syntax and program options to stdout.
54 --icons
56 Use admonition or navigation icon images in output documents. The
57 default behavior is to use text in place of icons.
58 --icons-dir=PATH
60 A path (relative to output files) containing admonition and
61 navigation icons. Defaults to images/icons. The --icons option is
62 implicit if this option is used.
63 -k, --keep-artifacts
65 Do not delete temporary build files.
66 --lynx
68 Use lynx(1) to generate text formatted output. The default behavior
69 is to use w3m(1).
70 -L, --no-xmllint
72 Do not check asciidoc output with xmllint(1).
73 ---epubcheck
75 Check EPUB output with epubcheck(1).
76 -n, --dry-run
78 Do not do anything just print what would have been done.
79 -r, --resource=RESOURCE_SPEC
81 Specify a resource. This option may be specified more than once.
82 See the RESOURCES section for more details.
83 -m, --resource-manifest=FILE
85 FILE contains a list resources (one per line). Manifest FILE
87 entries are formatted just like --resource option arguments.
88 Environment variables and tilde home directories are allowed.
89 --stylesheet=STYLESHEET
91 A space delimited list of one or more CSS stylesheet file names
92 that are used to style HTML output generated by DocBook XSL
93 Stylesheets. Defaults to docbook-xsl.css. The stylesheets are
94 processed in list order. The stylesheets must reside in a valid
95 resource file location. Applies to HTML formats: xhtml, epub,
96 chunked, htmlhelp formats.
97 -v, --verbose
99 Print operational details to stderr. A second -v option applies the
100 verbose option to toolchain commands.
101 --version
103 Print program version to stdout.
104 --xsltproc-opts=XSLTPROC_OPTS
106 Additional xsltproc(1) options. This option may be specified more
107 than once.
108 --xsl-file=XSL_FILE
110 Override the built-in XSL stylesheet with the custom XSL stylesheet
111 XSL_FILE.
112 --fop
114 Use FOP to generate PDFs. The default behavior is to use
115 dblatex(1). The --fop option is implicit if this option is used.
116 --fop-opts=FOP_OPTS
118 Additional fop(1) options. If this option is specified FOP is used
119 to generate PDFs. This option may be specified more than once.
120 --dblatex-opts=DBLATEX_OPTS
122 Additional dblatex(1) options. This option may be specified more
123 than once.
124 --backend-opts=BACKEND_OPTS
126 Options for the backend plugin specified by the --backend option.
127 This option may be specified more than once.
128 Options can also be set in the AsciiDoc source file. If SOURCE_FILE
130 contains a comment line beginning with // a2x: then the remainder of
131 the line will be treated as a2x command-line options. For example:
132 // a2x default options.
134 // a2x: -dbook --epubcheck
135 // Suppress revision history in dblatex outputs.
136 // a2x: --dblatex-opts "-P latex.output.revhistory=0"
137 · Options spanning multiple such comment lines will be concatenated.
139 · Zero or more white space characters can appear between the leading
141 // and a2x:.
142 · Command-line options take precedence over options set in the source
144 file.
145
147 Output files are written to the directory specified by the
148 --destination-dir option. If no --destination-dir option is set output
149 files are written to the SOURCE_FILE directory.
150 Output files have the same name as the SOURCE_FILE but with an
152 appropriate file name extension: .html for xhtml; .epub for epub; .hhp
153 for htmlhelp; .pdf for pdf; .text for text, .xml for docbook. By
154 convention manpages have no .man extension (man page section number
155 only). Chunked HTML directory names have a .chunked extension; chunked
156 HTML Help directory names have a .htmlhelp extension.
157 Same named existing files are overwritten.
159 In addition to generating HTML files the xhtml, epub, chunked and
161 htmlhelp formats ensure resource files are copied to their correct
162 destination directory locations.
163
165 Resources are files (typically CSS and images) that are required by
166 HTML based outputs (xhtml, epub, chunked, htmlhelp formats). a2x scans
167 the generated HTML files and builds a list of required CSS and image
168 files. Additional resource files can be specified explicitly using the
169 --resource option.
170 a2x searches for resource files in the following locations in the
172 following order:
173 1. The SOURCE_FILE directory.
175 2. Resource directories specified by the --resource option (searched
177 recursively).
178 3. Resource directories specified by the --resource-manifest option
180 (searched recursively in the order they appear in the manifest
181 file).
182 4. The stock images and stylesheets directories in the asciidoc(1)
184 configuration files directories (searched recursively).
185 5. The destination directory.
187 When a resource file is found it is copied to the correct relative
189 destination directory. Missing destination sub-directories are created
190 automatically.
191 There are two distinct mechanisms for specifying additional resources:
193 1. A resource directory which will be searched recursively for missing
195 resource files.
196 2. A resource file which will be copied to the output destination
198 directory.
199 Resources are specified with --resource option values which can be one
201 of the following formats:
202 <resource_dir>
204 <resource_file>[=<destination_file>]
205 .<ext>=<mimetype>
206 Where:
208 <resource_dir>
210 Specifies a directory (absolute or relative to the SOURCE_FILE)
211 which is searched recursively for missing resource files. To
212 eliminate ambiguity the <resource_dir> name should end with a
213 directory separator character.
214 <resource_file>
216 Specifies a resource file (absolute or relative to the SOURCE_FILE)
217 which will be copied to <destination_file>. If <destination_file>
218 is not specified then it is the same as the <resource_file>.
219 <destination_file>
221 Specifies the destination of the copied source file. The
222 <destination_file> path is relative to the destination directory
223 (absolute paths are not allowed). The location of the destination
224 directory depends on the output FORMAT (see the OUTPUT FILES
225 section for details):
226 chunked, htmlhelp
228 The chunked output directory.
229 epub
231 The archived OEBPS directory.
232 xhtml
234 The output DESTINATION_DIR.
235 .<ext>=<mimetype>
237 When adding resources to EPUB files the mimetype is inferred from
238 the <destination file> extension, if the mimetype cannot be guessed
239 an error occurs. The .<ext>=<mimetype> resource syntax can be used
240 to explicitly set mimetypes. <ext> is the file name extension,
241 <mimetype> is the corresponding MIME type.
242 Resource option examples:
244 --resource ../images/
246 --resource doc/README.txt=README.txt
247 --resource ~/images/tiger.png=images/tiger.png
248 --resource .ttf=application/x-font-ttf
249
251 a2x -f pdf doc/source-highlight-filter.txt
252 Generates doc/source-highlight-filter.pdf file.
253 a2x -f xhtml -D ../doc --icons -r ../images/ team.txt
255 Creates HTML file ../doc/team.html, uses admonition icons and
256 recursively searches the ../images/ directory for any missing
257 resources.
258 a2x -f manpage doc/asciidoc.1.txt
260 Generate doc/asciidoc.1 manpage.
261
263 a2x uses the following programs:
264 · Asciidoc: http://www.methods.co.nz/asciidoc/
266 · xsltproc: (all formats except text): http://xmlsoft.org/XSLT/
268 · DocBook XSL Stylesheets (all formats except text):
270 http://docbook.sourceforge.net/projects/xsl/
271 · dblatex (pdf, dvi, ps, tex formats):
273 http://dblatex.sourceforge.net/
274 · FOP (pdf format — alternative PDF file generator):
276 http://xmlgraphics.apache.org/fop/
277 · w3m (text format): http://w3m.sourceforge.net/index.en.html
279 · Lynx (text format — alternative text file generator):
281 http://lynx.isc.org/
282 · epubcheck (epub format — EPUB file validator):
284 http://code.google.com/p/epubcheck/
285 See also the latest README file.
287
289 A configuration file contains executable Python code that overrides the
290 global configuration parameters in a2x.py. Optional configuration files
291 are loaded in the following order:
292 1. a2x.conf from the directory containing the a2x.py executable.
294 2. a2x.conf from the AsciiDoc global configuration directory. Skip
296 this step if we are executing a locally installed (non system wide)
297 copy.
298 3. a2x.conf from the AsciiDoc $HOME/.asciidoc configuration
300 directory.
301 4. The CONF_FILE specified in the --conf-file option.
303 Here are the default configuration file option values:
305 # Optional environment variable dictionary passed to
307 # executing programs. If set to None the existing
308 # environment is used.
309 ENV = None
310 # External executables.
312 ASCIIDOC = 'asciidoc'
313 XSLTPROC = 'xsltproc'
314 DBLATEX = 'dblatex' # pdf generation.
315 FOP = 'fop' # pdf generation (--fop option).
316 W3M = 'w3m' # text generation.
317 LYNX = 'lynx' # text generation (if no w3m).
318 XMLLINT = 'xmllint' # Set to '' to disable.
319 EPUBCHECK = 'epubcheck' # Set to '' to disable.
320 # External executable default options.
321 ASCIIDOC_OPTS = ''
322 DBLATEX_OPTS = ''
323 FOP_OPTS = ''
324 XSLTPROC_OPTS = ''
325
327 See the AsciiDoc distribution BUGS file.
328
330 a2x was originally written by Stuart Rackham. Many people have
331 contributed to it.
332
334 SourceForge: http://sourceforge.net/projects/asciidoc/
335 Main web site: http://www.methods.co.nz/asciidoc/
337
339 Copyright (C) 2002-2011 Stuart Rackham. Free use of this software is
340 granted under the terms of the MIT license.
341 8.6.8 17 July 2012 A2X(1)