Versions

Section 27.2 Versions

A version is formed by including or excluding content coming from your PreTeXt source. This could be optional content, or it could be content that varies between versions. See Subsection 27.2.3 for specific examples.

Subsection 27.2.1 Marking Your Source

The @component attribute is used by an author to identify elements in the PreTeXt source. The value of the attribute is any name that makes sense to a publisher. Examples might be videos, labs, genome, or color. There is a (huge) un-component which is the collection of all elements not contained in an element that is in some named component. You can think of it as a default component, or an un-named component—it is content that will be in every version, no matter what.

Subsection 27.2.2 Forming a Version

Now, a publisher can elect to include or exclude all of the content of each component. This is accomplished with the @include attribute of the source/include element inside a publication file. The value of this attribute is a space-separated listing of some of the component names in use. An example minimal publication file could look like the following example. See Subsection 44.7.2 for the specifics.

<publication>
    <source>
        <version include="videos labs"/>
    </source>
</publication>

This attribute is interpreted according to these rules:

An element whose @component value is in the list in @include will be included in the source that will be converted.
An element whose @component value is not in the list in @include will not be included in the source that will be converted.
If there is no @include attribute in the publication file, the indication of the components are ignored and the entire source is processed. This would be the same as listing every component name in @include.
Setting @include to an empty value (include="") achieves the opposite effect and excludes every component from the source that will be converted.

You can nest one component inside another. But understand that once a PreTeXt element is excluded because the version in play does not include a certain component, then all of that element’s contained source is gone and never coming back. In other words, an element nested inside an excluded element cannot be influenced by whatever other component it may be assigned to. However, the converse is possible: include an element via a component, and exclude contained elements via a different component.

Subsection 27.2.3 Types of Versions

Here are three typical use cases for versions.

Additional Material.

Some material may not be desired for every output format. Some interactive material might not make sense in a printed book. Or perhaps certain types of exercises are included at the end of each chapter, or not. By putting these elements in components, they may be included or excluded via a publication file. The idea here is that some versions contain a subset of all the available, authored material. For example, a version might include content in the videos and labs components, but exclude content in the genome component.

An “annotated” Instructor’s Version can be accomplished with additional material, perhaps in a selection of <commentary> elements looking like like

<commentary component="instructor">

Alternate Treatments.

It may be possible to present a topic in two logically correct orders, but with substantial differences in how subtopics are treated. An example is the “early” or “late” treatment of transcendental functions in calculus. If the rearrangement is cosmetic, then an alternate main file can simply include divisions (chapters, sections) from separate files in a different order via the xi:include mechanism. See Section 5.3 for details.

When the two pathways through the material have common and distinct material, then two components can be employed and the publication file would always include exactly one component.

Or for excluded material you might create some sort of placeholder text indicating what is missing. So all <video> elements might be excluded by placing them into the videos component. But you might want to indicate that there is a video available in some other format and include an indication of its title or topic. So you could write a short paragraph next to the <video> and place it in a novideos component. Now you would typically include exactly one of videos or novideos within each publication file in use. If your <video> live in numbered figures, you could exclude the <figure> and use a numbered block, such a <remark> as the alternate and perhaps preserve numbering of later items.

Alternate Presentation.

This is an example similar to one Sean Fitzpatrick uses. His <docinfo> configures the way color is used in his TikZ diagrams. But instead he has two configurations, one for full color (HTML, electronic PDF), and another for black-and-white (printed hardcopy). The former is in the color component, and the second is in the nocolor component. If his project has color photographs, he could make careful gray-scale versions with specialized tools, and then place the resulting pair of <image> into each of the two components separately.

Releasing Material over Time.

Many authors are simultaneously publishers, and some are also instructors. And a few author-publisher-instructors like to “release” their material over time. This could be accomplished with versions. First there will be some base material like the front matter, back matter, and a preparatory Chapter 1. Now, mark Chapters 2 and 3 each with the component week1. Mark Chapter 4 with component week2. Mark Chapters 5, 6 and 7 with component week3. And so on.

Then the publisher file can be edited each week, or there can be multiple publisher files (one per week), which successively accumulate more components to include. For example,

<version include="week1"/>
<version include="week1 week2"/>
<version include="week1 week2 week3"/>

Note how the numbering of older material will not be affected by the addition of newer material, you will just want to be careful about forward cross-references from released material into un-released material. Of course, this example just uses chapters as the granular unit—you could use other divisions, or a mix.

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.

Numbering.

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.

Cross-References.

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.

Identifiers.

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 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.

Prev Top Next