Skip to main content

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 43 for what you need to do different for xsltproc).

Let us suppose that 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.

  • 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 “master” 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 main source file (the one with the <pretext> tags).

The book generated by pretext new book 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.28 for some of the finer points of this topic.