Skip navigation links
4.4.2 Referring to Files in Other Directories »
Section Navigation      [Toggle]

4.4.1. Partitioning Document Content into Multiple Files

A document file can include document content directly (inline), or it can reference its parts by using XInclude directives. For a longer document, the usual structuring arrangement uses a “main” document file and a separate file per chapter. The main file contains the root element, the document title, the “info” element, and XInclude directives that refer to the chapter files. For example, the MySQL Test Framework Manual has a main file named mysqltest.xml that looks like this: 

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % all.entities SYSTEM "all-entities.ent">
  %all.entities;
]>
<book id="mysql-test-framework" lang="en">

  <title>The MySQL Test Framework</title>

  <bookinfo>
    ... standard info element parts ...
  </bookinfo>

  <xi:include href="preface.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  <xi:include href="introduction.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  <xi:include href="components.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  <xi:include href="tutorial.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  <xi:include href="programs.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  <xi:include href="command-reference.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>

  <index/>

</book>

XInclude directives are used for files that have XML (or perhaps text) content, but not for files that define entities. Entity files should be listed in the DOCTYPE declaration. (See Section 4.4.4, “Entities and Entity Files”.)

A DocBook content file that is referenced via an XInclude directive must itself be a valid DocBook file. That is, it must begin with an XML declaration and DOCTYPE declaration, and it must have a single root element. For example, you cannot have two <chapter> elements in the file. You must have two files, each containing one <chapter> element.

Sometimes document content is stored in a file and referenced via XInclude for reasons that have nothing to do with document length:

  • Some pieces of content are so stereotypical that they are the same for every document (or at least for several documents). The legalnotice.en.xml file is like this. In such cases, we put the content in a file, copy it to every document directory where it's needed, and refer to it from within each document via XInclude.

  • If content is used by multiple documents, put it in a separate file and include it in those documents by using XInclude. Files in the refman-common directory are instances of this concept. For example, the copyright.en.xml file contains the full Reference Manual copyright notice.

  • Some documents contain program-generated content. In such cases, it's usually easiest to use a separate file for this content so that you can simply run the program again to update the file. Examples of this are the Reference Manual files that list SQL reserved words and error messages. The reserved words and error messages vary per version of the manual, but are generated for each manual by running programs that parse server source files in the appropriate source tree.

The MySQL Reference Manual is an example where multiple documents share files. There are actually several versions of the manual, which use directories located in the mysqldoc repository as follows: 

mysqldoc/
        |common/
               |fixedchars.ent
        |refman-common/
                      |all-entities.ent
                      |urls.ent
                      |...
        |refman-6.0/
                   |all-entities.ent
                   |versions.ent
                   |manual.xml
                   |preface.xml
                   |...
        |refman-5.1/
                   |all-entities.ent
                   |versions.ent
                   |manual.xml
                   |preface.xml
                   |...
        |refman-5.0/
                   |all-entities.ent
                   |versions.ent
                   |manual.xml
                   |preface.xml
                   |...
        |refman-4.1/
                   |all-entities.ent
                   |versions.ent
                   |manual.xml
                   |preface.xml
                   |...
        |...

The files in the refman-common directory are shared by all versions of the Reference Manual. For each version of the manual, chapter structure (and order) is governed by the manual.xml file that uses XInclude directories to reference the chapter files: 

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % all.entities SYSTEM "all-entities.ent">
  %all.entities;
]>
<book id="refman-5-1" lang="en">

  <title>MySQL 5.1 Reference Manual</title>

  <bookinfo>
    ... standard info element parts ...
  </bookinfo>

  <xi:include href="preface.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  <xi:include href="introduction.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  <xi:include href="installing.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  <xi:include href="tutorial.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  ...
  <xi:include href="../refman-common/ha.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  ...

  <index/>

</book>