PreTeXt Cheatsheet

Subsection7.1figure

The gold standard for graphics to include in PreTeXt documents is, well, complicated. If you're only working with HTML output, then SVG is what you want. If you're producing PDF by using LaTeX, then you'll also want PDF graphics files. Fortunately, it's not too hard to convert between these formats on the command line.¹Windows users have run into some problems in this area. Since conversion is a rare task, it may be easiest to do in a cloud environment like CoCalc. Just be sure to keep track of which file type is your master file and which file type is produced from the other. PNG is also supported by modern web browsers and LaTeX, so that's a good option when vector graphic formats like SVG and PDF are not available or appropriate.

<figure xml:id="fig-graph">
    <caption>A small graph (from <booktitle>Applied Combinatorics</booktitle>
    by Keller and Trotter)</caption>
    <image source="images/small_graph" width="20%"/>
</figure>

The code in Listing 7.1 produces the following output:

Note that the path to the image file does not include the file extension. When you run xsltproc, the output format you're generating will determine what gets added on so that the right file is grabbed. If your browser says it can't find the image file, make sure that the SVG file is in the correct location relative to the HTML file. Here, we need a directory called images that lives next to our HTML files with a file called small_graph.svg inside that directory. If using a PNG file, put the extension in the filename so that the file is used in both HTML and LaTeX.

Subsection7.2sidebyside

One of the more complex pieces of code in PreTeXt, by most accounts, is that used for positioning objects (usually figures) next to each other. If you've tried to do this in LaTeX, you know that it can be challenging on a good day. Fortunately, PreTeXt does the heavy lifting for us here for both LaTeX and HTML.

We include two examples here. The first places the sidebyside directly in the current division and places a figure with a caption inside the sidebyside. The second puts the sidebyside inside figure and then uses an image not contained in a figure to include the graphic. It's possible to do all sorts of nesting and get nice subnumbering automatically. The sample article demonstrates all the capabilities of sidebyside.

<sidebyside widths="25% 25%" valign="middle">
    <figure>
        <caption>Small graph</caption>
        <image source="images/small_graph" />
    </figure>
        <p>We can put a paragraph here. Yes, a paragraph. Isn't this
        the most exciting paragraph that you've ever seen? It goes on
        and on and on and on and on and on. We want to put enough
        here to make it wrap, really, is all. Let's hope that this is enough.</p>
</sidebyside>

The code in Listing 7.3 produces the following output:

We can put a paragraph here. Yes, a paragraph. Isn't this the most exciting paragraph that you've ever seen? It goes on and on and on and on and on and on. We want to put enough here to make it wrap, really, is all. Let's hope that this is enough.

<figure>
    <caption>A graphic next to a paragraph of text.</caption>
    <sidebyside widths="25% 35%" margins="0% 0%" valigns="bottom top">
        <image source="images/small_graph" />
        <p>We can put a paragraph here. Yes, a paragraph. Isn't this
        the most exciting paragraph that you've ever seen? It goes on
        and on and on and on and on and on. We want to put enough
        here to make it wrap, really, is all. Let's hope that this is enough.</p>
    </sidebyside>
</figure>

The code in Listing 7.5 produces the following output:

We can put a paragraph here. Yes, a paragraph. Isn't this the most exciting paragraph that you've ever seen? It goes on and on and on and on and on and on. We want to put enough here to make it wrap, really, is all. Let's hope that this is enough.

Another use for sidebyside occurs when you want to center a graphc or tabular environment (or a number of other things) on a line by itself but without a caption and number.

Subsection7.3LaTeX-generated images

PreTeXt makes it straightforward to embed LaTeX code that produces images (such as TikZ) into your source files. xsltproc basically just dumps your code out to your LaTeX file so that it compiles nicely. However, for HTML display, you will need SVG graphic files. This is where the mbx script comes in. Running the mbx script frequently requires patience, particularly on Windows, so settle in with an experienced user before attempting the steps in this subsection.

Our example here just illustrates using TikZ to make a simple figure (the Hasse diagram of a poset), but lots of other LaTeX graphics packages can be used. One step required is to put

<latex-image-preamble>
    \usepackage{tikz}
</latex-image-preamble>

in the docinfo tag of your main file. latex-image-preamble is used to set up the preamble that should be used for making SVG images from your PreTeXt source. Macros that you wish to use more broadly should be put inside macros inside docinfo.

<figure xml:id="fig-tikz">
    <caption>A figure generated with TikZ in <latex /></caption>
    <image width="15%" xml:id="poset">
        <latex-image >
            \begin{tikzpicture}
            \draw (0,0) -- (0,1);
            \draw (1,0) -- (1,1) -- (1,2) -- (1,3);
            \draw (0,0) -- (1,2);
            \draw (0,1) -- (1,0);
            \draw [fill] (0,0) circle [radius=0.1];
            \draw [fill] (0,1) circle [radius=0.1];
            \draw [fill] (1,0) circle [radius=0.1];
            \draw [fill] (1,1) circle [radius=0.1];
            \draw [fill] (1,2) circle [radius=0.1];
            \draw [fill] (1,3) circle [radius=0.1];
            \node [left] at (0,0) {$x$};
            \node [left] at (0,1) {$b$};
            \node [right] at (1,0) {$a$};
            \node [right] at (1,1) {$y$};
            \node [right] at (1,2) {$c$};
            \node [right] at (1,3) {$d$};
            \end{tikzpicture}
        </latex-image>
    </image>
</figure>

The code in Listing 7.7 produces the following output:

Well, that's not 100% true for HTML. If you just run xsltproc, your browser will display an error message about not being able to find the graphic file, since it doesn't exist. To generate the image, we have to run the mbx script.²Will the script someday be renamed the ptx script? Tune in again next time to find out! To do this, on the command line we run the following command (on a single line).

[path to mathbook]/script/mbx -c latex-image -f svg
                -d ./images [path to PTX source file]

This command assumes that we're in the directory where we usually run xsltproc to produce our HTML and that we want to put the images in a directory called images inside that directory.