DocBook 5: The Definitive Guide

Physical Divisions: Breaking a Document into Separate Files

The rest of this chapter describes how you can break documents into logical chunks, such as books, chapters, sections, and so on. Before we begin, and while the subject of the internal subset is fresh in your mind, let’s take a quick look at how to break documents into separate files.

Actually, we’ve already told you how to do it. If you recall, in the preceding sections we had declarations of the form:

<!ENTITY name SYSTEM "filename">

If you refer to the entity name in your document after this declaration, the system will insert the contents of the file filename into your document at that point. So, if you’ve got a book that consists of three chapters and two appendixes, you might create a file called book.xml, which looks like this:

<!DOCTYPE book [
<!ENTITY chap1 SYSTEM "chap1.xml">
<!ENTITY chap2 SYSTEM "chap2.xml">
<!ENTITY chap3 SYSTEM "chap3.xml">
<!ENTITY appa SYSTEM "appa.xml">
<!ENTITY appb SYSTEM "appb.xml">
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>My First Book</title>
&chap1;
&chap2;
&chap3;
&appa;
&appb;
</book>

You can then write the chapters and appendixes conveniently in separate files.

Documents that you reference with external parsed entities cannot have a Document Type Declaration. For example, Chapter 1 might begin like this:

<chapter xml:id="ch1"><title>My First Chapter</title>
<para>My first paragraph.</para>
…

But it must not begin with its own Document Type Declaration:

<!DOCTYPE ...