Top-level directories

The directories under the `texmf' root identify the major components of a TeX system (see Section section Summary for a summary). A site may omit any unneeded directories.

Although the TDS by its nature can specify precise locations only for implementation-independent files, we recognize that installers may well wish to place other files under `texmf' to simplify administration of the TeX tree, especially if it is maintained by someone other than the system administrator. Therefore, additional top-level directories may be present.

The top-level directories specified by the TDS are:

• `tex' for TeX files (Section section Macros).
• `fonts' for font-related files (Section section Fonts).
• `metafont' for METAFONT files which are not fonts (Section section Non-font METAFONT files).
• `metapost' for MetaPost files (Section section MetaPost).
• `bibtex' for BibTeX files (Section section BibTeX).
• `doc' for user documentation (Section section Documentation).
• `source' for sources. This includes both traditional program sources (for example, Web2c sources go in `texmf/source/web2c') and, e.g., LaTeX `dtx' sources (which go in `texmf/source/latex'). The TDS leaves unspecified any structure under `source'. `source' is intended for files which are not needed at runtime by any TeX program; it should not be included in any search path. For example, `plain.tex' does not belong under `texmf/source', even though it is a "source file" in the sense of not being derived from another file. (It goes in `texmf/tex/plain/base', as explained in Section section Macros).
• `implementation' for implementations (examples: `emtex', `web2c'), to be used for whatever purpose deemed suitable by the implementor or TeX administrator. Files that cannot be shared between implementations, such as pool files (`tex.pool') and memory dump files (`plain.fmt') go here, in addition to implementation-wide configuration files. See Section section Example implementation-specific trees for examples of real `implementation' trees.
• `extension' for program-specific input files for new programs (examples: `etex', `pdftex', `omega') that are extensions of TeX, METAFONT, or any standard program. See Section section Extensions.
• `program' for program-specific input and configuration files for any TeX-related programs (examples: `mft', `dvips'). In fact, the `tex', `metafont', `metapost', `bibtex', and `extension' items above may all be seen as instances of this case.

• Macros
• Fonts
• Non-font METAFONT files
• MetaPost
• BibTeX
• Documentation
• Extensions

Macros

TeX macro files shall be stored in separate directories, segregated by TeX format and package name (we use `format' in its traditional TeX sense to mean a usefully `\dump'-able package):

texmf/tex/format/package/

• `format' is a format name (examples: `amstex', `latex', `plain', `texinfo'). The TDS allows distributions that can be used as either formats or packages (e.g., Texinfo, Eplain) to be stored at either level, at the option of the format author or TeX administrator. We recommend that packages used as formats at a particular site be stored at the `format' level: by adjusting the TeX inputs search path, it will be straightforward to use them as macro packages under another format, whereas placing them in another tree completely obscures their use as a format. The TDS reserves the following `format' names:
  • `generic', for input files that are useful across a wide range of formats (examples: `null.tex', `path.sty'). Generally, this means any format that uses the category codes of Plain TeX and does not rely on any particular format. This is in contrast to those files which are useful only with Plain TeX (which go under `texmf/tex/plain'), e.g., `testfont.tex' and `plain.tex' itself.
  • `local', for local additions. See Section section Local additions.
  Thus, for almost every format, it is necessary to search at least the `format' directory and then the `generic' directory (in that order). Other directories may need to be searched as well, depending on the format. When using AMS-TeX, for example, the `amstex', `plain', and `generic' directories should be searched, because AMS-TeX is compatible with Plain.
• `package' is a TeX package name (examples: `babel', `texdraw'). In the case where a format consists of only a single file and has no auxiliary packages, that file can simply be placed in the `format' directory, instead of `format/base'. For example, Texinfo goes in `texmf/tex/texinfo/texinfo.tex', not `texmf/tex/texinfo/base/texinfo.tex'. The TDS reserves the following `package' names:
  • `base', for the base distribution of each format, including files used by INITEX when dumping format files. For example, in the standard LaTeX distribution, the `ltx' files created during the build process shall be stored in the `base' directory.
  • `hyphen', for hyphenation patterns, including the original American English `hyphen.tex'. These are typically used only by INITEX. In most situations, this directory need exist only under the `generic' format.
  • `images', for image input files, such as Encapsulated PostScript figures. Although it is somewhat non-intuitive for these to be under a directory named `tex', TeX needs to read these files to glean bounding box or other information. A mechanism for sharing image inputs between TeX and other typesetting programs (e.g., Interleaf, FrameMaker) is beyond the scope of the TDS. In most situations, this directory need exist only under the `generic' format.
  • `local', for local additions and configuration files. See Section section Local additions.
  • `misc', for packages that consist of a single file. An administrator or package maintainer may create directories for single-file packages at their discretion, instead of using `misc'.

Fonts

Font files shall be stored in separate directories, segregated by file type, font supplier, and typeface (`PK' and `GF' files need additional structure, as detailed in the next section):

texmf/fonts/type/supplier/typeface/

• `type' is the type of font file. The TDS reserves the following `type' names:
  • `afm', for Adobe font metrics.
  • `gf', for generic font bitmap files.
  • `pk', for packed bitmap files.
  • `source', for font sources (METAFONT files, property lists, etc.).
  • `tfm', for TeX font metric files.
  • `type1', for Type 1 fonts (in any format).
  • `vf', for virtual fonts.
  As usual, a site may omit any of these directories that are unnecessary (`gf' is a particularly likely candidate for omission).
• `supplier' is a name identifying font source (examples: `adobe', `ams', `public'). The TDS reserves the following `supplier' names:
  • `ams', for the American Mathematical Society's AMS-fonts collection.
  • `local', for local additions. See Section section Local additions.
  • `public', for freely redistributable fonts where the supplier neither (1) requested their own directory (e.g., `ams'), nor (2) also made proprietary fonts (e.g., `adobe'). It does not contain all extant freely distributable fonts, nor are all files therein necessarily strictly public domain.
  • `tmp', for dynamically-generated fonts, as is traditional on some systems. It may be omitted if unnecessary, as usual.
• `typeface' is the name of a typeface family (examples: `cm', `euler', `times'). The TDS reserves the following `typeface' names:
  • `cm' (within `public'), for the 75 fonts defined in Computers and Typesetting, Volume E.
  • `latex' (within `public'), for those fonts distributed with LaTeX in the base distribution.
  • `local', for local additions. See Section section Local additions.

Some concrete examples:

texmf/fonts/source/public/pandora/pnr10.mf
texmf/fonts/tfm/public/cm/cmr10.tfm
texmf/fonts/type1/adobe/utopia/putr.pfa

For complete supplier and typeface name lists, consult Filenames for TeX fonts (see Appendix section Related references).

• Font bitmaps
• Valid font bitmaps

Font bitmaps

Font bitmap files require two characteristics in addition to the above to be uniquely identifiable: (1) the type of device (i.e., mode) for which the font was created; (2) the resolution of the bitmap.

Following common practice, the TDS segregates fonts with different device types into separate directories. See `modes.mf' in Appendix section Related references for recommended mode names.

Some printers operate at more than one resolution (e.g., at 300dpi and 600dpi), but each such resolution will necessarily have a different mode name. Nothing further is needed, since implicit in the TeX system is the assumption of a single target resolution.

Two naming strategies are commonly used to identify the resolution of bitmap font files. On systems that allow long filenames (and in the original METAFONT program itself), the resolution is included in the filename (e.g., `cmr10.300pk'). On systems which do not support long filenames, fonts are generally segregated into directories by resolution (e.g., `dpi300/cmr10.pk').

Because the TDS cannot require long filenames, we must use the latter scheme for naming fonts. So we have two more subdirectory levels under `pk' and `gf':

texmf/fonts/pk/mode/supplier/typeface/dpinnn/
texmf/fonts/gf/mode/supplier/typeface/dpinnn/

• `mode' is a name which identifies the device type (examples: `cx', `ljfour', `modeless'). Usually, this is the name of the METAFONT mode used to build the `PK' file. For fonts rendered as bitmaps by a program that does not distinguish between different output devices, the `mode' name shall be simply `modeless'. The `mode' level shall not be omitted, even if only a single mode happens to be in use.
• `dpinnn' specifies the resolution of the font (examples: `dpi300', `dpi329'). `dpi' stands for dots per inch, i.e., pixels per inch. We recognize that pixels per millimeter is used in many parts of the world, but dpi is too traditional in the TeX world to consider changing now. The integer `nnn' is to be calculated as if using METAFONT arithmetic and then rounded; i.e., it is the integer METAFONT uses in its output `gf' filename. We recognize small differences in the resolution are a common cause of frustration among users, however, and recommend implementors follow the level 0 DVI driver standard (see Appendix section Related references) in bitmap font searches by allowing a fuzz of +-0.2% (with a minimum of 1) in the `dpi'.

Implementations may provide extensions to the basic naming scheme, such as long filenames (as in the original METAFONT) and font library files (as in emTeX's `.fli' files), provided that the basic scheme is also supported.

Valid font bitmaps

The TWG recognizes that the use of short filenames has many disadvantages. The most vexing is that it results in the creation of dozens of different files with the same name. At a typical site, `cmr10.pk' will be the filename for Computer Modern Roman 10pt at 5--10 magnifications for 2--3 modes. (Section section Duplicate filenames discusses duplicate filenames in general.)

To minimize this problem, we strongly recommend that `PK' files contain enough information to identify precisely how they were created: at least the mode, base resolution, and magnification used to create the font.

This information is easy to supply: a simple addition to the local modes used for building the fonts with METAFONT will automatically provide the required information. If you have been using a local modes file derived from (or that is simply) `modes.mf' (see Appendix section Related references), the required information is already in your `PK' files. If not, a simple addition based on the code found in `modes.mf' can be made to your local modes file and the `PK' files rebuilt.

Non-font METAFONT files

Most METAFONT input files are font programs or parts of font programs and are thus covered by the previous section. However, a few non-font input files do exist. Such files shall be stored in:

texmf/metafont/package/

`package' is the name of a METAFONT package (for example, `mfpic').

The TDS reserves the following `package' names:

• `base', for the standard METAFONT macro files as described in The METAFONTbook, such as `plain.mf' and `expr.mf'.
• `local', for local additions. See Section section Local additions.
• `misc', for METAFONT packages consisting of only a single file (for example, `modes.mf').

MetaPost

MetaPost is a picture-drawing language developed by John Hobby, derived from Knuth's METAFONT. Its primary purpose is to output Encapsulated PostScript instead of bitmaps.

MetaPost input files and the support files for MetaPost-related utilities shall be stored in:

texmf/metapost/package/

`package' is the name of a MetaPost package. At the present writing none exist, but the TWG thought it prudent to leave room for contributed packages that might be written in the future.

The TDS reserves the following `package' names:

• `base', for the standard MetaPost macro files, such as `plain.mp', `mfplain.mp', `boxes.mp', and `graph.mp'. This includes files used by INIMP when dumping mem files containing preloaded macro definitions.
• `local', for local additions. See Section section Local additions.
• `misc', for MetaPost packages consisting of only a single file.
• `support', for additional input files required by MetaPost utility programs, including a font map, a character adjustment table, and a subdirectory containing low-level MetaPost programs for rendering some special characters.

BibTeX

BibTeX-related files shall be stored in:

texmf/bibtex/bib/package/
texmf/bibtex/bst/package/

The `bib' directory is for BibTeX database (`.bib') files, the `bst' directory for style (`.bst') files.

`package' is the name of a BibTeX package. The TDS reserves the following `package' names (the same names are reserved under both `bib' and `bst'):

• `base', for the standard BibTeX databases and styles, such as `xampl.bib', `plain.bst'.
• `local', for local additions. See Section section Local additions.
• `misc', for BibTeX packages consisting of only a single file.

Documentation

Most packages come with some form of documentation: user manuals, example files, programming guides, etc. In addition, many independent files not part of a macro or other package describe various aspects of the TeX system.

The TDS specifies that these additional documentation files shall be stored in a structure that parallels to some extent the `fonts' and `tex' directories, as follows:

texmf/doc/category/...

`category' identifies the general topic of documentation that resides below it; for example, a TeX format name (`latex'), program name (`bibtex', `tex'), language (`french', `german'), or other system components (`web', `fonts').

The TDS reserves the following categories:

• Within each `category' tree for a TeX format, the directory `base' is reserved for base documentation distributed by the format's maintainers.
• `general', for standalone documents not specific to any particular program (for example, Joachim Schrod's Components of TeX).
• `help', for meta-information, such as FAQ's, David Jones' macro index, etc.
• `html', for HTML documents.
• `info', for processed Texinfo documents. (Info files, like anything else, may also be stored outside the TDS, at the installer's option.)
• `local', for local additions. See Section section Local additions.

The `doc' directory is intended for implementation-independent and operating system-independent documentation files. Implementation-dependent files shall be stored elsewhere, as provided for by the implementation and/or TeX administrator (for example, VMS help files under `texmf/vms/help').

The documentation directories may contain TeX sources, DVI files, PostScript files, text files, example input files, or any other useful documentation format(s).

See Section section Documentation tree summary for a summary.

Extensions

New programs that are extensions of old ones shall use a new top-level directory name for their extension-specific input files. The new directory shall have the same general structure as the top-level directory of the original program, and the new program almost certainly should search the original top-level directory.

For example, several variants of TeX that recognize additional commands have been released. Input files that use these new commands cannot be placed in the top-level `tex' directory, since the original TeX program cannot read them. So they must go in a new directory, with the same package structure as `tex' (see Section section Macros).

Using e-TeX as an example, we have the following:

• A new top-level (in `texmf') directory `etex'.
• Since e-TeX is an extension of TeX, `texmf/etex' follows the same conventions as `texmf/tex'. `texmf/etex' contains only e-TeX-specific files.
• e-TeX searches first `texmf/etex', then `texmf/tex'.

These same principles hold for PDFTeX, Omega, and (most probably) future variants of TeX or METAFONT.