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
|
|
If present, it gives the name of an xsl:output element that describes
the serialization format for this output document; if absent, the unnamed
|
|
|
The URI for the result document. If this is a relative URI, it is interpreted
relative to the base output URI. The base output URI is the systemID of the
result object supplied as the destination for the transformation, or if you
are using the command line, the value of the If the base output URI is not known, then the current directory is used. This base output URI must be a writable location. Usually it will therefore be a URI that uses the "file:" scheme. However, Saxon attempts to open a connection whatever URI scheme is used, and it should therefore work with any URI where the Java VM has the capability to open a writable connection. Users have reported success in using "ftp:" and "mailto:" URIs. If the configuration option FeatureKeys.ALLOW-EXTERNAL-FUNCTIONS
is set, then for security reasons use of the
|
|
|
Requires Saxon-PE or Saxon-EE. |
|
|
Determines what happens to any type annotations on element or attribute nodes. Requires Saxon-PE or Saxon-EE. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Not available in XSLT. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
New in XSLT 3.0. Not implemented in Saxon 9.7. Allows serialization to be configured in an external document. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Serialization attribute, see Details for more information. |
|
|
Overrides the |
|
|
The default
for Saxon-EE is |
Notes on the Saxon implementation
Since Saxon 9.5, the xsl:result-document
instruction in Saxon-EE is
asynchronous. That is, the code to output the result document 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 option FeatureKeys.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 FeatureKeys.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 xsl:result-document
instruction may also take the extension serialization parameter
saxon:indent-spaces
. This attribute may be an AVT, so the values
can be decided at run-time. Any values specified on the
xsl:result-document
instruction override the values specified
on the xsl:output
declaration.
The new XSLT 3.0 attribute parameter-document
is first implemented in
Saxon 9.8.
Details
The xsl:result-document
element was introduced in XSLT 2.0,
replacing the previous extension element saxon:output
.
The destination of the result document can be altered programmatically by
defining an OutputURIResolver. In the absence of an
OutputURIResolver
, the document 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 document). 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
, cdata-section-elements
,
doctype-public
, doctype-system
,
encoding
, escape-uri-attributes
,
html-version
, include-content-type
,
indent
, item-separator
,
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.
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.