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
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
|
<?xml version='1.0'?> <!-- -*- xml -*- -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<articleinfo>
<title>xmlto</title>
<author>
<firstname>Tim</firstname>
<surname>Waugh</surname>
<affiliation>
<address><email>twaugh@redhat.com</email></address>
</affiliation>
<contrib>Original author, maintainer until 0.0.18</contrib>
</author>
<author>
<firstname>Ondřej</firstname>
<surname>Vašík</surname>
<affiliation>
<address><email>ovasik@redhat.com</email></address>
</affiliation>
<contrib>Maintainer since 0.0.19</contrib>
</author>
<copyright>
<year>2001-8</year>
<holder>Tim Waugh</holder>
</copyright>
<copyright>
<year>2008-9</year>
<holder>Ondřej Vašík</holder>
</copyright>
</articleinfo>
<section>
<title>Reference</title>
<refentry>
<refentryinfo>
<title>xmlto</title>
<date>November 2011</date>
<productname>xmlto 0.0.25</productname>
</refentryinfo>
<refmeta>
<refentrytitle>xmlto</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>xmlto</refname>
<refpurpose>apply an XSL stylesheet to an XML document</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>xmlto</command>
<arg choice="opt"><option>-o</option>
<replaceable>output_dir</replaceable></arg>
<arg choice="opt"><option>-x</option>
<replaceable>custom_xsl</replaceable></arg>
<arg choice="opt"><option>-m</option>
<replaceable>xsl_fragment</replaceable></arg>
<arg choice="opt"><option>-v</option></arg>
<arg choice="opt"><option>-p</option>
<replaceable>postprocessor_opts</replaceable></arg>
<arg choice="opt"><option>--extensions</option></arg>
<arg choice="opt"><option>--searchpath</option>
<replaceable>path</replaceable></arg>
<arg choice="opt"><option>--skip-validation</option></arg>
<arg choice="opt"><option>--stringparam</option>
<replaceable>paramname</replaceable>=<replaceable>paramvalue</replaceable></arg>
<arg choice="opt"><option>--noclean</option></arg>
<arg choice="opt"><option>--noautosize</option></arg>
<arg choice="opt"><option>--noextensions</option></arg>
<arg choice="opt"><option>--profile</option></arg>
<arg choice="opt"><option>--with-fop</option></arg>
<arg choice="opt"><option>--with-dblatex</option></arg>
<arg choice="req"><replaceable>format</replaceable></arg>
<arg choice="req"><replaceable>file</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>xmlto</command>
<group choice="req">
<arg>--help</arg>
<arg>--version</arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>The purpose of <command>xmlto</command> is to convert an
XML <replaceable>file</replaceable> to the desired
<replaceable>format</replaceable> using whatever means
necessary. This may involve two steps:</para>
<procedure>
<step>
<para>The application of an appropriate XSL stylesheet
using an XSL-T processor.</para>
</step>
<step>
<para>Further processing with other tools. This step may
not be necessary.</para>
</step>
</procedure>
<para>To decide which stylesheet to use and what, if any,
needs to be done to post-process the output,
<command>xmlto</command> makes use of <firstterm>format
scripts</firstterm>, which are simple shell scripts that
<command>xmlto</command> calls during the conversion.</para>
<para>The appropriate format script is selected based on the
type of XML file and the desired output format.
<command>xmlto</command> comes with some format scripts for
converting DocBook XML files to a variety of formats. You
may specify your own format script by using an absolute
filename for <replaceable>format</replaceable> on the command
line.</para>
<para>Firstly, if <command>xmlto</command> has not been told
explicitly which stylesheet to use (with the
<option>-x</option> option), the format script will be called
with <envar>$1</envar> set to <literal>stylesheet</literal>.
The environment variable <envar>XSLT_PROCESSOR</envar>
contains the base name of the executable that will be used to
perform the XSL-T transformation (for example
<literal>xsltproc</literal>). The format script should write
the name of the stylesheet to use to standard output and exit
successfully, or exit with a non-zero return code if there is
no appropriate stylesheet to use (for example, if the only
available stylesheet is known not to work with the XSL-T
processor that will be used). If nothing is written to
standard output but the script exits successfully, no XSL-T
transformation will be performed.</para>
<para>Secondly, after an XSL-T processor has been run using
the stylesheet, the format script will be called again, this
time with <envar>$1</envar> set to
<literal>post-process</literal>. The format script should
perform any necessary steps to translate the XSL-T processed
output into the desired output format, including copying the
output to the desired output directory. For post-processing,
the format script is run in a temporary directory containing
just the processed output (whose name is stored in
<envar>XSLT_PROCESSED</envar> and whose basename is that of
the original XML file with any filename extension replaced
with <literal>.proc</literal>). <envar>INPUT_FILE</envar> is
set to the name of the original XML file,
<envar>OUTPUT_DIR</envar> is set to the name of the directory
that the output (and only the output) must end up in, and
<envar>SEARCHPATH</envar> is set to a colon-separate list of
fallback directories in which to look for input (for images,
for example). If this step is unsuccessful the format script
should exit with a non-zero return code.</para>
</refsect1>
<refsect1>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-v</option></term>
<listitem>
<para>Be verbose (<option>-vv</option> for very
verbose).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-x</option> <replaceable>stylesheet</replaceable></term>
<listitem>
<para>Use <replaceable>stylesheet</replaceable> instead
of asking the format script to choose one.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-m</option> <replaceable>fragment</replaceable></term>
<listitem>
<para>Use the provided XSL
<replaceable>fragment</replaceable> to modify the
stylesheet.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o</option> <replaceable>directory</replaceable></term>
<listitem>
<para>Put output in the specified
<replaceable>directory</replaceable> instead of the
current working directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option> <replaceable>postprocessor_opts</replaceable></term>
<listitem>
<para>Pass <replaceable>postprocessor_opts</replaceable>
to processing stages after stylesheet application
(e.g. <application>lynx</application> or
<application>links</application> when going
through HTML to text, or <application>xmltex</application>
when going from through TeX to DVI). If
<option>-p</option> is specified a second time, the
options specified will be passed to second-stage
postprocessing; presently this is only applicable when
going through <application>xmltex</application> and
<application>dvips</application> to PostScript.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--extensions</option></term>
<listitem>
<para>Turn on stylesheet extensions for the tool chain
in use (<varname>use.extensions</varname> is turned on).
The variables turned on are the ones used
by Norman Walsh's DocBook XSL stylesheets.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--searchpath</option> <replaceable>path</replaceable></term>
<listitem>
<para>Add the colon-separated list of directories in
<replaceable>path</replaceable> as fallback
directories for including input.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--skip-validation</option></term>
<listitem>
<para>Skip the validation step that is normally
performed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--stringparam</option> <replaceable>paramname</replaceable>=<replaceable>paramvalue</replaceable></term>
<listitem>
<para>Pass a named parameter <replaceable>paramname</replaceable>
with value <replaceable>paramvalue</replaceable>
to stylesheet from the command line.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--noclean</option></term>
<listitem>
<para>Temporary files are not deleted(their names
are shown and kept in tmp directory). It could
help with analyzing problems.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--noautosize</option></term>
<listitem>
<para> By default, some XSL variables are overridden
by autodetection (<varname>page.width</varname> and
<varname>page.height</varname> for <application>paperconf</application>
(libpaper) use, <varname>paper.type</varname> for locale-based
(<envar>LC_PAPER</envar>) selection). With this
option, <command>xmlto</command> doesn’t use this autodetection
and user is able to modify defaults himself (either via default
<filename>param.xsl</filename> modification or by user-defined
XSL fragment).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--noextensions</option></term>
<listitem>
<para> By default, <command>xmlto</command> enables XSL params <varname>passivetex.extensions</varname> for
<application>passivetex</application> backend and <varname>fop.extensions</varname> and <varname>fop1.extensions</varname>
for <application>fop</application> backend.
This usually produces better results. If you for some reason don't want to use these parameters, just
disable them using this option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--profile</option></term>
<listitem>
<para>Pre-process the XML document with the profiling stylesheet.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-fop</option></term>
<listitem>
<para>Use <application>fop</application> for formatting.
It is an experimental option, expects <application>fop</application>
in specific location(detected at configured time), could be changed
manually in <command>xmlto</command> script by modification
of <varname>FOP_PATH</varname></para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-dblatex</option></term>
<listitem>
<para>Use <application>dblatex</application> for formatting.
It is an experimental option, expects <application>dblatex</application>
in specific location(detected at configured time), could be changed
manually in <command>xmlto</command> script by modification
of <varname>DBLATEX_PATH</varname></para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--help</option></term>
<listitem>
<para>Display a short usage message. It will describe xmlto's
options, and the available output formats.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem>
<para>Display the version number of xmlto.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Environment</title>
<variablelist>
<varlistentry>
<term><envar>XSLT_PROCESSOR</envar></term>
<listitem>
<para>Base name of the executable that will be used to
perform the XSL-T transformation (default: <citerefentry>
<refentrytitle>xsltproc</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>TMPDIR</envar></term>
<listitem>
<para>Directory, where to create temporary stylesheets
(default: <filename>/tmp</filename>).
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><errorcode>0</errorcode></term>
<listitem>
<para>Everything went fine. This is the expected exit code.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>1</errorcode></term>
<listitem>
<para><command>xmlto</command> was called with insufficient
arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>2</errorcode></term>
<listitem>
<para><citerefentry>
<refentrytitle>mktemp</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry> failed to create a file/directory. Make sure
<filename>/tmp</filename> or <envar>TMPDIR</envar> is
writable.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>3</errorcode></term>
<listitem>
<para><command>xmlto</command> failed to find some binary on
configured location. Make sure that all required packages
are installed and paths in <application>xmlto</application>
script are set properly.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>10+(Validation non-zero error code)</errorcode></term>
<listitem>
<para><command>xmlto</command> tried to validate a xml document, but validation failed. For better diagnostic, validation output and <application>xmllint</application> exit code is provided. Consider either fixing your document or using <option>--skip-validation</option>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<para>To convert a DocBook XML document to PDF, use:
<screen><command>xmlto pdf mydoc.xml</command></screen></para>
<para>To convert a DocBook XML document to HTML and store the
resulting HTML files in a separate directory use:
<screen><command>xmlto -o html-dir html mydoc.xml</command></screen></para>
<para>To convert a DocBook XML document to a single HTML file
use:
<screen><command>xmlto html-nochunks mydoc.xml</command></screen></para>
<para>To modify the output using an XSL fragment use:
<screen><command>xmlto -m ulink.xsl pdf mydoc.xml</command></screen></para>
<para>To specify which stylesheet to use (overriding the one
that the format script would choose) use:
<screen><command>xmlto -x mystylesheet.xsl pdf mydoc.xml</command></screen></para>
</refsect1>
</refentry>
</section>
</article>
|
