Skip to main content

Section 6.11 Images

Subsection 6.11.1 Raster Images

A raster image is an image described pixel-by-pixel, with different colors and intensities. Photographs are good examples. Common formats are Portable Network Graphics (PNG) and Joint Photographic Experts Group (JPEG, JPG), which will both work with pdflatex and modern browsers. JPEG are a good choice for photographics since they are compressed on the assumption they will be viewed by a human, while PNG is a lossless format and good for line art, diagrams and similar images (if you do not have vector graphics versions, see below).

To use these images, you simply provide the filename, with a relative path. A subdirectory such as images is a good choice for a place to put them. It is your responsibility to place these images where the output will find them or where the HTML output will find them. The XML would look like:

<image source="images/crocodiles.png" width="50%" />

Typically you would wrap this in a <figure> that might have an @xml:id attribute for cross-references, with or without a caption. There is no @height attribute, so the aspect ratio of your image is your responsibility outside of PreTeXt. The @width attribute is a percentage of the available width of the text (outside of a <sidebyside> panel). Default width is typically 90%.

You may also provide a <description> which will aid accessibility for electronic formats. Keep such readers in mind and provide as much description as possible. Keep the markup simple, since this will typically migrate to an HTML attribute that cannot contain any structure. Be careful to avoid double-quotes. For example,

<image source="images/crocodiles.jpeg" width="50%">
    <description>Five crocodiles partially submerged in the shallows.</description>

Subsection 6.11.2 Vector Graphics

An image is a vector graphic if the file describes the geometric shapes that constitute the image. So a simple diagram would be a good candidate, but a photograph would not. Popular formats are Portable Document Format (PDF) and Scalable Vector Graphics (SVG). You will get the best results with PDF images in output and SVG images for HTML. The principal advantage of these formats is that they scale (big or small) smoothly, along with fonts. This is critical when you cannot predict the screen size for a reader of an electronic version.

Unless you describe these images with a language (see next subsection), you are responsible for providing the PDF and SVG versions. The pdf2svg utility is very useful if you have PDF images only. To use these images, you simply follow the instructions above, but do not include a file extension. This alerts the conversion to use the best possible choice. So presuming we had files images/toad-life-cycle.pdf and images/toad-life-cycle.svg, an example would be:

<image source="images/toad-life-cycle" width="85%">
    <description>Diagram of the four stages of a toad's life.</description>

Subsection 6.11.3 (*) Images Described by Source Code

To be written once elements and tags solidfy, see sample article for examples.

Subsection 6.11.4 Image Archives

As an instructor, you might want to recycle images from a text for a classroom presentation, a project handout, or an examination question. As an author, you can elect to make images files available through links in the HTML version, and it is easy and flexible to produce those links automatically.

First, it is your responsibility to manufacture the files. For making different formats, the mbx script can sometimes help (Chapter 9). The Image Magick convert command is a quick way to make raster images in different formats, while the pdf2svg executable is good for converting vector graphics PDFs into SVGs. Also, to make this easy to specify, different versions of the same image must have identical paths and names, other than the suffixes. Finally, the case and spelling of the suffix in your MBX source must match the filename (e.g. jpg versus JPEG). OK, those are the ground rules.

For links for a single image, add the @archive attribute to the <image> element, such as

<image  ...  archive="pdf svg">

to get two links for a single image.

To have every single image receive an identical collection of links, in docinfo/images place an <archive> element whose content is the space-separated list of suffixes/formats.

<archive>png JPEG tex ods</archive>

will provide four links on every image, including a link to an OpenDocument spreadsheet.

For a collection of images that is contained within some portion of your document, you can place an @xml:id on the enclosing element and then in docinfo/images place

<archive from="the-xml-id-on-the-portion">svg png</archive>

to get two links on every image only in that portion (chapter, subsection, side-by-side, etc.). The @from attribute is meant to suggest the root of a subtree of your hierarchical document. If you use this, then do not use the global form that does not have @from.

You may accumulate several of the above semi-global semi-local forms in succession. An image will receive links according to the last <archive> whose @from subtree contains the image. So the strategy is to place general, large subtree, specifications early, and use refined, smaller subtree specifications later. For example,

<archive from="the-xml:id-on-a-chapter">svg png</archive>
<archive from="the-xml:id-on-the-introduction">jpeg</archive>
<archive from="the-xml:id-on-a-section-within" />

will put two links on every image of a chapter, but just one link on images in the introduction, and no links at all on every image image within one specific section. Again, do not mix with the global form. You can use the root document node (e.g. <book>) for @from to obtain a global treatment, but it is unnecessary (and inefficient) to provide empty content for the root node as first in the list—the same effect is the default behavior.

Notice that this facility does not restrict you to providing files of the same image, or even images at all. You could choose to make data files available for each data plot you provide, as spreadsheets, or text files, or whatever you have, or whatever you think your readers need.

Finally, “archive” may be a bit of a misnomer, since there is no historical aspect to any of this. Maybe “repository” would be more accurate. Though for a history textbook, it might be a perfect name.