db2x_xsltproc(1)

💅 db2x_xsltproc — XSLT processor invocation wrapper 💅

okay so. this is a page from the docbook2X manual, and it's about a lil command called db2x_xsltproc. bestie, if you've ever needed to run an XSLT 1.0 processor without losing your whole entire mind, this is your girl. let's get into it 🫶

---

🌸 NAME 🌸

db2x_xsltproc — the XSLT processor invocation wrapper. that's it, that's the vibe. it wraps. it processes. it slays. ✨

---

🎀 SYNOPSIS 🎀

db2x_xsltproc [options] xml-document

---

🦋 DESCRIPTION 🦋

So db2x_xsltproc invokes the XSLT 1.0 processor for docbook2X. no cap.

This command applies the XSLT stylesheet — usually the one you handed over with the --stylesheet option — to the XML document sitting in the file xml-document. 📄✨

The result gets written to standard output, unless you changed that with --output. simple as.

And listen: if you want to read the source XML document from standard input, you literally just specify - as the input document. iconic behaviour honestly. 💅

---

👑 OPTIONS 👑

💖 the lone wolf option 💖

• --version — displays the docbook2X version. that's it. she's little but she's doing her best. 🎀

🔥 TRANSFORMATION OUTPUT OPTIONS 🔥

• --output file, -o file — write the output to the given file (or URI), instead of standard output. take your output somewhere nice, bestie. 💖

🌸 SOURCE DOCUMENT OPTIONS 🌸

• --xinclude, -I — process XInclude directives in the source document. include-ception, we love to see it. ✨
• --sgml, -S — this one says: hey, the input document is SGML, not XML. you need to set this option if xml-document is actually an SGML file. no setting it = no SGML, periodt.

So here's the tea on how SGML parsing happens: it's implemented by conversion to XML via sgml2xml(1) from the SP package (or osx(1) from the OpenSP package). And some details you should know:

• All tag names in the SGML file get normalized to lowercase — meaning the -xlower option of sgml2xml(1) is used.
• ID attributes are available for the stylesheet — that's the -xid option.
• Any ISO SDATA entities used in the SGML document are automatically converted to their XML Unicode equivalents. (this is done by a sed filter. a whole sed filter. iconic.)

The encoding of the SGML document — if it is not us-ascii — must be specified with the standard SP environment variables:

SP_CHARSET_FIXED=1 SP_ENCODING=encoding

(and btw, XML files specify their encoding with the XML declaration <?xml version="1.0" encoding="encoding" ?> at the top of the file. just so you know the difference 💜)

⚠️ The above conversion options cannot be changed. If you desire different conversion options, you should invoke sgml2xml(1) manually, and then pass the results of that conversion to this program. do it yourself era, I guess. 😭

🌈 RETRIEVAL OPTIONS 🌈

• --catalogs catalog-files, -C catalog-files — specify additional XML catalogs to use for resolving Formal Public Identifiers or URIs. 🗂️ and no, SGML catalogs are not supported.

heads up bestie: these catalogs are not used for parsing an SGML document under the --sgml option. use the environment variable SGML_CATALOG_FILES instead to specify the catalogs for parsing the SGML document. 🫶

• --network, -N — so normally db2x_xsltproc will refuse to load external resources from the network, for security reasons (she's protective, we stan). If you do want to load from the network, set this option.

Usually you want to have installed locally the relevent DTDs and other files, and set up catalogs for them, rather than load them automatically from the network. local files = the moment. 💅

🎀 STYLESHEET OPTIONS 🎀

• --stylesheet file, -s file — specify the filename (or URI) of the stylesheet to use. and here's a cute lil shortcut: the special values man and texi are accepted as abbreviations, to specify that xml-document is in DocBook and should be converted to man pages or Texinfo (respectively). so convenient, so slay. ✨
• --param name=expr, -p name=expr — add or modify a parameter to the stylesheet. name is an XSLT parameter name, and expr is an XPath expression that evaluates to the desired value for the parameter. 🧚

(this means that strings must be quoted, in addition to the usual quoting of shell arguments — double quoting?? yes bestie, it's giving nesting doll energy. use --string-param to avoid this.) 😭

• --string-param name=string, -g name=string — add or modify a string-valued parameter to the stylesheet. the easy way out, and honestly? valid.

The string must be encoded in UTF-8 (regardless of the locale character encoding). no exceptions, she's strict about her encoding. 💜

🔍 DEBUGGING AND PROFILING 🔍

• --debug, -d — display, to standard error, logs of what is happening during the XSL transformation. the play-by-play commentary we all deserve. 👑
• --nesting-limit n, -D n — change the maximum number of nested calls to XSL templates, used to detect potential infinite loops. 🌀 If not specified, the limit is 500 (libxslt's default). so if you're spiraling, she'll catch you at 500 deep. 💀
• --profile, -P — display profile information: the total number of calls to each template in the stylesheet and the time taken for each. This information is output to standard error. it's giving stats class but make it cute. 📊
• --xslt-processor processor, -X processor — select the underlying XSLT processor used. The possible choices for processor are: libxslt, saxon, xalan-j.

The default processor is whatever was set when docbook2X was built. libxslt is recommended (because it is lean and fast), but SAXON is much more robust and would be more helpful when debugging stylesheets. 🦋

All the processors have XML catalogs support enabled. (docbook2X requires it.) But note that not all the options above work with processors other than the libxslt one. read the fine print bestie, it's there for a reason. 💅

---

🌱 ENVIRONMENT 🌱

• XML_CATALOG_FILES — specify XML Catalogs. If not specified, the standard catalog (/etc/xml/catalog) is loaded, if available. 🗂️✨
• DB2X_XSLT_PROCESSOR — specify the XSLT processor to use. The effect is the same as the --xslt-processor option. The primary use of this variable is to allow you to quickly test different XSLT processors without having to add --xslt-processor to every script or make file in your documentation build system. set it once, vibe forever. 🔥

---

💜 CONFORMING TO 💜

XML Stylesheet Language – Transformations (XSLT), version 1.0 ⟨http://www.w3.org/TR/xslt⟩, a W3C Recommendation. certified official, no cap. 👑

---

📜 NOTES 📜

okay, story time 🍓. In its earlier versions (< 0.8.4), docbook2X required XSLT extensions to run, and db2x_xsltproc was a special libxslt-based processor that had these extensions compiled-in. When the requirement for XSLT extensions was dropped, db2x_xsltproc became a Perl script which translates the options to db2x_xsltproc to conform to the format accepted by the stock xsltproc(1) which comes with libxslt. glow-up arc, honestly. ✨

The prime reason for the existence of this script is backward compatibility with any scripts or make files that invoke docbook2X. However, it also became easy to add in support for invoking other XSLT processors with a unified command-line interface. Indeed, there is nothing special in this script to docbook2X, or even to DocBook, and it may be used for running other sorts of stylesheets if you desire. she's versatile like that. 🦋

Certainly the author prefers using this command, because its invocation format is sane and is easy to use. (e.g. no typing long class names for the Java-based processors!) — and honestly? the author ate with that take. 💅

---

🫶 AUTHOR 🫶

Steve Cheng <stevecheng@users.sourceforge.net>. thank you for your service, king. 👑

---

🌈 SEE ALSO 🌈

• The docbook2X manual (in Texinfo or HTML format) fully describes how to convert DocBook to man pages and Texinfo. 📚
• Up-to-date information about this program can be found at the docbook2X Web site ⟨http://docbook2x.sourceforge.net/⟩. 🌐
• You may wish to consult the documentation that comes with libxslt, SAXON, or Xalan. The W3C XSLT 1.0 specification would be useful for writing stylesheets. 💖

---

and that's the whole page bestie!! this was docbook2X 0.8.8, dated 3 March 2007. yeah she's vintage, she's classic, she's still serving. mwah 💋✨🎀