File: a2x.1.txt

package info (click to toggle)
asciidoc 8.6.9-5
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 3,684 kB
  • sloc: python: 6,972; sh: 369; makefile: 144; xml: 77
file content (365 lines) | stat: -rw-r--r-- 11,821 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
A2X(1)
======
:doctype: manpage


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


SYNOPSIS
--------
*a2x* ['OPTIONS'] 'SOURCE_FILE'


DESCRIPTION
-----------
A DocBook toolchain manager that translates an AsciiDoc text file
'SOURCE_FILE' to PDF, EPUB, DVI, PS, LaTeX, XHTML (single page or
chunked), man page, HTML Help or plain text formats using
'asciidoc(1)' and other applications (see <<X1,REQUISITES section>>).
'SOURCE_FILE' can also be a DocBook file with an .xml extension.


OPTIONS
-------
*-a, --attribute*='ATTRIBUTE'::
  Set asciidoc(1) attribute value (shortcut for *--asciidoc-opts*='"-a
  ATTRIBUTE"' option).
  This option may be specified more than once.

*--asciidoc-opts*='ASCIIDOC_OPTS'::
  Additional 'asciidoc(1)' options.
  This option may be specified more than once.

*--conf-file*='CONF_FILE'::
  Load configuration file. See <<X2,CONF FILES section>>.

*-D, --destination-dir*='DESTINATION_DIR'::
  Output directory. Defaults to 'SOURCE_FILE' directory. This option
  is only applicable to HTML based output formats ('chunked', 'epub',
  'htmlhelp', 'xhtml').

*-d, --doctype*='DOCTYPE'::
  DocBook document type: 'article', 'manpage' or 'book'.  Default
  document type is 'article' unless the format is 'manpage' (in which
  case it defaults to 'manpage').

*-b, --backend*='BACKEND'::
  'BACKEND' is the name of an installed backend plugin. When this
  option is specified 'a2x' attempts load a file name 'a2x-backend.py'
  from the 'BACKEND' plugin directory It then converts the
  'SOURCE_FILE' to a 'BACKEND' formatted output file using a global
  function defined in 'a2x-backend.py' called 'to_BACKEND'.

*-f, --format*='FORMAT'::
  Output formats: 'chunked', 'docbook', 'dvi', 'epub', 'htmlhelp',
  'manpage', 'pdf' (default), 'ps', 'tex', 'text', 'xhtml'.
  The AsciiDoc 'a2x-format' attribute value is set to 'FORMAT'.

*-h, --help*::
  Print command-line syntax and program options to stdout.

*--icons*::
  Use admonition or navigation icon images in output documents. The
  default behavior is to use text in place of icons.

*--icons-dir*='PATH'::
  A path (relative to output files) containing admonition
  and navigation icons. Defaults to `images/icons`.
  The '--icons' option is implicit if this option is used.

*-k, --keep-artifacts*::
  Do not delete temporary build files.

*--lynx*::
  Use 'lynx(1)' to generate text formatted output. The default
  behavior is to use 'w3m(1)'.

*-L, --no-xmllint*::
  Do not check asciidoc output with 'xmllint(1)'.

*---epubcheck*::
  Check EPUB output with 'epubcheck(1)'.

*-n, --dry-run*::
  Do not do anything just print what would have been done.

*-r, --resource*='RESOURCE_SPEC'::
  Specify a resource.  This option may be specified more than once.
  See the <<X3,*RESOURCES*>> section for more details.

*-m, --resource-manifest*='FILE'::
  'FILE' contains a list resources (one per line). Manifest 'FILE'
  entries are formatted just like *--resource* option arguments.
  Environment variables and tilde home directories are allowed.

*--stylesheet*='STYLESHEET'::
  A space delimited list of one or more CSS stylesheet file names that
  are used to style HTML output generated by DocBook XSL Stylesheets.
  Defaults to 'docbook-xsl.css'.  The stylesheets are processed in
  list order. The stylesheets must reside in a valid <<X3, resource
  file>> location.  Applies to HTML formats: 'xhtml', 'epub',
  'chunked', 'htmlhelp' formats.

*-v, --verbose*::
  Print operational details to stderr.
  A second *-v* option applies the verbose option to toolchain commands.

*--version*::
  Print program version to stdout.

*--xsltproc-opts*='XSLTPROC_OPTS'::
  Additional 'xsltproc(1)' options.
  This option may be specified more than once.

*--xsl-file*='XSL_FILE'::
  Override the built-in XSL stylesheet with the custom XSL stylesheet
  'XSL_FILE'.

*--fop*::
  Use FOP to generate PDFs. The default behavior is to use
  'dblatex(1)'.  The '--fop' option is implicit if this option is
  used.

*--fop-opts*='FOP_OPTS'::
  Additional 'fop(1)' options. If this option is specified FOP is used
  to generate PDFs.
  This option may be specified more than once.

*--dblatex-opts*='DBLATEX_OPTS'::
  Additional 'dblatex(1)' options.
  This option may be specified more than once.

*--backend-opts*='BACKEND_OPTS'::
  Options for the backend plugin specified by the '--backend' option.
  This option may be specified more than once.

Options can also be set in the AsciiDoc source file. If 'SOURCE_FILE'
contains a comment line beginning with *// a2x:* then the remainder of
the line will be treated as 'a2x' command-line options. For example:

  // a2x default options.
  //    a2x: -dbook --epubcheck
  // Suppress revision history in dblatex outputs.
  //    a2x: --dblatex-opts "-P latex.output.revhistory=0"

- Options spanning multiple such comment lines will be concatenated.
- Zero or more white space characters can appear between the leading
  *//* and *a2x:*.
- Command-line options take precedence over options set in the source
  file.


[[X4]]
OUTPUT FILES
------------
Output files are written to the directory specified by the
*--destination-dir* option. If no *--destination-dir* option is set
output files are written to the 'SOURCE_FILE' directory.

Output files have the same name as the 'SOURCE_FILE' but with an
appropriate file name extension: `.html` for 'xhtml'; `.epub` for
'epub'; `.hhp` for 'htmlhelp'; `.pdf` for 'pdf'; `.text` for 'text',
`.xml` for 'docbook'. By convention manpages have no `.man` extension
(man page section number only).  Chunked HTML directory names have a
`.chunked` extension; chunked HTML Help directory names have a
`.htmlhelp` extension.

Same named existing files are overwritten.

In addition to generating HTML files the 'xhtml', 'epub', 'chunked'
and 'htmlhelp' formats ensure <<X3,resource files>> are copied to
their correct destination directory locations.


[[X3]]
RESOURCES
---------
Resources are files (typically CSS and images) that are required by
HTML based outputs ('xhtml', 'epub', 'chunked', 'htmlhelp' formats).
'a2x' scans the generated HTML files and builds a list of required CSS
and image files. Additional resource files can be specified explicitly
using the *--resource* option.

'a2x' searches for resource files in the following locations in the
following order:

. The 'SOURCE_FILE' directory.
. Resource directories specified by the *--resource* option (searched
  recursively).
. Resource directories specified by the *--resource-manifest* option
  (searched recursively in the order they appear in the manifest
  file).
. The stock `images` and `stylesheets` directories in the
  'asciidoc(1)' configuration files directories (searched
  recursively).
. The destination directory.

When a resource file is found it is copied to the correct relative
destination directory. Missing destination sub-directories are created
automatically.

There are two distinct mechanisms for specifying additional resources:

. A resource directory which will be searched recursively for missing
  resource files.
. A resource file which will be copied to the output destination
  directory.

Resources are specified with *--resource* option values which can be
one of the following formats:

  <resource_dir>
  <resource_file>[=<destination_file>]
  .<ext>=<mimetype>

Where:

`<resource_dir>`::
  Specifies a directory (absolute or relative to the 'SOURCE_FILE')
  which is searched recursively for missing resource files.  To
  eliminate ambiguity the `<resource_dir>` name should end with a
  directory separator character.

`<resource_file>`::
  Specifies a resource file (absolute or relative to the
  'SOURCE_FILE') which will be copied to `<destination_file>`. If
  `<destination_file>` is not specified then it is the same as the
  `<resource_file>`.

`<destination_file>`::
  Specifies the destination of the copied source file. The
  `<destination_file>` path is relative to the destination directory
  (absolute paths are not allowed). The location of the destination
  directory depends on the output 'FORMAT' (see the <<X4,*OUTPUT
  FILES*>> section for details):

  chunked, htmlhelp;; The chunked output directory.
  epub;;              The archived `OEBPS` directory.
  xhtml;;             The output *DESTINATION_DIR*.

`.<ext>=<mimetype>`::
  When adding resources to EPUB files the mimetype is inferred from
  the `<destination file>` extension, if the mimetype cannot be
  guessed an error occurs. The `.<ext>=<mimetype>` resource syntax can
  be used to explicitly set mimetypes. `<ext>` is the file name
  extension, `<mimetype>` is the corresponding MIME type.

Resource option examples:

  --resource ../images/
  --resource doc/README.txt=README.txt
  --resource ~/images/tiger.png=images/tiger.png
  --resource .ttf=application/x-font-ttf


EXAMPLES
--------
`a2x -f pdf doc/source-highlight-filter.txt`::
  Generates `doc/source-highlight-filter.pdf` file.

`a2x -f xhtml -D ../doc --icons -r ../images/ team.txt`::
  Creates HTML file `../doc/team.html`, uses admonition icons and
  recursively searches the `../images/` directory for any missing
  resources.

`a2x -f manpage doc/asciidoc.1.txt`::
  Generate `doc/asciidoc.1` manpage.


[[X1]]
REQUISITES
----------
'a2x' uses the following programs:

- *Asciidoc*:
  http://asciidoc.org/
- *xsltproc*: (all formats except text):
  http://xmlsoft.org/XSLT/
- *DocBook XSL Stylesheets* (all formats except text):
  http://docbook.sourceforge.net/projects/xsl/
- *dblatex* (pdf, dvi, ps, tex formats):
  http://dblatex.sourceforge.net/
- *FOP* (pdf format -- alternative PDF file generator):
  http://xmlgraphics.apache.org/fop/
- *w3m* (text format):
  http://w3m.sourceforge.net/index.en.html
- *Lynx* (text format -- alternative text file generator):
  http://lynx.isc.org/
- *epubcheck* (epub format -- EPUB file validator):
  http://code.google.com/p/epubcheck/

See also the latest README file.


[[X2]]
CONF FILES
----------
A configuration file contains executable Python code that overrides
the global configuration parameters in `a2x.py`.  Optional configuration
files are loaded in the following order:

. `a2x.conf` from the directory containing the 'a2x.py' executable.
. `a2x.conf` from the AsciiDoc global configuration directory.  Skip
  this step if we are executing a locally installed (non system wide)
  copy.
. `a2x.conf` from the AsciiDoc `$HOME/.asciidoc` configuration
  directory.
. The 'CONF_FILE' specified in the '--conf-file' option.

Here are the default configuration file option values:

---------------------------------------------------------------------
# Optional environment variable dictionary passed to
# executing programs. If set to None the existing
# environment is used.
ENV = None

# External executables.
ASCIIDOC = 'asciidoc'
XSLTPROC = 'xsltproc'
DBLATEX = 'dblatex'         # pdf generation.
FOP = 'fop'                 # pdf generation (--fop option).
W3M = 'w3m'                 # text generation.
LYNX = 'lynx'               # text generation (if no w3m).
XMLLINT = 'xmllint'         # Set to '' to disable.
EPUBCHECK = 'epubcheck'     # Set to '' to disable.
# External executable default options.
ASCIIDOC_OPTS = ''
DBLATEX_OPTS = ''
FOP_OPTS = ''
XSLTPROC_OPTS = ''
---------------------------------------------------------------------


BUGS
----
See the AsciiDoc distribution BUGS file.


AUTHOR
------
a2x was originally written by Stuart Rackham. Many people have
contributed to it.


RESOURCES
---------
SourceForge: http://sourceforge.net/projects/asciidoc/

Main web site: http://asciidoc.org/


SEE ALSO
--------
asciidoc(1)


COPYING
-------
Copyright \(C) 2002-2011 Stuart Rackham. Free use of this software is
granted under the terms of the MIT license.