Chapter 10. Best Practices in Working with TAN Files

Table of Contents

File Setup
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, especially the mistakes, of TAN users. The material is designed for users of TAN files who have advanced experience in working with XML files or technology, generally.

TAN files may be set up in any kind of structure one wishes, but because those files are meant to be shared, it is in everyone's interests to use similar conventions, so that TAN files with relative URLs have a chance of staying intact.

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

Under this model, any time you decided to develop a collection of TAN files, you would 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 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 different but overlapping TAN collections.

Any given TAN collection will be littered with files that share certain metadata such as work, language, editor, and date. When you name class 1 files, 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, they can wind up with filenames that are 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. 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. The examples subdirectory illustrates these naming suggestions.

If you are have a local copy of a TAN collection from someone else, and you wish to write 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. Validation will use only the first document available, so only the local version will be checked. But if you share your dependent TAN file with someone else who does not have access to the collection you did, the absolute URL will step in to provide the first document available.