Secondary output

The term secondary output refers to values produced using the xsl:result-document instruction. As with the principal output, applications can control both the destination of secondary output, and its format.

When running from the command line, secondary outputs are always serialized, using the serialization parameters supplied on the xsl:result-document instruction itself, or in the xsl:output declaration referenced in its format attribute. Serialization parameters supplied on the command line (for example !indent=yes) only take effect if the xsl:result-document chooses to use the default output format.

By default, secondary outputs are written to a file whose name is established by resolving the relative URI given in the @href attribute of xsl:result-document against the base output URI of the transformation. The base output URI defaults to the destination of the principal output.

The destination and format of secondary outputs can be influenced using the Java or C# API:

In the case of an xsl:result-document instruction with no href attribute, the output is sent to the principal output destination, which must not then be used for anything else. The main reason for this is to allow serialization options to be set dynamically.

Because xsl:result-document is an instruction that by its nature has side-effects, which runs against the grain of XSLT's pure functional language philosophy, the XSLT specification defines a number of rules constraining what the instruction can do. Notably (a) you can't write more than one output to the same URI, and (b) you can't write to a URI that the transformation also reads from. Using a ResultDocumentHandler, it's very easy to circumvent these rules (for example by using URIs containing an arbitrary query part, and having the result handler drop the query part), but the consequences might be unpredictable behaviour if instructions in the stylesheet are executed in an unexpected order.

Saxon-EE evaluates the xsl:result-document instruction asynchronously, unless multi-threading is explicitly disabled. This means that the transformation might be building several output files in parallel. This will cause problems if the stylesheet uses extension functions that have side-effects.