Section4.2Modular 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.
xsltproc supports an include mechanism that makes this possible. 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.
Add the switch
-xincludeto your invocation of
xsltproc, just after
xsltproc, but before the filenames for the stylesheet and the master source file. Note that for some versions of
xsltprocit might be necessary to use two dashes for the switch,
So now a typical invocation (using one dash) might look like
xsltproc -xinclude xsl/mathbook-html.xsl ~/books/aota/animals.xml
Note that when you invoke
xsltproc the default directory can be far away from your source, and the processor will locate all the component files of your project through the relative file locations in the
@href attribute. 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.
I am forever forgetting the
-xincludeswitch. Empty output, or cryptic error messages, are your first clue to this simple, but common, mistake.
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:nsdelaration 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 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 6.20 for some of the finer points of this topic.