Section 5.2 The PreTeXt-CLI
Here we will outline the functionality of the PreTeXt-CLI. Instructions for installing this command line interface can be found in Section 2.1.
First, to verify that you have the CLI installed correctly, enter the following command in a terminal:
You should get back something like
1.0.2. If this doesn't work, try starting the previous line with
python -m (or maybe
python3 -m on Mac/Linux), which might help if your PATH is not set up correctly. In fact, prepending
python -m to all commands in this section might be necessary, depending on your system.
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
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
Subsection 5.2.1 Starting a New Project:
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.
Inside the “new-pretext-project” folder, you will find the following folders and files:
A folder to place static (external) assets, such as images or data files, that you will include in your project, for example, with
A folder that will hold assets (such as images) generated from source, using the
pretext generatecommand. You should not manually edit any contents of this folder.
A folder to hold your publication files. One publication file is included, but you can have as many as you want. See Chapter 42.
A folder to hold all your PreTeXt source files. These are the main files you will edit to control the content of your project.
A file containing a list of folders and files that should not be tracked by git if you use it for version control.
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.6.
A file that you can use to describe your project.
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.2 Converting:
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
Subsection 5.2.3 Viewing output:
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 local server at a provided address (perhaps
http://localhost:8000). Replace “web” in the above with other build targets as appropriate.
If you are on your own machine (i.e., not CoCalc),
pretext view will attempt to open your default program for the type of file you are opening. You can prevent this attempt using the
pretext view command accepts a useful option for small projects that allow you to automatically rebuild your source every time you save it. Try:
pretext view web --watch
(You can use
-w as a shorthand for
--watch.) This currently only supports HTML-format targets.
When you are done, stop the server by hitting
In addition to the watch option
-w, you can use the flags
-b to build before viewing,
-g to generate assets before viewing, or combine these with
Note that the project is only viewable on your local machine (even if you are working in 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.4 Generating assets:
Some PreTeXt elements require special processing: WeBWorK exercises,
<asymptote> images, as well as previews for embedded youtube videos. We call these elements “assets” or “generated assets”. To generate the assets, run the following command.
You can also generate assets and build at the same time, using
pretext build -g web which will generate all assets for the target named “web”.
This will generate all assets in the default formats for the first target in the project manifest. If you need formats for another target, you can specify the target name with the
-t flag, as in, for the target named “print”,
pretext generate -t print
Generating assets can be time consuming, so likely you will not want to repeat this step unless you have edited one of the elements of a particular asset type. To further speed up the process, 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
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
Subsection 5.2.5 Hosting your project:
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 1 , 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:
This copies the contents of the html output folder into
docs, commits the changes, and pushes them to GitHub. All you need to do then is ensure that you enable the pages feature in your GitHub repository (
Pages, then set to deploy from a branch: gh-pages).
If your project is not already tracked on GitHub, the CLI will walk you through the steps you need to get set up.
Subsection 5.2.6 The project manifest:
The project manifest, always named “project.ptx”, contains information about each target you will build, as well as the names of executables of external tools that might be needed for building targets and generating assets.
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 for you to copy from to your current manifest.
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. Below we show a sample manifest (you can also look at the result of
pretext new or
<?xml version="1.0" encoding="utf-8"?> <project> <targets> <target name="web"> <format>html</format> <source>source/main.ptx</source> <publication>publication/publication.ptx</publication> <output-dir>output/web</output-dir> </target> <target name="print" pdf-method="xelatex"> <format>pdf</format> <source>source/main.ptx</source> <publication>publication/publication.ptx</publication> <output-dir>output/print</output-dir> </target> <target name="print-latex"> <format>latex</format> <source>source/main.ptx</source> <publication>publication/publication.ptx</publication> <output-dir>output/print-latex</output-dir> </target> <target name="subset"> <format>html</format> <source>source/main.ptx</source> <publication>publication/publication.ptx</publication> <output-dir>output/subset</output-dir> <stringparam key="debug.skip-knowls" value="yes"/> <xmlid-root>ch_first</xmlid-root> </target> </targets> <executables> <latex>latex</latex> <pdflatex>pdflatex</pdflatex> <xelatex>xelatex</xelatex> <pdfsvg>pdf2svg</pdfsvg> <asy>asy</asy> <sage>sage</sage> <pdfpng>convert</pdfpng> <pdfeps>pdftops</pdfeps> <node>node</node> <liblouis>file2brl</liblouis> </executables> </project>
Inside the root
<project>, we have
<executables>. The latter contains the commands you would call on the terminal to execute the specified command. You can likely leave this as is, but if a command is not on your PATH, you could put the full path to the executable here.
Each element of
<targets> is a
<target> that has a
@name attribute. The name (e.g., web, print) is what you specify when you run build, view, or generate assets for a specific target (so
pretext build web,
pretext view web or
pretext generate -t web).
The children of a
<target> start with
<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 8/10/2022). If the format is “pdf”, you can specify the latex engine used to process the .tex file by using the
@pdf-method attribute on
Next we have
<source> which contains a (preferably) relative path to the main source file you will compile. Different targets might have different main source files, in case you create a separate version of your project that includes only some chapters, for example.
<publication> element specifies the path the the publication file for the target. Different targets can have different publication files.
<output-dir> element gives the path to the folder where the output of
pretext build should go. It is strongly recommended that this be a subfolder of “output”, which is ignored by git by default. Again, different targets can, and probably should, have different output folders.
The above tags are required for each target. There are also some optional tags that can further customize the behavior of a particular target. The
<stringparam/> tag with attributes
@value can be used to specify stringparameter options (although most of the stringparameters that were previously used to control output are now controlled by the publication file). The
<xmlid-root> element is used to specify the xml:id of a division of a project for building only that subset of the project (useful for quickly testing just one chapter or section).
The last optional element we will mention is the
<xsl> element. Here you would provide the path to a custom xsl file that itself calls the standard pretext-provided xsl. To import the standard xsl file (say pretext-common.xsl) near the top of the custom xsl file, import it using
<xsl:import href="./core/pretext-common.xsl"/>. To see an example of this used to build a revealjs slideshow, try
pretext new slideshow. Note that if you use the “custom” format, the
<xsl> element is required, although it can be used on any format. This is also how you would use the custom latex styles provided by pretext.
Subsection 5.2.7 Getting help
In addition to checking
pretext build --help,
pretext generate --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 file “cli.log”, which includes even 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 (
generates, etc.). That is, enter the following for example,
pretext -v debug build web