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:
<!ENTITYnameSYSTEM "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 chapter>
<chapter xmlns="http://docbook.org/ns/docbook"
xml:id="ch1">
<title>My First Chapter</title>
<para>My first paragraph.</para>
…It is also possible to construct documents from different files using XInclude. Recasting the previous example using XInclude yields:
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
<title>My First Book</title>
<xi:include href="chap1.xml"/>
<xi:include href="chap2.xml"/>
<xi:include href="chap3.xml"/>
<xi:include href="appa.xml"/>
<xi:include href="appb.xml"/>
</book>Notice that we can completely omit the Document Type Declaration in this case, but we must declare the XInclude namespace.
The essential trade-offs between external parsed entities and XInclude are:
XInclude can be used in a document that does not have a Document Type Declaration. Many web services applications (ones that rely on SOAP, anyway) forbid a Document Type Declaration and therefore cannot use entities of any sort.
The documents referenced by XInclude are complete, free-standing XML documents. They can declare their own local entities using a Document Type Declaration. Documents referenced by external parsed entities cannot have a Document Type Declaration. If they use entities, those entities must be declared in the document that does the including.
External parsed entities can have multiple top-level elements. They are not required to be “single rooted.” XIncluded documents must be wholly well-formed XML.
All XML validators support external parsed entities. (Validators that do not are not conformant XML processors.) XInclude is a separate specification and may or may not be supported by tools.
The XML validator expands entities and therefore “sees” the entire document. This means that ID/IDREF links can freely cross entity boundaries. Because XIncluded documents are free-standing, a document containing an IDREF that crosses a document boundary cannot be valid. It can be well-formed, and processors can do the right thing, but the validator cannot determine that the document is valid. What’s more, the same ID value can occur in several XIncluded documents without causing a validity error. This may cause subsequent processing to fail.
As time passes, the use of DTD-based mechanisms like entities is diminishing. If you have an eye on the future, to the extent that it is practical, it is probably better to use XInclude than entities.