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.
