p:add-xml-base (3.0) 

Add explicit xml:base attributes to a document.

Summary

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

The p:add-xml-base step adds explicit xml:base attributes to the source document. An xml:base attribute annotates an element with a “base URI” value, which is usually the URI this element came from.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

xml html

false

The document to add the xml:base attributes to.

result

output

true

xml html

false

The resulting document.

Options:

Name

Type

Req?

Default

Description

all

xs:boolean

false

false

Whether to add the xml:base attributes to all elements.

relative

xs:boolean

false

true

Whether to make the value of the xml:base attributes on child elements of the root relative instead of absolute.

Description

Nodes (elements, attributes, etc.) in XML documents “remember” where they came from: they have a so-called “base URI” attached. This is usually the URI this node came from: the path (for instance on disk) to the document where it belonged to. In most cases the base URI is invisible. The p:add-xml-base step exposes this by adding (or adapting) xml:base attributes.

The operation of the p:add-xml-base step depends on the values of the all and relative options:

all

relative

Operation

false

false

  • The root element of the document gets an xml:base attribute with an absolute URI. An existing xml:base attribute is updated.

  • Child elements where the base URI differs from its parent get an xml:base attribute with an absolute URI. An existing xml:base attribute is updated.

  • Any other xml:base attributes are removed.

false

true

These are the default values for these options.

  • The root element of the document gets an xml:base attribute with an absolute URI. An existing xml:base attribute is updated.

  • Child elements where the base URI differs from its parent get an xml:base attribute with an relative URI. An existing xml:base attribute is updated.

  • Any other xml:base attributes are removed.

true

false

  • The root element of the document gets an xml:base attribute with an absolute URI. An existing xml:base attribute is updated.

  • All child elements get an xml:base attribute with an absolute URI. An existing xml:base attribute is updated.

true

true

This is not allowed. Error XC0058 is raised.

Examples

Straight step usage

The following example shows what happens if we use p:add-xml-base straight out of the box:

Assume the following source document called in1.xml:

<texts>
   <text>Hello XProc lovers…</text>
</texts>

Pipeline document:

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

  <p:input port="source"/>
  <p:output port="result"/>

  <p:add-xml-base/>

</p:declare-step>

Result document:

<texts xml:base="file:/…/…/in1.xml">
   <text>Hello XProc lovers…</text>
</texts>

We can create an xml:base attribute on every element by setting the all option to true. Because the default value for the relative option is true and both options can’t both be true, we have to set the relative option to false explicitly.

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

  <p:input port="source"/>
  <p:output port="result"/>

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

</p:declare-step>

Result document:

<texts xml:base="file:/…/…/in1.xml">
   <text xml:base="file:/…/…/in1.xml">Hello XProc lovers…</text>
</texts>

Multiple base URIs

The following example shows what happens if you combine two documents. For this, we’re going to use another XML document called in2.xml:

<specialtext>Are you in for something special?</specialtext>

The following pipeline first creates a combined document by inserting this into the same source document we used in the previous example Straight step usage:

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

  <p:input port="source"/>
  <p:output port="result"/>

  <p:insert match="/*" position="last-child">
    <p:with-input port="insertion" href="in2.xml"/>
  </p:insert>

  <p:add-xml-base/>

</p:declare-step>

The result document has a relative xml:base value on the inserted document because the default value for the relative option is true:

<texts xml:base="file:/…/…/in1.xml">
   <text>Hello XProc lovers…</text>
   <specialtext xml:base="in2.xml">Are you in for something special?</specialtext>
</texts>

But we could also ask for absolute base URI values:

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

  <p:input port="source"/>
  <p:output port="result"/>

  <p:insert match="/*" position="last-child">
    <p:with-input port="insertion" href="in2.xml"/>
  </p:insert>

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

</p:declare-step>

Result document:

<texts xml:base="file:/…/…/in1.xml">
   <text>Hello XProc lovers…</text>
   <specialtext xml:base="file:/…/…/in2.xml">Are you in for something special?</specialtext>
</texts>

Additional details

  • p:add-xml-base preserves all document-properties of the document(s) appearing on its source port.

  • The xml namespace prefix as used here is bound to the namespace http://www.w3.org/XML/1998/namespace. In most cases you don’t have to bind this prefix explicitly (by adding xmlns:xml="http://www.w3.org/XML/1998/namespace"). This namespace binding is part of the XML language.

  • A formal definition of base URIs and xml:base attributes can be found here.

Errors raised

Error code

Description

XC0058

It is a dynamic error if the all and relative options are both true.

Reference information

This description of the p:add-xml-base 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:add-xml-base step can be found here.

The p:add-xml-base step is part of categories:

The p:add-xml-base step is also present in version: 3.1.