Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller

Section 47.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 41. Historically, various customizations have been supported by “thin” XSL stylesheets (Section 28.2), but as certain themes have become apparent we have moved these customizations to simpler techniques (e.g. publication files, Section 26.1). Other than styling PDF, you should think carefully about if an additional stylesheet is necessary.
The -X (--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 -X argument will certainly import the base xsl/pretext-html.xsl stylesheet. 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 xsl/pretext-latex.xsl stylesheet.
  • 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 user directory, placed as a peer of the xsl directory, as described in Section 28.2.
  • So a common mistake is to use -X to 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 user so that the import is effective on everybody’s system.
As of 2021-08-04, this technique is only effective for HTML, PDF, and 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.
PrevTopNext