The PreTeXt Guide

The xinclude mechanism is not part of PreTeXt, per se. It is of some use for organizing your authoring, so you do not have mammoth files open in your text editor. As discussed in Section 5.3 there is very little value in modularizing so much that you have many very small files, and also almost no benefit whatsoever to using directory structure to duplicate the inherent tree-like structure of XML. Many small files, or deeply-nested directories, seem to be of little help and can cause more headaches than they are worth.

The xinclude mechanism automatically introduces a @xml:base attribute, which we need to account for in the RELAX-NG schema (Chapter 6). So we limit which PreTeXt elements may be the root element of an included file. The rough, general rule is that if an element can have a title, then it can be the root element of an included file. So in particular each of the divisions (<chapter>, <section>, etc.) is a candidate.

One special exception to this restriction is the use of text files, containing absolutely no markup at all. Two good examples are the <code> child of a <program> or the <latex-image> element used to describe an <image> by source code that LaTeX understands.

In both cases you can put the text content of these elements in a separate file, use the @href attribute of <xi:include> to point to the file, and then the twist is to set the @parse attribute to the value text. This has two general benefits. First, you now cannot have any XML in the file, so you do not have to have a single root element for the file (and so the schema imposes no restrictions). Second, you do not need to escape any problematic characters like ampersands and angle brackets (Section 4.4), nor use the misunderstood CDATA mechanism.

Additionally, in the case of <latex-image> you can park unsightly code away in files so you do not have to look at it, or you can create a small driver LaTeX program to test each one, or even better, you may want to use the same image more than once (maybe in different figures?) and can just include it repeatedly, while only ever editing the single copy.

Finally, the <input> and <output> children of <sage>, and <console> as well as the <code> of <program> are also candidates for this device. In particular, you may want to have the code for a program in its own file where you can test it easily with an interpreter or compiler. There is one gotcha. If you were to put a newline between <code> and <xi:include> there is the very real potential of unwanted whitespace bleeding into your PreTeXt output. Our suggested remedy uses an example from Bob Plantz. Convert

<program language="c">
    <code>
        <xi:include parse="text" href="intAndFloat.c"/>
    </code>
</program>

to

<program language="c">
    <code><xi:include parse="text" href="intAndFloat.c"/></code>
</program>

There are some fancy XSLT tricks you can employ to use more complicated content repeatedly. Your source will be less portable, and we do not support or recommend these techniques. But if you want a go anyway, see hints at www.sagehill.net/docbookxsl/DuplicateIDs.html. Note the reliance on xpointer(), and that the final technique is restricted to DocBook, a different XML vocabulary.