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:
pretext --version
You should get back something like 0.4.1
. If this doesn't work, try starting the previous line with python -m
, 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.
You can upgrade the CLI to the most recent version through PIP using the command:
pip install pretextbook --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 build
with new
or view
or etc.)
Subsection 5.2.1 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
.
The new project includes a file “project.ptx” which we call the project manifest. This is an XML file that specifies options for converting your source into different target outputs. We will describe the contents of this file more in a bit.
Subsection 5.2.2 Converting: pretext build
To convert your source into one of the available output formats, say HTML, run the command:
pretext build html
Here “html” is the @name
of one of the targets in the project manifest (project.ptx
).
Subsection 5.2.3 Viewing output: pretext view
After you convert your source into, say HTML, you can view the output using the command:
pretext view html
This will direct you to open a local server at a provided address (perhaps http://localhost:8000
). Replace “html” in the above with other build targets as appropriate.
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 html --watch
This currently only supports HTML-format targets.