Section 6.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 47 for what you need to do different for
bookon animals has a
chapteron mammals with a
sectionon monkeys. Then you need to do the following:
- 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.
- 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
@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.
- 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:nsdeclaration 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
- 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 bookhas modular source, so is a nice starting point to see how this works. Other examples are the sample book in
examples/sample-bookamply 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-guideis a simple example of modular source files, and might be a good template to follow for your book. See Section 5.35 for some of the finer points of this topic.