1XMLTO(1) Reference XMLTO(1)
2
6 xmlto - apply an XSL stylesheet to an XML document
7
9 xmlto [-o output_dir] [-x custom_xsl] [-m xsl_fragment] [-v]
10 [-p postprocessor_opts] [--extensions] [--searchpath path]
11 [--skip-validation] [--stringparam paramname=paramvalue]
12 [--noclean] [--noautosize] [--noextensions] [--profile]
13 [--with-fop] [--with-dblatex] {format} {file}
14 xmlto {[--help] | [--version]}
16
18 The purpose of xmlto is to convert an XML file to the desired format
19 using whatever means necessary. This may involve two steps:
20 1. The application of an appropriate XSL stylesheet using an XSL-T
22 processor.
23 2. Further processing with other tools. This step may not be
25 necessary.
26 To decide which stylesheet to use and what, if any, needs to be done to
28 post-process the output, xmlto makes use of format scripts, which are
29 simple shell scripts that xmlto calls during the conversion.
30 The appropriate format script is selected based on the type of XML file
32 and the desired output format. xmlto comes with some format scripts
33 for converting DocBook XML files to a variety of formats. You may
34 specify your own format script by using an absolute filename for format
35 on the command line.
36 Firstly, if xmlto has not been told explicitly which stylesheet to use
38 (with the -x option), the format script will be called with $1 set to
39 stylesheet. The environment variable XSLT_PROCESSOR contains the base
40 name of the executable that will be used to perform the XSL-T
41 transformation (for example xsltproc). The format script should write
42 the name of the stylesheet to use to standard output and exit
43 successfully, or exit with a non-zero return code if there is no
44 appropriate stylesheet to use (for example, if the only available
45 stylesheet is known not to work with the XSL-T processor that will be
46 used). If nothing is written to standard output but the script exits
47 successfully, no XSL-T transformation will be performed.
48 Secondly, after an XSL-T processor has been run using the stylesheet,
50 the format script will be called again, this time with $1 set to
51 post-process. The format script should perform any necessary steps to
52 translate the XSL-T processed output into the desired output format,
53 including copying the output to the desired output directory. For
54 post-processing, the format script is run in a temporary directory
55 containing just the processed output (whose name is stored in
56 XSLT_PROCESSED and whose basename is that of the original XML file with
57 any filename extension replaced with .proc). INPUT_FILE is set to the
58 name of the original XML file, OUTPUT_DIR is set to the name of the
59 directory that the output (and only the output) must end up in, and
60 SEARCHPATH is set to a colon-separate list of fallback directories in
61 which to look for input (for images, for example). If this step is
62 unsuccessful the format script should exit with a non-zero return code.
63
65 -v
66 Be verbose (-vv for very verbose).
67 -x stylesheet
69 Use stylesheet instead of asking the format script to choose one.
70 -m fragment
72 Use the provided XSL fragment to modify the stylesheet.
73 -o directory
75 Put output in the specified directory instead of the current
76 working directory.
77 -p postprocessor_opts
79 Pass postprocessor_opts to processing stages after stylesheet
80 application (e.g. lynx or links when going through HTML to text,
81 or xmltex when going from through TeX to DVI). If -p is specified a
82 second time, the options specified will be passed to second-stage
83 postprocessing; presently this is only applicable when going
84 through xmltex and dvips to PostScript.
85 --extensions
87 Turn on stylesheet extensions for the tool chain in use
88 (use.extensions is turned on). The variables turned on are the ones
89 used by Norman Walsh's DocBook XSL stylesheets.
90 --searchpath path
92 Add the colon-separated list of directories in path as fallback
93 directories for including input.
94 --skip-validation
96 Skip the validation step that is normally performed.
97 --stringparam paramname=paramvalue
99 Pass a named parameter paramname with value paramvalue to
100 stylesheet from the command line.
101 --noclean
103 Temporary files are not deleted(their names are shown and kept in
104 tmp directory). It could help with analyzing problems.
105 --noautosize
107 By default, some XSL variables are overridden by autodetection
108 (page.width and page.height for paperconf (libpaper) use,
109 paper.type for locale-based (LC_PAPER) selection). With this
110 option, xmlto doesn’t use this autodetection and user is able to
111 modify defaults himself (either via default param.xsl modification
112 or by user-defined XSL fragment).
113 --noextensions
115 By default, xmlto enables XSL params passivetex.extensions for
116 passivetex backend and fop.extensions and fop1.extensions for fop
117 backend. This usually produces better results. If you for some
118 reason don't want to use these parameters, just disable them using
119 this option.
120 --profile
122 Pre-process the XML document with the profiling stylesheet.
123 --with-fop
125 Use fop for formatting. It is an experimental option, expects fop
126 in specific location(detected at configured time), could be changed
127 manually in xmlto script by modification of FOP_PATH
128 --with-dblatex
130 Use dblatex for formatting. It is an experimental option, expects
131 dblatex in specific location(detected at configured time), could be
132 changed manually in xmlto script by modification of DBLATEX_PATH
133 --help
135 Display a short usage message. It will describe xmlto's options,
136 and the available output formats.
137 --version
139 Display the version number of xmlto.
140
142 XSLT_PROCESSOR
143 Base name of the executable that will be used to perform the XSL-T
144 transformation (default: xsltproc(1)).
145 TMPDIR
147 Directory, where to create temporary stylesheets (default: /tmp).
148
150 0
151 Everything went fine. This is the expected exit code.
152 1
154 xmlto was called with insufficient arguments.
155 2
157 mktemp(1) failed to create a file/directory. Make sure /tmp or
158 TMPDIR is writable.
159 3
161 xmlto failed to find some binary on configured location. Make sure
162 that all required packages are installed and paths in xmlto script
163 are set properly.
164 10+(Validation non-zero error code)
166 xmlto tried to validate a xml document, but validation failed. For
167 better diagnostic, validation output and xmllint exit code is
168 provided. Consider either fixing your document or using
169 --skip-validation.
170
172 To convert a DocBook XML document to PDF, use:
173 xmlto pdf mydoc.xml
175 To convert a DocBook XML document to HTML and store the resulting HTML
177 files in a separate directory use:
178 xmlto -o html-dir html mydoc.xml
180 To convert a DocBook XML document to a single HTML file use:
182 xmlto html-nochunks mydoc.xml
184 To modify the output using an XSL fragment use:
186 xmlto -m ulink.xsl pdf mydoc.xml
188 To specify which stylesheet to use (overriding the one that the format
190 script would choose) use:
191 xmlto -x mystylesheet.xsl pdf mydoc.xml
193
195 Tim Waugh <twaugh@redhat.com>
196 Original author, maintainer until 0.0.18
197 Ondřej Vašík <ovasik@redhat.com>
199 Maintainer since 0.0.19
200
202xmlto 0.0.25 November 2011 XMLTO(1)