Previous Up Next


p:add-xml-base

p:add-xml-base — Adds explicit xml:base attributes.

Synopsis

<p:declare-step type="p:add-xml-base">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="all" select="'false'"/>                       <!-- boolean -->
     <p:option name="relative" select="'true'"/>                   <!-- boolean -->
</p:declare-step>

Description

The p:add-xml-base step exposes the base URIs in the document via explicit xml:base attributes. If that sounds a little odd, it's important to realize that the base URI of a node is an intrinsic property of that node. What p:add-xml-base does is copy that intrinsic value to the explicit value of the xml:base attribute.

The input document from the source port is copied to the result port with xml:base attributes added to, or corrected on, each element as specified by the options on this step.

XML provides documents, elements, and processing instructions with an intrinsic “base URI” property. As documents flow through an XProc pipeline this property is generally preserved. However, there are operations that cannot preserve the intrinsic base URI; examples include storing the document to disk or sending it to a remote web service via p:http-request.

The [XML Base] specification provides for an explicit syntax to represent the base URI: the xml:base attribute.

This step makes any base URIs in the document explicit using xml:base. Specifically:

  • An xml:base attribute is added to the document element.

  • For other elements, if either the all option is true or the base URI of the element is different than its parent, an xml:base attribute is added to the element.

If the relative option is true, then the value of the xml:base attribute is an appropriate relative URI, otherwise it's an absolute URI.

Note

If the all option is false, then p:add-xml-base attributes will actually remove redundant xml:base attributes. In other words, you can think of the process as removing all xml:base attributes and then only adding the ones that are necessary per the options specified to the step.

Errors

Error Description
err:C0058 Occurs if the all and relative options are both true.

Examples

This examples in this section rely on the fact that the input document is constructed using an XML feature called external parsed entities:

  1 <!DOCTYPE book [
    <!ENTITY ch01 SYSTEM "chaps/ch01.xml">
    <!ENTITY ch02 SYSTEM "chaps/ch02.xml">
    <!ENTITY appa SYSTEM "apps/appa.xml">
  5 ]>
    <book>
    <title>Some Title</title>
    &ch01;
    &ch02;
 10 &appa;
    </book>

When the parser expands the entities, the base URI of the parts becomes part of the data model, but it's not reflected in the serialized form shown below. This is precisely the problem that p:add-xml-base is designed to address.

With that caveat, we can see how this pipeline adds xml:base attributes where necessary in the document.

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                version="1.0">
    
      <p:add-xml-base/>
  5 </p:pipeline>
Input Output
1 <book>
<title>Some Title</title>
<chapter>
<title>First chapter</title>
5 <para>Some text</para>
</chapter>
<chapter>
<title>Second chapter</title>
<para>Some text</para>
10 </chapter>
<appendix>
<title>Appendix</title>
<para>Some text</para>
</appendix>
15 </book>
 
1 <book xml:base="file:/projects/xproc/src/core/docs/main.xml">
<title>Some Title</title>
<chapter xml:base="chaps/ch01.xml">
<title>First chapter</title>
5 <para>Some text</para>
</chapter>
<chapter xml:base="chaps/ch02.xml">
<title>Second chapter</title>
<para>Some text</para>
10 </chapter>
<appendix xml:base="apps/appa.xml">
<title>Appendix</title>
<para>Some text</para>
</appendix>
15 </book>

This pipeline performs the same function, but inserts absolute URIs throughout.

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                version="1.0">
    
      <p:add-xml-base relative="false"/>
  5 </p:pipeline>
Input Output
1 <book>
<title>Some Title</title>
<chapter>
<title>First chapter</title>
5 <para>Some text</para>
</chapter>
<chapter>
<title>Second chapter</title>
<para>Some text</para>
10 </chapter>
<appendix>
<title>Appendix</title>
<para>Some text</para>
</appendix>
15 </book>
 
1 <book xml:base="file:/projects/xproc/src/core/docs/main.xml">
<title>Some Title</title>
<chapter xml:base="file:/projects/xproc/src/core/docs/chaps/ch01.xml">
<title>First chapter</title>
5 <para>Some text</para>
</chapter>
<chapter xml:base="file:/projects/xproc/src/core/docs/chaps/ch02.xml">
<title>Second chapter</title>
<para>Some text</para>
10 </chapter>
<appendix xml:base="file:/projects/xproc/src/core/docs/apps/appa.xml">
<title>Appendix</title>
<para>Some text</para>
</appendix>
15 </book>

The all option can be used to force xml:base attributes throughout.

  1 <p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
                version="1.0">
    
      <p:add-xml-base relative="false" all="true"/>
  5 </p:pipeline>
Input Output
1 <book>
<title>Some Title</title>
<chapter>
<title>First chapter</title>
5 <para>Some text</para>
</chapter>
<chapter>
<title>Second chapter</title>
<para>Some text</para>
10 </chapter>
<appendix>
<title>Appendix</title>
<para>Some text</para>
</appendix>
15 </book>
 
1 <book xml:base="file:/projects/xproc/src/core/docs/main.xml">
<title xml:base="file:/projects/xproc/src/core/docs/main.xml">Some Title</title>
<chapter xml:base="file:/projects/xproc/src/core/docs/chaps/ch01.xml">
<title xml:base="file:/projects/xproc/src/core/docs/chaps/ch01.xml">First chapter</title>
5 <para xml:base="file:/projects/xproc/src/core/docs/chaps/ch01.xml">Some text</para>
</chapter>
<chapter xml:base="file:/projects/xproc/src/core/docs/chaps/ch02.xml">
<title xml:base="file:/projects/xproc/src/core/docs/chaps/ch02.xml">Second chapter</title>
<para xml:base="file:/projects/xproc/src/core/docs/chaps/ch02.xml">Some text</para>
10 </chapter>
<appendix xml:base="file:/projects/xproc/src/core/docs/apps/appa.xml">
<title xml:base="file:/projects/xproc/src/core/docs/apps/appa.xml">Appendix</title>
<para xml:base="file:/projects/xproc/src/core/docs/apps/appa.xml">Some text</para>
</appendix>
15 </book>

FIXME: add an example to show how all=false can remove xml:base attributes.