Using XInclude

Note: The specification of the XPointer xpointer() scheme has never been finished. It has stalled at "Working Draft" status, and there are very few implementations. In fact, the examples below that use xpointer="xpointer(...)" only work with xmllint and xsltproc (which are based on the libxml2 and libxslt libraries). There are probably no other parsers/processors that support the xpointer() scheme.

Including an entire file of DocBook content

This is the simple use of <xi:include>. All contents of the file are included.

<xi:include href="source-docbook.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

Including a named DocBook element

This includes only the named element from source file.

<xi:include href="source-docbook.xml"
            xmlns:xi="http://www.w3.org/2001/XInclude" 
            xpointer="element(IdOfTheSourceSection)" />

Notes:

• This has been seen to work using xmllint in Cygwin (xmllint --xinclude source.xml > resolved.xml).

• The source DocBook file must be complete and valid. If you are including content from a modular file that does not have its own DOCTYPE declaration (for example, you keep chapters of a book in separate files), this xi:include element must point to the resolved file.

Including all children of a <section> in a <chapter>

This is used to share content among DocBook documents when the <section> or <chapter> that is being shared would not be valid in the location at which it is being included. For example, you want to use a <section> of one document at the top level of a <book> so the <section> element must be converted to a <chapter> element.

<chapter>
 <xi:include href="path/to/source/file/source-docbook.xml"
             xmlns:xi="http://www.w3.org/2001/XInclude" 
             xpointer="xpointer(//section[@id='IdOfTheSourceSection']/*)"/>
</chapter>

Notes:

• This has been seen to work using xmllint in Cygwin (xmllint --xinclude source.xml > resolved.xml).

• The source DocBook file must be complete and valid. If you are including content from a modular file that does not have its own DOCTYPE declaration (for example, you keep chapters of a book in separate files), this xi:include element must point to the resolved file.

Including all children of a <section> except the <title>

This is used to import all the contents of a <section> into an <article>. Since the <article> has its own <title> and also <articleinfo>, the <xi:include> must take all children of the <section> but not the <title>. An example use for this is to publish one section of a much larger <book> as a separate information sheet.

<article>
 <title>Lorem Ipsum</title> 
 <articleinfo>
   <copyright><year>2007</year><holder>Some Corporation</holder></copyright>
 </articleinfo> 
 <xi:include href="path/to/source/file/source-docbook.xml"
             xmlns:xi="http://www.w3.org/2001/XInclude"
             xpointer="xpointer(//section[@id='IdOfTheSourceSection']/title/following-sibling::*)"/>
</article>

Notes:

• This has been seen to work using xmllint in Cygwin (xmllint --xinclude source.xml > resolved.xml).

• The source DocBook file must be complete and valid. If you are including content from a modular file that does not have its own DOCTYPE declaration (for example, you keep chapters of a book in separate files), this <xi:include> element must point to the resolved file.