Skip to main content

The PreTeXt Guide

Subsection 27.2.4 Caveats for Creating Versions

There are some subtleties when you get fancy with manipulating your source this way, and we cannot protect you from every pitfall. You may get warnings for some of this. If you find new gotchas the hard way, please let us know.


It is very possible that material that is common between versions ends up with different numbers. An exception is if you subset by excluding material at the end of a division. This may be very natural for optional material. Then elect a numbering option that resets at the next division. In this way later “higher” numbers go missing, and it does not affect the sequence of earlier “smaller” numbers.


Do not create a cross-reference into content you might exclude, there may not be a target for the <xref>. You should get a warning about this. When you have alternate versions, you will need to think carefully about @xml:id and <xref> for your two versions. It is possible that what you think is common material might really need to go into two components because an <xref> points at a target that actually resides in two different components.


Allied with cross-referencing, be careful not to create source that had duplicate identifiers that are meant to be unique. You may get warnings about this situation.

Generated and External Files.

Some portions of your PreTeXt source get manipulated into additional files in particular formats (“generated”). Examples would include images given in or Asymptote syntax, and trace files for Runestone CodeLens environments. Depending on what you include or exclude in different versions, these files could have different characteristics. As one example, suppose you define different color palettes for use in images described using the TikZ language (inside a PreTeXt <latex-image> element). And then you employ the two different palettes by using versions and components to control which palette is used for each version. If you want to save these images (say, by commiting to a repository) rather than repeatedly regenerate them, then you need to save two different collections of generated images.
Versions are given by a publication file (Chapter 44), and the publication file allows you to specify which directory has these generated images (Section 5.6) so you can easily coordinate the generation and employment of these images with a coherent publication file.
You also sometimes bring “external” files to your project, such as JPEG images, which are not derived from your PreTeXt source. As in the example above, you could have color images for a version used to produce electronic formats and grayscale images for a version produced for physical printing. Again, the publication file could be used to employ a different collection/directory of external images for different versions via the options described in Section 5.6.