XProc 3.1: paged media steps

Community Group Report

Latest editor’s draft:
https://spec.xproc.org/master/head/paged-media/
Editors:
Norman Walsh
Achim Berndzen
Gerrit Imsieke
Erik Siegel
Participate:
GitHub xproc/3.0-steps
Report an issue
Changes:
Diff against current “status quo” draft
Commits for this specification

This document is also available in these non-normative formats: XML and HTML with automatic change markup courtesy of DeltaXML.

Copyright © 2018, 2019, 2020 the Contributors to the XProc 3.1: paged media steps specification, published by the XProc Next Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

Abstract

This specification describes the p:css-formatter and p:xsl-formatter steps for XProc 3.1: An XML Pipeline Language.

Status of this Document

This specification was published by the XProc Next Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

If you wish to make comments regarding this document, please send them to xproc-dev@w3.org. (subscribe, archives).

This document is derived from XProc: An XML Pipeline Language published by the W3C.

Note

This draft is a “last call” draft. This version is stable and will not be updated.

1. Introduction

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.1] steps is assumed.

2. Step library

2.1. p:css-formatter

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.

Summary

Input portPrimarySequenceContent typesDefault binding
source  xml html 
stylesheet ✔ text p:empty
Output portPrimarySequenceContent typesDefault binding
result✔  any 
Option nameTypeDefault value
content-typexs:string?()
parametersmap(xs:QName,item()*)?()
Errors
Error codeDescription
err:XC0166It is a dynamic error if the requested document cannot be produced.
err:XC0204It is a dynamic error if the requested content-type is not supported.
err:XD0079It is a dynamic error if a supplied content-type is not a valid media type of the form “type/subtype+ext” or “type/subtype”.
Implementation details
ImplementationDescription
DefinedThe use of media type parameters on the content-type option is implementation-defined.
DefinedIf the content-type option is not specified, the output type is implementation-defined.
DefinedThe precise way that the p:css-formatter step selects stylesheets is implementation-defined.
DefinedA 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.
DefinedThe CSS level and the particular CSS features supported by p:css-formatter are implementation-defined.
Declaration

<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.

It is a dynamic error (err:XC0166) if the requested document cannot be produced.

Document properties

No document properties are preserved.

2.2. p:xsl-formatter

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

Summary

Input portPrimarySequenceContent types
source✔  xml 
Output portPrimarySequenceContent types
result✔  any 
Option nameTypeDefault value
content-typexs:string?()
parametersmap(xs:QName,item()*)?()
Errors
Error codeDescription
err:XC0167It is a dynamic error if the requested document cannot be produced.
err:XC0204It is a dynamic error if the requested content-type is not supported.
err:XD0079It is a dynamic error if a supplied content-type is not a valid media type of the form “type/subtype+ext” or “type/subtype”.
Implementation details
ImplementationDescription
DefinedThe use of media type parameters on the content-type option is implementation-defined.
DefinedIf the content-type option is not specified, the output type is implementation-defined.
DefinedA 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.
Declaration

<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.

It is a dynamic error (err:XC0167) if the requested document cannot be produced.

Document properties

No document properties are preserved.

3. Step Errors

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:

err:XC0166

It is a dynamic error if the requested document cannot be produced.

See: p:css-formatter

err:XC0167

It is a dynamic error if the requested document cannot be produced.

See: p:xsl-formatter

err:XC0204

It is a dynamic error if the requested content-type is not supported.

See: p:css-formatter, p:xsl-formatter

A. Conformance

Conformant processors must implement all of the features described in this specification except those that are explicitly identified as optional.

Some aspects of processor behavior are not completely specified; those features are either implementation-dependent or implementation-defined.

[Definition: An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.]

[Definition: An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.]

A.1. Implementation-defined features

The following features are implementation-defined:

  1. The use of media type parameters on the content-type option is implementation-defined. See Section 2.1, “p:css-formatter”.
  2. If the content-type option is not specified, the output type is implementation-defined. See Section 2.1, “p:css-formatter”.
  3. The precise way that the p:css-formatter step selects stylesheets is implementation-defined. See Section 2.1, “p:css-formatter”.
  4. 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. See Section 2.1, “p:css-formatter”.
  5. The CSS level and the particular CSS features supported by p:css-formatter are implementation-defined. See Section 2.1, “p:css-formatter”.
  6. The use of media type parameters on the content-type option is implementation-defined. See Section 2.2, “p:xsl-formatter”.
  7. If the content-type option is not specified, the output type is implementation-defined. See Section 2.2, “p:xsl-formatter”.
  8. 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. See Section 2.2, “p:xsl-formatter”.

B. References

[XProc 3.1] XProc 3.1: An XML Pipeline Language. Norman Walsh, Achim Berndzen, Gerrit Imsieke and Erik Siegel, editors.

[CSS] CSS Snapshot 2018. Tab Atkins Jr., Elika J. Etemad, and Florial Rivoal editors. W3C Note 22 January 2019.

[XSL 1.1] Extensible Stylesheet Language (XSL) Version 1.1. Anders Berglund, editor. W3C Recommendation. 5 December 2006.

[IANA Media Types] IANA MIME Media Types. Internet Engineering Task Force.

C. Glossary

dynamic error

A dynamic error is one which occurs while a pipeline is being evaluated.

implementation-defined

An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.

implementation-dependent

An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.

D. Ancillary files

This specification includes by reference a number of ancillary files.

steps.xpl

An XProc step library for the declared steps.