Chapter 10. Best Practices in Working with TAN Files

Table of Contents

Local Setup
Creating and maintaining TAN collections
Creating and editing TAN files
Sharing TAN files
Doing Things with TAN Files (Stylesheets and the Function Library)

In this chapter we discuss ways to manage, create, edit, and share TAN files. The material discussed here is non-normative. That is, these are suggestions based upon the experience, particularly the mistakes, of TAN users. The material is written for intermediate or advanced users of XML technology.

TAN files may be set up in any kind of structure one wishes, but because those files are meant to be shared, it is beneficial to use similar conventions, to minimize the possibility of breaking relative URLs in shared TAN files.

Below is one way to organize the subdirectories of a typical local TAN project:

Under this model, any time you decide to develop a collection of TAN files, you create a subdirectory within the library. It is a good idea to try to keep these collections to a manageable size, although it cannot be predicted what the limits might be. If you use Git, each of these collections could be its own Git repository. This is also where you would put other people's TAN collections. Collections inevitably need to "talk" to each other, so it is a good idea to name collection subdirectories as predictably and briefly as possible, preferably a single word in lowercase. For example, scriptural collections could be named simply bible or quran, although you may find a need to add a suffix if you are working with overlapping TAN collections.

When you name class 1 files (the filename, not the IRI name; see the section called “@id and a TAN file's IRI Name”), it is a good idea to start with an acronym for the work, followed by the language code, the editor's last name, and perhaps the date when the underlying scriptum was created or published. Class 2 files are tougher. Because they bring two or more files or concepts together, filenames could become very long or unpredictably structured. At this time, the best recommendation is to make sure that each class 2 file is put into a subdirectory, separate from class 1 files, given a brief but meaningful name that points to the research question that motivated its creation. Class 3 are a bit easier. It is recommended that TAN-mor files begin with the language code then an acronym for the person or group responsible for creating the features. TAN-key and TAN-c files are written generally to serve a specific collection, so the collection name and the TAN type should suffice.

If you are have a local copy of someone else's TAN collection, and you wish to create TAN files that depend on them, you are in all likelihood going to depend upon relative URLs to those files. It is recommended that you also include absolute URL through secondary <location>s. The validation routine checks only the first document available. From time to time, you might comment out the first <location> and run the validation process again. If you share your dependent TAN file with someone else who does not have a local copy of the collection, the second <location>, with the absolute URL, will furnish a copy of the document.