summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/tds/tds.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/tds/tds.tex')
-rw-r--r--Master/texmf-dist/doc/generic/tds/tds.tex1585
1 files changed, 1585 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/tds/tds.tex b/Master/texmf-dist/doc/generic/tds/tds.tex
new file mode 100644
index 00000000000..55c1b4ddcc3
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/tds/tds.tex
@@ -0,0 +1,1585 @@
+%&latex
+% $Id: tds.tex,v 1.43 2004/06/23 17:24:42 karl Exp $
+\NeedsTeXFormat{LaTeX2e} % compatibility with 2.09 is too painful
+\documentclass{tdsguide}
+
+\tdsVersion{1.1}
+
+\title{A Directory Structure for \TeX{} Files}
+\author{TUG Working Group on a \TeX{} Directory Structure (TWG-TDS)}
+
+\begin{document}
+
+\maketitle
+
+\begin{legalnotice}
+
+Copyright {\copyright} 1994, 1995, 1996, 1997, 1998, 1999, 2003, 2004
+\TeX{} Users Group.
+
+Permission to use, copy, and distribute this document \emphasis{without
+modification} for any purpose and without fee is hereby granted,
+provided that this notice appears in all copies. It is provided ``as
+is'' without expressed or implied warranty.
+
+Permission is granted to copy and distribute modified versions of this
+document under the conditions for verbatim copying, provided that the
+modifications are clearly marked and the document is not represented as
+the official one.
+
+This document is available on any \abbr{ctan} host
+(see Appendix~\ref{sec:Related references}).
+Please send questions or suggestions by email to
+\email|tds@tug.org|. We welcome all comments. This is version
+\the\tdsVersion.
+
+\end{legalnotice}
+
+
+\tableofcontents
+
+
+\newpage
+\section{Introduction}
+
+\TeX{} is a powerful, flexible typesetting system used by many people
+around the world. It is extremely 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 (\abbr{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 \TeX{} files into a single structure. The
+\abbr{TDS} has been designed to work on all modern systems. In
+particular, the Technical Working Group (\abbr{TWG}) believes it is usable
+under Mac\abbr{OS}, \abbr{ms-dos}, \abbr{os/2}, Unix, \abbr{vms}, and
+Windows \abbr{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 preparing \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~\ref{sec:Related references}.
+
+
+\subsection{History}
+
+Version 1.0 of the \abbr{TDS} was released in February 2003.
+
+Version 1.1 was released in June 2004, with the following non-editorial
+changes:
+
+\begin{itemize-squeeze}
+\item Inputs for \TeX{} extensions included under \path|tex|, instead
+ of in their own top-level directories (Section~\ref{sec:Extensions})
+\item New top-level directory \path|scripts| (Section~\ref{sec:Scripts}).
+\item New subdirectories \path|lig|, \path|opentype|,
+ \path|truetype|, and \path|type3| under \path|fonts|
+ (Section~\ref{sec:Fonts}).
+\item \path|enc|, \path|lig|, and \path|map| all use
+ \replaceable{syntax}\path|/|\replaceable{package} subdirectories
+ (Section~\ref{sec:Fonts}).
+\item \path|pfm| files specified to go under \path|type1|, and
+ \path|inf| files under \path|afm| (Section~\ref{sec:Fonts}).
+\end{itemize-squeeze}
+
+
+\subsection{The role of the \abbr{TDS}}
+
+The role of the \abbr{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 Comprehensive \TeX{} Archive
+Network (\abbr{ctan}) fulfills at least part of this role, but this is
+not the case. The role of \abbr{ctan} is to simplify archiving and
+distribution, not installation and use.
+
+In fact, the roles of the \abbr{TDS} and \abbr{ctan} are frequently in
+conflict, as we will see. 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.
+
+
+\subsection{Conventions}
+
+In this document, ``\path|/|'' is used to separate filename components;
+for example, \path|texmf/fonts|. This is the Unix convention but the
+ideas are in no way Unix-specific.
+
+In this document, ``\TeX{}'' generally means the \TeX{} system, including
+\MF{}, \abbr{DVI} drivers, utilities, etc., not just the \TeX{}
+program itself.
+
+The word ``package'' in this document has its usual meaning: a set of
+related files distributed, installed, and maintained as a unit. This is
+\emphasis{not} a \LaTeXe{} package, which is a style file supplementing
+a document class.
+
+We use the following typographic conventions:
+
+\begin{description}
+
+\item[\literal{literal}] Literal text such as \literal{filename} is
+typeset in typewriter type.
+
+\item[\replaceable{replaceable}] Replaceable text such as
+\replaceable{package}, identifying a class of things, is typeset in
+italics inside angle brackets.
+
+\end{description}
+
+
+\section{General}
+
+This section describes common properties throughout the \abbr{TDS} tree.
+
+\subsection{Subdirectory searching}
+\label{sec:Subdirectory searching}
+
+Older \TeX{} installations store large numbers of related files in single
+directories, for example, all \path|TFM| files and\slash 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 \abbr{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 \abbr{TWG} concluded that a comprehensive \abbr{TDS}
+requires implementations to support some form of implicit subdirectory
+searching. More precisely, implementations must make it possible to
+specify that \TeX{}, \MF{}, 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 \abbr{TDS} does not specify a syntax for specifying recursive
+searching, but we encourage implementors to provide interoperability
+(see Section~\ref{sec:More on subdirectory searching}).
+
+
+\subsection{Rooting the tree}
+\label{sec:Rooting the tree}
+
+In this document, we shall designate the root \abbr{TDS} directory by
+`\texmf{}' (for ``\TeX{} and \MF{}''). We recommend using that name
+where possible, but the actual name of the directory is up to the
+installer. On \abbr{pc} networks, for example, this could map to a
+logical drive specification such as \path|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, \path|/usr/local/share|, \path|/usr/local|,
+\path|/usr/local/lib|, and \path|/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 \MF{}, \MP{}, \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 \abbr{TDS} hierarchy installed
+(for example, when installing an upgrade). This is perfectly legitimate.
+
+
+\subsection{Local additions}
+\label{sec:Local additions}
+
+The \abbr{TDS} cannot specify precisely when a package is or is not a
+``local addition''. Each site must determine this according to its own
+conventions. At the two extremes, one site might wish to consider
+``nonlocal'' all files 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 employ
+both simultaneously:
+
+\begin{enumerate}
+
+\item A completely separate tree which is a \abbr{TDS} structure
+itself; for example, \path|/usr/local/umbtex| at the University of
+Massachusetts at Boston. This is another example of the multiple
+\texmf{} hierarchies mentioned in the previous section.
+
+\item A directory named `\path|local|' at any appropriate level, for
+example, in the \replaceable{format}, \replaceable{package}, and
+\replaceable{supplier} directories discussed in the following sections.
+The \abbr{TDS} reserves the directory name \path|local| for this
+purpose.
+
+We recommend using \path|local| for site-adapted configuration files,
+such as \path|language.dat| for the Babel package or \path|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.
+
+\end{enumerate}
+
+One common case of local additions is dynamically generated files, e.g.,
+\abbr{PK} fonts by the \path|mktexpk| script (which originated in
+\application{Dvips} as \path|MakeTeXPK|). A site may store the
+generated files directly in any of:
+\begin{itemize-squeeze}
+\item their standard location in the main \abbr{TDS} tree (if it can be
+made globally writable);
+
+\item an alternative location in the main \abbr{TDS} tree (for
+example, under \path|texmf/fonts/tmp|);
+
+\item a second complete \abbr{TDS} tree (as outlined above);
+
+\item any other convenient directory (perhaps under
+\path|/var|, for example \path|/var/spool/fonts|).
+
+\end{itemize-squeeze}
+
+No one solution will be appropriate for all sites.
+
+
+\subsection{Duplicate filenames}
+\label{sec:Duplicate filenames}
+
+Different files by the same name may exist in a \abbr{TDS} tree. The
+\abbr{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 \abbr{TDS} requires implementations to support the following
+exceptions:
+
+\begin{itemize}
+
+\item Names of \TeX{} input files must be unique within each first-level
+subdirectory of \path|texmf/tex| and \path|texmf/tex/generic|, but not
+within all of \path|texmf/tex|; i.e., different \TeX{} formats may have
+files by the same name. (Section~\ref{sec:Macros} discusses this
+further.) Thus, no single format-independent path specification, such
+as a recursive search beginning at \path|texmf/tex| specifying no other
+directories, suffices. So implementations must provide format-dependent
+path specifications, for example via wrapper scripts or configuration
+files.
+
+\item Many font files will have the same name (e.g., \path|cmr10.pk|),
+as discussed in Section~\ref{sec:Valid font bitmaps}. Implementations
+must distinguish these files by mode and resolution.
+
+\end{itemize}
+
+All implementations we know of already have these capabilities.
+
+One place where duplicate names are likely to occur is not an exception:
+
+\begin{itemize}
+
+\item Names of \MF{} input files (as opposed to bitmaps) must be unique
+within all of \path|texmf/fonts|. In practice, this is a problem with
+some variants of Computer Modern which contain slightly modified files
+named \path|punct.mf|, \path|romanl.mf|, and so on. We believe the only
+feasible solution is to rename the derivative files to be
+unique.
+
+\end{itemize}
+
+
+\section{Top-level directories}
+\label{sec:Top-level directories}
+
+The directories under the \texmf{} root identify the major components of
+a \TeX{} system (see Section~\ref{sec:Summary} for a summary). A site
+may omit any unneeded directories.
+
+Although the \abbr{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 \abbr{TDS} are:
+
+\begin{description}
+\item[\path|tex|]
+for \TeX{} files (Section~\ref{sec:Macros}).
+
+\item[\path|fonts|]
+for font-related files (Section~\ref{sec:Fonts}).
+
+\item[\path|metafont|]
+for \MF{} files which are not fonts (Section~\ref{sec:Non-font MF files}).
+
+\item[\path|metapost|]
+for \MP{} files (Section~\ref{sec:MetaPost}).
+
+\item[\path|bibtex|]
+for \BibTeX{} files (Section~\ref{sec:BibTeX}).
+
+\item[\path|scripts|]
+for platform-independent executables (Section~\ref{sec:Scripts}).
+
+\item[\path|doc|]
+for user documentation (Section~\ref{sec:Documentation}).
+
+\item[\path|source|] for sources. This includes both traditional
+program sources (for example, \application{Web2C} sources go in
+\path|texmf/source/web2c|) and, e.g., \LaTeX{} \path|dtx| sources (which
+go in \path|texmf/source/latex|). The \abbr{TDS} leaves unspecified any
+structure under \path|source|.
+
+\path|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, \path|plain.tex| does not belong under \path|texmf/source|,
+even though it is a ``source file'' in the sense of not being derived
+from another file. (It goes in \path|texmf/tex/plain/base|, as explained
+in Section~\ref{sec:Macros}).
+
+\item[\replaceable{implementation}] for implementations (examples:
+\path|emtex|, \path|vtex|, \path|web2c|), to be used for whatever
+purpose deemed suitable by the implementor or \TeX{} administrator.
+That is, files that cannot be shared between implementations, such as
+pool files (\path|tex.pool|) and memory dump files (\path|plain.fmt|) go
+here, in addition to implementation-wide configuration files. See
+Section~\ref{sec:Example implementation-specific trees} for examples of
+real \replaceable{implementation} trees.
+
+Such implementation-specific configuration files should \emphasis{not}
+be located using the main \TeX{} input search path (e.g.,
+\path|TEXINPUTS|). This must be reserved for files actually read by a
+\TeX{} engine. See Section~\ref{sec:Extensions}.
+
+\item[\replaceable{program}] for program-specific input and
+configuration files for any \TeX{}-related programs (examples:
+\path|mft|, \path|dvips|). In fact, the \path|tex|, \path|metafont|,
+\path|metapost|, and \path|bibtex| items above may all be seen as
+instances of this case.
+
+\end{description}
+
+
+\subsection{Macros}
+\label{sec: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 \path|\dump|-able package):
+\begin{ttdisplay}
+texmf/tex/\replaceable{format}/\replaceable{package}/
+\end{ttdisplay}
+
+\begin{description}
+
+\item[\replaceable{format}] is a format name (examples: \path|amstex|,
+\path|latex|, \path|plain|, \path|texinfo|).
+
+The \abbr{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
+\replaceable{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 \abbr{TDS} reserves the following \replaceable{format} names:
+
+\begin{itemize}
+
+\item \path|generic|, for input files that are useful across a wide
+range of formats (examples: \path|null.tex|, \path|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
+\path|texmf/tex/plain|), e.g., \path|testfont.tex| and \path|plain.tex|
+itself.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local
+additions}.
+
+\end{itemize}
+
+Thus, for almost every format, it is necessary to search at least the
+\replaceable{format} directory and then the \path|generic| directory (in
+that order). Other directories may need to be searched as well,
+depending on the format. When using \AMSTeX{}, for example, the
+\path|amstex|, \path|plain|, and \path|generic| directories should be
+searched, because \AMSTeX{} is compatible with Plain.
+
+\item[\replaceable{package}] is a \TeX{} package name (examples:
+\path|babel|, \path|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
+\replaceable{format} directory, instead of
+\replaceable{format}\path|/base|. For example, Texinfo may go in
+\path|texmf/tex/texinfo/texinfo.tex|, not
+\path|texmf/tex/texinfo/base/texinfo.tex|.
+
+The \abbr{TDS} reserves the following \replaceable{package} names:
+
+\begin{itemize}
+
+\item \path|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 \path|ltx| files
+created during the build process. Another example: the \path|.ini|
+driver files for formats used by \TeX{} Live and other distributions.
+
+\item \path|hyphen|, for hyphenation patterns, including the original
+American English \path|hyphen.tex|. These are typically used only by
+\iniTeX{}. In most situations, this directory need exist only under the
+\literal{generic} format.
+
+\item \path|images|, for image input files, such as Encapsulated
+PostScript figures. Although it is somewhat non-intuitive for these to
+be under a directory named ``\path|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
+\abbr{TDS}\@. In most situations, this directory need exist only under
+the \literal{generic} format.
+
+\item \path|local|, for local additions and configuration files. See
+Section~\ref{sec:Local additions}.
+
+\item \path|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 \path|misc|.
+
+\end{itemize}
+
+\end{description}
+
+
+\subsubsection{Extensions}
+\label{sec:Extensions}
+
+\TeX{} has spawned many companion and successor programs (``engines''),
+such as \abbr{PDF}\TeX{}, Omega, and others. The \abbr{TDS} specifies
+that the input files for such programs (using a \TeX{}-like syntax) be
+placed within the top-level \path|tex| directory, either at the top
+level or within a format subdirectory, even though the original \TeX{}
+program may not be able to read them. For example:
+
+\begin{ttdisplay}
+texmf/tex/aleph
+texmf/tex/enctex
+\end{ttdisplay}
+
+This is a change from \abbr{TDS}~1.0, which specified top-level
+\replaceable{extension} directories for each such program. We felt the
+new approach is preferable, because:
+
+\begin{itemize}
+
+\item Authors of relevant packages typically make their code detect the
+engine being used, and issue error messages or adapt to circumstances
+appropriately. Furthermore, as a package matures, it may support
+multiple engines. Thus, a package could conceivably be placed in any of
+several top-level directories, at different times. Putting all packages
+under the top-level \path|tex| directory provides a stable location over
+time.
+
+\item Users need to be able to switch between engines, and configuring
+different search paths for each engine is difficult and error-prone.
+
+\end{itemize}
+
+Thus, in practice, having different top-level directories caused
+difficulties for everyone involved---users, package authors, site
+administrators, and system distributors.
+
+Please contrast this approach with the \replaceable{implementation}
+top-level subdirectory (Section~\ref{sec:Top-level directories}), which
+is to be used for configuration files that (presumably) do not use
+\TeX{} syntax and in any case should not be found along the main \TeX{}
+input search path.
+
+
+\subsection{Fonts}
+\label{sec:Fonts}
+
+Font files are stored in separate directories, segregated by file type,
+and then (in most cases) font supplier and typeface. \abbr{PK} and
+\abbr{GF} files need additional structure, as detailed in the next
+section.
+
+\begin{ttdisplay}
+texmf/fonts/\replaceable{type}/\replaceable{supplier}/\replaceable{typeface}/
+texmf/fonts/enc,lig,map/\replaceable{subpath}/
+\end{ttdisplay}
+
+\begin{description}
+
+\item[\replaceable{type}] is the type of font file. The \abbr{TDS}
+reserves the following \replaceable{type} names for common \TeX{} file
+types:
+
+\begin{itemize-squeeze}
+\item \path|afm|, for Adobe font metrics, and \path|inf| files.
+\item \path|gf|, for generic font bitmap files.
+\item \path|opentype|, for OpenType fonts.
+\item \path|pk|, for packed bitmap files.
+\item \path|source|, for font sources (\MF{} files, property lists, etc.).
+\item \path|tfm|, for \TeX{} font metric files.
+\item \path|truetype|, for TrueType fonts.
+\item \path|type1|, for PostScript Type 1 fonts (in \path|pfa|,
+ \path|pfb|, or any other format), and \path|pfm| files.
+\item \path|type3|, for PostScript Type 3 fonts.
+\item \path|vf|, for virtual fonts.
+\end{itemize-squeeze}
+
+The \abbr{TDS} also reserves the names \path|enc|, \path|lig|, and
+\path|map| for font encoding, ligature, and mapping files, respectively.
+All of these directories are structured the same way, with
+\replaceable{syntax} subdirectories, and then \replaceable{package}
+subsubdirectories. Each of these file types is intended to be searched
+along its own recursively-searched path. The names of the actual files
+must be unique within their subtree, as usual. Examples:
+\begin{ttdisplay}
+fonts/map/dvipdfm/updmap/dvipdfm.map
+fonts/map/dvips/lm/lm.map
+fonts/enc/dvips/base/8r.enc
+\end{ttdisplay}
+
+The Fontname and Dvips packages have more examples of the \path|enc| and
+\path|map| types. The \path|afm2pl| program uses \path|lig| files.
+
+\path|pfm| files are included in the \path|type1| directory, instead of
+being given their own directory, for two reasons: 1)~a \path|.pfm| file
+is always an adjunct to a given \path|.pfb| file; 2)~they must be
+installed from the same directory for Windows programs other than \TeX{}
+to use them.
+
+\path|inf| files are included in the \path|afm| directory, since
+an \path|inf| and \path|afm| file can be used to generate a \path|pfm|.
+(Unfortunately, Adobe Type Manager and perhaps other software requires
+that the \path|pfb| be in the same directory as \path|afm| and
+\path|inf| for installation.)
+
+As usual, a site may omit any of these directories that are unnecessary.
+\path|gf| is a particularly likely candidate for omission.
+
+\item[\replaceable{supplier}] is a name identifying font source
+(examples: \path|adobe|, \path|ams|, \path|public|). The \abbr{TDS}
+reserves the following \replaceable{supplier} names:
+
+\begin{itemize}
+
+\item \path|ams|, for the American Mathematical Society's \AmS{}-fonts
+collection.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local additions}.
+
+\item \path|public|, for freely redistributable fonts where the supplier
+neither (1)~requested their own directory (e.g., \path|ams|), nor
+(2)~also made proprietary fonts (e.g., \path|adobe|). It does not
+contain all extant freely distributable fonts, nor are all files therein
+necessarily strictly public domain.
+
+\item \path|tmp|, for dynamically-generated fonts, as is traditional on
+some systems. It may be omitted if unnecessary, as usual.
+
+\end{itemize}
+
+
+\item[\replaceable{typeface}] is the name of a typeface family
+(examples: \path|cm|, \path|euler|, \path|times|). The \abbr{TDS}
+reserves the following \replaceable{typeface} names:
+
+\begin{itemize}
+
+\item \path|cm| (within \path|public|), for the 75 fonts defined in
+\citetitle{Computers and Typesetting, Volume~E}.
+
+\item \path|latex| (within \path|public|), for those fonts distributed
+with \LaTeX{} in the base distribution.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local additions}.
+
+\end{itemize}
+
+\end{description}
+
+Some concrete examples:
+\begin{ttdisplay}
+texmf/fonts/source/public/pandora/pnr10.mf
+texmf/fonts/tfm/public/cm/cmr10.tfm
+texmf/fonts/type1/adobe/utopia/putr.pfa
+\end{ttdisplay}
+
+For complete supplier and typeface name lists, consult
+\citetitle{Filenames for \TeX{} fonts} (see Appendix~\ref{sec:Related
+references}).
+
+\subsubsection{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 \abbr{TDS} segregates fonts with
+different device types into separate directories. See \path|modes.mf|
+in Appendix~\ref{sec:Related references} for recommended mode names.
+
+Some printers operate at more than one resolution (e.g., at 300\,dpi and
+600\,dpi), 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 \MF{} program itself), the resolution is included in the
+filename (e.g., \path|cmr10.300pk|). On systems which do not support
+long filenames, fonts are generally segregated into directories by
+resolution (e.g., \path|dpi300/cmr10.pk|).
+
+Because the \abbr{TDS} cannot require long filenames, we must use the
+latter scheme for naming fonts. So we have two more subdirectory
+levels under \path|pk| and \path|gf|:
+
+\begin{ttdisplay}
+texmf/fonts/pk/\replaceable{mode}/\replaceable{supplier}/\replaceable{typeface}/dpi\replaceable{nnn}/
+texmf/fonts/gf/\replaceable{mode}/\replaceable{supplier}/\replaceable{typeface}/dpi\replaceable{nnn}/
+\end{ttdisplay}
+
+\begin{description}
+
+\item[\replaceable{mode}] is a name which identifies the device type
+(examples: \path|cx|, \path|ljfour|, \path|modeless|). Usually, this is
+the name of the \MF{} mode used to build the \abbr{PK} file. For fonts
+rendered as bitmaps by a program that does not distinguish between
+different output devices, the \replaceable{mode} name shall be simply
+\path|modeless|. The \replaceable{mode} level shall not be omitted,
+even if only a single mode happens to be in use.
+
+\item[\path|dpi|\replaceable{nnn}] specifies the resolution of the font
+(examples: \path|dpi300|, \path|dpi329|). `\literal{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 \replaceable{nnn} is to be calculated as if using \MF{}
+arithmetic and then rounded; i.e., it is the integer \MF{} uses in its
+output \path|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 \abbr{DVI} driver standard
+(see Appendix~\ref{sec:Related references}) in bitmap font searches by
+allowing a fuzz of $\pm0.2$\% (with a minimum of $1$) in the
+\replaceable{dpi}.
+
+\end{description}
+
+Implementations may provide extensions to the basic naming scheme, such
+as long filenames (as in the original \MF{}) and font library files (as
+in em\TeX{}'s \path|.fli| files), provided that the basic scheme is also
+supported.
+
+\subsubsection{Valid font bitmaps}
+\label{sec:Valid font bitmaps}
+
+The \abbr{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,
+\path|cmr10.pk| will be the filename for Computer Modern Roman 10\,pt at
+5--10 magnifications for 2--3 modes. (Section~\ref{sec:Duplicate
+filenames} discusses duplicate filenames in general.)
+
+To minimize this problem, we strongly recommend that \abbr{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 \MF{} will automatically provide the
+required information. If you have been using a local modes file derived
+from (or that is simply) \path|modes.mf| (see Appendix~\ref{sec:Related
+references}), the required information is already in your \abbr{PK}
+files. If not, a simple addition based on the code found in
+\path|modes.mf| can be made to your local modes file and the \abbr{PK}
+files rebuilt.
+
+
+\subsection{Non-font \MF{} files}
+\label{sec:Non-font MF files}
+
+Most \MF{} 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:
+
+\begin{ttdisplay}
+texmf/metafont/\replaceable{package}/
+\end{ttdisplay}
+
+\replaceable{package} is the name of a
+\MF{} package (for example, \path|mfpic|).
+
+The \abbr{TDS} reserves the following \replaceable{package} names:
+
+\begin{itemize}
+
+\item \path|base|, for the standard \MF{} macro files as described in
+\citetitle{The \MF{}book}, such as \path|plain.mf| and \path|expr.mf|.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local additions}.
+
+\item \path|misc|, for \MF{} packages consisting of only a single file
+(for example, \path|modes.mf|). An administrator or package maintainer
+may create directories for single-file packages at their discretion,
+instead of using \path|misc|.
+
+\end{itemize}
+
+
+\subsection{\MP{}}
+\label{sec:MetaPost}
+
+\MP{} is a picture-drawing language developed by John Hobby, derived
+from Knuth's \MF{}. Its primary purpose is to output Encapsulated \PS{}
+instead of bitmaps.
+
+\MP{} input files and the support files for \MP{}-related utilities
+shall be stored in:
+
+\begin{ttdisplay}
+texmf/metapost/\replaceable{package}/
+\end{ttdisplay}
+
+\replaceable{package} is the name of a \MP{} package. At the present
+writing none exist, but the \abbr{TWG} thought it prudent to leave room
+for contributed packages that might be written in the future.
+
+The \abbr{TDS} reserves the following \replaceable{package} names:
+
+\begin{itemize}
+
+\item \path|base|, for the standard \MP{} macro files, such as
+\path|plain.mp|, \path|mfplain.mp|, \path|boxes.mp|, and
+\path|graph.mp|. This includes files used by \iniMP{} when dumping mem
+files containing preloaded macro definitions.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local
+additions}.
+
+\item \path|misc|, for \MP{} packages consisting of only a single file.
+An administrator or package maintainer may create directories for
+single-file packages at their discretion, instead of using \path|misc|.
+
+\item \path|support|, for additional input files required by \MP{}
+utility programs, including a font map, a character adjustment table,
+and a subdirectory containing low-level \MP{} programs for rendering
+some special characters.
+
+\end{itemize}
+
+
+\subsection{\BibTeX{}}
+\label{sec:BibTeX}
+
+\BibTeX{}-related files shall be stored in:
+
+\begin{ttdisplay}
+texmf/bibtex/bib/\replaceable{package}/
+texmf/bibtex/bst/\replaceable{package}/
+\end{ttdisplay}
+
+The \path|bib| directory is for \BibTeX{} database (\path|.bib|) files,
+the \path|bst| directory for style (\path|.bst|) files.
+
+\replaceable{package} is the name of a \BibTeX{} package. The
+\abbr{TDS} reserves the following \replaceable{package} names (the same
+names are reserved under both \path|bib| and \path|bst|):
+
+\begin{itemize}
+
+\item \path|base|, for the standard \BibTeX{} databases and styles, such
+as \path|xampl.bib|, \path|plain.bst|.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local
+additions}.
+
+\item \path|misc|, for \BibTeX{} packages consisting of only a single
+file. An administrator or package maintainer may create directories for
+single-file packages at their discretion, instead of using \path|misc|.
+
+\end{itemize}
+
+
+\subsection{Scripts}
+\label{sec:Scripts}
+
+The top-level \path|scripts| directory is for platform-independent
+executables, such as Perl, Python, and shell scripts, and Java class
+files. Subdirectories under \path|scripts| are package names. This
+eases creating distributions, by providing a common place for such
+platform-independent programs.
+
+The intent is not for all such directories to be added to a user's
+command search path, which would be quite impractical. Rather, these
+executables are primarily for the benefit of wrapper scripts in whatever
+executable directory a distribution may provide (which is not specified
+by the \abbr{TDS}).
+
+Truly auxiliary scripts which are invoked directly by other programs,
+rather than wrapper scripts, may also be placed here. That is,
+\path|scripts| also serves as a platform-independent analog of the
+standard Unix \path|libexec| directory.
+
+We recommend using extensions specifying the language (such as
+\path|.pl|, \path|.py|, \path|.sh|) on these files, to help uniquely
+identify the name. Since the intent of the \abbr{TDS} is for programs
+in \path|scripts| not to be invoked directly by users, this poses no
+inconvenience.
+
+For example, in the \TeX{} Live distribution, the Con\TeX{}t user-level
+program \path|texexec| can exist as a small wrapper script in each
+\path|bin/|\replaceable{platform}\path|/texexec| (which is outside the
+\path|texmf| tree), which merely finds and calls
+\path|texmf/scripts/context/perl/texexec.pl|.
+
+Examples:
+\begin{ttdisplay}
+scripts/context/perl/texexec.pl
+scripts/context/ruby/examplex.rb
+scripts/thumbpdf/thumbpdf.pl
+\end{ttdisplay}
+
+The \abbr{TDS} does not specify a location for platform-dependent
+binary executables, whether auxiliary or user-level.
+
+
+\subsection{Documentation}
+\label{sec:Documentation}
+
+Most packages come with some form of documentation: user manuals,
+example files, programming guides, etc. In addition, many independent
+files not part of any macro or other package have been created to
+describe various aspects of the \TeX{} system.
+
+The \abbr{TDS} specifies that these additional documentation files shall
+be stored in a structure that parallels to some extent the
+\path|fonts| and \path|tex| directories, as follows:
+
+\begin{ttdisplay}
+texmf/doc/\replaceable{category}/...
+\end{ttdisplay}
+
+\replaceable{category} identifies the general topic of documentation
+that resides below it; for example, a \TeX{} format name (\path|latex|),
+program name (\path|bibtex|, \path|tex|), language (\path|french|,
+\path|german|), a file format (\path|info|, \path|man|), or other system
+components (\path|web|, \path|fonts|).
+
+One possible arrangement is to organize \path|doc| by language, with all
+the other category types below that. This helps users find
+documentation in the language(s) in which they are fluent. Neither this
+nor any other particular arrangement is required, however.
+
+Within each \replaceable{category} tree for a \TeX{} format, the
+directory \path|base| is reserved for base documentation distributed by
+the format's maintainers.
+
+The \abbr{TDS} reserves the following category names:
+
+\begin{itemize}
+
+\item \path|general|, for standalone documents not specific to any
+particular program (for example, Joachim Schrod's \citetitle{Components
+of \TeX{}}).
+
+\item \path|help|, for meta-information, such as \abbr{faq}'s,
+the \TeX{} Catalogue, etc.
+
+\item \path|info|, for processed Texinfo documents. (Info files, like
+anything else, may also be stored outside the \abbr{TDS}, at the
+installer's option.)
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local
+additions}.
+
+\end{itemize}
+
+The \path|doc| directory is intended for implementation-independent and
+operating system-independent documentation
+files. Implementation-dependent files are best stored elsewhere, as
+provided for by the implementation and/or \TeX{} administrator (for
+example, \abbr{VMS} help files under \path|texmf/vms/help|).
+
+The documentation directories may contain \TeX{} sources, \abbr{DVI}
+files, \PS{} files, text files, example input files, or any other useful
+documentation format(s).
+
+See Section~\ref{sec:Documentation tree summary} for a summary.
+
+
+\newpage
+\section{Summary}
+\label{sec:Summary}
+
+A skeleton of a \abbr{TDS} \texmf{} directory tree. This is not to
+imply these are the only entries allowed. For example, \path|local| may
+occur at any level.
+
+\begin{tdsSummary}
+ bibtex/ \BibTeX{} input files
+ . bib/ \BibTeX{} databases
+ . . base/ base distribution (e.g., \path|xampl.bib|)
+ . . misc/ single-file databases
+ . <package>/ name of a package
+ . bst/ \BibTeX{} style files
+ . . base/ base distribution (e.g., \path|plain.bst|, \path|acm.bst|)
+ . . misc/ single-file styles
+ . <package>/ name of a package
+ doc/ see Section~\ref{sec:Documentation} and the summary below
+ fonts/ font-related files
+ . <type>/ file type (e.g., \path|pk|)
+ . . <mode>/ type of output device (for \path|pk| and \path|gf| only)
+ . . . <supplier>/ name of a font supplier (e.g., \path|public|)
+ . . . . <typeface>/ name of a typeface (e.g., \path|cm|)
+ . . . . . dpi<nnn>/ font resolution (for \path|pk| and \path|gf| only)
+ <implementation>/ \TeX{} implementations, by name (e.g., \path|emtex|)
+ local/ files created or modified at the local site
+ metafont/ \MF{} (non-font) input files
+ . base/ base distribution (e.g., \path|plain.mf|)
+ . misc/ single-file packages (e.g., \path|modes.mf|)
+ . <package>/ name of a package (e.g., \path|mfpic|)
+ metapost/ \MP{} input and support files
+ . base/ base distribution (e.g., \path|plain.mp|)
+ . misc/ single-file packages
+ . <package>/ name of a package
+ . support/ support files for \MP{}-related utilities
+ mft/ \path|MFT| inputs (e.g., \path|plain.mft|)
+ <program>/ \TeX{}-related programs, by name (e.g., \path|dvips|)
+ source/ program source code by name (e.g., \path|latex|, \path|web2c|)
+ tex/ \TeX{} input files
+ . <engine>/ name of an engine (e.g., \path|aleph|); can also be lower
+ . <format>/ name of a format (e.g., \path|plain|)
+ . . base/ base distribution for format (e.g., \path|plain.tex|)
+ . . misc/ single-file packages (e.g., \path|webmac.tex|)
+ . . local/ local additions to or local configuration files for \replaceable{format}
+ . . <package>/ name of a package (e.g., \path|graphics|, \path|mfnfss|)
+ . generic/ format-independent packages
+ . . hyphen/ hyphenation patterns (e.g., \path|hyphen.tex|)
+ . . images/ image input files (e.g., Encapsulated PostScript)
+ . . misc/ single-file format-independent packages (e.g., \path|null.tex|).
+ . . <package>/ name of a package (e.g., \path|babel|)
+\end{tdsSummary}
+
+
+\newpage
+\subsection{Documentation tree summary}
+\label{sec:Documentation tree summary}
+
+An example skeleton of a \abbr{TDS} directory tree under
+\path|texmf/doc|. This is not to imply these are the only entries
+allowed, or that this structure must be followed precisely for the
+entries listed.
+
+As mentioned, the \path|texmf/doc| tree may be organized by language, so
+that all documentation in French, say, is in a \path|french|
+subdirectory. In that case, the example structure here would be in a
+given language directory.
+
+\begin{tdsSummary}
+ ams/
+ . amsfonts/ \path|amsfonts.faq|, \path|amfndoc|
+ . amslatex/ \path|amslatex.faq|, \path|amsldoc|
+ . amstex/ \path|amsguide|, \path|joyerr|
+ bibtex/ \BibTeX{}
+ . base/ \path|btxdoc.tex|
+ fonts/
+ . fontname/ \citetitle{Filenames for \TeX{} fonts}
+ . oldgerm/ \path|corkpapr|
+ <format>/ name of a \TeX{} format (e.g., \path|generic|, \path|latex|)
+ . base/ for the base distribution
+ . misc/ for contributed single-file package documentation
+ . <package>/ for \emphasis{package}
+ general/ across programs, generalities
+ . errata/ \path|errata|, \path|errata[1-8]|
+ . texcomp/ \citetitle{Components of \TeX{}}
+ help/ meta-information
+ . ctan/ info about \abbr{ctan} mirror sites
+ . faq/ \abbr{faq}s of \path|comp.text.tex|, etc.
+ info/ \abbr{gnu} Info files, made from Texinfo sources
+ latex/ example of \replaceable{format}
+ . base/ \path|ltnews*|, \path|*guide|, etc.
+ . graphics/ \path|grfguide|
+ local/ site-specific documentation
+ man/ Unix man pages
+ <program>/ \TeX{}-related programs, by name (examples follow)
+ metafont/ \path|mfbook.tex|, \path|metafont-for-beginners|, etc.
+ metapost/ \path|mpman|, \path|manfig|, etc.
+ tex/ \path|texbook.tex|, \citetitle{A Gentle Introduction to \TeX{}}, etc.
+ web/ \path|webman|, \path|cwebman|
+\end{tdsSummary}
+
+
+\newpage
+\appendix
+
+\section{Unspecified pieces}
+
+The \abbr{TDS} cannot address the following aspects of a functioning
+\TeX{} system:
+
+\begin{enumerate}
+
+\item The location of executable programs: this is too site-dependent
+even to recommend a location, let alone require one. A site may place
+executables outside the \texmf{} tree altogether (e.g.,
+\path|/usr/local/bin|), in a platform-dependent directory within
+\texmf{}, or elsewhere.
+
+\item Upgrading packages when new releases are made: we could find no
+way of introducing version specifiers into \texmf{} that would do more
+good than harm, or that would be practical for even a plurality of
+installations.
+
+\item The location of implementation-specific files (e.g., \TeX{}
+\path|.fmt| files): by their nature, these must be left to the
+implementor or \TeX{} maintainer. See Section~\ref{sec:Example
+implementation-specific trees}.
+
+\item Precisely when a package or file should be considered ``local'',
+and where such local files are installed. See Section~\ref{sec:Local
+additions} for more discussion.
+
+\end{enumerate}
+
+
+\subsection{Portable filenames}
+\label{sec:Portable filenames}
+
+The \abbr{TDS} cannot require any particular restriction on filenames in
+the tree, since the names of many existing \TeX{} files conform to no
+standard scheme. For the benefit of people who wish to make a portable
+\TeX{} distribution or installation, however, we outline here the
+necessary restrictions. The \abbr{TDS} specifications themselves are
+compatible with these.
+
+\abbr{ISO}-9660 is the only universally acceptable file system format
+for \abbr{CD-ROM}s. A subset thereof meets the stringent limitations of
+all operating systems in use today. It specifies the following:
+
+\begin{itemize-squeeze}
+
+\item File and directory names, not including any directory path or
+extension part, may not exceed eight characters.
+
+\item Filenames may have a single extension. Extensions may not exceed
+three characters. Directory names may not have an extension.
+
+\item Names and extensions may consist of \emphasis{only} the characters
+\literal{A}--\literal{Z}, \literal{0}--\literal{9}, and underscore.
+Lowercase letters are excluded.
+
+\item A period separates the filename from the extension and is always
+present, even if the name or extension is missing (e.g.,
+\path|FILENAME.| or \path|.EXT|).
+
+\item A version number, ranging from 1--32767, is appended to the file
+extension, separated by a semicolon (e.g., \path|FILENAME.EXT;1|).
+
+\item Only eight directory levels are allowed, including the top-level
+(mounted) directory (see Section~\ref{sec:Rooting the tree}). Thus, the
+deepest valid \abbr{ISO}-9660 path is:
+\begin{ttdisplay}
+texmf/L2/L3/L4/L5/L6/L7/L8/FOO.BAR;1
+1 2 3 4 5 6 7 8
+\end{ttdisplay}
+The deepest \abbr{TDS} path needs only seven levels:
+\begin{ttdisplay}
+texmf/fonts/pk/cx/public/cm/dpi300/cmr10.pk
+1 2 3 4 5 6 7
+\end{ttdisplay}
+
+\end{itemize-squeeze}
+
+Some systems display a modified format of \abbr{ISO}-9660 names,
+mapping alphabetic characters to lowercase, removing version numbers and
+trailing periods, etc.
+
+Before the December 1996 release, \LaTeX{} used mixed-case names for
+font descriptor files. Fortunately, it never relied on case alone to
+distinguish among the files. Nowadays, it uses only monocase names.
+
+\section{Implementation issues}
+
+We believe that the \abbr{TDS} can bring a great deal of order to the
+current anarchic state of many \TeX{} installations. In addition, by
+providing a common frame of reference, it will ease the burden of
+documenting administrative tasks. Finally, it is a necessary part of
+any reasonable system of true ``drop-in'' distribution packages for
+\TeX{}.
+
+
+\subsection{Adoption of the \abbr{TDS}}
+
+[This section is retained for historical purposes; the \abbr{TDS}
+is now quite firmly entrenched in most \TeX{} distributions.]
+
+We recognize that adoption of the \abbr{TDS} will not be immediate or
+universal. Most \TeX{} administrators will not be inclined to make the
+final switch until:
+
+\begin{itemize-squeeze}
+\item Clear and demonstrable benefits can be shown for the \abbr{TDS}.
+\item \abbr{TDS}-compliant versions of all key programs are available
+in ported, well-tested forms.
+\item A ``settling'' period has taken place, to flush out problems. The
+public release of the first draft of this document was the first step in
+this process.
+\end{itemize-squeeze}
+
+Consequently, most of the first trials of the \abbr{TDS} will be made by
+members of the \abbr{TDS} committee and/or developers of \TeX{}-related
+software. This has already taken place during the course of our
+deliberations (see Appendix~\ref{sec:Related references} for a sample
+tree available electronically). They will certainly result in the
+production of a substantial number of \abbr{TDS}-compliant packages.
+Indeed, the \application{te\TeX{}} and \application{\TeX{} Live}
+distributions are \abbr{TDS}-compliant and in use now at many sites.
+
+Once installable forms of key \abbr{TDS}-compliant packages are more
+widespread, some \TeX{} administrators will set up \abbr{TDS}-compliant
+trees, possibly in parallel to existing production directories. This
+testing will likely flush out problems that were not obvious in the
+confined settings of the developers' sites; for example, it should help
+to resolve system and package dependencies, package interdependencies, and
+other details not addressed by this \abbr{TDS} version.
+
+After most of the dust has settled, hopefully even conservative \TeX{}
+administrators will begin to adopt the \abbr{TDS}. Eventually, most
+\TeX{} sites will have adopted the common structure, and most packages
+will be readily available in \abbr{TDS}-compliant form.
+
+We believe that this process will occur relatively quickly. The
+\abbr{TDS} committee spans a wide range of interests in the \TeX{}
+community. Consequently, we believe that most of the key issues
+involved in defining a workable \abbr{TDS} definition have been covered,
+often in detail. \TeX{} developers have been consulted about
+implementation issues, and have been trying out the \abbr{TDS}
+arrangement. Thus, we hope for few surprises as implementations mature.
+
+Finally, there are several (current or prospective) publishers of \TeX{}
+\abbr{CD-ROM}s. These publishers are highly motivated to work out
+details of \abbr{TDS} implementation, and their products will provide
+inexpensive and convenient ways for experimentally-minded \TeX{}
+administrators to experiment with the \abbr{TDS}.
+
+
+\subsection{More on subdirectory searching}
+\label{sec:More on subdirectory searching}
+
+Recursive subdirectory searching is the ability to specify a search not
+only of a specified directory \replaceable{d}, but recursively of all
+directories below \replaceable{d}.
+
+Since the \abbr{TDS} specifies precise locations for most files, with no
+extra levels of subdirectories allowed, true recursive searching is not
+actually required for a \abbr{TDS}-compliant implementation. We do,
+however, strongly recommend recursive searching as the most
+user-friendly and natural approach to the problem, rather than
+convoluted methods to specify paths without recursion.
+
+This feature is already supported by many implementations of \TeX{} and
+companion utilities, for example \abbr{DECUS} \TeX{} for \abbr{VMS},
+\application{Dvips(k)}, \application{em\TeX{}} (and its drivers),
+\application{PubliC \TeX{}}, \application{Web2C}, \application{Xdvi(k)},
+and \application{Y\&Y\TeX{}}. The Kpathsea library is a reusable
+implementation of subdirectory searching for \TeX{}, used in a number of
+the above programs.
+
+Even if your \TeX{} implementation does not directly support
+subdirectory searching, you may find it useful to adopt the structure if
+you do not use many fonts or packages. For instance, if you only use
+Computer Modern and \abbr{ams} fonts, it would be feasible to store them
+in the \abbr{TDS} layout and list the directories individually in
+configuration files or environment variables.
+
+The \abbr{TWG} recognizes that subdirectory searching places an extra
+burden on the system and may be the source of performance bottlenecks,
+particularly on slower machines. Nevertheless, we feel that
+subdirectory searching is imperative for a well-organized \abbr{TDS},
+for the reasons stated in Section~\ref{sec:Subdirectory searching}.
+Implementors are encouraged to provide enhancements to the basic
+principle of subdirectory searching to avoid performance problems, e.g.,
+the use of a filename cache (this can be as simple as a recursive
+directory listing) that is consulted before disk searching begins. If a
+match is found in the database, subdirectory searching is not required,
+and performance is thus independent of the number of subdirectories
+present on the system.
+
+Different implementations specify subdirectory searching differently.
+In the interest of typographic clarity, the examples here do not use the
+\replaceable{replaceable} font.
+
+\begin{description-squeeze}
+
+\item[\application{Dvips}:] via a separate
+\systemitem{ENVIRONVAR}{TEXFONTS\_SUBDIR} environment variable.
+
+\item[\application{em\TeX{}}:] \path|t:\subdir!!|; \path|t:\subdir!| for
+a single level of searching.
+
+\item[\application{Kpathsea}:] \path|texmf/subdir//|
+
+\item[\abbr{VMS}:] \path|texmf:[subdir...]|
+
+\item[\application{Xdvi} (patchlevel 20):] \path|texmf/subdir/**|;
+\path|texmf/subdir/*| for a single level of searching. Version 20.50
+and above support the \path|//| notation.
+
+\item[\application{Y\&Y \TeX{}}:] \path|t:/subdir//| or
+\path|t:\subdir\\|.
+
+\end{description-squeeze}
+
+
+\subsection{Example implementation-specific trees}
+\label{sec:Example implementation-specific trees}
+
+The \abbr{TDS} cannot specify a precise location for
+implementation-specific files, such as \path|texmf/ini|, because a site
+may have multiple \TeX{} implementations.
+
+Nevertheless, for informative purposes, we provide here the default
+locations for some implementations. Please contact us with additions or
+corrections. These paths are not definitive, may not match anything at
+your site, and may change without warning.
+
+We recommend all implementations have default search paths that start
+with the current directory (e.g., `\path|.|'). Allowing users to
+include the parent directory (e.g., `\path|..|') is also helpful.
+
+
+\subsubsection{AmiWeb2c 2.0}
+
+(Email \email|scherer@physik.rwth-aachen.de| to contact the maintainer
+of this implementation.)
+
+AmiWeb2c 2 is compatible with Web2c 7 to the greatest possible
+extent, so only the very few differences are described in this
+section. Detailed information about the basic concepts is given in
+the section for Web2c 7 below.
+
+Thanks to the \path|SELFAUTO| mechanism of Kpathsea 3.0 no specific
+location for the installation of AmiWeb2c is required as long as the
+general structure of the distribution is preserved.
+
+In addition to Kpathsea's \path|//| notation recursive path search may
+also be started by \replaceable{DEVICE}\path|:/|, e.g., \path|TeXMF:/|
+will scan this specific device completely.
+
+Binaries coming with the AmiWeb2c distribution are installed in the
+directory \path|bin/amiweb2c/| outside the common \abbr{TDS} tree
+\path|share/texmf/|. In addition to the set of AmiWeb2c binaries
+you will find two subdirectories \path|local/| and \path|pastex/|
+with auxiliary programs.
+
+A stripped version of the Pas\TeX{} system (used by kind permission of
+Georg He\ss{}mann) is coming with AmiWeb2c, pre-installed in its own
+\path|share/texmf/amiweb2c/pastex/| directory. If you want to use
+Pas\TeX{} you have to \path|assign| the name \path|TeX:| to this place.
+
+Documentation files in AmigaGuide format should be stored at
+\path|doc/guide/| similar to \path|doc/info/|.
+
+
+\subsubsection{Public \abbr{DECUS} \TeX{}}
+
+If another \abbr{VMS} implementation besides Public \abbr{DECUS} \TeX{}
+appears, the top level implementation directory name will be modified to
+something more specific (e.g., \path|vms_decus|).
+
+\begin{tdsSummary}
+ texmf/
+ . vms/ \abbr{VMS} implementation specific files
+ . . exe/ end-user commands
+ . . . common/ command procedures, command definition files, etc.
+ . . . axp/ binary executables for Alpha \abbr{AXP}
+ . . . vax/ binary executables for \abbr{VAX}
+ . . formats/ pool files, formats, bases
+ . . help/ \abbr{VMS} help library, and miscellaneous help sources
+ . . mgr/ command procedures, programs, docs, etc., for system management
+\end{tdsSummary}
+
+
+\subsubsection{Web2c 7}
+
+All implementation-dependent \TeX{} system files (\path|.pool|,
+\path|.fmt|, \path|.base|, \path|.mem|) are stored by default directly
+in \path|texmf/web2c|. The configuration file \path|texmf.cnf| and
+various subsidiary \path|MakeTeX...| scripts used as subroutines are
+also stored there.
+
+Non-\TeX{} specific files are stored following the \abbr{GNU} coding
+standards. Given a root directory \replaceable{prefix}
+(\path|/usr/local| by default), we have default locations as follows:
+
+\begin{tdsSummary}
+ <prefix>/ installation root (\path|/usr/local| by default)
+ . bin/ executables
+ . man/ man pages
+ . info/ info files
+ . lib/ libraries (\path|libkpathsea.*|)
+ . share/ architecture-independent files
+ . . texmf/ \abbr{TDS} root
+ . . . web2c/ implementation-dependent files (\path|.pool|, \path|.fmt|, \path|texmf.cnf|, etc.)
+\end{tdsSummary}
+
+See \url|http://www.gnu.org/prep/standards_toc.html| for the
+rationale behind and descriptions of this arrangement. A site may of
+course override these defaults; for example, it may put everything under
+a single directory such as \path|/usr/local/texmf|.
+
+
+\section{Is there a better way?}
+
+Defining the \abbr{TDS} required many compromises. Both the overall
+structure and the details of the individual directories were arrived at
+by finding common ground among many opinions. The driving forces were
+feasibility (in terms of what could technically be done and what could
+reasonably be expected from developers) and regularity (files grouped
+together in an arrangement that ``made sense'').
+
+Some interesting ideas could not be applied due to implementations
+lacking the necessary support:
+
+\begin{itemize}
+
+\item Path searching control at the \TeX{} level. If documents could
+restrict subdirectory searching to a subdirectory via some portable
+syntax in file names, restrictions on uniqueness of filenames could be
+relaxed considerably (with the cooperation of the formats), and the
+\TeX{} search path would not need to depend on the format.
+
+\item Multiple logical \texmf{} trees. For example, a site might have
+one (read-only) location for stable files, and a different (writable)
+location for dynamically-created fonts or other files. It would be
+reasonable for two such trees to be logically merged when searching.
+See Michael Downes' article in the references for how this can work in
+practice with Web2C.
+
+\end{itemize}
+
+\subsection{Macro structure}
+
+The \abbr{TWG} settled on the
+\replaceable{format}\path|/|\replaceable{package} arrangement after long
+discussion about how best to arrange the files.
+
+The primary alternative to this arrangement was a scheme which reversed
+the order of these directories:
+\replaceable{package}\path|/|\replaceable{format}. This reversed
+arrangement has a strong appeal: it keeps all of the files related to a
+particular package in a single place. The arrangement actually adopted
+tends to spread files out into two or three places (macros,
+documentation, and fonts, for example, are spread into different
+sections of the tree right at the top level).
+
+Nevertheless, the \replaceable{format}\path|/|\replaceable{package}
+structure won for a couple of reasons:
+
+\begin{itemize-squeeze}
+\item It is closer to current practice; in fact, several members of the
+\abbr{TWG} have already implemented the \abbr{TDS} hierarchy. The
+alternative is not in use at any known site, and the \abbr{TWG} felt it
+wrong to mandate something with which there is no practical experience.
+
+\item The alternative arrangement increases the number of top-level
+directories, so the files that must be found using subdirectory
+searching are spread out in a wide, shallow tree. This could have a
+profound impact on the efficiency of subdirectory searching.
+
+\end{itemize-squeeze}
+
+
+\subsection{Font structure}
+
+The \abbr{TWG} struggled more with the font directory structure than
+anything else. This is not surprising; the need to use the proliferation
+of PostScript fonts with \TeX{} is what made the previous arrangement
+with all files in a single directory untenable, and therefore what
+initiated the \abbr{TDS} effort.
+
+
+\subsubsection{Font file type location}
+
+We considered the supplier-first arrangement in use at many sites:
+
+\begin{ttdisplay}
+texmf/fonts/\replaceable{supplier}/\replaceable{typeface}/\replaceable{type}/
+\end{ttdisplay}
+
+This improves the maintainability of the font tree, since all files
+comprising a given typeface are in one place, but unless all the
+programs that search this tree employ some form of caching, there are
+serious performance concerns. For example, in order to find a
+\path|TFM| file, the simplest implementation would require \TeX{} to
+search through all the directories that contain \abbr{PK} files in all
+modes and at all resolutions.
+
+In the end, a poll of developers revealed considerable resistance to
+implementing sufficient caching mechanisms, so this arrangement was
+abandoned. The \abbr{TDS} arrangement allows the search tree to be
+restricted to the correct type of file, at least. Concerns about
+efficiency remain, but there seems to be no more we can do without
+abandoning subdirectory searching entirely.
+
+We also considered segregating all font-related files strictly by file
+type, so that \MF{} sources would be in a directory
+\path|texmf/fonts/mf|, property list files in \path|texmf/fonts/pl|, the
+various forms of Type~1 fonts separated, and so on. Although more
+blindly consistent, we felt that the drawback of more complicated path
+constructions outweighed this. The \abbr{TDS} merges file types
+(\path|mf| and \path|pl| under \path|source|, \path|pfa| and \path|pfb|
+and \path|gsf| under \path|type1|) where we felt this was beneficial.
+
+
+\subsubsection{Mode and resolution location}
+
+We considered having the \path|mode| at the bottom of the font tree:
+\begin{ttdisplay}
+texmf/fonts/pk/\replaceable{supplier}/\replaceable{typeface}/\replaceable{mode}/\replaceable{dpi}/
+\end{ttdisplay}
+
+In this case, however, it is difficult to limit subdirectory searching
+to the mode required for a particular device.
+
+We then considered moving the \path|dpi|\replaceable{nnn} up to below
+the mode:
+\begin{ttdisplay}
+texmf/fonts/pk/\replaceable{mode}/\replaceable{dpi}/\replaceable{supplier}/\replaceable{typeface}/
+\end{ttdisplay}
+
+But then it is not feasible to omit the \path|dpi|\replaceable{nnn}
+level altogether on systems which can and do choose to use long
+filenames.
+
+
+\subsubsection{Modeless bitmaps}
+
+The \abbr{TDS} specifies using a single directory \path|modeless/| as
+the mode name for those utilities which generate bitmaps, e.g.,
+\path|texmf/fonts/modeless/times/|. This has the considerable advantage
+of not requiring each such directory name to be listed in a search path.
+
+An alternative was to use the utility name below which all such
+directories could be gathered. That has the advantage of separating,
+say, \path|gsftopk|-generated bitmaps from \path|ps2pk|-generated ones.
+However, we decided this was not necessary; most sites will use only one
+program for the purpose. Also, \abbr{PK} and \abbr{GF} fonts generally
+identify their creator in the font comment following the \path|PK_ID|
+byte.
+
+We are making an implicit assumption that \MF{} is the only program
+producing mode-dependent bitmaps. If this becomes false we could add an
+abbreviation for the program to mode names, as in \path|mfcx| vs.\
+\path|xyzcx| for a hypothetical program \application{Xyz}, or we could
+at that time add an additional program name level uniformly to the tree.
+It seemed more important to concisely represent the current situation
+than to worry about hypothetical possibilities that may never~happen.
+
+
+\subsection{Documentation structure}
+
+We considered placing additional documentation files in the same
+directory as the source files for the packages, but we felt that users
+should be able to find documentation separately from sources, since most
+users have no interest in sources.
+
+We hope that a separate, but parallel, structure for documentation would
+(1)~keep the documentation together and (2)~make it as straightforward
+as possible for users to find the particular documentation they were
+after.
+
+
+\section{Related references}
+\label{sec:Related references}
+
+This appendix gives pointers to related files and other documents. For
+\abbr{CTAN} references, we use \path|http://www.ctan.org| as the
+top-level domain only to make the links be live in this document. See
+\url|http://www.ctan.org/tex-archive/CTAN.sites| for a complete list of
+\abbr{ctan} sites; there are mirrors worldwide.
+
+\begin{itemize-squeeze}
+
+\item This document, in many formats (tex, dvi, info, pdf):\\ \hspace*{1em}
+\url|http://tug.org/tds/|
+
+\item The \abbr{TDS} mailing list archives:\\ \hspace*{1em}
+\url|http://tug.org/mail-archives/twg-tds/|
+
+\item The level~0 \abbr{DVI} driver standard:\\ \hspace*{1em}
+\url|http://www.ctan.org/tex-archive/dviware/driv-standard/level-0/|
+
+\item \citetitle{Filenames for \TeX{} fonts}, with lists of recommended
+supplier and typeface names:\\ \hspace*{1em}
+\url|http://tug.org/fontname/|
+
+\item \abbr{ISO}-9660 \abbr{CD-ROM} file system standard:\\ \hspace*{1em}
+\url|http://www.iso.ch/cate/cat.html|
+
+\item \citetitle{Components of \TeX{}}, a paper by Joachim
+Schrod:\\ \hspace*{1em}
+\url|http://www.ctan.org/tex-archive/documentation/components-of-TeX/|
+
+\item \citetitle{Managing Multiple TDS trees}, an article by Michael
+Downes:\\ \hspace*{1em}
+\url|http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf|
+
+\item A complete set of \MF{} modes:\\ \hspace*{1em}
+\url|http://www.ctan.org/tex-archive/fonts/modes/modes.mf|
+
+\item A large collection of \BibTeX{} databases and styles:\\ \hspace*{1em}
+\url|ftp://ftp.math.utah.edu/pub/tex/bib/|
+
+\end{itemize-squeeze}
+
+
+\section{Contributors}
+
+The \abbr{TWG} has had no physical meetings; electronic mail was the
+communication medium.
+
+Sebastian Rahtz is the \TeX{} Users Group Technical Council liaison.
+Norman Walsh was the original committee chair. Karl Berry is the
+current editor.
+
+The list of contributors has grown too large to fairly include, as some
+would surely be inadvertently omitted. Please consider the archives of
+the \email|tds@tug.org| and \email|tex-live@tug.org| mailing lists as
+the record of contributions.
+
+
+\end{document}