Section 44.9 Extra Stylesheet
There are situations when an “extra” XSL stylesheet is necessary for processing your XML source. A good example is the supported method for styling PDF output, described at Chapter 38. Historically, various customizations have been supported by “thin” XSL stylesheets (Section 5.7), but as certain themes have become apparent we have moved these customizations to simpler techniques (e.g. publisher files, Section 26.1). Other than styling PDF, you should think carefully about if an additional stylesheet is necessary.
--XSL) switch is used to specify an “extra” XSL stylesheet that will be applied to your source. Note that it is now possible to do anything you want to your source and so can create run-time failures at any point in the process. Here are the simple mistakes to avoid.
If you are expecting HTML output because you used
-f html, then your stylesheet supplied in the
-Xargument will certainly import the base
xsl/pretext-html.xslstylesheet. When you understand this, then you will understand that perhaps we should call this an “alternate” stylesheet. This advice applies equally well to extending the base
The import just described will behave better for others (meaning co-authors, or authors who fork your project) if the import uses a relative path, meaning relative to location of the extra stylesheet. We therefore suggest using a
userdirectory, placed as a peer of the
xsldirectory, as described in Section 5.7.
So a common mistake is to use
-Xto point to an extra stylesheet someplace close-by your project's source files, when you have sensibly setup a relative import of the base stylesheet, and instead should point to the copy you have placed in
userso that the import is effective on everybody's system.
As of 2021-08-04, this technique is only effective for HTML, PDF, and LaTeX outputs. It may be natural for some other output formats (e.g., EPUB), and perhaps possible for others (e.g., braille). Make a feature request for expanding applicability.