Section 1.3 Converting Your Source to Output
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. Detailed instructions for doing this, including a plethora of options, will be discussed in Chapter 5; here we will give a very brief overview to illustrate the basic ideas.
Once you have your computer set up correctly, converting PreTeXt XML into a full HTML website can be as simple as typing
pretext build html in a terminal, or even hitting
Ctrl+B in Visual Studio Code. Behind-the-scenes, these commands use XSL 1.0 (eXtensiible Stylesheet Language) to transform the XML source using a number of XSL stylesheets that come with PreTeXt.
There are other methods of combining the supplied XSL stylesheets with your XML source, including
xsltproc, a command line program that is usually installed by default on Linux systems and MacOS. For many years, this was the preferred method of converting PreTeXt documents, by entering a command such as:
xsltproc -xinclude ../mathbook/xsl/pretext-html.xsl source/main.ptx
This workflow is still supported, and for authors who would like more control over their projects, this might still be the best option. Documentation for how to use
xsltproc with PreTeXt can be found in Chapter 44.
Some features of PreTeXt, such as the inclusion of images described in source, or including WeBWorK exercises, requires the use of an additional Python script, also shipped with PreTeXt. Instructions for using this script can be found in Chapter 45.
For the majority of authors who are starting out with PreTeXt, a simpler workflow is available: the PreTeXt-CLI (CLI is Command Line Interface). This is a Python program that implements the most common conversion tasks that previously required
xsltproc and the pretext script. If you are ready to install and get started see Section 2.1.