XProc 3.0: XSL Formatter

Editor's Draft 11 April 2018 at 14:02 UTC (build 304)

This Version:: https://xproc.github.io/3.0-specification/revert-362-fix-361/head/xsl-formatter/
Latest Version:: http://spec.xproc.org/master/head/xsl-formatter/
Editors:: Achim Berndzen; Gerrit Imsieke; Erik Siegel; Norman Walsh
Repository:: This specification on GitHub; Report an issue
Changes:: Commits for this specification

This document is also available in these non-normative formats: XML.

Abstract

This specification describes the p:xsl-formatter step for XProc 3.0: An XML Pipeline Language.

Status of this Document

This document is an editor's draft that has no official standing.

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

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

1 Introduction
2 p:xsl-formatter
- 2.1 Document properties
3 Step Errors
A Conformance
- A.1 Implementation-defined features
- A.2 Implementation-dependent features
B References
C Glossary

1 Introduction

This specification describes the p:xsl-formatter XProc step. 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].

2 p:xsl-formatter

The p:xsl-formatter step receives an [XSL 1.1] document and renders the content. The result of rendering is stored to the URI provided via the href option. A reference to that result is produced on the output port.

<p:declare-step type="p:xsl-formatter">
     <p:input port="source" content-types="application/xml text/xml */*+xml"/>
     <p:output port="result" content-types="*/*"/>
     <p:option name="parameters" as="map(xs:QName,item())"/>
     <p:option name="href" required="true" as="xs:anyURI"/>
     <p:option name="content-type" as="xs:string"/>
</p:declare-step>

The value of the href option must be an anyURI. If it is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:xsl-formatter in the case of a syntactic shortcut value).

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

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 a single c:result element whose content is the absolute URI of the document stored by the step.

2.1 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:

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:

The use of media type parameters on the content-type option is implementation-defined. See Section 2, “p:xsl-formatter”.
If the content-type option is not specified, the output type is implementation-defined. See Section 2, “p:xsl-formatter”.
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, “p:xsl-formatter”.

A.2 Implementation-dependent features

The following features are implementation-dependent:

B References

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

[XProc 3.0 Steps] XProc 3.0 Steps: An Introduction. Achim Berndzen, Gerrit Imsieke, Erik Siegel and Norman Walsh, editors.

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