The global variables in the TAN function library provide quick access to some important material. For a complete list of global variables, with detailed lists of dependencies and dependents, see Chapter 13, TAN functions, templates, global variables, and keys. That technical appendix will not provide the context necessary to identify some of the key features of the global variables, which this section attempts to provide.
As noted above, the primary task of the TAN function library is to drive the
validation process, described in the previous section. If you are developing an
application that begins with a TAN file, whether as primary or secondary input, it is
often best to start with it in its resolved or expanded state. If that TAN file is
the primary (catalyzing) input, use the global variables $tan:self-resolved
and
$tan:self-expanded
.
If it is secondary input, use tan:resolve-doc()
and tan:expand-doc()
. You must resolve a TAN file before you attempt
to expand it.
For a class-2 file, $tan:self-expanded
, or the output of tan:expand-doc()
, is a sequence of
documents, starting with an expansion of the class-2 file, followed by expansions of
its dependencies (TAN-T or TAN-mor). Its expanded class-1 sources will be tokenized
where required, and marked with anchors for each reference in the class-2 file. If a
token straddles leaf <div>
s,
the token will be reconstituted by moving the tail of the token up. These expanded
sources are excellent candidates for other types of transformation. For example, HTML
pages can be created to integrate class-2 annotations and their class-1 sources, in a
variety of ways.
Even when the validation mode is turned off (default), the validation phase (terse, normal, verbose) plays a significant role in the results of expansion. At the terse and normal phases, an expanded class-2 file will contain expanded versions of both the host file and its sources.
At the verbose level, an expanded TAN-A file will conclude its $tan:self-expanded
sequence with
one or more documents with a root element <TAN-T_merge>
, one file per
detected work. A TAN-T_merge file has one <head>
per class-1 source that has been merged, and the
<body>
contains a master
set of <div>
s that merge all
the other sources' <div>
s that
share the same reference, after all <adjustments>
have been made. Each leaf <div>
in each source appears in the
appropriate place, but as a child of a common <div>
that encompasses all other leaf <div>
s with the same reference. For
each version's leaf div, @type
is
changed to #version
, and other markers signify which source it
corresponds to. A TAN-T_merge file is a good basis building parallel displays (e.g.,
the section called “Parabola”) or statistical analyses. These merge files can be
created on an ad hoc basis through the function tan:merge-expanded-docs()
,
applied to individual class-1 files, after expansion.
If your application uses a TAN file as the primary input, you may want to take advantage of some other important global (see the section called “Networked Files”):
Table 10.1. Global variables for networked files
Raw (first document available) | Resolved | Expanded | |
---|---|---|---|
<inclusion> | — | $inclusions-resolved | — |
<vocabulary> | — | $vocabularies-resolved | — |
<source> | — | $sources-resolved | $self-expanded[tan:TAN-T] |
<see-also> | $see-alsos-1st-da | $see-alsos-resolved | — |
The column labeled "raw" lists variables that hold the first documents available,
without alteration. Variables in the next column hold the resolved form, following
the same process described above for $tan:self-resolved
. The resolved forms of <inclusion>
and <vocabulary>
are sufficient for
validation, therefore they do not have expanded versions. Expanded sources are always
bundled with their class-2's $tan:self-expanded
.
For most applications, a resolved file is a sufficient starting point. But even
then, there will be places where you will want to fetch the vocabulary bound to a
particular attribute or element. One of the more important functions to familiarize
yourself with is tan:vocabulary()
, which can be used to get the IRI + name pattern
of a specific node, or to get all the vocabulary available for a given type.
Some developers will find even tan:vocabulary()
a hassle to use. Consider setting the global
parameter $tan:distribute-vocabulary
(default false
) to
true
. If that happens, whenever an attribute with an idref appears,
it it will be imprinted with the corresponding IRI + name pattern for the referred
vocabulary item. Exercise this option with care: the expanded document will grow
significantly larger.