CLI versions 1 vs 2

Appendix O CLI versions 1 vs 2

Oscar Levin

This appendix describes the differences between the PreTeXt-CLI version 1.x and 2.x. Generally, projects started in version 1 of the CLI will continue to work in version 2.

The primary difference between the versions of the CLI is the format of the project manifest (project.ptx): in version 1, most properties were described as XML elements, where they are now given as attributes. The functions of each attribute for the version 2 manifest is described in Subsection 5.2.7. Here we illustrate how these relate to the legacy elements.

In Listing O.0.1 we show a project manifest containing almost all options available. Then Listing O.0.2 shows the same project manifest in version 2 format.

<?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>
      <output-filename>mybook.pdf</output-filename>
    </target>
    <target name="runestone">
      <format>html</format>
      <source>source/main.ptx</source>
      <publication>publication/rs-publication.ptx</publication>
      <output-dir>published/mydoc-id</output-dir>
      <stringparam key="author.tools" value="yes"/>
      <stringparam key="html.css.extra" value="external/custom-styles.css" />
      <xsl>xsl/runestone.xsl</xsl>
    </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>

Listing O.0.1. Example of version 1 project manifest

<?xml version="1.0" encoding="utf-8"?>
<project ptx-version="2">
  <targets>
    <target
      name="web"
      format="html"
      source="source/main.ptx"
      publication="publication/publication.ptx"
      output-dir="output/web" />
    <target
      name="print"
      format="pdf"
      pdf-method="xelatex"
      source="source/main.ptx"
      publication="publication/publication.ptx"
      output-dir="output/print"
      output-filename="mybook.pdf" />
    <target
      name="runestone"
      format="html"
      platform="runestone"
      source="source/main.ptx"
      publication="publication/rs-publication.ptx"
      output-dir="published/mydoc-id"
      xsl="xsl/runestone.xsl">
      <stringparams author.tools="yes" html.css.extra="external/custom-styles.css" />
    </target>
  </targets>
</project>

Listing O.0.2. Example of version 2 project manifest

One advantage of version 2 of the CLI is that many of the options are now optional, or can be applied at the project level to all targets. The example shown above can be further simplified, as shown in Listing O.0.3, since most values are the defaults anyway.

<?xml version="1.0" encoding="utf-8"?>
<project ptx-version="2" publication="publication">
  <targets>
    <target
      name="web"
      format="html" />
    <target
      name="print"
      format="pdf"
      output-filename="mybook.pdf" />
    <target
      name="runestone"
      format="html"
      platform="runestone"
      publication="rs-publication.ptx"
      output-dir="published/mydoc-id"
      xsl="xsl/runestone.xsl">
      <stringparams author.tools="yes" html.css.extra="external/custom-styles.css" />
    </target>
  </targets>
</project>

Listing O.0.3. Simplified project manifest in version 2 format

Attributes for the <project> element that describe paths are common roots for any paths specified in <target> elements.

Notice that there is no longer a place to specify your executables in the manifest. This is because your executables are generally specific to a particular system, not a project. So instead, you specify executables in the file executables.ptx which is ignored by git. As with the version 2 manifest, the name or path to the executables are given as values of attributes. An example is shown in Listing 5.2.8.

The project manifest can be further simplified by setting attributes for the <project> element. See Subsection 5.2.7 for details.

Hopefully the examples above make it clear how the two versions compare for basic options. Below we list a few more differences between how you specify options in the version 1 and version 2 manifests.

@ptx-version: For the CLI to know you are using a version 2 manifest, you must include the @ptx-version attribute in the <project> element, with value “2”.
string parameters: In version 1, you would specify string parameters as a sequence of <stringparam> elements, each with @key and @value attributes. In version 2, you use a single <stringparams> element with attributes for each key set to the value for the string parameter’s value. See the example in Listing O.0.2
zipped output: In version 1, you could get a zipped version of your html output by setting the format of the target to html-zipped. In version 2, this is replaced by setting the @compression attribute to “zip” in the <target> element.
Braille options: In version 2, you specify what embossing method you use for Braille formatted targets using the @braille-mode attribute, with value either “emboss” or “electronic”.
WeBWorK Sets: In version 1, you could generate webwork sets using the "webwork-sets" format. In version 2, this is replaced by setting the @format attribute to “webwork” in the <target> element. Such a target can be compressed using the @compression attribute.
Local asymptote: In version 2, you can require that asymptote elements are generated using a local version of asymptote (instead of the server). You can specify this by setting the @asy-method attribute to “local”, in either the <target> element, or as an attribute of <project> to use this method for all targets.

Prev Top Next