p:xinclude (3.1)

Apply XInclude procesing to a document.

Summary
Description
Examples
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:xinclude">
  <input port="source" primary="true" content-types="xml html" sequence="true"/>
  <output port="result" primary="true" content-types="xml html" sequence="true"/>
  <option name="fixup-xml-base" as="xs:boolean" required="false" select="false()"/>
  <option name="fixup-xml-lang" as="xs:boolean" required="false" select="false()"/>
</p:declare-step>

The p:xinclude step applies XInclude processing to the document appearing on the source document.

Ports:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`xml html`	`true`	The document to apply the XInclude processing to.
`output`	`result`	`true`	`xml html`	`true`	The resulting document.

Options:

Name	Type	Req?	Default	Description
`fixup-xml-base`	`xs:boolean`	`false`	`false`	Perform base URI fixup to the resulting document. Basically this means that `xml:base` elements are added to the root elements of the included files, containing the URIs they were included from. See also the Base URI fixup example.
`fixup-xml-lang`	`xs:boolean`	`false`	`false`	Perform language fixup on the resulting document. Basically this means that an `xml:lang` attribute is added to the root elements of the included documents. This stops the language settings of the including document from being inherited by the included document. See also the Language fixup example.

Description

The XInclude standard defines a syntax for specifying document inclusions. Basically this means:

In your source document you write (zero, one or multiple times): <xi:include href="…"/> (the xi namespace prefix must be bound to the namespace http://www.w3.org/2001/XInclude).
You run your document through the p:xinclude step.
All <xi:include> elements are replaced with the contents of the document their href attribute is pointing to.
All <xi:include> elements in the included documents are processed also, recursively.

Additionally, the XInclude standard defines some additional attributes for the <xi:include> element. The most used one is probably the parse attribute: parse="xml" (the default) means the document must be a well-formed XML document and is included as an XML fragment; parse="text" means the document is included as plain text. There is also an <xi:fallback> child element that defines what will happen if the included document could not be found.

Examples

Basic usage

Remark upfront: some of the example documents contain xml:lang attributes. These are intended for the Language fixup example below.

Assume we have a master document called document-0.xml that XIncludes two other documents:

<document-0 xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en-us">
  <description>This is the master document</description>
  <xi:include href="includes/document-1.xml"/>
  <xi:include href="includes/document-2.xml"/>
</document-0>

The first include document includes/document-1.xml looks like this, please notice that it contains an <xi:include> element itself:

<document-1 xmlns:xi="http://www.w3.org/2001/XInclude">
  <description>This is include document 1</description>
  <xi:include href="document-2.xml"/>
</document-1>

The second include document includes/document-2.xml (that is also included by includes/document-1.xml) looks like this:

<document-1 xmlns:xi="http://www.w3.org/2001/XInclude">
  <description>This is include document 1</description>
  <xi:include href="document-2.xml"/>
</document-1>

Now if we run document-0.xml through the p:xinclude step, the result is as follows:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" href="document-0.xml"/>
  <p:output port="result"/>

  <p:xinclude/>

</p:declare-step>

Result document:

<document-0 xml:lang="en-us">
   <description>This is the master document</description>
   <document-1>
      <description>This is include document 1</description>
      <document-2 xml:lang="en-gb">
         <description>This is include document 2</description>
      </document-2>
   </document-1>
   <document-2 xml:lang="en-gb">
      <description>This is include document 2</description>
   </document-2>
</document-0>

Base URI fixup

The XInclude base URI fixup means that an xml:base attribute is added to the root elements of the included documents. Using the same documents and include structure as the Basic usage example, it looks like this:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" href="document-0.xml"/>
  <p:output port="result"/>

  <p:xinclude fixup-xml-base="true"/>

</p:declare-step>

Result document:

<document-0 xml:lang="en-us">
   <description>This is the master document</description>
   <document-1 xml:base="file:/…/…/includes/document-1.xml">
      <description>This is include document 1</description>
      <document-2 xml:lang="en-gb" xml:base="file:/…/…/includes/document-2.xml">
         <description>This is include document 2</description>
      </document-2>
   </document-1>
   <document-2 xml:lang="en-gb" xml:base="file:/…/…/includes/document-2.xml">
      <description>This is include document 2</description>
   </document-2>
</document-0>

Notice that there is no xml:base attribute added to the root element of the master document. If you need all document root elements having an xml:base attribute, use the p:add-xml-base step instead of XInclude base URI fixup:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" href="document-0.xml"/>
  <p:output port="result"/>

  <p:xinclude/>
  <p:add-xml-base relative="false"/>

</p:declare-step>

Result document:

<document-0 xml:lang="en-us" xml:base="file:/…/…/document-0.xml">
   <description>This is the master document</description>
   <document-1 xml:base="file:/…/…/includes/document-1.xml">
      <description>This is include document 1</description>
      <document-2 xml:lang="en-gb" xml:base="file:/…/…/includes/document-2.xml">
         <description>This is include document 2</description>
      </document-2>
   </document-1>
   <document-2 xml:lang="en-gb" xml:base="file:/…/…/includes/document-2.xml">
      <description>This is include document 2</description>
   </document-2>
</document-0>

Language fixup

The XInclude language fixup means that an xml:lang attribute is added to the root elements of the included documents. This stops the language settings of the including document from being inherited by the included documents. Using the same documents and include structure as the Basic usage example, it looks like this:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" href="document-0.xml"/>
  <p:output port="result"/>

  <p:xinclude fixup-xml-lang="true"/>

</p:declare-step>

Result document:

<document-0 xml:lang="en-us">
   <description>This is the master document</description>
   <document-1 xml:lang="">
      <description>This is include document 1</description>
      <document-2 xml:lang="en-gb">
         <description>This is include document 2</description>
      </document-2>
   </document-1>
   <document-2 xml:lang="en-gb">
      <description>This is include document 2</description>
   </document-2>
</document-0>

Notice the empty xml:base="" attribute on the <document-1> element. That wasn’t there in the source. It stops the language settings of the including document document-0.xml (xml:lang="en-us") from automatically being inherited by the included document includes/document-1.xml.

Additional details

p:xinclude preserves all document-properties of the document(s) appearing on its source port.

Errors raised

Error code	Description
`XC0029`	It is a dynamic error if an XInclude error occurs during processing.

Reference information

This description of the p:xinclude step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).

The formal specification for the p:xinclude step can be found here.

The p:xinclude step is part of categories:

The p:xinclude step is also present in version: 3.0.