p:pack (3.1)

Merges two document sequences, pair-wise.

Summary
Description
Examples
- Basic usage
Additional details
Reference information

Summary

<p:declare-step type="p:pack">
  <input port="source" primary="true" content-types="text xml html" sequence="true"/>
  <output port="result" primary="true" content-types="application/xml" sequence="true"/>
  <input port="alternate" primary="false" content-types="text xml html" sequence="true"/>
  <option name="wrapper" as="xs:QName" required="true"/>
</p:declare-step>

The p:pack step takes the document sequences appearing on its source and alternate ports and combines these documents in a pair-wise fashion, wrapping the pairs in a wrapper element.

Ports:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`text xml html`	`true`	The first document sequence to merge.
`output`	`result`	`true`	`application/xml`	`true`	The resulting merged document sequences.
`input`	`alternate`	`false`	`text xml html`	`true`	The second document sequence to merge.

Options:

Name	Type	Req?	Description
`wrapper`	`xs:QName`	`true`	The element to wrap the document pairs in.

Description

The p:pack step takes two document sequences, one on its source and one on its alternate port. It then takes the first document in both sequences, concatenates these and wraps this in a wrapper element as indicated by the wrapper option. The same is done for the second pair, etc. The resulting wrapped document pairs are emitted on the result port.

If p:pack reaches the end of one input sequence before the other, the remaining documents will be wrapped as single documents.

Examples

Basic usage

The following pipeline provides p:pack with two document sequences. The pairs are wrapped in a <pair-wrapper> element. Since the sequence on the alternate port is one document longer than the one on the source port, the remaining document <alternate-doc-3/> is wrapped as single document.

The resulting document sequence here is wrapped using p:wrap-sequence, just to show the results.

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

  <p:output port="result"/>

  <p:pack wrapper="pair-wrapper">
    <p:with-input port="source">
      <source-doc-1/>
      <source-doc-2/>
    </p:with-input>
    <p:with-input port="alternate">
      <alternate-doc-1/>
      <alternate-doc-2/>
      <alternate-doc-3/>
    </p:with-input>
  </p:pack>

  <p:wrap-sequence wrapper="all-packed-results"/>

</p:declare-step>

Result document:

<all-packed-results>
   <pair-wrapper>
      <source-doc-1/>
      <alternate-doc-1/>
   </pair-wrapper>
   <pair-wrapper>
      <source-doc-2/>
      <alternate-doc-2/>
   </pair-wrapper>
   <pair-wrapper>
      <alternate-doc-3/>
   </pair-wrapper>
</all-packed-results>

Additional details

No document-properties of the source/alternate documents survive.
The resulting document(s) have no base-uri property.

Reference information

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

The p:pack step is part of categories:

The p:pack step is also present in version: 3.0.