Combining XML Documents and Fragments Using XInclude

A chapter file (introduction.xml) looks like this:

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter>
    <title>Getting started</title>
    <section>
        <title>Section title</title>
        <para>Para text</para>
    </section>
</chapter>

The main article (main file) looks like this:

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.docbook.org/xml/4.3/docbookx.dtd"
[ <!ENTITY % xinclude SYSTEM "../frameworks/docbook/dtd/xinclude.mod">
%xinclude;
]>
<article>
    <title>Install guide</title>
    <para>This is the install guide.</para>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
                    href="introduction.xml">
      <xi:fallback>
        <para>
          <emphasis>FIXME: MISSING XINCLUDE CONTENT</emphasis>
        </para>
      </xi:fallback>
    </xi:include>
</article>

In this example, note the following:

• The DOCTYPE declaration defines an entity that references a file containing the information to add the xi namespace to certain elements defined by the DocBook DTD.
• The href attribute of the xi:include element specifies that the introduction.xml file will replace the xi:include element when the document is parsed.
• If the introduction.xml file cannot be found, the parser will use the value of the xi:fallback element - a FIXME message.

If you want to include only a fragment of a file in the main file, the fragment must be contained in a tag having an @xml:id attribute and you must use an XPointer expression pointing to the @xml:id value.

For example, if the main file is:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="test.rng" type="application/xml" 
        schematypens="http://relaxng.org/ns/structure/1.0"?>
<test>
    <xi:include href="a.xml" xpointer="a1"
        xmlns:xi="http://www.w3.org/2001/XInclude"/>
</test>        

and the file (a.xml) is:

<?xml version="1.0" encoding="UTF-8"?>
<test>
    <a xml:id="a1">test</a>
</test>        

after resolving the XPointer reference, the document is:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="test.rng" type="application/xml" 
          schematypens="http://relaxng.org/ns/structure/1.0"?>
<test>
    <a xml:id="a1" xml:base="a.xml">test</a>
</test>

When a transformation scenario is applied on the main file, an intermediary file combines all the referenced content and it will be expanded in the final output. If you want to see how the referenced content will be expanded before applying the transformationCreate a minimal XSLT stylesheet that simply copies the XML content, then create a transformation scenario that applies the stylesheet over the XML. The XSLT stylesheet would look like this:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:math="http://www.w3.org/2005/xpath-functions/math"
    exclude-result-prefixes="xs math"
    version="3.0">
    <xsl:template match="node() | @*">
        <xsl:copy>
            <xsl:apply-templates select="node() | @*"/>
        </xsl:copy>
    </xsl:template>
    
</xsl:stylesheet>

• Fragment Identifiers

  You can use <xi:include> to reference a text file and specify the @fragid value so that you only get part of that text file in the main document. For some examples and to see how the <xi:include> gets expanded when the @fragid specifies a line range or character range, see Textual Inclusion Examples with RFC5147 Fragment Identifiers.

• Attribute Copying

  Any namespaced attribute defined on the <xi:include> element will be passed to the root element of the included content.

  For example, if you have this:

  <xi:include href="section2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" 
    set-xml-id="sectInner1"/>

  and section2.xml looks like this:

  <sect2 xmlns="http://docbook.org/ns/docbook" version="5.0"
      xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section2">
      <title>FS2</title>
      <para>P2</para>
  </sect2>

  then the final processed result will have the original xml:id="section2" replaced with the value specified in the xi:included section.

  For more information, see Attribute Copying when Processing XML. Also, to see more examples, see Attribute Copying Examples.