Skip to main content

Section 3 Usage

For your convenience, documentation on using all features of the command-line interface may be viewed below, or displayed on the command line by using the --help option. Use pretext --help to see what commands are available, and (for example) pretext new --help to learn how to use each command.

Subsection 3.1 pretext --help Output

Usage: pretext [OPTIONS] COMMAND [ARGS]...

  Command line tools for quickly creating, authoring, and building PreTeXt
  documents.

Options:
  --silent   suppress basic feedback
  --verbose  show debug info
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  build    Build specified format target
  new      Provision a new PreTeXt document.
  publish  Prepares project for publishing on GitHub Pages.
  view     Preview built PreTeXt documents in your browser.


-------------------------------------------------------------------------------

Usage: pretext new [OPTIONS] [TITLE]

  Creates a subdirectory with the files needed to author a PreTeXt document.

  Usage: pretext new "My Great Book!"

Options:
  --directory PATH   Directory to create/use for the project. Defaults to a
                     subdirectory of the current path based on book title.
  --chapter TEXT     Provide one or more chapter titles.
  -i, --interactive  Interactively requests names of book chapters.
  --help             Show this message and exit.


-------------------------------------------------------------------------------

Usage: pretext build [OPTIONS] [[html|latex|diagrams|all]]

  Process PreTeXt files into specified format.

  For html, images coded in source (latex-image, etc) are only processed using
  the --diagrams option.

  If the project included WeBWorK exercises, these must be processed using the
  --webwork option.

Options:
  -i, --input PATH                Path to main *.ptx file  [default:
                                  source/main.ptx]
  -o, --output PATH               Path to main output directory  [default:
                                  output]
  -p, --publisher PATH            Publisher file name, with path relative to
                                  base folder
  --param TEXT                    Define a stringparam to use during
                                  processing. Usage: pretext build --param
                                  foo:bar --param baz:woo
  -d, --diagrams                  Regenerate images coded in source (latex-
                                  image, etc) using pretext script
  -df, --diagrams-format [svg|pdf|eps|tex]
                                  Specify output format for generated images
                                  (svg, png, etc).
  -w, --webwork                   Reprocess WeBWorK exercises, creating fresh
                                  webwork-representations.ptx file
  --pdf                           Compile LaTeX output to PDF using
                                  commandline pdflatex
  --config FILE                   Read options from configuration FILE
                                  specified.  [default: .ptxconfig]  Use
                                  `--config None` to run with standard default
                                  options.
  -sc, --save-config              save any options provided to local
                                  configuration file, specified with --config
                                  (or default ".ptxconfig")
  --help                          Show this message and exit.


-------------------------------------------------------------------------------

Usage: pretext view [OPTIONS]

  Starts a local server to preview built PreTeXt documents in your browser.

Options:
  --directory PATH                Directory containing built PreTeXt
                                  documents.  [default: output]
  --access [public|private|cocalc]
                                  Choose whether or not to allow other
                                  computers on your local network to access
                                  your documents using your IP address, with
                                  special option to support CoCalc.com users.
                                  [default: private]
  --port INTEGER                  Choose which port to use for the local
                                  server.  [default: 8000]
  --config FILE                   Read options from configuration FILE
                                  specified.  [default: .ptxconfig]  Use
                                  `--config None` to run with standard default
                                  options.
  -sc, --save-config              save any options provided to local
                                  configuration file, specified with --config
                                  (or default ".ptxconfig")
  --help                          Show this message and exit.


-------------------------------------------------------------------------------

Usage: pretext publish [OPTIONS]

  Prepares the project locally for HTML publication on GitHub Pages to make
  the built document available to the general public. Only supports the
  default `output/html` build directory. Requires Git and a GitHub account.

Options:
  --help  Show this message and exit.