XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (230 page)

Content

The content of the

element is a sequence constructor.

The

element may contain an

element. If it does, the

element defines the action that an XSLT 1.0 processor will take when it encounters the

instruction. Note that the fallback processing only applies if the stylesheet is executing in forward-compatible mode, which will be the case if you set
version=“2.0”
on the

element.

Effect

When the

instruction is evaluated, a new document node is created, in the same way as for the

instruction. The sequence constructor contained in the

is evaluated to produce a sequence of items, and this sequence is used to form the content of the document node as described under

in the section
The Content of the Document
on page 303. The tree rooted at this document node is referred to as a final result tree.

Validation of the result tree also follows the same rules as

: See
Validating and Annotating the Document
on page 305. Note that although the validation process (if requested) conceptually creates a result tree in which the elements and attributes are annotated with types, these type annotations will never be seen if the result tree is immediately serialized. But a very useful processing model is to run a series of transformations in a pipeline, where the output of one stylesheet provides the input to the next. The pipeline might also include non-XSLT applications. The new XProc specification from W3 C (
www.w3.org/TR/XProc
) is designed to standardize the way such pipelines are written.

The difference between

and

is that

adds the new document node to the result sequence, making it available for further processing by the stylesheet, while

outputs the new document as a final result of the transformation.

What actually happens to a final result tree is to some degree system-dependent, and it is likely that vendors will provide a degree of control over this through the processor API.

Often, the result tree will be serialized (perhaps as XML or HTML) and written to a file on disk. The location of the file on disk is controlled using the
href
attribute, and the format in which it is serialized is controlled using the
format
attribute, supplemented by the serialization attributes (
method
,
byte-order-mark
,
cdata-section-elements
,
doctype-public
,
doctype-system
,
encoding
,
escape-uri-attributes
,
include-content-type
,
indent
,
media-type
,
normalization-form
,
omit-xml-declaration
,
standalone
,
undeclare-prefixes
,
use-character-maps
, and
output-version
).

If the
format
attribute is present then its value must be a lexical QName, which must match the
name
attribute of an

declaration in the stylesheet. The result tree will then be serialized as specified by that

declaration, except that any serialization attributes provided on the

override the corresponding attributes in the

declaration. All of the serialization attributes except
use-character-maps
are attribute value templates, which means that their values may be calculated at runtime, perhaps based on a stylesheet parameter or on data in the source document. If there is no
format
attribute, then the result tree (assuming it is serialized at all) will be serialized as specified by the unnamed

declaration if there is one, or the default serialization rules if not, except that again any serialization attributes provided on the

override the corresponding attributes in the

declaration. The effect of the serialization attributes is fully described in Chapter 15.

The way in which the
href
attribute is used is deliberately left a little vague in the specification, because the details are likely to be implementation-dependent. Its value is a relative or absolute URI. Details of the URI schemes that may be specified are left entirely to the implementation. The specification is also written in such a way that the URI can be interpreted as referring either to the result tree itself or to its serialized representation. The important thing that the specification says is that it is safe to use relative URIs as links from one output document to another: if you create one result document with
href=“chap1.html”
and another with
href=“chap2.html”
, then the content of the first document can include an element such as
href=“chap2.html”>next
chapter
and expect the link to work, whether the result trees are actually serialized or not. The specification achieves this by saying that any relative URI used in the
href
attribute of an

element is interpreted relative to a
Base Output URI
, which in effect is supplied in the API that invokes the transformation.

The specification of

is complicated by the fact that it is an instruction that has side effects. The instruction does not return a result (technically, it returns an empty sequence, which means it doesn't affect the result of evaluating the sequence constructor that it is part of). In a pure functional language, side effects are always problematical—though, of course, the only purpose of running any program is to change something in the environment in which it is run. Normally, if a compiler knows that a particular construct will return a particular result, then it can generate code that short cuts the evaluation of this construct. But it would destroy the purpose of

if it did nothing, just because the compiler already knows what result it will return.