XProc 3.0: paged media steps

This specification describes the p:css-formatter and p:xsl-formatter XProc steps. A machine-readable description of these steps may be found in steps.xpl.

Familarity with the general nature of [XProc 3.0] steps is assumed; for background details, see [XProc 3.0 Steps].

The p:css-formatter step applies [CSS] formatting to an XML or HTML document. The output of this step is often, but not necessarily, a PDF document.

<p:declare-step type="p:css-formatter">
     <p:input port="source" content-types="xml html"/>
     <p:input port="stylesheet" content-types="text" sequence="true">
          <p:empty/>
     </p:input>
     <p:output port="result" content-types="any"/>
     <p:option name="parameters" as="map(xs:QName,item()*)?"/>     
     <p:option name="content-type" as="xs:string?"/>               
</p:declare-step>

The document on the source port is formatted using one or more CSS stylesheets. The content-type of the output is controlled by the content-type option. This option specifies a media type as defined by [IANA Media Types]. It is a dynamic error (err:XD0079) if a supplied content-type is not a valid media type of the form “type/subtype+ext” or “type/subtype”. The option may include media type parameters as well (e.g. "application/someformat; charset=UTF-8"). The use of media type parameters on the content-type option is implementation-defined. If the content-type option is not specified, the output type is implementation-defined. The default should be PDF. It is a dynamic error (err:XC0204) if the requested content-type is not supported.

If one or more stylesheets are provided on the stylesheet port, they should be used. The precise way that the p:css-formatter step selects stylesheets is implementation-defined. Because CSS stylesheets may have import statements that rely on relative URI references, it may be more convenient for authors and implementors to allow stylesheets to be specified as a list of URIs (in, for example, one of the parameters).

A formatter may take any number of optional rendering parameters via the step's parameters; such parameters are defined by the CSS implementation used and are implementation-defined.

The CSS level and the particular CSS features supported by p:css-formatter are implementation-defined.

The p:xsl-formatter step receives an [XSL 1.1] document and renders the content.

<p:declare-step type="p:xsl-formatter">
     <p:input port="source" content-types="xml"/>
     <p:output port="result" content-types="any"/>
     <p:option name="parameters" as="map(xs:QName,item()*)?"/>     
     <p:option name="content-type" as="xs:string?"/>               
</p:declare-step>

The content-type of the output is controlled by the content-type option. This option specifies a media type as defined by [IANA Media Types]. It is a dynamic error (err:XD0079) if a supplied content-type is not a valid media type of the form “type/subtype+ext” or “type/subtype”. The option may include media type parameters as well (e.g. "application/someformat; charset=UTF-8"). The use of media type parameters on the content-type option is implementation-defined.

If the content-type option is not specified, the output type is implementation-defined. The default should be PDF. It is a dynamic error (err:XC0204) if the requested content-type is not supported.

A formatter may take any number of optional rendering parameters via the step's parameters; such parameters are defined by the XSL implementation used and are implementation-defined.

The output of this step is a document containing the result of processing. This is often, but not necessarily, a PDF document.

This step can raise dynamic errors.

[Definition: A dynamic error is one which occurs while a pipeline is being evaluated.] Examples of dynamic errors include references to URIs that cannot be resolved, steps which fail, and pipelines that exhaust the capacity of an implementation (such as memory or disk space). For a more complete discussion of dynamic errors, see Dynamic Errors in XProc 3.0: An XML Pipeline Language.

If a step fails due to a dynamic error, failure propagates upwards until either a p:try is encountered or the entire pipeline fails. In other words, outside of a p:try, step failure causes the entire pipeline to fail.

The following errors can be raised by this step: