Doing Things with TAN Files (Stylesheets and the Function Library)

The TAN format is not an end in itself. Indeed, there is no point to any file format, unless you can do things with it. TAN was designed primarily so that users could do unusual and interesting things. /do things, a major subdirectory in the project file, is populated with folders named with actions you might want to perform on a TAN file, and they contain XSLT stylesheets that fall into that area of activity.

Those stylesheets are the front end of a long process that begins with TAN validation. Whenever you validate a TAN file, the Schematron validation file (the companion to the RELAX-NG validation file) is invoked. But that Schematron file is very small, and does very little work during validation, other than to look for errors, information, and help in a second version of the file being validated. That second version of the file is created through a very large library of XSLT stylesheets that resolve, normalize, and expand the document, and mark its errors.

That extensive library of XSLT we call here the function library (we use both words, to distinguish the collection from individual, generic functions). The function library provides definitive interpretations of the TAN format, marking parts that are in error. The function library is also an important step to creating your own tools or stylesheets, anticipating, as it does, many things you might want to do with a TAN file. Certain considerations that have been put into the design of the function library are worth noting.

First, the function library has a structure similar to that of the RELAX-NG schemas. That is, the primary access point is through one of the eight XSLT files named after a primary TAN formats. Access deeper into the function library structure is possible, but you might be missing out on some important features useful to the particular TAN format you are working with.

Before executing any validation, an engine computes all global variables, even those that might, in the end, not be required. Therefore the function library defines only those global variables that are central to the validation process. Functions, templates, and keys, on the other hand, are used by a validation engine only when needed, so some of them provide functionality that looks beyond the validation process.

The most complex and important global variables are the two principal transformations to the TAN file itself, $self-resolved and $self-prepped.

$self-resolved is the result of changing the TAN file through some key steps, including (1) stamping the original uri of the file @base-uri


This attribute is one of a number of new attributes and elements that are introduced in the validation process, and are not defined by the TAN schema.

in the root element, (2) converting all numeration systems to Arabic numerals, (3) replacing all elements that have @include with resolved forms of the element, (4) replacing elements with @which with their resolved IRI + name form, (5) stamping elements with @q and a number representing the nth place of that element relative to its original siblings (included elements are given the @q of their host element).

$self-prepped is the result of combing through the file and looking for errors that have been defined in the master list of errors. The process differs from one TAN file type to the next.

The next most important global variables have to do with the other TAN files the self refers to:

Table 10.1. Global variables for referred files

The first column lists variables that hold the first documents available, without alteration. Variable in the second column hold the resolved form of the -1st-da variables, following the same process described above for $self-resolved. Once $self-resolved has been determined, neither <inclusion> nor <key> are needed for further validation, therefore they do not have prepped versions. Any bearing <see-also> has on validation of the original TAN file can be determined from the resolved form. But it frequently happens, mainly with class 2 files, that the sources need to go through some preparation before determining whether or not the original is valid, so a similar process of preparation is applied.

These global variables have been described above very generally. To know more precisely how their values are calculated, please consult the function library.

The other components of the function library—the functions, keys, and templates—cannot be described conveniently or succinctly here. But they are critical parts of building successful stylesheets that transform TAN files. The next chapter provides a comprehensive view of how they work.