p:make-absolute-uris (3.1) 

Summary

<p:declare-step type="p:make-absolute-uris">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html" sequence="false"/>
  <option name="match" as="xs:string" required="true"/>
  <option name="base-uri" as="xs:anyURI?" required="false" select="()"/>
</p:declare-step>

The p:make-absolute-uris step makes element and/or attribute values in the document appearing on the source port absolute by applying a base URI.

Ports:

Options:

Description

The p:make-absolute-uris step takes the document appearing on its source port and searches for elements and/or attributes as indicated by the match option. The values of these elements/attributes are taken as URIs and, if relative, resolved against a base URI as specified in the base-uri option. If there's no base-uri option, the base URI of the element/attribute is used.

Why is this useful? URIs in documents that are edited or received from the web are often relative. They point to other documents, for instance images, that are elsewhere on disk or the web, in a location relative to the source document. For instance: images/picture.jpg. This allows for flexibility in the location of the documents. However, when processing these URIs and access the referenced documents, the code needs to know how to resolve them into absolute ones. It is practical to arrange all this URI resolving in advance, and this is what p:make-absolute-uris is for.

There is an important thing to keep in mind when supplying a value for the base-uri option:

• When its value ends with a slash (/), it points to a location. All URIs are resolved against that location. For instance: file:///myapp/images/

• When its value does not end with a slash, it points to a document. All URIs are resolved against the location of this document. For instance, for a base-uri value file:///myapp/images/logo.svg, the URIs are resolved against the location file:///myapp/images/

The Basic usage example shows this difference.

Examples

<URIs>
   <URI>image.jpg</URI>
   <URI>A/B/C/</URI>
   <URI>/image.jpg</URI>
   <URI>https://xprocref.org/index.html</URI>
</URIs>

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

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

  <p:make-absolute-uris match="URI" base-uri="file:///X/Y/Z/"/>

</p:declare-step>

<URIs>
   <URI>file:/…/…/image.jpg</URI>
   <URI>file:/…/…/file:/X/Y/Z/A/B/C/</URI>
   <URI>file:/…/…/image.jpg</URI>
   <URI>https://xprocref.org/index.html</URI>
</URIs>

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

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

  <p:make-absolute-uris match="URI" base-uri="file:///X/Y/Z"/>
  
</p:declare-step>

<URIs>
   <URI>file:/…/…/image.jpg</URI>
   <URI>file:/…/…/file:/X/Y/A/B/C/</URI>
   <URI>file:/…/…/image.jpg</URI>
   <URI>https://xprocref.org/index.html</URI>
</URIs>

Additional details

• p:make-absolute-uris preserves all document-properties of the document(s) appearing on its source port.

• The match option must match attributes or elements. If anything else is matched, error XC0023 is raised.

• A relative value for the base-uri option is resolved against the base URI of the element on which this option is specified. In most cases this will be the static base URI of your pipeline (the path where the XProc source containing the p:make-absolute-uris is stored). This is very probably not what you want.

• If no base-uri option is specified and an element/attribute matched has no base URI also, the result is implementation-defined and therefore dependent on the XProc processor used.

Errors raised

Reference information

This description of the p:make-absolute-uris 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:make-absolute-uris step can be found here.

The p:make-absolute-uris step is part of categories:

• Standard XProc steps

• Interaction with the environment

• Miscellaneous

The p:make-absolute-uris step is also present in version: 3.0.