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
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:
For the file containing the
<chapter>tag for the chapter on mammals, place the attribute
on the outermost tag in the file.
<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
@hrefattribute 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:nsdeclaration 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
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
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.