XMLTO(1)

🌸 NAME 🌸

xmlto — apply an XSL stylesheet to an XML document ✨

---

okay so welcome to XMLTO(1), bestie 💖 this is the reference page for xmlto, and honestly? she's a little powerhouse. she takes your XML file and makes it become whatever format you asked for, using literally whatever means necessary. no cap. 🫶

🎀 SYNOPSIS 🎀

xmlto [-o output_dir] [-x custom_xsl] [-m xsl_fragment] [-v]
      [-p postprocessor_opts] [--extensions] [--searchpath path]
      [--skip-validation] [--stringparam paramname=paramvalue]
      [--noclean] [--noautosize] [--noextensions] [--profile]
      [--with-fop] [--with-dblatex] {format} {file}

xmlto {[--help] | [--version]}

---

🦋 DESCRIPTION 🦋

So the whole purpose of xmlto is to convert an XML file to the format you want, using whatever means necessary. 💅 And sometimes that's a two-step kind of situation:

1. Applying an appropriate XSL stylesheet using an XSL-T processor. 🧚
2. Further processing with other tools. (this step might not even be necessary, she's flexible like that)

To figure out which stylesheet to use and what (if anything) needs to happen to post-process the output, xmlto uses format scripts — they're just simple shell scripts that xmlto calls during the conversion. 🎀

The right format script gets picked based on the type of XML file and the output format you want. xmlto ships with some format scripts for converting DocBook XML files into a whole variety of formats. And yes bestie, you can bring your own format script — just use an absolute filename for format on the command line. 👑

✨ The first call: choosing a stylesheet ✨

Firstly, if xmlto hasn't been told explicitly which stylesheet to use (that's the -x option), the format script gets called with $1 set to stylesheet. The environment variable XSLT_PROCESSOR holds the base name of the executable that'll do the XSL-T transformation (like, for example, xsltproc). 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's no appropriate stylesheet to use (for example, if the only stylesheet available is known not to work with the XSL-T processor that's gonna be used 🙈).

And here's a lil plot twist: if nothing gets written to standard output but the script still exits successfully, then no XSL-T transformation will be performed. Periodt.

💜 The second call: post-processing 💜

Secondly, after an XSL-T processor has been run using the stylesheet, the format script gets called again, this time with $1 set to post-process. The format script should do whatever necessary steps 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 runs in a temporary directory containing just the processed output (its name is stored in XSLT_PROCESSED, and its basename is that of the original XML file with any filename extension replaced with .proc). Also:

• INPUT_FILE is set to the name of the original XML file
• OUTPUT_DIR is set to the name of the directory that the output (and only the output) must end up in
• SEARCHPATH 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. 😭

---

💅 OPTIONS 💅

• -v — be verbose (-vv for very verbose). she's chatty, we love that 💬
• -x stylesheet — use stylesheet instead of asking the format script to choose one.
• -m fragment — use the provided XSL fragment to modify the stylesheet.
• -o directory — put output in the specified directory instead of the current working directory.
• -p postprocessor_opts — pass postprocessor_opts to processing stages after stylesheet application (e.g. lynx or links when going through HTML to text, or xmltex when going from through TeX to DVI). If -p is specified a second time, the options specified will be passed to second-stage postprocessing; presently this is only applicable when going through xmltex and dvips to PostScript.
• --extensions — turn on stylesheet extensions for the tool chain in use (use.extensions is turned on). The variables turned on are the ones used by Norman Walsh's DocBook XSL stylesheets. 🔥
• --searchpath path — add the colon-separated list of directories in path as fallback directories for including input.
• --skip-validation — skip the validation step that is normally performed. living dangerously, love that for you 🙈
• --stringparam paramname=paramvalue — pass a named parameter paramname with value paramvalue to stylesheet from the command line.
• --noclean — temporary files are not deleted (their names are shown and kept in tmp directory). It could help with analyzing problems. 🔍
• --noautosize — by default, some XSL variables are overridden by autodetection (page.width and page.height for paperconf (libpaper) use, paper.type for locale-based (LC_PAPER) selection). With this option, xmlto doesn't use this autodetection and user is able to modify defaults himself (either via default param.xsl modification or by user-defined XSL fragment).
• --noextensions — by default, xmlto enables XSL params passivetex.extensions for passivetex backend and fop.extensions and fop1.extensions for fop backend. This usually produces better results. If you for some reason don't want to use these parameters, just disable them using this option.
• --profile — pre-process the XML document with the profiling stylesheet.
• --with-fop — use fop for formatting. It is an experimental option, expects fop in specific location (detected at configured time), could be changed manually in xmlto script by modification of FOP_PATH.

⚠️ bestie, --with-fop is experimental, ok? don't come for me.

• --with-dblatex — use dblatex for formatting. It is an experimental option, expects dblatex in specific location (detected at configured time), could be changed manually in xmlto script by modification of DBLATEX_PATH.

⚠️ same energy: --with-dblatex is experimental too 💀

• --help — display a short usage message. It will describe xmlto's options, and the available output formats. 🫶
• --version — display the version number of xmlto.

---

🌈 ENVIRONMENT 🌈

• XSLT_PROCESSOR — base name of the executable that will be used to perform the XSL-T transformation (default: xsltproc(1)).
• TMPDIR — directory, where to create temporary stylesheets (default: /tmp).

---

⭐ DIAGNOSTICS ⭐

• 0 — everything went fine. This is the expected exit code. 🎉
• 1 — xmlto was called with insufficient arguments. 😭
• 2 — mktemp(1) failed to create a file/directory. Make sure /tmp or TMPDIR is writable.
• 3 — xmlto failed to find some binary on configured location. Make sure that all required packages are installed and paths in xmlto script are set properly.
• 10+(Validation non-zero error code) — xmlto tried to validate a xml document, but validation failed. For better diagnostic, validation output and xmllint exit code is provided. Consider either fixing your document or using --skip-validation.

---

🍓 EXAMPLES 🍓

To convert a DocBook XML document to PDF, use:

xmlto pdf mydoc.xml

To convert a DocBook XML document to HTML and store the resulting HTML files in a separate directory use:

xmlto -o html-dir html mydoc.xml

To convert a DocBook XML document to a single HTML file use:

xmlto html-nochunks mydoc.xml

To modify the output using an XSL fragment use:

xmlto -m ulink.xsl pdf mydoc.xml

To specify which stylesheet to use (overriding the one that the format script would choose) use:

xmlto -x mystylesheet.xsl pdf mydoc.xml

---

👑 AUTHORS 👑

• Tim Waugh <twaugh@redhat.com> — original author, maintainer until 0.0.18 🫡
• Ondřej Vašík <ovasik@redhat.com> — maintainer since 0.0.19 💖

---

🧚 COPYRIGHT 🧚

(it's giving very "official business", so here's the receipts, bestie 💜)

---

and that's the whole page, bestie!! this manual is for xmlto 0.0.25, dated November 2011 — iconic behavior from 2011 that's still serving today. mwah 💅✨