Apply XInclude procesing to a document.
<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:
Port | Type | Primary? | Content types | Seq? | Description |
---|---|---|---|---|---|
|
|
|
|
| The document to apply the XInclude processing to. |
|
|
|
|
| The resulting document. |
Options:
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.
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>
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>
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
.
p:xinclude
preserves all document-properties of the document(s) appearing on its source
port.
Error code | Description |
---|---|
It is a dynamic error if an XInclude error occurs during processing. |
This description of the p:xinclude
step is for XProc version: 3.0. This is a required step (an XProc 3.0 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.1.