The PreTeXt Guide

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.

Some portions of your PreTeXt source get manipulated into additional files in particular formats (“generated”). Examples would include images given in LaTeX 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.