Subsection 4.14.5 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
pretext script can sometimes help (Chapter 47). 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 PreTeXt 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.
