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
@componentattribute 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
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
@includeattribute of the
source/includeelement 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
@componentvalue is in the list in
@includewill be included in the source that will be converted.
- An element whose
@componentvalue is not in the list in
@includewill not be included in the source that will be converted.
- If there is no
@includeattribute 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
@includeto an empty value (
include="") achieves the opposite effect and excludes every component from the source that will be converted.
Note that we have not experimented with one component nested inside another. Once an element is excluded because it is in some component, all of its contained source is gone and never coming back. But it should be possible to include an element via a component, and exclude portions of that element via a different component.
Subsection 27.2.3 Types of Versions
Here are three typical use cases for versions.
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
labscomponents, but exclude content in the
An “annotated” Instructor's Version can be accomplished with additional material, perhaps in a selection of
<commentary>elements looking like like
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:includemechanism. 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
videoscomponent. 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
novideoscomponent. Now you would typically include exactly one of
novideoswithin 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.
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
colorcomponent, and the second is in the
nocolorcomponent. 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.
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
<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.