Skip to main content

The PreTeXt Guide

Section 5.2 The PreTeXt-CLI

Here we will outline the functionality of the PreTeXt-CLI. Instructions for using the CLI without any local installation can be found in Chapter 2. Note that an easy first step toward getting PreTeXt working locally would be to download VS Code and install the pretext-tools extension (which will install the PreTeXt-CLI for you, assuming you have an appropriate version of python available).
We will work at the command-line inside of a terminal or console. If you do not know what this is, it will seem very primitive at first. This will be called a “Command Prompt” or “PowerShell” in Windows or a “Terminal” on a Mac. In Linux it may be known as a “console” or a “shell”. Whenever the guide says to enter something on the command line or in a terminal, or just to enter the command, this is what we are talking about.
A final note before we get started: everything we describe here can be done locally or using an online service like CoCalc
 1 
cocalc.com
, which has a terminal and has all the required software (python, , sagemath, etc) installed already. To use CoCalc, you likely will need a paid account so you have internet access (required if you want to get the most recent version of PreTeXt or want to use pretext deploy to save and host your work on GitHub).

Subsection 5.2.1 Installing PreTeXt

Before you can install PreTeXt locally, make sure you have the following software on your computer, or else install it using instructions easily searched for online.
  • Python, version 3.8.5 or later. In a terminal, type python --version to ensure you are already set up. On MacOS or Linux, your command for python might be called python3, so also try python3 --version.
  • To produce a pdf, or to generate tikz images from source, you need . Try xelatex --version to see if you already have this.
  • Any text editor. Visual Studio Code
     2 
    code.visualstudio.com
    is an excellent choice (and has an extension, PreTeXt-tools
     3 
    marketplace.visualstudio.com/items?itemName=oscarlevin.pretext-tools
    , with specific language support), but other editors such as SublimeText, atom, emacs, vi, etc. can also be used. See Appendix D.
Now we can install PreTeXt. Open a terminal and type the following:
$ pip install pretext
If this fails, try:
$ python -m pip install pretext
(or, if python3 worked above, do python3 -m pip install pretext.)
The python -m helps in case Python is on your PATH but pip is not. This is a useful fix for the rest of the commands listed for the PreTeXt-CLI.
To verify that the CLI is installed, type pretext --version (or python -m pretext --version) and you should get back a number (1.7.5, for example).
For quick hints about what you can do, the CLI has built-in help. You can access this by entering pretext --help or pretext build --help (replacing build with new or view or generate etc.).

Upgrading.

This documentation will assume you have version 1.0 or later of the CLI. You can upgrade the CLI to the most recent version through PIP using the command:
$ pip install pretext --upgrade
If you want to experiment with bleeding-edge features, you can install a nightly development version of the CLI by running:
$ pip install pretext --upgrade --pre
If you ever want to downgrade to previous version, you can do that with pip as well. For example, to install version 1.7.5:
$ pip install pretext=="1.7.5"
Warning 5.2.1.
If you installed the PreTeXt-CLI before version 1.0, you need to manually uninstall the package pretextbook (which is what the CLI was called during early development). Run pip uninstall pretextbook and then pip install pretext te get caught up.

Subsection 5.2.2 Starting a New Project: pretext new

To generate a new book or article, from the folder in which you want to project located, type:
$ pretext new book
This creates a new book in the folder “new-pretext-project” (which you can safely rename). For a new article, use pretext new article. You might also try pretext new demo to get a project that shows off more features available.
Inside the “new-pretext-project” folder, you will find the following folders and files:
assets
A folder to place static (external) assets, such as images or data files, that you will include in your project, for example, with <image source="frog.jpg"/>.
generated-assets
A folder that will hold assets (such as images) generated from source, using the pretext build or pretext generate commands. You should not manually edit any contents of this folder.
publication
A folder to hold your “publication” files used to customize how your output looks. One publication file is included, but you can have as many as you want. See Chapter 44.
source
A folder to hold all your PreTeXt source files. These are the main files you will edit to control the content of your project.
.gitignore
A file containing a list of folders and files that should not be tracked by git if you use it for version control.
project.ptx
An XML file called the project manifest. This specifies options for converting your source into different target outputs. We will describe the contents of this file in Subsection 5.2.7.
README.md
A file that you can use to describe your project.
requirements.txt
A simple text file that contains the version of the CLI that is initially used to build the project. If you upgrade the CLI, you will be warned to also update the version in this file once you know that things build as expected.
Once you build your project, you will get a folder called “output”. Do not edit the contents of this folder manually.

Subsection 5.2.3 Converting: pretext build

To convert your source into one of the available output formats, say HTML, run the command:
$ pretext build web
Here “web” is the @name of one of the targets in the project manifest (project.ptx). To build different targets, replace it with the @name of another target, as in pretext build print.
You can also build the first (default) target of the manifest by omitting the target: just type pretext build.

Subsection 5.2.4 Viewing output: pretext view

After you convert your source into, say HTML, you can view the output using the command:
$ pretext view web
This will direct you to open a file running in a local server (that the CLI started for you) at a provided address (perhaps http://localhost:8128/output/web). Once you have run pretext view once, you can navigate to other output targets by navigating to a different url (maybe http://localhost:8128/output/print) or just rerun the pretext view command with a different target name.
Running pretext view will attempt to open your default program for the type of file you are opening. You can prevent this attempt using the --no-launch flag.
Assuming you ran this command in a terminal, the easiest way to continue working is to open a new terminal tab to run pretext build again; the local server will continue in the original terminal until you stop it with CTRL+C.

Warning 5.2.2.

When using pretext view, your project is only viewable on your local machine (even if you are working in a Codespace or on CoCalc). To make the output available to the public, you will need to copy the output to a web server, or use the pretext deploy command, described below.

Subsection 5.2.5 Hosting your project: pretext deploy

When you are ready to share your project with the world, you can copy the contents of the output/web (or whatever you called the output of your html build) to any webserver. A convenient free option is to use GitHub Pages
 4 
pages.github.com/
, and the CLI makes this especially easy.
If you already track your source files using GitHub, all you need to do is enter the following command:
$ pretext deploy
If you watch the terminal, you will either get directions for how to set up your repository, or will simply be told what the live website for your project is.
Behind the scenes, this command copies the contents of the output folders you want to deploy to a folder output/stage, and then moves the entire contents of that folder to the gh-pages branch of your github repository. If you have not already created a gh-pages branch, the CLI will create one for you. If you have not already set up your repository to track your source files, the CLI will walk you through the steps you need to get set up.

Tip 5.2.3.

You can deploy multiple targets, starting with the 2.0 release of the CLI. To do this, you will need to specify a @deploy-dir attribute in your project manifest for each target you want to deploy. Additionally, you should create a folder in the root of your project called site and create a landing page for your project. The site folder and the output folders for each specified project will all be copied to output/stage. We recommend using the flag --stage-only so you can preview you complete site before deploying it.

Subsection 5.2.6 Generating assets: pretext generate

Some PreTeXt elements require special processing: WeBWorK exercises, <latex-image>, <sageplot>, and <asymptote> images, as well as previews for embedded youtube videos or interactive elements. We call these elements “assets” or “generated assets”. \
Prior to version 1.7 of the CLI, you would need to run pretext generate -t [target] (where “[target]” is the name of a target, like “web”) in order to generate assets. Since then, you can still do this, but it is usually not necessary: whenever you build a target, the CLI will automatically generate any assets that are out of date. If you want to force the generation of assets, you can use the -g flag when building (e.g., pretext build web -g). If you really don’t want to automatically regenerate assets, you can use the --no-generate flag when building (e.g., pretext build web --no-generate).
If you are using an older version of the CLI, or if you want to generate assets without building, the following instructions can help you limit what you generate.
  • You can limit which sorts of assets you generate. For example, if you edit a few <latex-image> elements, you can just generate these (for the first target in the manifest) with pretext generate latex-image.
    Valid choices for what types of assets you can generate in this specific way are: webwork, latex-image, sageplot, asymptote, interactive, youtube, codelense, and datafile.
  • To be even more precise, if the element you wish to generate has an @xml:id, you can generate just that element using the -x flag. For example, if your <latex-image> has id “img-circle”, generate it with pretext generate -x img-circle
  • Finally, there might be times you would like to get all output formats for the assets you are generating. You can accomplish this using the --all-formats flag on pretext generate

Subsection 5.2.7 The project manifest: project.ptx

The project manifest, always named “project.ptx”, contains information about each target you will build. Prior to version 2.0 of the CLI, it also contained the names of executables of external tools that might be needed for building targets and generating assets. (In 2.0 and later, if you need to change the default names or paths to executables, you will use a separate executables.ptx file.)
The CLI looks for this file, so you should have only one. If you have a project that was not created using pretext new, you can get a copy of the file by running pretext init. You can also get the most recent template version of the manifest by running pretext init --refresh, which will create time-stamped versions of the files (so your files with matching names don’t get overwritten) for you to copy from.
While we use the .ptx extension, the manifest is not technically a PreTeXt document, since it does not agree with the schema. However, it must have a specific structure to be used with the CLI. An example of a simple manifest is given in Listing 5.2.4. Note this is version 2 manifest; for a comparison of “legacy” manifests and the current format, see Appendix O.
<?xml version="1.0" encoding="utf-8"?>
<project ptx-version="2">
<targets>
    <target name="web" format="html" />
    <target name="rs" format="html" platform="runestone" />
    <target name="print" format="pdf" />
</targets>
</project>
Listing 5.2.4. Example of a very simple project manifest.
The manifest contains a single <project> element with a @ptx-version attribute. This attribute is required and must be set to “2” for the CLI to recognize the file as a valid manifest. Additional optional attributes of <project> can also be specified, which we will describe below. The <project> element has a single child, <targets>, which contains a list of <target> elements.
Each <target> must have a @name attribute. The name (e.g., web, print) is what you specify when you run build, view, or generate for a specific target (so pretext build web, pretext view web or pretext generate -t web).
The second required attribute of <target> is @format, which must be one of html, pdf, latex, custom, epub, kindle, or braille (although the last three of these are still experimental, as of 9/1/2023).
With just these attributes, as with the manifest in Listing 5.2.4, the CLI assumes your project uses default values throughout. The following defaults are constucted from the default value for an attribute of the root <project> element with the default value for an attribute of a particular <target> element. Each of the two pieces can be overrided. The net default folders are:
  • The source is source/main.ptx.
  • The publication file is publication/publication.ptx.
  • Output is stored in output/ (with each target in a subfolder identical to the target’s name).
  • The staging directory to preview deploys is output/stage.
Again, each of these can be modified using the appropriate attribute of either the root <project> element or a particular <target> element.
In Table 5.2.5 and Table 5.2.6 we give all the attributes you can have on the <project> and <target> elements, respectively. Some attributes can be specified for both elements. In such cases, the values will be paths, and the path given in the <target>’s attribute will be relative to the path given in the <project>’s attribute. This can be useful, for example, if all targets have publication files in the same folder, but the files for some targets are different.
All paths described in Table 5.2.5 are given relative to the root of your project (the location of the project.ptx file).
Table 5.2.5. Attributes available for the <project> element.
Attribute Description
@ptx-version
Required. Must have value 2.
@source
Optional, default: source. Path to folder holding main source file.
@publication
Optional, default: publication. Path to folder holding publication file.
@output-dir
Optional, default: output. Path to folder in which output files/folders for each target will be created.
@site
Optional, default: site. Path to folder holding user-provided landing page for deploying multiple targets.
@stage
Optional, default: output/stage. Path to folder where deployable targets will be collected before they are deployed.
@xsl
Optional, default: xsl. Path to folder holding custom xsl files.
@asy-method
Optional, default: server. Valid values: server or local. Used to specify whether asymptote images should be generated using the server asymptote version or a local asymptote install.
Any file paths described in attributes of a <target> element are relative to a corresponding attribute value from the root <project> element.
Table 5.2.6. Attributes available for the <target> elements.
Attribute Description
@name
Required. The name you use when executing a CLI command.
@format
Required. Valid values: html, pdf, latex, epub, kindle, braille, webwork, and custom. The format the target will be built into.
@source
Optional, default: main.ptx. Path to the root source file of the project (relative to the value of the @source of <project>).
@publication
Optional, default: publication.ptx. Path to publication file (relative to the value of @publication attribute of <project>).
@output-dir
Optional, default: the value of @name. Path to folder in which output files/folders will be created (relative to the value of @output-dir attribute of <project>).
@output-filename
Optional, default: generated by pretext. Only valid for formats that produce a single output file. Path to output file to be built (relative to the value of @output-dir of the same <target> element).
@deploy-dir
Optional, no default. Path to subdirectory of deployed site where this target will live. If deploying multiple targets, then this attribute must have a value for it to be deployed.
@xsl
Optional, no default. Required when @format is custom. Path to custom XSL file (relative to the value of @xsl attribute of <project>).
@latex-engine
Optional, default: xelatex. Valid values: xelatex, pdflatex, or latex. Only used on targets that build with latex, to specify what latex command to call in that step.
@braille-mode
Optional, default: emboss. Valid values: emboss or electronic. Only used when @format is braille, to specify the mode for braille.
@platform
Optional, no default. Only valid when @format is html. Valid values: runestone. Used to specify that the target will be hosted on Runestone.
@compression
Optional, no default. Only valid when @format is webwork or html and @platform is not runestone. Valid values: zip. Results in output being compressed (as .zip file).
@asy-method
Optional, default: server. Valid values: server or local. Overrides the @asy-method attribute on <project>.

Example 5.2.7. Example Project Manifest.

To illustrate how the relative paths work, with attributes on both <project> and <targets> elements, consider the following manifest:
<?xml version="1.0" encoding="utf-8"?>
<project ptx-version="2" source="src" output-dir="out">
    <targets>
        <target
            name="web"
            format="html"
            output-dir="web" />
        <target
            name="print"
            format="pdf"
            source="main-print.ptx"
            publication="pub/publication.ptx"/>
    </targets>
</project>
Here, the web target, with format html, will build from the root PreTeXt file "src/main.ptx", using the publication file "publication/publication.ptx", and will place the output in the folder "out/web".
The print target, with format pdf, will build from the file "src/main-print.ptx", using the publication file "publication/pub/publication.ptx", and will place the output in the folder "out/print".
In addition to the attributes available for <target> elements, there is one optional child element, <stringparams>, which can be used to specify string parameter options (see Section 28.1). These are specified using an attribute for the name of the string parameter, and the value of the attribute is the value of the string parameter. Multiple string parameters are set using multiple attributes on the single <stringparams> element.

Subsection 5.2.8 Executables

PreTeXt uses several external tools to build and generate assets. The CLI will automatically find these tools if they are installed in the default location for your operating system. If you have installed them in a non-standard location, you can specify the path to the executable in a executables.ptx file, at the root of your project. In Listing 5.2.8 we give the defaults and formatting of such a file.
<?xml version="1.0" encoding="utf-8"?>
<executables
      latex="latex"
      pdflatex="pdflatex"
      xelatex="xelatex"
      asy="asy"
      sage="sage"
      pdfpng="convert"
      pdfeps="pdftops"
      node="node"
      liblouis="file2brl" />
Listing 5.2.8. Example of version 2 executables file

Warning 5.2.9.

Prior to version 2 of the CLI, these executables were contained in the project.ptx file. If you are using a version prior to 2.0, see Appendix O.

Subsection 5.2.9 Getting help

In addition to checking pretext --help, pretext build --help, pretext view --help, etc, you have a few options when you run into trouble. If you are getting errors that don’t make sense, even after trying follow the suggestion of the error messages, look at the time-stamped log files inside the logs folder (or the “cli.log” file if you are using a CLI version prior to 2.0), which includes debug-level log messages. You can also run the CLI using this higher level of verbosity using the -v debug option, which must go right after pretext command, before the subcommands (build, deploy, etc.). That is, enter the following for example,
$ pretext -v debug build web
You can also ask for help on the google support group
 5 
groups.google.com/g/pretext-support
. When you post there, please run pretext support from inside your project’s folder and copy the output into your help request.