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

There is no point in the TAN format itself. Indeed, there is no point to any file format, unless you can do things with it. TAN was designed with use primarily in mind. A major subdirectory in the official TAN release is called do things, populated with subdirectories 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, 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 is authoritative. It provides definitive interpretations of the TAN format and specifies if parts are in error. The function library is also powerful, in that many things you might want to do with a TAN file are already anticipated by at least one of its functions. But certain considerations that have been put into their design are worth noting.

First, the function library has a structure similar to that of the RELAX-NG schemas. That is, the primary way into the function library is through one of the eight XSLT files named after a primary TAN formats. You can access the function library deeper into the network, but you might be missing out on some important features.

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 into @base-uri 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

 Raw (first document available)ResolvedPrepped
<inclusion>$inclusions-1st-da$inclusions-resolved
<key>$keys-1st-da$keys-resolved
<source>$sources-1st-da$sources-resolved$sources-prepped
<see-also>$see-alsos-1st-da$see-alsos-resolved


The first column lists variables that hold the value of the first documents available for each element, without alteration. The second column lists variables that 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. If you wish to know more precisely how their values are determined, 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.