The PreTeXt Guide

It is possible to include an image without a number or caption, centered on its own line by using <image>.

The gold standard for graphics to include in PreTeXt documents is, well, complicated. If you’re only working with HTML or EPUB output then SVG is what you want. If you’re producing PDF by using LaTeX, then you’ll also want PDF graphics files. If you plan to produce an ebook that can be read on Kindle devices, you will need PNG graphics files. Fortunately, it’s not too hard to convert between these formats on the command line.¹ In order to produce HTML, PDF, and Kindle, you will need to always have three files available. We recommend that you consistently pick PDF or SVG to be the one that you edit and then convert to the other format. Otherwise, you might have parabola.svg and parabola.pdf and parabola.png contain three different graphics, and then the different output formats for your project will have different images in them! PNG and JPEG are supported by modern web browsers, LaTeX, and Kindle, so that’s a good option when vector graphic formats like SVG and PDF are not available or appropriate.

<image source="small-graph" width="20%">
    <description>A graph on five vertices. One of the vertices is isolated, while the other four form a path on four vertices.</description>
</image>

Use of @width on an image must be a percentage, and for an <image> as in this example, the percentage is of the current line width. The code in Listing 19.1.1 produces the following output:

The example in Listing 19.1.1 also illustrates the use of <description>. We admit to not using a <description> for most of the other <image>s in this Guide, but doing so is strongly recommended for accessibility reasons. A reader who is unable to see the visual element of your book can use assistive technology to have the <description> read to them. As much as is practical, authors should endeavor to include <description>s for their <image>s.

Note that the path to the image file does not include the file extension. When you process your source, the output format you’re generating will determine what gets added on so that the right file is used. 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 or JPEG file across HTML, LaTeX/PDF, EPUB, and Kindle, put the extension in the filename so that the file is used for all. Many authors have an images directory that lives in the same directory as their PreTeXt source files and then produce the .tex file or HTML files in another directory. When doing so, you need to copy the images directory to be in the same directory as the .tex file before generating a PDF or in the same directory as your many .html files before viewing your HTML files in a web browser.