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

Usage

The

instruction is generally used to report error conditions detected by the stylesheet logic. An example might be where an element such as

is expected to have a numeric value, but is found to have a nonnumeric value:

• With
  terminate=“no”
  (the default), the stylesheet can report the error and continue processing.
  
• With
  terminate=“yes”
  , the stylesheet can report the error and quit.
  

Before using

in a production environment, check what happens to the messages and whether they can be redirected. You need to be particularly clear about whether your messages are intended to be read by the source document author, the stylesheet author, or the end user: this will affect the way in which you write the text of the message.

The output produced by

can be unpredictable, because the sequence of execution of a stylesheet is not defined in the standard. For example, some products (including Saxon) defer evaluation of a variable until the variable is first used, which means that the order in which different variables are evaluated is difficult to predict. If evaluation of a variable triggers execution of

, the order of the messages may be surprising. Certainly, it can vary from one XSLT processor to another.

A common use of

is to generate diagnostic output so you can work out why your stylesheet isn't behaving as expected. This works well with products that have a fairly predictable sequence of execution, but it can be rather bewildering with a processor that does things in a different order from the one you would expect. Placing diagnostics as comments into the result tree (using

) is probably a more flexible solution. Some products, of course, have vendor-defined debugging aids built-in, or available from third parties.

Examples

The following example issues a message and quits if the value of the

element is non-numeric:

Unfortunately, there is no mechanism defined in the XSLT standard that allows the location of the error in the source document to be included in the message. In this example, validation against a schema would probably give better diagnostics.

The following example extends this by allowing several such errors to be reported in a single run, terminating the run only after all errors have been reported. It works by assigning a global variable to the set of nodes in error:

Localized Messages

XSLT is designed very much with internationalization in mind, and no doubt the requirement to localize message text was discussed by the working group. They clearly decided that no special facilities were needed and instead included a detailed example in the XSLT 1.0 specification showing how the message text can be localized (output in the user's native language). The example is worth repeating because it shows a general technique.

Messages for a particular language are stored in a file whose name identifies the language, for example German messages might be stored in
messages/de.xml
. The message file might have the structure:

A stylesheet that wishes to produce messages in the appropriate local language will need a parameter to identify this language. The stylesheet can then get access to the messages file for the appropriate language, and read the messages from there:

The same technique can, of course, be used for producing localized text to include in the output of the transformation.

See Also

on page 445

xsl:namespace

The

instruction constructs a namespace node that is written to the result sequence. Constructing namespace nodes in this way is not a frequent requirement, but there are situations where it is the only way of getting a required namespace declaration in the output.

Changes in 2.0

This instruction is new in XSLT 2.0.

Format

Position

is an instruction. It is always used as part of a sequence constructor.

Attributes

Content

If the
select
attribute is present, the element must be empty. Otherwise, it must contain a nonempty sequence constructor.

Effect

The
name
attribute determines the name of the namespace node. This corresponds to the namespace prefix. If the value of the
name
attribute is a zero-length string, the namespace node defines the default namespace. Otherwise, the name must be an NCName (a valid XML name containing no colon). The
name
attribute can be written as an attribute value template, allowing the name to be computed dynamically.

The string value of the namespace node, which represents the namespace URI, is established using either the
select
attribute or the contained sequence constructor. For consistency, this instruction uses the results of evaluating the
select
attribute or sequence constructor in the same way as other instructions such as

and

. This means that the result may be a sequence. Adjacent text nodes are merged, the sequence is atomized, each item in the atomized sequence is converted to a string, and the resulting strings are concatenated, with an intervening space used as a separator in the case where the
select
attribute is used. Normally, however, the result of the
select
attribute should be a single string.