The PreTeXt Guide

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 (2.13.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.).

$ pip install pretext --upgrade

$ pip install pretext --upgrade --pre

$ pip install pretext=="2.13.5"

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, or pretext new course for a collection of course documents.

Once you build your project, you will get a folder called “output”. Do not edit the contents of this folder manually.

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.

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.

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

⁴

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.

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).

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.5. Note this is version 2 manifest; for a comparison of “legacy” manifests and the current format, see Appendix P.

<?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>

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).

In Table 5.2.6 and Table 5.2.7 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.6 are given relative to the root of your project (the location of the project.ptx file).

Any file paths described in attributes of a <target> element are relative to a corresponding attribute value from the root <project> element.

<?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>

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.

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.9 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"
      pdfeps="pdftops"
      node="node"
      liblouis="file2brl" />

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

⁵

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.