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

• The
  letter-value
  attribute is intended for languages such as Hebrew that have several possible sequences starting with the same token (see
  http://www.i18nguy.com/unicode/hebrew-numbers.html
  ). The two permitted values are
  alphabetic
  and
  traditional
  .
  

The detailed effect of these attributes is left entirely to the implementor, so you can't expect different products necessarily to behave in the same way. There has been a great deal of discussion on Internet mailing lists about the exact details of certain numbering sequences. With those sequences such as Roman numerals and Hebrew numbering that have a long history, practices have certainly varied at different times and places, so there is no single answer.

All the attributes controlling formatting are attribute value templates, so they can be parameterized using expressions enclosed in curly braces. This is mainly useful if you want to select the values from a localization file based on the preferred language of the current user. To achieve this, you can use the same techniques as described for localizing messages: see

on page 389.

Outputting the Number

The final action of

is to write the generated string to the current result sequence, as a text node.

If you want to do something else with the number (perhaps to write it as an attribute or to copy it to every page heading), you can save it as the value of a variable, as follows:

Writing the value to a variable also allows you to perform further manipulation. For example, if you want to use the traditional numbering sequence for footnotes
(*
,
†
,
‡
,
§
,
¶ )
, you cannot do this directly in

because these characters are punctuation symbols rather than alphanumerics. What you can do, however, is use conventional decimal numbering and then convert, for example:

The
translate()
function replaces characters in its second argument by the corresponding character in the third argument: It is described in Chapter 13. In practice it might be safer to use character references for these special characters to avoid them being mangled by a text editor that doesn't understand Unicode.

Usage and Examples

Although the rules for

are very general and sometimes complex, most common cases are quite straightforward.

The general rules allow for numbering any kind of node, but in practice the

instruction is almost invariably used for numbering elements. So in this section, I'll assume that the selected node is an element.

level = “single”

This option (the default) is used to number sibling elements.

The simplest way of using

is without any attributes:

If the current element is the eighth

element owned by its parent element, say, this will write the text value
8
to the current output destination. Technically, the processor is counting all the elements that match the pattern in the
count
attribute, and the default for the
count
attribute in this case is a pattern that matches

elements.

For this simple kind of numbering, it is often better to use the
position()
function, particularly if there are many nodes to be numbered. This is because with a typical implementation, each node that is numbered using

will result in the preceding siblings being counted, which will take an increasingly long time as the number of siblings increases. With the
position()
function, it is much more likely that the system already knows the position and doesn't have to do any special walking around the tree and pattern matching. Of course, this is only possible where
position()
and

produce the same answer, which will happen when the sequence of nodes being processed using

or

consists of all the sibling elements of a particular element type.

Another option for numbering is to use the
count()
function, for example
count(preceding-sibling::item)+1
. This is often simpler if you want to use the number for further processing, rather than formatting it for output.