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 , which has a terminal and has all the required software (python,
LaTeX, 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 LaTeX. Try xelatex --version to see if you already have this.
Any text editor.
Visual Studio Code 2 is an excellent choice (and has an extension,
PreTeXt-tools 3 , 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:
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.4.2, 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.1.0:
pip install pretext=="1.1.0"
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:
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:
- 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"/>.
- generate-assets
A folder that will hold assets (such as images) generated from source, using the pretext generate command. You should not manually edit any contents of this folder.
- publication
A folder to hold your publication files. 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:
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:
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 --no-launch flag.
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:
(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 CTRL+C
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.5 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”. To generate the assets, run the following command.
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
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.
Subsection 5.2.6 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 , 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 (Settings, then 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.7 The project manifest: project.ptx
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 pretext init).
<?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 <targets> and <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 <target>.
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.
The <publication> element specifies the path the the publication file for the target. Different targets can have different publication files.
The <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
@key and
@value can be used to specify string parameter options (
Section 28.1. 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.8 Getting help
In addition to checking pretext --help, 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 (build, generates, 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 . When you post there, please run
pretext support from inside your project’s folder and copy the output into your help request.
marketplace.visualstudio.com/items?itemName=oscarlevin.pretext-tools
groups.google.com/g/pretext-support
