1A2X(1)                                                                  A2X(1)
2
3
4

NAME

6       a2x - A toolchain manager for AsciiDoc (converts Asciidoc text files to
7       other file formats)
8

SYNOPSIS

10       a2x [OPTIONS] SOURCE_FILE
11

DESCRIPTION

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

OPTIONS

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
24       --asciidoc-opts=ASCIIDOC_OPTS
25           Additional asciidoc(1) options. This option may be specified more
26           than once.
27
28       --conf-file=CONF_FILE
29           Load configuration file. See CONF FILES section.
30
31       -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
36       -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
41       -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
48       -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
53       -h, --help
54           Print command-line syntax and program options to stdout.
55
56       --icons
57           Use admonition or navigation icon images in output documents. The
58           default behavior is to use text in place of icons.
59
60       --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
65       -k, --keep-artifacts
66           Do not delete temporary build files.
67
68       --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
74       -L, --no-xmllint
75           Do not check asciidoc output with xmllint(1).
76
77       ---epubcheck
78           Check EPUB output with epubcheck(1).
79
80       -n, --dry-run
81           Do not do anything just print what would have been done.
82
83       -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
87       -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
92       --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
100       -v, --verbose
101           Print operational details to stderr. A second -v option applies the
102           verbose option to toolchain commands.
103
104       --version
105           Print program version to stdout.
106
107       --xsltproc-opts=XSLTPROC_OPTS
108           Additional xsltproc(1) options. This option may be specified more
109           than once.
110
111       --xsl-file=XSL_FILE
112           Override the built-in XSL stylesheet with the custom XSL stylesheet
113           XSL_FILE.
114
115       --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
120       --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
124       --dblatex-opts=DBLATEX_OPTS
125           Additional dblatex(1) options. This option may be specified more
126           than once.
127
128       --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
132       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
136           // a2x default options.
137           //    a2x: -dbook --epubcheck
138           // Suppress revision history in dblatex outputs.
139           //    a2x: --dblatex-opts "-P latex.output.revhistory=0"
140
141       ·   Options spanning multiple such comment lines will be concatenated.
142
143       ·   Zero or more white space characters can appear between the leading
144           // and a2x:.
145
146       ·   Command-line options take precedence over options set in the source
147           file.
148

OUTPUT FILES

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
154       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
161       Same named existing files are overwritten.
162
163       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

RESOURCES

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
174       a2x searches for resource files in the following locations in the
175       following order:
176
177        1. The SOURCE_FILE directory.
178
179        2. Resource directories specified by the --resource option (searched
180           recursively).
181
182        3. Resource directories specified by the --resource-manifest option
183           (searched recursively in the order they appear in the manifest
184           file).
185
186        4. The stock images and stylesheets directories in the asciidoc(1)
187           configuration files directories (searched recursively).
188
189        5. The destination directory.
190
191       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
195       There are two distinct mechanisms for specifying additional resources:
196
197        1. A resource directory which will be searched recursively for missing
198           resource files.
199
200        2. A resource file which will be copied to the output destination
201           directory.
202
203       Resources are specified with --resource option values which can be one
204       of the following formats:
205
206           <resource_dir>
207           <resource_file>[=<destination_file>]
208           .<ext>=<mimetype>
209
210       Where:
211
212       <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
218       <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
223       <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
230           chunked, htmlhelp
231               The chunked output directory.
232
233           epub
234               The archived OEBPS directory.
235
236           xhtml
237               The output DESTINATION_DIR.
238
239       .<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
246       Resource option examples:
247
248           --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

EXAMPLES

254       a2x -f pdf doc/source-highlight-filter.txt
255           Generates doc/source-highlight-filter.pdf file.
256
257       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
262       a2x -f manpage doc/asciidoc.1.txt
263           Generate doc/asciidoc.1 manpage.
264

REQUISITES

266       a2x uses the following programs:
267
268       ·   Asciidoc: https://asciidoc.org/
269
270       ·   xsltproc: (all formats except text): http://xmlsoft.org/XSLT/
271
272       ·   DocBook XSL Stylesheets (all formats except text):
273           https://github.com/docbook/xslt10-stylesheets
274
275       ·   dblatex (pdf, dvi, ps, tex formats):
276           http://dblatex.sourceforge.net/
277
278       ·   FOP (pdf format — alternative PDF file generator):
279           http://xmlgraphics.apache.org/fop/
280
281       ·   w3m (text format): http://w3m.sourceforge.net/index.en.html
282
283       ·   Lynx (text format — alternative text file generator):
284           https://invisible-island.net/lynx/
285
286       ·   epubcheck (epub format — EPUB file validator):
287           https://github.com/w3c/epubcheck
288
289       See also the latest README file.
290

CONF FILES

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
296        1. a2x.conf from the directory containing the a2x.py executable.
297
298        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
302        3. a2x.conf from the AsciiDoc $HOME/.asciidoc configuration directory.
303
304        4. The CONF_FILE specified in the --conf-file option.
305
306       Here are the default configuration file option values:
307
308           # Optional environment variable dictionary passed to
309           # executing programs. If set to None the existing
310           # environment is used.
311           ENV = None
312
313           # 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
331       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

BUGS

340       See the AsciiDoc distribution BUGS file.
341

AUTHOR

343       a2x was originally written by Stuart Rackham. Many people have
344       contributed to it.
345

RESOURCES

347       GitHub: https://github.com/asciidoc/asciidoc-py3/
348
349       Main web site: https://asciidoc.org/
350

SEE ALSO

352       asciidoc(1)
353

COPYING

355       Copyright (C) 2002-2013 Stuart Rackham.
356
357       Copyright (C) 2013-2020 AsciiDoc Contributors.
358
359       Free use of this software is granted under the terms of the MIT
360       license.
361
362
363
364                                  02/16/2021                            A2X(1)
Impressum