General

This section describes common properties throughout the TDS tree.

• Subdirectory searching
• Rooting the tree
• Local additions
• Duplicate filenames

Subdirectory searching

Many TeX installations store large numbers of related files in single directories, for example, all `TFM' files and/or all TeX input files.

This monolithic arrangement hinders maintenance of a TeX system: it is difficult to determine what files are used by what packages, what files need to be updated when a new version is installed, or what files should be deleted if a package is removed. It is also a source of error if two or more packages happen to have input files with the same name.

Therefore, the TWG felt each package should be in a separate directory. But we recognized that explicitly listing all directories to be searched would be unbearable. A site may wish to install dozens of packages. Aside from anything else, listing that many directories would produce search paths many thousands of characters long, overflowing the available space on some systems.

Also, if all directories are explicitly listed, installing or removing a new package would mean changing a path as well as installing or removing the actual files. This would be a time-consuming and error-prone operation, even with implementations that provide some way to specify the directories to search at runtime. On systems without runtime configuration, it would require recompiling software, an intolerable burden.

As a result, the TWG concluded that a comprehensive TDS requires implementations to support some form of implicit subdirectory searching. More precisely, implementations must make it possible to specify that TeX, METAFONT, and their companion utilities search in both a specified directory and recursively through all subdirectories of that directory when looking for an input file. Other forms of subdirectory searching, for example recursive-to-one-level searches, may also be provided. We encourage implementors to provide subdirectory searching at the option of the installer and user for all paths.

The TDS does not specify a syntax for specifying recursive searching, but we encourage implementors to provide interoperability (see Section section More on subdirectory searching).

Rooting the tree

In this document, we shall designate the root TDS directory by `texmf' (for "TeX and METAFONT"). We recommend using that name where possible, but the actual name of the directory is up to the installer. On PC networks, for example, this could map to a logical drive specification such as `T:'.

Similarly, the location of this directory on the system is site-dependent. It may be at the root of the file system; on Unix systems, `/usr/local/share', `/usr/local', `/usr/local/lib', and `/opt' are common choices.

The name `texmf' was chosen for several reasons: it reflects the fact that the directory contains files pertaining to an entire TeX system (including METAFONT, MetaPost, BibTeX, etc.), not just TeX itself; and it is descriptive of a generic installation rather than a particular implementation.

A site may choose to have more than one TDS hierarchy installed (for example, when installing an upgrade). This is perfectly legitimate.

Local additions

The TDS cannot specify precisely when a package is or is not a "local addition". Each site must determine this according to their own conventions. At the two extremes, one site might wish to consider "nonlocal" all files that not acquired as part of the installed TeX distribution; another site might consider "local" only those files that were actually developed at the local site and not distributed elsewhere.

We recognize two common methods for local additions to a distributed `texmf' tree. Both have their place; in fact, some sites may employ both simultaneously:

1. A completely separate tree which is a TDS structure itself; for example, `/usr/local/umbtex' at the University of Massachusetts at Boston. This is another example of the multiple `texmf' hierarchies mentioned in the previous section.
2. A directory named `local' at any appropriate level, for example, in the `format', `package', and `supplier' directories discussed in the following sections. The TDS reserves the directory name `local' for this purpose. We recommend using `local' for site-adapted configuration files, such as `language.dat' for the Babel package or `graphics.cfg' for the graphics package. Unmodified configuration files from a package should remain in the package directory. The intent is to separate locally modified or created files from distribution files, to ease installing new releases.

One common case of local additions is dynamically generated files, e.g., `PK' fonts by the `MakeTeXPK' script originated by Dvips. A site may store the generated files directly in any of:

• their standard location in the main TDS tree (if it can be made globally writable);
• an alternative location in the main TDS tree (for example, under `texmf/fonts/tmp');
• a second complete TDS tree (as outlined above);
• any other convenient directory (perhaps under `/var', for example `/var/spool/fonts').

No one solution will be appropriate for all sites.

Duplicate filenames

Different files by the same name may exist in a TDS tree. The TDS generally leaves unspecified which of two files by the same name in a search path will be found, so generally the only way to reliably find a given file is for it to have a unique name. However, the TDS requires implementations to support the following exceptions:

• Names of TeX input files must be unique within each first-level subdirectory of `texmf/tex' and `texmf/tex/generic', but not within all of `texmf/tex'; i.e., different TeX formats may have files by the same name. (Section section Macros discusses this further.) Thus, no single format-independent path specification, such as a recursive search beginning at `texmf/tex' specifying no other directories, suffices. So implementations must provide format-dependent path specifications, for example via wrapper scripts or configuration files.
• Many font files will have the same name (e.g., `cmr10.pk'), as discussed in Section section Valid font bitmaps. Implementations must distinguish these files by mode and resolution.

All implementations we know of already have these capabilities.

One place where duplicate names are likely to occur is not an exception:

• Names of METAFONT input files (as opposed to bitmaps) must be unique within all of `texmf/fonts'. In practice, this is a problem with some variants of Computer Modern which contain slightly modified files named `punct.mf', `romanl.mf', and so on. We believe the only feasible solution is to rename the derivative files to be unique.