The PreTeXt Guide

The customization feature allows you to create two or more versions of your text for slightly different audiences. To do this, an author defines custom elements that find their translations in a file specified in the publication file. Multiple customization files can then be used to build different versions of the text. For example, we might want to create two versions of our AOTA book, one for zoologists and one for laypeople. For the zoologist edition we want animal names to be scientific names, but in the edition for laypeople we want to use common names. The rest of the text is identical. To execute this, we make every animal name a custom element and create a customization file for each of the two versions.

Say we want to write a sentence that reads “The IUCN red list classification of the western lowland gorilla is critically endangered” in the layperson’s edition and “The IUCN red list classification of the Gorilla gorilla gorilla is critically endangered” in the zoologist’s edition. We begin by writing the sentence in the source and creating a <custom> element as a place-holder for the name of the gorilla:

The <init>IUCN</init> red list classification of
the <custom ref="gorilla-name"/> is critically endangered.

Then the file of translations will contain a <custom> element, with a @name attribute that has value gorilla-name, and whose content is the translation.

Once you have placed <custom> elements in your source, you need to create one or more files of translations. To stay organized you might choose to place them in a directory of their own. The customization file opens with a special element and then contains a definition for each customization.

For the example above, here is the beginning of the customization file we might name customizations/zoologist.ptx.

<pi:customizations xmlns:pi="http://pretextbook.org/2020/pretext/internal">
  <!-- Name of Western mountain gorilla -->
  <custom name= "gorilla-name">
    <taxon>Gorilla gorilla gorilla</taxon>
  </custom>
</pi:customizations>

Note that employing a common value for the @name attribute and the @ref attribute makes the association for the replacement in the source. Next, we would also create a customization file named “customizations/layperson.ptx” that looks like the following.

<pi:customizations xmlns:pi="http://pretextbook.org/2020/pretext/internal">
  <!-- Name of Western mountain gorilla -->
  <custom name= "gorilla-name">western lowland gorilla</custom>
</pi:customizations>

Once the customization files are created, the element <custom ref="gorilla-name"/> can be used throughout the text and will populate automatically depending on which customization file is specified in the publication file.

When choosing names to use as values for the @ref and @name attributes, develop a consistent scheme that will make sense to other authors. Do not use spaces or capital letters. This name will never be visible to readers but should be easy for developers to understand. Placing careful comments in one “main” customization file can help other authors create new customizations that are accurate.

Note that this functionality is limited when it comes to irregular plurals and capitalization. Take care with the placement of custom elements: they will not, for example, capitalize automatically at the beginning of a sentence.

See Subsection 44.7.3 for the mechanics of specifying a file of customizations via the publication file.