summaryrefslogtreecommitdiff
path: root/info/tds/tds.html
diff options
context:
space:
mode:
Diffstat (limited to 'info/tds/tds.html')
-rw-r--r--info/tds/tds.html1997
1 files changed, 1997 insertions, 0 deletions
diff --git a/info/tds/tds.html b/info/tds/tds.html
new file mode 100644
index 0000000000..49da35a2f5
--- /dev/null
+++ b/info/tds/tds.html
@@ -0,0 +1,1997 @@
+<html lang="en">
+<head>
+<title>A Directory Structure for TeX Files</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="A Directory Structure for TeX Files">
+<meta name="generator" content="makeinfo 4.7">
+<link title="Top" rel="top" href="#Top">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+ pre.display { font-family:inherit }
+ pre.format { font-family:inherit }
+ pre.smalldisplay { font-family:inherit; font-size:smaller }
+ pre.smallformat { font-family:inherit; font-size:smaller }
+ pre.smallexample { font-size:smaller }
+ pre.smalllisp { font-size:smaller }
+ span.sc { font-variant:small-caps }
+ span.roman { font-family:serif; font-weight:normal; }
+--></style>
+</head>
+<body>
+<h1 class="settitle">A Directory Structure for TeX Files</h1>
+<div class="node">
+<p><hr>
+<a name="Top"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Introduction">Introduction</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#dir">(dir)</a>
+<br>
+</div>
+
+<h2 class="unnumbered">A Directory Structure for TeX Files</h2>
+
+<p>Copyright &copy; 1994, 1995, 1996, 1997, 1998, 1999, 2003, 2004
+TeX Users Group.
+
+ <p>Permission to use, copy, and distribute this document <em>without
+modification</em> for any purpose and without fee is hereby granted,
+provided that this notice appears in all copies. It is provided &ldquo;as
+is&rdquo; without expressed or implied warranty.
+
+ <p>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.
+
+ <p>This document is available on any CTAN host
+(see Appendix&nbsp;<!-- /@w --><a href="#Related-references">Related references</a>).
+Please send questions or suggestions by email to
+<a href="mailto:tds@tug.org">tds@tug.org</a>. We welcome all comments. This is version
+1.1.
+
+<ul class="menu">
+<li><a accesskey="1" href="#Introduction">Introduction</a>
+<li><a accesskey="2" href="#General">General</a>
+<li><a accesskey="3" href="#Top_002dlevel-directories">Top-level directories</a>
+<li><a accesskey="4" href="#Summary">Summary</a>
+<li><a accesskey="5" href="#Unspecified-pieces">Unspecified pieces</a>
+<li><a accesskey="6" href="#Implementation-issues">Implementation issues</a>
+<li><a accesskey="7" href="#Is-there-a-better-way_003f">Is there a better way?</a>
+<li><a accesskey="8" href="#Related-references">Related references</a>
+<li><a accesskey="9" href="#Contributors">Contributors</a>
+
+</li></ul>
+<p>--- The Detailed Node Listing ---
+
+<p>Introduction
+
+</p>
+<ul class="menu">
+<li><a href="#History">History</a>
+<li><a href="#The-role-of-the-TDS">The role of the TDS</a>
+<li><a href="#Conventions">Conventions</a>
+
+</li></ul>
+<p>General
+
+</p>
+<ul class="menu">
+<li><a href="#Subdirectory-searching">Subdirectory searching</a>
+<li><a href="#Rooting-the-tree">Rooting the tree</a>
+<li><a href="#Local-additions">Local additions</a>
+<li><a href="#Duplicate-filenames">Duplicate filenames</a>
+
+</li></ul>
+<p>Top-level directories
+
+</p>
+<ul class="menu">
+<li><a href="#Macros">Macros</a>
+<li><a href="#Fonts">Fonts</a>
+<li><a href="#Non_002dfont-Metafont-files">Non-font Metafont files</a>
+<li><a href="#MetaPost">MetaPost</a>
+<li><a href="#BibTeX">BibTeX</a>
+<li><a href="#Scripts">Scripts</a>
+<li><a href="#Documentation">Documentation</a>
+
+</li></ul>
+<p>Macros
+
+</p>
+<ul class="menu">
+<li><a href="#Extensions">Extensions</a>
+
+</li></ul>
+<p>Fonts
+
+</p>
+<ul class="menu">
+<li><a href="#Font-bitmaps">Font bitmaps</a>
+<li><a href="#Valid-font-bitmaps">Valid font bitmaps</a>
+
+</li></ul>
+<p>Summary
+
+</p>
+<ul class="menu">
+<li><a href="#Documentation-tree-summary">Documentation tree summary</a>
+
+</li></ul>
+<p>Unspecified pieces
+
+</p>
+<ul class="menu">
+<li><a href="#Portable-filenames">Portable filenames</a>
+
+</li></ul>
+<p>Implementation issues
+
+</p>
+<ul class="menu">
+<li><a href="#Adoption-of-the-TDS">Adoption of the TDS</a>
+<li><a href="#More-on-subdirectory-searching">More on subdirectory searching</a>
+<li><a href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>
+
+</li></ul>
+<p>Example implementation-specific trees
+
+</p>
+<ul class="menu">
+<li><a href="#AmiWeb2c-2_002e0">AmiWeb2c 2.0</a>
+<li><a href="#Public-DECUS-TeX">Public DECUS TeX</a>
+<li><a href="#Web2c-7">Web2c 7</a>
+
+</li></ul>
+<p>Is there a better way?
+
+</p>
+<ul class="menu">
+<li><a href="#Macro-structure">Macro structure</a>
+<li><a href="#Font-structure">Font structure</a>
+<li><a href="#Documentation-structure">Documentation structure</a>
+
+</li></ul>
+<p>Font structure
+
+</p>
+<ul class="menu">
+<li><a href="#Font-file-type-location">Font file type location</a>
+<li><a href="#Mode-and-resolution-location">Mode and resolution location</a>
+<li><a href="#Modeless-bitmaps">Modeless bitmaps</a>
+
+ </ul>
+
+<div class="node">
+<p><hr>
+<a name="Introduction"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#General">General</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Top">Top</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
+<br>
+</div>
+
+<h2 class="chapter">1 Introduction</h2>
+
+<p>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 &ldquo;right&rdquo; way to install it.
+This has resulted in many sites having different installed arrangements.
+
+ <p>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 TeX files into a 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.
+
+ <p>This document is intended both for the TeX system administrator at a
+site and for people preparing TeX distributions&mdash;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&nbsp;<!-- /@w --><a href="#Related-references">Related references</a>.
+
+<ul class="menu">
+<li><a accesskey="1" href="#History">History</a>
+<li><a accesskey="2" href="#The-role-of-the-TDS">The role of the TDS</a>
+<li><a accesskey="3" href="#Conventions">Conventions</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="History"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#The-role-of-the-TDS">The role of the TDS</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Introduction">Introduction</a>
+<br>
+</div>
+
+<h3 class="section">1.1 History</h3>
+
+<p>Version 1.0 of the TDS was released in February 2003.
+
+ <p>Version 1.1 was released in June 2004, with the following non-editorial
+changes:
+
+ <ul>
+<li>Inputs for TeX extensions included under <samp><span class="file">tex</span></samp>, instead
+ of in their own top-level directories (Section&nbsp;<!-- /@w --><a href="#Extensions">Extensions</a>)
+<li>New top-level directory <samp><span class="file">scripts</span></samp> (Section&nbsp;<!-- /@w --><a href="#Scripts">Scripts</a>).
+<li>New subdirectories <samp><span class="file">lig</span></samp>, <samp><span class="file">opentype</span></samp>,
+ <samp><span class="file">truetype</span></samp>, and <samp><span class="file">type3</span></samp> under <samp><span class="file">fonts</span></samp>
+ (Section&nbsp;<!-- /@w --><a href="#Fonts">Fonts</a>).
+<li>`<samp><span class="samp">enc</span></samp>',
+<samp><span class="file">lig</span></samp>, and <samp><span class="file">map</span></samp> all use
+ <samp><var>syntax</var><span class="file">/</span><var>package</var></samp> subdirectories
+ (Section&nbsp;<!-- /@w --><a href="#Fonts">Fonts</a>).
+<li>`<samp><span class="samp">pfm</span></samp>' files specified to go under <samp><span class="file">type1</span></samp>,
+and
+ <samp><span class="file">inf</span></samp> files under <samp><span class="file">afm</span></samp> (Section&nbsp;<!-- /@w --><a href="#Fonts">Fonts</a>).
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="The-role-of-the-TDS"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Conventions">Conventions</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#History">History</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Introduction">Introduction</a>
+<br>
+</div>
+
+<h3 class="section">1.2 The role of the TDS</h3>
+
+<p>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.
+
+ <p>At first glance, it may seem that the Comprehensive TeX Archive
+Network (CTAN) fulfills 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.
+
+ <p>In fact, the roles of the TDS and 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.
+
+<div class="node">
+<p><hr>
+<a name="Conventions"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-role-of-the-TDS">The role of the TDS</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Introduction">Introduction</a>
+<br>
+</div>
+
+<h3 class="section">1.3 Conventions</h3>
+
+<p>In this document, <samp><span class="file">/</span></samp> is used to separate filename components;
+for example, <samp><span class="file">texmf/fonts</span></samp>. This is the Unix convention but the
+ideas are in no way Unix-specific.
+
+ <p>In this document, &ldquo;TeX&rdquo; generally means the TeX system, including
+Metafont, DVI drivers, utilities, etc., not just the TeX
+program itself.
+
+ <p>The word &ldquo;package&rdquo; in this document has its usual meaning: a set of
+related files distributed, installed, and maintained as a unit. This is
+<em>not</em> a LaTeX2e package, which is a style file supplementing
+a document class.
+
+ <p>We use the following typographic conventions:
+
+ <ul>
+<li>`<samp><span class="samp">literal</span></samp>'
+Literal text such as <samp><span class="file">filename</span></samp> is
+typeset in typewriter type.
+
+ <li>`<samp><var>replaceable</var></samp>'
+Replaceable text such as
+<samp><var>package</var></samp>, identifying a class of things, is typeset in
+italics inside angle brackets.
+
+ </ul>
+
+<div class="node">
+<p><hr>
+<a name="General"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Top_002dlevel-directories">Top-level directories</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Introduction">Introduction</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
+<br>
+</div>
+
+<h2 class="chapter">2 General</h2>
+
+<p>This section describes common properties throughout the TDS tree.
+
+<ul class="menu">
+<li><a accesskey="1" href="#Subdirectory-searching">Subdirectory searching</a>
+<li><a accesskey="2" href="#Rooting-the-tree">Rooting the tree</a>
+<li><a accesskey="3" href="#Local-additions">Local additions</a>
+<li><a accesskey="4" href="#Duplicate-filenames">Duplicate filenames</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="Subdirectory-searching"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Rooting-the-tree">Rooting the tree</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#General">General</a>
+<br>
+</div>
+
+<h3 class="section">2.1 Subdirectory searching</h3>
+
+<p>Older TeX installations store large numbers of related files in single
+directories, for example, all <samp><span class="file">TFM</span></samp> files and/or all TeX
+input files.
+
+ <p>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.
+
+ <p>Therefore, the TWG felt each package should be in a separate
+directory. But we recognized that explicitly listing all directories to
+be searched would be unbearable. A site may wish to install dozens of
+packages. Aside from anything else, listing that many directories would
+produce search paths many thousands of characters long, overflowing the
+available space on some systems.
+
+ <p>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.
+
+ <p>As a result, the TWG concluded that a comprehensive TDS
+requires implementations to support some form of implicit subdirectory
+searching. More precisely, implementations must make it possible to
+specify that TeX, Metafont, and their companion utilities search in both
+a specified directory and recursively through all subdirectories of that
+directory when looking for an input file. Other forms of subdirectory
+searching, for example recursive-to-one-level searches, may also be
+provided. We encourage implementors to provide subdirectory searching
+at the option of the installer and user for all paths.
+
+ <p>The TDS does not specify a syntax for specifying recursive
+searching, but we encourage implementors to provide interoperability
+(see Section&nbsp;<!-- /@w --><a href="#More-on-subdirectory-searching">More on subdirectory searching</a>).
+
+<div class="node">
+<p><hr>
+<a name="Rooting-the-tree"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Local-additions">Local additions</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Subdirectory-searching">Subdirectory searching</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#General">General</a>
+<br>
+</div>
+
+<h3 class="section">2.2 Rooting the tree</h3>
+
+<p>In this document, we shall designate the root TDS directory by
+<samp><span class="file">texmf</span></samp> (for &ldquo;TeX and Metafont&rdquo;). We recommend using that name
+where possible, but the actual name of the directory is up to the
+installer. On PC networks, for example, this could map to a
+logical drive specification such as <samp><span class="file">T:</span></samp>.
+
+ <p>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, <samp><span class="file">/usr/local/share</span></samp>, <samp><span class="file">/usr/local</span></samp>,
+<samp><span class="file">/usr/local/lib</span></samp>, and <samp><span class="file">/opt</span></samp> are common choices.
+
+ <p>The name <samp><span class="file">texmf</span></samp> was chosen for several reasons: it reflects the fact
+that the directory contains files pertaining to an entire TeX system
+(including Metafont, MetaPost, BibTeX, etc.), not just TeX itself; and it
+is descriptive of a generic installation rather than a particular
+implementation.
+
+ <p>A site may choose to have more than one TDS hierarchy installed
+(for example, when installing an upgrade). This is perfectly legitimate.
+
+<div class="node">
+<p><hr>
+<a name="Local-additions"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Duplicate-filenames">Duplicate filenames</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Rooting-the-tree">Rooting the tree</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#General">General</a>
+<br>
+</div>
+
+<h3 class="section">2.3 Local additions</h3>
+
+<p>The TDS cannot specify precisely when a package is or is not a
+&ldquo;local addition&rdquo;. Each site must determine this according to its own
+conventions. At the two extremes, one site might wish to consider
+&ldquo;nonlocal&rdquo; all files not acquired as part of the installed TeX
+distribution; another site might consider &ldquo;local&rdquo; only those files
+that were actually developed at the local site and not distributed
+elsewhere.
+
+ <p>We recognize two common methods for local additions to a distributed
+<samp><span class="file">texmf</span></samp> tree. Both have their place; in fact, some sites employ
+both simultaneously:
+
+ <ol type=1 start=1>
+
+ <li>A completely separate tree which is a TDS structure
+itself; for example, <samp><span class="file">/usr/local/umbtex</span></samp> at the University of
+Massachusetts at Boston. This is another example of the multiple
+<samp><span class="file">texmf</span></samp> hierarchies mentioned in the previous section.
+
+ <li>A directory named <samp><span class="file">local</span></samp> at any appropriate level, for
+example, in the <samp><var>format</var></samp>, <samp><var>package</var></samp>, and
+<samp><var>supplier</var></samp> directories discussed in the following sections.
+The TDS reserves the directory name <samp><span class="file">local</span></samp> for this
+purpose.
+
+ <p>We recommend using <samp><span class="file">local</span></samp> for site-adapted configuration files,
+such as <samp><span class="file">language.dat</span></samp> for the Babel package or <samp><span class="file">graphics.cfg</span></samp>
+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.
+
+ </ol>
+
+ <p>One common case of local additions is dynamically generated files, e.g.,
+PK fonts by the <samp><span class="file">mktexpk</span></samp> script (which originated in
+Dvips as <samp><span class="file">MakeTeXPK</span></samp>). A site may store the
+generated files directly in any of:
+ <ul>
+<li>their standard location in the main TDS tree (if it can be
+made globally writable);
+
+ <li>an alternative location in the main TDS tree (for
+example, under <samp><span class="file">texmf/fonts/tmp</span></samp>);
+
+ <li>a second complete TDS tree (as outlined above);
+
+ <li>any other convenient directory (perhaps under
+<samp><span class="file">/var</span></samp>, for example <samp><span class="file">/var/spool/fonts</span></samp>).
+
+ </ul>
+
+ <p>No one solution will be appropriate for all sites.
+
+<div class="node">
+<p><hr>
+<a name="Duplicate-filenames"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#Local-additions">Local additions</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#General">General</a>
+<br>
+</div>
+
+<h3 class="section">2.4 Duplicate filenames</h3>
+
+<p>Different files by the same name may exist in a TDS tree. The
+TDS generally leaves unspecified which of two files by the same
+name in a search path will be found, so generally the only way to
+reliably find a given file is for it to have a unique name. However,
+the TDS requires implementations to support the following
+exceptions:
+
+ <ul>
+<li>Names of TeX input files must be unique within each first-level
+subdirectory of <samp><span class="file">texmf/tex</span></samp> and <samp><span class="file">texmf/tex/generic</span></samp>, but not
+within all of <samp><span class="file">texmf/tex</span></samp>; i.e., different TeX formats may have
+files by the same name. (Section&nbsp;<!-- /@w --><a href="#Macros">Macros</a> discusses this
+further.) Thus, no single format-independent path specification, such
+as a recursive search beginning at <samp><span class="file">texmf/tex</span></samp> specifying no other
+directories, suffices. So implementations must provide format-dependent
+path specifications, for example via wrapper scripts or configuration
+files.
+
+ <li>Many font files will have the same name (e.g., <samp><span class="file">cmr10.pk</span></samp>),
+as discussed in Section&nbsp;<!-- /@w --><a href="#Valid-font-bitmaps">Valid font bitmaps</a>. Implementations
+must distinguish these files by mode and resolution.
+
+ </ul>
+
+ <p>All implementations we know of already have these capabilities.
+
+ <p>One place where duplicate names are likely to occur is not an exception:
+
+ <ul>
+<li>Names of Metafont input files (as opposed to bitmaps) must be unique
+within all of <samp><span class="file">texmf/fonts</span></samp>. In practice, this is a problem with
+some variants of Computer Modern which contain slightly modified files
+named <samp><span class="file">punct.mf</span></samp>, <samp><span class="file">romanl.mf</span></samp>, and so on. We believe the only
+feasible solution is to rename the derivative files to be
+unique.
+
+ </ul>
+
+<div class="node">
+<p><hr>
+<a name="Top_002dlevel-directories"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Summary">Summary</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#General">General</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
+<br>
+</div>
+
+<h2 class="chapter">3 Top-level directories</h2>
+
+<p>The directories under the <samp><span class="file">texmf</span></samp> root identify the major components of
+a TeX system (see Section&nbsp;<!-- /@w --><a href="#Summary">Summary</a> for a summary). A site
+may omit any unneeded directories.
+
+ <p>Although the TDS by its nature can specify precise locations only
+for implementation-independent files, we recognize that installers may
+well wish to place other files under <samp><span class="file">texmf</span></samp> 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.
+
+ <p>The top-level directories specified by the TDS are:
+
+ <ul>
+<li>`<samp><span class="samp">tex</span></samp>'
+for TeX files (Section&nbsp;<!-- /@w --><a href="#Macros">Macros</a>).
+
+ <li>`<samp><span class="samp">fonts</span></samp>'
+for font-related files (Section&nbsp;<!-- /@w --><a href="#Fonts">Fonts</a>).
+
+ <li>`<samp><span class="samp">metafont</span></samp>'
+for Metafont files which are not fonts (Section&nbsp;<!-- /@w --><a href="#Non_002dfont-Metafont-files">Non-font Metafont files</a>).
+
+ <li>`<samp><span class="samp">metapost</span></samp>'
+for MetaPost files (Section&nbsp;<!-- /@w --><a href="#MetaPost">MetaPost</a>).
+
+ <li>`<samp><span class="samp">bibtex</span></samp>'
+for BibTeX files (Section&nbsp;<!-- /@w --><a href="#BibTeX">BibTeX</a>).
+
+ <li>`<samp><span class="samp">scripts</span></samp>'
+for platform-independent executables (Section&nbsp;<!-- /@w --><a href="#Scripts">Scripts</a>).
+
+ <li>`<samp><span class="samp">doc</span></samp>'
+for user documentation (Section&nbsp;<!-- /@w --><a href="#Documentation">Documentation</a>).
+
+ <li>`<samp><span class="samp">source</span></samp>'
+for sources. This includes both traditional
+program sources (for example, Web2C sources go in
+<samp><span class="file">texmf/source/web2c</span></samp>) and, e.g., LaTeX <samp><span class="file">dtx</span></samp> sources (which
+go in <samp><span class="file">texmf/source/latex</span></samp>). The TDS leaves unspecified any
+structure under <samp><span class="file">source</span></samp>.
+
+ <p><samp><span class="file">source</span></samp> 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, <samp><span class="file">plain.tex</span></samp> does not belong under <samp><span class="file">texmf/source</span></samp>,
+even though it is a &ldquo;source file&rdquo; in the sense of not being derived
+from another file. (It goes in <samp><span class="file">texmf/tex/plain/base</span></samp>, as explained
+in Section&nbsp;<!-- /@w --><a href="#Macros">Macros</a>).
+
+ <li>`<samp><var>implementation</var></samp>'
+for implementations (examples:
+<samp><span class="file">emtex</span></samp>, <samp><span class="file">vtex</span></samp>, <samp><span class="file">web2c</span></samp>), 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 (<samp><span class="file">tex.pool</span></samp>) and memory dump files (<samp><span class="file">plain.fmt</span></samp>) go
+here, in addition to implementation-wide configuration files. See
+Section&nbsp;<!-- /@w --><a href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a> for examples of
+real <samp><var>implementation</var></samp> trees.
+
+ <p>Such implementation-specific configuration files should <em>not</em>
+be located using the main TeX input search path (e.g.,
+<samp><span class="file">TEXINPUTS</span></samp>). This must be reserved for files actually read by a
+TeX engine. See Section&nbsp;<!-- /@w --><a href="#Extensions">Extensions</a>.
+
+ <li>`<samp><var>program</var></samp>'
+for program-specific input and
+configuration files for any TeX-related programs (examples:
+<samp><span class="file">mft</span></samp>, <samp><span class="file">dvips</span></samp>). In fact, the <samp><span class="file">tex</span></samp>, <samp><span class="file">metafont</span></samp>,
+<samp><span class="file">metapost</span></samp>, and <samp><span class="file">bibtex</span></samp> items above may all be seen as
+instances of this case.
+
+ </ul>
+
+<ul class="menu">
+<li><a accesskey="1" href="#Macros">Macros</a>
+<li><a accesskey="2" href="#Fonts">Fonts</a>
+<li><a accesskey="3" href="#Non_002dfont-Metafont-files">Non-font Metafont files</a>
+<li><a accesskey="4" href="#MetaPost">MetaPost</a>
+<li><a accesskey="5" href="#BibTeX">BibTeX</a>
+<li><a accesskey="6" href="#Scripts">Scripts</a>
+<li><a accesskey="7" href="#Documentation">Documentation</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="Macros"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Fonts">Fonts</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+<br>
+</div>
+
+<h3 class="section">3.1 Macros</h3>
+
+<p>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 <samp><span class="file">\dump</span></samp>-able package):
+<pre class="example"> texmf/tex/<var>format</var>/<var>package</var>/
+</pre>
+ <ul>
+<li>`<samp><var>format</var></samp>'
+is a format name (examples: <samp><span class="file">amstex</span></samp>,
+<samp><span class="file">latex</span></samp>, <samp><span class="file">plain</span></samp>, <samp><span class="file">texinfo</span></samp>).
+
+ <p>The TDS allows distributions that can be used as either formats or
+packages (e.g., Texinfo, Eplain) to be stored at either level, at the
+option of the format author or TeX administrator. We recommend that
+packages used as formats at a particular site be stored at the
+<samp><var>format</var></samp> 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.
+
+ <p>The TDS reserves the following <samp><var>format</var></samp> names:
+
+ <ul>
+<li>`<samp><span class="samp">generic</span></samp>',
+for input files that are useful across a wide
+range of formats (examples: <samp><span class="file">null.tex</span></samp>, <samp><span class="file">path.sty</span></samp>).
+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
+<samp><span class="file">texmf/tex/plain</span></samp>), e.g., <samp><span class="file">testfont.tex</span></samp> and <samp><span class="file">plain.tex</span></samp>
+itself.
+
+ <li>`<samp><span class="samp">local</span></samp>',
+for local additions. See Section&nbsp;<!-- /@w --><a href="#Local-additions">Local additions</a>.
+
+ </ul>
+
+ <p>Thus, for almost every format, it is necessary to search at least the
+<samp><var>format</var></samp> directory and then the <samp><span class="file">generic</span></samp> directory (in
+that order). Other directories may need to be searched as well,
+depending on the format. When using AMS-TeX, for example, the
+<samp><span class="file">amstex</span></samp>, <samp><span class="file">plain</span></samp>, and <samp><span class="file">generic</span></samp> directories should be
+searched, because AMS-TeX is compatible with Plain.
+
+ <li>`<samp><var>package</var></samp>'
+is a TeX package name (examples:
+<samp><span class="file">babel</span></samp>, <samp><span class="file">texdraw</span></samp>).
+
+ <p>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
+<samp><var>format</var></samp> directory, instead of
+<samp><var>format</var><span class="file">/base</span></samp>. For example, Texinfo may go in
+<samp><span class="file">texmf/tex/texinfo/texinfo.tex</span></samp>, not
+<samp><span class="file">texmf/tex/texinfo/base/texinfo.tex</span></samp>.
+
+ <p>The TDS reserves the following <samp><var>package</var></samp> names:
+
+ <ul>
+<li>`<samp><span class="samp">base</span></samp>',
+for the base distribution of each format,
+including files used by INITEX when dumping format files. For
+example, in the standard LaTeX distribution, the <samp><span class="file">ltx</span></samp> files
+created during the build process. Another example: the <samp><span class="file">.ini</span></samp>
+driver files for formats used by TeX Live and other distributions.
+
+ <li>`<samp><span class="samp">hyphen</span></samp>',
+for hyphenation patterns, including the original
+American English <samp><span class="file">hyphen.tex</span></samp>. These are typically used only by
+INITEX. In most situations, this directory need exist only under the
+<samp><span class="file">generic</span></samp> format.
+
+ <li>`<samp><span class="samp">images</span></samp>',
+for image input files, such as Encapsulated
+PostScript figures. Although it is somewhat non-intuitive for these to
+be under a directory named <samp><span class="file">tex</span></samp>, TeX needs to read these
+files to glean bounding box or other information. A mechanism for
+sharing image inputs between TeX and other typesetting programs
+(e.g., Interleaf, FrameMaker) is beyond the scope of the
+TDS. In most situations, this directory need exist only under
+the <samp><span class="file">generic</span></samp> format.
+
+ <li>`<samp><span class="samp">local</span></samp>',
+for local additions and configuration files. See
+Section&nbsp;<!-- /@w --><a href="#Local-additions">Local additions</a>.
+
+ <li>`<samp><span class="samp">misc</span></samp>',
+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 <samp><span class="file">misc</span></samp>.
+
+ </ul>
+
+ </ul>
+
+<ul class="menu">
+<li><a accesskey="1" href="#Extensions">Extensions</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="Extensions"></a>Up:&nbsp;<a rel="up" accesskey="u" href="#Macros">Macros</a>
+<br>
+</div>
+
+<h4 class="subsection">3.1.1 Extensions</h4>
+
+<p>TeX has spawned many companion and successor programs (&ldquo;engines&rdquo;),
+such as PDFTeX, Omega, and others. The TDS specifies
+that the input files for such programs (using a TeX-like syntax) be
+placed within the top-level <samp><span class="file">tex</span></samp> 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:
+
+<pre class="example"> texmf/tex/aleph
+ texmf/tex/enctex
+</pre>
+ <p>This is a change from TDS&nbsp;<!-- /@w -->1.0, which specified top-level
+<samp><var>extension</var></samp> directories for each such program. We felt the
+new approach is preferable, because:
+
+ <ul>
+<li>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 <samp><span class="file">tex</span></samp> directory provides a stable location over
+time.
+
+ <li>Users need to be able to switch between engines, and configuring
+different search paths for each engine is difficult and error-prone.
+
+ </ul>
+
+ <p>Thus, in practice, having different top-level directories caused
+difficulties for everyone involved&mdash;users, package authors, site
+administrators, and system distributors.
+
+ <p>Please contrast this approach with the <samp><var>implementation</var></samp>
+top-level subdirectory (Section&nbsp;<!-- /@w --><a href="#Top_002dlevel-directories">Top-level directories</a>), 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.
+
+<div class="node">
+<p><hr>
+<a name="Fonts"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Non_002dfont-Metafont-files">Non-font Metafont files</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Macros">Macros</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+<br>
+</div>
+
+<h3 class="section">3.2 Fonts</h3>
+
+<p>Font files are stored in separate directories, segregated by file type,
+and then (in most cases) font supplier and typeface. PK and
+GF files need additional structure, as detailed in the next
+section.
+
+<pre class="example"> texmf/fonts/<var>type</var>/<var>supplier</var>/<var>typeface</var>/
+ texmf/fonts/enc,lig,map/<var>subpath</var>/
+</pre>
+ <ul>
+<li>`<samp><var>type</var></samp>'
+is the type of font file. The TDS
+reserves the following <samp><var>type</var></samp> names for common TeX file
+types:
+
+ <ul>
+<li>`<samp><span class="samp">afm</span></samp>',
+for Adobe font metrics, and <samp><span class="file">inf</span></samp> files.
+<li>`<samp><span class="samp">gf</span></samp>',
+for generic font bitmap files.
+<li>`<samp><span class="samp">opentype</span></samp>',
+for OpenType fonts.
+<li>`<samp><span class="samp">pk</span></samp>',
+for packed bitmap files.
+<li>`<samp><span class="samp">source</span></samp>',
+for font sources (Metafont files, property lists, etc.).
+<li>`<samp><span class="samp">tfm</span></samp>',
+for TeX font metric files.
+<li>`<samp><span class="samp">truetype</span></samp>',
+for TrueType fonts.
+<li>`<samp><span class="samp">type1</span></samp>',
+for PostScript Type 1 fonts (in <samp><span class="file">pfa</span></samp>,
+ <samp><span class="file">pfb</span></samp>, or any other format), and <samp><span class="file">pfm</span></samp> files.
+<li>`<samp><span class="samp">type3</span></samp>',
+for PostScript Type 3 fonts.
+<li>`<samp><span class="samp">vf</span></samp>',
+for virtual fonts.
+</ul>
+
+ <p>The TDS also reserves the names <samp><span class="file">enc</span></samp>, <samp><span class="file">lig</span></samp>, and
+<samp><span class="file">map</span></samp> for font encoding, ligature, and mapping files, respectively.
+All of these directories are structured the same way, with
+<samp><var>syntax</var></samp> subdirectories, and then <samp><var>package</var></samp>
+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:
+ <pre class="example"> fonts/map/dvipdfm/updmap/dvipdfm.map
+ fonts/map/dvips/lm/lm.map
+ fonts/enc/dvips/base/8r.enc
+ </pre>
+ <p>The Fontname and Dvips packages have more examples of the <samp><span class="file">enc</span></samp> and
+<samp><span class="file">map</span></samp> types. The <samp><span class="file">afm2pl</span></samp> program uses <samp><span class="file">lig</span></samp> files.
+
+ <p><samp><span class="file">pfm</span></samp> files are included in the <samp><span class="file">type1</span></samp> directory, instead of
+being given their own directory, for two reasons: 1)&nbsp;<!-- /@w -->a <samp><span class="file">.pfm</span></samp> file
+is always an adjunct to a given <samp><span class="file">.pfb</span></samp> file; 2)&nbsp;<!-- /@w -->they must be
+installed from the same directory for Windows programs other than TeX
+to use them.
+
+ <p><samp><span class="file">inf</span></samp> files are included in the <samp><span class="file">afm</span></samp> directory, since
+an <samp><span class="file">inf</span></samp> and <samp><span class="file">afm</span></samp> file can be used to generate a <samp><span class="file">pfm</span></samp>.
+(Unfortunately, Adobe Type Manager and perhaps other software requires
+that the <samp><span class="file">pfb</span></samp> be in the same directory as <samp><span class="file">afm</span></samp> and
+<samp><span class="file">inf</span></samp> for installation.)
+
+ <p>As usual, a site may omit any of these directories that are unnecessary.
+<samp><span class="file">gf</span></samp> is a particularly likely candidate for omission.
+
+ <li>`<samp><var>supplier</var></samp>'
+is a name identifying font source
+(examples: <samp><span class="file">adobe</span></samp>, <samp><span class="file">ams</span></samp>, <samp><span class="file">public</span></samp>). The TDS
+reserves the following <samp><var>supplier</var></samp> names:
+
+ <ul>
+<li>`<samp><span class="samp">ams</span></samp>',
+for the American Mathematical Society's AMS-fonts
+collection.
+
+ <li>`<samp><span class="samp">local</span></samp>',
+for local additions. See Section&nbsp;<!-- /@w --><a href="#Local-additions">Local additions</a>.
+
+ <li>`<samp><span class="samp">public</span></samp>',
+for freely redistributable fonts where the supplier
+neither (1)&nbsp;<!-- /@w -->requested their own directory (e.g., <samp><span class="file">ams</span></samp>), nor
+(2)&nbsp;<!-- /@w -->also made proprietary fonts (e.g., <samp><span class="file">adobe</span></samp>). It does not
+contain all extant freely distributable fonts, nor are all files therein
+necessarily strictly public domain.
+
+ <li>`<samp><span class="samp">tmp</span></samp>',
+for dynamically-generated fonts, as is traditional on
+some systems. It may be omitted if unnecessary, as usual.
+
+ </ul>
+
+ <li>`<samp><var>typeface</var></samp>'
+is the name of a typeface family
+(examples: <samp><span class="file">cm</span></samp>, <samp><span class="file">euler</span></samp>, <samp><span class="file">times</span></samp>). The TDS
+reserves the following <samp><var>typeface</var></samp> names:
+
+ <ul>
+<li>`<samp><span class="samp">cm</span></samp>' (within <samp><span class="file">public</span></samp>),
+for the 75 fonts defined in
+<cite>Computers and Typesetting, Volume&nbsp;<!-- /@w -->E</cite>.
+
+ <li>`<samp><span class="samp">latex</span></samp>' (within <samp><span class="file">public</span></samp>),
+for those fonts distributed
+with LaTeX in the base distribution.
+
+ <li>`<samp><span class="samp">local</span></samp>',
+for local additions. See Section&nbsp;<!-- /@w --><a href="#Local-additions">Local additions</a>.
+
+ </ul>
+
+ </ul>
+
+ <p>Some concrete examples:
+<pre class="example"> texmf/fonts/source/public/pandora/pnr10.mf
+ texmf/fonts/tfm/public/cm/cmr10.tfm
+ texmf/fonts/type1/adobe/utopia/putr.pfa
+</pre>
+ <p>For complete supplier and typeface name lists, consult
+<cite>Filenames for TeX fonts</cite> (see Appendix&nbsp;<!-- /@w --><a href="#Related-references">Related references</a>).
+
+<ul class="menu">
+<li><a accesskey="1" href="#Font-bitmaps">Font bitmaps</a>
+<li><a accesskey="2" href="#Valid-font-bitmaps">Valid font bitmaps</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="Font-bitmaps"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Valid-font-bitmaps">Valid font bitmaps</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Fonts">Fonts</a>
+<br>
+</div>
+
+<h4 class="subsection">3.2.1 Font bitmaps</h4>
+
+<p>Font bitmap files require two characteristics in addition to the above
+to be uniquely identifiable: (1)&nbsp;<!-- /@w -->the type of device (i.e., mode) for
+which the font was created; (2)&nbsp;<!-- /@w -->the resolution of the bitmap.
+
+ <p>Following common practice, the TDS segregates fonts with
+different device types into separate directories. See <samp><span class="file">modes.mf</span></samp>
+in Appendix&nbsp;<!-- /@w --><a href="#Related-references">Related references</a> for recommended mode names.
+
+ <p>Some printers operate at more than one resolution (e.g., at 300<span class="dmn">dpi</span> and
+600<span class="dmn">dpi</span>), 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.
+
+ <p>Two naming strategies are commonly used to identify the resolution of
+bitmap font files. On systems that allow long filenames (and in the
+original Metafont program itself), the resolution is included in the
+filename (e.g., <samp><span class="file">cmr10.300pk</span></samp>). On systems which do not support
+long filenames, fonts are generally segregated into directories by
+resolution (e.g., <samp><span class="file">dpi300/cmr10.pk</span></samp>).
+
+ <p>Because the TDS cannot require long filenames, we must use the
+latter scheme for naming fonts. So we have two more subdirectory
+levels under <samp><span class="file">pk</span></samp> and <samp><span class="file">gf</span></samp>:
+
+<pre class="example"> texmf/fonts/pk/<var>mode</var>/<var>supplier</var>/<var>typeface</var>/dpi<var>nnn</var>/
+ texmf/fonts/gf/<var>mode</var>/<var>supplier</var>/<var>typeface</var>/dpi<var>nnn</var>/
+</pre>
+ <ul>
+<li>`<samp><var>mode</var></samp>'
+is a name which identifies the device type
+(examples: <samp><span class="file">cx</span></samp>, <samp><span class="file">ljfour</span></samp>, <samp><span class="file">modeless</span></samp>). Usually, this is
+the name of the Metafont mode used to build the PK file. For fonts
+rendered as bitmaps by a program that does not distinguish between
+different output devices, the <samp><var>mode</var></samp> name shall be simply
+<samp><span class="file">modeless</span></samp>. The <samp><var>mode</var></samp> level shall not be omitted,
+even if only a single mode happens to be in use.
+
+ <li>`<samp><span class="samp">dpi</span><var>nnn</var></samp>'
+specifies the resolution of the font
+(examples: <samp><span class="file">dpi300</span></samp>, <samp><span class="file">dpi329</span></samp>). <samp><span class="file">dpi</span></samp> 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.
+
+ <p>The integer <samp><var>nnn</var></samp> is to be calculated as if using Metafont
+arithmetic and then rounded; i.e., it is the integer Metafont uses in its
+output <samp><span class="file">gf</span></samp> filename. We recognize small differences in the
+resolution are a common cause of frustration among users, however, and
+recommend implementors follow the level&nbsp;<!-- /@w -->0 DVI driver standard
+(see Appendix&nbsp;<!-- /@w --><a href="#Related-references">Related references</a>) in bitmap font searches by
+allowing a fuzz of +-0.2% (with a minimum of 1) in the
+<samp><var>dpi</var></samp>.
+
+ </ul>
+
+ <p>Implementations may provide extensions to the basic naming scheme, such
+as long filenames (as in the original Metafont) and font library files (as
+in emTeX's <samp><span class="file">.fli</span></samp> files), provided that the basic scheme is also
+supported.
+
+<div class="node">
+<p><hr>
+<a name="Valid-font-bitmaps"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#Font-bitmaps">Font bitmaps</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Fonts">Fonts</a>
+<br>
+</div>
+
+<h4 class="subsection">3.2.2 Valid font bitmaps</h4>
+
+<p>The TWG recognizes that the use of short filenames has many
+disadvantages. The most vexing is that it results in the creation of
+dozens of different files with the same name. At a typical site,
+<samp><span class="file">cmr10.pk</span></samp> will be the filename for Computer Modern Roman 10<span class="dmn">pt</span> at
+5&ndash;10 magnifications for 2&ndash;3 modes. (Section&nbsp;<!-- /@w --><a href="#Duplicate-filenames">Duplicate filenames</a> discusses duplicate filenames in general.)
+
+ <p>To minimize this problem, we strongly recommend that PK files
+contain enough information to identify precisely how they were created:
+at least the mode, base resolution, and magnification used to create the
+font.
+
+ <p>This information is easy to supply: a simple addition to the local modes
+used for building the fonts with Metafont will automatically provide the
+required information. If you have been using a local modes file derived
+from (or that is simply) <samp><span class="file">modes.mf</span></samp> (see Appendix&nbsp;<!-- /@w --><a href="#Related-references">Related references</a>), the required information is already in your PK
+files. If not, a simple addition based on the code found in
+<samp><span class="file">modes.mf</span></samp> can be made to your local modes file and the PK
+files rebuilt.
+
+<div class="node">
+<p><hr>
+<a name="Non_002dfont-Metafont-files"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#MetaPost">MetaPost</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Fonts">Fonts</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+<br>
+</div>
+
+<h3 class="section">3.3 Non-font Metafont files</h3>
+
+<p>Most Metafont input files are font programs or parts of font programs and
+are thus covered by the previous section. However, a few non-font input
+files do exist. Such files shall be stored in:
+
+<pre class="example"> texmf/metafont/<var>package</var>/
+</pre>
+ <p><samp><var>package</var></samp> is the name of a
+Metafont package (for example, <samp><span class="file">mfpic</span></samp>).
+
+ <p>The TDS reserves the following <samp><var>package</var></samp> names:
+
+ <ul>
+<li>`<samp><span class="samp">base</span></samp>',
+for the standard Metafont macro files as described in
+<cite>The Metafontbook</cite>, such as <samp><span class="file">plain.mf</span></samp> and <samp><span class="file">expr.mf</span></samp>.
+
+ <li>`<samp><span class="samp">local</span></samp>',
+for local additions. See Section&nbsp;<!-- /@w --><a href="#Local-additions">Local additions</a>.
+
+ <li>`<samp><span class="samp">misc</span></samp>',
+for Metafont packages consisting of only a single file
+(for example, <samp><span class="file">modes.mf</span></samp>). An administrator or package maintainer
+may create directories for single-file packages at their discretion,
+instead of using <samp><span class="file">misc</span></samp>.
+
+ </ul>
+
+<div class="node">
+<p><hr>
+<a name="MetaPost"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#BibTeX">BibTeX</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Non_002dfont-Metafont-files">Non-font Metafont files</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+<br>
+</div>
+
+<h3 class="section">3.4 MetaPost</h3>
+
+<p>MetaPost is a picture-drawing language developed by John Hobby, derived
+from Knuth's Metafont. Its primary purpose is to output Encapsulated PostScript
+instead of bitmaps.
+
+ <p>MetaPost input files and the support files for MetaPost-related utilities
+shall be stored in:
+
+<pre class="example"> texmf/metapost/<var>package</var>/
+</pre>
+ <p><samp><var>package</var></samp> is the name of a MetaPost package. At the present
+writing none exist, but the TWG thought it prudent to leave room
+for contributed packages that might be written in the future.
+
+ <p>The TDS reserves the following <samp><var>package</var></samp> names:
+
+ <ul>
+<li>`<samp><span class="samp">base</span></samp>',
+for the standard MetaPost macro files, such as
+<samp><span class="file">plain.mp</span></samp>, <samp><span class="file">mfplain.mp</span></samp>, <samp><span class="file">boxes.mp</span></samp>, and
+<samp><span class="file">graph.mp</span></samp>. This includes files used by INIMP when dumping mem
+files containing preloaded macro definitions.
+
+ <li>`<samp><span class="samp">local</span></samp>',
+for local additions. See Section&nbsp;<!-- /@w --><a href="#Local-additions">Local additions</a>.
+
+ <li>`<samp><span class="samp">misc</span></samp>',
+for MetaPost 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 <samp><span class="file">misc</span></samp>.
+
+ <li>`<samp><span class="samp">support</span></samp>',
+for additional input files required by MetaPost
+utility programs, including a font map, a character adjustment table,
+and a subdirectory containing low-level MetaPost programs for rendering
+some special characters.
+
+ </ul>
+
+<div class="node">
+<p><hr>
+<a name="BibTeX"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Scripts">Scripts</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#MetaPost">MetaPost</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+<br>
+</div>
+
+<h3 class="section">3.5 BibTeX</h3>
+
+<p>BibTeX-related files shall be stored in:
+
+<pre class="example"> texmf/bibtex/bib/<var>package</var>/
+ texmf/bibtex/bst/<var>package</var>/
+</pre>
+ <p>The <samp><span class="file">bib</span></samp> directory is for BibTeX database (<samp><span class="file">.bib</span></samp>) files,
+the <samp><span class="file">bst</span></samp> directory for style (<samp><span class="file">.bst</span></samp>) files.
+
+ <p><samp><var>package</var></samp> is the name of a BibTeX package. The
+TDS reserves the following <samp><var>package</var></samp> names (the same
+names are reserved under both <samp><span class="file">bib</span></samp> and <samp><span class="file">bst</span></samp>):
+
+ <ul>
+<li>`<samp><span class="samp">base</span></samp>',
+for the standard BibTeX databases and styles, such
+as <samp><span class="file">xampl.bib</span></samp>, <samp><span class="file">plain.bst</span></samp>.
+
+ <li>`<samp><span class="samp">local</span></samp>',
+for local additions. See Section&nbsp;<!-- /@w --><a href="#Local-additions">Local additions</a>.
+
+ <li>`<samp><span class="samp">misc</span></samp>',
+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 <samp><span class="file">misc</span></samp>.
+
+ </ul>
+
+<div class="node">
+<p><hr>
+<a name="Scripts"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Documentation">Documentation</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#BibTeX">BibTeX</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+<br>
+</div>
+
+<h3 class="section">3.6 Scripts</h3>
+
+<p>The top-level <samp><span class="file">scripts</span></samp> directory is for platform-independent
+executables, such as Perl, Python, and shell scripts, and Java class
+files. Subdirectories under <samp><span class="file">scripts</span></samp> are package names. This
+eases creating distributions, by providing a common place for such
+platform-independent programs.
+
+ <p>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 TDS).
+
+ <p>Truly auxiliary scripts which are invoked directly by other programs,
+rather than wrapper scripts, may also be placed here. That is,
+<samp><span class="file">scripts</span></samp> also serves as a platform-independent analog of the
+standard Unix <samp><span class="file">libexec</span></samp> directory.
+
+ <p>We recommend using extensions specifying the language (such as
+<samp><span class="file">.pl</span></samp>, <samp><span class="file">.py</span></samp>, <samp><span class="file">.sh</span></samp>) on these files, to help uniquely
+identify the name. Since the intent of the TDS is for programs
+in <samp><span class="file">scripts</span></samp> not to be invoked directly by users, this poses no
+inconvenience.
+
+ <p>For example, in the TeX Live distribution, the ConTeXt user-level
+program <samp><span class="file">texexec</span></samp> can exist as a small wrapper script in each
+<samp><span class="file">bin/</span><var>platform</var><span class="file">/texexec</span></samp> (which is outside the
+<samp><span class="file">texmf</span></samp> tree), which merely finds and calls
+<samp><span class="file">texmf/scripts/context/perl/texexec.pl</span></samp>.
+
+ <p>Examples:
+<pre class="example"> scripts/context/perl/texexec.pl
+ scripts/context/ruby/examplex.rb
+ scripts/thumbpdf/thumbpdf.pl
+</pre>
+ <p>The TDS does not specify a location for platform-dependent
+binary executables, whether auxiliary or user-level.
+
+<div class="node">
+<p><hr>
+<a name="Documentation"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#Scripts">Scripts</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+<br>
+</div>
+
+<h3 class="section">3.7 Documentation</h3>
+
+<p>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.
+
+ <p>The TDS specifies that these additional documentation files shall
+be stored in a structure that parallels to some extent the
+<samp><span class="file">fonts</span></samp> and <samp><span class="file">tex</span></samp> directories, as follows:
+
+<pre class="example"> texmf/doc/<var>category</var>/...
+</pre>
+ <p><samp><var>category</var></samp> identifies the general topic of documentation
+that resides below it; for example, a TeX format name (<samp><span class="file">latex</span></samp>),
+program name (<samp><span class="file">bibtex</span></samp>, <samp><span class="file">tex</span></samp>), language (<samp><span class="file">french</span></samp>,
+<samp><span class="file">german</span></samp>), a file format (<samp><span class="file">info</span></samp>, <samp><span class="file">man</span></samp>), or other system
+components (<samp><span class="file">web</span></samp>, <samp><span class="file">fonts</span></samp>).
+
+ <p>One possible arrangement is to organize <samp><span class="file">doc</span></samp> 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.
+
+ <p>Within each <samp><var>category</var></samp> tree for a TeX format, the
+directory <samp><span class="file">base</span></samp> is reserved for base documentation distributed by
+the format's maintainers.
+
+ <p>The TDS reserves the following category names:
+
+ <ul>
+<li>`<samp><span class="samp">general</span></samp>',
+for standalone documents not specific to any
+particular program (for example, Joachim Schrod's <cite>Components
+of TeX</cite>).
+
+ <li>`<samp><span class="samp">help</span></samp>',
+for meta-information, such as FAQ's,
+the TeX Catalogue, etc.
+
+ <li>`<samp><span class="samp">info</span></samp>',
+for processed Texinfo documents. (Info files, like
+anything else, may also be stored outside the TDS, at the
+installer's option.)
+
+ <li>`<samp><span class="samp">local</span></samp>',
+for local additions. See Section&nbsp;<!-- /@w --><a href="#Local-additions">Local additions</a>.
+
+ </ul>
+
+ <p>The <samp><span class="file">doc</span></samp> 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, VMS help files under <samp><span class="file">texmf/vms/help</span></samp>).
+
+ <p>The documentation directories may contain TeX sources, DVI
+files, PostScript files, text files, example input files, or any other useful
+documentation format(s).
+
+ <p>See Section&nbsp;<!-- /@w --><a href="#Documentation-tree-summary">Documentation tree summary</a> for a summary.
+
+<div class="node">
+<p><hr>
+<a name="Summary"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Unspecified-pieces">Unspecified pieces</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Top_002dlevel-directories">Top-level directories</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
+<br>
+</div>
+
+<h2 class="chapter">4 Summary</h2>
+
+<p>A skeleton of a TDS <samp><span class="file">texmf</span></samp> directory tree. This is not to
+imply these are the only entries allowed. For example, <samp><span class="file">local</span></samp> may
+occur at any level.
+
+<pre class="example"> bibtex/ BibTeX input files
+ bib/ BibTeX databases
+ base/ base distribution (e.g., <samp><span class="file">xampl.bib</span></samp>)
+ misc/ single-file databases
+ &lt;package&gt;/ name of a package
+ bst/ BibTeX style files
+ base/ base distribution (e.g., <samp><span class="file">plain.bst</span></samp>, <samp><span class="file">acm.bst</span></samp>)
+ misc/ single-file styles
+ &lt;package&gt;/ name of a package
+ doc/ see Section&nbsp;<!-- /@w --><a href="#Documentation">Documentation</a> and the summary below
+ fonts/ font-related files
+ &lt;type&gt;/ file type (e.g., <samp><span class="file">pk</span></samp>)
+ &lt;mode&gt;/ type of output device (for <samp><span class="file">pk</span></samp> and <samp><span class="file">gf</span></samp> only)
+ &lt;supplier&gt;/ name of a font supplier (e.g., <samp><span class="file">public</span></samp>)
+ &lt;typeface&gt;/ name of a typeface (e.g., <samp><span class="file">cm</span></samp>)
+ dpi&lt;nnn&gt;/ font resolution (for <samp><span class="file">pk</span></samp> and <samp><span class="file">gf</span></samp> only)
+ &lt;implementation&gt;/ TeX implementations, by name (e.g., <samp><span class="file">emtex</span></samp>)
+ local/ files created or modified at the local site
+ metafont/ Metafont (non-font) input files
+ base/ base distribution (e.g., <samp><span class="file">plain.mf</span></samp>)
+ misc/ single-file packages (e.g., <samp><span class="file">modes.mf</span></samp>)
+ &lt;package&gt;/ name of a package (e.g., <samp><span class="file">mfpic</span></samp>)
+ metapost/ MetaPost input and support files
+ base/ base distribution (e.g., <samp><span class="file">plain.mp</span></samp>)
+ misc/ single-file packages
+ &lt;package&gt;/ name of a package
+ support/ support files for MetaPost-related utilities
+ mft/ <samp><span class="file">MFT</span></samp> inputs (e.g., <samp><span class="file">plain.mft</span></samp>)
+ &lt;program&gt;/ TeX-related programs, by name (e.g., <samp><span class="file">dvips</span></samp>)
+ source/ program source code by name (e.g., <samp><span class="file">latex</span></samp>, <samp><span class="file">web2c</span></samp>)
+ tex/ TeX input files
+ &lt;engine&gt;/ name of an engine (e.g., <samp><span class="file">aleph</span></samp>); can also be lower
+ &lt;format&gt;/ name of a format (e.g., <samp><span class="file">plain</span></samp>)
+ base/ base distribution for format (e.g., <samp><span class="file">plain.tex</span></samp>)
+ misc/ single-file packages (e.g., <samp><span class="file">webmac.tex</span></samp>)
+ local/ local additions to or local configuration files for <samp><var>format</var></samp>
+ &lt;package&gt;/ name of a package (e.g., <samp><span class="file">graphics</span></samp>, <samp><span class="file">mfnfss</span></samp>)
+ generic/ format-independent packages
+ hyphen/ hyphenation patterns (e.g., <samp><span class="file">hyphen.tex</span></samp>)
+ images/ image input files (e.g., Encapsulated PostScript)
+ misc/ single-file format-independent packages (e.g., <samp><span class="file">null.tex</span></samp>).
+ &lt;package&gt;/ name of a package (e.g., <samp><span class="file">babel</span></samp>)
+</pre>
+ <ul class="menu">
+<li><a accesskey="1" href="#Documentation-tree-summary">Documentation tree summary</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="Documentation-tree-summary"></a>Up:&nbsp;<a rel="up" accesskey="u" href="#Summary">Summary</a>
+<br>
+</div>
+
+<h3 class="section">4.1 Documentation tree summary</h3>
+
+<p>An example skeleton of a TDS directory tree under
+<samp><span class="file">texmf/doc</span></samp>. This is not to imply these are the only entries
+allowed, or that this structure must be followed precisely for the
+entries listed.
+
+ <p>As mentioned, the <samp><span class="file">texmf/doc</span></samp> tree may be organized by language, so
+that all documentation in French, say, is in a <samp><span class="file">french</span></samp>
+subdirectory. In that case, the example structure here would be in a
+given language directory.
+
+<pre class="example"> ams/
+ amsfonts/ <samp><span class="file">amsfonts.faq</span></samp>, <samp><span class="file">amfndoc</span></samp>
+ amslatex/ <samp><span class="file">amslatex.faq</span></samp>, <samp><span class="file">amsldoc</span></samp>
+ amstex/ <samp><span class="file">amsguide</span></samp>, <samp><span class="file">joyerr</span></samp>
+ bibtex/ BibTeX
+ base/ <samp><span class="file">btxdoc.tex</span></samp>
+ fonts/
+ fontname/ <cite>Filenames for TeX fonts</cite>
+ oldgerm/ <samp><span class="file">corkpapr</span></samp>
+ &lt;format&gt;/ name of a TeX format (e.g., <samp><span class="file">generic</span></samp>, <samp><span class="file">latex</span></samp>)
+ base/ for the base distribution
+ misc/ for contributed single-file package documentation
+ &lt;package&gt;/ for <em>package</em>
+ general/ across programs, generalities
+ errata/ <samp><span class="file">errata</span></samp>, <samp><span class="file">errata[1-8]</span></samp>
+ texcomp/ <cite>Components of TeX</cite>
+ help/ meta-information
+ ctan/ info about CTAN mirror sites
+ faq/ FAQs of <samp><span class="file">comp.text.tex</span></samp>, etc.
+ info/ GNU Info files, made from Texinfo sources
+ latex/ example of <samp><var>format</var></samp>
+ base/ <samp><span class="file">ltnews*</span></samp>, <samp><span class="file">*guide</span></samp>, etc.
+ graphics/ <samp><span class="file">grfguide</span></samp>
+ local/ site-specific documentation
+ man/ Unix man pages
+ &lt;program&gt;/ TeX-related programs, by name (examples follow)
+ metafont/ <samp><span class="file">mfbook.tex</span></samp>, <samp><span class="file">metafont-for-beginners</span></samp>, etc.
+ metapost/ <samp><span class="file">mpman</span></samp>, <samp><span class="file">manfig</span></samp>, etc.
+ tex/ <samp><span class="file">texbook.tex</span></samp>, <cite>A Gentle Introduction to TeX</cite>, etc.
+ web/ <samp><span class="file">webman</span></samp>, <samp><span class="file">cwebman</span></samp>
+</pre>
+ <div class="node">
+<p><hr>
+<a name="Unspecified-pieces"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Implementation-issues">Implementation issues</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Summary">Summary</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
+<br>
+</div>
+
+<h2 class="appendix">Appendix A Unspecified pieces</h2>
+
+<p>The TDS cannot address the following aspects of a functioning
+TeX system:
+
+ <ol type=1 start=1>
+
+ <li>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 <samp><span class="file">texmf</span></samp> tree altogether (e.g.,
+<samp><span class="file">/usr/local/bin</span></samp>), in a platform-dependent directory within
+<samp><span class="file">texmf</span></samp>, or elsewhere.
+
+ <li>Upgrading packages when new releases are made: we could find no
+way of introducing version specifiers into <samp><span class="file">texmf</span></samp> that would do more
+good than harm, or that would be practical for even a plurality of
+installations.
+
+ <li>The location of implementation-specific files (e.g., TeX
+<samp><span class="file">.fmt</span></samp> files): by their nature, these must be left to the
+implementor or TeX maintainer. See Section&nbsp;<!-- /@w --><a href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>.
+
+ <li>Precisely when a package or file should be considered &ldquo;local&rdquo;,
+and where such local files are installed. See Section&nbsp;<!-- /@w --><a href="#Local-additions">Local additions</a> for more discussion.
+
+ </ol>
+
+<ul class="menu">
+<li><a accesskey="1" href="#Portable-filenames">Portable filenames</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="Portable-filenames"></a>Up:&nbsp;<a rel="up" accesskey="u" href="#Unspecified-pieces">Unspecified pieces</a>
+<br>
+</div>
+
+<h3 class="section">A.1 Portable filenames</h3>
+
+<p>The 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 TDS specifications themselves are
+compatible with these.
+
+ <p>ISO-9660 is the only universally acceptable file system format
+for CD-ROMs. A subset thereof meets the stringent limitations of
+all operating systems in use today. It specifies the following:
+
+ <ul>
+<li>File and directory names, not including any directory path or
+extension part, may not exceed eight characters.
+
+ <li>Filenames may have a single extension. Extensions may not exceed
+three characters. Directory names may not have an extension.
+
+ <li>Names and extensions may consist of <em>only</em> the characters
+<samp><span class="file">A</span></samp>&ndash;<samp><span class="file">Z</span></samp>, <samp><span class="file">0</span></samp>&ndash;<samp><span class="file">9</span></samp>, and underscore.
+Lowercase letters are excluded.
+
+ <li>A period separates the filename from the extension and is always
+present, even if the name or extension is missing (e.g.,
+<samp><span class="file">FILENAME.</span></samp> or <samp><span class="file">.EXT</span></samp>).
+
+ <li>A version number, ranging from 1&ndash;32767, is appended to the file
+extension, separated by a semicolon (e.g., <samp><span class="file">FILENAME.EXT;1</span></samp>).
+
+ <li>Only eight directory levels are allowed, including the top-level
+(mounted) directory (see Section&nbsp;<!-- /@w --><a href="#Rooting-the-tree">Rooting the tree</a>). Thus, the
+deepest valid ISO-9660 path is:
+ <pre class="example"> texmf/L2/L3/L4/L5/L6/L7/L8/FOO.BAR;1
+ 1 2 3 4 5 6 7 8
+ </pre>
+ <p>The deepest TDS path needs only seven levels:
+ <pre class="example"> texmf/fonts/pk/cx/public/cm/dpi300/cmr10.pk
+ 1 2 3 4 5 6 7
+ </pre>
+ </ul>
+
+ <p>Some systems display a modified format of ISO-9660 names,
+mapping alphabetic characters to lowercase, removing version numbers and
+trailing periods, etc.
+
+ <p>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.
+
+<div class="node">
+<p><hr>
+<a name="Implementation-issues"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Is-there-a-better-way_003f">Is there a better way?</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Unspecified-pieces">Unspecified pieces</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
+<br>
+</div>
+
+<h2 class="appendix">Appendix B Implementation issues</h2>
+
+<p>We believe that the 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 &ldquo;drop-in&rdquo; distribution packages for
+TeX.
+
+<ul class="menu">
+<li><a accesskey="1" href="#Adoption-of-the-TDS">Adoption of the TDS</a>
+<li><a accesskey="2" href="#More-on-subdirectory-searching">More on subdirectory searching</a>
+<li><a accesskey="3" href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="Adoption-of-the-TDS"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#More-on-subdirectory-searching">More on subdirectory searching</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Implementation-issues">Implementation issues</a>
+<br>
+</div>
+
+<h3 class="section">B.1 Adoption of the TDS</h3>
+
+<p>[This section is retained for historical purposes; the TDS
+is now quite firmly entrenched in most TeX distributions.]
+
+ <p>We recognize that adoption of the TDS will not be immediate or
+universal. Most TeX administrators will not be inclined to make the
+final switch until:
+
+ <ul>
+<li>Clear and demonstrable benefits can be shown for the TDS.
+<li>TDS-compliant versions of all key programs are available
+in ported, well-tested forms.
+<li>A &ldquo;settling&rdquo; 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.
+</ul>
+
+ <p>Consequently, most of the first trials of the TDS will be made by
+members of the TDS committee and/or developers of TeX-related
+software. This has already taken place during the course of our
+deliberations (see Appendix&nbsp;<!-- /@w --><a href="#Related-references">Related references</a> for a sample
+tree available electronically). They will certainly result in the
+production of a substantial number of TDS-compliant packages.
+Indeed, the teTeX and TeX Live
+distributions are TDS-compliant and in use now at many sites.
+
+ <p>Once installable forms of key TDS-compliant packages are more
+widespread, some TeX administrators will set up 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 TDS version.
+
+ <p>After most of the dust has settled, hopefully even conservative TeX
+administrators will begin to adopt the TDS. Eventually, most
+TeX sites will have adopted the common structure, and most packages
+will be readily available in TDS-compliant form.
+
+ <p>We believe that this process will occur relatively quickly. The
+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 TDS definition have been covered,
+often in detail. TeX developers have been consulted about
+implementation issues, and have been trying out the TDS
+arrangement. Thus, we hope for few surprises as implementations mature.
+
+ <p>Finally, there are several (current or prospective) publishers of TeX
+CD-ROMs. These publishers are highly motivated to work out
+details of TDS implementation, and their products will provide
+inexpensive and convenient ways for experimentally-minded TeX
+administrators to experiment with the TDS.
+
+<div class="node">
+<p><hr>
+<a name="More-on-subdirectory-searching"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Adoption-of-the-TDS">Adoption of the TDS</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Implementation-issues">Implementation issues</a>
+<br>
+</div>
+
+<h3 class="section">B.2 More on subdirectory searching</h3>
+
+<p>Recursive subdirectory searching is the ability to specify a search not
+only of a specified directory <samp><var>d</var></samp>, but recursively of all
+directories below <samp><var>d</var></samp>.
+
+ <p>Since the TDS specifies precise locations for most files, with no
+extra levels of subdirectories allowed, true recursive searching is not
+actually required for a 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.
+
+ <p>This feature is already supported by many implementations of TeX and
+companion utilities, for example DECUS TeX for VMS,
+Dvips(k), emTeX (and its drivers),
+PubliC TeX, Web2C, Xdvi(k),
+and Y&amp;YTeX. The Kpathsea library is a reusable
+implementation of subdirectory searching for TeX, used in a number of
+the above programs.
+
+ <p>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 AMS fonts, it would be feasible to store them
+in the TDS layout and list the directories individually in
+configuration files or environment variables.
+
+ <p>The 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 TDS,
+for the reasons stated in Section&nbsp;<!-- /@w --><a href="#Subdirectory-searching">Subdirectory searching</a>.
+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.
+
+ <p>Different implementations specify subdirectory searching differently.
+In the interest of typographic clarity, the examples here do not use the
+<samp><var>replaceable</var></samp> font.
+
+ <ul>
+<li>Dvips:
+via a separate
+<samp><span class="file">TEXFONTS_SUBDIR</span></samp> environment variable.
+
+ <li>emTeX:
+<samp><span class="file">t:\subdir!!</span></samp>; <samp><span class="file">t:\subdir!</span></samp> for
+a single level of searching.
+
+ <li>Kpathsea:
+<samp><span class="file">texmf/subdir//</span></samp>
+
+ <li>VMS:
+<samp><span class="file">texmf:[subdir...]</span></samp>
+
+ <li>Xdvi (patchlevel 20):
+<samp><span class="file">texmf/subdir/**</span></samp>;
+<samp><span class="file">texmf/subdir/*</span></samp> for a single level of searching. Version 20.50
+and above support the <samp><span class="file">//</span></samp> notation.
+
+ <li>Y&amp;Y TeX:
+<samp><span class="file">t:/subdir//</span></samp> or
+<samp><span class="file">t:\subdir\\</span></samp>.
+
+ </ul>
+
+<div class="node">
+<p><hr>
+<a name="Example-implementation_002dspecific-trees"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#More-on-subdirectory-searching">More on subdirectory searching</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Implementation-issues">Implementation issues</a>
+<br>
+</div>
+
+<h3 class="section">B.3 Example implementation-specific trees</h3>
+
+<p>The TDS cannot specify a precise location for
+implementation-specific files, such as <samp><span class="file">texmf/ini</span></samp>, because a site
+may have multiple TeX implementations.
+
+ <p>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.
+
+ <p>We recommend all implementations have default search paths that start
+with the current directory (e.g., <samp><span class="file">.</span></samp>). Allowing users to
+include the parent directory (e.g., <samp><span class="file">..</span></samp>) is also helpful.
+
+<ul class="menu">
+<li><a accesskey="1" href="#AmiWeb2c-2_002e0">AmiWeb2c 2.0</a>
+<li><a accesskey="2" href="#Public-DECUS-TeX">Public DECUS TeX</a>
+<li><a accesskey="3" href="#Web2c-7">Web2c 7</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="AmiWeb2c-2_002e0"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Public-DECUS-TeX">Public DECUS TeX</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>
+<br>
+</div>
+
+<h4 class="subsection">B.3.1 AmiWeb2c 2.0</h4>
+
+<p>(Email <a href="mailto:scherer@physik.rwth-aachen.de">scherer@physik.rwth-aachen.de</a> to contact the maintainer
+of this implementation.)
+
+ <p>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.
+
+ <p>Thanks to the <samp><span class="file">SELFAUTO</span></samp> 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.
+
+ <p>In addition to Kpathsea's <samp><span class="file">//</span></samp> notation recursive path search may
+also be started by <samp><var>DEVICE</var><span class="file">:/</span></samp>, e.g., <samp><span class="file">TeXMF:/</span></samp>
+will scan this specific device completely.
+
+ <p>Binaries coming with the AmiWeb2c distribution are installed in the
+directory <samp><span class="file">bin/amiweb2c/</span></samp> outside the common TDS tree
+<samp><span class="file">share/texmf/</span></samp>. In addition to the set of AmiWeb2c binaries
+you will find two subdirectories <samp><span class="file">local/</span></samp> and <samp><span class="file">pastex/</span></samp>
+with auxiliary programs.
+
+ <p>A stripped version of the PasTeX system (used by kind permission of
+Georg He&szlig;mann) is coming with AmiWeb2c, pre-installed in its own
+<samp><span class="file">share/texmf/amiweb2c/pastex/</span></samp> directory. If you want to use
+PasTeX you have to <samp><span class="file">assign</span></samp> the name <samp><span class="file">TeX:</span></samp> to this place.
+
+ <p>Documentation files in AmigaGuide format should be stored at
+<samp><span class="file">doc/guide/</span></samp> similar to <samp><span class="file">doc/info/</span></samp>.
+
+<div class="node">
+<p><hr>
+<a name="Public-DECUS-TeX"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Web2c-7">Web2c 7</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#AmiWeb2c-2_002e0">AmiWeb2c 2.0</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>
+<br>
+</div>
+
+<h4 class="subsection">B.3.2 Public DECUS TeX</h4>
+
+<p>If another VMS implementation besides Public DECUS TeX
+appears, the top level implementation directory name will be modified to
+something more specific (e.g., <samp><span class="file">vms_decus</span></samp>).
+
+<pre class="example"> 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
+</pre>
+ <div class="node">
+<p><hr>
+<a name="Web2c-7"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#Public-DECUS-TeX">Public DECUS TeX</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>
+<br>
+</div>
+
+<h4 class="subsection">B.3.3 Web2c 7</h4>
+
+<p>All implementation-dependent TeX system files (<samp><span class="file">.pool</span></samp>,
+<samp><span class="file">.fmt</span></samp>, <samp><span class="file">.base</span></samp>, <samp><span class="file">.mem</span></samp>) are stored by default directly
+in <samp><span class="file">texmf/web2c</span></samp>. The configuration file <samp><span class="file">texmf.cnf</span></samp> and
+various subsidiary <samp><span class="file">MakeTeX...</span></samp> scripts used as subroutines are
+also stored there.
+
+ <p>Non-TeX specific files are stored following the GNU coding
+standards. Given a root directory <samp><var>prefix</var></samp>
+(<samp><span class="file">/usr/local</span></samp> by default), we have default locations as follows:
+
+<pre class="example"> &lt;prefix&gt;/ installation root (<samp><span class="file">/usr/local</span></samp> by default)
+ bin/ executables
+ man/ man pages
+ info/ info files
+ lib/ libraries (<samp><span class="file">libkpathsea.*</span></samp>)
+ share/ architecture-independent files
+ texmf/ TDS root
+ web2c/ implementation-dependent files (<samp><span class="file">.pool</span></samp>, <samp><span class="file">.fmt</span></samp>, <samp><span class="file">texmf.cnf</span></samp>, etc.)
+</pre>
+ <p>See <a href="http://www.gnu.org/prep/standards_toc.html">http://www.gnu.org/prep/standards_toc.html</a> 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 <samp><span class="file">/usr/local/texmf</span></samp>.
+
+<div class="node">
+<p><hr>
+<a name="Is-there-a-better-way_003f"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Related-references">Related references</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Implementation-issues">Implementation issues</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
+<br>
+</div>
+
+<h2 class="appendix">Appendix C Is there a better way?</h2>
+
+<p>Defining the 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 &ldquo;made sense&rdquo;).
+
+ <p>Some interesting ideas could not be applied due to implementations
+lacking the necessary support:
+
+ <ul>
+<li>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.
+
+ <li>Multiple logical <samp><span class="file">texmf</span></samp> 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.
+
+ </ul>
+
+<ul class="menu">
+<li><a accesskey="1" href="#Macro-structure">Macro structure</a>
+<li><a accesskey="2" href="#Font-structure">Font structure</a>
+<li><a accesskey="3" href="#Documentation-structure">Documentation structure</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="Macro-structure"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Font-structure">Font structure</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Is-there-a-better-way_003f">Is there a better way?</a>
+<br>
+</div>
+
+<h3 class="section">C.1 Macro structure</h3>
+
+<p>The TWG settled on the
+<samp><var>format</var><span class="file">/</span><var>package</var></samp> arrangement after long
+discussion about how best to arrange the files.
+
+ <p>The primary alternative to this arrangement was a scheme which reversed
+the order of these directories:
+<samp><var>package</var><span class="file">/</span><var>format</var></samp>. 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).
+
+ <p>Nevertheless, the <samp><var>format</var><span class="file">/</span><var>package</var></samp>
+structure won for a couple of reasons:
+
+ <ul>
+<li>It is closer to current practice; in fact, several members of the
+TWG have already implemented the TDS hierarchy. The
+alternative is not in use at any known site, and the TWG felt it
+wrong to mandate something with which there is no practical experience.
+
+ <li>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.
+
+ </ul>
+
+<div class="node">
+<p><hr>
+<a name="Font-structure"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Documentation-structure">Documentation structure</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Macro-structure">Macro structure</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Is-there-a-better-way_003f">Is there a better way?</a>
+<br>
+</div>
+
+<h3 class="section">C.2 Font structure</h3>
+
+<p>The 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 TDS effort.
+
+<ul class="menu">
+<li><a accesskey="1" href="#Font-file-type-location">Font file type location</a>
+<li><a accesskey="2" href="#Mode-and-resolution-location">Mode and resolution location</a>
+<li><a accesskey="3" href="#Modeless-bitmaps">Modeless bitmaps</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="Font-file-type-location"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Mode-and-resolution-location">Mode and resolution location</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Font-structure">Font structure</a>
+<br>
+</div>
+
+<h4 class="subsection">C.2.1 Font file type location</h4>
+
+<p>We considered the supplier-first arrangement in use at many sites:
+
+<pre class="example"> texmf/fonts/<var>supplier</var>/<var>typeface</var>/<var>type</var>/
+</pre>
+ <p>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
+<samp><span class="file">TFM</span></samp> file, the simplest implementation would require TeX to
+search through all the directories that contain PK files in all
+modes and at all resolutions.
+
+ <p>In the end, a poll of developers revealed considerable resistance to
+implementing sufficient caching mechanisms, so this arrangement was
+abandoned. The 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.
+
+ <p>We also considered segregating all font-related files strictly by file
+type, so that Metafont sources would be in a directory
+<samp><span class="file">texmf/fonts/mf</span></samp>, property list files in <samp><span class="file">texmf/fonts/pl</span></samp>, the
+various forms of Type&nbsp;<!-- /@w -->1 fonts separated, and so on. Although more
+blindly consistent, we felt that the drawback of more complicated path
+constructions outweighed this. The TDS merges file types
+(<samp><span class="file">mf</span></samp> and <samp><span class="file">pl</span></samp> under <samp><span class="file">source</span></samp>, <samp><span class="file">pfa</span></samp> and <samp><span class="file">pfb</span></samp>
+and <samp><span class="file">gsf</span></samp> under <samp><span class="file">type1</span></samp>) where we felt this was beneficial.
+
+<div class="node">
+<p><hr>
+<a name="Mode-and-resolution-location"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Modeless-bitmaps">Modeless bitmaps</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Font-file-type-location">Font file type location</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Font-structure">Font structure</a>
+<br>
+</div>
+
+<h4 class="subsection">C.2.2 Mode and resolution location</h4>
+
+<p>We considered having the <samp><span class="file">mode</span></samp> at the bottom of the font tree:
+<pre class="example"> texmf/fonts/pk/<var>supplier</var>/<var>typeface</var>/<var>mode</var>/<var>dpi</var>/
+</pre>
+ <p>In this case, however, it is difficult to limit subdirectory searching
+to the mode required for a particular device.
+
+ <p>We then considered moving the <samp><span class="file">dpi</span><var>nnn</var></samp> up to below
+the mode:
+<pre class="example"> texmf/fonts/pk/<var>mode</var>/<var>dpi</var>/<var>supplier</var>/<var>typeface</var>/
+</pre>
+ <p>But then it is not feasible to omit the <samp><span class="file">dpi</span><var>nnn</var></samp>
+level altogether on systems which can and do choose to use long
+filenames.
+
+<div class="node">
+<p><hr>
+<a name="Modeless-bitmaps"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#Mode-and-resolution-location">Mode and resolution location</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Font-structure">Font structure</a>
+<br>
+</div>
+
+<h4 class="subsection">C.2.3 Modeless bitmaps</h4>
+
+<p>The TDS specifies using a single directory <samp><span class="file">modeless/</span></samp> as
+the mode name for those utilities which generate bitmaps, e.g.,
+<samp><span class="file">texmf/fonts/modeless/times/</span></samp>. This has the considerable advantage
+of not requiring each such directory name to be listed in a search path.
+
+ <p>An alternative was to use the utility name below which all such
+directories could be gathered. That has the advantage of separating,
+say, <samp><span class="file">gsftopk</span></samp>-generated bitmaps from <samp><span class="file">ps2pk</span></samp>-generated ones.
+However, we decided this was not necessary; most sites will use only one
+program for the purpose. Also, PK and GF fonts generally
+identify their creator in the font comment following the <samp><span class="file">PK_ID</span></samp>
+byte.
+
+ <p>We are making an implicit assumption that Metafont 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 <samp><span class="file">mfcx</span></samp> vs.
+<samp><span class="file">xyzcx</span></samp> for a hypothetical program 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&nbsp;<!-- /@w -->happen.
+
+<div class="node">
+<p><hr>
+<a name="Documentation-structure"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#Font-structure">Font structure</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Is-there-a-better-way_003f">Is there a better way?</a>
+<br>
+</div>
+
+<h3 class="section">C.3 Documentation structure</h3>
+
+<p>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.
+
+ <p>We hope that a separate, but parallel, structure for documentation would
+(1)&nbsp;<!-- /@w -->keep the documentation together and (2)&nbsp;<!-- /@w -->make it as straightforward
+as possible for users to find the particular documentation they were
+after.
+
+<div class="node">
+<p><hr>
+<a name="Related-references"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Contributors">Contributors</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="#Is-there-a-better-way_003f">Is there a better way?</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
+<br>
+</div>
+
+<h2 class="appendix">Appendix D Related references</h2>
+
+<p>This appendix gives pointers to related files and other documents. For
+CTAN references, we use <samp><span class="file">http://www.ctan.org</span></samp> as the
+top-level domain only to make the links be live in this document. See
+<a href="http://www.ctan.org/tex-archive/CTAN.sites">http://www.ctan.org/tex-archive/CTAN.sites</a> for a complete list of
+CTAN sites; there are mirrors worldwide.
+
+ <ul>
+<li>This document, in many formats (tex, dvi, info, pdf):<br>
+<a href="http://tug.org/tds/">http://tug.org/tds/</a>
+
+ <li>The TDS mailing list archives:<br>
+<a href="http://tug.org/mail-archives/twg-tds/">http://tug.org/mail-archives/twg-tds/</a>
+
+ <li>The level&nbsp;<!-- /@w -->0 DVI driver standard:<br>
+<a href="http://www.ctan.org/tex-archive/dviware/driv-standard/level-0/">http://www.ctan.org/tex-archive/dviware/driv-standard/level-0/</a>
+
+ <li><cite>Filenames for TeX fonts</cite>, with lists of recommended
+supplier and typeface names:<br>
+<a href="http://tug.org/fontname/">http://tug.org/fontname/</a>
+
+ <li>ISO-9660 CD-ROM file system standard:<br>
+<a href="http://www.iso.ch/cate/cat.html">http://www.iso.ch/cate/cat.html</a>
+
+ <li><cite>Components of TeX</cite>, a paper by Joachim
+Schrod:<br>
+<a href="http://www.ctan.org/tex-archive/documentation/components-of-TeX/">http://www.ctan.org/tex-archive/documentation/components-of-TeX/</a>
+
+ <li><cite>Managing Multiple TDS trees</cite>, an article by Michael
+Downes:<br>
+<a href="http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf">http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf</a>
+
+ <li>A complete set of Metafont modes:<br>
+<a href="http://www.ctan.org/tex-archive/fonts/modes/modes.mf">http://www.ctan.org/tex-archive/fonts/modes/modes.mf</a>
+
+ <li>A large collection of BibTeX databases and styles:<br>
+<a href="ftp://ftp.math.utah.edu/pub/tex/bib/">ftp://ftp.math.utah.edu/pub/tex/bib/</a>
+
+ </ul>
+
+<div class="node">
+<p><hr>
+<a name="Contributors"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#Related-references">Related references</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
+<br>
+</div>
+
+<h2 class="appendix">Appendix E Contributors</h2>
+
+<p>The TWG has had no physical meetings; electronic mail was the
+communication medium.
+
+ <p>Sebastian Rahtz is the TeX Users Group Technical Council liaison.
+Norman Walsh was the original committee chair. Karl Berry is the
+current editor.
+
+ <p>The list of contributors has grown too large to fairly include, as some
+would surely be inadvertently omitted. Please consider the archives of
+the <a href="mailto:tds@tug.org">tds@tug.org</a> and <a href="mailto:tex-live@tug.org">tex-live@tug.org</a> mailing lists as
+the record of contributions.
+
+</body></html>
+