[Debian-tex-commits] SVN tex-common commit + diffs: r1986 -
tex-common/trunk/doc/tds-1.1
Frank Küster
frank at alioth.debian.org
Wed Dec 6 17:12:46 CET 2006
Author: frank
Date: 2006-12-06 17:12:46 +0100 (Wed, 06 Dec 2006)
New Revision: 1986
Added:
tex-common/trunk/doc/tds-1.1/ChangeLog
tex-common/trunk/doc/tds-1.1/Makefile
tex-common/trunk/doc/tds-1.1/index.html
tex-common/trunk/doc/tds-1.1/packages.zip
tex-common/trunk/doc/tds-1.1/tds.aux
tex-common/trunk/doc/tds-1.1/tds.dvi
tex-common/trunk/doc/tds-1.1/tds.html
tex-common/trunk/doc/tds-1.1/tds.info
tex-common/trunk/doc/tds-1.1/tds.pdf
tex-common/trunk/doc/tds-1.1/tds.sed
tex-common/trunk/doc/tds-1.1/tds.tex
tex-common/trunk/doc/tds-1.1/tds.texi
tex-common/trunk/doc/tds-1.1/tds.texi.tmp
tex-common/trunk/doc/tds-1.1/tds2texi.el
tex-common/trunk/doc/tds-1.1/tdsguide.cls
Log:
add tds sources
Added: tex-common/trunk/doc/tds-1.1/ChangeLog
===================================================================
--- tex-common/trunk/doc/tds-1.1/ChangeLog 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/ChangeLog 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1,312 @@
+2004-06-23 Karl Berry <karl at gnu.org>
+
+ * tds.tex: version 1.1.
+ * tds.tex: make that june 2004.
+
+2004-06-08 Karl Berry <karl at gnu.org>
+
+ * tds.tex: type3, version 1.096.
+
+2004-06-06 Karl Berry <karl at gnu.org>
+
+ * tds.tex: 1.095 (still draft).
+
+2004-06-04 Karl Berry <karl at gnu.org>
+
+ * tds2texi.el [ ] doesn't make sense; changed to "\s ".
+ * tds.tex: use \TeX{} uniformly, not \TeX\ , since that's what
+ tds2texi.el handles. We ended up with "Inputs for, TeX".
+ Report from: Hans Fredrik Nordhaug,
+ 2 Jun 2004 23:01:15 +0200.
+
+ * tds2texi.el (tds2texi-fixup-texinfo): fix the reference to the
+ "Non-font Metafont" node here instead.
+ * tds.sed: no non-font special case.
+
+ * tds.tex: specify opentype and truetype under fonts.
+
+2004-06-03 Karl Berry <karl at gnu.org>
+
+ * tds2texi.el (tds2texi-logos-alist): Metafont instead of
+ METAFONT.
+
+2004-05-15 Karl Berry <karl at gnu.org>
+
+ * tds.tex: doc/ subtree improvements from Chris Rowley, and more.
+
+2004-05-14 Karl Berry <karl at gnu.org>
+
+ * 1.094.
+ * tds.tex: clarify description of enc & map, maybe.
+
+2004-05-08 Karl Berry <karl at gnu.org>
+
+ * tds.tex: fixes from Staszek.
+ * tds.tex: check in.
+
+2004-04-03 Karl Berry <karl at gnu.org>
+
+ * Makefile (packages.zip): new target.
+ (dist): depend on it, and include it in
+ distribution tar file.
+
+ * tds.tex: wording improvement from vojta, 1.093.
+
+2004-03-28 Karl Berry <karl at gnu.org>
+
+ * tdsguide.cls (\tdsSummary): \let\obeylines=\relax after we set
+ it, so url.sty v3.0's usage of \obeylines does not cause errors.
+
+ * tds.tex (etex): fix in tds example.
+
+2004-03-27 Karl Berry <karl at gnu.org>
+
+ * tds.tex: 1.092, move extension input files within tex. also
+ check in from previous changes, notably new scripts/ dir.
+
+2004-02-11 Karl Berry <karl at gnu.org>
+
+ * tds.tex: pfm text, etc., from feb03.
+
+2003-02-02 <karl at gnu.org>
+
+ * tds.tex: 1.0
+
+2003-01-18 <karl at gnu.org>
+
+ * Version 0.9998.
+
+ * tds.tex: force line breaks in references, add Downs reference.
+ * tds2texi.el: handle \\ in references section.
+ * Makefile (tds.texi.tmp): don't read emacs init files.
+
+2003-01-17 <karl at gnu.org>
+
+ * tds2texi.el: doc fixes, @tie.
+ * tds.tex: enc/maps vs fontname clarification, removal of some
+ history.
+
+2003-01-12 <karl at gnu.org>
+
+ * tds.tex: first cut at fonts/enc and fonts/map, version 0.9997.
+ * Makefile: clean up directory for dist, and remake everything.
+ * Makefile: use makeinfo --no-split.
+
+Mon Jul 19 16:54:37 1999 Karl Berry <karl at gnu.org>
+
+ * tds2texi.el (tds2texi-fixup-texinfo): Don't need to do this with
+ Emacs 20.4, at least.
+
+Sun Jul 11 12:55:53 1999 Karl Berry <karl at gnu.org>
+
+ * tds.tex: I have a new address.
+
+Wed Apr 21 15:30:34 1999 Karl Berry <karl at gnu.org>
+
+ * version 0.9996.
+
+ * tds2texi.el: @ifnottex, not @ifinfo.
+
+ * Grammar fixes (Demitrios Athens).
+ Non-font METAFONT section title (Reinhard Kotucha).
+ Mention Kpathsea as a sample implementation (Paul Abrahams).
+ Allow discretion for single-file packages of all kinds (Matthew Swift).
+
+ * fancyhdr.sty: get latest version.
+
+1998-01-26 Karl Berry <karl at cs.umb.edu>
+
+ * tds.tex: Version 0.9995: add extension section.
+
+ * tdsguide.cls (\TeXinfo): Remove unused and incorrect name.
+ (\parsep): Decrease slightly.
+ (\l at section): Decrease section spacing for toc slightly.
+ (\@maketitle): Remove word `draft'.
+
+Fri Jan 23 17:14:01 1998 Karl Berry <karl at cs.umb.edu>
+
+ * tds.tex: checkin 0.9994.
+
+Sun Jul 20 16:29:37 1997 Karl Berry <karl at cs.umb.edu>
+
+ * Version 0.9994.
+
+ * tds2texi.el: We can do @ss.
+
+ * tds2texi.el: Texinfo @url is now @uref.
+
+Fri Feb 7 15:47:17 1997 Karl Berry <karl at cs.umb.edu>
+
+ * tds2texi.el: @detailmenu, other fixes, from Ulrik.
+
+ * tdsguide.cls: Fix : in tdsSummary, more doc.
+
+Tue Feb 4 16:27:56 1997 Karl Berry <karl at cs.umb.edu>
+
+ * Version 0.9992.
+
+ * tds.tex: Replace gsftopk/ps2pk/etc. with just `modeless'.
+
+Tue Nov 19 01:24:46 1996 Ulrik Vieth <vieth at thphy.uni-duesseldorf.de>
+
+ * tds.tex: Fix up indentation in `tdsSummary' environments
+ for the sake of Texinfo, should be consistent everywhere now.
+
+ * tds2texi.el: Fix bug when combining multiple @file tags.
+ Added some missing functionality from tds.sed and tds.awk.
+
+ * tds.sed: Handle a few translations in Elisp where possible.
+ Only leave those that are specific to document context.
+
+ * tds.awk: File made redundant.
+
+ * Makefile: Eliminate unnecessary gawk translation step.
+
+Sat Nov 16 07:16:03 1996 Karl Berry <karl at cs.umb.edu>
+
+ * tds.tex: Version 0.991.
+
+ * tds2texi.el: More logos; no extra blank lines after sections;
+ handle \url and \email like \path.
+
+ * tds.awk, tds.sed: New files.
+
+ * url.sty, mflogo.sty, Ulogo.fd: Get latest versions.
+
+ * tdsguide.cls: Changes for 0.9991.
+
+Tue Nov 12 17:16:54 1996 Karl Berry <karl at cs.umb.edu>
+
+ * tdsguide.cls: Saving version as of 0.999.
+
+Sun Nov 10 17:36:36 1996 Karl Berry <karl at cs.umb.edu>
+
+ * Mention texmf/ini loses.
+ * Say that the mode/ level is not optional.
+
+ * Mention the possibility of doc/<language>.
+ From Sebastian.
+
+ * Include AmiWeb2c 2.0 summary.
+ From: <Scherer at physik.rwth-aachen.de>
+
+ * Allow distribution of modified versions as long they don't
+ pretend to be the TDS.
+
+ * tds.tex: 0.999.
+
+Thu Nov 30 11:41:58 1995 Karl Berry <karl at cs.umb.edu>
+
+ * tds.tex: pnr10.tfm should be pnr10.mf. From Pierre.
+
+Wed Nov 22 11:46:51 1995 Karl Berry <karl at cs.umb.edu>
+
+ * tds.tex: Some periods after capital letters end sentences, and
+ some periods after lowercase don't. From bb.
+ Remove make uninstall text.
+
+Tue Nov 21 19:56:35 1995 Karl Berry <karl at cs.umb.edu>
+
+ * Version 0.999 sent to TUGboat (well, not really).
+
+Wed Nov 15 19:50:37 1995 Karl Berry <karl at cs.umb.edu>
+
+ * Version 0.104. Public release.
+
+ * tds.tex: Add tex/generic/images to the figure.
+
+Sat Nov 11 11:47:16 1995 Karl Berry <karl at cs.umb.edu>
+
+ * tds.tex: Mention the possibility of multiple texmf's. Fix
+ non-sentence. From Paul Abrahams.
+
+ * Version 0.103.
+
+ * Move filename constraints to an appendix; we don't require this.
+
+Fri Oct 27 14:04:09 1995 Karl Berry <karl at cs.umb.edu>
+
+ * Version 0.102.
+
+ * Include package subdirectories under bibtex.
+
+ * Version 0.101.
+
+Tue Oct 17 13:22:08 1995 Karl Berry <karl at cs.umb.edu>
+
+ - Mention what `texmf' stands for.
+ - Info documents might be stored outside the tree.
+ - Recommend PK specials, rather require them.
+ - Try to define format and package a bit more clearly.
+ - Explicitly unspecify when something is local.
+ These things from Paul Abrahams.
+
+Sat Oct 14 16:07:16 1995 Karl Berry <karl at cs.umb.edu>
+
+ * Version 0.100.
+
+Fri Oct 13 16:23:34 1995 Karl Berry <karl at cs.umb.edu>
+
+ * tdsguide.cls (\textwidth): Make a little larger. Don't bother
+ reading tdsguide.cfg just to get mflogo.
+
+ - Mention that a format author doesn't have to have a <format>
+ directory.
+ - Don't use makeindx as an example.
+
+Thu Oct 12 14:19:25 1995 Karl Berry <karl at cs.umb.edu>
+
+ - Add Christian Spieler to the author list.
+ - Reserve tex/images for eps files etc.
+ - Remove implication the texmf/tex/plain has no subdirectories.
+ - More implementation-specific stuff, this time under
+ `program'. From Alex Kok et al.
+ - Expound on texmf/source a bit. From Alex Kok.
+ - Tell people to go read if we're talking about mysteries
+ - Remove all instances of the confusing word `application'.
+ - Mention that examples are documentation, and move discussion of
+ the alternative to an appendix.
+
+Tue Oct 10 15:45:32 1995 Karl Berry <karl at cs.umb.edu>
+
+ - New section on duplicate filenames.
+ - Image files are likely to go under texmf/tex.
+ - Printers can have multiple resolutions. From Bernard Gaulle.
+ - Reference the level 0 DVI standard.
+ - Define `dpi' better. From Nelson Beebe, David Kastrup.
+ - Document the reasons for not using modeless/. From David Kastrup.
+ - Mention the (presently impractical) possibility of \input
+ latex2e/file.tex. From Paul Vojta.
+ - make uninstall or an equivalent is desirable. From Alan Dunwell.
+ - Remove `files are...' text. From Doug Waud.
+ - /opt is another likely root. From Jeff Gealow.
+ - Use dpiNNN, not just dpi. From Bart Childs.
+ - Slightly improved description of MP. From Bart.
+ - Recommend . at beginning of search paths. From DEK via Sebastian.
+ - Include musictex as an example generic/ directory.
+
+Mon Oct 9 17:36:27 1995 Karl Berry <karl at cs.umb.edu>
+
+ - mft/ is no longer a special case under tex/.
+ - Move `package distribution' to an appendix section.
+
+Fri Oct 6 17:23:15 1995 Karl Berry <karl at cs.umb.edu>
+
+ - Remove \protect. From Ulrik.
+
+Wed Oct 4 15:08:01 1995 Karl Berry <karl at cs.umb.edu>
+
+ * Version 0.99.
+ - Don't hardwire version number in more than place.
+ - Use TUG instead of O'Reilly for postal mail.
+ - texmf/tex// does not suffice in general.
+ - Incorporate `subdirectory searching syntax' section into main
+ subdir searching section, and `Expeding the Process' into
+ `Adoption of the TDS'.
+ - Move bin/ out of the main text.
+ - Reserve `local' at every level.
+ - Top-level directories should be a chapter, and
+ implementation-specific files need more discussion.
+ - Make macros, fonts, etc. sections under the top-level
+ directories chapter.
+
Added: tex-common/trunk/doc/tds-1.1/Makefile
===================================================================
--- tex-common/trunk/doc/tds-1.1/Makefile 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/Makefile 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1,44 @@
+# $Id: Makefile,v 1.5 2004/04/04 00:14:59 karl Exp karl $
+# Makefile for tds, by Karl Berry.
+# Public domain.
+
+default all: tds.info tds.html tds.dvi tds.pdf
+
+tds.dvi: tds.tex tdsguide.cls
+ latex '\nonstopmode \input tds'
+
+tds.pdf: tds.tex tdsguide.cls
+ pdflatex '\nonstopmode \input tds'
+
+tds.texi: tds.texi.tmp tds.sed
+ sed -f tds.sed $< >$@
+
+tds.texi.tmp: tds.tex tds2texi.el
+ emacs -q --no-site -batch -l tds2texi.el -f tds2texi-convert --eval '(write-file "$@")'
+
+tds.info: tds.texi
+ makeinfo --no-split $<
+
+tds_toc.html: tds.texi /usr/local/gnu/bin/texi2html
+ texi2html -split_node -menu $<
+
+tds.html: tds.texi
+ makeinfo --number-sections --html --no-split $<
+
+check:
+ dw <tds.tex
+# chkdelim <tds.tex
+ ispell -t -l <tds.tex | sort -u
+
+# so that when we're mirrored on CTAN, we don't show up as a good place
+# to get these packages.
+packages.zip: Ulogo.fd fancyhdr.sty mflogo.sty url.sty
+ zip $@ $^
+
+dist: all packages.zip
+# -rcsdiff -c tds.tex >/tmp/diff
+ rm -f tds.texi* *~
+ rm -f tds.cp tds.fn tds.ky tds.pg tds.tp tds.vr tds.log tds.toc
+ tar cvvzf /tmp/tds.tar.gz C* M* tds* index.html packages.zip
+# shar -z tds.dvi >/tmp/shar
+# @echo "Now ci -l -m'version' tds.tex and increment the tdsVersion."
Added: tex-common/trunk/doc/tds-1.1/index.html
===================================================================
--- tex-common/trunk/doc/tds-1.1/index.html 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/index.html 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1 @@
+link tds.html
\ No newline at end of file
Property changes on: tex-common/trunk/doc/tds-1.1/index.html
___________________________________________________________________
Name: svn:special
+ *
Added: tex-common/trunk/doc/tds-1.1/packages.zip
===================================================================
(Binary files differ)
Property changes on: tex-common/trunk/doc/tds-1.1/packages.zip
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: tex-common/trunk/doc/tds-1.1/tds.aux
===================================================================
--- tex-common/trunk/doc/tds-1.1/tds.aux 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/tds.aux 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1,61 @@
+\relax
+\@writefile{toc}{\contentsline {section}{\numberline {1}Introduction}{2}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {1.1}History}{2}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {1.2}The role of the {\tds at reduced@size \uppercase {TDS}}}{2}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {1.3}Conventions}{3}}
+\@writefile{toc}{\contentsline {section}{\numberline {2}General}{3}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {2.1}Subdirectory searching}{3}}
+\newlabel{sec:Subdirectory searching}{{2.1}{3}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {2.2}Rooting the tree}{4}}
+\newlabel{sec:Rooting the tree}{{2.2}{4}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {2.3}Local additions}{4}}
+\newlabel{sec:Local additions}{{2.3}{4}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {2.4}Duplicate filenames}{5}}
+\newlabel{sec:Duplicate filenames}{{2.4}{5}}
+\@writefile{toc}{\contentsline {section}{\numberline {3}Top-level directories}{5}}
+\newlabel{sec:Top-level directories}{{3}{5}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.1}Macros}{6}}
+\newlabel{sec:Macros}{{3.1}{6}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {3.1.1}Extensions}{7}}
+\newlabel{sec:Extensions}{{3.1.1}{7}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.2}Fonts}{8}}
+\newlabel{sec:Fonts}{{3.2}{8}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {3.2.1}Font bitmaps}{9}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {3.2.2}Valid font bitmaps}{10}}
+\newlabel{sec:Valid font bitmaps}{{3.2.2}{10}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.3}Non-font \textlogo {META}\discretionary {-}{}{}\textlogo {FONT}\spacefactor \@m {} files}{10}}
+\newlabel{sec:Non-font MF files}{{3.3}{10}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.4}\textlogo {META}\discretionary {-}{}{}\textlogo {POST}\spacefactor \@m {}}{10}}
+\newlabel{sec:MetaPost}{{3.4}{10}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.5}B\kern -.05em{\tds at smsize IB}\kern -.08emT\kern -.1667em\lower .5ex\hbox {E}\kern -.125emX\spacefactor \@m {}}{11}}
+\newlabel{sec:BibTeX}{{3.5}{11}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.6}Scripts}{11}}
+\newlabel{sec:Scripts}{{3.6}{11}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.7}Documentation}{12}}
+\newlabel{sec:Documentation}{{3.7}{12}}
+\@writefile{toc}{\contentsline {section}{\numberline {4}Summary}{13}}
+\newlabel{sec:Summary}{{4}{13}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {4.1}Documentation tree summary}{14}}
+\newlabel{sec:Documentation tree summary}{{4.1}{14}}
+\@writefile{toc}{\contentsline {section}{\numberline {A}Unspecified pieces}{15}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {A.1}Portable filenames}{15}}
+\newlabel{sec:Portable filenames}{{A.1}{15}}
+\@writefile{toc}{\contentsline {section}{\numberline {B}Implementation issues}{16}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {B.1}Adoption of the {\tds at reduced@size \uppercase {TDS}}}{16}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {B.2}More on subdirectory searching}{17}}
+\newlabel{sec:More on subdirectory searching}{{B.2}{17}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {B.3}Example implementation-specific trees}{17}}
+\newlabel{sec:Example implementation-specific trees}{{B.3}{17}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {B.3.1}AmiWeb2c 2.0}{18}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {B.3.2}Public {\tds at reduced@size \uppercase {DECUS}} T\kern -.1667em\lower .5ex\hbox {E}\kern -.125emX\spacefactor \@m {}}{18}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {B.3.3}Web2c 7}{18}}
+\@writefile{toc}{\contentsline {section}{\numberline {C}Is there a better way?}{19}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.1}Macro structure}{19}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.2}Font structure}{20}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {C.2.1}Font file type location}{20}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {C.2.2}Mode and resolution location}{20}}
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {C.2.3}Modeless bitmaps}{21}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {C.3}Documentation structure}{21}}
+\@writefile{toc}{\contentsline {section}{\numberline {D}Related references}{21}}
+\newlabel{sec:Related references}{{D}{21}}
+\@writefile{toc}{\contentsline {section}{\numberline {E}Contributors}{22}}
Added: tex-common/trunk/doc/tds-1.1/tds.dvi
===================================================================
(Binary files differ)
Property changes on: tex-common/trunk/doc/tds-1.1/tds.dvi
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: tex-common/trunk/doc/tds-1.1/tds.html
===================================================================
--- tex-common/trunk/doc/tds-1.1/tds.html 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/tds.html 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1,2044 @@
+<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.8">
+<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; }
+ span.sansserif { font-family:sans-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: <a rel="next" accesskey="n" href="#Introduction">Introduction</a>,
+Up: <a rel="up" accesskey="u" href="#dir">(dir)</a>
+
+</div>
+
+<h2 class="unnumbered">A Directory Structure for TeX Files</h2>
+
+<p>Copyright © 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 “as
+is” 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 <!-- /@w --><a href="#Related-references">Related references</a>).
+Please send questions or suggestions by email to
+<a href="mailto:tds at tug.org">tds at 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: <a rel="next" accesskey="n" href="#General">General</a>,
+Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+
+</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 “right” 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—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 <!-- /@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: <a rel="next" accesskey="n" href="#The-role-of-the-TDS">The role of the TDS</a>,
+Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
+
+</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 <!-- /@w --><a href="#Extensions">Extensions</a>)
+<li>New top-level directory <samp><span class="file">scripts</span></samp> (Section <!-- /@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 <!-- /@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 <!-- /@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 <!-- /@w --><a href="#Fonts">Fonts</a>).
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="The-role-of-the-TDS"></a>
+Next: <a rel="next" accesskey="n" href="#Conventions">Conventions</a>,
+Previous: <a rel="previous" accesskey="p" href="#History">History</a>,
+Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
+
+</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: <a rel="previous" accesskey="p" href="#The-role-of-the-TDS">The role of the TDS</a>,
+Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
+
+</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, “TeX” generally means the TeX system, including
+Metafont, DVI drivers, utilities, etc., not just the TeX
+program itself.
+
+ <p>The word “package” 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: <a rel="next" accesskey="n" href="#Top_002dlevel-directories">Top-level directories</a>,
+Previous: <a rel="previous" accesskey="p" href="#Introduction">Introduction</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+
+</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: <a rel="next" accesskey="n" href="#Rooting-the-tree">Rooting the tree</a>,
+Up: <a rel="up" accesskey="u" href="#General">General</a>
+
+</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 <!-- /@w --><a href="#More-on-subdirectory-searching">More on subdirectory searching</a>).
+
+<div class="node">
+<p><hr>
+<a name="Rooting-the-tree"></a>
+Next: <a rel="next" accesskey="n" href="#Local-additions">Local additions</a>,
+Previous: <a rel="previous" accesskey="p" href="#Subdirectory-searching">Subdirectory searching</a>,
+Up: <a rel="up" accesskey="u" href="#General">General</a>
+
+</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 “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 <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: <a rel="next" accesskey="n" href="#Duplicate-filenames">Duplicate filenames</a>,
+Previous: <a rel="previous" accesskey="p" href="#Rooting-the-tree">Rooting the tree</a>,
+Up: <a rel="up" accesskey="u" href="#General">General</a>
+
+</div>
+
+<h3 class="section">2.3 Local additions</h3>
+
+<p>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.
+
+ <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: <a rel="previous" accesskey="p" href="#Local-additions">Local additions</a>,
+Up: <a rel="up" accesskey="u" href="#General">General</a>
+
+</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 <!-- /@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 <!-- /@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-level-directories"></a>
+<a name="Top_002dlevel-directories"></a>
+Next: <a rel="next" accesskey="n" href="#Summary">Summary</a>,
+Previous: <a rel="previous" accesskey="p" href="#General">General</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+
+</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 <!-- /@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 <!-- /@w --><a href="#Macros">Macros</a>).
+
+ <li>`<samp><span class="samp">fonts</span></samp>'
+for font-related files (Section <!-- /@w --><a href="#Fonts">Fonts</a>).
+
+ <li>`<samp><span class="samp">metafont</span></samp>'
+for Metafont files which are not fonts (Section <!-- /@w --><a href="#Non_002dfont-Metafont-files">Non-font Metafont files</a>).
+
+ <li>`<samp><span class="samp">metapost</span></samp>'
+for MetaPost files (Section <!-- /@w --><a href="#MetaPost">MetaPost</a>).
+
+ <li>`<samp><span class="samp">bibtex</span></samp>'
+for BibTeX files (Section <!-- /@w --><a href="#BibTeX">BibTeX</a>).
+
+ <li>`<samp><span class="samp">scripts</span></samp>'
+for platform-independent executables (Section <!-- /@w --><a href="#Scripts">Scripts</a>).
+
+ <li>`<samp><span class="samp">doc</span></samp>'
+for user documentation (Section <!-- /@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 “source file” 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 <!-- /@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 <!-- /@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 <!-- /@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: <a rel="next" accesskey="n" href="#Fonts">Fonts</a>,
+Up: <a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+
+</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 <!-- /@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 <!-- /@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: <a rel="up" accesskey="u" href="#Macros">Macros</a>
+
+</div>
+
+<h4 class="subsection">3.1.1 Extensions</h4>
+
+<p>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 <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 <!-- /@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—users, package authors, site
+administrators, and system distributors.
+
+ <p>Please contrast this approach with the <samp><var>implementation</var></samp>
+top-level subdirectory (Section <!-- /@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: <a rel="next" accesskey="n" href="#Non_002dfont-Metafont-files">Non-font Metafont files</a>,
+Previous: <a rel="previous" accesskey="p" href="#Macros">Macros</a>,
+Up: <a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+
+</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) <!-- /@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) <!-- /@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 <!-- /@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) <!-- /@w -->requested their own directory (e.g., <samp><span class="file">ams</span></samp>), nor
+(2) <!-- /@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 <!-- /@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 <!-- /@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 <!-- /@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: <a rel="next" accesskey="n" href="#Valid-font-bitmaps">Valid font bitmaps</a>,
+Up: <a rel="up" accesskey="u" href="#Fonts">Fonts</a>
+
+</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) <!-- /@w -->the type of device (i.e., mode) for
+which the font was created; (2) <!-- /@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 <!-- /@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 <!-- /@w -->0 DVI driver standard
+(see Appendix <!-- /@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: <a rel="previous" accesskey="p" href="#Font-bitmaps">Font bitmaps</a>,
+Up: <a rel="up" accesskey="u" href="#Fonts">Fonts</a>
+
+</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–10 magnifications for 2–3 modes. (Section <!-- /@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 <!-- /@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-font-Metafont-files"></a>
+<a name="Non_002dfont-Metafont-files"></a>
+Next: <a rel="next" accesskey="n" href="#MetaPost">MetaPost</a>,
+Previous: <a rel="previous" accesskey="p" href="#Fonts">Fonts</a>,
+Up: <a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+
+</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 <!-- /@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: <a rel="next" accesskey="n" href="#BibTeX">BibTeX</a>,
+Previous: <a rel="previous" accesskey="p" href="#Non_002dfont-Metafont-files">Non-font Metafont files</a>,
+Up: <a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+
+</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 <!-- /@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: <a rel="next" accesskey="n" href="#Scripts">Scripts</a>,
+Previous: <a rel="previous" accesskey="p" href="#MetaPost">MetaPost</a>,
+Up: <a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+
+</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 <!-- /@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: <a rel="next" accesskey="n" href="#Documentation">Documentation</a>,
+Previous: <a rel="previous" accesskey="p" href="#BibTeX">BibTeX</a>,
+Up: <a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+
+</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: <a rel="previous" accesskey="p" href="#Scripts">Scripts</a>,
+Up: <a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a>
+
+</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 <!-- /@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 <!-- /@w --><a href="#Documentation-tree-summary">Documentation tree summary</a> for a summary.
+
+<div class="node">
+<p><hr>
+<a name="Summary"></a>
+Next: <a rel="next" accesskey="n" href="#Unspecified-pieces">Unspecified pieces</a>,
+Previous: <a rel="previous" accesskey="p" href="#Top_002dlevel-directories">Top-level directories</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+
+</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
+ <package>/ 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
+ <package>/ name of a package
+ doc/ see Section <!-- /@w --><a href="#Documentation">Documentation</a> and the summary below
+ fonts/ font-related files
+ <type>/ file type (e.g., <samp><span class="file">pk</span></samp>)
+ <mode>/ type of output device (for <samp><span class="file">pk</span></samp> and <samp><span class="file">gf</span></samp> only)
+ <supplier>/ name of a font supplier (e.g., <samp><span class="file">public</span></samp>)
+ <typeface>/ name of a typeface (e.g., <samp><span class="file">cm</span></samp>)
+ dpi<nnn>/ font resolution (for <samp><span class="file">pk</span></samp> and <samp><span class="file">gf</span></samp> only)
+ <implementation>/ 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>)
+ <package>/ 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
+ <package>/ 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>)
+ <program>/ 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
+ <engine>/ name of an engine (e.g., <samp><span class="file">aleph</span></samp>); can also be lower
+ <format>/ 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>
+ <package>/ 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>).
+ <package>/ 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: <a rel="up" accesskey="u" href="#Summary">Summary</a>
+
+</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>
+ <format>/ 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
+ <package>/ 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
+ <program>/ 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: <a rel="next" accesskey="n" href="#Implementation-issues">Implementation issues</a>,
+Previous: <a rel="previous" accesskey="p" href="#Summary">Summary</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+
+</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 <!-- /@w --><a href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>.
+
+ <li>Precisely when a package or file should be considered “local”,
+and where such local files are installed. See Section <!-- /@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: <a rel="up" accesskey="u" href="#Unspecified-pieces">Unspecified pieces</a>
+
+</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>–<samp><span class="file">Z</span></samp>, <samp><span class="file">0</span></samp>–<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–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 <!-- /@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: <a rel="next" accesskey="n" href="#Is-there-a-better-way_003f">Is there a better way?</a>,
+Previous: <a rel="previous" accesskey="p" href="#Unspecified-pieces">Unspecified pieces</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+
+</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 “drop-in” 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: <a rel="next" accesskey="n" href="#More-on-subdirectory-searching">More on subdirectory searching</a>,
+Up: <a rel="up" accesskey="u" href="#Implementation-issues">Implementation issues</a>
+
+</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 “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.
+</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 <!-- /@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: <a rel="next" accesskey="n" href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>,
+Previous: <a rel="previous" accesskey="p" href="#Adoption-of-the-TDS">Adoption of the TDS</a>,
+Up: <a rel="up" accesskey="u" href="#Implementation-issues">Implementation issues</a>
+
+</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&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 <!-- /@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&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-specific-trees"></a>
+<a name="Example-implementation_002dspecific-trees"></a>
+Previous: <a rel="previous" accesskey="p" href="#More-on-subdirectory-searching">More on subdirectory searching</a>,
+Up: <a rel="up" accesskey="u" href="#Implementation-issues">Implementation issues</a>
+
+</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.0"></a>
+<a name="AmiWeb2c-2_002e0"></a>
+Next: <a rel="next" accesskey="n" href="#Public-DECUS-TeX">Public DECUS TeX</a>,
+Up: <a rel="up" accesskey="u" href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>
+
+</div>
+
+<h4 class="subsection">B.3.1 AmiWeb2c 2.0</h4>
+
+<p>(Email <a href="mailto:scherer at physik.rwth-aachen.de">scherer at 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ß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: <a rel="next" accesskey="n" href="#Web2c-7">Web2c 7</a>,
+Previous: <a rel="previous" accesskey="p" href="#AmiWeb2c-2_002e0">AmiWeb2c 2.0</a>,
+Up: <a rel="up" accesskey="u" href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>
+
+</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: <a rel="previous" accesskey="p" href="#Public-DECUS-TeX">Public DECUS TeX</a>,
+Up: <a rel="up" accesskey="u" href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a>
+
+</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"> <prefix>/ 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%3f"></a>
+<a name="Is-there-a-better-way_003f"></a>
+Next: <a rel="next" accesskey="n" href="#Related-references">Related references</a>,
+Previous: <a rel="previous" accesskey="p" href="#Implementation-issues">Implementation issues</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+
+</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 “made sense”).
+
+ <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: <a rel="next" accesskey="n" href="#Font-structure">Font structure</a>,
+Up: <a rel="up" accesskey="u" href="#Is-there-a-better-way_003f">Is there a better way?</a>
+
+</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: <a rel="next" accesskey="n" href="#Documentation-structure">Documentation structure</a>,
+Previous: <a rel="previous" accesskey="p" href="#Macro-structure">Macro structure</a>,
+Up: <a rel="up" accesskey="u" href="#Is-there-a-better-way_003f">Is there a better way?</a>
+
+</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: <a rel="next" accesskey="n" href="#Mode-and-resolution-location">Mode and resolution location</a>,
+Up: <a rel="up" accesskey="u" href="#Font-structure">Font structure</a>
+
+</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 <!-- /@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: <a rel="next" accesskey="n" href="#Modeless-bitmaps">Modeless bitmaps</a>,
+Previous: <a rel="previous" accesskey="p" href="#Font-file-type-location">Font file type location</a>,
+Up: <a rel="up" accesskey="u" href="#Font-structure">Font structure</a>
+
+</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: <a rel="previous" accesskey="p" href="#Mode-and-resolution-location">Mode and resolution location</a>,
+Up: <a rel="up" accesskey="u" href="#Font-structure">Font structure</a>
+
+</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 <!-- /@w -->happen.
+
+<div class="node">
+<p><hr>
+<a name="Documentation-structure"></a>
+Previous: <a rel="previous" accesskey="p" href="#Font-structure">Font structure</a>,
+Up: <a rel="up" accesskey="u" href="#Is-there-a-better-way_003f">Is there a better way?</a>
+
+</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) <!-- /@w -->keep the documentation together and (2) <!-- /@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: <a rel="next" accesskey="n" href="#Contributors">Contributors</a>,
+Previous: <a rel="previous" accesskey="p" href="#Is-there-a-better-way_003f">Is there a better way?</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+
+</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 <!-- /@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: <a rel="previous" accesskey="p" href="#Related-references">Related references</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+
+</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 at tug.org">tds at tug.org</a> and <a href="mailto:tex-live at tug.org">tex-live at tug.org</a> mailing lists as
+the record of contributions.
+
+</body></html>
+
Added: tex-common/trunk/doc/tds-1.1/tds.info
===================================================================
--- tex-common/trunk/doc/tds-1.1/tds.info 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/tds.info 2006-12-06 16:12:46 UTC (rev 1986)
@@ -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 at 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 at 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 at tug.org> and <tex-live at 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
Added: tex-common/trunk/doc/tds-1.1/tds.pdf
===================================================================
(Binary files differ)
Property changes on: tex-common/trunk/doc/tds-1.1/tds.pdf
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: tex-common/trunk/doc/tds-1.1/tds.sed
===================================================================
--- tex-common/trunk/doc/tds-1.1/tds.sed 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/tds.sed 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1,14 @@
+# $Id: tds.sed,v 1.2 2004/06/04 17:11:34 karl Exp $
+# Written by Ulrik Vieth and Karl Berry.
+# Public domain.
+#
+# Things that are too hard to do in Elisp. Run after tds2texi-convert.
+
+# Indentation blocks in tdsSummary environments.
+s/ \./ /g
+
+# References that are too hard to convert automatically.
+s/Table, ref{tab:summary}/@pxref{Summary},/
+
+/^Copyright.*Group/a\
+This is version @value{version}.
Added: tex-common/trunk/doc/tds-1.1/tds.tex
===================================================================
--- tex-common/trunk/doc/tds-1.1/tds.tex 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/tds.tex 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1,1585 @@
+%&latex
+% $Id: tds.tex,v 1.43 2004/06/23 17:24:42 karl Exp $
+\NeedsTeXFormat{LaTeX2e} % compatibility with 2.09 is too painful
+\documentclass{tdsguide}
+
+\tdsVersion{1.1}
+
+\title{A Directory Structure for \TeX{} Files}
+\author{TUG Working Group on a \TeX{} Directory Structure (TWG-TDS)}
+
+\begin{document}
+
+\maketitle
+
+\begin{legalnotice}
+
+Copyright {\copyright} 1994, 1995, 1996, 1997, 1998, 1999, 2003, 2004
+\TeX{} Users Group.
+
+Permission to use, copy, and distribute this document \emphasis{without
+modification} for any purpose and without fee is hereby granted,
+provided that this notice appears in all copies. It is provided ``as
+is'' without expressed or implied warranty.
+
+Permission is granted to copy and distribute modified versions of this
+document under the conditions for verbatim copying, provided that the
+modifications are clearly marked and the document is not represented as
+the official one.
+
+This document is available on any \abbr{ctan} host
+(see Appendix~\ref{sec:Related references}).
+Please send questions or suggestions by email to
+\email|tds at tug.org|. We welcome all comments. This is version
+\the\tdsVersion.
+
+\end{legalnotice}
+
+
+\tableofcontents
+
+
+\newpage
+\section{Introduction}
+
+\TeX{} is a powerful, flexible typesetting system used by many people
+around the world. It is extremely portable and runs on virtually all
+operating systems. One unfortunate side effect of \TeX{}'s flexibility,
+however, is that there has been no single ``right'' way to install it.
+This has resulted in many sites having different installed arrangements.
+
+The primary purpose of this document is to describe a standard \TeX{}
+Directory Structure (\abbr{TDS}): a directory hierarchy for macros,
+fonts, and the other implementation-independent \TeX{} system files. As
+a matter of practicality, this document also suggests ways to
+incorporate the rest of the \TeX{} files into a single structure. The
+\abbr{TDS} has been designed to work on all modern systems. In
+particular, the Technical Working Group (\abbr{TWG}) believes it is usable
+under Mac\abbr{OS}, \abbr{ms-dos}, \abbr{os/2}, Unix, \abbr{vms}, and
+Windows \abbr{nt}\@. We hope that administrators and developers of both
+free and commercial \TeX{} implementations will adopt this standard.
+
+This document is intended both for the \TeX{} system administrator at a
+site and for people preparing \TeX{} distributions---everything from a
+complete runnable system to a single macro or style file. It may also
+help \TeX{} users find their way around systems organized this way. It
+is not a tutorial: we necessarily assume knowledge of the many parts of
+a working \TeX{} system. If you are unfamiliar with any of the programs
+or file formats we refer to, consult the references in
+Appendix~\ref{sec:Related references}.
+
+
+\subsection{History}
+
+Version 1.0 of the \abbr{TDS} was released in February 2003.
+
+Version 1.1 was released in June 2004, with the following non-editorial
+changes:
+
+\begin{itemize-squeeze}
+\item Inputs for \TeX{} extensions included under \path|tex|, instead
+ of in their own top-level directories (Section~\ref{sec:Extensions})
+\item New top-level directory \path|scripts| (Section~\ref{sec:Scripts}).
+\item New subdirectories \path|lig|, \path|opentype|,
+ \path|truetype|, and \path|type3| under \path|fonts|
+ (Section~\ref{sec:Fonts}).
+\item \path|enc|, \path|lig|, and \path|map| all use
+ \replaceable{syntax}\path|/|\replaceable{package} subdirectories
+ (Section~\ref{sec:Fonts}).
+\item \path|pfm| files specified to go under \path|type1|, and
+ \path|inf| files under \path|afm| (Section~\ref{sec:Fonts}).
+\end{itemize-squeeze}
+
+
+\subsection{The role of the \abbr{TDS}}
+
+The role of the \abbr{TDS} is to stabilize the organization of
+\TeX{}-related software packages that are installed and in use, possibly
+on multiple platforms simultaneously.
+
+At first glance, it may seem that the Comprehensive \TeX{} Archive
+Network (\abbr{ctan}) fulfills at least part of this role, but this is
+not the case. The role of \abbr{ctan} is to simplify archiving and
+distribution, not installation and use.
+
+In fact, the roles of the \abbr{TDS} and \abbr{ctan} are frequently in
+conflict, as we will see. For distribution, many different types of
+files must be combined into a single unit; for use, it is traditional to
+segregate files (even similar files) from a single package into
+separate, occasionally distant, directories.
+
+
+\subsection{Conventions}
+
+In this document, ``\path|/|'' is used to separate filename components;
+for example, \path|texmf/fonts|. This is the Unix convention but the
+ideas are in no way Unix-specific.
+
+In this document, ``\TeX{}'' generally means the \TeX{} system, including
+\MF{}, \abbr{DVI} drivers, utilities, etc., not just the \TeX{}
+program itself.
+
+The word ``package'' in this document has its usual meaning: a set of
+related files distributed, installed, and maintained as a unit. This is
+\emphasis{not} a \LaTeXe{} package, which is a style file supplementing
+a document class.
+
+We use the following typographic conventions:
+
+\begin{description}
+
+\item[\literal{literal}] Literal text such as \literal{filename} is
+typeset in typewriter type.
+
+\item[\replaceable{replaceable}] Replaceable text such as
+\replaceable{package}, identifying a class of things, is typeset in
+italics inside angle brackets.
+
+\end{description}
+
+
+\section{General}
+
+This section describes common properties throughout the \abbr{TDS} tree.
+
+\subsection{Subdirectory searching}
+\label{sec:Subdirectory searching}
+
+Older \TeX{} installations store large numbers of related files in single
+directories, for example, all \path|TFM| files and\slash or all \TeX{}
+input files.
+
+This monolithic arrangement hinders maintenance of a \TeX{} system: it
+is difficult to determine what files are used by what packages, what
+files need to be updated when a new version is installed, or what files
+should be deleted if a package is removed. It is also a source of error
+if two or more packages happen to have input files with the same name.
+
+Therefore, the \abbr{TWG} felt each package should be in a separate
+directory. But we recognized that explicitly listing all directories to
+be searched would be unbearable. A site may wish to install dozens of
+packages. Aside from anything else, listing that many directories would
+produce search paths many thousands of characters long, overflowing the
+available space on some systems.
+
+Also, if all directories are explicitly listed, installing or removing a
+new package would mean changing a path as well as installing or removing
+the actual files. This would be a time-consuming and error-prone
+operation, even with implementations that provide some way to specify
+the directories to search at runtime. On systems without runtime
+configuration, it would require recompiling software, an intolerable
+burden.
+
+As a result, the \abbr{TWG} concluded that a comprehensive \abbr{TDS}
+requires implementations to support some form of implicit subdirectory
+searching. More precisely, implementations must make it possible to
+specify that \TeX{}, \MF{}, and their companion utilities search in both
+a specified directory and recursively through all subdirectories of that
+directory when looking for an input file. Other forms of subdirectory
+searching, for example recursive-to-one-level searches, may also be
+provided. We encourage implementors to provide subdirectory searching
+at the option of the installer and user for all paths.
+
+The \abbr{TDS} does not specify a syntax for specifying recursive
+searching, but we encourage implementors to provide interoperability
+(see Section~\ref{sec:More on subdirectory searching}).
+
+
+\subsection{Rooting the tree}
+\label{sec:Rooting the tree}
+
+In this document, we shall designate the root \abbr{TDS} directory by
+`\texmf{}' (for ``\TeX{} and \MF{}''). We recommend using that name
+where possible, but the actual name of the directory is up to the
+installer. On \abbr{pc} networks, for example, this could map to a
+logical drive specification such as \path|T:|.
+
+Similarly, the location of this directory on the system is
+site-dependent. It may be at the root of the file system; on Unix
+systems, \path|/usr/local/share|, \path|/usr/local|,
+\path|/usr/local/lib|, and \path|/opt| are common choices.
+
+The name \texmf{} was chosen for several reasons: it reflects the fact
+that the directory contains files pertaining to an entire \TeX{} system
+(including \MF{}, \MP{}, \BibTeX{}, etc.), not just \TeX{} itself; and it
+is descriptive of a generic installation rather than a particular
+implementation.
+
+A site may choose to have more than one \abbr{TDS} hierarchy installed
+(for example, when installing an upgrade). This is perfectly legitimate.
+
+
+\subsection{Local additions}
+\label{sec:Local additions}
+
+The \abbr{TDS} cannot specify precisely when a package is or is not a
+``local addition''. Each site must determine this according to its own
+conventions. At the two extremes, one site might wish to consider
+``nonlocal'' all files not acquired as part of the installed \TeX{}
+distribution; another site might consider ``local'' only those files
+that were actually developed at the local site and not distributed
+elsewhere.
+
+We recognize two common methods for local additions to a distributed
+\texmf{} tree. Both have their place; in fact, some sites employ
+both simultaneously:
+
+\begin{enumerate}
+
+\item A completely separate tree which is a \abbr{TDS} structure
+itself; for example, \path|/usr/local/umbtex| at the University of
+Massachusetts at Boston. This is another example of the multiple
+\texmf{} hierarchies mentioned in the previous section.
+
+\item A directory named `\path|local|' at any appropriate level, for
+example, in the \replaceable{format}, \replaceable{package}, and
+\replaceable{supplier} directories discussed in the following sections.
+The \abbr{TDS} reserves the directory name \path|local| for this
+purpose.
+
+We recommend using \path|local| for site-adapted configuration files,
+such as \path|language.dat| for the Babel package or \path|graphics.cfg|
+for the graphics package. Unmodified configuration files from a package
+should remain in the package directory. The intent is to separate
+locally modified or created files from distribution files, to ease
+installing new releases.
+
+\end{enumerate}
+
+One common case of local additions is dynamically generated files, e.g.,
+\abbr{PK} fonts by the \path|mktexpk| script (which originated in
+\application{Dvips} as \path|MakeTeXPK|). A site may store the
+generated files directly in any of:
+\begin{itemize-squeeze}
+\item their standard location in the main \abbr{TDS} tree (if it can be
+made globally writable);
+
+\item an alternative location in the main \abbr{TDS} tree (for
+example, under \path|texmf/fonts/tmp|);
+
+\item a second complete \abbr{TDS} tree (as outlined above);
+
+\item any other convenient directory (perhaps under
+\path|/var|, for example \path|/var/spool/fonts|).
+
+\end{itemize-squeeze}
+
+No one solution will be appropriate for all sites.
+
+
+\subsection{Duplicate filenames}
+\label{sec:Duplicate filenames}
+
+Different files by the same name may exist in a \abbr{TDS} tree. The
+\abbr{TDS} generally leaves unspecified which of two files by the same
+name in a search path will be found, so generally the only way to
+reliably find a given file is for it to have a unique name. However,
+the \abbr{TDS} requires implementations to support the following
+exceptions:
+
+\begin{itemize}
+
+\item Names of \TeX{} input files must be unique within each first-level
+subdirectory of \path|texmf/tex| and \path|texmf/tex/generic|, but not
+within all of \path|texmf/tex|; i.e., different \TeX{} formats may have
+files by the same name. (Section~\ref{sec:Macros} discusses this
+further.) Thus, no single format-independent path specification, such
+as a recursive search beginning at \path|texmf/tex| specifying no other
+directories, suffices. So implementations must provide format-dependent
+path specifications, for example via wrapper scripts or configuration
+files.
+
+\item Many font files will have the same name (e.g., \path|cmr10.pk|),
+as discussed in Section~\ref{sec:Valid font bitmaps}. Implementations
+must distinguish these files by mode and resolution.
+
+\end{itemize}
+
+All implementations we know of already have these capabilities.
+
+One place where duplicate names are likely to occur is not an exception:
+
+\begin{itemize}
+
+\item Names of \MF{} input files (as opposed to bitmaps) must be unique
+within all of \path|texmf/fonts|. In practice, this is a problem with
+some variants of Computer Modern which contain slightly modified files
+named \path|punct.mf|, \path|romanl.mf|, and so on. We believe the only
+feasible solution is to rename the derivative files to be
+unique.
+
+\end{itemize}
+
+
+\section{Top-level directories}
+\label{sec:Top-level directories}
+
+The directories under the \texmf{} root identify the major components of
+a \TeX{} system (see Section~\ref{sec:Summary} for a summary). A site
+may omit any unneeded directories.
+
+Although the \abbr{TDS} by its nature can specify precise locations only
+for implementation-independent files, we recognize that installers may
+well wish to place other files under \texmf{} to simplify administration
+of the \TeX{} tree, especially if it is maintained by someone other than
+the system administrator. Therefore, additional top-level directories
+may be present.
+
+The top-level directories specified by the \abbr{TDS} are:
+
+\begin{description}
+\item[\path|tex|]
+for \TeX{} files (Section~\ref{sec:Macros}).
+
+\item[\path|fonts|]
+for font-related files (Section~\ref{sec:Fonts}).
+
+\item[\path|metafont|]
+for \MF{} files which are not fonts (Section~\ref{sec:Non-font MF files}).
+
+\item[\path|metapost|]
+for \MP{} files (Section~\ref{sec:MetaPost}).
+
+\item[\path|bibtex|]
+for \BibTeX{} files (Section~\ref{sec:BibTeX}).
+
+\item[\path|scripts|]
+for platform-independent executables (Section~\ref{sec:Scripts}).
+
+\item[\path|doc|]
+for user documentation (Section~\ref{sec:Documentation}).
+
+\item[\path|source|] for sources. This includes both traditional
+program sources (for example, \application{Web2C} sources go in
+\path|texmf/source/web2c|) and, e.g., \LaTeX{} \path|dtx| sources (which
+go in \path|texmf/source/latex|). The \abbr{TDS} leaves unspecified any
+structure under \path|source|.
+
+\path|source| is intended for files which are not needed at runtime by
+any \TeX{} program; it should not be included in any search path. For
+example, \path|plain.tex| does not belong under \path|texmf/source|,
+even though it is a ``source file'' in the sense of not being derived
+from another file. (It goes in \path|texmf/tex/plain/base|, as explained
+in Section~\ref{sec:Macros}).
+
+\item[\replaceable{implementation}] for implementations (examples:
+\path|emtex|, \path|vtex|, \path|web2c|), to be used for whatever
+purpose deemed suitable by the implementor or \TeX{} administrator.
+That is, files that cannot be shared between implementations, such as
+pool files (\path|tex.pool|) and memory dump files (\path|plain.fmt|) go
+here, in addition to implementation-wide configuration files. See
+Section~\ref{sec:Example implementation-specific trees} for examples of
+real \replaceable{implementation} trees.
+
+Such implementation-specific configuration files should \emphasis{not}
+be located using the main \TeX{} input search path (e.g.,
+\path|TEXINPUTS|). This must be reserved for files actually read by a
+\TeX{} engine. See Section~\ref{sec:Extensions}.
+
+\item[\replaceable{program}] for program-specific input and
+configuration files for any \TeX{}-related programs (examples:
+\path|mft|, \path|dvips|). In fact, the \path|tex|, \path|metafont|,
+\path|metapost|, and \path|bibtex| items above may all be seen as
+instances of this case.
+
+\end{description}
+
+
+\subsection{Macros}
+\label{sec:Macros}
+
+\TeX{} macro files shall be stored in separate directories, segregated
+by \TeX{} format and package name (we use `format' in its traditional
+\TeX{} sense to mean a usefully \path|\dump|-able package):
+\begin{ttdisplay}
+texmf/tex/\replaceable{format}/\replaceable{package}/
+\end{ttdisplay}
+
+\begin{description}
+
+\item[\replaceable{format}] is a format name (examples: \path|amstex|,
+\path|latex|, \path|plain|, \path|texinfo|).
+
+The \abbr{TDS} allows distributions that can be used as either formats or
+packages (e.g., Texinfo, Eplain) to be stored at either level, at the
+option of the format author or \TeX{} administrator. We recommend that
+packages used as formats at a particular site be stored at the
+\replaceable{format} level: by adjusting the \TeX{} inputs search path,
+it will be straightforward to use them as macro packages under another
+format, whereas placing them in another tree completely obscures their
+use as a format.
+
+The \abbr{TDS} reserves the following \replaceable{format} names:
+
+\begin{itemize}
+
+\item \path|generic|, for input files that are useful across a wide
+range of formats (examples: \path|null.tex|, \path|path.sty|).
+Generally, this means any format that uses the category codes of Plain
+\TeX{} and does not rely on any particular format. This is in contrast
+to those files which are useful only with Plain \TeX{} (which go under
+\path|texmf/tex/plain|), e.g., \path|testfont.tex| and \path|plain.tex|
+itself.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local
+additions}.
+
+\end{itemize}
+
+Thus, for almost every format, it is necessary to search at least the
+\replaceable{format} directory and then the \path|generic| directory (in
+that order). Other directories may need to be searched as well,
+depending on the format. When using \AMSTeX{}, for example, the
+\path|amstex|, \path|plain|, and \path|generic| directories should be
+searched, because \AMSTeX{} is compatible with Plain.
+
+\item[\replaceable{package}] is a \TeX{} package name (examples:
+\path|babel|, \path|texdraw|).
+
+In the case where a format consists of only a single file and has no
+auxiliary packages, that file can simply be placed in the
+\replaceable{format} directory, instead of
+\replaceable{format}\path|/base|. For example, Texinfo may go in
+\path|texmf/tex/texinfo/texinfo.tex|, not
+\path|texmf/tex/texinfo/base/texinfo.tex|.
+
+The \abbr{TDS} reserves the following \replaceable{package} names:
+
+\begin{itemize}
+
+\item \path|base|, for the base distribution of each format,
+including files used by \iniTeX{} when dumping format files. For
+example, in the standard \LaTeX{} distribution, the \path|ltx| files
+created during the build process. Another example: the \path|.ini|
+driver files for formats used by \TeX{} Live and other distributions.
+
+\item \path|hyphen|, for hyphenation patterns, including the original
+American English \path|hyphen.tex|. These are typically used only by
+\iniTeX{}. In most situations, this directory need exist only under the
+\literal{generic} format.
+
+\item \path|images|, for image input files, such as Encapsulated
+PostScript figures. Although it is somewhat non-intuitive for these to
+be under a directory named ``\path|tex|'', \TeX{} needs to read these
+files to glean bounding box or other information. A mechanism for
+sharing image inputs between \TeX{} and other typesetting programs
+(e.g., Interleaf, FrameMaker) is beyond the scope of the
+\abbr{TDS}\@. In most situations, this directory need exist only under
+the \literal{generic} format.
+
+\item \path|local|, for local additions and configuration files. See
+Section~\ref{sec:Local additions}.
+
+\item \path|misc|, for packages that consist of a single file. An
+administrator or package maintainer may create directories for
+single-file packages at their discretion, instead of using \path|misc|.
+
+\end{itemize}
+
+\end{description}
+
+
+\subsubsection{Extensions}
+\label{sec:Extensions}
+
+\TeX{} has spawned many companion and successor programs (``engines''),
+such as \abbr{PDF}\TeX{}, Omega, and others. The \abbr{TDS} specifies
+that the input files for such programs (using a \TeX{}-like syntax) be
+placed within the top-level \path|tex| directory, either at the top
+level or within a format subdirectory, even though the original \TeX{}
+program may not be able to read them. For example:
+
+\begin{ttdisplay}
+texmf/tex/aleph
+texmf/tex/enctex
+\end{ttdisplay}
+
+This is a change from \abbr{TDS}~1.0, which specified top-level
+\replaceable{extension} directories for each such program. We felt the
+new approach is preferable, because:
+
+\begin{itemize}
+
+\item Authors of relevant packages typically make their code detect the
+engine being used, and issue error messages or adapt to circumstances
+appropriately. Furthermore, as a package matures, it may support
+multiple engines. Thus, a package could conceivably be placed in any of
+several top-level directories, at different times. Putting all packages
+under the top-level \path|tex| directory provides a stable location over
+time.
+
+\item Users need to be able to switch between engines, and configuring
+different search paths for each engine is difficult and error-prone.
+
+\end{itemize}
+
+Thus, in practice, having different top-level directories caused
+difficulties for everyone involved---users, package authors, site
+administrators, and system distributors.
+
+Please contrast this approach with the \replaceable{implementation}
+top-level subdirectory (Section~\ref{sec:Top-level directories}), which
+is to be used for configuration files that (presumably) do not use
+\TeX{} syntax and in any case should not be found along the main \TeX{}
+input search path.
+
+
+\subsection{Fonts}
+\label{sec:Fonts}
+
+Font files are stored in separate directories, segregated by file type,
+and then (in most cases) font supplier and typeface. \abbr{PK} and
+\abbr{GF} files need additional structure, as detailed in the next
+section.
+
+\begin{ttdisplay}
+texmf/fonts/\replaceable{type}/\replaceable{supplier}/\replaceable{typeface}/
+texmf/fonts/enc,lig,map/\replaceable{subpath}/
+\end{ttdisplay}
+
+\begin{description}
+
+\item[\replaceable{type}] is the type of font file. The \abbr{TDS}
+reserves the following \replaceable{type} names for common \TeX{} file
+types:
+
+\begin{itemize-squeeze}
+\item \path|afm|, for Adobe font metrics, and \path|inf| files.
+\item \path|gf|, for generic font bitmap files.
+\item \path|opentype|, for OpenType fonts.
+\item \path|pk|, for packed bitmap files.
+\item \path|source|, for font sources (\MF{} files, property lists, etc.).
+\item \path|tfm|, for \TeX{} font metric files.
+\item \path|truetype|, for TrueType fonts.
+\item \path|type1|, for PostScript Type 1 fonts (in \path|pfa|,
+ \path|pfb|, or any other format), and \path|pfm| files.
+\item \path|type3|, for PostScript Type 3 fonts.
+\item \path|vf|, for virtual fonts.
+\end{itemize-squeeze}
+
+The \abbr{TDS} also reserves the names \path|enc|, \path|lig|, and
+\path|map| for font encoding, ligature, and mapping files, respectively.
+All of these directories are structured the same way, with
+\replaceable{syntax} subdirectories, and then \replaceable{package}
+subsubdirectories. Each of these file types is intended to be searched
+along its own recursively-searched path. The names of the actual files
+must be unique within their subtree, as usual. Examples:
+\begin{ttdisplay}
+fonts/map/dvipdfm/updmap/dvipdfm.map
+fonts/map/dvips/lm/lm.map
+fonts/enc/dvips/base/8r.enc
+\end{ttdisplay}
+
+The Fontname and Dvips packages have more examples of the \path|enc| and
+\path|map| types. The \path|afm2pl| program uses \path|lig| files.
+
+\path|pfm| files are included in the \path|type1| directory, instead of
+being given their own directory, for two reasons: 1)~a \path|.pfm| file
+is always an adjunct to a given \path|.pfb| file; 2)~they must be
+installed from the same directory for Windows programs other than \TeX{}
+to use them.
+
+\path|inf| files are included in the \path|afm| directory, since
+an \path|inf| and \path|afm| file can be used to generate a \path|pfm|.
+(Unfortunately, Adobe Type Manager and perhaps other software requires
+that the \path|pfb| be in the same directory as \path|afm| and
+\path|inf| for installation.)
+
+As usual, a site may omit any of these directories that are unnecessary.
+\path|gf| is a particularly likely candidate for omission.
+
+\item[\replaceable{supplier}] is a name identifying font source
+(examples: \path|adobe|, \path|ams|, \path|public|). The \abbr{TDS}
+reserves the following \replaceable{supplier} names:
+
+\begin{itemize}
+
+\item \path|ams|, for the American Mathematical Society's \AmS{}-fonts
+collection.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local additions}.
+
+\item \path|public|, for freely redistributable fonts where the supplier
+neither (1)~requested their own directory (e.g., \path|ams|), nor
+(2)~also made proprietary fonts (e.g., \path|adobe|). It does not
+contain all extant freely distributable fonts, nor are all files therein
+necessarily strictly public domain.
+
+\item \path|tmp|, for dynamically-generated fonts, as is traditional on
+some systems. It may be omitted if unnecessary, as usual.
+
+\end{itemize}
+
+
+\item[\replaceable{typeface}] is the name of a typeface family
+(examples: \path|cm|, \path|euler|, \path|times|). The \abbr{TDS}
+reserves the following \replaceable{typeface} names:
+
+\begin{itemize}
+
+\item \path|cm| (within \path|public|), for the 75 fonts defined in
+\citetitle{Computers and Typesetting, Volume~E}.
+
+\item \path|latex| (within \path|public|), for those fonts distributed
+with \LaTeX{} in the base distribution.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local additions}.
+
+\end{itemize}
+
+\end{description}
+
+Some concrete examples:
+\begin{ttdisplay}
+texmf/fonts/source/public/pandora/pnr10.mf
+texmf/fonts/tfm/public/cm/cmr10.tfm
+texmf/fonts/type1/adobe/utopia/putr.pfa
+\end{ttdisplay}
+
+For complete supplier and typeface name lists, consult
+\citetitle{Filenames for \TeX{} fonts} (see Appendix~\ref{sec:Related
+references}).
+
+\subsubsection{Font bitmaps}
+
+Font bitmap files require two characteristics in addition to the above
+to be uniquely identifiable: (1)~the type of device (i.e., mode) for
+which the font was created; (2)~the resolution of the bitmap.
+
+Following common practice, the \abbr{TDS} segregates fonts with
+different device types into separate directories. See \path|modes.mf|
+in Appendix~\ref{sec:Related references} for recommended mode names.
+
+Some printers operate at more than one resolution (e.g., at 300\,dpi and
+600\,dpi), but each such resolution will necessarily have a different
+mode name. Nothing further is needed, since implicit in the \TeX{}
+system is the assumption of a single target resolution.
+
+Two naming strategies are commonly used to identify the resolution of
+bitmap font files. On systems that allow long filenames (and in the
+original \MF{} program itself), the resolution is included in the
+filename (e.g., \path|cmr10.300pk|). On systems which do not support
+long filenames, fonts are generally segregated into directories by
+resolution (e.g., \path|dpi300/cmr10.pk|).
+
+Because the \abbr{TDS} cannot require long filenames, we must use the
+latter scheme for naming fonts. So we have two more subdirectory
+levels under \path|pk| and \path|gf|:
+
+\begin{ttdisplay}
+texmf/fonts/pk/\replaceable{mode}/\replaceable{supplier}/\replaceable{typeface}/dpi\replaceable{nnn}/
+texmf/fonts/gf/\replaceable{mode}/\replaceable{supplier}/\replaceable{typeface}/dpi\replaceable{nnn}/
+\end{ttdisplay}
+
+\begin{description}
+
+\item[\replaceable{mode}] is a name which identifies the device type
+(examples: \path|cx|, \path|ljfour|, \path|modeless|). Usually, this is
+the name of the \MF{} mode used to build the \abbr{PK} file. For fonts
+rendered as bitmaps by a program that does not distinguish between
+different output devices, the \replaceable{mode} name shall be simply
+\path|modeless|. The \replaceable{mode} level shall not be omitted,
+even if only a single mode happens to be in use.
+
+\item[\path|dpi|\replaceable{nnn}] specifies the resolution of the font
+(examples: \path|dpi300|, \path|dpi329|). `\literal{dpi}' stands for
+dots per inch, i.e., pixels per inch. We recognize that pixels per
+millimeter is used in many parts of the world, but dpi is too
+traditional in the \TeX{} world to consider changing now.
+
+The integer \replaceable{nnn} is to be calculated as if using \MF{}
+arithmetic and then rounded; i.e., it is the integer \MF{} uses in its
+output \path|gf| filename. We recognize small differences in the
+resolution are a common cause of frustration among users, however, and
+recommend implementors follow the level~0 \abbr{DVI} driver standard
+(see Appendix~\ref{sec:Related references}) in bitmap font searches by
+allowing a fuzz of $\pm0.2$\% (with a minimum of $1$) in the
+\replaceable{dpi}.
+
+\end{description}
+
+Implementations may provide extensions to the basic naming scheme, such
+as long filenames (as in the original \MF{}) and font library files (as
+in em\TeX{}'s \path|.fli| files), provided that the basic scheme is also
+supported.
+
+\subsubsection{Valid font bitmaps}
+\label{sec:Valid font bitmaps}
+
+The \abbr{TWG} recognizes that the use of short filenames has many
+disadvantages. The most vexing is that it results in the creation of
+dozens of different files with the same name. At a typical site,
+\path|cmr10.pk| will be the filename for Computer Modern Roman 10\,pt at
+5--10 magnifications for 2--3 modes. (Section~\ref{sec:Duplicate
+filenames} discusses duplicate filenames in general.)
+
+To minimize this problem, we strongly recommend that \abbr{PK} files
+contain enough information to identify precisely how they were created:
+at least the mode, base resolution, and magnification used to create the
+font.
+
+This information is easy to supply: a simple addition to the local modes
+used for building the fonts with \MF{} will automatically provide the
+required information. If you have been using a local modes file derived
+from (or that is simply) \path|modes.mf| (see Appendix~\ref{sec:Related
+references}), the required information is already in your \abbr{PK}
+files. If not, a simple addition based on the code found in
+\path|modes.mf| can be made to your local modes file and the \abbr{PK}
+files rebuilt.
+
+
+\subsection{Non-font \MF{} files}
+\label{sec:Non-font MF files}
+
+Most \MF{} input files are font programs or parts of font programs and
+are thus covered by the previous section. However, a few non-font input
+files do exist. Such files shall be stored in:
+
+\begin{ttdisplay}
+texmf/metafont/\replaceable{package}/
+\end{ttdisplay}
+
+\replaceable{package} is the name of a
+\MF{} package (for example, \path|mfpic|).
+
+The \abbr{TDS} reserves the following \replaceable{package} names:
+
+\begin{itemize}
+
+\item \path|base|, for the standard \MF{} macro files as described in
+\citetitle{The \MF{}book}, such as \path|plain.mf| and \path|expr.mf|.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local additions}.
+
+\item \path|misc|, for \MF{} packages consisting of only a single file
+(for example, \path|modes.mf|). An administrator or package maintainer
+may create directories for single-file packages at their discretion,
+instead of using \path|misc|.
+
+\end{itemize}
+
+
+\subsection{\MP{}}
+\label{sec:MetaPost}
+
+\MP{} is a picture-drawing language developed by John Hobby, derived
+from Knuth's \MF{}. Its primary purpose is to output Encapsulated \PS{}
+instead of bitmaps.
+
+\MP{} input files and the support files for \MP{}-related utilities
+shall be stored in:
+
+\begin{ttdisplay}
+texmf/metapost/\replaceable{package}/
+\end{ttdisplay}
+
+\replaceable{package} is the name of a \MP{} package. At the present
+writing none exist, but the \abbr{TWG} thought it prudent to leave room
+for contributed packages that might be written in the future.
+
+The \abbr{TDS} reserves the following \replaceable{package} names:
+
+\begin{itemize}
+
+\item \path|base|, for the standard \MP{} macro files, such as
+\path|plain.mp|, \path|mfplain.mp|, \path|boxes.mp|, and
+\path|graph.mp|. This includes files used by \iniMP{} when dumping mem
+files containing preloaded macro definitions.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local
+additions}.
+
+\item \path|misc|, for \MP{} packages consisting of only a single file.
+An administrator or package maintainer may create directories for
+single-file packages at their discretion, instead of using \path|misc|.
+
+\item \path|support|, for additional input files required by \MP{}
+utility programs, including a font map, a character adjustment table,
+and a subdirectory containing low-level \MP{} programs for rendering
+some special characters.
+
+\end{itemize}
+
+
+\subsection{\BibTeX{}}
+\label{sec:BibTeX}
+
+\BibTeX{}-related files shall be stored in:
+
+\begin{ttdisplay}
+texmf/bibtex/bib/\replaceable{package}/
+texmf/bibtex/bst/\replaceable{package}/
+\end{ttdisplay}
+
+The \path|bib| directory is for \BibTeX{} database (\path|.bib|) files,
+the \path|bst| directory for style (\path|.bst|) files.
+
+\replaceable{package} is the name of a \BibTeX{} package. The
+\abbr{TDS} reserves the following \replaceable{package} names (the same
+names are reserved under both \path|bib| and \path|bst|):
+
+\begin{itemize}
+
+\item \path|base|, for the standard \BibTeX{} databases and styles, such
+as \path|xampl.bib|, \path|plain.bst|.
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local
+additions}.
+
+\item \path|misc|, for \BibTeX{} packages consisting of only a single
+file. An administrator or package maintainer may create directories for
+single-file packages at their discretion, instead of using \path|misc|.
+
+\end{itemize}
+
+
+\subsection{Scripts}
+\label{sec:Scripts}
+
+The top-level \path|scripts| directory is for platform-independent
+executables, such as Perl, Python, and shell scripts, and Java class
+files. Subdirectories under \path|scripts| are package names. This
+eases creating distributions, by providing a common place for such
+platform-independent programs.
+
+The intent is not for all such directories to be added to a user's
+command search path, which would be quite impractical. Rather, these
+executables are primarily for the benefit of wrapper scripts in whatever
+executable directory a distribution may provide (which is not specified
+by the \abbr{TDS}).
+
+Truly auxiliary scripts which are invoked directly by other programs,
+rather than wrapper scripts, may also be placed here. That is,
+\path|scripts| also serves as a platform-independent analog of the
+standard Unix \path|libexec| directory.
+
+We recommend using extensions specifying the language (such as
+\path|.pl|, \path|.py|, \path|.sh|) on these files, to help uniquely
+identify the name. Since the intent of the \abbr{TDS} is for programs
+in \path|scripts| not to be invoked directly by users, this poses no
+inconvenience.
+
+For example, in the \TeX{} Live distribution, the Con\TeX{}t user-level
+program \path|texexec| can exist as a small wrapper script in each
+\path|bin/|\replaceable{platform}\path|/texexec| (which is outside the
+\path|texmf| tree), which merely finds and calls
+\path|texmf/scripts/context/perl/texexec.pl|.
+
+Examples:
+\begin{ttdisplay}
+scripts/context/perl/texexec.pl
+scripts/context/ruby/examplex.rb
+scripts/thumbpdf/thumbpdf.pl
+\end{ttdisplay}
+
+The \abbr{TDS} does not specify a location for platform-dependent
+binary executables, whether auxiliary or user-level.
+
+
+\subsection{Documentation}
+\label{sec:Documentation}
+
+Most packages come with some form of documentation: user manuals,
+example files, programming guides, etc. In addition, many independent
+files not part of any macro or other package have been created to
+describe various aspects of the \TeX{} system.
+
+The \abbr{TDS} specifies that these additional documentation files shall
+be stored in a structure that parallels to some extent the
+\path|fonts| and \path|tex| directories, as follows:
+
+\begin{ttdisplay}
+texmf/doc/\replaceable{category}/...
+\end{ttdisplay}
+
+\replaceable{category} identifies the general topic of documentation
+that resides below it; for example, a \TeX{} format name (\path|latex|),
+program name (\path|bibtex|, \path|tex|), language (\path|french|,
+\path|german|), a file format (\path|info|, \path|man|), or other system
+components (\path|web|, \path|fonts|).
+
+One possible arrangement is to organize \path|doc| by language, with all
+the other category types below that. This helps users find
+documentation in the language(s) in which they are fluent. Neither this
+nor any other particular arrangement is required, however.
+
+Within each \replaceable{category} tree for a \TeX{} format, the
+directory \path|base| is reserved for base documentation distributed by
+the format's maintainers.
+
+The \abbr{TDS} reserves the following category names:
+
+\begin{itemize}
+
+\item \path|general|, for standalone documents not specific to any
+particular program (for example, Joachim Schrod's \citetitle{Components
+of \TeX{}}).
+
+\item \path|help|, for meta-information, such as \abbr{faq}'s,
+the \TeX{} Catalogue, etc.
+
+\item \path|info|, for processed Texinfo documents. (Info files, like
+anything else, may also be stored outside the \abbr{TDS}, at the
+installer's option.)
+
+\item \path|local|, for local additions. See Section~\ref{sec:Local
+additions}.
+
+\end{itemize}
+
+The \path|doc| directory is intended for implementation-independent and
+operating system-independent documentation
+files. Implementation-dependent files are best stored elsewhere, as
+provided for by the implementation and/or \TeX{} administrator (for
+example, \abbr{VMS} help files under \path|texmf/vms/help|).
+
+The documentation directories may contain \TeX{} sources, \abbr{DVI}
+files, \PS{} files, text files, example input files, or any other useful
+documentation format(s).
+
+See Section~\ref{sec:Documentation tree summary} for a summary.
+
+
+\newpage
+\section{Summary}
+\label{sec:Summary}
+
+A skeleton of a \abbr{TDS} \texmf{} directory tree. This is not to
+imply these are the only entries allowed. For example, \path|local| may
+occur at any level.
+
+\begin{tdsSummary}
+ bibtex/ \BibTeX{} input files
+ . bib/ \BibTeX{} databases
+ . . base/ base distribution (e.g., \path|xampl.bib|)
+ . . misc/ single-file databases
+ . <package>/ name of a package
+ . bst/ \BibTeX{} style files
+ . . base/ base distribution (e.g., \path|plain.bst|, \path|acm.bst|)
+ . . misc/ single-file styles
+ . <package>/ name of a package
+ doc/ see Section~\ref{sec:Documentation} and the summary below
+ fonts/ font-related files
+ . <type>/ file type (e.g., \path|pk|)
+ . . <mode>/ type of output device (for \path|pk| and \path|gf| only)
+ . . . <supplier>/ name of a font supplier (e.g., \path|public|)
+ . . . . <typeface>/ name of a typeface (e.g., \path|cm|)
+ . . . . . dpi<nnn>/ font resolution (for \path|pk| and \path|gf| only)
+ <implementation>/ \TeX{} implementations, by name (e.g., \path|emtex|)
+ local/ files created or modified at the local site
+ metafont/ \MF{} (non-font) input files
+ . base/ base distribution (e.g., \path|plain.mf|)
+ . misc/ single-file packages (e.g., \path|modes.mf|)
+ . <package>/ name of a package (e.g., \path|mfpic|)
+ metapost/ \MP{} input and support files
+ . base/ base distribution (e.g., \path|plain.mp|)
+ . misc/ single-file packages
+ . <package>/ name of a package
+ . support/ support files for \MP{}-related utilities
+ mft/ \path|MFT| inputs (e.g., \path|plain.mft|)
+ <program>/ \TeX{}-related programs, by name (e.g., \path|dvips|)
+ source/ program source code by name (e.g., \path|latex|, \path|web2c|)
+ tex/ \TeX{} input files
+ . <engine>/ name of an engine (e.g., \path|aleph|); can also be lower
+ . <format>/ name of a format (e.g., \path|plain|)
+ . . base/ base distribution for format (e.g., \path|plain.tex|)
+ . . misc/ single-file packages (e.g., \path|webmac.tex|)
+ . . local/ local additions to or local configuration files for \replaceable{format}
+ . . <package>/ name of a package (e.g., \path|graphics|, \path|mfnfss|)
+ . generic/ format-independent packages
+ . . hyphen/ hyphenation patterns (e.g., \path|hyphen.tex|)
+ . . images/ image input files (e.g., Encapsulated PostScript)
+ . . misc/ single-file format-independent packages (e.g., \path|null.tex|).
+ . . <package>/ name of a package (e.g., \path|babel|)
+\end{tdsSummary}
+
+
+\newpage
+\subsection{Documentation tree summary}
+\label{sec:Documentation tree summary}
+
+An example skeleton of a \abbr{TDS} directory tree under
+\path|texmf/doc|. This is not to imply these are the only entries
+allowed, or that this structure must be followed precisely for the
+entries listed.
+
+As mentioned, the \path|texmf/doc| tree may be organized by language, so
+that all documentation in French, say, is in a \path|french|
+subdirectory. In that case, the example structure here would be in a
+given language directory.
+
+\begin{tdsSummary}
+ ams/
+ . amsfonts/ \path|amsfonts.faq|, \path|amfndoc|
+ . amslatex/ \path|amslatex.faq|, \path|amsldoc|
+ . amstex/ \path|amsguide|, \path|joyerr|
+ bibtex/ \BibTeX{}
+ . base/ \path|btxdoc.tex|
+ fonts/
+ . fontname/ \citetitle{Filenames for \TeX{} fonts}
+ . oldgerm/ \path|corkpapr|
+ <format>/ name of a \TeX{} format (e.g., \path|generic|, \path|latex|)
+ . base/ for the base distribution
+ . misc/ for contributed single-file package documentation
+ . <package>/ for \emphasis{package}
+ general/ across programs, generalities
+ . errata/ \path|errata|, \path|errata[1-8]|
+ . texcomp/ \citetitle{Components of \TeX{}}
+ help/ meta-information
+ . ctan/ info about \abbr{ctan} mirror sites
+ . faq/ \abbr{faq}s of \path|comp.text.tex|, etc.
+ info/ \abbr{gnu} Info files, made from Texinfo sources
+ latex/ example of \replaceable{format}
+ . base/ \path|ltnews*|, \path|*guide|, etc.
+ . graphics/ \path|grfguide|
+ local/ site-specific documentation
+ man/ Unix man pages
+ <program>/ \TeX{}-related programs, by name (examples follow)
+ metafont/ \path|mfbook.tex|, \path|metafont-for-beginners|, etc.
+ metapost/ \path|mpman|, \path|manfig|, etc.
+ tex/ \path|texbook.tex|, \citetitle{A Gentle Introduction to \TeX{}}, etc.
+ web/ \path|webman|, \path|cwebman|
+\end{tdsSummary}
+
+
+\newpage
+\appendix
+
+\section{Unspecified pieces}
+
+The \abbr{TDS} cannot address the following aspects of a functioning
+\TeX{} system:
+
+\begin{enumerate}
+
+\item The location of executable programs: this is too site-dependent
+even to recommend a location, let alone require one. A site may place
+executables outside the \texmf{} tree altogether (e.g.,
+\path|/usr/local/bin|), in a platform-dependent directory within
+\texmf{}, or elsewhere.
+
+\item Upgrading packages when new releases are made: we could find no
+way of introducing version specifiers into \texmf{} that would do more
+good than harm, or that would be practical for even a plurality of
+installations.
+
+\item The location of implementation-specific files (e.g., \TeX{}
+\path|.fmt| files): by their nature, these must be left to the
+implementor or \TeX{} maintainer. See Section~\ref{sec:Example
+implementation-specific trees}.
+
+\item Precisely when a package or file should be considered ``local'',
+and where such local files are installed. See Section~\ref{sec:Local
+additions} for more discussion.
+
+\end{enumerate}
+
+
+\subsection{Portable filenames}
+\label{sec:Portable filenames}
+
+The \abbr{TDS} cannot require any particular restriction on filenames in
+the tree, since the names of many existing \TeX{} files conform to no
+standard scheme. For the benefit of people who wish to make a portable
+\TeX{} distribution or installation, however, we outline here the
+necessary restrictions. The \abbr{TDS} specifications themselves are
+compatible with these.
+
+\abbr{ISO}-9660 is the only universally acceptable file system format
+for \abbr{CD-ROM}s. A subset thereof meets the stringent limitations of
+all operating systems in use today. It specifies the following:
+
+\begin{itemize-squeeze}
+
+\item File and directory names, not including any directory path or
+extension part, may not exceed eight characters.
+
+\item Filenames may have a single extension. Extensions may not exceed
+three characters. Directory names may not have an extension.
+
+\item Names and extensions may consist of \emphasis{only} the characters
+\literal{A}--\literal{Z}, \literal{0}--\literal{9}, and underscore.
+Lowercase letters are excluded.
+
+\item A period separates the filename from the extension and is always
+present, even if the name or extension is missing (e.g.,
+\path|FILENAME.| or \path|.EXT|).
+
+\item A version number, ranging from 1--32767, is appended to the file
+extension, separated by a semicolon (e.g., \path|FILENAME.EXT;1|).
+
+\item Only eight directory levels are allowed, including the top-level
+(mounted) directory (see Section~\ref{sec:Rooting the tree}). Thus, the
+deepest valid \abbr{ISO}-9660 path is:
+\begin{ttdisplay}
+texmf/L2/L3/L4/L5/L6/L7/L8/FOO.BAR;1
+1 2 3 4 5 6 7 8
+\end{ttdisplay}
+The deepest \abbr{TDS} path needs only seven levels:
+\begin{ttdisplay}
+texmf/fonts/pk/cx/public/cm/dpi300/cmr10.pk
+1 2 3 4 5 6 7
+\end{ttdisplay}
+
+\end{itemize-squeeze}
+
+Some systems display a modified format of \abbr{ISO}-9660 names,
+mapping alphabetic characters to lowercase, removing version numbers and
+trailing periods, etc.
+
+Before the December 1996 release, \LaTeX{} used mixed-case names for
+font descriptor files. Fortunately, it never relied on case alone to
+distinguish among the files. Nowadays, it uses only monocase names.
+
+\section{Implementation issues}
+
+We believe that the \abbr{TDS} can bring a great deal of order to the
+current anarchic state of many \TeX{} installations. In addition, by
+providing a common frame of reference, it will ease the burden of
+documenting administrative tasks. Finally, it is a necessary part of
+any reasonable system of true ``drop-in'' distribution packages for
+\TeX{}.
+
+
+\subsection{Adoption of the \abbr{TDS}}
+
+[This section is retained for historical purposes; the \abbr{TDS}
+is now quite firmly entrenched in most \TeX{} distributions.]
+
+We recognize that adoption of the \abbr{TDS} will not be immediate or
+universal. Most \TeX{} administrators will not be inclined to make the
+final switch until:
+
+\begin{itemize-squeeze}
+\item Clear and demonstrable benefits can be shown for the \abbr{TDS}.
+\item \abbr{TDS}-compliant versions of all key programs are available
+in ported, well-tested forms.
+\item A ``settling'' period has taken place, to flush out problems. The
+public release of the first draft of this document was the first step in
+this process.
+\end{itemize-squeeze}
+
+Consequently, most of the first trials of the \abbr{TDS} will be made by
+members of the \abbr{TDS} committee and/or developers of \TeX{}-related
+software. This has already taken place during the course of our
+deliberations (see Appendix~\ref{sec:Related references} for a sample
+tree available electronically). They will certainly result in the
+production of a substantial number of \abbr{TDS}-compliant packages.
+Indeed, the \application{te\TeX{}} and \application{\TeX{} Live}
+distributions are \abbr{TDS}-compliant and in use now at many sites.
+
+Once installable forms of key \abbr{TDS}-compliant packages are more
+widespread, some \TeX{} administrators will set up \abbr{TDS}-compliant
+trees, possibly in parallel to existing production directories. This
+testing will likely flush out problems that were not obvious in the
+confined settings of the developers' sites; for example, it should help
+to resolve system and package dependencies, package interdependencies, and
+other details not addressed by this \abbr{TDS} version.
+
+After most of the dust has settled, hopefully even conservative \TeX{}
+administrators will begin to adopt the \abbr{TDS}. Eventually, most
+\TeX{} sites will have adopted the common structure, and most packages
+will be readily available in \abbr{TDS}-compliant form.
+
+We believe that this process will occur relatively quickly. The
+\abbr{TDS} committee spans a wide range of interests in the \TeX{}
+community. Consequently, we believe that most of the key issues
+involved in defining a workable \abbr{TDS} definition have been covered,
+often in detail. \TeX{} developers have been consulted about
+implementation issues, and have been trying out the \abbr{TDS}
+arrangement. Thus, we hope for few surprises as implementations mature.
+
+Finally, there are several (current or prospective) publishers of \TeX{}
+\abbr{CD-ROM}s. These publishers are highly motivated to work out
+details of \abbr{TDS} implementation, and their products will provide
+inexpensive and convenient ways for experimentally-minded \TeX{}
+administrators to experiment with the \abbr{TDS}.
+
+
+\subsection{More on subdirectory searching}
+\label{sec:More on subdirectory searching}
+
+Recursive subdirectory searching is the ability to specify a search not
+only of a specified directory \replaceable{d}, but recursively of all
+directories below \replaceable{d}.
+
+Since the \abbr{TDS} specifies precise locations for most files, with no
+extra levels of subdirectories allowed, true recursive searching is not
+actually required for a \abbr{TDS}-compliant implementation. We do,
+however, strongly recommend recursive searching as the most
+user-friendly and natural approach to the problem, rather than
+convoluted methods to specify paths without recursion.
+
+This feature is already supported by many implementations of \TeX{} and
+companion utilities, for example \abbr{DECUS} \TeX{} for \abbr{VMS},
+\application{Dvips(k)}, \application{em\TeX{}} (and its drivers),
+\application{PubliC \TeX{}}, \application{Web2C}, \application{Xdvi(k)},
+and \application{Y\&Y\TeX{}}. The Kpathsea library is a reusable
+implementation of subdirectory searching for \TeX{}, used in a number of
+the above programs.
+
+Even if your \TeX{} implementation does not directly support
+subdirectory searching, you may find it useful to adopt the structure if
+you do not use many fonts or packages. For instance, if you only use
+Computer Modern and \abbr{ams} fonts, it would be feasible to store them
+in the \abbr{TDS} layout and list the directories individually in
+configuration files or environment variables.
+
+The \abbr{TWG} recognizes that subdirectory searching places an extra
+burden on the system and may be the source of performance bottlenecks,
+particularly on slower machines. Nevertheless, we feel that
+subdirectory searching is imperative for a well-organized \abbr{TDS},
+for the reasons stated in Section~\ref{sec:Subdirectory searching}.
+Implementors are encouraged to provide enhancements to the basic
+principle of subdirectory searching to avoid performance problems, e.g.,
+the use of a filename cache (this can be as simple as a recursive
+directory listing) that is consulted before disk searching begins. If a
+match is found in the database, subdirectory searching is not required,
+and performance is thus independent of the number of subdirectories
+present on the system.
+
+Different implementations specify subdirectory searching differently.
+In the interest of typographic clarity, the examples here do not use the
+\replaceable{replaceable} font.
+
+\begin{description-squeeze}
+
+\item[\application{Dvips}:] via a separate
+\systemitem{ENVIRONVAR}{TEXFONTS\_SUBDIR} environment variable.
+
+\item[\application{em\TeX{}}:] \path|t:\subdir!!|; \path|t:\subdir!| for
+a single level of searching.
+
+\item[\application{Kpathsea}:] \path|texmf/subdir//|
+
+\item[\abbr{VMS}:] \path|texmf:[subdir...]|
+
+\item[\application{Xdvi} (patchlevel 20):] \path|texmf/subdir/**|;
+\path|texmf/subdir/*| for a single level of searching. Version 20.50
+and above support the \path|//| notation.
+
+\item[\application{Y\&Y \TeX{}}:] \path|t:/subdir//| or
+\path|t:\subdir\\|.
+
+\end{description-squeeze}
+
+
+\subsection{Example implementation-specific trees}
+\label{sec:Example implementation-specific trees}
+
+The \abbr{TDS} cannot specify a precise location for
+implementation-specific files, such as \path|texmf/ini|, because a site
+may have multiple \TeX{} implementations.
+
+Nevertheless, for informative purposes, we provide here the default
+locations for some implementations. Please contact us with additions or
+corrections. These paths are not definitive, may not match anything at
+your site, and may change without warning.
+
+We recommend all implementations have default search paths that start
+with the current directory (e.g., `\path|.|'). Allowing users to
+include the parent directory (e.g., `\path|..|') is also helpful.
+
+
+\subsubsection{AmiWeb2c 2.0}
+
+(Email \email|scherer at physik.rwth-aachen.de| to contact the maintainer
+of this implementation.)
+
+AmiWeb2c 2 is compatible with Web2c 7 to the greatest possible
+extent, so only the very few differences are described in this
+section. Detailed information about the basic concepts is given in
+the section for Web2c 7 below.
+
+Thanks to the \path|SELFAUTO| mechanism of Kpathsea 3.0 no specific
+location for the installation of AmiWeb2c is required as long as the
+general structure of the distribution is preserved.
+
+In addition to Kpathsea's \path|//| notation recursive path search may
+also be started by \replaceable{DEVICE}\path|:/|, e.g., \path|TeXMF:/|
+will scan this specific device completely.
+
+Binaries coming with the AmiWeb2c distribution are installed in the
+directory \path|bin/amiweb2c/| outside the common \abbr{TDS} tree
+\path|share/texmf/|. In addition to the set of AmiWeb2c binaries
+you will find two subdirectories \path|local/| and \path|pastex/|
+with auxiliary programs.
+
+A stripped version of the Pas\TeX{} system (used by kind permission of
+Georg He\ss{}mann) is coming with AmiWeb2c, pre-installed in its own
+\path|share/texmf/amiweb2c/pastex/| directory. If you want to use
+Pas\TeX{} you have to \path|assign| the name \path|TeX:| to this place.
+
+Documentation files in AmigaGuide format should be stored at
+\path|doc/guide/| similar to \path|doc/info/|.
+
+
+\subsubsection{Public \abbr{DECUS} \TeX{}}
+
+If another \abbr{VMS} implementation besides Public \abbr{DECUS} \TeX{}
+appears, the top level implementation directory name will be modified to
+something more specific (e.g., \path|vms_decus|).
+
+\begin{tdsSummary}
+ texmf/
+ . vms/ \abbr{VMS} implementation specific files
+ . . exe/ end-user commands
+ . . . common/ command procedures, command definition files, etc.
+ . . . axp/ binary executables for Alpha \abbr{AXP}
+ . . . vax/ binary executables for \abbr{VAX}
+ . . formats/ pool files, formats, bases
+ . . help/ \abbr{VMS} help library, and miscellaneous help sources
+ . . mgr/ command procedures, programs, docs, etc., for system management
+\end{tdsSummary}
+
+
+\subsubsection{Web2c 7}
+
+All implementation-dependent \TeX{} system files (\path|.pool|,
+\path|.fmt|, \path|.base|, \path|.mem|) are stored by default directly
+in \path|texmf/web2c|. The configuration file \path|texmf.cnf| and
+various subsidiary \path|MakeTeX...| scripts used as subroutines are
+also stored there.
+
+Non-\TeX{} specific files are stored following the \abbr{GNU} coding
+standards. Given a root directory \replaceable{prefix}
+(\path|/usr/local| by default), we have default locations as follows:
+
+\begin{tdsSummary}
+ <prefix>/ installation root (\path|/usr/local| by default)
+ . bin/ executables
+ . man/ man pages
+ . info/ info files
+ . lib/ libraries (\path|libkpathsea.*|)
+ . share/ architecture-independent files
+ . . texmf/ \abbr{TDS} root
+ . . . web2c/ implementation-dependent files (\path|.pool|, \path|.fmt|, \path|texmf.cnf|, etc.)
+\end{tdsSummary}
+
+See \url|http://www.gnu.org/prep/standards_toc.html| for the
+rationale behind and descriptions of this arrangement. A site may of
+course override these defaults; for example, it may put everything under
+a single directory such as \path|/usr/local/texmf|.
+
+
+\section{Is there a better way?}
+
+Defining the \abbr{TDS} required many compromises. Both the overall
+structure and the details of the individual directories were arrived at
+by finding common ground among many opinions. The driving forces were
+feasibility (in terms of what could technically be done and what could
+reasonably be expected from developers) and regularity (files grouped
+together in an arrangement that ``made sense'').
+
+Some interesting ideas could not be applied due to implementations
+lacking the necessary support:
+
+\begin{itemize}
+
+\item Path searching control at the \TeX{} level. If documents could
+restrict subdirectory searching to a subdirectory via some portable
+syntax in file names, restrictions on uniqueness of filenames could be
+relaxed considerably (with the cooperation of the formats), and the
+\TeX{} search path would not need to depend on the format.
+
+\item Multiple logical \texmf{} trees. For example, a site might have
+one (read-only) location for stable files, and a different (writable)
+location for dynamically-created fonts or other files. It would be
+reasonable for two such trees to be logically merged when searching.
+See Michael Downes' article in the references for how this can work in
+practice with Web2C.
+
+\end{itemize}
+
+\subsection{Macro structure}
+
+The \abbr{TWG} settled on the
+\replaceable{format}\path|/|\replaceable{package} arrangement after long
+discussion about how best to arrange the files.
+
+The primary alternative to this arrangement was a scheme which reversed
+the order of these directories:
+\replaceable{package}\path|/|\replaceable{format}. This reversed
+arrangement has a strong appeal: it keeps all of the files related to a
+particular package in a single place. The arrangement actually adopted
+tends to spread files out into two or three places (macros,
+documentation, and fonts, for example, are spread into different
+sections of the tree right at the top level).
+
+Nevertheless, the \replaceable{format}\path|/|\replaceable{package}
+structure won for a couple of reasons:
+
+\begin{itemize-squeeze}
+\item It is closer to current practice; in fact, several members of the
+\abbr{TWG} have already implemented the \abbr{TDS} hierarchy. The
+alternative is not in use at any known site, and the \abbr{TWG} felt it
+wrong to mandate something with which there is no practical experience.
+
+\item The alternative arrangement increases the number of top-level
+directories, so the files that must be found using subdirectory
+searching are spread out in a wide, shallow tree. This could have a
+profound impact on the efficiency of subdirectory searching.
+
+\end{itemize-squeeze}
+
+
+\subsection{Font structure}
+
+The \abbr{TWG} struggled more with the font directory structure than
+anything else. This is not surprising; the need to use the proliferation
+of PostScript fonts with \TeX{} is what made the previous arrangement
+with all files in a single directory untenable, and therefore what
+initiated the \abbr{TDS} effort.
+
+
+\subsubsection{Font file type location}
+
+We considered the supplier-first arrangement in use at many sites:
+
+\begin{ttdisplay}
+texmf/fonts/\replaceable{supplier}/\replaceable{typeface}/\replaceable{type}/
+\end{ttdisplay}
+
+This improves the maintainability of the font tree, since all files
+comprising a given typeface are in one place, but unless all the
+programs that search this tree employ some form of caching, there are
+serious performance concerns. For example, in order to find a
+\path|TFM| file, the simplest implementation would require \TeX{} to
+search through all the directories that contain \abbr{PK} files in all
+modes and at all resolutions.
+
+In the end, a poll of developers revealed considerable resistance to
+implementing sufficient caching mechanisms, so this arrangement was
+abandoned. The \abbr{TDS} arrangement allows the search tree to be
+restricted to the correct type of file, at least. Concerns about
+efficiency remain, but there seems to be no more we can do without
+abandoning subdirectory searching entirely.
+
+We also considered segregating all font-related files strictly by file
+type, so that \MF{} sources would be in a directory
+\path|texmf/fonts/mf|, property list files in \path|texmf/fonts/pl|, the
+various forms of Type~1 fonts separated, and so on. Although more
+blindly consistent, we felt that the drawback of more complicated path
+constructions outweighed this. The \abbr{TDS} merges file types
+(\path|mf| and \path|pl| under \path|source|, \path|pfa| and \path|pfb|
+and \path|gsf| under \path|type1|) where we felt this was beneficial.
+
+
+\subsubsection{Mode and resolution location}
+
+We considered having the \path|mode| at the bottom of the font tree:
+\begin{ttdisplay}
+texmf/fonts/pk/\replaceable{supplier}/\replaceable{typeface}/\replaceable{mode}/\replaceable{dpi}/
+\end{ttdisplay}
+
+In this case, however, it is difficult to limit subdirectory searching
+to the mode required for a particular device.
+
+We then considered moving the \path|dpi|\replaceable{nnn} up to below
+the mode:
+\begin{ttdisplay}
+texmf/fonts/pk/\replaceable{mode}/\replaceable{dpi}/\replaceable{supplier}/\replaceable{typeface}/
+\end{ttdisplay}
+
+But then it is not feasible to omit the \path|dpi|\replaceable{nnn}
+level altogether on systems which can and do choose to use long
+filenames.
+
+
+\subsubsection{Modeless bitmaps}
+
+The \abbr{TDS} specifies using a single directory \path|modeless/| as
+the mode name for those utilities which generate bitmaps, e.g.,
+\path|texmf/fonts/modeless/times/|. This has the considerable advantage
+of not requiring each such directory name to be listed in a search path.
+
+An alternative was to use the utility name below which all such
+directories could be gathered. That has the advantage of separating,
+say, \path|gsftopk|-generated bitmaps from \path|ps2pk|-generated ones.
+However, we decided this was not necessary; most sites will use only one
+program for the purpose. Also, \abbr{PK} and \abbr{GF} fonts generally
+identify their creator in the font comment following the \path|PK_ID|
+byte.
+
+We are making an implicit assumption that \MF{} is the only program
+producing mode-dependent bitmaps. If this becomes false we could add an
+abbreviation for the program to mode names, as in \path|mfcx| vs.\
+\path|xyzcx| for a hypothetical program \application{Xyz}, or we could
+at that time add an additional program name level uniformly to the tree.
+It seemed more important to concisely represent the current situation
+than to worry about hypothetical possibilities that may never~happen.
+
+
+\subsection{Documentation structure}
+
+We considered placing additional documentation files in the same
+directory as the source files for the packages, but we felt that users
+should be able to find documentation separately from sources, since most
+users have no interest in sources.
+
+We hope that a separate, but parallel, structure for documentation would
+(1)~keep the documentation together and (2)~make it as straightforward
+as possible for users to find the particular documentation they were
+after.
+
+
+\section{Related references}
+\label{sec:Related references}
+
+This appendix gives pointers to related files and other documents. For
+\abbr{CTAN} references, we use \path|http://www.ctan.org| as the
+top-level domain only to make the links be live in this document. See
+\url|http://www.ctan.org/tex-archive/CTAN.sites| for a complete list of
+\abbr{ctan} sites; there are mirrors worldwide.
+
+\begin{itemize-squeeze}
+
+\item This document, in many formats (tex, dvi, info, pdf):\\ \hspace*{1em}
+\url|http://tug.org/tds/|
+
+\item The \abbr{TDS} mailing list archives:\\ \hspace*{1em}
+\url|http://tug.org/mail-archives/twg-tds/|
+
+\item The level~0 \abbr{DVI} driver standard:\\ \hspace*{1em}
+\url|http://www.ctan.org/tex-archive/dviware/driv-standard/level-0/|
+
+\item \citetitle{Filenames for \TeX{} fonts}, with lists of recommended
+supplier and typeface names:\\ \hspace*{1em}
+\url|http://tug.org/fontname/|
+
+\item \abbr{ISO}-9660 \abbr{CD-ROM} file system standard:\\ \hspace*{1em}
+\url|http://www.iso.ch/cate/cat.html|
+
+\item \citetitle{Components of \TeX{}}, a paper by Joachim
+Schrod:\\ \hspace*{1em}
+\url|http://www.ctan.org/tex-archive/documentation/components-of-TeX/|
+
+\item \citetitle{Managing Multiple TDS trees}, an article by Michael
+Downes:\\ \hspace*{1em}
+\url|http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf|
+
+\item A complete set of \MF{} modes:\\ \hspace*{1em}
+\url|http://www.ctan.org/tex-archive/fonts/modes/modes.mf|
+
+\item A large collection of \BibTeX{} databases and styles:\\ \hspace*{1em}
+\url|ftp://ftp.math.utah.edu/pub/tex/bib/|
+
+\end{itemize-squeeze}
+
+
+\section{Contributors}
+
+The \abbr{TWG} has had no physical meetings; electronic mail was the
+communication medium.
+
+Sebastian Rahtz is the \TeX{} Users Group Technical Council liaison.
+Norman Walsh was the original committee chair. Karl Berry is the
+current editor.
+
+The list of contributors has grown too large to fairly include, as some
+would surely be inadvertently omitted. Please consider the archives of
+the \email|tds at tug.org| and \email|tex-live at tug.org| mailing lists as
+the record of contributions.
+
+
+\end{document}
Added: tex-common/trunk/doc/tds-1.1/tds.texi
===================================================================
--- tex-common/trunk/doc/tds-1.1/tds.texi 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/tds.texi 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1,1834 @@
+% Id: tds.tex,v 1.43 2004/06/23 17:24:42 karl Exp
+\input texinfo
+ at setfilename tds.info
+ at settitle A Directory Structure for TeX Files
+
+ at set version 1.1
+
+ at dircategory TeX
+ at direntry
+* TeX Directories: (tds). A directory structure for TeX files.
+ at end direntry
+
+
+ at titlepage
+ at title A Directory Structure for TeX Files
+ at subtitle Version @value{version}
+ at author TUG Working Group on a TeX Directory Structure (TWG-TDS)
+
+ at page
+ at vskip 0pt plus 1filll
+
+Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2003, 2004
+TeX Users Group.
+
+Permission to use, copy, and distribute this document @emph{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 at tie{}@ref{Related references}).
+Please send questions or suggestions by email to
+ at email{tds@@tug.org}. We welcome all comments. This is version
+ at value{version}.
+
+ at end titlepage
+
+ at ifnottex
+ at node Top
+ at top A Directory Structure for TeX Files
+
+Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2003, 2004
+TeX Users Group.
+
+Permission to use, copy, and distribute this document @emph{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 at tie{}@ref{Related references}).
+Please send questions or suggestions by email to
+ at email{tds@@tug.org}. We welcome all comments. This is version
+ at value{version}.
+
+ at menu
+* Introduction::
+* General::
+* Top-level directories::
+* Summary::
+* Unspecified pieces::
+* Implementation issues::
+* Is there a better way?::
+* Related references::
+* Contributors::
+
+ at detailmenu
+ --- 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::
+
+ at end detailmenu
+ at end menu
+
+ at end ifnottex
+
+
+
+ at node Introduction
+ at chapter 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 at . 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 at tie{}@ref{Related references}.
+
+
+ at menu
+* History::
+* The role of the TDS::
+* Conventions::
+ at end menu
+
+ at node History
+ at section 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:
+
+ at itemize @bullet
+ at item Inputs for TeX extensions included under @file{tex}, instead
+ of in their own top-level directories (Section at tie{}@ref{Extensions})
+ at item New top-level directory @file{scripts} (Section at tie{}@ref{Scripts}).
+ at item New subdirectories @file{lig}, @file{opentype},
+ @file{truetype}, and @file{type3} under @file{fonts}
+ (Section at tie{}@ref{Fonts}).
+ at item @samp{enc},
+ at file{lig}, and @file{map} all use
+ @file{@var{syntax}/@var{package}} subdirectories
+ (Section at tie{}@ref{Fonts}).
+ at item @samp{pfm} files specified to go under @file{type1},
+and
+ @file{inf} files under @file{afm} (Section at tie{}@ref{Fonts}).
+ at end itemize
+
+
+ at node The role of the TDS
+ at section 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.
+
+
+ at node Conventions
+ at section Conventions
+
+In this document, @file{/} is used to separate filename components;
+for example, @file{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
+ at emph{not} a LaTeX2e package, which is a style file supplementing
+a document class.
+
+We use the following typographic conventions:
+
+ at itemize @bullet
+
+ at item @samp{literal}
+Literal text such as @file{filename} is
+typeset in typewriter type.
+
+ at item @samp{@var{replaceable}}
+Replaceable text such as
+ at file{@var{package}}, identifying a class of things, is typeset in
+italics inside angle brackets.
+
+ at end itemize
+
+
+ at node General
+ at chapter General
+
+This section describes common properties throughout the TDS tree.
+
+ at menu
+* Subdirectory searching::
+* Rooting the tree::
+* Local additions::
+* Duplicate filenames::
+ at end menu
+
+ at node Subdirectory searching
+ at section Subdirectory searching
+
+Older TeX installations store large numbers of related files in single
+directories, for example, all @file{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 at tie{}@ref{More on subdirectory searching}).
+
+
+ at node Rooting the tree
+ at section Rooting the tree
+
+In this document, we shall designate the root TDS directory by
+ at file{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 @file{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, @file{/usr/local/share}, @file{/usr/local},
+ at file{/usr/local/lib}, and @file{/opt} are common choices.
+
+The name @file{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.
+
+
+ at node Local additions
+ at section 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
+ at file{texmf} tree. Both have their place; in fact, some sites employ
+both simultaneously:
+
+ at enumerate
+
+ at item A completely separate tree which is a TDS structure
+itself; for example, @file{/usr/local/umbtex} at the University of
+Massachusetts at Boston. This is another example of the multiple
+ at file{texmf} hierarchies mentioned in the previous section.
+
+ at item A directory named @file{local} at any appropriate level, for
+example, in the @file{@var{format}}, @file{@var{package}}, and
+ at file{@var{supplier}} directories discussed in the following sections.
+The TDS reserves the directory name @file{local} for this
+purpose.
+
+We recommend using @file{local} for site-adapted configuration files,
+such as @file{language.dat} for the Babel package or @file{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.
+
+ at end enumerate
+
+One common case of local additions is dynamically generated files, e.g.,
+PK fonts by the @file{mktexpk} script (which originated in
+Dvips as @file{MakeTeXPK}). A site may store the
+generated files directly in any of:
+ at itemize @bullet
+ at item their standard location in the main TDS tree (if it can be
+made globally writable);
+
+ at item an alternative location in the main TDS tree (for
+example, under @file{texmf/fonts/tmp});
+
+ at item a second complete TDS tree (as outlined above);
+
+ at item any other convenient directory (perhaps under
+ at file{/var}, for example @file{/var/spool/fonts}).
+
+ at end itemize
+
+No one solution will be appropriate for all sites.
+
+
+ at node Duplicate filenames
+ at section 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:
+
+ at itemize @bullet
+
+ at item Names of TeX input files must be unique within each first-level
+subdirectory of @file{texmf/tex} and @file{texmf/tex/generic}, but not
+within all of @file{texmf/tex}; i.e., different TeX formats may have
+files by the same name. (Section at tie{}@ref{Macros} discusses this
+further.) Thus, no single format-independent path specification, such
+as a recursive search beginning at @file{texmf/tex} specifying no other
+directories, suffices. So implementations must provide format-dependent
+path specifications, for example via wrapper scripts or configuration
+files.
+
+ at item Many font files will have the same name (e.g., @file{cmr10.pk}),
+as discussed in Section at tie{}@ref{Valid font bitmaps}. Implementations
+must distinguish these files by mode and resolution.
+
+ at end itemize
+
+All implementations we know of already have these capabilities.
+
+One place where duplicate names are likely to occur is not an exception:
+
+ at itemize @bullet
+
+ at item Names of Metafont input files (as opposed to bitmaps) must be unique
+within all of @file{texmf/fonts}. In practice, this is a problem with
+some variants of Computer Modern which contain slightly modified files
+named @file{punct.mf}, @file{romanl.mf}, and so on. We believe the only
+feasible solution is to rename the derivative files to be
+unique.
+
+ at end itemize
+
+
+ at node Top-level directories
+ at chapter Top-level directories
+
+The directories under the @file{texmf} root identify the major components of
+a TeX system (see Section at tie{}@ref{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 @file{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:
+
+ at itemize @bullet
+ at item @samp{tex}
+for TeX files (Section at tie{}@ref{Macros}).
+
+ at item @samp{fonts}
+for font-related files (Section at tie{}@ref{Fonts}).
+
+ at item @samp{metafont}
+for Metafont files which are not fonts (Section at tie{}@ref{Non-font Metafont files}).
+
+ at item @samp{metapost}
+for MetaPost files (Section at tie{}@ref{MetaPost}).
+
+ at item @samp{bibtex}
+for BibTeX files (Section at tie{}@ref{BibTeX}).
+
+ at item @samp{scripts}
+for platform-independent executables (Section at tie{}@ref{Scripts}).
+
+ at item @samp{doc}
+for user documentation (Section at tie{}@ref{Documentation}).
+
+ at item @samp{source}
+for sources. This includes both traditional
+program sources (for example, Web2C sources go in
+ at file{texmf/source/web2c}) and, e.g., LaTeX @file{dtx} sources (which
+go in @file{texmf/source/latex}). The TDS leaves unspecified any
+structure under @file{source}.
+
+ at file{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, @file{plain.tex} does not belong under @file{texmf/source},
+even though it is a ``source file'' in the sense of not being derived
+from another file. (It goes in @file{texmf/tex/plain/base}, as explained
+in Section at tie{}@ref{Macros}).
+
+ at item @samp{@var{implementation}}
+for implementations (examples:
+ at file{emtex}, @file{vtex}, @file{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 (@file{tex.pool}) and memory dump files (@file{plain.fmt}) go
+here, in addition to implementation-wide configuration files. See
+Section at tie{}@ref{Example implementation-specific trees} for examples of
+real @file{@var{implementation}} trees.
+
+Such implementation-specific configuration files should @emph{not}
+be located using the main TeX input search path (e.g.,
+ at file{TEXINPUTS}). This must be reserved for files actually read by a
+TeX engine. See Section at tie{}@ref{Extensions}.
+
+ at item @samp{@var{program}}
+for program-specific input and
+configuration files for any TeX-related programs (examples:
+ at file{mft}, @file{dvips}). In fact, the @file{tex}, @file{metafont},
+ at file{metapost}, and @file{bibtex} items above may all be seen as
+instances of this case.
+
+ at end itemize
+
+
+ at menu
+* Macros::
+* Fonts::
+* Non-font Metafont files::
+* MetaPost::
+* BibTeX::
+* Scripts::
+* Documentation::
+ at end menu
+
+ at node Macros
+ at section 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 @file{\dump}-able package):
+ at example
+texmf/tex/@var{format}/@var{package}/
+ at end example
+
+ at itemize @bullet
+
+ at item @samp{@var{format}}
+is a format name (examples: @file{amstex},
+ at file{latex}, @file{plain}, @file{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
+ at file{@var{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 @file{@var{format}} names:
+
+ at itemize @bullet
+
+ at item @samp{generic},
+for input files that are useful across a wide
+range of formats (examples: @file{null.tex}, @file{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
+ at file{texmf/tex/plain}), e.g., @file{testfont.tex} and @file{plain.tex}
+itself.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local
+additions}.
+
+ at end itemize
+
+Thus, for almost every format, it is necessary to search at least the
+ at file{@var{format}} directory and then the @file{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
+ at file{amstex}, @file{plain}, and @file{generic} directories should be
+searched, because AMS-TeX is compatible with Plain.
+
+ at item @samp{@var{package}}
+is a TeX package name (examples:
+ at file{babel}, @file{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
+ at file{@var{format}} directory, instead of
+ at file{@var{format}/base}. For example, Texinfo may go in
+ at file{texmf/tex/texinfo/texinfo.tex}, not
+ at file{texmf/tex/texinfo/base/texinfo.tex}.
+
+The TDS reserves the following @file{@var{package}} names:
+
+ at itemize @bullet
+
+ at item @samp{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 @file{ltx} files
+created during the build process. Another example: the @file{.ini}
+driver files for formats used by TeX Live and other distributions.
+
+ at item @samp{hyphen},
+for hyphenation patterns, including the original
+American English @file{hyphen.tex}. These are typically used only by
+INITEX. In most situations, this directory need exist only under the
+ at file{generic} format.
+
+ at item @samp{images},
+for image input files, such as Encapsulated
+PostScript figures. Although it is somewhat non-intuitive for these to
+be under a directory named @file{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 at . In most situations, this directory need exist only under
+the @file{generic} format.
+
+ at item @samp{local},
+for local additions and configuration files. See
+Section at tie{}@ref{Local additions}.
+
+ at item @samp{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 @file{misc}.
+
+ at end itemize
+
+ at end itemize
+
+
+ at menu
+* Extensions::
+ at end menu
+
+ at node Extensions
+ at subsection 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 @file{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:
+
+ at example
+texmf/tex/aleph
+texmf/tex/enctex
+ at end example
+
+This is a change from TDS at tie{}1.0, which specified top-level
+ at file{@var{extension}} directories for each such program. We felt the
+new approach is preferable, because:
+
+ at itemize @bullet
+
+ at item Authors of relevant packages typically make their code detect the
+engine being used, and issue error messages or adapt to circumstances
+appropriately. Furthermore, as a package matures, it may support
+multiple engines. Thus, a package could conceivably be placed in any of
+several top-level directories, at different times. Putting all packages
+under the top-level @file{tex} directory provides a stable location over
+time.
+
+ at item Users need to be able to switch between engines, and configuring
+different search paths for each engine is difficult and error-prone.
+
+ at end itemize
+
+Thus, in practice, having different top-level directories caused
+difficulties for everyone involved---users, package authors, site
+administrators, and system distributors.
+
+Please contrast this approach with the @file{@var{implementation}}
+top-level subdirectory (Section at tie{}@ref{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.
+
+
+ at node Fonts
+ at section 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.
+
+ at example
+texmf/fonts/@var{type}/@var{supplier}/@var{typeface}/
+texmf/fonts/enc,lig,map/@var{subpath}/
+ at end example
+
+ at itemize @bullet
+
+ at item @samp{@var{type}}
+is the type of font file. The TDS
+reserves the following @file{@var{type}} names for common TeX file
+types:
+
+ at itemize @bullet
+ at item @samp{afm},
+for Adobe font metrics, and @file{inf} files.
+ at item @samp{gf},
+for generic font bitmap files.
+ at item @samp{opentype},
+for OpenType fonts.
+ at item @samp{pk},
+for packed bitmap files.
+ at item @samp{source},
+for font sources (Metafont files, property lists, etc.).
+ at item @samp{tfm},
+for TeX font metric files.
+ at item @samp{truetype},
+for TrueType fonts.
+ at item @samp{type1},
+for PostScript Type 1 fonts (in @file{pfa},
+ @file{pfb}, or any other format), and @file{pfm} files.
+ at item @samp{type3},
+for PostScript Type 3 fonts.
+ at item @samp{vf},
+for virtual fonts.
+ at end itemize
+
+The TDS also reserves the names @file{enc}, @file{lig}, and
+ at file{map} for font encoding, ligature, and mapping files, respectively.
+All of these directories are structured the same way, with
+ at file{@var{syntax}} subdirectories, and then @file{@var{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:
+ at example
+fonts/map/dvipdfm/updmap/dvipdfm.map
+fonts/map/dvips/lm/lm.map
+fonts/enc/dvips/base/8r.enc
+ at end example
+
+The Fontname and Dvips packages have more examples of the @file{enc} and
+ at file{map} types. The @file{afm2pl} program uses @file{lig} files.
+
+ at file{pfm} files are included in the @file{type1} directory, instead of
+being given their own directory, for two reasons: 1)@tie{}a @file{.pfm} file
+is always an adjunct to a given @file{.pfb} file; 2)@tie{}they must be
+installed from the same directory for Windows programs other than TeX
+to use them.
+
+ at file{inf} files are included in the @file{afm} directory, since
+an @file{inf} and @file{afm} file can be used to generate a @file{pfm}.
+(Unfortunately, Adobe Type Manager and perhaps other software requires
+that the @file{pfb} be in the same directory as @file{afm} and
+ at file{inf} for installation.)
+
+As usual, a site may omit any of these directories that are unnecessary.
+ at file{gf} is a particularly likely candidate for omission.
+
+ at item @samp{@var{supplier}}
+is a name identifying font source
+(examples: @file{adobe}, @file{ams}, @file{public}). The TDS
+reserves the following @file{@var{supplier}} names:
+
+ at itemize @bullet
+
+ at item @samp{ams},
+for the American Mathematical Society's AMS-fonts
+collection.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local additions}.
+
+ at item @samp{public},
+for freely redistributable fonts where the supplier
+neither (1)@tie{}requested their own directory (e.g., @file{ams}), nor
+(2)@tie{}also made proprietary fonts (e.g., @file{adobe}). It does not
+contain all extant freely distributable fonts, nor are all files therein
+necessarily strictly public domain.
+
+ at item @samp{tmp},
+for dynamically-generated fonts, as is traditional on
+some systems. It may be omitted if unnecessary, as usual.
+
+ at end itemize
+
+
+ at item @samp{@var{typeface}}
+is the name of a typeface family
+(examples: @file{cm}, @file{euler}, @file{times}). The TDS
+reserves the following @file{@var{typeface}} names:
+
+ at itemize @bullet
+
+ at item @samp{cm} (within @file{public}),
+for the 75 fonts defined in
+ at cite{Computers and Typesetting, Volume at tie{}E}.
+
+ at item @samp{latex} (within @file{public}),
+for those fonts distributed
+with LaTeX in the base distribution.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local additions}.
+
+ at end itemize
+
+ at end itemize
+
+Some concrete examples:
+ at example
+texmf/fonts/source/public/pandora/pnr10.mf
+texmf/fonts/tfm/public/cm/cmr10.tfm
+texmf/fonts/type1/adobe/utopia/putr.pfa
+ at end example
+
+For complete supplier and typeface name lists, consult
+ at cite{Filenames for TeX fonts} (see Appendix at tie{}@ref{Related
+references}).
+
+ at menu
+* Font bitmaps::
+* Valid font bitmaps::
+ at end menu
+
+ at node Font bitmaps
+ at subsection Font bitmaps
+
+Font bitmap files require two characteristics in addition to the above
+to be uniquely identifiable: (1)@tie{}the type of device (i.e., mode) for
+which the font was created; (2)@tie{}the resolution of the bitmap.
+
+Following common practice, the TDS segregates fonts with
+different device types into separate directories. See @file{modes.mf}
+in Appendix at tie{}@ref{Related references} for recommended mode names.
+
+Some printers operate at more than one resolution (e.g., at 300 at dmn{dpi} and
+600 at dmn{dpi}), but each such resolution will necessarily have a different
+mode name. Nothing further is needed, since implicit in the TeX
+system is the assumption of a single target resolution.
+
+Two naming strategies are commonly used to identify the resolution of
+bitmap font files. On systems that allow long filenames (and in the
+original Metafont program itself), the resolution is included in the
+filename (e.g., @file{cmr10.300pk}). On systems which do not support
+long filenames, fonts are generally segregated into directories by
+resolution (e.g., @file{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 @file{pk} and @file{gf}:
+
+ at example
+texmf/fonts/pk/@var{mode}/@var{supplier}/@var{typeface}/dpi at var{nnn}/
+texmf/fonts/gf/@var{mode}/@var{supplier}/@var{typeface}/dpi at var{nnn}/
+ at end example
+
+ at itemize @bullet
+
+ at item @samp{@var{mode}}
+is a name which identifies the device type
+(examples: @file{cx}, @file{ljfour}, @file{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 @file{@var{mode}} name shall be simply
+ at file{modeless}. The @file{@var{mode}} level shall not be omitted,
+even if only a single mode happens to be in use.
+
+ at item @samp{dpi at var{nnn}}
+specifies the resolution of the font
+(examples: @file{dpi300}, @file{dpi329}). @file{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 @file{@var{nnn}} is to be calculated as if using Metafont
+arithmetic and then rounded; i.e., it is the integer Metafont uses in its
+output @file{gf} filename. We recognize small differences in the
+resolution are a common cause of frustration among users, however, and
+recommend implementors follow the level at tie{}0 DVI driver standard
+(see Appendix at tie{}@ref{Related references}) in bitmap font searches by
+allowing a fuzz of +-0.2% (with a minimum of 1) in the
+ at file{@var{dpi}}.
+
+ at end itemize
+
+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 @file{.fli} files), provided that the basic scheme is also
+supported.
+
+ at node Valid font bitmaps
+ at subsection 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,
+ at file{cmr10.pk} will be the filename for Computer Modern Roman 10 at dmn{pt} at
+5--10 magnifications for 2--3 modes. (Section at tie{}@ref{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) @file{modes.mf} (see Appendix at tie{}@ref{Related
+references}), the required information is already in your PK
+files. If not, a simple addition based on the code found in
+ at file{modes.mf} can be made to your local modes file and the PK
+files rebuilt.
+
+
+ at node Non-font Metafont files
+ at section 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:
+
+ at example
+texmf/metafont/@var{package}/
+ at end example
+
+ at file{@var{package}} is the name of a
+Metafont package (for example, @file{mfpic}).
+
+The TDS reserves the following @file{@var{package}} names:
+
+ at itemize @bullet
+
+ at item @samp{base},
+for the standard Metafont macro files as described in
+ at cite{The Metafontbook}, such as @file{plain.mf} and @file{expr.mf}.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local additions}.
+
+ at item @samp{misc},
+for Metafont packages consisting of only a single file
+(for example, @file{modes.mf}). An administrator or package maintainer
+may create directories for single-file packages at their discretion,
+instead of using @file{misc}.
+
+ at end itemize
+
+
+ at node MetaPost
+ at section 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:
+
+ at example
+texmf/metapost/@var{package}/
+ at end example
+
+ at file{@var{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 @file{@var{package}} names:
+
+ at itemize @bullet
+
+ at item @samp{base},
+for the standard MetaPost macro files, such as
+ at file{plain.mp}, @file{mfplain.mp}, @file{boxes.mp}, and
+ at file{graph.mp}. This includes files used by INIMP when dumping mem
+files containing preloaded macro definitions.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local
+additions}.
+
+ at item @samp{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 @file{misc}.
+
+ at item @samp{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.
+
+ at end itemize
+
+
+ at node BibTeX
+ at section BibTeX
+
+BibTeX-related files shall be stored in:
+
+ at example
+texmf/bibtex/bib/@var{package}/
+texmf/bibtex/bst/@var{package}/
+ at end example
+
+The @file{bib} directory is for BibTeX database (@file{.bib}) files,
+the @file{bst} directory for style (@file{.bst}) files.
+
+ at file{@var{package}} is the name of a BibTeX package. The
+TDS reserves the following @file{@var{package}} names (the same
+names are reserved under both @file{bib} and @file{bst}):
+
+ at itemize @bullet
+
+ at item @samp{base},
+for the standard BibTeX databases and styles, such
+as @file{xampl.bib}, @file{plain.bst}.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local
+additions}.
+
+ at item @samp{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 @file{misc}.
+
+ at end itemize
+
+
+ at node Scripts
+ at section Scripts
+
+The top-level @file{scripts} directory is for platform-independent
+executables, such as Perl, Python, and shell scripts, and Java class
+files. Subdirectories under @file{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,
+ at file{scripts} also serves as a platform-independent analog of the
+standard Unix @file{libexec} directory.
+
+We recommend using extensions specifying the language (such as
+ at file{.pl}, @file{.py}, @file{.sh}) on these files, to help uniquely
+identify the name. Since the intent of the TDS is for programs
+in @file{scripts} not to be invoked directly by users, this poses no
+inconvenience.
+
+For example, in the TeX Live distribution, the ConTeXt user-level
+program @file{texexec} can exist as a small wrapper script in each
+ at file{bin/@var{platform}/texexec} (which is outside the
+ at file{texmf} tree), which merely finds and calls
+ at file{texmf/scripts/context/perl/texexec.pl}.
+
+Examples:
+ at example
+scripts/context/perl/texexec.pl
+scripts/context/ruby/examplex.rb
+scripts/thumbpdf/thumbpdf.pl
+ at end example
+
+The TDS does not specify a location for platform-dependent
+binary executables, whether auxiliary or user-level.
+
+
+ at node Documentation
+ at section 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
+ at file{fonts} and @file{tex} directories, as follows:
+
+ at example
+texmf/doc/@var{category}/...
+ at end example
+
+ at file{@var{category}} identifies the general topic of documentation
+that resides below it; for example, a TeX format name (@file{latex}),
+program name (@file{bibtex}, @file{tex}), language (@file{french},
+ at file{german}), a file format (@file{info}, @file{man}), or other system
+components (@file{web}, @file{fonts}).
+
+One possible arrangement is to organize @file{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 @file{@var{category}} tree for a TeX format, the
+directory @file{base} is reserved for base documentation distributed by
+the format's maintainers.
+
+The TDS reserves the following category names:
+
+ at itemize @bullet
+
+ at item @samp{general},
+for standalone documents not specific to any
+particular program (for example, Joachim Schrod's @cite{Components
+of TeX}).
+
+ at item @samp{help},
+for meta-information, such as FAQ's,
+the TeX Catalogue, etc.
+
+ at item @samp{info},
+for processed Texinfo documents. (Info files, like
+anything else, may also be stored outside the TDS, at the
+installer's option.)
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local
+additions}.
+
+ at end itemize
+
+The @file{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 @file{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 at tie{}@ref{Documentation tree summary} for a summary.
+
+
+ at node Summary
+ at chapter Summary
+
+A skeleton of a TDS @file{texmf} directory tree. This is not to
+imply these are the only entries allowed. For example, @file{local} may
+occur at any level.
+
+ at example
+ bibtex/ BibTeX input files
+ bib/ BibTeX databases
+ base/ base distribution (e.g., @file{xampl.bib})
+ misc/ single-file databases
+ <package>/ name of a package
+ bst/ BibTeX style files
+ base/ base distribution (e.g., @file{plain.bst}, @file{acm.bst})
+ misc/ single-file styles
+ <package>/ name of a package
+ doc/ see Section at tie{}@ref{Documentation} and the summary below
+ fonts/ font-related files
+ <type>/ file type (e.g., @file{pk})
+ <mode>/ type of output device (for @file{pk} and @file{gf} only)
+ <supplier>/ name of a font supplier (e.g., @file{public})
+ <typeface>/ name of a typeface (e.g., @file{cm})
+ dpi<nnn>/ font resolution (for @file{pk} and @file{gf} only)
+ <implementation>/ TeX implementations, by name (e.g., @file{emtex})
+ local/ files created or modified at the local site
+ metafont/ Metafont (non-font) input files
+ base/ base distribution (e.g., @file{plain.mf})
+ misc/ single-file packages (e.g., @file{modes.mf})
+ <package>/ name of a package (e.g., @file{mfpic})
+ metapost/ MetaPost input and support files
+ base/ base distribution (e.g., @file{plain.mp})
+ misc/ single-file packages
+ <package>/ name of a package
+ support/ support files for MetaPost-related utilities
+ mft/ @file{MFT} inputs (e.g., @file{plain.mft})
+ <program>/ TeX-related programs, by name (e.g., @file{dvips})
+ source/ program source code by name (e.g., @file{latex}, @file{web2c})
+ tex/ TeX input files
+ <engine>/ name of an engine (e.g., @file{aleph}); can also be lower
+ <format>/ name of a format (e.g., @file{plain})
+ base/ base distribution for format (e.g., @file{plain.tex})
+ misc/ single-file packages (e.g., @file{webmac.tex})
+ local/ local additions to or local configuration files for @file{@var{format}}
+ <package>/ name of a package (e.g., @file{graphics}, @file{mfnfss})
+ generic/ format-independent packages
+ hyphen/ hyphenation patterns (e.g., @file{hyphen.tex})
+ images/ image input files (e.g., Encapsulated PostScript)
+ misc/ single-file format-independent packages (e.g., @file{null.tex}).
+ <package>/ name of a package (e.g., @file{babel})
+ at end example
+
+
+ at menu
+* Documentation tree summary::
+ at end menu
+
+ at node Documentation tree summary
+ at section Documentation tree summary
+
+An example skeleton of a TDS directory tree under
+ at file{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 @file{texmf/doc} tree may be organized by language, so
+that all documentation in French, say, is in a @file{french}
+subdirectory. In that case, the example structure here would be in a
+given language directory.
+
+ at example
+ ams/
+ amsfonts/ @file{amsfonts.faq}, @file{amfndoc}
+ amslatex/ @file{amslatex.faq}, @file{amsldoc}
+ amstex/ @file{amsguide}, @file{joyerr}
+ bibtex/ BibTeX
+ base/ @file{btxdoc.tex}
+ fonts/
+ fontname/ @cite{Filenames for TeX fonts}
+ oldgerm/ @file{corkpapr}
+ <format>/ name of a TeX format (e.g., @file{generic}, @file{latex})
+ base/ for the base distribution
+ misc/ for contributed single-file package documentation
+ <package>/ for @emph{package}
+ general/ across programs, generalities
+ errata/ @file{errata}, @file{errata[1-8]}
+ texcomp/ @cite{Components of TeX}
+ help/ meta-information
+ ctan/ info about CTAN mirror sites
+ faq/ FAQs of @file{comp.text.tex}, etc.
+ info/ GNU Info files, made from Texinfo sources
+ latex/ example of @file{@var{format}}
+ base/ @file{ltnews*}, @file{*guide}, etc.
+ graphics/ @file{grfguide}
+ local/ site-specific documentation
+ man/ Unix man pages
+ <program>/ TeX-related programs, by name (examples follow)
+ metafont/ @file{mfbook.tex}, @file{metafont-for-beginners}, etc.
+ metapost/ @file{mpman}, @file{manfig}, etc.
+ tex/ @file{texbook.tex}, @cite{A Gentle Introduction to TeX}, etc.
+ web/ @file{webman}, @file{cwebman}
+ at end example
+
+
+
+ at node Unspecified pieces
+ at appendix Unspecified pieces
+
+The TDS cannot address the following aspects of a functioning
+TeX system:
+
+ at enumerate
+
+ at item The location of executable programs: this is too site-dependent
+even to recommend a location, let alone require one. A site may place
+executables outside the @file{texmf} tree altogether (e.g.,
+ at file{/usr/local/bin}), in a platform-dependent directory within
+ at file{texmf}, or elsewhere.
+
+ at item Upgrading packages when new releases are made: we could find no
+way of introducing version specifiers into @file{texmf} that would do more
+good than harm, or that would be practical for even a plurality of
+installations.
+
+ at item The location of implementation-specific files (e.g., TeX
+ at file{.fmt} files): by their nature, these must be left to the
+implementor or TeX maintainer. See Section at tie{}@ref{Example
+implementation-specific trees}.
+
+ at item Precisely when a package or file should be considered ``local'',
+and where such local files are installed. See Section at tie{}@ref{Local
+additions} for more discussion.
+
+ at end enumerate
+
+
+ at menu
+* Portable filenames::
+ at end menu
+
+ at node Portable filenames
+ at section 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:
+
+ at itemize @bullet
+
+ at item File and directory names, not including any directory path or
+extension part, may not exceed eight characters.
+
+ at item Filenames may have a single extension. Extensions may not exceed
+three characters. Directory names may not have an extension.
+
+ at item Names and extensions may consist of @emph{only} the characters
+ at file{A}-- at file{Z}, @file{0}-- at file{9}, and underscore.
+Lowercase letters are excluded.
+
+ at item A period separates the filename from the extension and is always
+present, even if the name or extension is missing (e.g.,
+ at file{FILENAME.} or @file{.EXT}).
+
+ at item A version number, ranging from 1--32767, is appended to the file
+extension, separated by a semicolon (e.g., @file{FILENAME.EXT;1}).
+
+ at item Only eight directory levels are allowed, including the top-level
+(mounted) directory (see Section at tie{}@ref{Rooting the tree}). Thus, the
+deepest valid ISO-9660 path is:
+ at example
+texmf/L2/L3/L4/L5/L6/L7/L8/FOO.BAR;1
+1 2 3 4 5 6 7 8
+ at end example
+The deepest TDS path needs only seven levels:
+ at example
+texmf/fonts/pk/cx/public/cm/dpi300/cmr10.pk
+1 2 3 4 5 6 7
+ at end example
+
+ at end itemize
+
+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.
+
+ at node Implementation issues
+ at appendix 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.
+
+
+ at menu
+* Adoption of the TDS::
+* More on subdirectory searching::
+* Example implementation-specific trees::
+ at end menu
+
+ at node Adoption of the TDS
+ at section 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:
+
+ at itemize @bullet
+ at item Clear and demonstrable benefits can be shown for the TDS.
+ at item TDS-compliant versions of all key programs are available
+in ported, well-tested forms.
+ at item A ``settling'' period has taken place, to flush out problems. The
+public release of the first draft of this document was the first step in
+this process.
+ at end itemize
+
+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 at tie{}@ref{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.
+
+
+ at node More on subdirectory searching
+ at section More on subdirectory searching
+
+Recursive subdirectory searching is the ability to specify a search not
+only of a specified directory @file{@var{d}}, but recursively of all
+directories below @file{@var{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 at tie{}@ref{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
+ at file{@var{replaceable}} font.
+
+ at itemize @bullet
+
+ at item Dvips:
+via a separate
+ at file{TEXFONTS_SUBDIR} environment variable.
+
+ at item emTeX:
+ at file{t:\subdir!!}; @file{t:\subdir!} for
+a single level of searching.
+
+ at item Kpathsea:
+ at file{texmf/subdir//}
+
+ at item VMS:
+ at file{texmf:[subdir...]}
+
+ at item Xdvi (patchlevel 20):
+ at file{texmf/subdir/**};
+ at file{texmf/subdir/*} for a single level of searching. Version 20.50
+and above support the @file{//} notation.
+
+ at item Y&Y TeX:
+ at file{t:/subdir//} or
+ at file{t:\subdir\\}.
+
+ at end itemize
+
+
+ at node Example implementation-specific trees
+ at section Example implementation-specific trees
+
+The TDS cannot specify a precise location for
+implementation-specific files, such as @file{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., @file{.}). Allowing users to
+include the parent directory (e.g., @file{..}) is also helpful.
+
+
+ at menu
+* AmiWeb2c 2.0::
+* Public DECUS TeX::
+* Web2c 7::
+ at end menu
+
+ at node AmiWeb2c 2.0
+ at subsection AmiWeb2c 2.0
+
+(Email @email{scherer@@physik.rwth-aachen.de} to contact the maintainer
+of this implementation.)
+
+AmiWeb2c 2 is compatible with Web2c 7 to the greatest possible
+extent, so only the very few differences are described in this
+section. Detailed information about the basic concepts is given in
+the section for Web2c 7 below.
+
+Thanks to the @file{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 @file{//} notation recursive path search may
+also be started by @file{@var{DEVICE}:/}, e.g., @file{TeXMF:/}
+will scan this specific device completely.
+
+Binaries coming with the AmiWeb2c distribution are installed in the
+directory @file{bin/amiweb2c/} outside the common TDS tree
+ at file{share/texmf/}. In addition to the set of AmiWeb2c binaries
+you will find two subdirectories @file{local/} and @file{pastex/}
+with auxiliary programs.
+
+A stripped version of the PasTeX system (used by kind permission of
+Georg He at ss{}mann) is coming with AmiWeb2c, pre-installed in its own
+ at file{share/texmf/amiweb2c/pastex/} directory. If you want to use
+PasTeX you have to @file{assign} the name @file{TeX:} to this place.
+
+Documentation files in AmigaGuide format should be stored at
+ at file{doc/guide/} similar to @file{doc/info/}.
+
+
+ at node Public DECUS TeX
+ at subsection 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., @file{vms_decus}).
+
+ at 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
+ at end example
+
+
+ at node Web2c 7
+ at subsection Web2c 7
+
+All implementation-dependent TeX system files (@file{.pool},
+ at file{.fmt}, @file{.base}, @file{.mem}) are stored by default directly
+in @file{texmf/web2c}. The configuration file @file{texmf.cnf} and
+various subsidiary @file{MakeTeX...} scripts used as subroutines are
+also stored there.
+
+Non-TeX specific files are stored following the GNU coding
+standards. Given a root directory @file{@var{prefix}}
+(@file{/usr/local} by default), we have default locations as follows:
+
+ at example
+ <prefix>/ installation root (@file{/usr/local} by default)
+ bin/ executables
+ man/ man pages
+ info/ info files
+ lib/ libraries (@file{libkpathsea.*})
+ share/ architecture-independent files
+ texmf/ TDS root
+ web2c/ implementation-dependent files (@file{.pool}, @file{.fmt}, @file{texmf.cnf}, etc.)
+ at end example
+
+See @uref{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 @file{/usr/local/texmf}.
+
+
+ at node Is there a better way?
+ at appendix 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:
+
+ at itemize @bullet
+
+ at item Path searching control at the TeX level. If documents could
+restrict subdirectory searching to a subdirectory via some portable
+syntax in file names, restrictions on uniqueness of filenames could be
+relaxed considerably (with the cooperation of the formats), and the
+TeX search path would not need to depend on the format.
+
+ at item Multiple logical @file{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.
+
+ at end itemize
+
+ at menu
+* Macro structure::
+* Font structure::
+* Documentation structure::
+ at end menu
+
+ at node Macro structure
+ at section Macro structure
+
+The TWG settled on the
+ at file{@var{format}/@var{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:
+ at file{@var{package}/@var{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 @file{@var{format}/@var{package}}
+structure won for a couple of reasons:
+
+ at itemize @bullet
+ at item 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.
+
+ at item The alternative arrangement increases the number of top-level
+directories, so the files that must be found using subdirectory
+searching are spread out in a wide, shallow tree. This could have a
+profound impact on the efficiency of subdirectory searching.
+
+ at end itemize
+
+
+ at node Font structure
+ at section 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.
+
+
+ at menu
+* Font file type location::
+* Mode and resolution location::
+* Modeless bitmaps::
+ at end menu
+
+ at node Font file type location
+ at subsection Font file type location
+
+We considered the supplier-first arrangement in use at many sites:
+
+ at example
+texmf/fonts/@var{supplier}/@var{typeface}/@var{type}/
+ at end example
+
+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
+ at file{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
+ at file{texmf/fonts/mf}, property list files in @file{texmf/fonts/pl}, the
+various forms of Type at tie{}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
+(@file{mf} and @file{pl} under @file{source}, @file{pfa} and @file{pfb}
+and @file{gsf} under @file{type1}) where we felt this was beneficial.
+
+
+ at node Mode and resolution location
+ at subsection Mode and resolution location
+
+We considered having the @file{mode} at the bottom of the font tree:
+ at example
+texmf/fonts/pk/@var{supplier}/@var{typeface}/@var{mode}/@var{dpi}/
+ at end example
+
+In this case, however, it is difficult to limit subdirectory searching
+to the mode required for a particular device.
+
+We then considered moving the @file{dpi at var{nnn}} up to below
+the mode:
+ at example
+texmf/fonts/pk/@var{mode}/@var{dpi}/@var{supplier}/@var{typeface}/
+ at end example
+
+But then it is not feasible to omit the @file{dpi at var{nnn}}
+level altogether on systems which can and do choose to use long
+filenames.
+
+
+ at node Modeless bitmaps
+ at subsection Modeless bitmaps
+
+The TDS specifies using a single directory @file{modeless/} as
+the mode name for those utilities which generate bitmaps, e.g.,
+ at file{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, @file{gsftopk}-generated bitmaps from @file{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 @file{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 @file{mfcx} vs.@:
+ at file{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 at tie{}happen.
+
+
+ at node Documentation structure
+ at section 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)@tie{}keep the documentation together and (2)@tie{}make it as straightforward
+as possible for users to find the particular documentation they were
+after.
+
+
+ at node Related references
+ at appendix Related references
+
+This appendix gives pointers to related files and other documents. For
+CTAN references, we use @file{http://www.ctan.org} as the
+top-level domain only to make the links be live in this document. See
+ at uref{http://www.ctan.org/tex-archive/CTAN.sites} for a complete list of
+CTAN sites; there are mirrors worldwide.
+
+ at itemize @bullet
+
+ at item This document, in many formats (tex, dvi, info, pdf):@*
+ at uref{http://tug.org/tds/}
+
+ at item The TDS mailing list archives:@*
+ at uref{http://tug.org/mail-archives/twg-tds/}
+
+ at item The level at tie{}0 DVI driver standard:@*
+ at uref{http://www.ctan.org/tex-archive/dviware/driv-standard/level-0/}
+
+ at item @cite{Filenames for TeX fonts}, with lists of recommended
+supplier and typeface names:@*
+ at uref{http://tug.org/fontname/}
+
+ at item ISO-9660 CD-ROM file system standard:@*
+ at uref{http://www.iso.ch/cate/cat.html}
+
+ at item @cite{Components of TeX}, a paper by Joachim
+Schrod:@*
+ at uref{http://www.ctan.org/tex-archive/documentation/components-of-TeX/}
+
+ at item @cite{Managing Multiple TDS trees}, an article by Michael
+Downes:@*
+ at uref{http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf}
+
+ at item A complete set of Metafont modes:@*
+ at uref{http://www.ctan.org/tex-archive/fonts/modes/modes.mf}
+
+ at item A large collection of BibTeX databases and styles:@*
+ at uref{ftp://ftp.math.utah.edu/pub/tex/bib/}
+
+ at end itemize
+
+
+ at node Contributors
+ at appendix 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 @email{tds@@tug.org} and @email{tex-live@@tug.org} mailing lists as
+the record of contributions.
+
+
+ at iftex
+ at contents
+ at end iftex
+ at bye
Added: tex-common/trunk/doc/tds-1.1/tds.texi.tmp
===================================================================
--- tex-common/trunk/doc/tds-1.1/tds.texi.tmp 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/tds.texi.tmp 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1,1834 @@
+% Id: tds.tex,v 1.43 2004/06/23 17:24:42 karl Exp
+\input texinfo
+ at setfilename tds.info
+ at settitle A Directory Structure for TeX Files
+
+ at set version 1.1
+
+ at dircategory TeX
+ at direntry
+* TeX Directories: (tds). A directory structure for TeX files.
+ at end direntry
+
+
+ at titlepage
+ at title A Directory Structure for TeX Files
+ at subtitle Version @value{version}
+ at author TUG Working Group on a TeX Directory Structure (TWG-TDS)
+
+ at page
+ at vskip 0pt plus 1filll
+
+Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2003, 2004
+TeX Users Group.
+
+Permission to use, copy, and distribute this document @emph{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 at tie{}@ref{Related references}).
+Please send questions or suggestions by email to
+ at email{tds@@tug.org}. We welcome all comments. This is version
+ at value{version}.
+
+ at end titlepage
+
+ at ifnottex
+ at node Top
+ at top A Directory Structure for TeX Files
+
+Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2003, 2004
+TeX Users Group.
+
+Permission to use, copy, and distribute this document @emph{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 at tie{}@ref{Related references}).
+Please send questions or suggestions by email to
+ at email{tds@@tug.org}. We welcome all comments. This is version
+ at value{version}.
+
+ at menu
+* Introduction::
+* General::
+* Top-level directories::
+* Summary::
+* Unspecified pieces::
+* Implementation issues::
+* Is there a better way?::
+* Related references::
+* Contributors::
+
+ at detailmenu
+ --- 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::
+
+ at end detailmenu
+ at end menu
+
+ at end ifnottex
+
+
+
+ at node Introduction
+ at chapter 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 at . 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 at tie{}@ref{Related references}.
+
+
+ at menu
+* History::
+* The role of the TDS::
+* Conventions::
+ at end menu
+
+ at node History
+ at section 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:
+
+ at itemize @bullet
+ at item Inputs for TeX extensions included under @file{tex}, instead
+ of in their own top-level directories (Section at tie{}@ref{Extensions})
+ at item New top-level directory @file{scripts} (Section at tie{}@ref{Scripts}).
+ at item New subdirectories @file{lig}, @file{opentype},
+ @file{truetype}, and @file{type3} under @file{fonts}
+ (Section at tie{}@ref{Fonts}).
+ at item @samp{enc},
+ at file{lig}, and @file{map} all use
+ @file{@var{syntax}/@var{package}} subdirectories
+ (Section at tie{}@ref{Fonts}).
+ at item @samp{pfm} files specified to go under @file{type1},
+and
+ @file{inf} files under @file{afm} (Section at tie{}@ref{Fonts}).
+ at end itemize
+
+
+ at node The role of the TDS
+ at section 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.
+
+
+ at node Conventions
+ at section Conventions
+
+In this document, @file{/} is used to separate filename components;
+for example, @file{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
+ at emph{not} a LaTeX2e package, which is a style file supplementing
+a document class.
+
+We use the following typographic conventions:
+
+ at itemize @bullet
+
+ at item @samp{literal}
+Literal text such as @file{filename} is
+typeset in typewriter type.
+
+ at item @samp{@var{replaceable}}
+Replaceable text such as
+ at file{@var{package}}, identifying a class of things, is typeset in
+italics inside angle brackets.
+
+ at end itemize
+
+
+ at node General
+ at chapter General
+
+This section describes common properties throughout the TDS tree.
+
+ at menu
+* Subdirectory searching::
+* Rooting the tree::
+* Local additions::
+* Duplicate filenames::
+ at end menu
+
+ at node Subdirectory searching
+ at section Subdirectory searching
+
+Older TeX installations store large numbers of related files in single
+directories, for example, all @file{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 at tie{}@ref{More on subdirectory searching}).
+
+
+ at node Rooting the tree
+ at section Rooting the tree
+
+In this document, we shall designate the root TDS directory by
+ at file{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 @file{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, @file{/usr/local/share}, @file{/usr/local},
+ at file{/usr/local/lib}, and @file{/opt} are common choices.
+
+The name @file{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.
+
+
+ at node Local additions
+ at section 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
+ at file{texmf} tree. Both have their place; in fact, some sites employ
+both simultaneously:
+
+ at enumerate
+
+ at item A completely separate tree which is a TDS structure
+itself; for example, @file{/usr/local/umbtex} at the University of
+Massachusetts at Boston. This is another example of the multiple
+ at file{texmf} hierarchies mentioned in the previous section.
+
+ at item A directory named @file{local} at any appropriate level, for
+example, in the @file{@var{format}}, @file{@var{package}}, and
+ at file{@var{supplier}} directories discussed in the following sections.
+The TDS reserves the directory name @file{local} for this
+purpose.
+
+We recommend using @file{local} for site-adapted configuration files,
+such as @file{language.dat} for the Babel package or @file{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.
+
+ at end enumerate
+
+One common case of local additions is dynamically generated files, e.g.,
+PK fonts by the @file{mktexpk} script (which originated in
+Dvips as @file{MakeTeXPK}). A site may store the
+generated files directly in any of:
+ at itemize @bullet
+ at item their standard location in the main TDS tree (if it can be
+made globally writable);
+
+ at item an alternative location in the main TDS tree (for
+example, under @file{texmf/fonts/tmp});
+
+ at item a second complete TDS tree (as outlined above);
+
+ at item any other convenient directory (perhaps under
+ at file{/var}, for example @file{/var/spool/fonts}).
+
+ at end itemize
+
+No one solution will be appropriate for all sites.
+
+
+ at node Duplicate filenames
+ at section 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:
+
+ at itemize @bullet
+
+ at item Names of TeX input files must be unique within each first-level
+subdirectory of @file{texmf/tex} and @file{texmf/tex/generic}, but not
+within all of @file{texmf/tex}; i.e., different TeX formats may have
+files by the same name. (Section at tie{}@ref{Macros} discusses this
+further.) Thus, no single format-independent path specification, such
+as a recursive search beginning at @file{texmf/tex} specifying no other
+directories, suffices. So implementations must provide format-dependent
+path specifications, for example via wrapper scripts or configuration
+files.
+
+ at item Many font files will have the same name (e.g., @file{cmr10.pk}),
+as discussed in Section at tie{}@ref{Valid font bitmaps}. Implementations
+must distinguish these files by mode and resolution.
+
+ at end itemize
+
+All implementations we know of already have these capabilities.
+
+One place where duplicate names are likely to occur is not an exception:
+
+ at itemize @bullet
+
+ at item Names of Metafont input files (as opposed to bitmaps) must be unique
+within all of @file{texmf/fonts}. In practice, this is a problem with
+some variants of Computer Modern which contain slightly modified files
+named @file{punct.mf}, @file{romanl.mf}, and so on. We believe the only
+feasible solution is to rename the derivative files to be
+unique.
+
+ at end itemize
+
+
+ at node Top-level directories
+ at chapter Top-level directories
+
+The directories under the @file{texmf} root identify the major components of
+a TeX system (see Section at tie{}@ref{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 @file{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:
+
+ at itemize @bullet
+ at item @samp{tex}
+for TeX files (Section at tie{}@ref{Macros}).
+
+ at item @samp{fonts}
+for font-related files (Section at tie{}@ref{Fonts}).
+
+ at item @samp{metafont}
+for Metafont files which are not fonts (Section at tie{}@ref{Non-font Metafont files}).
+
+ at item @samp{metapost}
+for MetaPost files (Section at tie{}@ref{MetaPost}).
+
+ at item @samp{bibtex}
+for BibTeX files (Section at tie{}@ref{BibTeX}).
+
+ at item @samp{scripts}
+for platform-independent executables (Section at tie{}@ref{Scripts}).
+
+ at item @samp{doc}
+for user documentation (Section at tie{}@ref{Documentation}).
+
+ at item @samp{source}
+for sources. This includes both traditional
+program sources (for example, Web2C sources go in
+ at file{texmf/source/web2c}) and, e.g., LaTeX @file{dtx} sources (which
+go in @file{texmf/source/latex}). The TDS leaves unspecified any
+structure under @file{source}.
+
+ at file{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, @file{plain.tex} does not belong under @file{texmf/source},
+even though it is a ``source file'' in the sense of not being derived
+from another file. (It goes in @file{texmf/tex/plain/base}, as explained
+in Section at tie{}@ref{Macros}).
+
+ at item @samp{@var{implementation}}
+for implementations (examples:
+ at file{emtex}, @file{vtex}, @file{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 (@file{tex.pool}) and memory dump files (@file{plain.fmt}) go
+here, in addition to implementation-wide configuration files. See
+Section at tie{}@ref{Example implementation-specific trees} for examples of
+real @file{@var{implementation}} trees.
+
+Such implementation-specific configuration files should @emph{not}
+be located using the main TeX input search path (e.g.,
+ at file{TEXINPUTS}). This must be reserved for files actually read by a
+TeX engine. See Section at tie{}@ref{Extensions}.
+
+ at item @samp{@var{program}}
+for program-specific input and
+configuration files for any TeX-related programs (examples:
+ at file{mft}, @file{dvips}). In fact, the @file{tex}, @file{metafont},
+ at file{metapost}, and @file{bibtex} items above may all be seen as
+instances of this case.
+
+ at end itemize
+
+
+ at menu
+* Macros::
+* Fonts::
+* Non-font Metafont files::
+* MetaPost::
+* BibTeX::
+* Scripts::
+* Documentation::
+ at end menu
+
+ at node Macros
+ at section 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 @file{\dump}-able package):
+ at example
+texmf/tex/@var{format}/@var{package}/
+ at end example
+
+ at itemize @bullet
+
+ at item @samp{@var{format}}
+is a format name (examples: @file{amstex},
+ at file{latex}, @file{plain}, @file{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
+ at file{@var{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 @file{@var{format}} names:
+
+ at itemize @bullet
+
+ at item @samp{generic},
+for input files that are useful across a wide
+range of formats (examples: @file{null.tex}, @file{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
+ at file{texmf/tex/plain}), e.g., @file{testfont.tex} and @file{plain.tex}
+itself.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local
+additions}.
+
+ at end itemize
+
+Thus, for almost every format, it is necessary to search at least the
+ at file{@var{format}} directory and then the @file{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
+ at file{amstex}, @file{plain}, and @file{generic} directories should be
+searched, because AMS-TeX is compatible with Plain.
+
+ at item @samp{@var{package}}
+is a TeX package name (examples:
+ at file{babel}, @file{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
+ at file{@var{format}} directory, instead of
+ at file{@var{format}/base}. For example, Texinfo may go in
+ at file{texmf/tex/texinfo/texinfo.tex}, not
+ at file{texmf/tex/texinfo/base/texinfo.tex}.
+
+The TDS reserves the following @file{@var{package}} names:
+
+ at itemize @bullet
+
+ at item @samp{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 @file{ltx} files
+created during the build process. Another example: the @file{.ini}
+driver files for formats used by TeX Live and other distributions.
+
+ at item @samp{hyphen},
+for hyphenation patterns, including the original
+American English @file{hyphen.tex}. These are typically used only by
+INITEX. In most situations, this directory need exist only under the
+ at file{generic} format.
+
+ at item @samp{images},
+for image input files, such as Encapsulated
+PostScript figures. Although it is somewhat non-intuitive for these to
+be under a directory named @file{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 at . In most situations, this directory need exist only under
+the @file{generic} format.
+
+ at item @samp{local},
+for local additions and configuration files. See
+Section at tie{}@ref{Local additions}.
+
+ at item @samp{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 @file{misc}.
+
+ at end itemize
+
+ at end itemize
+
+
+ at menu
+* Extensions::
+ at end menu
+
+ at node Extensions
+ at subsection 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 @file{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:
+
+ at example
+texmf/tex/aleph
+texmf/tex/enctex
+ at end example
+
+This is a change from TDS at tie{}1.0, which specified top-level
+ at file{@var{extension}} directories for each such program. We felt the
+new approach is preferable, because:
+
+ at itemize @bullet
+
+ at item Authors of relevant packages typically make their code detect the
+engine being used, and issue error messages or adapt to circumstances
+appropriately. Furthermore, as a package matures, it may support
+multiple engines. Thus, a package could conceivably be placed in any of
+several top-level directories, at different times. Putting all packages
+under the top-level @file{tex} directory provides a stable location over
+time.
+
+ at item Users need to be able to switch between engines, and configuring
+different search paths for each engine is difficult and error-prone.
+
+ at end itemize
+
+Thus, in practice, having different top-level directories caused
+difficulties for everyone involved---users, package authors, site
+administrators, and system distributors.
+
+Please contrast this approach with the @file{@var{implementation}}
+top-level subdirectory (Section at tie{}@ref{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.
+
+
+ at node Fonts
+ at section 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.
+
+ at example
+texmf/fonts/@var{type}/@var{supplier}/@var{typeface}/
+texmf/fonts/enc,lig,map/@var{subpath}/
+ at end example
+
+ at itemize @bullet
+
+ at item @samp{@var{type}}
+is the type of font file. The TDS
+reserves the following @file{@var{type}} names for common TeX file
+types:
+
+ at itemize @bullet
+ at item @samp{afm},
+for Adobe font metrics, and @file{inf} files.
+ at item @samp{gf},
+for generic font bitmap files.
+ at item @samp{opentype},
+for OpenType fonts.
+ at item @samp{pk},
+for packed bitmap files.
+ at item @samp{source},
+for font sources (Metafont files, property lists, etc.).
+ at item @samp{tfm},
+for TeX font metric files.
+ at item @samp{truetype},
+for TrueType fonts.
+ at item @samp{type1},
+for PostScript Type 1 fonts (in @file{pfa},
+ @file{pfb}, or any other format), and @file{pfm} files.
+ at item @samp{type3},
+for PostScript Type 3 fonts.
+ at item @samp{vf},
+for virtual fonts.
+ at end itemize
+
+The TDS also reserves the names @file{enc}, @file{lig}, and
+ at file{map} for font encoding, ligature, and mapping files, respectively.
+All of these directories are structured the same way, with
+ at file{@var{syntax}} subdirectories, and then @file{@var{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:
+ at example
+fonts/map/dvipdfm/updmap/dvipdfm.map
+fonts/map/dvips/lm/lm.map
+fonts/enc/dvips/base/8r.enc
+ at end example
+
+The Fontname and Dvips packages have more examples of the @file{enc} and
+ at file{map} types. The @file{afm2pl} program uses @file{lig} files.
+
+ at file{pfm} files are included in the @file{type1} directory, instead of
+being given their own directory, for two reasons: 1)@tie{}a @file{.pfm} file
+is always an adjunct to a given @file{.pfb} file; 2)@tie{}they must be
+installed from the same directory for Windows programs other than TeX
+to use them.
+
+ at file{inf} files are included in the @file{afm} directory, since
+an @file{inf} and @file{afm} file can be used to generate a @file{pfm}.
+(Unfortunately, Adobe Type Manager and perhaps other software requires
+that the @file{pfb} be in the same directory as @file{afm} and
+ at file{inf} for installation.)
+
+As usual, a site may omit any of these directories that are unnecessary.
+ at file{gf} is a particularly likely candidate for omission.
+
+ at item @samp{@var{supplier}}
+is a name identifying font source
+(examples: @file{adobe}, @file{ams}, @file{public}). The TDS
+reserves the following @file{@var{supplier}} names:
+
+ at itemize @bullet
+
+ at item @samp{ams},
+for the American Mathematical Society's AMS-fonts
+collection.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local additions}.
+
+ at item @samp{public},
+for freely redistributable fonts where the supplier
+neither (1)@tie{}requested their own directory (e.g., @file{ams}), nor
+(2)@tie{}also made proprietary fonts (e.g., @file{adobe}). It does not
+contain all extant freely distributable fonts, nor are all files therein
+necessarily strictly public domain.
+
+ at item @samp{tmp},
+for dynamically-generated fonts, as is traditional on
+some systems. It may be omitted if unnecessary, as usual.
+
+ at end itemize
+
+
+ at item @samp{@var{typeface}}
+is the name of a typeface family
+(examples: @file{cm}, @file{euler}, @file{times}). The TDS
+reserves the following @file{@var{typeface}} names:
+
+ at itemize @bullet
+
+ at item @samp{cm} (within @file{public}),
+for the 75 fonts defined in
+ at cite{Computers and Typesetting, Volume at tie{}E}.
+
+ at item @samp{latex} (within @file{public}),
+for those fonts distributed
+with LaTeX in the base distribution.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local additions}.
+
+ at end itemize
+
+ at end itemize
+
+Some concrete examples:
+ at example
+texmf/fonts/source/public/pandora/pnr10.mf
+texmf/fonts/tfm/public/cm/cmr10.tfm
+texmf/fonts/type1/adobe/utopia/putr.pfa
+ at end example
+
+For complete supplier and typeface name lists, consult
+ at cite{Filenames for TeX fonts} (see Appendix at tie{}@ref{Related
+references}).
+
+ at menu
+* Font bitmaps::
+* Valid font bitmaps::
+ at end menu
+
+ at node Font bitmaps
+ at subsection Font bitmaps
+
+Font bitmap files require two characteristics in addition to the above
+to be uniquely identifiable: (1)@tie{}the type of device (i.e., mode) for
+which the font was created; (2)@tie{}the resolution of the bitmap.
+
+Following common practice, the TDS segregates fonts with
+different device types into separate directories. See @file{modes.mf}
+in Appendix at tie{}@ref{Related references} for recommended mode names.
+
+Some printers operate at more than one resolution (e.g., at 300 at dmn{dpi} and
+600 at dmn{dpi}), but each such resolution will necessarily have a different
+mode name. Nothing further is needed, since implicit in the TeX
+system is the assumption of a single target resolution.
+
+Two naming strategies are commonly used to identify the resolution of
+bitmap font files. On systems that allow long filenames (and in the
+original Metafont program itself), the resolution is included in the
+filename (e.g., @file{cmr10.300pk}). On systems which do not support
+long filenames, fonts are generally segregated into directories by
+resolution (e.g., @file{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 @file{pk} and @file{gf}:
+
+ at example
+texmf/fonts/pk/@var{mode}/@var{supplier}/@var{typeface}/dpi at var{nnn}/
+texmf/fonts/gf/@var{mode}/@var{supplier}/@var{typeface}/dpi at var{nnn}/
+ at end example
+
+ at itemize @bullet
+
+ at item @samp{@var{mode}}
+is a name which identifies the device type
+(examples: @file{cx}, @file{ljfour}, @file{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 @file{@var{mode}} name shall be simply
+ at file{modeless}. The @file{@var{mode}} level shall not be omitted,
+even if only a single mode happens to be in use.
+
+ at item @samp{dpi at var{nnn}}
+specifies the resolution of the font
+(examples: @file{dpi300}, @file{dpi329}). @file{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 @file{@var{nnn}} is to be calculated as if using Metafont
+arithmetic and then rounded; i.e., it is the integer Metafont uses in its
+output @file{gf} filename. We recognize small differences in the
+resolution are a common cause of frustration among users, however, and
+recommend implementors follow the level at tie{}0 DVI driver standard
+(see Appendix at tie{}@ref{Related references}) in bitmap font searches by
+allowing a fuzz of +-0.2% (with a minimum of 1) in the
+ at file{@var{dpi}}.
+
+ at end itemize
+
+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 @file{.fli} files), provided that the basic scheme is also
+supported.
+
+ at node Valid font bitmaps
+ at subsection 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,
+ at file{cmr10.pk} will be the filename for Computer Modern Roman 10 at dmn{pt} at
+5--10 magnifications for 2--3 modes. (Section at tie{}@ref{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) @file{modes.mf} (see Appendix at tie{}@ref{Related
+references}), the required information is already in your PK
+files. If not, a simple addition based on the code found in
+ at file{modes.mf} can be made to your local modes file and the PK
+files rebuilt.
+
+
+ at node Non-font Metafont files
+ at section 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:
+
+ at example
+texmf/metafont/@var{package}/
+ at end example
+
+ at file{@var{package}} is the name of a
+Metafont package (for example, @file{mfpic}).
+
+The TDS reserves the following @file{@var{package}} names:
+
+ at itemize @bullet
+
+ at item @samp{base},
+for the standard Metafont macro files as described in
+ at cite{The Metafontbook}, such as @file{plain.mf} and @file{expr.mf}.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local additions}.
+
+ at item @samp{misc},
+for Metafont packages consisting of only a single file
+(for example, @file{modes.mf}). An administrator or package maintainer
+may create directories for single-file packages at their discretion,
+instead of using @file{misc}.
+
+ at end itemize
+
+
+ at node MetaPost
+ at section 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:
+
+ at example
+texmf/metapost/@var{package}/
+ at end example
+
+ at file{@var{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 @file{@var{package}} names:
+
+ at itemize @bullet
+
+ at item @samp{base},
+for the standard MetaPost macro files, such as
+ at file{plain.mp}, @file{mfplain.mp}, @file{boxes.mp}, and
+ at file{graph.mp}. This includes files used by INIMP when dumping mem
+files containing preloaded macro definitions.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local
+additions}.
+
+ at item @samp{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 @file{misc}.
+
+ at item @samp{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.
+
+ at end itemize
+
+
+ at node BibTeX
+ at section BibTeX
+
+BibTeX-related files shall be stored in:
+
+ at example
+texmf/bibtex/bib/@var{package}/
+texmf/bibtex/bst/@var{package}/
+ at end example
+
+The @file{bib} directory is for BibTeX database (@file{.bib}) files,
+the @file{bst} directory for style (@file{.bst}) files.
+
+ at file{@var{package}} is the name of a BibTeX package. The
+TDS reserves the following @file{@var{package}} names (the same
+names are reserved under both @file{bib} and @file{bst}):
+
+ at itemize @bullet
+
+ at item @samp{base},
+for the standard BibTeX databases and styles, such
+as @file{xampl.bib}, @file{plain.bst}.
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local
+additions}.
+
+ at item @samp{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 @file{misc}.
+
+ at end itemize
+
+
+ at node Scripts
+ at section Scripts
+
+The top-level @file{scripts} directory is for platform-independent
+executables, such as Perl, Python, and shell scripts, and Java class
+files. Subdirectories under @file{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,
+ at file{scripts} also serves as a platform-independent analog of the
+standard Unix @file{libexec} directory.
+
+We recommend using extensions specifying the language (such as
+ at file{.pl}, @file{.py}, @file{.sh}) on these files, to help uniquely
+identify the name. Since the intent of the TDS is for programs
+in @file{scripts} not to be invoked directly by users, this poses no
+inconvenience.
+
+For example, in the TeX Live distribution, the ConTeXt user-level
+program @file{texexec} can exist as a small wrapper script in each
+ at file{bin/@var{platform}/texexec} (which is outside the
+ at file{texmf} tree), which merely finds and calls
+ at file{texmf/scripts/context/perl/texexec.pl}.
+
+Examples:
+ at example
+scripts/context/perl/texexec.pl
+scripts/context/ruby/examplex.rb
+scripts/thumbpdf/thumbpdf.pl
+ at end example
+
+The TDS does not specify a location for platform-dependent
+binary executables, whether auxiliary or user-level.
+
+
+ at node Documentation
+ at section 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
+ at file{fonts} and @file{tex} directories, as follows:
+
+ at example
+texmf/doc/@var{category}/...
+ at end example
+
+ at file{@var{category}} identifies the general topic of documentation
+that resides below it; for example, a TeX format name (@file{latex}),
+program name (@file{bibtex}, @file{tex}), language (@file{french},
+ at file{german}), a file format (@file{info}, @file{man}), or other system
+components (@file{web}, @file{fonts}).
+
+One possible arrangement is to organize @file{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 @file{@var{category}} tree for a TeX format, the
+directory @file{base} is reserved for base documentation distributed by
+the format's maintainers.
+
+The TDS reserves the following category names:
+
+ at itemize @bullet
+
+ at item @samp{general},
+for standalone documents not specific to any
+particular program (for example, Joachim Schrod's @cite{Components
+of TeX}).
+
+ at item @samp{help},
+for meta-information, such as FAQ's,
+the TeX Catalogue, etc.
+
+ at item @samp{info},
+for processed Texinfo documents. (Info files, like
+anything else, may also be stored outside the TDS, at the
+installer's option.)
+
+ at item @samp{local},
+for local additions. See Section at tie{}@ref{Local
+additions}.
+
+ at end itemize
+
+The @file{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 @file{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 at tie{}@ref{Documentation tree summary} for a summary.
+
+
+ at node Summary
+ at chapter Summary
+
+A skeleton of a TDS @file{texmf} directory tree. This is not to
+imply these are the only entries allowed. For example, @file{local} may
+occur at any level.
+
+ at example
+ bibtex/ BibTeX input files
+ . bib/ BibTeX databases
+ . . base/ base distribution (e.g., @file{xampl.bib})
+ . . misc/ single-file databases
+ . <package>/ name of a package
+ . bst/ BibTeX style files
+ . . base/ base distribution (e.g., @file{plain.bst}, @file{acm.bst})
+ . . misc/ single-file styles
+ . <package>/ name of a package
+ doc/ see Section at tie{}@ref{Documentation} and the summary below
+ fonts/ font-related files
+ . <type>/ file type (e.g., @file{pk})
+ . . <mode>/ type of output device (for @file{pk} and @file{gf} only)
+ . . . <supplier>/ name of a font supplier (e.g., @file{public})
+ . . . . <typeface>/ name of a typeface (e.g., @file{cm})
+ . . . . . dpi<nnn>/ font resolution (for @file{pk} and @file{gf} only)
+ <implementation>/ TeX implementations, by name (e.g., @file{emtex})
+ local/ files created or modified at the local site
+ metafont/ Metafont (non-font) input files
+ . base/ base distribution (e.g., @file{plain.mf})
+ . misc/ single-file packages (e.g., @file{modes.mf})
+ . <package>/ name of a package (e.g., @file{mfpic})
+ metapost/ MetaPost input and support files
+ . base/ base distribution (e.g., @file{plain.mp})
+ . misc/ single-file packages
+ . <package>/ name of a package
+ . support/ support files for MetaPost-related utilities
+ mft/ @file{MFT} inputs (e.g., @file{plain.mft})
+ <program>/ TeX-related programs, by name (e.g., @file{dvips})
+ source/ program source code by name (e.g., @file{latex}, @file{web2c})
+ tex/ TeX input files
+ . <engine>/ name of an engine (e.g., @file{aleph}); can also be lower
+ . <format>/ name of a format (e.g., @file{plain})
+ . . base/ base distribution for format (e.g., @file{plain.tex})
+ . . misc/ single-file packages (e.g., @file{webmac.tex})
+ . . local/ local additions to or local configuration files for @file{@var{format}}
+ . . <package>/ name of a package (e.g., @file{graphics}, @file{mfnfss})
+ . generic/ format-independent packages
+ . . hyphen/ hyphenation patterns (e.g., @file{hyphen.tex})
+ . . images/ image input files (e.g., Encapsulated PostScript)
+ . . misc/ single-file format-independent packages (e.g., @file{null.tex}).
+ . . <package>/ name of a package (e.g., @file{babel})
+ at end example
+
+
+ at menu
+* Documentation tree summary::
+ at end menu
+
+ at node Documentation tree summary
+ at section Documentation tree summary
+
+An example skeleton of a TDS directory tree under
+ at file{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 @file{texmf/doc} tree may be organized by language, so
+that all documentation in French, say, is in a @file{french}
+subdirectory. In that case, the example structure here would be in a
+given language directory.
+
+ at example
+ ams/
+ . amsfonts/ @file{amsfonts.faq}, @file{amfndoc}
+ . amslatex/ @file{amslatex.faq}, @file{amsldoc}
+ . amstex/ @file{amsguide}, @file{joyerr}
+ bibtex/ BibTeX
+ . base/ @file{btxdoc.tex}
+ fonts/
+ . fontname/ @cite{Filenames for TeX fonts}
+ . oldgerm/ @file{corkpapr}
+ <format>/ name of a TeX format (e.g., @file{generic}, @file{latex})
+ . base/ for the base distribution
+ . misc/ for contributed single-file package documentation
+ . <package>/ for @emph{package}
+ general/ across programs, generalities
+ . errata/ @file{errata}, @file{errata[1-8]}
+ . texcomp/ @cite{Components of TeX}
+ help/ meta-information
+ . ctan/ info about CTAN mirror sites
+ . faq/ FAQs of @file{comp.text.tex}, etc.
+ info/ GNU Info files, made from Texinfo sources
+ latex/ example of @file{@var{format}}
+ . base/ @file{ltnews*}, @file{*guide}, etc.
+ . graphics/ @file{grfguide}
+ local/ site-specific documentation
+ man/ Unix man pages
+ <program>/ TeX-related programs, by name (examples follow)
+ metafont/ @file{mfbook.tex}, @file{metafont-for-beginners}, etc.
+ metapost/ @file{mpman}, @file{manfig}, etc.
+ tex/ @file{texbook.tex}, @cite{A Gentle Introduction to TeX}, etc.
+ web/ @file{webman}, @file{cwebman}
+ at end example
+
+
+
+ at node Unspecified pieces
+ at appendix Unspecified pieces
+
+The TDS cannot address the following aspects of a functioning
+TeX system:
+
+ at enumerate
+
+ at item The location of executable programs: this is too site-dependent
+even to recommend a location, let alone require one. A site may place
+executables outside the @file{texmf} tree altogether (e.g.,
+ at file{/usr/local/bin}), in a platform-dependent directory within
+ at file{texmf}, or elsewhere.
+
+ at item Upgrading packages when new releases are made: we could find no
+way of introducing version specifiers into @file{texmf} that would do more
+good than harm, or that would be practical for even a plurality of
+installations.
+
+ at item The location of implementation-specific files (e.g., TeX
+ at file{.fmt} files): by their nature, these must be left to the
+implementor or TeX maintainer. See Section at tie{}@ref{Example
+implementation-specific trees}.
+
+ at item Precisely when a package or file should be considered ``local'',
+and where such local files are installed. See Section at tie{}@ref{Local
+additions} for more discussion.
+
+ at end enumerate
+
+
+ at menu
+* Portable filenames::
+ at end menu
+
+ at node Portable filenames
+ at section 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:
+
+ at itemize @bullet
+
+ at item File and directory names, not including any directory path or
+extension part, may not exceed eight characters.
+
+ at item Filenames may have a single extension. Extensions may not exceed
+three characters. Directory names may not have an extension.
+
+ at item Names and extensions may consist of @emph{only} the characters
+ at file{A}-- at file{Z}, @file{0}-- at file{9}, and underscore.
+Lowercase letters are excluded.
+
+ at item A period separates the filename from the extension and is always
+present, even if the name or extension is missing (e.g.,
+ at file{FILENAME.} or @file{.EXT}).
+
+ at item A version number, ranging from 1--32767, is appended to the file
+extension, separated by a semicolon (e.g., @file{FILENAME.EXT;1}).
+
+ at item Only eight directory levels are allowed, including the top-level
+(mounted) directory (see Section at tie{}@ref{Rooting the tree}). Thus, the
+deepest valid ISO-9660 path is:
+ at example
+texmf/L2/L3/L4/L5/L6/L7/L8/FOO.BAR;1
+1 2 3 4 5 6 7 8
+ at end example
+The deepest TDS path needs only seven levels:
+ at example
+texmf/fonts/pk/cx/public/cm/dpi300/cmr10.pk
+1 2 3 4 5 6 7
+ at end example
+
+ at end itemize
+
+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.
+
+ at node Implementation issues
+ at appendix 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.
+
+
+ at menu
+* Adoption of the TDS::
+* More on subdirectory searching::
+* Example implementation-specific trees::
+ at end menu
+
+ at node Adoption of the TDS
+ at section 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:
+
+ at itemize @bullet
+ at item Clear and demonstrable benefits can be shown for the TDS.
+ at item TDS-compliant versions of all key programs are available
+in ported, well-tested forms.
+ at item A ``settling'' period has taken place, to flush out problems. The
+public release of the first draft of this document was the first step in
+this process.
+ at end itemize
+
+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 at tie{}@ref{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.
+
+
+ at node More on subdirectory searching
+ at section More on subdirectory searching
+
+Recursive subdirectory searching is the ability to specify a search not
+only of a specified directory @file{@var{d}}, but recursively of all
+directories below @file{@var{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 at tie{}@ref{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
+ at file{@var{replaceable}} font.
+
+ at itemize @bullet
+
+ at item Dvips:
+via a separate
+ at file{TEXFONTS_SUBDIR} environment variable.
+
+ at item emTeX:
+ at file{t:\subdir!!}; @file{t:\subdir!} for
+a single level of searching.
+
+ at item Kpathsea:
+ at file{texmf/subdir//}
+
+ at item VMS:
+ at file{texmf:[subdir...]}
+
+ at item Xdvi (patchlevel 20):
+ at file{texmf/subdir/**};
+ at file{texmf/subdir/*} for a single level of searching. Version 20.50
+and above support the @file{//} notation.
+
+ at item Y&Y TeX:
+ at file{t:/subdir//} or
+ at file{t:\subdir\\}.
+
+ at end itemize
+
+
+ at node Example implementation-specific trees
+ at section Example implementation-specific trees
+
+The TDS cannot specify a precise location for
+implementation-specific files, such as @file{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., @file{.}). Allowing users to
+include the parent directory (e.g., @file{..}) is also helpful.
+
+
+ at menu
+* AmiWeb2c 2.0::
+* Public DECUS TeX::
+* Web2c 7::
+ at end menu
+
+ at node AmiWeb2c 2.0
+ at subsection AmiWeb2c 2.0
+
+(Email @email{scherer@@physik.rwth-aachen.de} to contact the maintainer
+of this implementation.)
+
+AmiWeb2c 2 is compatible with Web2c 7 to the greatest possible
+extent, so only the very few differences are described in this
+section. Detailed information about the basic concepts is given in
+the section for Web2c 7 below.
+
+Thanks to the @file{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 @file{//} notation recursive path search may
+also be started by @file{@var{DEVICE}:/}, e.g., @file{TeXMF:/}
+will scan this specific device completely.
+
+Binaries coming with the AmiWeb2c distribution are installed in the
+directory @file{bin/amiweb2c/} outside the common TDS tree
+ at file{share/texmf/}. In addition to the set of AmiWeb2c binaries
+you will find two subdirectories @file{local/} and @file{pastex/}
+with auxiliary programs.
+
+A stripped version of the PasTeX system (used by kind permission of
+Georg He at ss{}mann) is coming with AmiWeb2c, pre-installed in its own
+ at file{share/texmf/amiweb2c/pastex/} directory. If you want to use
+PasTeX you have to @file{assign} the name @file{TeX:} to this place.
+
+Documentation files in AmigaGuide format should be stored at
+ at file{doc/guide/} similar to @file{doc/info/}.
+
+
+ at node Public DECUS TeX
+ at subsection 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., @file{vms_decus}).
+
+ at 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
+ at end example
+
+
+ at node Web2c 7
+ at subsection Web2c 7
+
+All implementation-dependent TeX system files (@file{.pool},
+ at file{.fmt}, @file{.base}, @file{.mem}) are stored by default directly
+in @file{texmf/web2c}. The configuration file @file{texmf.cnf} and
+various subsidiary @file{MakeTeX...} scripts used as subroutines are
+also stored there.
+
+Non-TeX specific files are stored following the GNU coding
+standards. Given a root directory @file{@var{prefix}}
+(@file{/usr/local} by default), we have default locations as follows:
+
+ at example
+ <prefix>/ installation root (@file{/usr/local} by default)
+ . bin/ executables
+ . man/ man pages
+ . info/ info files
+ . lib/ libraries (@file{libkpathsea.*})
+ . share/ architecture-independent files
+ . . texmf/ TDS root
+ . . . web2c/ implementation-dependent files (@file{.pool}, @file{.fmt}, @file{texmf.cnf}, etc.)
+ at end example
+
+See @uref{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 @file{/usr/local/texmf}.
+
+
+ at node Is there a better way?
+ at appendix 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:
+
+ at itemize @bullet
+
+ at item Path searching control at the TeX level. If documents could
+restrict subdirectory searching to a subdirectory via some portable
+syntax in file names, restrictions on uniqueness of filenames could be
+relaxed considerably (with the cooperation of the formats), and the
+TeX search path would not need to depend on the format.
+
+ at item Multiple logical @file{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.
+
+ at end itemize
+
+ at menu
+* Macro structure::
+* Font structure::
+* Documentation structure::
+ at end menu
+
+ at node Macro structure
+ at section Macro structure
+
+The TWG settled on the
+ at file{@var{format}/@var{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:
+ at file{@var{package}/@var{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 @file{@var{format}/@var{package}}
+structure won for a couple of reasons:
+
+ at itemize @bullet
+ at item 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.
+
+ at item The alternative arrangement increases the number of top-level
+directories, so the files that must be found using subdirectory
+searching are spread out in a wide, shallow tree. This could have a
+profound impact on the efficiency of subdirectory searching.
+
+ at end itemize
+
+
+ at node Font structure
+ at section 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.
+
+
+ at menu
+* Font file type location::
+* Mode and resolution location::
+* Modeless bitmaps::
+ at end menu
+
+ at node Font file type location
+ at subsection Font file type location
+
+We considered the supplier-first arrangement in use at many sites:
+
+ at example
+texmf/fonts/@var{supplier}/@var{typeface}/@var{type}/
+ at end example
+
+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
+ at file{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
+ at file{texmf/fonts/mf}, property list files in @file{texmf/fonts/pl}, the
+various forms of Type at tie{}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
+(@file{mf} and @file{pl} under @file{source}, @file{pfa} and @file{pfb}
+and @file{gsf} under @file{type1}) where we felt this was beneficial.
+
+
+ at node Mode and resolution location
+ at subsection Mode and resolution location
+
+We considered having the @file{mode} at the bottom of the font tree:
+ at example
+texmf/fonts/pk/@var{supplier}/@var{typeface}/@var{mode}/@var{dpi}/
+ at end example
+
+In this case, however, it is difficult to limit subdirectory searching
+to the mode required for a particular device.
+
+We then considered moving the @file{dpi at var{nnn}} up to below
+the mode:
+ at example
+texmf/fonts/pk/@var{mode}/@var{dpi}/@var{supplier}/@var{typeface}/
+ at end example
+
+But then it is not feasible to omit the @file{dpi at var{nnn}}
+level altogether on systems which can and do choose to use long
+filenames.
+
+
+ at node Modeless bitmaps
+ at subsection Modeless bitmaps
+
+The TDS specifies using a single directory @file{modeless/} as
+the mode name for those utilities which generate bitmaps, e.g.,
+ at file{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, @file{gsftopk}-generated bitmaps from @file{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 @file{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 @file{mfcx} vs.@:
+ at file{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 at tie{}happen.
+
+
+ at node Documentation structure
+ at section 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)@tie{}keep the documentation together and (2)@tie{}make it as straightforward
+as possible for users to find the particular documentation they were
+after.
+
+
+ at node Related references
+ at appendix Related references
+
+This appendix gives pointers to related files and other documents. For
+CTAN references, we use @file{http://www.ctan.org} as the
+top-level domain only to make the links be live in this document. See
+ at uref{http://www.ctan.org/tex-archive/CTAN.sites} for a complete list of
+CTAN sites; there are mirrors worldwide.
+
+ at itemize @bullet
+
+ at item This document, in many formats (tex, dvi, info, pdf):@*
+ at uref{http://tug.org/tds/}
+
+ at item The TDS mailing list archives:@*
+ at uref{http://tug.org/mail-archives/twg-tds/}
+
+ at item The level at tie{}0 DVI driver standard:@*
+ at uref{http://www.ctan.org/tex-archive/dviware/driv-standard/level-0/}
+
+ at item @cite{Filenames for TeX fonts}, with lists of recommended
+supplier and typeface names:@*
+ at uref{http://tug.org/fontname/}
+
+ at item ISO-9660 CD-ROM file system standard:@*
+ at uref{http://www.iso.ch/cate/cat.html}
+
+ at item @cite{Components of TeX}, a paper by Joachim
+Schrod:@*
+ at uref{http://www.ctan.org/tex-archive/documentation/components-of-TeX/}
+
+ at item @cite{Managing Multiple TDS trees}, an article by Michael
+Downes:@*
+ at uref{http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf}
+
+ at item A complete set of Metafont modes:@*
+ at uref{http://www.ctan.org/tex-archive/fonts/modes/modes.mf}
+
+ at item A large collection of BibTeX databases and styles:@*
+ at uref{ftp://ftp.math.utah.edu/pub/tex/bib/}
+
+ at end itemize
+
+
+ at node Contributors
+ at appendix 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 @email{tds@@tug.org} and @email{tex-live@@tug.org} mailing lists as
+the record of contributions.
+
+
+ at iftex
+ at contents
+ at end iftex
+ at bye
Added: tex-common/trunk/doc/tds-1.1/tds2texi.el
===================================================================
--- tex-common/trunk/doc/tds-1.1/tds2texi.el 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/tds2texi.el 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1,577 @@
+;;; tds2texi.el --- convert TDS draft from LaTeX to Texinfo
+
+;; Copyright (C) 1996, 1999, 2003, 2004 Ulrik Vieth and the TeX Users Group.
+
+;; This programm is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 2, or (at your option)
+;; any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have a copy of the GNU General Public License; see the
+;; file COPYING. If not, write to the Free Software Foundation, Inc.,
+;; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+
+;; Author: Ulrik Vieth <vieth at thphy.uni-duesseldorf.de>
+;; Maintainer: karl at mail.tug.org
+;; Version: $Id: tds2texi.el,v 1.12 2004/06/04 17:25:49 karl Exp $
+;; Keywords: TDS, LaTeX, Texinfo, Info, HTML, tex, maint
+
+;;; Commentary:
+
+;; Description:
+;;
+;; This file provides a limited LaTeX-to-Texinfo conversion function
+;; `tds2texi-convert' which is intended to convert the LaTeX
+;; source of the TDS draft document `tds.tex', using a couple of
+;; special markup tags defined in the document class `tdsguide.cls'.
+;; It is definitely *not* suitable to be used as a general-purpose
+;; LaTeX-to-Texinfo converter and is not intended to be used as such.
+;;
+
+;; Usage (also see the Makefile):
+;;
+;; 0. load or autoload this file, e.g: (load-library "tds2texi")
+;;
+;; 1. go to a directory containing `tds.tex', e.g. in dired mode
+;;
+;; 2. run M-x tds2texi-convert -- this does all the conversion and
+;; leaves you in a buffer `tds.texi' containing the converted file
+;;
+;; 3. edit the buffer if necessary and save it -- you will be asked
+;; for a file name (which should be `tds.texi', of course)
+;;
+;; 4. run M-x makeinfo-buffer or invoke makeinfo and/or texi2html
+;; from the shell -- don't try texi2dvi, it may work all right,
+;; but it's not recommended since it will only cause confusion
+;; with the DVI file created from the original LaTeX source!
+;;
+
+;; Bugs:
+;;
+;; * whitespace (esp. blank lines) before and after environments
+;; will be inconsistent (should be fixed in the LaTeX version!)
+;;
+;; * whitespace (esp. indentation) in tdsSummary environments
+;; will be inconsistent (should be fixed in the LaTeX version!)
+;;
+;; * labels are references are assumed to coincide with names
+;; of @nodes -- this is not always true, e.g. for MF vs. \MF{}
+;;
+;; * the last comma in the list of contributors should be a period
+;;
+;; * the list of contributors should be handled in a better way
+;; (currently: LaTeX tabbing -> @quotation -> HTML <blockquote>)
+;;
+;; * the contents of the top node may get lost in the texi2html
+;; conversion under some circumstances, or else it may end up
+;; in the wrong split file -- this seems to be a texi2html bug
+;;
+
+;; History:
+;;
+;; v 0.0 -- 1996/01/23 UV created
+;; v 0.1 -- 1996/01/24 UV first rough version, posted to twg-tds
+;; v 0.2 -- 1996/01/24 UV added some commentary and doc strings
+;; v 0.3 -- 1996/01/25 UV modularized code, handle header and trailer,
+;; call texinfo routines for @nodes and @menus
+;; v 0.4 -- 1996/01/27 UV slightly touched-up and some doc fixes,
+;; improved handling of legalnotice header
+;; v 0.5 -- 1996/01/28 UV more documentation added, code freeze
+;;
+;; v 1.0 -- 1996/02/20 UV renamed to tds2texi, bumped version number,
+;; also fixed a minor typo in "@item samp"
+;; v 1.1 -- 1996/11/12 KB no node pointers, no double blank line after
+;; sections, allow braces after abbrevs.
+;; v 1.2 -- 1996/11/16 KB ??? (see ChangeLog)
+;; v 1.3 -- 1996/11/18 UV added translation for umlaut accents,
+;; added tds2texi-direntry header lines,
+;; added function tds2texi-fixup-texinfo,
+;; fixed bug when combining multiple "@file"s.
+
+
+;;; Code:
+
+(require 'texinfo) ; needed to update @nodes and @menus
+
+;; file name variables
+
+(defvar tds2texi-source-file "tds.tex"
+ "File name of TDS LaTeX source to be converted.")
+
+(defvar tds2texi-target-file "tds.texi"
+ "File name of TDS Texinfo source to be created.")
+
+(defvar tds2texi-filename "tds.info"
+ "File name of Info file to be inserted in Texinfo header.")
+
+(defvar tds2texi-direntry
+ (concat
+ "@dircategory TeX\n"
+ "@direntry\n"
+ "* TeX Directories: (tds). A directory structure for TeX files.\n"
+ "@end direntry\n"))
+
+;; translation tables
+
+(defvar tds2texi-logos-alist
+ '(("{\\TeX}" . "TeX") ; when only doing Info
+ ("\\TeX{}" . "TeX") ; no need to use "@TeX{}"
+ ("{\\LaTeX}" . "LaTeX")
+ ("\\LaTeX{}" . "LaTeX")
+ ("{\\LaTeXe}" . "LaTeX2e")
+ ("\\LaTeXe{}" . "LaTeX2e")
+ ("{\\AmS}" . "AMS")
+ ("\\AmS{}" . "AMS")
+ ("{\\AMSTeX}" . "AMS-TeX")
+ ("\\AMSTeX{}" . "AMS-TeX")
+ ("\\MF{}" . "Metafont")
+ ("\\MP{}" . "MetaPost")
+ ("\\BibTeX{}" . "BibTeX")
+ ("{\\iniTeX}" . "INITEX")
+ ("\\iniTeX{}" . "INITEX")
+ ("{\\iniMF}" . "INIMF")
+ ("\\iniMF{}" . "INIMF")
+ ("{\\iniMP}" . "INIMP")
+ ("\\iniMP{}" . "INIMP")
+ ("{\\PS}" . "PostScript")
+ ("\\PS{}" . "PostScript")
+ ("{\\copyright}" . "@copyright{}")
+ )
+ "List of TeX logos and their replacement text after conversion.")
+
+(defvar tds2texi-logos-regexp-1 "\\(\\\\[A-Za-z]+{}\\)"
+ "Regexp for TeX logos to be converted using `tds2texi-logos-alist'.")
+
+(defvar tds2texi-logos-regexp-2 "\\({\\\\[^}]+}\\)"
+ "Regexp for TeX logos to be converted using `tds2texi-logos-alist'.")
+
+;;
+
+(defvar tds2texi-tags-alist
+ '(("\\emphasis" . "@emph")
+ ("\\citetitle" . "@cite")
+ ("\\literal" . "@file")
+ ("\\replaceable" . "@var")
+ ("\\command" . "@code") ; defined, but not used
+ ;; ("\\application" . "@r") ; unnecessary, but ...
+ ;; ("\\abbr" . "@sc") ; unnecessary, but ...
+ )
+ "List of markup tags and their replacement text after conversion.")
+
+(defvar tds2texi-tags-regexp "\\(\\\\[a-z]+\\)"
+ "Regexp for markup tags to be converted using `tds2texi-tags-alist'.")
+
+;;
+
+(defvar tds2texi-env-alist
+ '(("\\begin{ttdisplay}" . "@example")
+ ("\\end{ttdisplay}" . "@end example")
+ ("\\begin{tdsSummary}" . "@example")
+ ("\\end{tdsSummary}" . "@end example")
+ ("\\begin{enumerate}" . "@enumerate")
+ ("\\end{enumerate}" . "@end enumerate")
+ ("\\begin{enumerate-squeeze}" . "@enumerate")
+ ("\\end{enumerate-squeeze}" . "@end enumerate")
+ ("\\begin{itemize}" . "@itemize @bullet")
+ ("\\end{itemize}" . "@end itemize")
+ ("\\begin{itemize-squeeze}" . "@itemize @bullet")
+ ("\\end{itemize-squeeze}" . "@end itemize")
+ ("\\begin{description}" . "@itemize @bullet")
+ ("\\end{description}" . "@end itemize")
+ ("\\begin{description-squeeze}" . "@itemize @bullet")
+ ("\\end{description-squeeze}" . "@end itemize")
+ ("\\begin{legalnotice}" . "@titlepage") ; special hack
+ ("\\end{legalnotice}" . "@end titlepage")
+ ("\\begin{tabbing}" . "@quotation") ; special hack
+ ("\\end{tabbing}" . "@end quotation")
+ )
+ "List of environments and their replacement text after conversion.")
+
+(defvar tds2texi-env-regexp "\\(\\\\\\(begin\\|end\\){[^}]+}\\)"
+ "Regexp for environments to be converted using `tds2texi-env-alist'.")
+
+
+;;; some utility functions
+
+(defun tds2texi-string-replace (x-string x-replace)
+ "Searches for occurences of X-STRING, replacing them by X-REPLACE."
+ (save-excursion
+ (while (search-forward x-string nil t)
+ (replace-match x-replace t t)))) ; use fixed case!
+
+(defun tds2texi-regexp-replace (x-regexp x-replace)
+ "Searches for occurences of X-REGEXP, replacing them by X-REPLACE."
+ (save-excursion
+ (while (re-search-forward x-regexp nil t)
+ (replace-match x-replace t nil)))) ; use fixed case!
+
+
+(defun tds2texi-alist-replace (x-regexp x-alist)
+ "Searches for ocurrences of X-REGEXP, replacing them using X-ALIST.
+If no match is found in X-ALIST, leaves the original text unchanged."
+ (save-excursion
+ (let (x-match
+ x-replace)
+ (while (re-search-forward x-regexp nil t)
+ (setq x-match (match-string 1))
+ (setq x-replace (or (cdr (assoc x-match x-alist)) x-match))
+ (replace-match x-replace t t))))) ; use fixed case!
+
+
+;;; the main conversion function
+
+(defun tds2texi-convert ()
+ "Have a try at converting LaTeX to Texinfo. Good luck!"
+ (interactive)
+
+ ;; get a buffer to operate on and insert the LaTeX source
+ (set-buffer (get-buffer-create tds2texi-target-file))
+ (erase-buffer)
+ (insert-file-contents-literally tds2texi-source-file)
+
+ ;; tab characters can mess up tds-summary envrionments,
+ ;; so get rid of them as soon as possible
+ (untabify (point-min) (point-max))
+ (goto-char (point-min))
+
+ ;; do the conversion steps for the text body
+ (tds2texi-do-simple-tags) ; mostly general
+ (tds2texi-do-fancy-logos) ; mostly specific to TDS
+ (tds2texi-do-sectioning) ; mostly general
+ (tds2texi-do-markup-tags) ; mostly specific to TDS
+ (tds2texi-do-environments) ; partly specific to TDS
+
+ ;; do the conversion for header and trailer
+ (tds2texi-do-header) ; partly specific to TDS
+ (tds2texi-do-trailer) ; partly specific to TDS
+
+ ;; standard Texinfo functions
+ ; (texinfo-every-node-update) ; I don't like the extra node pointers.
+ (texinfo-all-menus-update)
+ (texinfo-master-menu nil)
+
+ (tds2texi-fixup-texinfo)
+
+ ;; all that's left to do is saving the buffer to a file
+ ;; -- we simply select the buffer and leave saving it to
+ ;; the user in case some manual intervention is needed
+ (switch-to-buffer tds2texi-target-file)
+ )
+
+
+;;; various steps of the conversion process
+
+(defun tds2texi-do-simple-tags ()
+ "First step of \\[tds2texi-convert]. Not useable by itself."
+
+ ;; literal `@' -- should come before anything else, since it's
+ ;; the Texinfo control character.
+ (tds2texi-regexp-replace "\\([^\\\\]\\)@" "\\1@@")
+
+ ;; fancy spacing -- should come early before we have many `@'
+
+ ;; "\@" -- space factor corrections before sentence end `.'
+ (tds2texi-regexp-replace "\\\\@\\." "@.")
+ ;; "\ " -- control space after `.' in the middle of sentences. Also
+ ;; converts \\ to \.
+ (tds2texi-regexp-replace "\\.\\\\\\([ \n]+\\)" ".@:\\1")
+ ;; "\ " -- control space used otherwise
+ (tds2texi-regexp-replace "\\\\\\([ \n]+\\)" "\\1")
+
+ ;; "\," -- thin space used with dimensions like "dpi" or "pt"
+ (tds2texi-regexp-replace "\\\\,\\([a-z]+\\)" "@dmn{\\1}")
+
+ ;; "\\" -- forced line breaks in references, where it's always
+ ;; preceded by a :. Previous "\ " conversion reduced \\ to \.
+ (tds2texi-string-replace ":\\ " ":@*\n")
+
+ ;; "\"" -- accents etc.:
+ (tds2texi-string-replace "\\\"" "@\"")
+ (tds2texi-string-replace "\\ss" "@ss")
+
+ ;; special TeX characters that needn't be quoted in Texinfo:
+ (tds2texi-string-replace "\\_" "_")
+ (tds2texi-string-replace "\\&" "&")
+ (tds2texi-string-replace "\\%" "%")
+
+ ;; special TeX characters that we prefer to transliterate:
+ (tds2texi-regexp-replace "\\\\slash[ ]*" "/")
+
+ ;; we could translate $...$ into @math{...}, but why bother
+ ;; when we can transliterate it easily?
+ (tds2texi-string-replace "$" "")
+ (tds2texi-string-replace "\\pm" "+-")
+)
+
+
+(defun tds2texi-do-fancy-logos ()
+ "Second step of \\[tds2texi-convert]. Not useable by itself."
+
+ ;; fancy TeX logos -- these are used in arguments of sections,
+ ;; so we have to do them early before doing sectioning commands.
+ (tds2texi-alist-replace tds2texi-logos-regexp-1 tds2texi-logos-alist)
+ (tds2texi-alist-replace tds2texi-logos-regexp-2 tds2texi-logos-alist)
+
+ ;; acronyms -- these are also used in arguments of sections.
+ ;; There's no need to use @sc markup, just upcase the argument.
+ (save-excursion
+ (while (re-search-forward "\\\\abbr{\\([^}]+\\)}" nil t)
+ (replace-match (upcase (match-string 1)) nil t)))
+
+ ;; applications -- similar to acronyms, so done here as well.
+ ;; There's no need to use @r markup either, it's the default!
+ (tds2texi-regexp-replace "\\\\application{\\([^}]+\\)}" "\\1")
+ )
+
+
+(defun tds2texi-do-sectioning ()
+ "Third step of \\[tds2texi-convert]. Not useable by itself."
+
+ ;; first do @chapter and @appendix by narrowing
+ (save-excursion
+ (save-restriction
+ (narrow-to-region
+ (point-min) (search-forward "\\appendix" nil t))
+ (goto-char (point-min))
+ (tds2texi-regexp-replace
+ "\\\\section{\\([^}]+\\)}[ ]*" "@node \\1\n at chapter \\1")
+ ))
+ (save-excursion
+ (save-restriction
+ (narrow-to-region
+ (search-forward "\\appendix" nil t) (point-max))
+ (tds2texi-regexp-replace
+ "\\\\section{\\([^}]+\\)}[ ]*" "@node \\1\n at appendix \\1")
+ ))
+
+ ;; @section and @subsection are just shifted a level up
+ (tds2texi-regexp-replace
+ "\\\\subsection{\\([^}]+\\)}[ ]*" "@node \\1\n at section \\1")
+ (tds2texi-regexp-replace
+ "\\\\subsubsection{\\([^}]+\\)}[ ]*" "@node \\1\n at subsection \\1")
+
+ ;; now we no longer need \appendix as a marker
+ (tds2texi-regexp-replace "\\\\appendix[ ]*\n" "")
+
+ ;; \newpage can go as well
+ (tds2texi-regexp-replace "%?\\\\newpage[ ]*\n" "")
+
+ ;; \labels are redundant since we have @nodes
+ (tds2texi-regexp-replace "\\\\label{sec:\\([^}]+\\)}[ ]*\n" "")
+
+ ;; \refs now refer to @nodes instead of \labels
+ (tds2texi-regexp-replace "\\\\ref{sec:\\([^}]+\\)}" "@ref{\\1}")
+ )
+
+
+(defun tds2texi-do-markup-tags ()
+ "Fourth step of \\[tds2texi-convert]. Not usable by itself."
+
+ ;; special tags -- for \CTAN, we must used fixed-case replace!
+ (tds2texi-string-replace "\\the\\tdsVersion" "@value{version}")
+ (tds2texi-string-replace "\\texmf{}" "@file{texmf}")
+ (tds2texi-string-replace "\\CTAN:" "@file{@var{CTAN}:}")
+
+ ;; convert simple tags without expanding their arguments:
+ ;; \emphasis, \citetitle, \literal, \replaceable
+ (tds2texi-alist-replace tds2texi-tags-regexp tds2texi-tags-alist)
+
+ ;; \\systemitem -- a silly tag with an extra argument that
+ ;; isn't printed. It is used exactly once!
+ (tds2texi-regexp-replace
+ "\\\\systemitem{\\([^}]+\\)}{\\([^}]+\\)}" "@file{\\2}")
+
+ ;; \path, \url -- here we can't avoid shuffling the argument
+ (tds2texi-regexp-replace "\\\\path|\\([^|]+\\)|" "@file{\\1}")
+ (tds2texi-regexp-replace "\\\\url|\\([^|]+\\)|" "@uref{\\1}")
+ (tds2texi-regexp-replace "\\\\email|\\([^|]+\\)|" "@email{\\1}")
+
+ ;; After turning \replaceable into @var above we now have to
+ ;; turn @var{...} into @file{@var{...}} to get quotation marks
+ ;; around file names consistent. (Read: those extra quotation
+ ;; marks inserted automatically by makeinfo in the @file tag.)
+
+ ;; For simplicity we first do the change everywhere and then
+ ;; undo it again inside `ttdisplay' environments, where we
+ ;; can leave @var by itself as @file isn't used there anyway.
+
+ (tds2texi-regexp-replace "@var{\\([^}]+\\)}" "@file{@var{\\1}}")
+ (save-excursion
+ (while (search-forward "\\begin{ttdisplay}" nil t)
+ (save-restriction
+ (narrow-to-region
+ (point) (search-forward "\\end{ttdisplay}" nil t))
+ (goto-char (point-min))
+ (tds2texi-regexp-replace "@file{@var{\\([^}]+\\)}}" "@var{\\1}")
+ )))
+
+ ;; eliminate redundant quotation marks around @file
+ (tds2texi-regexp-replace "``\\(@file{[^}]+}\\)''" "\\1")
+ (tds2texi-regexp-replace "`\\(@file{[^}]+}\\)'" "\\1")
+
+ ;; ... and combine multiple @file{}s in one line
+ (tds2texi-regexp-replace
+ "@file{\\([^ ]+\\)}@file{\\([^ ]+\\)}@file{\\([^ ]+\\)}" "@file{\\1\\2\\3}")
+ (tds2texi-regexp-replace
+ "@file{\\([^ ]+\\)}@file{\\([^ ]+\\)}" "@file{\\1\\2}")
+
+ ;; ... also simplify cases of nested @file{}s
+ (tds2texi-regexp-replace
+ "@file{@file{\\([^ ]+\\)}\\([^ ]+\\)}" "@file{\\1\\2}")
+
+ ;; literal `~' -- if it hasn't been converted to space earlier,
+ ;; we can now do the conversion to @w{word1 word2} without
+ ;; running the risk of confusion the regexp matcher somewhere.
+ ;; Unfortunately @w will get lost again in the HTML conversion
+ ;; because or   are not yet standard HTML tags.
+ (tds2texi-string-replace "~" "@tie{}")
+ )
+
+
+(defun tds2texi-do-environments ()
+ "Fifth step of \\[tds2texi-convert]. Not useable by itself."
+
+ ;; convert \begin and \end of environments
+ (tds2texi-alist-replace tds2texi-env-regexp tds2texi-env-alist)
+
+ ;; convert \items
+ (tds2texi-string-replace "\\item" "@item")
+
+ ;; insert newlines after description items where appropriate
+ (tds2texi-regexp-replace
+ "@item\\[\\([^]]+\\)\\][ ]*\n" "@item \\1\n")
+ (tds2texi-regexp-replace
+ "@item\\[\\([^]]+\\)\\][ ]*" "@item \\1\n")
+
+ ;; insert newlines after @item @file, also replace @item @file
+ ;; by @item @samp -- this is done because it may look nicer
+ ;; in the HTML version, but it depends on the style sheet used
+ (tds2texi-regexp-replace
+ "@item @file\\([^,\n]*\\),[ ]*" "@item @samp\\1,\n")
+ (tds2texi-regexp-replace
+ "@item @file" "@item @samp")
+ )
+
+
+;;; handling the header and trailer
+
+(defun tds2texi-do-header ()
+ "Convert LaTeX header to Texinfo. Used in \\[tds2texi-convert]."
+ (let (title-string
+ author-string
+ version-string)
+
+ ;; collect information
+ (save-excursion
+ (re-search-forward "\\\\tdsVersion{\\(.*\\)}" nil t)
+ (setq version-string (match-string 1))
+ (re-search-forward "\\\\title{\\(.*\\)}" nil t)
+ (setq title-string (match-string 1))
+ (re-search-forward "\\\\author{\\(.*\\)}" nil t)
+ (setq author-string (match-string 1))
+ )
+
+ ;; discard information lines
+ (tds2texi-regexp-replace "\\\\title{.*}[ ]*\n" "")
+ (tds2texi-regexp-replace "\\\\author{.*}[ ]*\n" "")
+ (tds2texi-regexp-replace "\\\\tdsVersion{.*}[ ]*\n\n" "")
+
+ ;; discard pre-title lines
+ (tds2texi-regexp-replace "%&latex[ ]*\n" "")
+ (tds2texi-regexp-replace "\\\\NeedsTeXFormat.*\n" "")
+
+ ;; convert \documentclass to \input texinfo
+ (tds2texi-regexp-replace "\\\\documentclass.*\n\n" "\\\\input texinfo\n")
+
+ ;; insert Texinfo header lines
+ (save-excursion
+ (goto-char (search-forward "texinfo\n" nil t))
+ (insert "@setfilename " tds2texi-filename "\n")
+ (insert "@settitle " title-string "\n\n")
+ (insert "@set version " version-string "\n\n")
+ (insert tds2texi-direntry "\n")
+ )
+
+ ;; discard \begin{document} and \maketitle
+ (tds2texi-regexp-replace "\\\\begin{document}[ ]*\n\n" "")
+ (tds2texi-regexp-replace "\\\\maketitle[ ]*\n\n" "")
+
+ ;; copy contents of `legalnotice' environments
+ (save-excursion
+ (let ((begin (search-forward "@titlepage\n\n" nil t))
+ (end (progn
+ (search-forward "@end titlepage" nil t)
+ (match-beginning 0))))
+ (copy-region-as-kill begin end)
+ ))
+
+ ;; insert stuff for title page before `legalnotice' environment
+ ;; -- \begin{legalnotice} has been converted to @titlepage
+ (save-excursion
+ (goto-char (search-forward "@titlepage\n" nil t))
+ (insert "@title " title-string "\n")
+ (insert "@subtitle Version @value{version}\n")
+ (insert "@author " author-string "\n\n")
+ (insert "@page\n at vskip 0pt plus 1filll\n")
+ )
+
+ ;; insert stuff for @node Top and master menu after `legalnotice'
+ ;; -- \end{legalnotice} has been converted to @end titlepage
+ (save-excursion
+ (goto-char (search-forward "@end titlepage\n\n" nil t))
+
+ (insert "@ifnottex\n")
+ (insert "@node Top\n at top " title-string "\n\n")
+
+ ;; insert contents of `legalnotice' copied above
+ (yank) ; should include a "\n\n" at the end
+
+ (insert "@menu\n at end menu\n")
+ (insert "@end ifnottex\n\n")
+ )
+
+ ;; discard \tableofcontents -- @contents belongs in the trailer
+ (tds2texi-regexp-replace "\\\\tableofcontents[ ]*\n\n" "")
+ ))
+
+(defun tds2texi-do-trailer ()
+ "Convert LaTeX trailer to Texinfo. Used in \\[tds2texi-convert]."
+
+ ;; The list of contributors is a LaTeX tabbing environment, which
+ ;; is difficult to convert -- we convert it to a normal paragraph
+ ;; inside a @quotation environment, so it gets indented a little.
+
+ ;; Conversion of the tabbing environment is already done elsewhere,
+ ;; so we just have to remove some redundant tags.
+
+ ;; discard alignment preamble consisting of lines starting with
+ ;; \hspace{0.25\linewidth}. We use \hspace in other places too.
+ (tds2texi-regexp-replace "\\\\hspace.*\n" "")
+
+ ;; convert "\>" and "\\" in tabbing environment to comma
+ (tds2texi-regexp-replace " +\\\\>[ ]*" ", ")
+
+ ;; In the earlier conversion of "\ ", "\\" followed by newline
+ ;; was already converted to "\", so we just have to convert
+ ;; the remaining instances of "\" followed by space or newline.
+ (tds2texi-regexp-replace "\\s +\\\\\\s +" ", ")
+
+ ;; convert \end{document} to @contents and @bye
+ (tds2texi-string-replace "\\end{document}"
+ "@iftex\n at contents\n at end iftex\n at bye")
+ )
+
+(defun tds2texi-fixup-texinfo ()
+ "Fix up a few last-minute items. Used in \\[tds2texi-convert]."
+
+ ;; Fix the reference to the node name with the logo.
+ (tds2texi-string-replace "Non-font MF" "Non-font Metafont")
+ )
+
+;;; tds2texi.el ends here
Added: tex-common/trunk/doc/tds-1.1/tdsguide.cls
===================================================================
--- tex-common/trunk/doc/tds-1.1/tdsguide.cls 2006-12-06 16:12:33 UTC (rev 1985)
+++ tex-common/trunk/doc/tds-1.1/tdsguide.cls 2006-12-06 16:12:46 UTC (rev 1986)
@@ -0,0 +1,845 @@
+% $Id: tdsguide.cls,v 1.19 2004/03/28 14:21:10 karl Exp $
+% LaTeX document class tdsguide
+% (history at end)
+%
+% This class provides markup & layout for the TDS report.
+%
+\NeedsTeXFormat{LaTeX2e}[1994/12/01] % star-form of \CheckCommand, etc.
+
+
+% The code below is explained in the implementation documentation of the
+% rcs package.
+
+\begingroup
+ \def\RCSClass#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{%
+ \def\date{#4}\def\id{v#7}%
+ \ProvidesClass{#1}[\date\space\id\space #2]%
+ }
+
+ \RCSClass{tdsguide}{markup and layout for TDS document}
+ $Date: 2004/03/28 14:21:10 $: 9999/00/00 \endRCS
+ $Revision: 1.19 $: 0.0 \endRCS
+\endgroup
+
+
+% default setup
+\ifx \CatEscape\undefined
+ \chardef\CatEscape=0
+ \chardef\CatOpen=1
+ \chardef\CatClose=2
+ \chardef\CatIgnore=9
+ \chardef\CatLetter=11
+ \chardef\CatOther=12
+ \chardef\CatActive=13
+
+ \chardef\CatUsCode=\catcode`\_
+\fi
+
+
+
+%%% ======================================================================
+
+%
+% OPTIONS
+%
+
+\catcode`\_=\CatLetter
+
+
+% We can select to use Roman for METAFONT/METAPOST logos by the
+% nomflogo option. That should be done if no current logo fonts (with
+% `P' & `S') are available. Of course, it would be best to install
+% current fonts.
+% The mflogo options is provided for upward compatibility.
+
+\let\tds_mflogo\relax
+\DeclareOption{nomflogo}{%
+ \def\tds_mflogo{\let\textlogo\tds at transfer@logo} % gimme refinements! :(
+ }
+\DeclareOption{mflogo}{}
+
+
+\newif\ifTdsDraft
+ \TdsDraftfalse
+\DeclareOption{draft}{%
+ \TdsDrafttrue
+ \PassOptionsToClass{\CurrentOption}{article}%
+ }
+\DeclareOption{final}{%
+ \TdsDraftfalse
+ \PassOptionsToClass{\CurrentOption}{article}%
+ }
+
+
+\catcode`\_=\CatUsCode
+
+
+%%% ------------------------------------------------------------
+
+
+%
+% CONFIGURATION, INHERITANCE, AND OTHER MODULES
+%
+
+
+% configure this class
+
+\InputIfFileExists{tdsguide.cfg}{%
+ \typeout{*************************************^^J%
+ *^^J%
+ * Local config file tdsguide.cfg used^^J%
+ *^^J%
+ *************************************%
+ }%
+ }{}
+
+
+% inherit article class
+
+\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
+\ProcessOptions
+\LoadClass{article}
+
+
+% add more modules
+
+\RequirePackage{url} % file names & email addresses
+\RequirePackage{mflogo} % MF & MP logos (but see below)
+%\RequirePackage{hyperref} % navigation specials in .dvi
+\RequirePackage{fancyhdr} % rev. no & draft notice in headers
+
+% Put hypertext links in the DVI file on the URL's:
+% \def\UrlLeft#1\UrlRight{\special{html:<a href="#1">}#1\special{html:</a>}}
+% Don't do this because xdvi doesn't know what do with ftp url's, which
+% is the vast majority of links; also because we use the url package for
+% mere directory names.
+
+
+%%% ============================================================
+
+
+%
+% NEW MARKUP
+%
+
+\catcode`\_=\CatLetter
+
+% info about original SGML files
+
+\def\sourcefile#1{}
+\def\formatterfile#1{}
+
+% revision number (should use rcs package)
+
+\newtoks\tdsVersion
+
+
+
+%
+% RENDER DOCUMENT-SPECIFIC MARKUP
+%
+
+% categories for terms
+
+% typewriter type.
+% `_', `\_', and `\\' produce respective chars.
+
+\def\tds_tt{%
+ \begingroup
+ \catcode`\_=\CatOther
+ \chardef\_=`\_
+ \chardef\\=`\\
+ \tds_tt_set
+ }
+\def\tds_tt_set#1{%
+ \ttfamily
+ #1%
+ \endgroup
+ }
+
+\def\systemitem#1{\tds_tt}
+\def\replaceable#1{{\rmfamily $\langle$\textit{#1}$\rangle$}}
+\let\command=\tds_tt
+\def\application#1{\textrm{#1}}
+\let\literal=\tds_tt
+\let\email=\url
+
+% \abbr may be called with lowercase & uppercase letters, actually all
+% abbreviations are to be typeset with reduced-size uppercase letters.
+% (That lowercase letters are used as arguments was a half-hearted
+% attempt by Norm who did use small caps at this time.) `Reduced size'
+% means one point smaller than the current size. If the reduced size
+% is larger than 12pt, we issue a warning; if no font-generating
+% driver is used, this situation will lead to character replacements
+% most probably.
+%
+% This macro may be written to an auxilliary file, we must not use
+% underscores in its name.
+
+\DeclareRobustCommand\tds at reduced@size{%
+ \dimen@\f at size\p@
+ \advance \dimen@ -\p@ % dimen@ = font_size - 1
+ \ifdim \dimen@ >12\p@
+ \@font at warning{%
+Using font size `\the\dimen@' for abbreviations. That might lead%
+\MessageBreak
+to character replacements if you don't use a driver that\MessageBreak
+generates fonts.}%
+ \fi
+ \math at fontsfalse
+ \fontsize{\the\dimen@}\z@
+ \selectfont
+ }
+\def\abbr#1{{\tds at reduced@size \uppercase{#1}}}
+
+% references
+
+\let\xref\relax
+\let\citetitle=\textit
+
+% aliases for LaTeX markup
+
+\let\emphasis=\emph
+
+% environment `legalnotice', part of front matter
+
+\let\legalnotice=\par
+\let\endlegalnotice=\par
+
+% environment `ttdisplay', used to explicate some fact. Basically,
+% it's the alltt environment without parskip and with an additional
+% level of indentation.
+
+\def\ttdisplay{%
+ \begingroup
+ \list{}{%
+ \parsep\z at skip % no skip before env
+ \parskip\z at skip
+ \relax
+ }%
+ \item\relax
+ \parshape\z@
+ %% code below is copied from alltt.dtx.
+ \leftskip\@totalleftmargin
+ \@tempswafalse
+ \def\par{%
+ \if at tempswa
+ \leavevmode\null\@@par\penalty\interlinepenalty
+ \else
+ \@tempswatrue
+ \ifhmode
+ \@@par
+ \penalty\interlinepenalty
+ \fi
+ \fi
+ }%
+ \obeylines
+ \verbatim at font
+ \let\org at prime~%
+ \@noligs
+ \everymath \expandafter{\the\everymath \let~\org at prime}%
+ \everydisplay \expandafter{\the\everydisplay \let~\org at prime}%
+ \let\org at dospecials\dospecials
+ \g at remfrom@specials{\\}%
+ \g at remfrom@specials{\{}%
+ \g at remfrom@specials{\}}%
+ \let\do\@makeother \dospecials
+ \let\dospecials\org at dospecials
+ \frenchspacing\@vobeyspaces
+ \everypar \expandafter{\the\everypar \unpenalty}%
+ %}
+ }
+\def\endttdisplay{%
+ \endlist
+ \endgroup
+ \vskip -\parskip % undo skip after env
+ }
+
+% Code below is from alltt.dtx. I don't understand why it's not part
+% of the LaTeX kernel.
+\def\g at remfrom@specials#1{%
+ \def\@new at specials{}%
+ \def\@remove##1{%
+ \ifx ##1#1%
+ \else
+ \g at addto@macro\@new at specials{\do ##1}%
+ \fi
+ }%
+ \let\do\@remove \dospecials
+ \let\dospecials\@new at specials
+ }
+
+
+
+
+%%% ------------------------------------------------------------
+
+
+%
+% LOGOS
+%
+
+
+% Some of them are rather document-specific.
+
+\def\texmf{\path|texmf|}
+\def\CTAN:{\replaceable{\abbr{CTAN}:}}
+
+
+% Actually, I should use my logos package for the rest... [-js]
+
+% The AmS definition is from AmS-LaTeX, that's more stable in this
+% document's context than the one from AmS-TeX.
+\def\AmS{%
+ \begingroup
+ \protect\usefont{OMS}{cmsy}{m}{n}%
+ A\kern-.1667em \lower.5ex\hbox{M}\kern-.125em S%
+ \endgroup
+ }
+\def\AMSTeX{\AmS-\TeX}
+
+\def\iniTeX{\texttt{INITEX}\@}
+\def\iniMF{\texttt{INIMF}\@}
+\def\iniMP{\texttt{INIMP}\@}
+
+\def\PS{\textsc{PostScript}}
+
+
+% If we don't use logo fonts, both the Metafont and the MetaPost logo
+% is typeset in the current font, as shown in this comment. The macros
+% `\MF' & `\MP' expand to two \textfont macros, with uppercase
+% syllables as arguments. We check for the syllable `FONT', this has
+% to be typeset in lowercase. All other syllables are capitalized.
+
+\def\tds_logo_fontarg{FONT}
+\DeclareRobustCommand\tds at transfer@logo[1]{%
+ \def\tds_arg{#1}%
+ \ifx \tds_arg\tds_logo_fontarg
+ font%
+ \else
+ \tds_capitalize#1\tds_argend
+ \fi
+ }
+\def\tds_capitalize#1#2\tds_argend{%
+ \uppercase{#1}\lowercase{#2}%
+ }
+
+\tds_mflogo
+
+
+% Use a small caps fake for BibTeX's `ib'. This way we can typeset it
+% in bold face or sans-serif, too. The code is copied from the LaTeX
+% logo definition, from ltlogos.dtx.
+
+\DeclareRobustCommand\tds at smsize{%
+ $\m at th$% % force math size calculation
+ \csname S@\f at size\endcsname
+ \fontsize\sf at size\z@
+ \math at fontsfalse \selectfont
+ }
+
+\def\BibTeX{B\kern-.05em{\tds at smsize IB}\kern-.08em\TeX}
+
+
+%%% ============================================================
+
+%
+% TDS SUMMARIES
+%
+
+% Typeset a figure that shows the TeX directory layout. The layout is
+% input with optical markup:
+%
+% \begin{tdsSummary}
+% dir/ explanation of dir
+% . subdir/ explanation of subdir
+% . . subsubdir/ next subdir level
+% . dir/dir/ more than one dir in one line
+% . <category>/ explanation of category
+% \end{tdsSummary}
+%
+% Directories and category names don't have dots.
+
+% We transform that input into a table. The first table column (the
+% directory spec) is terminated by a slash that's followed by white
+% space. Directory names are typeset in monocase. <categories> are
+% tagged with \replaceable. Subdirectory levels are indented by one
+% quad. A quad is placed between columns. The explanation text
+% is typeset in one line.
+
+% As this is a special implementation for a special document, these
+% design decisions are hardwired, no protected interface is available.
+% Design changes will be realized by changes to the macro code.
+
+
+% The environment is realized as a trivlist to behave correctly in list
+% environments. I don't use a tabular environment, since I don't know
+% exactly how the first column is tokenized. Instead a halign is used.
+% IMO it does not matter, as tdsSummary does not use table markup
+% anyhow. If somebody wants to use longer explanations and if they must
+% be broken then, I have to use one of the tabulars of the tools bundle.
+
+% The first column (the directory names) is typeset in typewriter type. The
+% font chosen hereby must have the underscore at its ASCII position. If
+% that is not the case, one has to generalize \tds_dir_tags below.
+% Namely, this macro sets up the special lexical convention for this
+% column. As TeX will look at the first token of the column to check for
+% the table end, \cr, or \omit before \tds_dir_tags is evaluated, the
+% redefinition of the lexical analysis will not have happened for that
+% token. So we have to check this token specially if it's one of the
+% special optical markup chars.
+
+% After we started the trivlist, we need to supply the item (as this
+% macro really adds the vertical space). But it does not actually
+% start an item, it sets up the everypar register to do so. We fake
+% the item start as we don't want to go in horizontal mode, \halign
+% needs to be evaluated in vertical mode.
+%
+% \par is not evaluated by \endtrivlist and \end, so we don't need
+% another group around its redefinition.
+
+\def\tdsSummary{%
+ \trivlist \item\relax
+ \vskip\parskip
+ \global\@inlabelfalse \global\@newlistfalse \global\everypar{}%
+ \tabskip 0pt
+ \let\par\crcr \obeylines % can't use \obeycr, redefined by LaTeX
+ % redefine \obeylines to do nothing; url.sty v3.0 calls it, and the
+ % ^^M character therein causes a `Missing \endgroup inserted' error
+ % at a \path|...| within a tdsSummary, if it's already defined as \par.
+ \let\obeylines=\relax
+ \halign\bgroup
+ \ttfamily \tds_dir_tags \tds_first_token ##\unskip\hfil &%
+ \quad ##\unskip\hfil \cr
+ }
+\def\endtdsSummary{%
+ \crcr
+ \egroup
+ \endtrivlist
+ }
+
+
+% Our special lexical conventions are: `.' denotes the next directory
+% level, `<...>' denotes a directory category, and `/' is a column
+% separator if it is followed by space or tab, a typeset slash
+% otherwise. Underscores don't have any special meaning.
+
+\begingroup
+ \catcode`\.=\CatActive
+ \catcode`\<=\CatActive
+ \catcode`\/=\CatActive
+ \catcode`\:=\CatActive
+ \gdef\tds_dir_tags{%
+ \catcode`\.=\CatActive \let.=\tds_next_dir_level
+ \catcode`\<=\CatActive \let<=\tds_dir_category
+ \catcode`\/=\CatActive \let/=\tds_slash
+ \catcode`\:=\CatActive \let:=\tds_colon
+ \catcode`\_=\CatOther
+ \tt
+ }
+\endgroup
+
+% There are spaces between the dots, ignore them.
+
+\def\tds_next_dir_level{\quad \ignorespaces}
+\def\tds_dir_category#1>{\replaceable{#1}}
+
+\chardef\tds_dir_sep=`\/ % typeset a directory separator
+
+% The slash has to check the stuff behind. If it's a space or a tab,
+% \next is bound to the action `blank-space' (the binding of all
+% '(space . #\Space) tokens). A tab is usually tokenized to the same
+% token, but we care for redefinitions below.
+%
+\def\tds_slash{%
+ \futurelet\next \tds_check_dir_end
+ }
+
+% For colons in the examples.
+%
+\def\tds_colon{:&}
+
+% We need two control sequencess that are bound to the actions currently
+% bound to '(space . #\Space) and (tex:parse "\t"). A direct \let
+% evaluation is difficult as the lexical analysis collapses subsequent
+% spaces to one token. But we need one space token behind the equal
+% sign, to be able to \let our cseq to the next space token. The first
+% token is stored in the replacement list of a macro, the second token
+% comes as its argument.
+
+\def\tds_let#1#2{\let#1= #2}
+\tds_let\tds_space{ }
+\tds_let\tds_tab{^^I}
+
+\def\TdsColSep{/&} % use trailing slashes for dir names
+
+\def\tds_check_dir_end{%
+ \ifx \next\tds_space
+ \let\next\TdsColSep
+ \else
+ \ifx \next\tds_tab
+ \let\next\TdsColSep
+ \else
+ \let\next\tds_dir_sep
+ \fi
+ \fi
+ \next
+ }
+
+
+% We're almost finished with the tdsSummary setup. The stuff above is
+% not used for the first column token, as it's already tokenized when
+% the catcode changes take effect. So let's check and remap this token
+% by hand. Actually, I'm sloppy here; I assume that `/' won't be a
+% used as a directory name and that no directory name starts with an
+% underscore. But then, I know that this won't happen in TDS... :-)
+
+\def\tds_first_token{%
+ \futurelet\next \tds_check_special
+ }
+\def\tds_check_special{%
+ \ifx \next.%
+ \def\next{\afterassignment\tds_next_dir_level \let\next}%
+ \else
+ \ifx \next<%
+ \def\next{\afterassignment\tds_dir_category \let\next}%
+ \else
+ \let\next\relax
+ \fi
+ \fi
+ \next
+ }
+
+
+
+%%% ============================================================
+
+%
+% LAYOUT
+%
+
+
+% text area size
+
+% We use the same height as article's default, but increase the width.
+
+\textwidth=35pc
+\oddsidemargin = \paperwidth
+ \advance\oddsidemargin by -\textwidth
+ \divide\oddsidemargin by 2
+\evensidemargin = \oddsidemargin
+\hoffset = -1in
+
+
+% spacing
+
+\parindent=0pt % no paragraph indentation
+\emergencystretch=2em % fewer overfull hboxes, only a memo
+
+\parskip=1ex plus 1ex minus .5ex % between paragraphs; if you change it,
+ % change the spacing in section headers
+ % below, too!
+
+% Our spacing for lists is very simplistic, but uniform: We use (almost)
+% parskip everywhere, and don't distinguish vertical spacing for
+% different list levels. Actually, the latter is the thing we might want
+% to introduce later again.
+
+\labelsep=1.1em % increase distance between item & text
+\topsep=0pt % no extra skip above list in paragraph
+\partopsep=0pt % no extra skip above list starting par.
+\itemsep=0pt % no extra space between items
+\parsep=.9\parskip % between paragraphs in items
+
+\def\@listI{%
+ \leftmargin\leftmargini
+ }
+\let\@listi\@listI
+\@listi
+
+\def\@listii{%
+ \leftmargin\leftmarginii
+ \labelwidth\leftmarginii \advance \labelwidth-\labelsep
+ }
+
+\def\@listiii{%
+ \leftmargin\leftmarginiii
+ \labelwidth\leftmarginiii \advance \labelwidth-\labelsep
+ }
+
+
+% Like itemize, but squeeze the items.
+
+\newenvironment{itemize-squeeze}
+ {%
+ \parsep\z at skip
+ \itemize
+ }{%
+ \enditemize
+ }
+
+% Ditto, for description.
+
+\newenvironment{description-squeeze}
+ {%
+ \parsep\z at skip
+ \description
+ }{%
+ \enddescription
+ }
+
+
+% Redefine section headers, different spacing and other fonts.
+
+\newskip\TdsPreSubSectionSkip
+ \TdsPreSubSectionSkip = 2.5ex plus 0.5ex minus 0.2ex
+
+\def\section{%
+ \@startsection{section}{1}% % name and level
+ {\z@}% % indentation
+ {-3ex plus-.75ex minus-.2ex}% % skip above and don't indent next par
+ {1.5ex plus.2ex}% % skip below
+ {\reset at font \Large \sffamily}% % type
+ }
+\def\subsection{%
+ \@startsection{subsection}{2}% % name and level
+ {\z@}% % indentation
+ {-\TdsPreSubSectionSkip}% % skip above and don't indent next par
+ \parskip % skip below
+ {\reset at font \large \sffamily}% % type
+ }
+\def\subsubsection{%
+ \@startsection{subsubsection}{3}% % name and level
+ {\z@}% % indentation
+ {-\TdsPreSubSectionSkip}% % skip above and don't indent next par
+ \parskip % skip below
+ {\reset at font \normalsize \sffamily}% % type
+ }
+\def\paragraph{%
+ \@startsection{paragraph}{4}% % name and level
+ {\z@}% % indentation
+ \TdsPreSubSectionSkip % skip above and indent next par
+ {-1.5em}% % skip after, run in text
+ {\reset at font \normalsize \scshape}% % type
+ }
+
+
+% Table of contents
+
+\setcounter{tocdepth}{2} % only sections on first two levels
+
+% Less space between TOC entries, discard the parskip. For that, we
+% have to redefine \@starttoc, since no hook is available.
+\let\tds_orig_starttoc=\@starttoc
+\def\@starttoc#1{%
+ \begingroup
+ \parskip\z at skip
+ \tds_orig_starttoc{#1}%
+ \endgroup
+ }
+
+% Section TOC entries in sans serif, and less space above. The code
+% below is copied from the article view on classes.dtx, I have changed
+% space and font. But let's first assure that we shouldn't use a newer
+% version of this code.
+\CheckCommand*\l at section[2]{%
+ \ifnum \c at tocdepth >\z@
+ \addpenalty\@secpenalty
+ \addvspace{1.0em \@plus\p@}%
+ \setlength\@tempdima{1.5em}%
+ \begingroup
+ \parindent \z@ \rightskip \@pnumwidth
+ \parfillskip -\@pnumwidth
+ \leavevmode \bfseries
+ \advance\leftskip\@tempdima
+ \hskip -\leftskip
+ #1\nobreak\hfil \nobreak\hb at xt@\@pnumwidth{\hss #2}\par
+ \endgroup
+ \fi}
+\def\l at section#1#2{%
+ \ifnum \c at tocdepth >\z@
+ \addpenalty\@secpenalty
+ \addvspace{.75ex \@plus\p@ \@minus\p@}% % was: 1em plus 1pt
+ \setlength\@tempdima{1.5em}%
+ \begingroup
+ \parindent \z@
+ \rightskip \@pnumwidth
+ \parfillskip -\@pnumwidth
+ \leavevmode \sffamily % was: \bfseries
+ \advance\leftskip\@tempdima
+ \hskip -\leftskip
+ #1\nobreak \hfil \nobreak \hbox to\@pnumwidth{\hss #2}%
+ \par
+ \endgroup
+ \fi}
+
+
+% Not so spacey a title, please.
+
+\def\@maketitle{%
+ \null
+ \kern-90pt \relax \kern0pt
+ \begin{center}%
+ {\LARGE \@title \par}%
+ %\vskip 1.5em%
+ {\large
+ \lineskip .5em%
+ \begin{tabular}[t]{c}%
+ \@author
+ \end{tabular}\par}%
+ \vskip 1em%
+ {\large version \the\tdsVersion \quad \@date}%
+ \end{center}%
+ \par
+ \vskip 1.5em}
+
+
+% Make labels in the description environment come out in the
+% requested type rather than bold.
+
+\def\descriptionlabel#1{\hspace\labelsep #1}
+
+
+% Headline & footline
+
+\pagestyle{fancy}
+
+\lhead{}
+\chead{%
+ \ifTdsDraft draft \fi % <-- space!
+ TDS version \the\tdsVersion
+ }
+\rhead{}
+\renewcommand{\headrulewidth}{0.4pt}
+
+\lfoot{}
+\cfoot{\thepage}
+\rfoot{}
+\renewcommand{\footrulewidth}{0pt}
+
+
+
+%%% ============================================================
+
+\catcode`\_=\CatUsCode
+
+\endinput
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% $Log: tdsguide.cls,v $
+% Revision 1.19 2004/03/28 14:21:10 karl
+% (\tdsSummary): \let\obeylines=\relax after we set
+% it, so url.sty v3.0's usage of \obeylines does not
+% cause errors.
+%
+% Revision 1.18 1998/01/26 21:26:10 karl
+% (\TeXinfo): Remove unused and incorrect name.
+% (\parsep): Decrease slightly.
+% (\l at section): Decrease section spacing for toc slightly.
+% (\@maketitle): Remove word `draft'.
+%
+% Revision 1.17 1997/02/07 20:47:16 karl
+% Fix : in tdsSummary, more doc.
+%
+% Revision 1.16 1996/11/16 14:23:58 karl
+% fancyhdr requires different commands.
+%
+% Revision 1.13 1995/11/21 18:57:35 schrod
+% Add description-squeeze environment.
+%
+% Revision 1.12 1995/11/14 18:33:18 schrod
+% Drop draft hint in legalnotice environment, make title more
+% squeezed. Changes by Karl, to make title & toc fit on one page.
+%
+% Revision 1.11 1995/11/14 12:36:54 schrod
+% Use url.sty instead of path.sty. (On request of Karl, better input
+% syntax and different line breaks [0.103].)
+% Rename environment explicate to ttdisplay. (Proposal of Karl.)
+%
+% Revision 1.10 1995/11/11 16:29:01 schrod
+% Identify version of class in log file.
+% Change layout of table of contents. Implementation of a discussion
+% between Karl Berry and myself.
+%
+% Revision 1.9 1995/11/11 15:43:34 schrod
+% Replace alltt environment by explicate environment. Change
+% requested by Karl at 09 Nov 95.
+%
+% Revision 1.8 1995/11/02 10:52:29 schrod
+% Add option nomflogo, mflogo is default now.
+% Don't need provision for slanted typewriter type any more,
+% replacable texts are set in italics now.
+% Add logos \texmf and \CTAN:. [kb]
+% Set margins in addition to \textwidth. It's a bit wider, too. [kb]
+% Wider distance between item label and item text. [kb]
+% New environment itemize-squeeze, without space between items. [kb]
+%
+% Revision 1.7 1995/05/18 09:06:39 schrod
+% Don't parse arguments unnecessarily early, one might change
+% catcodes in them.
+% Use \tds_tt to switch to typewriter, also typesets backslashs and
+% underscores [kb].
+% Increase width to 33pc [kb].
+%
+% Revision 1.6 1995/05/12 23:19:07 schrod
+% \f at size may be a fraction, so use dimension register to compute
+% the reduced size for abbreviations [dc].
+% In summary tables, terminate the directory names with slashes [kb, nw].
+%
+% Revision 1.5 1995/05/09 01:46:24 schrod
+% Typeset abbreviation one point smaller than surrounding font [uv,
+% kb, bb], use always uppercase letters for them. Rename the tag from
+% \acronym to \abbr [kb, nw].
+%
+% Revision 1.4 1995/05/09 00:39:57 schrod
+% Repair vertical spacing around tdsSummary environment.
+%
+% Revision 1.3 1995/05/08 17:14:52 schrod
+% For TDS 0.72 Norm changed the document to use \abbr (argument with
+% lowercase letters) instead of \acronym. It's not looking better, of
+% course; small caps is not really a good font for abbreviations. This
+% revision just tracks his change, I'll look later if I can improve the
+% rendering.
+%
+% Revision 1.2 1995/05/07 18:22:53 schrod
+% In environment tdsSummary: Next directory level indented by one
+% quad, without dots for indentation [kb, !uv, js].
+% Renamed Draft flag to TdsDraft, to keep namespace clean.
+% Headline now features a centered short title [kb, uv, nw]. It's
+% still ruled.
+% \replaceable used spurious \selectfont [uv]. \dir & \ext are not
+% used [uv].
+% Subsubsections are also numbered and not indented [uv]. But they
+% are still not added to the table of contents. Actually, we have only
+% _one_ subsubsection...
+% Set erroneously counter `secnumdepth' when I wanted fewer section
+% headings in the table of contents. That's controlled by counter
+% `tocdepth' [uv].
+% Inherit tdsguide from article class, not from ltxguide. The tags
+% of the latter class are not appropriate and we define our layout
+% ourselves.
+%
+
+%
+% pre-CVS Log:
+%
+% 19 Apr 95 js Made a LaTeX2e class.
+% Use mflogo option to select MF/MP logo typesetting,
+% support configuration file.
+% 1994-1995 nw Initial revision.
+
+
+
+%%%------------------------------------------------------------
+
+% mode: LaTeX
+% Local Variables:
+% TeX-brace-indent-level: 4
+% indent-tabs-mode: t
+% TeX-auto-untabify: nil
+% TeX-auto-regexp-list: LaTeX-auto-regexp-list
+% page-delimiter: "^%%%"
+% End:
More information about the Debian-tex-commits
mailing list