History | Edit

XInclude is a standard for assembling XML instances into another XML document through inclusion. It enables larger documents to be dynamically created from smaller XML documents without having to physically duplicate the content of the smaller files in the master file. XInclude is targeted as the replacement for External Entities. The advantage of using XInclude is that, unlike the entities method, each of the assembled documents is permitted to contain a Document Type Declaration (DOCTYPE). This means that each file is a valid XML instance and can be independently validated. It also means that the main document, which includes smaller instances, can be validated without having to remove or comment out the DOCTYPE. as is the case with External Entities. This makes XInclude a more convenient and effective method for managing XML instances that need to be stand-alone documents and part of a much larger project.

The main application for XInclude is in the document-oriented content such as manuals and Web pages. Employing XInclude enables you to manage content in a modular fashion that is akin to Object Oriented methods used in languages such as Java, C++ or C#.

The advantages of modular documentation include: reusable content units, smaller file units that are easier to be edited, better version control and distributed authoring.

The XInclude support in Oxygen XML Editor is enabled by default. It is controlled by the Enable XInclude processing option in the XML > XML Parser preferences page. When enabled, Oxygen XML Editor will be able to validate and transform documents comprised of parts added using XInclude.

Example: Using XInclude to Include a Chapter in an Article

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>
Main article 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.

Example: Include only a Fragment

If you want to include only a fragment of a file in the master 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.
Note: Oxygen XML Editor supports the XPointer Framework and the XPointer element() Scheme, but it does NOT support the XPointer xpointer() Scheme.

For example, if the master 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 a.xml file 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>

XInclude 1.1 Features

Oxygen XML Editor offers partial support for XInclude 1.1 features. This includes support for fragment identifiers and attribute copying.

  • Fragment Identifiers

    You can xi:include 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 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 wll 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" 
      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.