Skip to main content

Section 4.2 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. 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:

  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.

  3. Add the switch -xinclude to 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 xsltproc it might be necessary to use two dashes for the switch, --xinclude.

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 -xinclude switch. 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:ns delaration 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 <mathbook> 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.

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.25 for some of the finer points of this topic.