A Directory Structure for Tex Files

TUGboat, Volume 16 (1995), No. 4 401

A Directory Structure for TEX Files (Version 0.999) TUG Working Group on a TEX Directory Structure (TWG-TDS) 1 Introduction TEX is a powerful, flexible typesetting system used by thousands of people around the world. It is ex- tremely portable and runs on virtually all operating systems. One unfortunate side effect of TEX’s flexibility, however, is that there has been no single “right” way to install it. This has resulted in many sites having different installed arrangements. The primary purpose of this document is to describe a standard TEX Directory Structure (TDS): a directory hierarchy for macros, fonts, and the other implementation-independent TEX system files. As a matter of practicality, this document also suggests ways to incorporate the rest of the TEXfilesintoa single structure. The TDS has been designed to work on all modern systems. In particular, the Technical Working Group (TWG) believes it is usable under MacOS, MS-DOS, OS/2,Unix,VMS, and Windows NT. We hope that administrators and developers of both free and commercial TEX implementations will adopt this standard. This document is intended both for the TEX system administrator at a site and for people prepar- ing TEX distributions—everything from a complete runnable system to a single macro or style file. It may also help TEX users find their way around systems organized this way. It is not a tutorial: we necessarily assume knowledge of the many parts of a working TEX system. If you are unfamiliar with any of the programs or file formats we refer to, consult the references in Appendix D.

1.1 The role of the TDS The role of the TDS is to stabilize the organization of TEX-related software packages that are installed and in use, possibly on multiple platforms simultaneously. At first glance, it may seem that the Compre- hensive TEX Archive Network (CTAN) archives ful- fill at least part of this role, but this is not the case. The role of CTAN is to simplify archiving and distribution, not installation and use. In fact, the roles of the TDS and CTAN are fre- quently in conflict, as you will see elsewhere in this document. For distribution, many different types of files must be combined into a single unit; for use, it is traditional to segregate files (even similar files) from a single package into separate, occasionally distant, directories. 402 TUGboat, Volume 16 (1995), No. 4

1.2 Conventions As a result, the TWG concluded that a com- In this document, “/” is used to separate ﬁlename prehensive TDS requires implementations to support components; for example, texmf/fonts. This is the some form of implicit subdirectory searching. More

Unix convention but the ideas are in no way Unix- precisely, implementations must make it possible to

AFONT speciﬁc. specify that TEX, MET , and their companion utilities search in both a speciﬁed directory and re- In this document, “TEX” generally means the

cursively through all subdirectories of that directory

AFONT TEX system, including MET , DVI drivers, when looking for an input file. Other forms of subdi- utilities, etc., not just the TEX program itself. The word “package” in this document has its rectory searching, for example recursive-to-one-level usual meaning: a set of related files distributed, searches, may also be provided. We encourage im- installed, and maintained as a unit. This is not a plementors to provide subdirectory searching at the option of the installer and user for all paths. LATEX2ε package, which is a style file supplementing a document class. The TDS does not specify a syntax for specify- We use the following typographic conventions: ing recursive searching, but we encourage implementors to provide interoperability (see Section B.2). literal Literal text such as filename is typeset in typewriter type. 2.2 Rooting the tree

In this document, we shall designate the root TDS

AFONT hreplaceablei Replaceable text such as hpackagei, directory by ‘texmf’(for“TEXandMET ”). identifying a class of things, is typeset in italics We recommend using that name where possible, but inside angle brackets. the actual name of the directory is up to the installer. On PC networks, for example, this could 2 General map to a logical drive specification such as T:. This section describes common properties through- Similarly, the location of this directory on the out the TDS tree. system is site-dependent. It may be at the root of the file system; on Unix systems, /usr/local/ 2.1 Subdirectory searching share, /usr/local, /usr/local/lib,and/opt are Many TEX installations store large numbers of re- common choices. lated files in single directories, for example, all TFM The name texmf was chosen for several rea- files and/or all TEX input files. sons: it reflects the fact that the directory contains

This monolithic arrangement hinders mainte- ﬁles pertaining to an entire TEX system (including

AFONT METAP OST

MET Bib nance of a TEX system: it is difficult to determine , , TEX, etc.), not just what files are used by what packages, what files need TEX itself; and it is descriptive of a generic installa- to be updated when a new version is installed, or tion rather than a particular implementation. what files should be deleted if a package is removed. A site may choose to have more than one TDS It is also a source of error if two or more packages hierarchy installed (for example, when installing an happen to have input files with the same name. upgrade). This is perfectly legitimate. Therefore, the TWG felt each package should 2.3 Local additions be in a separate directory. But we recognized that explicitly listing all directories to be searched would The TDS cannot specify precisely when a package be unbearable. A site may wish to install dozens is or is not a “local addition”. Each site must de- of packages. Aside from anything else, listing that termine this according to their own conventions. At many directories would produce search paths many the two extremes, one site might wish to consider thousands of characters long, overflowing the avail- “nonlocal” only those files that came with the par- able space on some systems. ticular TEX distribution they installed; another site Also, if all directories are explicitly listed, in- might consider “local” only those files that were ac- stalling or removing a new package would mean tually developed at the local site and not distributed changing a path as well as installing or removing elsewhere. the actual files. This would be a time-consuming We recognize two common methods for local and error-prone operation, even with implementa- additions to a distributed texmf tree. Both have tions that provide some way to specify the direc- their place; in fact, some sites may employ both tories to search at runtime. On systems without simultaneously: runtime configuration, it would require recompiling 1. A completely separate tree which is a TDS software, an intolerable burden. structure itself; for example, /usr/local/umbtex TUGboat, Volume 16 (1995), No. 4 403

at the University of Massachusetts at Boston. All implementations we know of already have This is another example of the multiple texmf these capabilities. hierarchies mentioned in the previous section. One place where duplicate names are likely to 2. A directory named ‘local’ at any appropriate occur is not an exception:

level, for example, in the hformati, hpackagei,

AFONT • Names of MET input files (as opposed and hsupplieri directories discussed in the fol- to bitmap fonts) must be unique within all of lowing sections. The TDS reserves the directory texmf/fonts. In practice, this is a problem name local for this purpose. with those variants of Computer Modern which We recommend using local for site-adapted contain slightly modified files named punct.mf, configuration files, such as language.dat for romanl.mf, and so on. We believe the only the Babel package or graphics.cfg for the feasible solution here is simply to rename the graphics package. Unmodified configuration derivative files to be unique. files from a package should remain in the package directory. The intent is to separate locally 3 Top-level directories modified or created files from distribution files, The directories under the texmf root identify the to ease installing new releases. major components of a TEX system (see Table 1 One common case of local additions is dynami- for a summary). A site may omit any unneeded cally generated files, e.g., PK fonts by the MakeTeXPK directories. script originated by Dvips. A site may store the gen- Although the TDS by its nature can specify pre- erated files directly in any of: cise locations only for implementation-independent • their standard location in the main TDS tree (if files, we recognize that installers may well wish to it can be made globally writable); place other files under texmf to simplify adminis- • an alternative location in the main TDS tree tration of the TEX tree, especially if it is maintained (for example, under texmf/fonts/tmp); by someone other than the system administrator. • a second complete TDS tree (as outlined above); Therefore, additional top-level directories may be present. • any other convenient directory (perhaps under The top-level directories specified by the TDS /var, for example /var/spool/fonts). are: No one solution will be appropriate for all sites. tex for TEX files (Section 3.1).

2.4 Duplicate ﬁlenames fonts for font-related ﬁles (Section 3.2).

AFONT Different files by the same name may exist in a TDS metafont for MET files which are not fonts tree. The TDS generally leaves unspecified which of (Section 3.3).

two files by the same name in a search path will be AP OST metapost for MET files (Section 3.4). found, so generally the only way to reliably find a bibtex for BibT X files (Section 3.5). given file is for it to have a unique name. However, E the TDS requires implementations to support the doc for user documentation (Section 3.6). following exceptions: source for sources. This includes both traditional • Names of TEX input files must be unique program sources (for example, Web2c sources within each first-level subdirectory of texmf/ go in texmf/source/web2c)andLATEX dtx tex and texmf/tex/generic, but not within sources (which go in texmf/source/latex). all of texmf/tex; i.e., different TEX formats source is intended for files which are not may have files by the same name. (Section 3.1 needed at runtime by any TEX program; it discusses this further.) Thus, no single format- should not be included in any search path. independent path specification, such as a re- For example, plain.tex does not belong under cursive search beginning at texmf/tex specify- texmf/source, even though it is a “source file” ing no other directories, suffices. So implemen- in the sense of not being derived from another tations must provide format-dependent path file, but rather in texmf/tex/plain/base,as specifications, for example via wrapper scripts explained in Section 3.1. or configuration files. himplementationi for implementations (examples: • Many font files will have the same name (e.g., emtex, web2c), to be used for whatever purpose cmr10.pk), as discussed in Section 3.2.2. Imple- deemed suitable by the implementor or TEXad- mentations must distinguish these files by mode ministrator. Files that cannot be shared be- and resolution. tween implementations, such as pool files (tex. 404 TUGboat, Volume 16 (1995), No. 4

pool) and memory dump files (plain.fmt)go In the case where a format consists of only a here, in addition to implementation-wide con- single file and has no auxiliary packages, that figuration files. See Section B.3 for examples of file can simply be placed in the hformati direc- real himplementationi trees. tory, instead of hformati/base. For example, hprogrami for individual configuration files and pro- Texinfo goes in texmf/tex/texinfo/texinfo. gram-specific input files for TEX-related pro- tex,nottexmf/tex/texinfo/base/texinfo. grams (examples: mft, dvips). In fact, the tex. tex, metafont, metapost,andbibtex direc- The TDS reserves the following hpackagei tories above may be seen as instances of this names: case. • base, for the base distribution of each format, including files used by when 3.1 Macros INITEX dumping format files. For example, in the TEX macro files shall be stored in separate direc- standard LATEX distribution, the ltx files tories, segregated by TEX format and package name created during the build process shall be (we use ‘format’ in its traditional TEX sense to mean stored in the base directory. a usefully \dump-able package): • hyphen, for hyphenation patterns, includ- texmf/tex/hformati/hpackagei/ ing the original American English hyphen. hformati is a format name (examples: amstex, tex. These are typically used only by latex, plain, texinfo). INITEX. In most situations, this directory The TDS allows distributions that can be need exist only under the generic format. used as either formats or packages (e.g., Tex- • images, for image input files, such as En- info, Eplain) to be stored at either level, at capsulated PostScript figures. Although the option of the format author or TEXadmin- it is somewhat non-intuitive for these to istrator. We recommend that packages used be under a directory named “tex”, TEX as formats at a particular site be stored at needs to read these files to glean bounding the hformati level: by adjusting the TEXin- box or other information. A mechanism puts search path, it will be straightforward to for sharing image inputs between TEXand use them as macro packages under another for- other typesetting programs (e.g., Interleaf, mat, whereas placing them in another tree com- FrameMaker) is beyond the scope of the pletely obscures their use as a format. TDS. In most situations, this directory The TDS reserves the following hformati need exist only under the generic format. names: • local, for local additions and configura- • generic, for input files that are useful tion files. See Section 2.3. across a wide range of formats (exam- • misc, for packages that consist of a single ples: null.tex, path.sty). Generally, file. An administrator or package main- this means any format that uses the cat- tainer may create directories for single-file egory codes of Plain TEX and does not packages at their discretion, instead of us- rely on any particular format. This is ing misc. in contrast to those files which are useful only with Plain TEX (which go un- 3.2 Fonts der texmf/tex/plain), e.g., testfont. Font files shall be stored in separate directories, seg- tex and plain.tex itself. regated by file type, font supplier, and typeface (PK • local, for local additions. See Section 2.3. and GF files need additional structure, as detailed in Thus, for almost every format, it is neces- the next section): sary to search at least the hformati directory texmf/fonts/htypei/hsupplieri/htypefacei/ and then the generic directory (in that order). htypei isthetypeoffontfile.TheTDS reserves the Other directories may need to be searched as following htypei names: well, depending on the format. When using • afm, for Adobe font metrics. AMS-TEX, for example, the amstex, plain, and generic directories should be searched, be- • gf, for generic font bitmap files. cause AMS-TEX is compatible with Plain. • pk, for packed bitmap files.

• AFONT hpackagei is a TEX package name (examples: babel, source, for font sources (MET ﬁles, texdraw). property lists, etc.). TUGboat, Volume 16 (1995), No. 4 405

• tfm,forTEX font metric files. system is the assumption of a single target resolu- • type1, for Type 1 fonts (in any format). tion. • vf, for virtual fonts. Two naming strategies are commonly used to identify the resolution of bitmap font files. On sys- As usual, a site may omit any of these direc- tems that allow long filenames (and in the origi-

tories that are unnecessary (gf is a particularly

AFONT nal MET program itself), the resolution is likely candidate for omission). included in the filename (e.g., cmr10.300pk). On hsupplieri is a name identifying font source (exam- systems which do not support long filenames, fonts ples: adobe, ams, public). The TDS reserves are generally segregated into directories by resolu- the following hsupplieri names: tion (e.g., dpi300/cmr10.pk). • ams, for the American Mathematical Soci- Because the TDS cannot require long filenames, ety’s AMS-fonts collection. we must use the latter scheme for naming fonts. So • local, for local additions. See Section 2.3. we have two more subdirectory levels under pk and • public, for freely redistributable fonts gf: where the supplier neither (1) requested texmf/fonts/pk/ their own directory (e.g., ams), nor (2) also hmodei/hsupplieri/htypefacei/dpihnnni/ made proprietary fonts (e.g., adobe). It texmf/fonts/gf/ does not contain all extant freely dis- hmodei/hsupplieri/htypefacei/dpihnnni/ tributable fonts, nor are all files therein hmodei is a name which identifies the device type necessarily strictly public domain. (examples: cx, gsftopk, ljfour). Usually, this

•

AFONT tmp, for dynamically-generated fonts, as is isthenameoftheMET mode used to traditional on some systems. It may be build the PK file. For fonts rendered as bitmaps omitted if unnecessary, as usual. by a program that does not distinguish between h i htypefacei is the name of a typeface family (exam- different output devices, the mode name shall ples: cm, euler, times). The TDS reserves the be that of the program (e.g., ps2pk, gsftopk). following htypefacei names: dpihnnni specifies the resolution of the font (exam- • cm (within public), for the 75 fonts de- ples: dpi300, dpi329). ‘dpi’ stands for dots fined in Computers and Typesetting, Vol- per inch, i.e., pixels per inch. We recognize that ume E. pixels per millimeter is used in many parts of the world, but dpi is too traditional in the T X • latex (within public), for those fonts dis- E world to consider changing now. tributed with LAT X in the base distribu- E h i

tion. The integer nnn is to be calculated as if us-

AFONT ing MET arithmetic and then rounded;

• local, for local additions. See Section 2.3.

AFONT i.e., it is the integer MET uses in its out- Some concrete examples: put gf filename. We recognize small differences texmf/fonts/source/public/pandora/pnr10.mf in the resolution are a common cause of frus- texmf/fonts/tfm/public/cm/cmr10.tfm tration among users, however, and recommend texmf/fonts/type1/adobe/utopia/putr.pfa implementors follow the level 0 DVI driver stan- For complete supplier and typeface name lists, dard (see Appendix D) in bitmap font searches by allowing a fuzz of 0.2% (with a minimum consult Filenames for TEX fonts (see Appendix D). of 1) in the hdpii. 3.2.1 Font bitmaps Implementations may provide extensions to the Font bitmap files require two characteristics in addi- basic naming scheme, such as long filenames and tion to the above to be uniquely identifiable: (1) the font library files, provided that the basic scheme is type of device (i.e., mode) for which the font was also supported. created; (2) the resolution of the bitmap. Following common practice, the TDS segregates 3.2.2 Valid font bitmaps fonts with different device types into separate di- The TWG recognizes that the use of short filenames rectories. See modes.mf in Appendix D for recom- has many disadvantages. The most vexing is that mended mode names. it results in the creation of dozens of different files Some printers operate at more than one resolu- with the same name. At a typical site, cmr10.pk will tion (e.g., at 300 dpi and 600 dpi), but each such res- be the filename for Computer Modern Roman 10 pt olution will necessarily have a different mode name. at 5–10 magnifications for 2–3 modes. (Section 2.4 Nothing further is needed, since implicit in the TEX discusses duplicate filenames in general.) 406 TUGboat, Volume 16 (1995), No. 4

To minimize this problem, we strongly recom- • support, for additional input ﬁles required by AP OST mend that PK ﬁles contain enough information to MET utility programs, including a font

identify precisely how they were created: at least map, a character adjustment table, and a sub- AP OST the mode, base resolution, and magniﬁcation used directory containing low-level MET pro- to create the font. grams for rendering some special characters. This information is easy to supply: a simple ad-

dition to the local modes used for building the fonts 3.5 BibTEX

AFONT with MET will automatically provide the re- BibTEX-related files shall be stored in: quired information. If you have been using a local texmf/bibtex/bib/hpackagei/ modes file derived from (or that is simply) modes.mf texmf/bibtex/bst/hpackagei/ (see Appendix D), the required information is al- The bib directory is for BibT X database (.bib) ready in your PK files. If not, a simple addition based E files, the bst directory for style (.bst)files. on the code found in modes.mf canbemadetoyour hpackagei is the name of a BibT X package. local modes file and the PK files rebuilt. E

The TDS reserves the following hpackagei names

AFONT 3.3 Non-font MET ﬁles (the same names are reserved under both bib and

bst):

AFONT Most MET input files are font programs or parts of font programs and are thus covered by the • base, for the standard BibTEX databases and previous section. However, a few non-font input files styles, such as xampl.bib, plain.bst. do exist. Such files shall be stored in: • local, for local additions. See Section 2.3. texmf/metafont/hpackagei/ • misc,forBibTEX packages consisting of only a

single ﬁle.

AFONT hpackagei is the name of a MET package (for example, mfpic). 3.6 Documentation The TDS reserves the following hpackagei names:

Most packages come with some form of documen-

AFONT • base, for the standard MET macro ﬁles

tation: user manuals, example ﬁles, programming

AFONT as described in The MET book,suchas plain.mf and expr.mf. guides, etc. In addition, many independent ﬁles not part of any macro or other package describe various • local, for local additions. See Section 2.3. aspects of the T X system.

• E AFONT misc,forMET packages consisting of The TDS specifies that these additional docu- only a single file (for example, modes.mf). mentation files shall be stored in a structure that

parallels to some extent the fonts and tex directo- AP OST 3.4 MET

ries, as follows: AP OST MET is a picture-drawing language developed

texmf/doc/hcategoryi/...

AFONT by John Hobby, derived from Knuth’s MET . Its primary purpose is to output Encapsulated Post- hcategoryi identiﬁes the general topic of docu-

Script instead of bitmaps. mentation that resides below it; for example, a TEX AP OST

MET input ﬁles and the support ﬁles for format name (latex), program name (bibtex, tex), AP OST MET -related utilities shall be stored in: or other system components (web, fonts). texmf/metapost/hpackagei/ The TDS reserves the following categories:

• Within each hcategoryi treeforaTEX format, AP OST hpackagei isthenameofa MET package. At the present writing none exist, but the TWG thought the directory base is reserved for base docu- it prudent to leave room for contributed packages mentation distributed by the format’s main- that might be written in the future. tainers. The TDS reserves the following hpackagei names: • general, for standalone documents not spe-

cific to any particular program (for example, AP OST • base, for the standard MET macro files, Joachim Schrod’s Components of T X ). such as plain.mp, mfplain.mp, boxes.mp,and E • graph.mp. This includes files used by INIMP help, for meta-information, such as FAQ’s, when dumping mem files containing preloaded David Jones’ macro index, etc. macro definitions. • html,forHTML documents. • local, for local additions. See Section 2.3. • info, for processed Texinfo documents. (Info

ﬁles, like anything else, may also be stored out- AP OST • misc,forMET packages consisting of only a single ﬁle. side the TDS, at the installer’s option.) • local, for local additions. See Section 2.3. TUGboat, Volume 16 (1995), No. 4 407

bibtex/ BibTEX input files bib/ BibTEX databases base/ base distribution (e.g., xampl.bib) misc/ single-file databases hpackagei/ name of a package bst/ BibTEXstylefiles base/ base distribution (e.g., plain.bst, acm.bst) misc/ single-file styles hpackagei/ name of a package doc/ see Section 3.6 and the summary below fonts/ font-related files htypei/ file type (e.g., pk) hmodei/ type of output device (for pk and gf only) hsupplieri/ name of a font supplier (e.g., public) htypefacei/ name of a typeface (e.g., cm) dpihnnni/ font resolution (for pk and gf only)

himplementationi/ TEX implementations, by name (e.g., emtex)

AFONT metafont/ MET (non-font) input ﬁles base/ base distribution (e.g., plain.mf) misc/ single-ﬁle packages (e.g., modes.mf)

hpackagei/ name of a package (e.g., mfpic) AP OST metapost/ MET input and support ﬁles base/ base distribution (e.g., plain.mp) misc/ single-ﬁle packages

hpackagei/ name of a package AP OST support/ support files for MET -related utilities mft/ MFT inputs (e.g., plain.mft) hprogrami/ TEX-related programs, by name (e.g., dvips) source/ program source code by name (e.g., latex, web2c) tex/ TEX input files hformati/ name of a format (e.g., plain) base/ base distribution for format (e.g., plain.tex) misc/ single-file packages (e.g., webmac.tex) local/ local additions to or local configuration files for hformati hpackagei/ name of a package (e.g., graphics, mfnfss) generic/ format-independent packages hyphen/ hyphenation patterns (e.g., hyphen.tex) images/ image input files (e.g., Encapsulated PostScript) misc/ single-file format-independent packages (e.g., null.tex). hpackagei/ name of a package (e.g., babel)

Table 1: A skeleton of a TDS texmf directory tree

The doc directory is intended for implementation- A Unspecified pieces independent and operating system-independent doc- The TDS cannot address the following aspects of a umentation files. Implementation-dependent files functioning TEX system: shall be stored elsewhere, as provided for by the implementation and/or TEX administrator (for example, VMS help files under texmf/vms/help). 1. The location of executable programs: this is too The documentation directories may contain site-dependent even to recommend a location, TEX sources, DVI files, PostScript files, text files, ex- let alone require one. A site may place exe- ample input files, or any other useful documentation cutables outside the texmf tree altogether (e.g., format(s). See Table 2 for a summary. /usr/local/bin), in a platform-dependent directory within texmf, or elsewhere. 408 TUGboat, Volume 16 (1995), No. 4

ams/ amsfonts/ amsfonts.faq, amfndoc amslatex/ amslatex.faq, amsldoc amstex/ amsguide, joyerr bibtex/ BibTEX base/ btxdoc.tex fonts/ fontname/ Filenames for TEX fonts oldgerm/ corkpapr hformati/ name of a TEX format (e.g., generic, latex) base/ for the base distribution misc/ for contributed single-file package documentation hpackagei/ for package general/ across programs, generalities errata/ errata, errata[1-8] texcomp/ Components of TEX generic/ for non-format-specific TEX packages babel/ german/ germdoc help/ meta-information ctan/ info about CTAN mirror sites faq/ FAQsofcomp.text.tex,etc. html/ HTML files info/ GNU Info files, made from Texinfo sources latex/ example of hformati base/ ltnews*, *guide,etc. graphics/ grfguide hprogrami/ TEX-related programs, by name (examples follow) metafont/ mfbook.tex, metafont-for-beginners,etc. metapost/ mpman, manfig,etc. tex/ texbook.tex, A Gentle Introduction to TEX,etc. web/ webman, cwebman

Table 2: A skeleton of a TDS directory tree under texmf/doc

2. Upgrading packages when new releases are made: TEX distribution or installation, however, we outline we could find no way of introducing version here the necessary restrictions. The TDS specifica- specifiers into texmf that would do more good tions themselves are compatible with these. than harm, or that would be practical for even ISO-9660 is the only universally acceptable file a plurality of installations. system format for CD-ROMs. A subset thereof meets the stringent limitations of all operating systems in 3. The location of implementation-specific files use today. It specifies the following: (e.g., TEX .fmt files): by their nature, these • must be left to the implementor or TEXmain- File and directory names, not including any di- tainer. See Section B.3. rectory path or extension part, may not exceed eight characters. 4. Precisely when a package or file should be con- • sidered “local”, and where such local files are Filenames may have a single extension. Exten- installed. See Section 2.3 for more discussion. sions may not exceed three characters. Direc- tory names may not have an extension. A.1 Portable filenames • Names and extensions may consist of only the The TDS cannot require any particular restriction on characters A–Z, 0–9, and underscore. Lowercase filenames in the tree, since the names of many exist- letters are excluded. (The only common place ing TEX files conform to no particular scheme. For where mixed-case names occur in the TEX sys- the benefit of people who wish to make a portable tem is in LATEX font descriptor files, and LATEX TUGboat, Volume 16 (1995), No. 4 409

does not rely on case alone to distinguish among parallel to existing production directories. This test- these files.) ing will likely flush out problems that were not obvi- • A period separates the filename from the exten- ous in the confined settings of the developers’ sites; sion and is always present, even if the name or for example, it should help to resolve OS and pack- extension is missing (e.g., FILENAME. or .EXT). age dependencies, package interdependencies, and • A version number, ranging from 1–32767, is other details not addressed by this TDS version. appended to the file extension, separated by a After most of the dust has settled, hopefully semicolon (e.g., FILENAME.EXT;1). even conservative TEX administrators will begin to • Only eight directory levels are allowed, includ- adopt the TDS.Eventually,mostTEX sites will have ing the top-level (mounted) directory (see Sec- adopted the common structure, and most packages tion 2.2). Thus, the deepest valid ISO-9660 will be readily available in TDS-compliant form. path is: We believe that this process will occur relatively texmf/L2/L3/L4/L5/L6/L7/L8/FOO.BAR;1 quickly. The TDS committee spans a wide range of 1 2345678 interests in the TEX community. Consequently, we believe that most of the key issues involved in defin- The deepest TDS path needs only seven levels: ing a workable TDS definition have been covered, texmf/fonts/pk/cx/public/cm/dpi300/cmr10.pk often in detail. TEX developers have been consulted 1 2 345 67 about implementation issues, and have been trying Some systems display a modified format of ISO- out the TDS arrangement. Thus, we hope for few 9660 names, mapping alphabetic characters to low- surprises as implementations mature. ercase, removing version numbers and trailing peri- Finally, there are several (current or prospec- ods, etc. tive) publishers of TEX CD-ROMs. These publishers are highly motivated to work out details of TDS B Implementation issues implementation, and their products will provide in- We believe that the TDS can bring a great deal of expensive and convenient ways for experimentally- order to the current anarchic state of many TEX minded TEX administrators to experiment with the installations. In addition, by providing a common TDS. frame of reference, it will ease the burden of docu- Efforts are under way to set up a “TDS Reg- menting administrative tasks. Finally, it is a neces- istry” that will coordinate assignment of TDS-com- sary part of any reasonable system of true “drop-in” pliant directory names and provide a definitive distribution packages for TEX. database of TDS-compliant software distributions. (Perhaps this could also serve many sites as the def- B.1 Adoption of the TDS inition of when a package is local.) For now, dis- We recognize that adoption of TDS will not be im- tribution through CTAN serves as an imprecise reg- mediate or universal. Most TEX administrators will istry. not be inclined to make the switch until: • Clear and demonstrable benefits can be shown B.2 More on subdirectory searching for the TDS. Recursive subdirectory searching is the ability to • TDS-compliant versions of all key programs are specify a search not only of a specified directory hdi, available in ported, well-tested forms. but recursively of all directories below hdi. • A “settling” period has taken place, to flush out Since the TDS specifies precise locations for problems. The public release of this document most files, with no extra levels of subdirectories al- is the first step in this process. lowed, true recursive searching is not actually re- Consequently, most of the first trials of the TDS quired for a TDS-compliant implementation. We do, will be made by members of the TDS committee however, strongly recommend recursive searching as and/or developers of TEX-related software. Indeed, the most user-friendly and natural approach to the some of this has taken place during the course of problem, rather than convoluted methods to specify our deliberations (see Appendix D for a sample tree paths without recursion. available electronically). They will certainly result This feature is already supported by many im- in the production of a substantial number of TDS- plementations of TEX and companion utilities, for compliant packages. example DECUS TEXforVMS, Dvips(k), emTEX Once installable forms of key TDS-compliant (and its drivers), PubliC TEX, Web2c, Xdvi(k),and packages are more widespread, some TEX adminis- Y&YTEX. trators will set up TDS-compliant trees, possibly in 410 TUGboat, Volume 16 (1995), No. 4

Even if your TEX implementation does not directory name will be modified to something more rectly support subdirectory searching, you may find specific (e.g., vms_decus). Table 3 shows the VMS it useful to adopt the structure if you do not use directory structure. many fonts or packages. For instance, if you only use Computer Modern and AMS fonts, it would be B.3.2 Web2c 7.0 feasible to store them in the TDS layout and list All implementation-dependent TEX system files (in- the directories individually in configuration files or cluding .pool, .fmt, .base,and.mem files) are environment variables. stored by default directly in texmf/web2c.The The TWG recognizes that subdirectory search- configuration file texmf.cnf and various subsidiary ing places an extra burden on the system and may MakeTeX... scripts used as subroutines are also be the source of performance bottlenecks, partic- stored there. ularly on slower machines. Nevertheless, we feel Non-TEX specific files are stored following the that subdirectory searching is imperative for a well- GNU coding standards. Given a root directory organized TDS, for the reasons stated in Section 2.1. hprefix i (/usr/local by default), we have default Implementors are encouraged to provide enhance- locations as follows as shown in Table 4. ments to the basic principle of subdirectory search- See prep.ai.mit.edu:/pub/gnu/standards. ing to avoid performance problems, e.g., the use of * for the rationale behind and descriptions of this a filename cache (this can be as simple as a re- arrangement. A site may of course override these cursive directory listing) that is consulted before defaults; for example, it may put everything under disk searching begins. If a match is found in the a single directory such as /usr/local/texmf. database, subdirectory searching is not required, and performance is thus independent of the num- C Is there a better way? ber of subdirectories present on the system. Defining the TDS required many compromises. Both Different implementations specify subdirectory the overall structure and the details of the individ- searching differently. In the interest of typographic ual directories were arrived at by finding common clarity, the examples here do not use the hreplaceablei ground among many opinions. The driving forces font. were feasibility (in terms of what could technically Dvips: via a separate TEXFONTS_SUBDIR environ- be done and what could reasonably be expected ment variable. from developers) and regularity (files grouped to- emTEX : t:\subdir!!; t:\subdir! for a single level gether in an arrangement that “made sense”). of searching. Some interesting ideas could not be applied due Kpathsea: texmf/subdir// to implementations lacking the necessary support: VMS: texmf:[subdir...] Xdvi: texmf/subdir/**; texmf/subdir/* forasin- • Path searching control at the TEX level. If doc- gle level of searching (patchlevel 20 of the pro- uments could restrict subdirectory searching to gram onwards). a subdirectory via some portable syntax in file Y&Y TEX : t:/subdir// or t:\subdir\\. names, restrictions on uniqueness of filenames B.3 Example implementation-specific trees could be relaxed considerably (with the cooper- ation of the formats), and the TEX search path The TDS cannot specify a precise location for would not need to depend on the format. implementation-specific files, but for informative purposes, we provide here the default locations for some implementations. Please contact us with additions or corrections. These paths are not defini- • Multiple logical texmf trees. For example, a tive, may not match anything at your site, and may site might have one (read-only) location for change without warning. stable files, and a different (writable) location We recommend all implementations have de- for dynamically-created fonts or other files. It fault search paths that start with the current direc- would be reasonable for two such trees to be tory (e.g., ‘.’). Allowing users to include the parent logically merged when searching. directory (e.g., ‘..’) is also helpful. C.1 Macro structure B.3.1 Public DECUS TEX The TWG settled on the hformati/hpackagei ar- If another VMS implementation besides Public DE- rangement after long discussion about how best to CUS TEX appears, the top level implementation di- arrange the files. TUGboat, Volume 16 (1995), No. 4 411 texmf/ vms/ VMS implementation specific files exe/ end-user commands common/ command procedures, command definition files, etc. axp/ binary executables for Alpha AXP vax/ binary executables for VAX formats/ pool files, formats, bases help/ VMS help library, and miscellaneous help sources mgr/ command procedures, programs, docs, etc., for system management

Table 3: The VMS directory structure hprefix i/ installation root (/usr/local by default) bin/ executables man/ man pages info/ info files lib/ libraries (libkpathsea.*) share/ texmf/ TDS root web2c/ implementation-dependent files (.pool, .fmt, texmf.cnf,etc.)

Table 4: The VMS directory structure

The primary alternative to this arrangement C.2.1 Font file type location was a scheme which reversed the order of these direc- We considered the supplier-first arrangement cur- h i h i tories: package / format . This reversed arrange- rently in use at many sites: ment has a strong appeal: it keeps all of the files related to a particular package in a single place. The fonts/hsupplieri/htypefacei/htypei/ arrangement actually adopted tends to spread files out into two or three places (macros, documenta- This improves the maintainability of the font tion, and fonts, for example, are spread into different tree, since all files comprising a given typeface are sections of the tree right at the top level). in one place, but unless all the programs that search this tree employ some form of caching, there are Nevertheless, the hformati/hpackagei structure won for a couple of reasons: serious performance concerns. For example, in order to find a TFM file, the simplest implementation would • It is closer to current practice; in fact, several require TEX to search through all the directories that members of the TWG have already implemented contain PK files in all modes and at all resolutions. the TDS hierarchy. The alternative is not in use In the end, a poll of developers revealed consid- at any known site, and the TWG felt it wrong erable resistance to implementing sufficient caching to mandate something with which there is no mechanisms, so this arrangement was abandoned. practical experience. The TDS arrangement allows the search tree to be • The alternative arrangement increases the num- restricted to the correct type of file, at least. Con- ber of top-level directories, so the files that cerns about efficiency remain, but there seems to be must be found using subdirectory searching are no more we can do without abandoning subdirectory spread out in a wide, shallow tree. This could searching entirely.

have a profound impact on the eﬃciency of sub- We also considered segregating all font-related

AFONT directory searching. files strictly by file type, so that MET sources wouldbeinadirectorytexmf/fonts/mf, prop- C.2 Font structure erty list files in texmf/fonts/pl, the various forms The TWG struggled more with the font directory of Type 1 fonts separated, and so on. Although structure than anything else. This is not surprising; more blindly consistent, we felt that the drawback the need to use the proliferation of PostScript fonts of more complicated path constructions outweighed with TEX is what made the previous arrangement this. The TDS merges file types (mf and pl under with all files in a single directory untenable, and source, pfa and pfb and gsf under type1)where therefore what initiated the TDS effort. beneficial. 412 TUGboat, Volume 16 (1995), No. 4

C.2.2 Mode and resolution location D Related references We considered having the mode at the bottom of the This appendix gives pointers to related files and font tree: other documents. In this document, hCTAN:i means the root of h i h i h i h i fonts/pk/ supplier / typeface / mode / dpi / an anonymous ftp CTAN tree. This is both a host In this case, however, it is difficult to limit sub- name and a directory name. For example: directory searching to the mode required for a par- ftp.dante.de:/tex-archive ticular device. ftp.shsu.edu:/tex-archive We then considered moving the dpihnnni up to ftp.tex.ac.uk:/tex-archive below the mode: Finger [email protected] foracompletelist of CTAN sites; there are mirrors worldwide. hmodei hdpii hsupplieri htypefacei fonts/pk/ / / / / Here are the references: But then it is not feasible to omit the dpihnnni • The TDS mailing list archives can be retrieved level altogether on systems which can and do choose via ftp from shsu.edu:[twg-tds] and to use long filenames. vms.rhbnc.ac.uk:/archives/twg.tds.*. • AsampleTDS tree: hCTAN:i . C.2.3 Modeless bitmaps tds • A collection of BibTEX databases and styles: The TDS specifies using utility names as mode ftp.math.utah.edu:/pub/tex/bib. names for those utilities which generate bitmaps, • e.g., texmf/fonts/pk/gsftopk/.Analternative Components of TEX by Joachim Schrod: h i was to introduce a single directory modeless/ below CTAN: documentation/components-of-TeX. which all such directories could be gathered. This • The level 0 DVI driver standard: has the considerable advantage of not requiring each hCTAN:idviware/driv-standard/level-0. such directory name to be listed in a search path. • Filenames for TEX fonts: But it has disadvantages, too: it would use the hCTAN:idocumentation/fontname. last available directory level, preventing any future This distribution includes recommended sup- expansions; and it would put PK files at different plier and typeface names. depths in the tree, possibly hindering search strate- • ISO-9660 CD-ROM file system standard: gies and certainly a likely source of confusion. We http://www.iso.ch/cate/cat.html.

decided to stay with existing practice and keep the

AFONT • A complete set of MET modes: utility name at the same level as the mode names. h i We are making an implicit assumption that CTAN: fonts/modes/modes.mf.

This ﬁle includes recommended mode names.

AFONT MET is the only program producing mode- dependent bitmaps. If this becomes false we could E Contributors add an abbreviation for the program to mode names, The TWG had no formal meetings; electronic mail as in mfcx vs. xyzcx for a hypothetical program Xyz, or we could at that time add an additional program was the primary communication medium. Sebastian Rahtz is the T X Users Group Tech- name level uniformly to the tree. For our present E nical Council liaison. Norman Walsh is the commit- purposes, it seems more important to concisely rep- resent the current situation than to take account of tee chair. For version 0.999 of the draft, Karl Berry took over as editor and coordinated this release. hypothetical possibilities that may never be realized. Original contributors: C.3 Documentation structure Barbara Beeton Karl Berry We considered placing additional documentation Vicki Brown David Carlisle files in the same directory as the source files for the Thomas Esser Alan Jeffrey packages, but we felt that users should be able to Jörg Knappen Pierre MacKay find documentation separately from sources, since Rich Morin Sebastian Rahtz most users have no interest in sources. Joachim Schrod Christian Spieler We hope that a separate, but parallel, structure Elizabeth Tachikawa Philip Taylor for documentation would (1) keep the documenta- Ulrik Vieth Paul Vojta tion together and (2) make it as straightforward as Norman Walsh possible for users to find the particular documentation they were after. TUGboat, Volume 16 (1995), No. 4 413

Additional contributors: David Aspinall Nelson Beebe Harriet Borton Bart Childs Damian Cugley Alan Dunwell Michael Ferguson Erik Frambach Bernard Gaulle Jeﬀrey Gealow George Greenwade Thomas Herter Berthold Horn Charles Karney David Kastrup David Kellerman Wonkoo Kim Richard Kinch Robin Kirkham Alex Kok Eberhard Mattes Bob Morris Lenny Muellner Oren Patashnik David Rhead Mark Sinke Andrew Trevorrow Doug Waud Chee-Wai Yeung