Copies the source to the result without modifications.
<p:declare-step type="p:identity"> <input port="source" primary="true" content-types="any" sequence="true"/> <output port="result" primary="true" content-types="any" sequence="true"/> </p:declare-step>
The p:identity
step makes a verbatim copy of what appears on its source
port to its result
port.
Ports:
Port | Type | Primary? | Content types | Seq? | Description |
---|---|---|---|---|---|
|
|
|
|
| The source document(s) |
|
|
|
|
| The resulting document(s). These will be exactly the same as what appeared on the |
The p:identity
step does… nothing. It makes a verbatim copy of all documents appearing on its source
port to its
result
port. Although it doesn’t do anything, it is actually extremely useful and virtually indispensable. The examples
below show some use cases.
There are many situations where you need to create a fixed document in your pipeline. For instance:
On an error catch you want some <error …>
element as result:
<p:catch> <p:identity> <p:with-input> <error … /> </p:with-input> </p:identity> </p:catch>
Some pipelines write their main results to disk and the actual output of the pipeline doesn’t matter. In these cases it is often useful to produce some kind of report document with relevant information (for instance, when it happened, where the results are, etc.):
<p:identity> <p:with-input> <report timestamp="{current-dateTime()}" href-result="{$href-result-location}" … /> </p:with-input> </p:identity>
Because the p:identity
step does’t do anything, it can be used to create “anchor points” in your pipeline. Assume you have
a complicated pipeline where some version of the document flowing through must be used somewhere else. The p:identity
step can be used to mark such
a location explicitly. In the following example an anchor point called raw-version
is created and, later on, referred to:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <!-- Some complicated computations… --> <p:identity name="raw-version"/> <!-- Some more complicated computations… --> <!-- And then a step refers back to the raw version: --> <p:insert match="/*" position="first-child"> <p:port port="insertion" pipe="@raw-version"/> </p:insert> <!-- And some more computations… --> </p:declare-step>
You could also achieve this by using the name="raw-version"
attribute on the last step of the first batch of computations.
However, by using an explicit p:identity
step it stands out in the code. Also, when the computations change (and they will), you don’t have to
remember to keep the name="raw-version"
attribute on the last one always.
XProc has a message
attribute (or p:message
on steps not in the XProc namespace) that results in a message when
the pipeline runs. Where this message appears depends on how the pipeline is run. Sometimes you want to explicitly produce messages when some
point in your pipeline is reached. Since p:identity
does’t do anything, it is ideal for this:
<p:identity message="We started processing!"/> <p:identity message="- Input document {$href-input}"/> <p:identity message="- Processing type {$processing-type}"/>
p:identity
preserves all document-properties of the document(s) appearing on its source
port.
This description of the p:identity
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:identity
step can be found here.
The p:identity
step is part of categories:
The p:identity
step is also present in version:
3.0.