xsl:result-document

Used to direct output to a secondary output destination.

Category: instruction
Content: sequence-constructor
Permitted parent elements: any XSLT element whose content model is sequence-constructor; any literal result element

Attributes

Saxon availability

Available in XSLT 2.0 and later versions. Available in all Saxon editions. Available for all platforms.

Notes on the Saxon implementation

Since Saxon 9.5, the xsl:result-document instruction in Saxon-EE is asynchronous. That is, the code to produce the secondary output runs in a separate thread, in parallel with other processing. The maximum number of threads used by xsl:result-document instructions is limited by the configuration property RESULT_DOCUMENT_THREADS which defaults to the number of processors available to the Java VM; setting this to zero or one will suppress multithreading. Setting ALLOW_MULTITHREADING to false has the same effect. (This can be useful when debugging, because otherwise the output from xsl:message and fn:trace() can be very confusing).

Asynchrony can also potentially cause problems if the code calls extension functions that have side-effects. Multi-threading can therefore be controlled, if required, using the saxon:asynchronous attribute on the xsl:result-document instruction: use saxon:asynchronous="no" to suppress multi-threading. Asynchronous processing of xsl:result-document is automatically suppressed if tracing (using a TraceListener) is enabled.

The XSLT 3.0 attribute parameter-document is first implemented in Saxon 9.8.

There was a change in Saxon 9.9 regarding the way in which an xsl:result-document instruction with no href attribute is handled. In previous releases Saxon attempted to reuse the output stream established for the primary output of the transformation. The new XSLT 3.0 options (such as raw output) make this difficult, and possibly non-conformant. The new model is therefore that the href attribute simply defaults to the base output URI, and is otherwise handled in the same way as any other call on xsl:result-document. This means that when no base output URI is supplied, this case will now cause a failure. It also means that when a user written result document resolver is in use, it will be called to handle this case with the base output URI supplied as the URI argument. For more information, see Secondary output.

Details

The xsl:result-document element was introduced in XSLT 2.0, obsoleting the previous extension element saxon6:output (which was reinstated in Saxon 9.9 as a synonym for xsl:result-document since legacy stylesheets still use it).

The destination of the secondary output can be altered programmatically as described in Secondary output. In other cases the secondary output is serialized and written to the file identified by the URI in the href attribute, resolved if it is relative against the base output URI for the transformation (which defaults to the destination of the principal output). The destination must use the file:/ URI scheme. Any previous file at this location is overwritten. If the transformation fails with a dynamic error, the content of any output files is undefined (no attempt is made to reset them to their original state).

The serialization attributes method, allow-duplicate-names, build-tree, byte-order-mark, canonical, cdata-section-elements, doctype-public, doctype-system, encoding, escape-uri-attributes, escape-solidus, html-version, include-content-type, indent, item-separator, json-lines, json-node-output-method, media-type, normalization-form, omit-xml-declaration, standalone, suppress-indentation, undeclare-prefixes, use-character-maps, and output-version may be used to override attributes defined in an output definition. For full definitions of these attributes, see the corresponding xsl:output element documentation.

See Additional serialization parameters for descriptions of additional attributes supported by Saxon-PE and Saxon-EE on xsl:result-document and xsl:output. Any values specified on the xsl:result-document instruction override the values specified on the xsl:output declaration.

Except for use-character-maps, any of these serialization attributes may be an AVT, so the values can be decided at run-time. For any of these attributes that is present on the xsl:result-document instruction, the effective value of the attribute overrides or supplements the corresponding value from the output definition. In the case of cdata-section-elements and suppress-indentation, the value of the serialization parameter is the union of the expanded names of the elements named in this instruction and the elements named in the selected output definition. In the case of use-character-maps, the character maps referenced in this instruction supplement and take precedence over those defined in the output definition. In all other cases, values of serialization attributes on the xsl:result-document instruction take precedence.

Examples

In the following, the body of the preface is directed to a file called preface.html (prefixed by a constant that supplies the directory name). Output then reverts to the previous destination, where an HTML hyperlink to the newly created file is inserted.

Links to W3C specifications

XSLT 3.0 Specification

XSLT 4.0 Specification

See also

xsl:output