The PreTeXt Guide

Once you have content created in PreTeXt files (i.e., XML files), you will want to convert these files into a output format such as HTML, to be viewed in a web browser, or a PDF. Instructions for doing this will be discussed in Chapter 2, and in even more detail in Chapter 5. Here we provide an overview of how the conversion works to help you understand what is possible.

With PreTeXt “installed” (on your computer or in the cloud), converting PreTeXt XML into a full HTML website can be as simple as typing pretext build html in a terminal, or hitting Ctrl+Alt+B in VS Code. Behind-the-scenes, these commands read through your XML and use XSL 1.0 (eXtensiible Stylesheet Language) to transform the XML source, using a number of XSL stylesheets that come with PreTeXt.

The recommended workflow for processing your source uses a python program we call the PreTeXt-CLI (CLI is command line interface). There are also a number of other free tools that can processes XML with XSL. For example, xsltproc is a command line program that is usually installed by default on Linux systems and MacOS. This was the recommended method in the early days of PreTeXt, and still works. Documentation for how to use xsltproc with PreTeXt can be found in Chapter 46, but unless you are helping with the development of PreTeXt or are trying to do something fancy, you probably don’t need it.

Some features of PreTeXt, such as the inclusion of images described in source, or including WeBWorK exercises, requires the use of an additional processing, done in python. Some of these also require additional software (such as LaTeX or Sage). The PreTeXt-CLI does this automatically when building (and regenerates these assets if they have changed since the last build). There is also a python script that can accesses these functions directly for use in development. See Chapter 47 if you are curious.