Skip to main content

Section 5.5 Customizations, Publisher File, String Parameters

There are some aspects of your output that are entirely divorced from the actual content, and are presumably all about how that content is presented. Two good examples are the size of the font used in /PDF/print output, and the granularity of web pages in HTML output (by this we mean, is each web page a whole chapter, a whole section, a whole subsection?). Producing output with varying values of these parameters does absolutely nothing to change your content in any way, and so should not be a part of your source.

At this writing (2019-07-10) we have begun to transition between two different ways to accomplish this. The new method is to create a publisher file that is an XML file that specifies options that are independent of your source material. See Section 26.1 in Part IV for details. We continue to provide many of the values for these parameters on the command-line at processing time. They have become known as stringparam since that is the name used to call them using xsltproc. The PreTeXt-CLI can set these stringparams easily as well.

Suppose you want to make a large-font version of your textbook for a student who has limited vision. Look inside the top of xsl/pretext-latex.xsl and find the latex.font.size parameter. The preceding comments in this file suggest 20pt is the maximum supported. To pass this parameter to the CLI, you would enter the following.

pretext build pdf --stringparam latex.font.size "20pt"

You can use as many stringparam as you like; just repeat the pattern --stringparam name value for each one. The quotation marks are not strictly needed in this example, but if the value of the parameter has spaces, slashes, etc., then you need to quote-protect the string from the command-line processor, and either single or double quotes will work (and protect the other kind).

Instead of passing these stringparams on the command line, you can specify them inside your project manifest. Inside a particular <target>, include <stringparam key="latex.font.size" value="20pt"/>, for example. Each stringparam you want to set gets its own <stringparam key="" value=""/> element.

These parameters are documented in the XSL files themselves, available in xsl fold in the PreTeXt GitHub repository, principally pretext-common.xsl, pretext-latex.xsl and pretext-html.xsl, and occur near the top. They assume sensible defaults for beginners, and error-checking is careful and robust. They will be easier to locate and use when we have the time to document them more carefully here in the Author's Guide.

One caveat for using these is that experience has taught us that some of the parameters we created early on really do affect your content. We will change some of these, but always provide a smooth upgrade path through deprecations, with little or no disruption to your workflow.