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