summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/info/tds.info
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
committerKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
commitb04c2e1a42573e9735547702356c7b9a769a6855 (patch)
treec0753443f39500a062d7698fe6b94359c813f871 /Master/texmf-dist/doc/info/tds.info
parentfb0bf13304a356f197bfc1add17f98c07e96f17b (diff)
texmf -> texmf-dist: doc
git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/info/tds.info')
-rw-r--r--Master/texmf-dist/doc/info/tds.info1714
1 files changed, 1714 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/info/tds.info b/Master/texmf-dist/doc/info/tds.info
new file mode 100644
index 00000000000..8b2418cd0a2
--- /dev/null
+++ b/Master/texmf-dist/doc/info/tds.info
@@ -0,0 +1,1714 @@
+This is tds.info, produced by makeinfo version 4.7 from tds.texi.
+
+INFO-DIR-SECTION TeX
+START-INFO-DIR-ENTRY
+* TeX Directories: (tds). A directory structure for TeX files.
+END-INFO-DIR-ENTRY
+
+
+File: tds.info, Node: Top, Next: Introduction, Up: (dir)
+
+A Directory Structure for TeX Files
+***********************************
+
+Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2003, 2004 TeX Users
+Group.
+
+ Permission to use, copy, and distribute this document _without
+modification_ for any purpose and without fee is hereby granted,
+provided that this notice appears in all copies. It is provided "as
+is" without expressed or implied warranty.
+
+ Permission is granted to copy and distribute modified versions of
+this document under the conditions for verbatim copying, provided that
+the modifications are clearly marked and the document is not
+represented as the official one.
+
+ This document is available on any CTAN host (see Appendix *Note
+Related references::). Please send questions or suggestions by email to
+<tds@tug.org>. We welcome all comments. This is version 1.1.
+
+* Menu:
+
+* Introduction::
+* General::
+* Top-level directories::
+* Summary::
+* Unspecified pieces::
+* Implementation issues::
+* Is there a better way?::
+* Related references::
+* Contributors::
+
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* History::
+* The role of the TDS::
+* Conventions::
+
+General
+
+* Subdirectory searching::
+* Rooting the tree::
+* Local additions::
+* Duplicate filenames::
+
+Top-level directories
+
+* Macros::
+* Fonts::
+* Non-font Metafont files::
+* MetaPost::
+* BibTeX::
+* Scripts::
+* Documentation::
+
+Macros
+
+* Extensions::
+
+Fonts
+
+* Font bitmaps::
+* Valid font bitmaps::
+
+Summary
+
+* Documentation tree summary::
+
+Unspecified pieces
+
+* Portable filenames::
+
+Implementation issues
+
+* Adoption of the TDS::
+* More on subdirectory searching::
+* Example implementation-specific trees::
+
+Example implementation-specific trees
+
+* AmiWeb2c 2.0::
+* Public DECUS TeX::
+* Web2c 7::
+
+Is there a better way?
+
+* Macro structure::
+* Font structure::
+* Documentation structure::
+
+Font structure
+
+* Font file type location::
+* Mode and resolution location::
+* Modeless bitmaps::
+
+
+File: tds.info, Node: Introduction, Next: General, Prev: Top, Up: Top
+
+1 Introduction
+**************
+
+TeX is a powerful, flexible typesetting system used by many people
+around the world. It is extremely portable and runs on virtually all
+operating systems. One unfortunate side effect of TeX's flexibility,
+however, is that there has been no single "right" way to install it.
+This has resulted in many sites having different installed arrangements.
+
+ The primary purpose of this document is to describe a standard TeX
+Directory Structure (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.
+
+ This document is intended both for the TeX system administrator at a
+site and for people preparing TeX distributions--everything from a
+complete runnable system to a single macro or style file. It may also
+help TeX users find their way around systems organized this way. It is
+not a tutorial: we necessarily assume knowledge of the many parts of a
+working TeX system. If you are unfamiliar with any of the programs or
+file formats we refer to, consult the references in Appendix *Note
+Related references::.
+
+* Menu:
+
+* History::
+* The role of the TDS::
+* Conventions::
+
+
+File: tds.info, Node: History, Next: The role of the TDS, Up: Introduction
+
+1.1 History
+===========
+
+Version 1.0 of the TDS was released in February 2003.
+
+ Version 1.1 was released in June 2004, with the following
+non-editorial changes:
+
+ * Inputs for TeX extensions included under `tex', instead of
+ in their own top-level directories (Section *Note Extensions::)
+
+ * New top-level directory `scripts' (Section *Note Scripts::).
+
+ * New subdirectories `lig', `opentype', `truetype', and
+ `type3' under `fonts' (Section *Note Fonts::).
+
+ * `enc', `lig', and `map' all use `SYNTAX/PACKAGE'
+ subdirectories (Section *Note Fonts::).
+
+ * `pfm' files specified to go under `type1', and `inf' files
+ under `afm' (Section *Note Fonts::).
+
+
+File: tds.info, Node: The role of the TDS, Next: Conventions, Prev: History, Up: Introduction
+
+1.2 The role of the TDS
+=======================
+
+The role of the TDS is to stabilize the organization of TeX-related
+software packages that are installed and in use, possibly on multiple
+platforms simultaneously.
+
+ At first glance, it may seem that the 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.
+
+ 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.
+
+
+File: tds.info, Node: Conventions, Prev: The role of the TDS, Up: Introduction
+
+1.3 Conventions
+===============
+
+In this document, `/' is used to separate filename components; for
+example, `texmf/fonts'. This is the Unix convention but the ideas are
+in no way Unix-specific.
+
+ In this document, "TeX" generally means the TeX system, including
+Metafont, DVI drivers, utilities, etc., not just the TeX program itself.
+
+ The word "package" in this document has its usual meaning: a set of
+related files distributed, installed, and maintained as a unit. This is
+_not_ a LaTeX2e package, which is a style file supplementing a document
+class.
+
+ We use the following typographic conventions:
+
+ * `literal' Literal text such as `filename' is typeset in typewriter
+ type.
+
+ * `REPLACEABLE' Replaceable text such as `PACKAGE', identifying a
+ class of things, is typeset in italics inside angle brackets.
+
+
+
+File: tds.info, Node: General, Next: Top-level directories, Prev: Introduction, Up: Top
+
+2 General
+*********
+
+This section describes common properties throughout the TDS tree.
+
+* Menu:
+
+* Subdirectory searching::
+* Rooting the tree::
+* Local additions::
+* Duplicate filenames::
+
+
+File: tds.info, Node: Subdirectory searching, Next: Rooting the tree, Up: General
+
+2.1 Subdirectory searching
+==========================
+
+Older TeX installations store large numbers of related files in single
+directories, for example, all `TFM' files and/or all TeX input files.
+
+ This monolithic arrangement hinders maintenance of a TeX system: it
+is difficult to determine what files are used by what packages, what
+files need to be updated when a new version is installed, or what files
+should be deleted if a package is removed. It is also a source of error
+if two or more packages happen to have input files with the same name.
+
+ Therefore, the TWG felt each package should be in a separate
+directory. But we recognized that explicitly listing all directories to
+be searched would be unbearable. A site may wish to install dozens of
+packages. Aside from anything else, listing that many directories would
+produce search paths many thousands of characters long, overflowing the
+available space on some systems.
+
+ Also, if all directories are explicitly listed, installing or
+removing a new package would mean changing a path as well as installing
+or removing the actual files. This would be a time-consuming and
+error-prone operation, even with implementations that provide some way
+to specify the directories to search at runtime. On systems without
+runtime configuration, it would require recompiling software, an
+intolerable burden.
+
+ As a result, the TWG concluded that a comprehensive TDS requires
+implementations to support some form of implicit subdirectory
+searching. More precisely, implementations must make it possible to
+specify that TeX, Metafont, and their companion utilities search in both
+a specified directory and recursively through all subdirectories of that
+directory when looking for an input file. Other forms of subdirectory
+searching, for example recursive-to-one-level searches, may also be
+provided. We encourage implementors to provide subdirectory searching
+at the option of the installer and user for all paths.
+
+ The TDS does not specify a syntax for specifying recursive
+searching, but we encourage implementors to provide interoperability
+(see Section *Note More on subdirectory searching::).
+
+
+File: tds.info, Node: Rooting the tree, Next: Local additions, Prev: Subdirectory searching, Up: General
+
+2.2 Rooting the tree
+====================
+
+In this document, we shall designate the root TDS directory by `texmf'
+(for "TeX and Metafont"). We recommend using that name where possible,
+but the actual name of the directory is up to the installer. On PC
+networks, for example, this could map to a logical drive specification
+such as `T:'.
+
+ Similarly, the location of this directory on the system is
+site-dependent. It may be at the root of the file system; on Unix
+systems, `/usr/local/share', `/usr/local', `/usr/local/lib', and `/opt'
+are common choices.
+
+ The name `texmf' was chosen for several reasons: it reflects the fact
+that the directory contains files pertaining to an entire TeX system
+(including Metafont, MetaPost, BibTeX, etc.), not just TeX itself; and
+it is descriptive of a generic installation rather than a particular
+implementation.
+
+ A site may choose to have more than one TDS hierarchy installed (for
+example, when installing an upgrade). This is perfectly legitimate.
+
+
+File: tds.info, Node: Local additions, Next: Duplicate filenames, Prev: Rooting the tree, Up: General
+
+2.3 Local additions
+===================
+
+The TDS cannot specify precisely when a package is or is not a "local
+addition". Each site must determine this according to its own
+conventions. At the two extremes, one site might wish to consider
+"nonlocal" all files not acquired as part of the installed TeX
+distribution; another site might consider "local" only those files that
+were actually developed at the local site and not distributed elsewhere.
+
+ We recognize two common methods for local additions to a distributed
+`texmf' tree. Both have their place; in fact, some sites employ both
+simultaneously:
+
+ 1. A completely separate tree which is a TDS structure itself; for
+ example, `/usr/local/umbtex' at the University of Massachusetts at
+ Boston. This is another example of the multiple `texmf'
+ hierarchies mentioned in the previous section.
+
+ 2. A directory named `local' at any appropriate level, for example,
+ in the `FORMAT', `PACKAGE', and `SUPPLIER' directories discussed
+ in the following sections. The TDS reserves the directory name
+ `local' for this purpose.
+
+ We recommend using `local' for site-adapted configuration files,
+ such as `language.dat' for the Babel package or `graphics.cfg' for
+ the graphics package. Unmodified configuration files from a
+ package should remain in the package directory. The intent is to
+ separate locally modified or created files from distribution
+ files, to ease installing new releases.
+
+
+ One common case of local additions is dynamically generated files,
+e.g., PK fonts by the `mktexpk' script (which originated in Dvips as
+`MakeTeXPK'). A site may store the generated files directly in any of:
+ * their standard location in the main TDS tree (if it can be made
+ globally writable);
+
+ * an alternative location in the main TDS tree (for example, under
+ `texmf/fonts/tmp');
+
+ * a second complete TDS tree (as outlined above);
+
+ * any other convenient directory (perhaps under `/var', for example
+ `/var/spool/fonts').
+
+
+ No one solution will be appropriate for all sites.
+
+
+File: tds.info, Node: Duplicate filenames, Prev: Local additions, Up: General
+
+2.4 Duplicate filenames
+=======================
+
+Different files by the same name may exist in a TDS tree. The TDS
+generally leaves unspecified which of two files by the same name in a
+search path will be found, so generally the only way to reliably find a
+given file is for it to have a unique name. However, the TDS requires
+implementations to support the following exceptions:
+
+ * Names of TeX input files must be unique within each first-level
+ subdirectory of `texmf/tex' and `texmf/tex/generic', but not
+ within all of `texmf/tex'; i.e., different TeX formats may have
+ files by the same name. (Section *Note Macros:: discusses this
+ further.) Thus, no single format-independent path specification,
+ such as a recursive search beginning at `texmf/tex' specifying no
+ other directories, suffices. So implementations must provide
+ format-dependent path specifications, for example via wrapper
+ scripts or configuration files.
+
+ * Many font files will have the same name (e.g., `cmr10.pk'), as
+ discussed in Section *Note Valid font bitmaps::. Implementations
+ must distinguish these files by mode and resolution.
+
+
+ All implementations we know of already have these capabilities.
+
+ One place where duplicate names are likely to occur is not an
+exception:
+
+ * Names of Metafont input files (as opposed to bitmaps) must be
+ unique within all of `texmf/fonts'. In practice, this is a problem
+ with some variants of Computer Modern which contain slightly
+ modified files named `punct.mf', `romanl.mf', and so on. We
+ believe the only feasible solution is to rename the derivative
+ files to be unique.
+
+
+
+File: tds.info, Node: Top-level directories, Next: Summary, Prev: General, Up: Top
+
+3 Top-level directories
+***********************
+
+The directories under the `texmf' root identify the major components of
+a TeX system (see Section *Note Summary:: for a summary). A site may
+omit any unneeded directories.
+
+ Although the TDS by its nature can specify precise locations only
+for implementation-independent files, we recognize that installers may
+well wish to place other files under `texmf' to simplify administration
+of the TeX tree, especially if it is maintained by someone other than
+the system administrator. Therefore, additional top-level directories
+may be present.
+
+ The top-level directories specified by the TDS are:
+
+ * `tex' for TeX files (Section *Note Macros::).
+
+ * `fonts' for font-related files (Section *Note Fonts::).
+
+ * `metafont' for Metafont files which are not fonts (Section *Note
+ Non-font Metafont files::).
+
+ * `metapost' for MetaPost files (Section *Note MetaPost::).
+
+ * `bibtex' for BibTeX files (Section *Note BibTeX::).
+
+ * `scripts' for platform-independent executables (Section *Note
+ Scripts::).
+
+ * `doc' for user documentation (Section *Note Documentation::).
+
+ * `source' for sources. This includes both traditional program
+ sources (for example, Web2C sources go in `texmf/source/web2c')
+ and, e.g., LaTeX `dtx' sources (which go in `texmf/source/latex').
+ The TDS leaves unspecified any structure under `source'.
+
+ `source' is intended for files which are not needed at runtime by
+ any TeX program; it should not be included in any search path. For
+ example, `plain.tex' does not belong under `texmf/source', even
+ though it is a "source file" in the sense of not being derived
+ from another file. (It goes in `texmf/tex/plain/base', as explained
+ in Section *Note Macros::).
+
+ * `IMPLEMENTATION' for implementations (examples: `emtex', `vtex',
+ `web2c'), to be used for whatever purpose deemed suitable by the
+ implementor or TeX administrator. That is, files that cannot be
+ shared between implementations, such as pool files (`tex.pool')
+ and memory dump files (`plain.fmt') go here, in addition to
+ implementation-wide configuration files. See Section *Note
+ Example implementation-specific trees:: for examples of real
+ `IMPLEMENTATION' trees.
+
+ Such implementation-specific configuration files should _not_ be
+ located using the main TeX input search path (e.g., `TEXINPUTS').
+ This must be reserved for files actually read by a TeX engine.
+ See Section *Note Extensions::.
+
+ * `PROGRAM' for program-specific input and configuration files for
+ any TeX-related programs (examples: `mft', `dvips'). In fact, the
+ `tex', `metafont', `metapost', and `bibtex' items above may all be
+ seen as instances of this case.
+
+
+* Menu:
+
+* Macros::
+* Fonts::
+* Non-font Metafont files::
+* MetaPost::
+* BibTeX::
+* Scripts::
+* Documentation::
+
+
+File: tds.info, Node: Macros, Next: Fonts, Up: Top-level directories
+
+3.1 Macros
+==========
+
+TeX macro files shall be stored in separate directories, segregated by
+TeX format and package name (we use `format' in its traditional TeX
+sense to mean a usefully `\dump'-able package):
+ texmf/tex/FORMAT/PACKAGE/
+
+ * `FORMAT' is a format name (examples: `amstex', `latex', `plain',
+ `texinfo').
+
+ The TDS allows distributions that can be used as either formats or
+ packages (e.g., Texinfo, Eplain) to be stored at either level, at
+ the option of the format author or TeX administrator. We recommend
+ that packages used as formats at a particular site be stored at the
+ `FORMAT' level: by adjusting the TeX inputs search path, it will
+ be straightforward to use them as macro packages under another
+ format, whereas placing them in another tree completely obscures
+ their use as a format.
+
+ The TDS reserves the following `FORMAT' names:
+
+ * `generic', for input files that are useful across a wide
+ range of formats (examples: `null.tex', `path.sty').
+ Generally, this means any format that uses the category codes
+ of Plain TeX and does not rely on any particular format.
+ This is in contrast to those files which are useful only with
+ Plain TeX (which go under `texmf/tex/plain'), e.g.,
+ `testfont.tex' and `plain.tex' itself.
+
+ * `local', for local additions. See Section *Note Local
+ additions::.
+
+
+ Thus, for almost every format, it is necessary to search at least
+ the `FORMAT' directory and then the `generic' directory (in that
+ order). Other directories may need to be searched as well,
+ depending on the format. When using AMS-TeX, for example, the
+ `amstex', `plain', and `generic' directories should be searched,
+ because AMS-TeX is compatible with Plain.
+
+ * `PACKAGE' is a TeX package name (examples: `babel', `texdraw').
+
+ In the case where a format consists of only a single file and has
+ no auxiliary packages, that file can simply be placed in the
+ `FORMAT' directory, instead of `FORMAT/base'. For example,
+ Texinfo may go in `texmf/tex/texinfo/texinfo.tex', not
+ `texmf/tex/texinfo/base/texinfo.tex'.
+
+ The TDS reserves the following `PACKAGE' names:
+
+ * `base', for the base distribution of each format, including
+ files used by INITEX when dumping format files. For example,
+ in the standard LaTeX distribution, the `ltx' files created
+ during the build process. Another example: the `.ini' driver
+ files for formats used by TeX Live and other distributions.
+
+ * `hyphen', for hyphenation patterns, including the original
+ American English `hyphen.tex'. These are typically used only
+ by INITEX. In most situations, this directory need exist
+ only under the `generic' format.
+
+ * `images', for image input files, such as Encapsulated
+ PostScript figures. Although it is somewhat non-intuitive for
+ these to be under a directory named `tex', TeX needs to read
+ these files to glean bounding box or other information. A
+ mechanism for sharing image inputs between TeX and other
+ typesetting programs (e.g., Interleaf, FrameMaker) is beyond
+ the scope of the TDS. In most situations, this directory need
+ exist only under the `generic' format.
+
+ * `local', for local additions and configuration files. See
+ Section *Note Local additions::.
+
+ * `misc', for packages that consist of a single file. An
+ administrator or package maintainer may create directories for
+ single-file packages at their discretion, instead of using
+ `misc'.
+
+
+
+* Menu:
+
+* Extensions::
+
+
+File: tds.info, Node: Extensions, Up: Macros
+
+3.1.1 Extensions
+----------------
+
+TeX has spawned many companion and successor programs ("engines"), 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 `tex' directory, either at the top level or within a format
+subdirectory, even though the original TeX program may not be able to
+read them. For example:
+
+ texmf/tex/aleph
+ texmf/tex/enctex
+
+ This is a change from TDS 1.0, which specified top-level `EXTENSION'
+directories for each such program. We felt the new approach is
+preferable, because:
+
+ * 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 `tex'
+ directory provides a stable location over time.
+
+ * Users need to be able to switch between engines, and configuring
+ different search paths for each engine is difficult and
+ error-prone.
+
+
+ Thus, in practice, having different top-level directories caused
+difficulties for everyone involved--users, package authors, site
+administrators, and system distributors.
+
+ Please contrast this approach with the `IMPLEMENTATION' top-level
+subdirectory (Section *Note Top-level directories::), which is to be
+used for configuration files that (presumably) do not use TeX syntax
+and in any case should not be found along the main TeX input search
+path.
+
+
+File: tds.info, Node: Fonts, Next: Non-font Metafont files, Prev: Macros, Up: Top-level directories
+
+3.2 Fonts
+=========
+
+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.
+
+ texmf/fonts/TYPE/SUPPLIER/TYPEFACE/
+ texmf/fonts/enc,lig,map/SUBPATH/
+
+ * `TYPE' is the type of font file. The TDS reserves the following
+ `TYPE' names for common TeX file types:
+
+ * `afm', for Adobe font metrics, and `inf' files.
+
+ * `gf', for generic font bitmap files.
+
+ * `opentype', for OpenType fonts.
+
+ * `pk', for packed bitmap files.
+
+ * `source', for font sources (Metafont files, property lists,
+ etc.).
+
+ * `tfm', for TeX font metric files.
+
+ * `truetype', for TrueType fonts.
+
+ * `type1', for PostScript Type 1 fonts (in `pfa', `pfb',
+ or any other format), and `pfm' files.
+
+ * `type3', for PostScript Type 3 fonts.
+
+ * `vf', for virtual fonts.
+
+ The TDS also reserves the names `enc', `lig', and `map' for font
+ encoding, ligature, and mapping files, respectively. All of these
+ directories are structured the same way, with `SYNTAX'
+ subdirectories, and then `PACKAGE' subsubdirectories. Each of
+ these file types is intended to be searched along its own
+ recursively-searched path. The names of the actual files must be
+ unique within their subtree, as usual. Examples:
+ fonts/map/dvipdfm/updmap/dvipdfm.map
+ fonts/map/dvips/lm/lm.map
+ fonts/enc/dvips/base/8r.enc
+
+ The Fontname and Dvips packages have more examples of the `enc' and
+ `map' types. The `afm2pl' program uses `lig' files.
+
+ `pfm' files are included in the `type1' directory, instead of
+ being given their own directory, for two reasons: 1) a `.pfm' file
+ is always an adjunct to a given `.pfb' file; 2) they must be
+ installed from the same directory for Windows programs other than
+ TeX to use them.
+
+ `inf' files are included in the `afm' directory, since an `inf'
+ and `afm' file can be used to generate a `pfm'. (Unfortunately,
+ Adobe Type Manager and perhaps other software requires that the
+ `pfb' be in the same directory as `afm' and `inf' for
+ installation.)
+
+ As usual, a site may omit any of these directories that are
+ unnecessary. `gf' is a particularly likely candidate for omission.
+
+ * `SUPPLIER' is a name identifying font source (examples: `adobe',
+ `ams', `public'). The TDS reserves the following `SUPPLIER' names:
+
+ * `ams', for the American Mathematical Society's AMS-fonts
+ collection.
+
+ * `local', for local additions. See Section *Note Local
+ additions::.
+
+ * `public', for freely redistributable fonts where the supplier
+ neither (1) requested their own directory (e.g., `ams'), nor
+ (2) also made proprietary fonts (e.g., `adobe'). It does not
+ contain all extant freely distributable fonts, nor are all
+ files therein necessarily strictly public domain.
+
+ * `tmp', for dynamically-generated fonts, as is traditional on
+ some systems. It may be omitted if unnecessary, as usual.
+
+
+ * `TYPEFACE' is the name of a typeface family (examples: `cm',
+ `euler', `times'). The TDS reserves the following `TYPEFACE' names:
+
+ * `cm' (within `public'), for the 75 fonts defined in
+ `Computers and Typesetting, Volume E'.
+
+ * `latex' (within `public'), for those fonts distributed with
+ LaTeX in the base distribution.
+
+ * `local', for local additions. See Section *Note Local
+ additions::.
+
+
+
+ Some concrete examples:
+ texmf/fonts/source/public/pandora/pnr10.mf
+ texmf/fonts/tfm/public/cm/cmr10.tfm
+ texmf/fonts/type1/adobe/utopia/putr.pfa
+
+ For complete supplier and typeface name lists, consult `Filenames
+for TeX fonts' (see Appendix *Note Related references::).
+
+* Menu:
+
+* Font bitmaps::
+* Valid font bitmaps::
+
+
+File: tds.info, Node: Font bitmaps, Next: Valid font bitmaps, Up: Fonts
+
+3.2.1 Font bitmaps
+------------------
+
+Font bitmap files require two characteristics in addition to the above
+to be uniquely identifiable: (1) the type of device (i.e., mode) for
+which the font was created; (2) the resolution of the bitmap.
+
+ Following common practice, the TDS segregates fonts with different
+device types into separate directories. See `modes.mf' in
+Appendix *Note Related references:: for recommended mode names.
+
+ Some printers operate at more than one resolution (e.g., at 300dpi
+and 600dpi), but each such resolution will necessarily have a different
+mode name. Nothing further is needed, since implicit in the TeX system
+is the assumption of a single target resolution.
+
+ Two naming strategies are commonly used to identify the resolution of
+bitmap font files. On systems that allow long filenames (and in the
+original Metafont program itself), the resolution is included in the
+filename (e.g., `cmr10.300pk'). On systems which do not support long
+filenames, fonts are generally segregated into directories by
+resolution (e.g., `dpi300/cmr10.pk').
+
+ Because the TDS cannot require long filenames, we must use the
+latter scheme for naming fonts. So we have two more subdirectory levels
+under `pk' and `gf':
+
+ texmf/fonts/pk/MODE/SUPPLIER/TYPEFACE/dpiNNN/
+ texmf/fonts/gf/MODE/SUPPLIER/TYPEFACE/dpiNNN/
+
+ * `MODE' is a name which identifies the device type (examples: `cx',
+ `ljfour', `modeless'). Usually, this is the name of the Metafont
+ mode used to build the PK file. For fonts rendered as bitmaps by
+ a program that does not distinguish between different output
+ devices, the `MODE' name shall be simply `modeless'. The `MODE'
+ level shall not be omitted, even if only a single mode happens to
+ be in use.
+
+ * `dpiNNN' specifies the resolution of the font (examples: `dpi300',
+ `dpi329'). `dpi' stands for dots per inch, i.e., pixels per inch.
+ We recognize that pixels per millimeter is used in many parts of
+ the world, but dpi is too traditional in the TeX world to consider
+ changing now.
+
+ The integer `NNN' is to be calculated as if using Metafont
+ arithmetic and then rounded; i.e., it is the integer Metafont uses
+ in its output `gf' filename. We recognize small differences in the
+ resolution are a common cause of frustration among users, however,
+ and recommend implementors follow the level 0 DVI driver standard
+ (see Appendix *Note Related references::) in bitmap font searches
+ by allowing a fuzz of +-0.2% (with a minimum of 1) in the `DPI'.
+
+
+ Implementations may provide extensions to the basic naming scheme,
+such as long filenames (as in the original Metafont) and font library
+files (as in emTeX's `.fli' files), provided that the basic scheme is
+also supported.
+
+
+File: tds.info, Node: Valid font bitmaps, Prev: Font bitmaps, Up: Fonts
+
+3.2.2 Valid font bitmaps
+------------------------
+
+The TWG recognizes that the use of short filenames has many
+disadvantages. The most vexing is that it results in the creation of
+dozens of different files with the same name. At a typical site,
+`cmr10.pk' will be the filename for Computer Modern Roman 10pt at 5-10
+magnifications for 2-3 modes. (Section *Note Duplicate filenames::
+discusses duplicate filenames in general.)
+
+ To minimize this problem, we strongly recommend that PK files
+contain enough information to identify precisely how they were created:
+at least the mode, base resolution, and magnification used to create the
+font.
+
+ This information is easy to supply: a simple addition to the local
+modes used for building the fonts with Metafont will automatically
+provide the required information. If you have been using a local modes
+file derived from (or that is simply) `modes.mf' (see Appendix *Note
+Related references::), the required information is already in your PK
+files. If not, a simple addition based on the code found in `modes.mf'
+can be made to your local modes file and the PK files rebuilt.
+
+
+File: tds.info, Node: Non-font Metafont files, Next: MetaPost, Prev: Fonts, Up: Top-level directories
+
+3.3 Non-font Metafont files
+===========================
+
+Most Metafont input files are font programs or parts of font programs
+and are thus covered by the previous section. However, a few non-font
+input files do exist. Such files shall be stored in:
+
+ texmf/metafont/PACKAGE/
+
+ `PACKAGE' is the name of a Metafont package (for example, `mfpic').
+
+ The TDS reserves the following `PACKAGE' names:
+
+ * `base', for the standard Metafont macro files as described in `The
+ Metafontbook', such as `plain.mf' and `expr.mf'.
+
+ * `local', for local additions. See Section *Note Local additions::.
+
+ * `misc', for Metafont packages consisting of only a single file
+ (for example, `modes.mf'). An administrator or package maintainer
+ may create directories for single-file packages at their
+ discretion, instead of using `misc'.
+
+
+
+File: tds.info, Node: MetaPost, Next: BibTeX, Prev: Non-font Metafont files, Up: Top-level directories
+
+3.4 MetaPost
+============
+
+MetaPost is a picture-drawing language developed by John Hobby, derived
+from Knuth's Metafont. Its primary purpose is to output Encapsulated
+PostScript instead of bitmaps.
+
+ MetaPost input files and the support files for MetaPost-related
+utilities shall be stored in:
+
+ texmf/metapost/PACKAGE/
+
+ `PACKAGE' is the name of a MetaPost package. At the present writing
+none exist, but the TWG thought it prudent to leave room for
+contributed packages that might be written in the future.
+
+ The TDS reserves the following `PACKAGE' names:
+
+ * `base', for the standard MetaPost macro files, such as `plain.mp',
+ `mfplain.mp', `boxes.mp', and `graph.mp'. This includes files
+ used by INIMP when dumping mem files containing preloaded macro
+ definitions.
+
+ * `local', for local additions. See Section *Note Local additions::.
+
+ * `misc', 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 `misc'.
+
+ * `support', for additional input files required by MetaPost utility
+ programs, including a font map, a character adjustment table, and
+ a subdirectory containing low-level MetaPost programs for rendering
+ some special characters.
+
+
+
+File: tds.info, Node: BibTeX, Next: Scripts, Prev: MetaPost, Up: Top-level directories
+
+3.5 BibTeX
+==========
+
+BibTeX-related files shall be stored in:
+
+ texmf/bibtex/bib/PACKAGE/
+ texmf/bibtex/bst/PACKAGE/
+
+ The `bib' directory is for BibTeX database (`.bib') files, the `bst'
+directory for style (`.bst') files.
+
+ `PACKAGE' is the name of a BibTeX package. The TDS reserves the
+following `PACKAGE' names (the same names are reserved under both `bib'
+and `bst'):
+
+ * `base', for the standard BibTeX databases and styles, such as
+ `xampl.bib', `plain.bst'.
+
+ * `local', for local additions. See Section *Note Local additions::.
+
+ * `misc', for BibTeX packages consisting of only a single file. An
+ administrator or package maintainer may create directories for
+ single-file packages at their discretion, instead of using `misc'.
+
+
+
+File: tds.info, Node: Scripts, Next: Documentation, Prev: BibTeX, Up: Top-level directories
+
+3.6 Scripts
+===========
+
+The top-level `scripts' directory is for platform-independent
+executables, such as Perl, Python, and shell scripts, and Java class
+files. Subdirectories under `scripts' are package names. This eases
+creating distributions, by providing a common place for such
+platform-independent programs.
+
+ The intent is not for all such directories to be added to a user's
+command search path, which would be quite impractical. Rather, these
+executables are primarily for the benefit of wrapper scripts in whatever
+executable directory a distribution may provide (which is not specified
+by the TDS).
+
+ Truly auxiliary scripts which are invoked directly by other programs,
+rather than wrapper scripts, may also be placed here. That is,
+`scripts' also serves as a platform-independent analog of the standard
+Unix `libexec' directory.
+
+ We recommend using extensions specifying the language (such as
+`.pl', `.py', `.sh') on these files, to help uniquely identify the
+name. Since the intent of the TDS is for programs in `scripts' not to
+be invoked directly by users, this poses no inconvenience.
+
+ For example, in the TeX Live distribution, the ConTeXt user-level
+program `texexec' can exist as a small wrapper script in each
+`bin/PLATFORM/texexec' (which is outside the `texmf' tree), which
+merely finds and calls `texmf/scripts/context/perl/texexec.pl'.
+
+ Examples:
+ scripts/context/perl/texexec.pl
+ scripts/context/ruby/examplex.rb
+ scripts/thumbpdf/thumbpdf.pl
+
+ The TDS does not specify a location for platform-dependent binary
+executables, whether auxiliary or user-level.
+
+
+File: tds.info, Node: Documentation, Prev: Scripts, Up: Top-level directories
+
+3.7 Documentation
+=================
+
+Most packages come with some form of documentation: user manuals,
+example files, programming guides, etc. In addition, many independent
+files not part of any macro or other package have been created to
+describe various aspects of the TeX system.
+
+ The TDS specifies that these additional documentation files shall be
+stored in a structure that parallels to some extent the `fonts' and
+`tex' directories, as follows:
+
+ texmf/doc/CATEGORY/...
+
+ `CATEGORY' identifies the general topic of documentation that
+resides below it; for example, a TeX format name (`latex'), program
+name (`bibtex', `tex'), language (`french', `german'), a file format
+(`info', `man'), or other system components (`web', `fonts').
+
+ One possible arrangement is to organize `doc' by language, with all
+the other category types below that. This helps users find
+documentation in the language(s) in which they are fluent. Neither this
+nor any other particular arrangement is required, however.
+
+ Within each `CATEGORY' tree for a TeX format, the directory `base'
+is reserved for base documentation distributed by the format's
+maintainers.
+
+ The TDS reserves the following category names:
+
+ * `general', for standalone documents not specific to any particular
+ program (for example, Joachim Schrod's `Components of TeX').
+
+ * `help', for meta-information, such as FAQ's, the TeX Catalogue,
+ etc.
+
+ * `info', for processed Texinfo documents. (Info files, like
+ anything else, may also be stored outside the TDS, at the
+ installer's option.)
+
+ * `local', for local additions. See Section *Note Local additions::.
+
+
+ The `doc' directory is intended for implementation-independent and
+operating system-independent documentation files.
+Implementation-dependent files are best stored elsewhere, as provided
+for by the implementation and/or TeX administrator (for example, VMS
+help files under `texmf/vms/help').
+
+ The documentation directories may contain TeX sources, DVI files,
+PostScript files, text files, example input files, or any other useful
+documentation format(s).
+
+ See Section *Note Documentation tree summary:: for a summary.
+
+
+File: tds.info, Node: Summary, Next: Unspecified pieces, Prev: Top-level directories, Up: Top
+
+4 Summary
+*********
+
+A skeleton of a TDS `texmf' directory tree. This is not to imply these
+are the only entries allowed. For example, `local' may occur at any
+level.
+
+ bibtex/ BibTeX input files
+ bib/ BibTeX databases
+ base/ base distribution (e.g., `xampl.bib')
+ misc/ single-file databases
+ <package>/ name of a package
+ bst/ BibTeX style files
+ base/ base distribution (e.g., `plain.bst', `acm.bst')
+ misc/ single-file styles
+ <package>/ name of a package
+ doc/ see Section *Note Documentation:: and the summary below
+ fonts/ font-related files
+ <type>/ file type (e.g., `pk')
+ <mode>/ type of output device (for `pk' and `gf' only)
+ <supplier>/ name of a font supplier (e.g., `public')
+ <typeface>/ name of a typeface (e.g., `cm')
+ dpi<nnn>/ font resolution (for `pk' and `gf' only)
+ <implementation>/ TeX implementations, by name (e.g., `emtex')
+ local/ files created or modified at the local site
+ metafont/ Metafont (non-font) input files
+ base/ base distribution (e.g., `plain.mf')
+ misc/ single-file packages (e.g., `modes.mf')
+ <package>/ name of a package (e.g., `mfpic')
+ metapost/ MetaPost input and support files
+ base/ base distribution (e.g., `plain.mp')
+ misc/ single-file packages
+ <package>/ name of a package
+ support/ support files for MetaPost-related utilities
+ mft/ `MFT' inputs (e.g., `plain.mft')
+ <program>/ TeX-related programs, by name (e.g., `dvips')
+ source/ program source code by name (e.g., `latex', `web2c')
+ tex/ TeX input files
+ <engine>/ name of an engine (e.g., `aleph'); can also be lower
+ <format>/ name of a format (e.g., `plain')
+ base/ base distribution for format (e.g., `plain.tex')
+ misc/ single-file packages (e.g., `webmac.tex')
+ local/ local additions to or local configuration files for `FORMAT'
+ <package>/ name of a package (e.g., `graphics', `mfnfss')
+ generic/ format-independent packages
+ hyphen/ hyphenation patterns (e.g., `hyphen.tex')
+ images/ image input files (e.g., Encapsulated PostScript)
+ misc/ single-file format-independent packages (e.g., `null.tex').
+ <package>/ name of a package (e.g., `babel')
+
+* Menu:
+
+* Documentation tree summary::
+
+
+File: tds.info, Node: Documentation tree summary, Up: Summary
+
+4.1 Documentation tree summary
+==============================
+
+An example skeleton of a TDS directory tree under `texmf/doc'. This is
+not to imply these are the only entries allowed, or that this structure
+must be followed precisely for the entries listed.
+
+ As mentioned, the `texmf/doc' tree may be organized by language, so
+that all documentation in French, say, is in a `french' subdirectory.
+In that case, the example structure here would be in a given language
+directory.
+
+ ams/
+ amsfonts/ `amsfonts.faq', `amfndoc'
+ amslatex/ `amslatex.faq', `amsldoc'
+ amstex/ `amsguide', `joyerr'
+ bibtex/ BibTeX
+ base/ `btxdoc.tex'
+ fonts/
+ fontname/ `Filenames for TeX fonts'
+ oldgerm/ `corkpapr'
+ <format>/ name of a TeX format (e.g., `generic', `latex')
+ base/ for the base distribution
+ misc/ for contributed single-file package documentation
+ <package>/ for _package_
+ general/ across programs, generalities
+ errata/ `errata', `errata[1-8]'
+ texcomp/ `Components of TeX'
+ help/ meta-information
+ ctan/ info about CTAN mirror sites
+ faq/ FAQs of `comp.text.tex', etc.
+ info/ GNU Info files, made from Texinfo sources
+ latex/ example of `FORMAT'
+ base/ `ltnews*', `*guide', etc.
+ graphics/ `grfguide'
+ local/ site-specific documentation
+ man/ Unix man pages
+ <program>/ TeX-related programs, by name (examples follow)
+ metafont/ `mfbook.tex', `metafont-for-beginners', etc.
+ metapost/ `mpman', `manfig', etc.
+ tex/ `texbook.tex', `A Gentle Introduction to TeX', etc.
+ web/ `webman', `cwebman'
+
+
+File: tds.info, Node: Unspecified pieces, Next: Implementation issues, Prev: Summary, Up: Top
+
+Appendix A Unspecified pieces
+*****************************
+
+The TDS cannot address the following aspects of a functioning TeX
+system:
+
+ 1. The location of executable programs: this is too site-dependent
+ even to recommend a location, let alone require one. A site may
+ place executables outside the `texmf' tree altogether (e.g.,
+ `/usr/local/bin'), in a platform-dependent directory within
+ `texmf', or elsewhere.
+
+ 2. Upgrading packages when new releases are made: we could find no
+ way of introducing version specifiers into `texmf' that would do
+ more good than harm, or that would be practical for even a
+ plurality of installations.
+
+ 3. The location of implementation-specific files (e.g., TeX `.fmt'
+ files): by their nature, these must be left to the implementor or
+ TeX maintainer. See Section *Note Example implementation-specific
+ trees::.
+
+ 4. Precisely when a package or file should be considered "local", and
+ where such local files are installed. See Section *Note Local
+ additions:: for more discussion.
+
+
+* Menu:
+
+* Portable filenames::
+
+
+File: tds.info, Node: Portable filenames, Up: Unspecified pieces
+
+A.1 Portable filenames
+======================
+
+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.
+
+ 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:
+
+ * File and directory names, not including any directory path or
+ extension part, may not exceed eight characters.
+
+ * Filenames may have a single extension. Extensions may not exceed
+ three characters. Directory names may not have an extension.
+
+ * Names and extensions may consist of _only_ the characters `A'-`Z',
+ `0'-`9', and underscore. Lowercase letters are excluded.
+
+ * A period separates the filename from the extension and is always
+ present, even if the name or extension is missing (e.g.,
+ `FILENAME.' or `.EXT').
+
+ * A version number, ranging from 1-32767, is appended to the file
+ extension, separated by a semicolon (e.g., `FILENAME.EXT;1').
+
+ * Only eight directory levels are allowed, including the top-level
+ (mounted) directory (see Section *Note Rooting the tree::). Thus,
+ the deepest valid ISO-9660 path is:
+ texmf/L2/L3/L4/L5/L6/L7/L8/FOO.BAR;1
+ 1 2 3 4 5 6 7 8
+ The deepest TDS path needs only seven levels:
+ texmf/fonts/pk/cx/public/cm/dpi300/cmr10.pk
+ 1 2 3 4 5 6 7
+
+
+ Some systems display a modified format of ISO-9660 names, mapping
+alphabetic characters to lowercase, removing version numbers and
+trailing periods, etc.
+
+ Before the December 1996 release, LaTeX used mixed-case names for
+font descriptor files. Fortunately, it never relied on case alone to
+distinguish among the files. Nowadays, it uses only monocase names.
+
+
+File: tds.info, Node: Implementation issues, Next: Is there a better way?, Prev: Unspecified pieces, Up: Top
+
+Appendix B Implementation issues
+********************************
+
+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 "drop-in" distribution packages for TeX.
+
+* Menu:
+
+* Adoption of the TDS::
+* More on subdirectory searching::
+* Example implementation-specific trees::
+
+
+File: tds.info, Node: Adoption of the TDS, Next: More on subdirectory searching, Up: Implementation issues
+
+B.1 Adoption of the TDS
+=======================
+
+[This section is retained for historical purposes; the TDS is now quite
+firmly entrenched in most TeX distributions.]
+
+ 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:
+
+ * Clear and demonstrable benefits can be shown for the TDS.
+
+ * TDS-compliant versions of all key programs are available in
+ ported, well-tested forms.
+
+ * A "settling" period has taken place, to flush out problems. The
+ public release of the first draft of this document was the first
+ step in this process.
+
+ 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 *Note Related references:: 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.
+
+ 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.
+
+ 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.
+
+ 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.
+
+ 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.
+
+
+File: tds.info, Node: More on subdirectory searching, Next: Example implementation-specific trees, Prev: Adoption of the TDS, Up: Implementation issues
+
+B.2 More on subdirectory searching
+==================================
+
+Recursive subdirectory searching is the ability to specify a search not
+only of a specified directory `D', but recursively of all directories
+below `D'.
+
+ 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.
+
+ 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&YTeX. The
+Kpathsea library is a reusable implementation of subdirectory searching
+for TeX, used in a number of the above programs.
+
+ Even if your TeX implementation does not directly support
+subdirectory searching, you may find it useful to adopt the structure if
+you do not use many fonts or packages. For instance, if you only use
+Computer Modern and AMS fonts, it would be feasible to store them in
+the TDS layout and list the directories individually in configuration
+files or environment variables.
+
+ 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 *Note Subdirectory searching::. Implementors
+are encouraged to provide enhancements to the basic principle of
+subdirectory searching to avoid performance problems, e.g., the use of
+a filename cache (this can be as simple as a recursive directory
+listing) that is consulted before disk searching begins. If a match is
+found in the database, subdirectory searching is not required, and
+performance is thus independent of the number of subdirectories present
+on the system.
+
+ Different implementations specify subdirectory searching differently.
+In the interest of typographic clarity, the examples here do not use the
+`REPLACEABLE' font.
+
+ * Dvips: via a separate `TEXFONTS_SUBDIR' environment variable.
+
+ * emTeX: `t:\subdir!!'; `t:\subdir!' for a single level of searching.
+
+ * Kpathsea: `texmf/subdir//'
+
+ * VMS: `texmf:[subdir...]'
+
+ * Xdvi (patchlevel 20): `texmf/subdir/**'; `texmf/subdir/*' for a
+ single level of searching. Version 20.50 and above support the
+ `//' notation.
+
+ * Y&Y TeX: `t:/subdir//' or `t:\subdir\\'.
+
+
+
+File: tds.info, Node: Example implementation-specific trees, Prev: More on subdirectory searching, Up: Implementation issues
+
+B.3 Example implementation-specific trees
+=========================================
+
+The TDS cannot specify a precise location for implementation-specific
+files, such as `texmf/ini', because a site may have multiple TeX
+implementations.
+
+ Nevertheless, for informative purposes, we provide here the default
+locations for some implementations. Please contact us with additions or
+corrections. These paths are not definitive, may not match anything at
+your site, and may change without warning.
+
+ We recommend all implementations have default search paths that start
+with the current directory (e.g., `.'). Allowing users to include the
+parent directory (e.g., `..') is also helpful.
+
+* Menu:
+
+* AmiWeb2c 2.0::
+* Public DECUS TeX::
+* Web2c 7::
+
+
+File: tds.info, Node: AmiWeb2c 2.0, Next: Public DECUS TeX, Up: Example implementation-specific trees
+
+B.3.1 AmiWeb2c 2.0
+------------------
+
+(Email <scherer@physik.rwth-aachen.de> to contact the maintainer of
+this implementation.)
+
+ AmiWeb2c 2 is compatible with Web2c 7 to the greatest possible
+extent, so only the very few differences are described in this section.
+Detailed information about the basic concepts is given in the section
+for Web2c 7 below.
+
+ Thanks to the `SELFAUTO' mechanism of Kpathsea 3.0 no specific
+location for the installation of AmiWeb2c is required as long as the
+general structure of the distribution is preserved.
+
+ In addition to Kpathsea's `//' notation recursive path search may
+also be started by `DEVICE:/', e.g., `TeXMF:/' will scan this specific
+device completely.
+
+ Binaries coming with the AmiWeb2c distribution are installed in the
+directory `bin/amiweb2c/' outside the common TDS tree `share/texmf/'.
+In addition to the set of AmiWeb2c binaries you will find two
+subdirectories `local/' and `pastex/' with auxiliary programs.
+
+ A stripped version of the PasTeX system (used by kind permission of
+Georg Hessmann) is coming with AmiWeb2c, pre-installed in its own
+`share/texmf/amiweb2c/pastex/' directory. If you want to use PasTeX
+you have to `assign' the name `TeX:' to this place.
+
+ Documentation files in AmigaGuide format should be stored at
+`doc/guide/' similar to `doc/info/'.
+
+
+File: tds.info, Node: Public DECUS TeX, Next: Web2c 7, Prev: AmiWeb2c 2.0, Up: Example implementation-specific trees
+
+B.3.2 Public DECUS TeX
+----------------------
+
+If another VMS implementation besides Public DECUS TeX appears, the top
+level implementation directory name will be modified to something more
+specific (e.g., `vms_decus').
+
+ 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
+
+
+File: tds.info, Node: Web2c 7, Prev: Public DECUS TeX, Up: Example implementation-specific trees
+
+B.3.3 Web2c 7
+-------------
+
+All implementation-dependent TeX system files (`.pool', `.fmt',
+`.base', `.mem') are stored by default directly in `texmf/web2c'. The
+configuration file `texmf.cnf' and various subsidiary `MakeTeX...'
+scripts used as subroutines are also stored there.
+
+ Non-TeX specific files are stored following the GNU coding
+standards. Given a root directory `PREFIX' (`/usr/local' by default),
+we have default locations as follows:
+
+ <prefix>/ installation root (`/usr/local' by default)
+ bin/ executables
+ man/ man pages
+ info/ info files
+ lib/ libraries (`libkpathsea.*')
+ share/ architecture-independent files
+ texmf/ TDS root
+ web2c/ implementation-dependent files (`.pool', `.fmt', `texmf.cnf', etc.)
+
+ See `http://www.gnu.org/prep/standards_toc.html' for the rationale
+behind and descriptions of this arrangement. A site may of course
+override these defaults; for example, it may put everything under a
+single directory such as `/usr/local/texmf'.
+
+
+File: tds.info, Node: Is there a better way?, Next: Related references, Prev: Implementation issues, Up: Top
+
+Appendix C Is there a better way?
+*********************************
+
+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 "made sense").
+
+ Some interesting ideas could not be applied due to implementations
+lacking the necessary support:
+
+ * 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.
+
+ * Multiple logical `texmf' trees. For example, a site might have one
+ (read-only) location for stable files, and a different (writable)
+ location for dynamically-created fonts or other files. It would be
+ reasonable for two such trees to be logically merged when
+ searching. See Michael Downes' article in the references for how
+ this can work in practice with Web2C.
+
+
+* Menu:
+
+* Macro structure::
+* Font structure::
+* Documentation structure::
+
+
+File: tds.info, Node: Macro structure, Next: Font structure, Up: Is there a better way?
+
+C.1 Macro structure
+===================
+
+The TWG settled on the `FORMAT/PACKAGE' arrangement after long
+discussion about how best to arrange the files.
+
+ The primary alternative to this arrangement was a scheme which
+reversed the order of these directories: `PACKAGE/FORMAT'. This
+reversed arrangement has a strong appeal: it keeps all of the files
+related to a particular package in a single place. The arrangement
+actually adopted tends to spread files out into two or three places
+(macros, documentation, and fonts, for example, are spread into
+different sections of the tree right at the top level).
+
+ Nevertheless, the `FORMAT/PACKAGE' structure won for a couple of
+reasons:
+
+ * 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.
+
+ * 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.
+
+
+
+File: tds.info, Node: Font structure, Next: Documentation structure, Prev: Macro structure, Up: Is there a better way?
+
+C.2 Font structure
+==================
+
+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.
+
+* Menu:
+
+* Font file type location::
+* Mode and resolution location::
+* Modeless bitmaps::
+
+
+File: tds.info, Node: Font file type location, Next: Mode and resolution location, Up: Font structure
+
+C.2.1 Font file type location
+-----------------------------
+
+We considered the supplier-first arrangement in use at many sites:
+
+ texmf/fonts/SUPPLIER/TYPEFACE/TYPE/
+
+ 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 `TFM'
+file, the simplest implementation would require TeX to search through
+all the directories that contain PK files in all modes and at all
+resolutions.
+
+ In the end, a poll of developers revealed considerable resistance to
+implementing sufficient caching mechanisms, so this arrangement was
+abandoned. The TDS arrangement allows the search tree to be restricted
+to the correct type of file, at least. Concerns about efficiency
+remain, but there seems to be no more we can do without abandoning
+subdirectory searching entirely.
+
+ We also considered segregating all font-related files strictly by
+file type, so that Metafont sources would be in a directory
+`texmf/fonts/mf', property list files in `texmf/fonts/pl', the various
+forms of Type 1 fonts separated, and so on. Although more blindly
+consistent, we felt that the drawback of more complicated path
+constructions outweighed this. The TDS merges file types (`mf' and `pl'
+under `source', `pfa' and `pfb' and `gsf' under `type1') where we felt
+this was beneficial.
+
+
+File: tds.info, Node: Mode and resolution location, Next: Modeless bitmaps, Prev: Font file type location, Up: Font structure
+
+C.2.2 Mode and resolution location
+----------------------------------
+
+We considered having the `mode' at the bottom of the font tree:
+ texmf/fonts/pk/SUPPLIER/TYPEFACE/MODE/DPI/
+
+ In this case, however, it is difficult to limit subdirectory
+searching to the mode required for a particular device.
+
+ We then considered moving the `dpiNNN' up to below the mode:
+ texmf/fonts/pk/MODE/DPI/SUPPLIER/TYPEFACE/
+
+ But then it is not feasible to omit the `dpiNNN' level altogether on
+systems which can and do choose to use long filenames.
+
+
+File: tds.info, Node: Modeless bitmaps, Prev: Mode and resolution location, Up: Font structure
+
+C.2.3 Modeless bitmaps
+----------------------
+
+The TDS specifies using a single directory `modeless/' as the mode name
+for those utilities which generate bitmaps, e.g.,
+`texmf/fonts/modeless/times/'. This has the considerable advantage of
+not requiring each such directory name to be listed in a search path.
+
+ An alternative was to use the utility name below which all such
+directories could be gathered. That has the advantage of separating,
+say, `gsftopk'-generated bitmaps from `ps2pk'-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 `PK_ID' byte.
+
+ 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 `mfcx'
+vs. `xyzcx' 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 happen.
+
+
+File: tds.info, Node: Documentation structure, Prev: Font structure, Up: Is there a better way?
+
+C.3 Documentation structure
+===========================
+
+We considered placing additional documentation files in the same
+directory as the source files for the packages, but we felt that users
+should be able to find documentation separately from sources, since most
+users have no interest in sources.
+
+ We hope that a separate, but parallel, structure for documentation
+would (1) keep the documentation together and (2) make it as
+straightforward as possible for users to find the particular
+documentation they were after.
+
+
+File: tds.info, Node: Related references, Next: Contributors, Prev: Is there a better way?, Up: Top
+
+Appendix D Related references
+*****************************
+
+This appendix gives pointers to related files and other documents. For
+CTAN references, we use `http://www.ctan.org' as the top-level domain
+only to make the links be live in this document. See
+`http://www.ctan.org/tex-archive/CTAN.sites' for a complete list of
+CTAN sites; there are mirrors worldwide.
+
+ * This document, in many formats (tex, dvi, info, pdf):
+ `http://tug.org/tds/'
+
+ * The TDS mailing list archives:
+ `http://tug.org/mail-archives/twg-tds/'
+
+ * The level 0 DVI driver standard:
+ `http://www.ctan.org/tex-archive/dviware/driv-standard/level-0/'
+
+ * `Filenames for TeX fonts', with lists of recommended supplier and
+ typeface names:
+ `http://tug.org/fontname/'
+
+ * ISO-9660 CD-ROM file system standard:
+ `http://www.iso.ch/cate/cat.html'
+
+ * `Components of TeX', a paper by Joachim Schrod:
+ `http://www.ctan.org/tex-archive/documentation/components-of-TeX/'
+
+ * `Managing Multiple TDS trees', an article by Michael Downes:
+ `http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf'
+
+ * A complete set of Metafont modes:
+ `http://www.ctan.org/tex-archive/fonts/modes/modes.mf'
+
+ * A large collection of BibTeX databases and styles:
+ `ftp://ftp.math.utah.edu/pub/tex/bib/'
+
+
+
+File: tds.info, Node: Contributors, Prev: Related references, Up: Top
+
+Appendix E Contributors
+***********************
+
+The TWG has had no physical meetings; electronic mail was the
+communication medium.
+
+ Sebastian Rahtz is the TeX Users Group Technical Council liaison.
+Norman Walsh was the original committee chair. Karl Berry is the
+current editor.
+
+ The list of contributors has grown too large to fairly include, as
+some would surely be inadvertently omitted. Please consider the
+archives of the <tds@tug.org> and <tex-live@tug.org> mailing lists as
+the record of contributions.
+
+
+
+Tag Table:
+Node: Top198
+Node: Introduction2185
+Node: History3846
+Node: The role of the TDS4648
+Node: Conventions5508
+Node: General6429
+Node: Subdirectory searching6714
+Node: Rooting the tree8968
+Node: Local additions10080
+Node: Duplicate filenames12293
+Node: Top-level directories14054
+Node: Macros17062
+Node: Extensions20919
+Node: Fonts22645
+Node: Font bitmaps26786
+Node: Valid font bitmaps29674
+Node: Non-font Metafont files30882
+Node: MetaPost31842
+Node: BibTeX33286
+Node: Scripts34155
+Node: Documentation35872
+Node: Summary38145
+Node: Documentation tree summary41031
+Node: Unspecified pieces43056
+Node: Portable filenames44267
+Node: Implementation issues46409
+Node: Adoption of the TDS47041
+Node: More on subdirectory searching49753
+Node: Example implementation-specific trees52568
+Node: AmiWeb2c 2.053447
+Node: Public DECUS TeX54889
+Node: Web2c 755752
+Node: Is there a better way?56974
+Node: Macro structure58480
+Node: Font structure59816
+Node: Font file type location60369
+Node: Mode and resolution location61946
+Node: Modeless bitmaps62625
+Node: Documentation structure63915
+Node: Related references64543
+Node: Contributors65959
+
+End Tag Table