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

This attribute is a bit of an oddity because in other cases, it is left to the API to control what happens to the input document before a transformation starts. Although you can ask for type annotations to be removed from the input document, you can't ask for them to be added (by invoking validation) unless you're prepared to make a copy of the document.

Usage

In theory, the time to use this attribute is when (a) your stylesheet is relying on nodes being untyped (this might be the case, for example, if it wants to manipulate dates as strings using regular expressions), and (b) there is a possibility that it will be presented with typed input.

I haven't come across the need for this with Saxon, because the input will only be typed if you explicitly request it. But it might be handy when you want your stylesheet to work with other processors. AltovaXML validates the input document if it contains an
xsi:schemaLocation
attribute, which is something that the processing application may not be able to control.

The use-when Attribute

This attribute may be specified on any element in the stylesheet (if specified on a literal result element, it is named
xsl:use-when
) and its value is an XPath expression. Although the full XPath syntax is allowed, the context for evaluation of the expression is severely restricted, which means that the expression cannot refer to anything in the source document or the stylesheet. In practice this means it is restricted to testing the results of functions such as
system-property()
,
function-available()
, and
element-available()
.

Effect

The expression is evaluated at compile time, and if its effective boolean value is false, the element on which it appears is effectively excluded from the stylesheet module at compile time. If the attribute is used on the

or

element itself, the effect is slightly different: the element itself is not excluded (because this would make the stylesheet invalid); instead, all the top-level declarations are excluded, so the stylesheet module becomes empty. This is only useful, of course, for an included or imported module.

The
use-when
attribute is discussed more fully in Chapter 3, page 127.

Usage

This attribute is provided to allow you to write stylesheets that are portable across different XSLT processors. For example, you can specify
use-when=“system-property(‘xsl:is-schema- aware’)=‘yes’”
to mark a section of stylesheet code that should be ignored by a processor that is not schema-aware, or you can test the
xsl:vendor
system property to include sections of code that are specific to particular XSLT implementations. You can also use the
function-available()
function to conditionally include or exclude sections of code based on whether a particular extension function is available in the implementation you are running on.

There are more examples of the use of this attribute in Chapter 3 (see page 127). It can be used on any XSLT element, both declarations (notably

,

, and

), and instructions. Just remember that the expression cannot access the source document, and it cannot access any variables: it is designed only to test properties of the environment in which the stylesheet is compiled. Check the documentation of
system-property()
in your chosen implementation to see whether it gives you access to environment variables set at the operating system level.

The version Attribute

The
version
attribute defines the version of the XSLT specification that the stylesheet is relying on. At present there are two published versions of the XSLT Recommendation, namely versions 1.0 and 2.0, so this attribute should take one of these two values.

Effect

The
version
attribute may be used to switch the XSLT processor into forward- or backward-compatibility mode. The rules are different for an XSLT 1.0 processor and a 2.0 processor, as shown in the table below.

Forward-compatible mode and backward-compatible mode are explained in Chapter 3. In essence:

• Forward-compatible mode means that the stylesheet doesn't fail if it contains constructs defined in a later version of the specification, provided that it avoids executing those constructs (for example, by using
  
  ).
  
• Backward-compatible mode, which applies only to 2.0, means that certain constructs behave in a different way to retain compatibility with 1.0. Most notably, using a sequence of items where a single item is expected does not cause an error, it causes all items after the first to be ignored.
  

The
version
attribute applies to the entire stylesheet module, except any parts contained within an XSLT element that has a
version
attribute, or a literal result element that has an
xsl:version
attribute. Its scope is the stylesheet module, not the full stylesheet tree constructed by applying

and

elements.

Note that in XSLT 1.0, the
version
attribute was allowed only on the

element, and
xsl:version
was allowed on literal result elements. In XSLT 2.0 this has been relaxed, so
version
can be specified on any element in the XSLT namespace. If your stylesheet is likely to be executed by an XSLT 1.0 processor, it is best to use it only in the places where it was allowed in XSLT 1.0.

Some products (XMLSpy is an example) use the
version
attribute to decide which processor to invoke. So if your stylesheet specifies
version=“1.0”
, it will run with a real XSLT 1.0 processor, not with a 2.0 processor in backward-compatibility mode. This means it will fail if it tries to use any 2.0 constructs.