Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller

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