Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller

Section 5.3 Modular Source Files

For a large project, such as a book, you will likely want to split up your source into logical units, such as chapters and sections. The PreTeXt-CLI supports an inclusion mechanism automatically (see Chapter 46 for what you need to do different for xsltproc).
Suppose your book on animals has a chapter on mammals with a section on monkeys. Then you need to do the following:
  1. For the file containing the <chapter> tag for the chapter on mammals, place the attribute
    xmlns:xi="http://www.w3.org/2001/XInclude"
    on the outermost tag in the file.
  2. Within the <chapter> element for the chapter on mammals, add the line <xi:include href="monkeys.xml" /> to “pull in” the section on monkeys at that location. The @href attribute can point to a file in a subdirectory, but will be interpreted relative to the location of the file containing the mammal chapter element.
Several comments are in order.
  • Begin small and start a project without using modular files. Modularizing seems to add a layer of complexity that sometimes obscures other beginner’s errors. So get comfortable with a single source file before branching out.
  • The XML specification requires that a source file only contain a single outermost element. So for example, two <chapter> elements cannot go into the same file as simultaneous outermost elements.
  • There will always be a “main” file that contains the <pretext> element as its single outermost element. In this Guide we will call this the top-level file.
  • Any file that uses an <xi:include> element will need the xml:ns declaration on the outermost element. So in our animal book example, the top-level file, which presumably includes several chapter files, would need this declaration on the <pretext> element.
  • In practice, there is not a lot to be gained by creating a subdirectory structure mirroring your modularization—all your source files can go into one big directory and the XML hierarchy will take care of the organization. I do sometimes like to name my files accordingly, so for example chapter-mammals.xml and section-monkeys.xml.
  • When you validate your source (see Section 5.4 and Chapter 6) you will always point to the top-level source file (the one with the <pretext> tags).
The book generated by pretext new demo has modular source, so is a nice starting point to see how this works. Other examples are the sample book in examples/sample-book amply demonstrates different ways to modularize parts of a project (but in no way should be taken as best practice in this regard). This guide, in doc/author-guide is a simple example of modular source files, and might be a good template to follow for your book. See Section 4.37 for some of the finer points of this topic.
PrevTopNext