diff options
Diffstat (limited to 'tds')
l--------- | tds | 1 | ||||
-rw-r--r-- | tds/ChangeLog | 312 | ||||
-rw-r--r-- | tds/Makefile | 44 | ||||
-rw-r--r-- | tds/README | 19 | ||||
l--------- | tds/README.html | 1 | ||||
-rw-r--r-- | tds/tds.aux | 61 | ||||
-rw-r--r-- | tds/tds.dvi | bin | 89212 -> 0 bytes | |||
-rw-r--r-- | tds/tds.html | 1997 | ||||
-rw-r--r-- | tds/tds.info | 1714 | ||||
-rw-r--r-- | tds/tds.pdf | bin | 195357 -> 0 bytes | |||
-rw-r--r-- | tds/tds.sed | 14 | ||||
-rw-r--r-- | tds/tds.tex | 1585 | ||||
-rw-r--r-- | tds/tds2texi.el | 577 | ||||
-rw-r--r-- | tds/tdsguide.cls | 845 |
14 files changed, 1 insertions, 7169 deletions
@@ -0,0 +1 @@ +info/tds
\ No newline at end of file diff --git a/tds/ChangeLog b/tds/ChangeLog deleted file mode 100644 index 90d726e479..0000000000 --- a/tds/ChangeLog +++ /dev/null @@ -1,312 +0,0 @@ -2004-06-23 Karl Berry <karl@gnu.org> - - * tds.tex: version 1.1. - * tds.tex: make that june 2004. - -2004-06-08 Karl Berry <karl@gnu.org> - - * tds.tex: type3, version 1.096. - -2004-06-06 Karl Berry <karl@gnu.org> - - * tds.tex: 1.095 (still draft). - -2004-06-04 Karl Berry <karl@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@gnu.org> - - * tds2texi.el (tds2texi-logos-alist): Metafont instead of - METAFONT. - -2004-05-15 Karl Berry <karl@gnu.org> - - * tds.tex: doc/ subtree improvements from Chris Rowley, and more. - -2004-05-14 Karl Berry <karl@gnu.org> - - * 1.094. - * tds.tex: clarify description of enc & map, maybe. - -2004-05-08 Karl Berry <karl@gnu.org> - - * tds.tex: fixes from Staszek. - * tds.tex: check in. - -2004-04-03 Karl Berry <karl@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@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@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@gnu.org> - - * tds.tex: pfm text, etc., from feb03. - -2003-02-02 <karl@gnu.org> - - * tds.tex: 1.0 - -2003-01-18 <karl@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@gnu.org> - - * tds2texi.el: doc fixes, @tie. - * tds.tex: enc/maps vs fontname clarification, removal of some - history. - -2003-01-12 <karl@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@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@gnu.org> - - * tds.tex: I have a new address. - -Wed Apr 21 15:30:34 1999 Karl Berry <karl@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@cs.umb.edu> - - * tds.tex: Version 0.9995: add extension section. - - * tdsguide.cls (\TeXinfo): Remove unused and incorrect name. - (\parsep): Decrease slightly. - (\l@section): Decrease section spacing for toc slightly. - (\@maketitle): Remove word `draft'. - -Fri Jan 23 17:14:01 1998 Karl Berry <karl@cs.umb.edu> - - * tds.tex: checkin 0.9994. - -Sun Jul 20 16:29:37 1997 Karl Berry <karl@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@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@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@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@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@cs.umb.edu> - - * tdsguide.cls: Saving version as of 0.999. - -Sun Nov 10 17:36:36 1996 Karl Berry <karl@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@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@cs.umb.edu> - - * tds.tex: pnr10.tfm should be pnr10.mf. From Pierre. - -Wed Nov 22 11:46:51 1995 Karl Berry <karl@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@cs.umb.edu> - - * Version 0.999 sent to TUGboat (well, not really). - -Wed Nov 15 19:50:37 1995 Karl Berry <karl@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@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@cs.umb.edu> - - * Version 0.102. - - * Include package subdirectories under bibtex. - - * Version 0.101. - -Tue Oct 17 13:22:08 1995 Karl Berry <karl@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@cs.umb.edu> - - * Version 0.100. - -Fri Oct 13 16:23:34 1995 Karl Berry <karl@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@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@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@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@cs.umb.edu> - - - Remove \protect. From Ulrik. - -Wed Oct 4 15:08:01 1995 Karl Berry <karl@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. - diff --git a/tds/Makefile b/tds/Makefile deleted file mode 100644 index 802f45b97c..0000000000 --- a/tds/Makefile +++ /dev/null @@ -1,44 +0,0 @@ -# $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." diff --git a/tds/README b/tds/README deleted file mode 100644 index f9aff03933..0000000000 --- a/tds/README +++ /dev/null @@ -1,19 +0,0 @@ -<pre> -This is the TeX Directory Structure (TDS) document, describing a runtime -layout of TeX-related files intended to be portable, -implementation-independent, etc. Most TeX distributions have adopted -this in some form. - -If any questions, comments, or suggestions, email twg-tds@tug.org. -Mailing list archives available at: http://tug.org/mail-archives/twg-tds/ - -tds.tex is the master source file. A few extra LaTeX packages that it -uses are in packages.zip, in the unlikely event that you don't already -have them. - -http://tug.org/tds/ contains the current released version. For older -versions, see ftp://tug.org/historic/docs/tds. <!-- For the current -development sources, see http://tds.sarovar.org. --> - -Happy installing. -</pre> diff --git a/tds/README.html b/tds/README.html deleted file mode 120000 index 100b93820a..0000000000 --- a/tds/README.html +++ /dev/null @@ -1 +0,0 @@ -README
\ No newline at end of file diff --git a/tds/tds.aux b/tds/tds.aux deleted file mode 100644 index 5314e41b6b..0000000000 --- a/tds/tds.aux +++ /dev/null @@ -1,61 +0,0 @@ -\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@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@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@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@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}} diff --git a/tds/tds.dvi b/tds/tds.dvi Binary files differdeleted file mode 100644 index ee93dac783..0000000000 --- a/tds/tds.dvi +++ /dev/null diff --git a/tds/tds.html b/tds/tds.html deleted file mode 100644 index 49da35a2f5..0000000000 --- a/tds/tds.html +++ /dev/null @@ -1,1997 +0,0 @@ -<html lang="en"> -<head> -<title>A Directory Structure for TeX Files</title> -<meta http-equiv="Content-Type" content="text/html"> -<meta name="description" content="A Directory Structure for TeX Files"> -<meta name="generator" content="makeinfo 4.7"> -<link title="Top" rel="top" href="#Top"> -<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> -<meta http-equiv="Content-Style-Type" content="text/css"> -<style type="text/css"><!-- - pre.display { font-family:inherit } - pre.format { font-family:inherit } - pre.smalldisplay { font-family:inherit; font-size:smaller } - pre.smallformat { font-family:inherit; font-size:smaller } - pre.smallexample { font-size:smaller } - pre.smalllisp { font-size:smaller } - span.sc { font-variant:small-caps } - span.roman { font-family:serif; font-weight:normal; } ---></style> -</head> -<body> -<h1 class="settitle">A Directory Structure for TeX Files</h1> -<div class="node"> -<p><hr> -<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#Introduction">Introduction</a>, -Up: <a rel="up" accesskey="u" href="#dir">(dir)</a> -<br> -</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@tug.org">tds@tug.org</a>. We welcome all comments. This is version -1.1. - -<ul class="menu"> -<li><a accesskey="1" href="#Introduction">Introduction</a> -<li><a accesskey="2" href="#General">General</a> -<li><a accesskey="3" href="#Top_002dlevel-directories">Top-level directories</a> -<li><a accesskey="4" href="#Summary">Summary</a> -<li><a accesskey="5" href="#Unspecified-pieces">Unspecified pieces</a> -<li><a accesskey="6" href="#Implementation-issues">Implementation issues</a> -<li><a accesskey="7" href="#Is-there-a-better-way_003f">Is there a better way?</a> -<li><a accesskey="8" href="#Related-references">Related references</a> -<li><a accesskey="9" href="#Contributors">Contributors</a> - -</li></ul> -<p>--- The Detailed Node Listing --- - -<p>Introduction - -</p> -<ul class="menu"> -<li><a href="#History">History</a> -<li><a href="#The-role-of-the-TDS">The role of the TDS</a> -<li><a href="#Conventions">Conventions</a> - -</li></ul> -<p>General - -</p> -<ul class="menu"> -<li><a href="#Subdirectory-searching">Subdirectory searching</a> -<li><a href="#Rooting-the-tree">Rooting the tree</a> -<li><a href="#Local-additions">Local additions</a> -<li><a href="#Duplicate-filenames">Duplicate filenames</a> - -</li></ul> -<p>Top-level directories - -</p> -<ul class="menu"> -<li><a href="#Macros">Macros</a> -<li><a href="#Fonts">Fonts</a> -<li><a href="#Non_002dfont-Metafont-files">Non-font Metafont files</a> -<li><a href="#MetaPost">MetaPost</a> -<li><a href="#BibTeX">BibTeX</a> -<li><a href="#Scripts">Scripts</a> -<li><a href="#Documentation">Documentation</a> - -</li></ul> -<p>Macros - -</p> -<ul class="menu"> -<li><a href="#Extensions">Extensions</a> - -</li></ul> -<p>Fonts - -</p> -<ul class="menu"> -<li><a href="#Font-bitmaps">Font bitmaps</a> -<li><a href="#Valid-font-bitmaps">Valid font bitmaps</a> - -</li></ul> -<p>Summary - -</p> -<ul class="menu"> -<li><a href="#Documentation-tree-summary">Documentation tree summary</a> - -</li></ul> -<p>Unspecified pieces - -</p> -<ul class="menu"> -<li><a href="#Portable-filenames">Portable filenames</a> - -</li></ul> -<p>Implementation issues - -</p> -<ul class="menu"> -<li><a href="#Adoption-of-the-TDS">Adoption of the TDS</a> -<li><a href="#More-on-subdirectory-searching">More on subdirectory searching</a> -<li><a href="#Example-implementation_002dspecific-trees">Example implementation-specific trees</a> - -</li></ul> -<p>Example implementation-specific trees - -</p> -<ul class="menu"> -<li><a href="#AmiWeb2c-2_002e0">AmiWeb2c 2.0</a> -<li><a href="#Public-DECUS-TeX">Public DECUS TeX</a> -<li><a href="#Web2c-7">Web2c 7</a> - -</li></ul> -<p>Is there a better way? - -</p> -<ul class="menu"> -<li><a href="#Macro-structure">Macro structure</a> -<li><a href="#Font-structure">Font structure</a> -<li><a href="#Documentation-structure">Documentation structure</a> - -</li></ul> -<p>Font structure - -</p> -<ul class="menu"> -<li><a href="#Font-file-type-location">Font file type location</a> -<li><a href="#Mode-and-resolution-location">Mode and resolution location</a> -<li><a href="#Modeless-bitmaps">Modeless bitmaps</a> - - </ul> - -<div class="node"> -<p><hr> -<a name="Introduction"></a>Next: <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> -<br> -</div> - -<h2 class="chapter">1 Introduction</h2> - -<p>TeX is a powerful, flexible typesetting system used by many people -around the world. It is extremely portable and runs on virtually all -operating systems. One unfortunate side effect of TeX's flexibility, -however, is that there has been no single “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> -<br> -</div> - -<h3 class="section">1.1 History</h3> - -<p>Version 1.0 of the TDS was released in February 2003. - - <p>Version 1.1 was released in June 2004, with the following non-editorial -changes: - - <ul> -<li>Inputs for TeX extensions included under <samp><span class="file">tex</span></samp>, instead - of in their own top-level directories (Section <!-- /@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> -<br> -</div> - -<h3 class="section">1.2 The role of the TDS</h3> - -<p>The role of the TDS is to stabilize the organization of -TeX-related software packages that are installed and in use, possibly -on multiple platforms simultaneously. - - <p>At first glance, it may seem that the Comprehensive TeX Archive -Network (CTAN) fulfills at least part of this role, but this is -not the case. The role of CTAN is to simplify archiving and -distribution, not installation and use. - - <p>In fact, the roles of the TDS and CTAN are frequently in -conflict, as we will see. For distribution, many different types of -files must be combined into a single unit; for use, it is traditional to -segregate files (even similar files) from a single package into -separate, occasionally distant, directories. - -<div class="node"> -<p><hr> -<a name="Conventions"></a>Previous: <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> -<br> -</div> - -<h3 class="section">1.3 Conventions</h3> - -<p>In this document, <samp><span class="file">/</span></samp> is used to separate filename components; -for example, <samp><span class="file">texmf/fonts</span></samp>. This is the Unix convention but the -ideas are in no way Unix-specific. - - <p>In this document, “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> -<br> -</div> - -<h2 class="chapter">2 General</h2> - -<p>This section describes common properties throughout the TDS tree. - -<ul class="menu"> -<li><a accesskey="1" href="#Subdirectory-searching">Subdirectory searching</a> -<li><a accesskey="2" href="#Rooting-the-tree">Rooting the tree</a> -<li><a accesskey="3" href="#Local-additions">Local additions</a> -<li><a accesskey="4" href="#Duplicate-filenames">Duplicate filenames</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Subdirectory-searching"></a>Next: <a rel="next" accesskey="n" href="#Rooting-the-tree">Rooting the tree</a>, -Up: <a rel="up" accesskey="u" href="#General">General</a> -<br> -</div> - -<h3 class="section">2.1 Subdirectory searching</h3> - -<p>Older TeX installations store large numbers of related files in single -directories, for example, all <samp><span class="file">TFM</span></samp> files and/or all TeX -input files. - - <p>This monolithic arrangement hinders maintenance of a TeX system: it -is difficult to determine what files are used by what packages, what -files need to be updated when a new version is installed, or what files -should be deleted if a package is removed. It is also a source of error -if two or more packages happen to have input files with the same name. - - <p>Therefore, the TWG felt each package should be in a separate -directory. But we recognized that explicitly listing all directories to -be searched would be unbearable. A site may wish to install dozens of -packages. Aside from anything else, listing that many directories would -produce search paths many thousands of characters long, overflowing the -available space on some systems. - - <p>Also, if all directories are explicitly listed, installing or removing a -new package would mean changing a path as well as installing or removing -the actual files. This would be a time-consuming and error-prone -operation, even with implementations that provide some way to specify -the directories to search at runtime. On systems without runtime -configuration, it would require recompiling software, an intolerable -burden. - - <p>As a result, the TWG concluded that a comprehensive TDS -requires implementations to support some form of implicit subdirectory -searching. More precisely, implementations must make it possible to -specify that TeX, Metafont, and their companion utilities search in both -a specified directory and recursively through all subdirectories of that -directory when looking for an input file. Other forms of subdirectory -searching, for example recursive-to-one-level searches, may also be -provided. We encourage implementors to provide subdirectory searching -at the option of the installer and user for all paths. - - <p>The TDS does not specify a syntax for specifying recursive -searching, but we encourage implementors to provide interoperability -(see Section <!-- /@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> -<br> -</div> - -<h3 class="section">2.2 Rooting the tree</h3> - -<p>In this document, we shall designate the root TDS directory by -<samp><span class="file">texmf</span></samp> (for “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> -<br> -</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> -<br> -</div> - -<h3 class="section">2.4 Duplicate filenames</h3> - -<p>Different files by the same name may exist in a TDS tree. The -TDS generally leaves unspecified which of two files by the same -name in a search path will be found, so generally the only way to -reliably find a given file is for it to have a unique name. However, -the TDS requires implementations to support the following -exceptions: - - <ul> -<li>Names of TeX input files must be unique within each first-level -subdirectory of <samp><span class="file">texmf/tex</span></samp> and <samp><span class="file">texmf/tex/generic</span></samp>, but not -within all of <samp><span class="file">texmf/tex</span></samp>; i.e., different TeX formats may have -files by the same name. (Section <!-- /@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_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> -<br> -</div> - -<h2 class="chapter">3 Top-level directories</h2> - -<p>The directories under the <samp><span class="file">texmf</span></samp> root identify the major components of -a TeX system (see Section <!-- /@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> -<br> -</div> - -<h3 class="section">3.1 Macros</h3> - -<p>TeX macro files shall be stored in separate directories, segregated -by TeX format and package name (we use `format' in its traditional -TeX sense to mean a usefully <samp><span class="file">\dump</span></samp>-able package): -<pre class="example"> texmf/tex/<var>format</var>/<var>package</var>/ -</pre> - <ul> -<li>`<samp><var>format</var></samp>' -is a format name (examples: <samp><span class="file">amstex</span></samp>, -<samp><span class="file">latex</span></samp>, <samp><span class="file">plain</span></samp>, <samp><span class="file">texinfo</span></samp>). - - <p>The TDS allows distributions that can be used as either formats or -packages (e.g., Texinfo, Eplain) to be stored at either level, at the -option of the format author or TeX administrator. We recommend that -packages used as formats at a particular site be stored at the -<samp><var>format</var></samp> level: by adjusting the TeX inputs search path, -it will be straightforward to use them as macro packages under another -format, whereas placing them in another tree completely obscures their -use as a format. - - <p>The TDS reserves the following <samp><var>format</var></samp> names: - - <ul> -<li>`<samp><span class="samp">generic</span></samp>', -for input files that are useful across a wide -range of formats (examples: <samp><span class="file">null.tex</span></samp>, <samp><span class="file">path.sty</span></samp>). -Generally, this means any format that uses the category codes of Plain -TeX and does not rely on any particular format. This is in contrast -to those files which are useful only with Plain TeX (which go under -<samp><span class="file">texmf/tex/plain</span></samp>), e.g., <samp><span class="file">testfont.tex</span></samp> and <samp><span class="file">plain.tex</span></samp> -itself. - - <li>`<samp><span class="samp">local</span></samp>', -for local additions. See Section <!-- /@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> -<br> -</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> -<br> -</div> - -<h3 class="section">3.2 Fonts</h3> - -<p>Font files are stored in separate directories, segregated by file type, -and then (in most cases) font supplier and typeface. PK and -GF files need additional structure, as detailed in the next -section. - -<pre class="example"> texmf/fonts/<var>type</var>/<var>supplier</var>/<var>typeface</var>/ - texmf/fonts/enc,lig,map/<var>subpath</var>/ -</pre> - <ul> -<li>`<samp><var>type</var></samp>' -is the type of font file. The TDS -reserves the following <samp><var>type</var></samp> names for common TeX file -types: - - <ul> -<li>`<samp><span class="samp">afm</span></samp>', -for Adobe font metrics, and <samp><span class="file">inf</span></samp> files. -<li>`<samp><span class="samp">gf</span></samp>', -for generic font bitmap files. -<li>`<samp><span class="samp">opentype</span></samp>', -for OpenType fonts. -<li>`<samp><span class="samp">pk</span></samp>', -for packed bitmap files. -<li>`<samp><span class="samp">source</span></samp>', -for font sources (Metafont files, property lists, etc.). -<li>`<samp><span class="samp">tfm</span></samp>', -for TeX font metric files. -<li>`<samp><span class="samp">truetype</span></samp>', -for TrueType fonts. -<li>`<samp><span class="samp">type1</span></samp>', -for PostScript Type 1 fonts (in <samp><span class="file">pfa</span></samp>, - <samp><span class="file">pfb</span></samp>, or any other format), and <samp><span class="file">pfm</span></samp> files. -<li>`<samp><span class="samp">type3</span></samp>', -for PostScript Type 3 fonts. -<li>`<samp><span class="samp">vf</span></samp>', -for virtual fonts. -</ul> - - <p>The TDS also reserves the names <samp><span class="file">enc</span></samp>, <samp><span class="file">lig</span></samp>, and -<samp><span class="file">map</span></samp> for font encoding, ligature, and mapping files, respectively. -All of these directories are structured the same way, with -<samp><var>syntax</var></samp> subdirectories, and then <samp><var>package</var></samp> -subsubdirectories. Each of these file types is intended to be searched -along its own recursively-searched path. The names of the actual files -must be unique within their subtree, as usual. Examples: - <pre class="example"> fonts/map/dvipdfm/updmap/dvipdfm.map - fonts/map/dvips/lm/lm.map - fonts/enc/dvips/base/8r.enc - </pre> - <p>The Fontname and Dvips packages have more examples of the <samp><span class="file">enc</span></samp> and -<samp><span class="file">map</span></samp> types. The <samp><span class="file">afm2pl</span></samp> program uses <samp><span class="file">lig</span></samp> files. - - <p><samp><span class="file">pfm</span></samp> files are included in the <samp><span class="file">type1</span></samp> directory, instead of -being given their own directory, for two reasons: 1) <!-- /@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> -<br> -</div> - -<h4 class="subsection">3.2.1 Font bitmaps</h4> - -<p>Font bitmap files require two characteristics in addition to the above -to be uniquely identifiable: (1) <!-- /@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> -<br> -</div> - -<h4 class="subsection">3.2.2 Valid font bitmaps</h4> - -<p>The TWG recognizes that the use of short filenames has many -disadvantages. The most vexing is that it results in the creation of -dozens of different files with the same name. At a typical site, -<samp><span class="file">cmr10.pk</span></samp> will be the filename for Computer Modern Roman 10<span class="dmn">pt</span> at -5–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_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> -<br> -</div> - -<h3 class="section">3.3 Non-font Metafont files</h3> - -<p>Most Metafont input files are font programs or parts of font programs and -are thus covered by the previous section. However, a few non-font input -files do exist. Such files shall be stored in: - -<pre class="example"> texmf/metafont/<var>package</var>/ -</pre> - <p><samp><var>package</var></samp> is the name of a -Metafont package (for example, <samp><span class="file">mfpic</span></samp>). - - <p>The TDS reserves the following <samp><var>package</var></samp> names: - - <ul> -<li>`<samp><span class="samp">base</span></samp>', -for the standard Metafont macro files as described in -<cite>The Metafontbook</cite>, such as <samp><span class="file">plain.mf</span></samp> and <samp><span class="file">expr.mf</span></samp>. - - <li>`<samp><span class="samp">local</span></samp>', -for local additions. See Section <!-- /@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> -<br> -</div> - -<h3 class="section">3.4 MetaPost</h3> - -<p>MetaPost is a picture-drawing language developed by John Hobby, derived -from Knuth's Metafont. Its primary purpose is to output Encapsulated PostScript -instead of bitmaps. - - <p>MetaPost input files and the support files for MetaPost-related utilities -shall be stored in: - -<pre class="example"> texmf/metapost/<var>package</var>/ -</pre> - <p><samp><var>package</var></samp> is the name of a MetaPost package. At the present -writing none exist, but the TWG thought it prudent to leave room -for contributed packages that might be written in the future. - - <p>The TDS reserves the following <samp><var>package</var></samp> names: - - <ul> -<li>`<samp><span class="samp">base</span></samp>', -for the standard MetaPost macro files, such as -<samp><span class="file">plain.mp</span></samp>, <samp><span class="file">mfplain.mp</span></samp>, <samp><span class="file">boxes.mp</span></samp>, and -<samp><span class="file">graph.mp</span></samp>. This includes files used by INIMP when dumping mem -files containing preloaded macro definitions. - - <li>`<samp><span class="samp">local</span></samp>', -for local additions. See Section <!-- /@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> -<br> -</div> - -<h3 class="section">3.5 BibTeX</h3> - -<p>BibTeX-related files shall be stored in: - -<pre class="example"> texmf/bibtex/bib/<var>package</var>/ - texmf/bibtex/bst/<var>package</var>/ -</pre> - <p>The <samp><span class="file">bib</span></samp> directory is for BibTeX database (<samp><span class="file">.bib</span></samp>) files, -the <samp><span class="file">bst</span></samp> directory for style (<samp><span class="file">.bst</span></samp>) files. - - <p><samp><var>package</var></samp> is the name of a BibTeX package. The -TDS reserves the following <samp><var>package</var></samp> names (the same -names are reserved under both <samp><span class="file">bib</span></samp> and <samp><span class="file">bst</span></samp>): - - <ul> -<li>`<samp><span class="samp">base</span></samp>', -for the standard BibTeX databases and styles, such -as <samp><span class="file">xampl.bib</span></samp>, <samp><span class="file">plain.bst</span></samp>. - - <li>`<samp><span class="samp">local</span></samp>', -for local additions. See Section <!-- /@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> -<br> -</div> - -<h3 class="section">3.6 Scripts</h3> - -<p>The top-level <samp><span class="file">scripts</span></samp> directory is for platform-independent -executables, such as Perl, Python, and shell scripts, and Java class -files. Subdirectories under <samp><span class="file">scripts</span></samp> are package names. This -eases creating distributions, by providing a common place for such -platform-independent programs. - - <p>The intent is not for all such directories to be added to a user's -command search path, which would be quite impractical. Rather, these -executables are primarily for the benefit of wrapper scripts in whatever -executable directory a distribution may provide (which is not specified -by the TDS). - - <p>Truly auxiliary scripts which are invoked directly by other programs, -rather than wrapper scripts, may also be placed here. That is, -<samp><span class="file">scripts</span></samp> also serves as a platform-independent analog of the -standard Unix <samp><span class="file">libexec</span></samp> directory. - - <p>We recommend using extensions specifying the language (such as -<samp><span class="file">.pl</span></samp>, <samp><span class="file">.py</span></samp>, <samp><span class="file">.sh</span></samp>) on these files, to help uniquely -identify the name. Since the intent of the TDS is for programs -in <samp><span class="file">scripts</span></samp> not to be invoked directly by users, this poses no -inconvenience. - - <p>For example, in the TeX Live distribution, the ConTeXt user-level -program <samp><span class="file">texexec</span></samp> can exist as a small wrapper script in each -<samp><span class="file">bin/</span><var>platform</var><span class="file">/texexec</span></samp> (which is outside the -<samp><span class="file">texmf</span></samp> tree), which merely finds and calls -<samp><span class="file">texmf/scripts/context/perl/texexec.pl</span></samp>. - - <p>Examples: -<pre class="example"> scripts/context/perl/texexec.pl - scripts/context/ruby/examplex.rb - scripts/thumbpdf/thumbpdf.pl -</pre> - <p>The TDS does not specify a location for platform-dependent -binary executables, whether auxiliary or user-level. - -<div class="node"> -<p><hr> -<a name="Documentation"></a>Previous: <a rel="previous" accesskey="p" href="#Scripts">Scripts</a>, -Up: <a rel="up" accesskey="u" href="#Top_002dlevel-directories">Top-level directories</a> -<br> -</div> - -<h3 class="section">3.7 Documentation</h3> - -<p>Most packages come with some form of documentation: user manuals, -example files, programming guides, etc. In addition, many independent -files not part of any macro or other package have been created to -describe various aspects of the TeX system. - - <p>The TDS specifies that these additional documentation files shall -be stored in a structure that parallels to some extent the -<samp><span class="file">fonts</span></samp> and <samp><span class="file">tex</span></samp> directories, as follows: - -<pre class="example"> texmf/doc/<var>category</var>/... -</pre> - <p><samp><var>category</var></samp> identifies the general topic of documentation -that resides below it; for example, a TeX format name (<samp><span class="file">latex</span></samp>), -program name (<samp><span class="file">bibtex</span></samp>, <samp><span class="file">tex</span></samp>), language (<samp><span class="file">french</span></samp>, -<samp><span class="file">german</span></samp>), a file format (<samp><span class="file">info</span></samp>, <samp><span class="file">man</span></samp>), or other system -components (<samp><span class="file">web</span></samp>, <samp><span class="file">fonts</span></samp>). - - <p>One possible arrangement is to organize <samp><span class="file">doc</span></samp> by language, with all -the other category types below that. This helps users find -documentation in the language(s) in which they are fluent. Neither this -nor any other particular arrangement is required, however. - - <p>Within each <samp><var>category</var></samp> tree for a TeX format, the -directory <samp><span class="file">base</span></samp> is reserved for base documentation distributed by -the format's maintainers. - - <p>The TDS reserves the following category names: - - <ul> -<li>`<samp><span class="samp">general</span></samp>', -for standalone documents not specific to any -particular program (for example, Joachim Schrod's <cite>Components -of TeX</cite>). - - <li>`<samp><span class="samp">help</span></samp>', -for meta-information, such as FAQ's, -the TeX Catalogue, etc. - - <li>`<samp><span class="samp">info</span></samp>', -for processed Texinfo documents. (Info files, like -anything else, may also be stored outside the TDS, at the -installer's option.) - - <li>`<samp><span class="samp">local</span></samp>', -for local additions. See Section <!-- /@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> -<br> -</div> - -<h2 class="chapter">4 Summary</h2> - -<p>A skeleton of a TDS <samp><span class="file">texmf</span></samp> directory tree. This is not to -imply these are the only entries allowed. For example, <samp><span class="file">local</span></samp> may -occur at any level. - -<pre class="example"> bibtex/ BibTeX input files - bib/ BibTeX databases - base/ base distribution (e.g., <samp><span class="file">xampl.bib</span></samp>) - misc/ single-file databases - <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> -<br> -</div> - -<h3 class="section">4.1 Documentation tree summary</h3> - -<p>An example skeleton of a TDS directory tree under -<samp><span class="file">texmf/doc</span></samp>. This is not to imply these are the only entries -allowed, or that this structure must be followed precisely for the -entries listed. - - <p>As mentioned, the <samp><span class="file">texmf/doc</span></samp> tree may be organized by language, so -that all documentation in French, say, is in a <samp><span class="file">french</span></samp> -subdirectory. In that case, the example structure here would be in a -given language directory. - -<pre class="example"> ams/ - amsfonts/ <samp><span class="file">amsfonts.faq</span></samp>, <samp><span class="file">amfndoc</span></samp> - amslatex/ <samp><span class="file">amslatex.faq</span></samp>, <samp><span class="file">amsldoc</span></samp> - amstex/ <samp><span class="file">amsguide</span></samp>, <samp><span class="file">joyerr</span></samp> - bibtex/ BibTeX - base/ <samp><span class="file">btxdoc.tex</span></samp> - fonts/ - fontname/ <cite>Filenames for TeX fonts</cite> - oldgerm/ <samp><span class="file">corkpapr</span></samp> - <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> -<br> -</div> - -<h2 class="appendix">Appendix A Unspecified pieces</h2> - -<p>The TDS cannot address the following aspects of a functioning -TeX system: - - <ol type=1 start=1> - - <li>The location of executable programs: this is too site-dependent -even to recommend a location, let alone require one. A site may place -executables outside the <samp><span class="file">texmf</span></samp> tree altogether (e.g., -<samp><span class="file">/usr/local/bin</span></samp>), in a platform-dependent directory within -<samp><span class="file">texmf</span></samp>, or elsewhere. - - <li>Upgrading packages when new releases are made: we could find no -way of introducing version specifiers into <samp><span class="file">texmf</span></samp> that would do more -good than harm, or that would be practical for even a plurality of -installations. - - <li>The location of implementation-specific files (e.g., TeX -<samp><span class="file">.fmt</span></samp> files): by their nature, these must be left to the -implementor or TeX maintainer. See Section <!-- /@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> -<br> -</div> - -<h3 class="section">A.1 Portable filenames</h3> - -<p>The TDS cannot require any particular restriction on filenames in -the tree, since the names of many existing TeX files conform to no -standard scheme. For the benefit of people who wish to make a portable -TeX distribution or installation, however, we outline here the -necessary restrictions. The TDS specifications themselves are -compatible with these. - - <p>ISO-9660 is the only universally acceptable file system format -for CD-ROMs. A subset thereof meets the stringent limitations of -all operating systems in use today. It specifies the following: - - <ul> -<li>File and directory names, not including any directory path or -extension part, may not exceed eight characters. - - <li>Filenames may have a single extension. Extensions may not exceed -three characters. Directory names may not have an extension. - - <li>Names and extensions may consist of <em>only</em> the characters -<samp><span class="file">A</span></samp>–<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> -<br> -</div> - -<h2 class="appendix">Appendix B Implementation issues</h2> - -<p>We believe that the TDS can bring a great deal of order to the -current anarchic state of many TeX installations. In addition, by -providing a common frame of reference, it will ease the burden of -documenting administrative tasks. Finally, it is a necessary part of -any reasonable system of true “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> -<br> -</div> - -<h3 class="section">B.1 Adoption of the TDS</h3> - -<p>[This section is retained for historical purposes; the TDS -is now quite firmly entrenched in most TeX distributions.] - - <p>We recognize that adoption of the TDS will not be immediate or -universal. Most TeX administrators will not be inclined to make the -final switch until: - - <ul> -<li>Clear and demonstrable benefits can be shown for the TDS. -<li>TDS-compliant versions of all key programs are available -in ported, well-tested forms. -<li>A “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> -<br> -</div> - -<h3 class="section">B.2 More on subdirectory searching</h3> - -<p>Recursive subdirectory searching is the ability to specify a search not -only of a specified directory <samp><var>d</var></samp>, but recursively of all -directories below <samp><var>d</var></samp>. - - <p>Since the TDS specifies precise locations for most files, with no -extra levels of subdirectories allowed, true recursive searching is not -actually required for a TDS-compliant implementation. We do, -however, strongly recommend recursive searching as the most -user-friendly and natural approach to the problem, rather than -convoluted methods to specify paths without recursion. - - <p>This feature is already supported by many implementations of TeX and -companion utilities, for example DECUS TeX for VMS, -Dvips(k), emTeX (and its drivers), -PubliC TeX, Web2C, Xdvi(k), -and Y&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_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> -<br> -</div> - -<h3 class="section">B.3 Example implementation-specific trees</h3> - -<p>The TDS cannot specify a precise location for -implementation-specific files, such as <samp><span class="file">texmf/ini</span></samp>, because a site -may have multiple TeX implementations. - - <p>Nevertheless, for informative purposes, we provide here the default -locations for some implementations. Please contact us with additions or -corrections. These paths are not definitive, may not match anything at -your site, and may change without warning. - - <p>We recommend all implementations have default search paths that start -with the current directory (e.g., <samp><span class="file">.</span></samp>). Allowing users to -include the parent directory (e.g., <samp><span class="file">..</span></samp>) is also helpful. - -<ul class="menu"> -<li><a accesskey="1" href="#AmiWeb2c-2_002e0">AmiWeb2c 2.0</a> -<li><a accesskey="2" href="#Public-DECUS-TeX">Public DECUS TeX</a> -<li><a accesskey="3" href="#Web2c-7">Web2c 7</a> -</ul> - -<div class="node"> -<p><hr> -<a name="AmiWeb2c-2_002e0"></a>Next: <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> -<br> -</div> - -<h4 class="subsection">B.3.1 AmiWeb2c 2.0</h4> - -<p>(Email <a href="mailto:scherer@physik.rwth-aachen.de">scherer@physik.rwth-aachen.de</a> to contact the maintainer -of this implementation.) - - <p>AmiWeb2c 2 is compatible with Web2c 7 to the greatest possible -extent, so only the very few differences are described in this -section. Detailed information about the basic concepts is given in -the section for Web2c 7 below. - - <p>Thanks to the <samp><span class="file">SELFAUTO</span></samp> mechanism of Kpathsea 3.0 no specific -location for the installation of AmiWeb2c is required as long as the -general structure of the distribution is preserved. - - <p>In addition to Kpathsea's <samp><span class="file">//</span></samp> notation recursive path search may -also be started by <samp><var>DEVICE</var><span class="file">:/</span></samp>, e.g., <samp><span class="file">TeXMF:/</span></samp> -will scan this specific device completely. - - <p>Binaries coming with the AmiWeb2c distribution are installed in the -directory <samp><span class="file">bin/amiweb2c/</span></samp> outside the common TDS tree -<samp><span class="file">share/texmf/</span></samp>. In addition to the set of AmiWeb2c binaries -you will find two subdirectories <samp><span class="file">local/</span></samp> and <samp><span class="file">pastex/</span></samp> -with auxiliary programs. - - <p>A stripped version of the PasTeX system (used by kind permission of -Georg Heß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> -<br> -</div> - -<h4 class="subsection">B.3.2 Public DECUS TeX</h4> - -<p>If another VMS implementation besides Public DECUS TeX -appears, the top level implementation directory name will be modified to -something more specific (e.g., <samp><span class="file">vms_decus</span></samp>). - -<pre class="example"> texmf/ - vms/ VMS implementation specific files - exe/ end-user commands - common/ command procedures, command definition files, etc. - axp/ binary executables for Alpha AXP - vax/ binary executables for VAX - formats/ pool files, formats, bases - help/ VMS help library, and miscellaneous help sources - mgr/ command procedures, programs, docs, etc., for system management -</pre> - <div class="node"> -<p><hr> -<a name="Web2c-7"></a>Previous: <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> -<br> -</div> - -<h4 class="subsection">B.3.3 Web2c 7</h4> - -<p>All implementation-dependent TeX system files (<samp><span class="file">.pool</span></samp>, -<samp><span class="file">.fmt</span></samp>, <samp><span class="file">.base</span></samp>, <samp><span class="file">.mem</span></samp>) are stored by default directly -in <samp><span class="file">texmf/web2c</span></samp>. The configuration file <samp><span class="file">texmf.cnf</span></samp> and -various subsidiary <samp><span class="file">MakeTeX...</span></samp> scripts used as subroutines are -also stored there. - - <p>Non-TeX specific files are stored following the GNU coding -standards. Given a root directory <samp><var>prefix</var></samp> -(<samp><span class="file">/usr/local</span></samp> by default), we have default locations as follows: - -<pre class="example"> <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_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> -<br> -</div> - -<h2 class="appendix">Appendix C Is there a better way?</h2> - -<p>Defining the TDS required many compromises. Both the overall -structure and the details of the individual directories were arrived at -by finding common ground among many opinions. The driving forces were -feasibility (in terms of what could technically be done and what could -reasonably be expected from developers) and regularity (files grouped -together in an arrangement that “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> -<br> -</div> - -<h3 class="section">C.1 Macro structure</h3> - -<p>The TWG settled on the -<samp><var>format</var><span class="file">/</span><var>package</var></samp> arrangement after long -discussion about how best to arrange the files. - - <p>The primary alternative to this arrangement was a scheme which reversed -the order of these directories: -<samp><var>package</var><span class="file">/</span><var>format</var></samp>. This reversed -arrangement has a strong appeal: it keeps all of the files related to a -particular package in a single place. The arrangement actually adopted -tends to spread files out into two or three places (macros, -documentation, and fonts, for example, are spread into different -sections of the tree right at the top level). - - <p>Nevertheless, the <samp><var>format</var><span class="file">/</span><var>package</var></samp> -structure won for a couple of reasons: - - <ul> -<li>It is closer to current practice; in fact, several members of the -TWG have already implemented the TDS hierarchy. The -alternative is not in use at any known site, and the TWG felt it -wrong to mandate something with which there is no practical experience. - - <li>The alternative arrangement increases the number of top-level -directories, so the files that must be found using subdirectory -searching are spread out in a wide, shallow tree. This could have a -profound impact on the efficiency of subdirectory searching. - - </ul> - -<div class="node"> -<p><hr> -<a name="Font-structure"></a>Next: <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> -<br> -</div> - -<h3 class="section">C.2 Font structure</h3> - -<p>The TWG struggled more with the font directory structure than -anything else. This is not surprising; the need to use the proliferation -of PostScript fonts with TeX is what made the previous arrangement -with all files in a single directory untenable, and therefore what -initiated the TDS effort. - -<ul class="menu"> -<li><a accesskey="1" href="#Font-file-type-location">Font file type location</a> -<li><a accesskey="2" href="#Mode-and-resolution-location">Mode and resolution location</a> -<li><a accesskey="3" href="#Modeless-bitmaps">Modeless bitmaps</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Font-file-type-location"></a>Next: <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> -<br> -</div> - -<h4 class="subsection">C.2.1 Font file type location</h4> - -<p>We considered the supplier-first arrangement in use at many sites: - -<pre class="example"> texmf/fonts/<var>supplier</var>/<var>typeface</var>/<var>type</var>/ -</pre> - <p>This improves the maintainability of the font tree, since all files -comprising a given typeface are in one place, but unless all the -programs that search this tree employ some form of caching, there are -serious performance concerns. For example, in order to find a -<samp><span class="file">TFM</span></samp> file, the simplest implementation would require TeX to -search through all the directories that contain PK files in all -modes and at all resolutions. - - <p>In the end, a poll of developers revealed considerable resistance to -implementing sufficient caching mechanisms, so this arrangement was -abandoned. The TDS arrangement allows the search tree to be -restricted to the correct type of file, at least. Concerns about -efficiency remain, but there seems to be no more we can do without -abandoning subdirectory searching entirely. - - <p>We also considered segregating all font-related files strictly by file -type, so that Metafont sources would be in a directory -<samp><span class="file">texmf/fonts/mf</span></samp>, property list files in <samp><span class="file">texmf/fonts/pl</span></samp>, the -various forms of Type <!-- /@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> -<br> -</div> - -<h4 class="subsection">C.2.2 Mode and resolution location</h4> - -<p>We considered having the <samp><span class="file">mode</span></samp> at the bottom of the font tree: -<pre class="example"> texmf/fonts/pk/<var>supplier</var>/<var>typeface</var>/<var>mode</var>/<var>dpi</var>/ -</pre> - <p>In this case, however, it is difficult to limit subdirectory searching -to the mode required for a particular device. - - <p>We then considered moving the <samp><span class="file">dpi</span><var>nnn</var></samp> up to below -the mode: -<pre class="example"> texmf/fonts/pk/<var>mode</var>/<var>dpi</var>/<var>supplier</var>/<var>typeface</var>/ -</pre> - <p>But then it is not feasible to omit the <samp><span class="file">dpi</span><var>nnn</var></samp> -level altogether on systems which can and do choose to use long -filenames. - -<div class="node"> -<p><hr> -<a name="Modeless-bitmaps"></a>Previous: <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> -<br> -</div> - -<h4 class="subsection">C.2.3 Modeless bitmaps</h4> - -<p>The TDS specifies using a single directory <samp><span class="file">modeless/</span></samp> as -the mode name for those utilities which generate bitmaps, e.g., -<samp><span class="file">texmf/fonts/modeless/times/</span></samp>. This has the considerable advantage -of not requiring each such directory name to be listed in a search path. - - <p>An alternative was to use the utility name below which all such -directories could be gathered. That has the advantage of separating, -say, <samp><span class="file">gsftopk</span></samp>-generated bitmaps from <samp><span class="file">ps2pk</span></samp>-generated ones. -However, we decided this was not necessary; most sites will use only one -program for the purpose. Also, PK and GF fonts generally -identify their creator in the font comment following the <samp><span class="file">PK_ID</span></samp> -byte. - - <p>We are making an implicit assumption that Metafont is the only program -producing mode-dependent bitmaps. If this becomes false we could add an -abbreviation for the program to mode names, as in <samp><span class="file">mfcx</span></samp> vs. -<samp><span class="file">xyzcx</span></samp> for a hypothetical program Xyz, or we could -at that time add an additional program name level uniformly to the tree. -It seemed more important to concisely represent the current situation -than to worry about hypothetical possibilities that may never <!-- /@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> -<br> -</div> - -<h3 class="section">C.3 Documentation structure</h3> - -<p>We considered placing additional documentation files in the same -directory as the source files for the packages, but we felt that users -should be able to find documentation separately from sources, since most -users have no interest in sources. - - <p>We hope that a separate, but parallel, structure for documentation would -(1) <!-- /@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> -<br> -</div> - -<h2 class="appendix">Appendix D Related references</h2> - -<p>This appendix gives pointers to related files and other documents. For -CTAN references, we use <samp><span class="file">http://www.ctan.org</span></samp> as the -top-level domain only to make the links be live in this document. See -<a href="http://www.ctan.org/tex-archive/CTAN.sites">http://www.ctan.org/tex-archive/CTAN.sites</a> for a complete list of -CTAN sites; there are mirrors worldwide. - - <ul> -<li>This document, in many formats (tex, dvi, info, pdf):<br> -<a href="http://tug.org/tds/">http://tug.org/tds/</a> - - <li>The TDS mailing list archives:<br> -<a href="http://tug.org/mail-archives/twg-tds/">http://tug.org/mail-archives/twg-tds/</a> - - <li>The level <!-- /@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> -<br> -</div> - -<h2 class="appendix">Appendix E Contributors</h2> - -<p>The TWG has had no physical meetings; electronic mail was the -communication medium. - - <p>Sebastian Rahtz is the TeX Users Group Technical Council liaison. -Norman Walsh was the original committee chair. Karl Berry is the -current editor. - - <p>The list of contributors has grown too large to fairly include, as some -would surely be inadvertently omitted. Please consider the archives of -the <a href="mailto:tds@tug.org">tds@tug.org</a> and <a href="mailto:tex-live@tug.org">tex-live@tug.org</a> mailing lists as -the record of contributions. - -</body></html> - diff --git a/tds/tds.info b/tds/tds.info deleted file mode 100644 index 8b2418cd0a..0000000000 --- a/tds/tds.info +++ /dev/null @@ -1,1714 +0,0 @@ -This is tds.info, produced by makeinfo version 4.7 from tds.texi. - -INFO-DIR-SECTION TeX -START-INFO-DIR-ENTRY -* TeX Directories: (tds). A directory structure for TeX files. -END-INFO-DIR-ENTRY - - -File: tds.info, Node: Top, Next: Introduction, Up: (dir) - -A Directory Structure for TeX Files -*********************************** - -Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2003, 2004 TeX Users -Group. - - Permission to use, copy, and distribute this document _without -modification_ for any purpose and without fee is hereby granted, -provided that this notice appears in all copies. It is provided "as -is" without expressed or implied warranty. - - Permission is granted to copy and distribute modified versions of -this document under the conditions for verbatim copying, provided that -the modifications are clearly marked and the document is not -represented as the official one. - - This document is available on any CTAN host (see Appendix *Note -Related references::). Please send questions or suggestions by email to -<tds@tug.org>. We welcome all comments. This is version 1.1. - -* Menu: - -* Introduction:: -* General:: -* Top-level directories:: -* Summary:: -* Unspecified pieces:: -* Implementation issues:: -* Is there a better way?:: -* Related references:: -* Contributors:: - - --- The Detailed Node Listing --- - -Introduction - -* History:: -* The role of the TDS:: -* Conventions:: - -General - -* Subdirectory searching:: -* Rooting the tree:: -* Local additions:: -* Duplicate filenames:: - -Top-level directories - -* Macros:: -* Fonts:: -* Non-font Metafont files:: -* MetaPost:: -* BibTeX:: -* Scripts:: -* Documentation:: - -Macros - -* Extensions:: - -Fonts - -* Font bitmaps:: -* Valid font bitmaps:: - -Summary - -* Documentation tree summary:: - -Unspecified pieces - -* Portable filenames:: - -Implementation issues - -* Adoption of the TDS:: -* More on subdirectory searching:: -* Example implementation-specific trees:: - -Example implementation-specific trees - -* AmiWeb2c 2.0:: -* Public DECUS TeX:: -* Web2c 7:: - -Is there a better way? - -* Macro structure:: -* Font structure:: -* Documentation structure:: - -Font structure - -* Font file type location:: -* Mode and resolution location:: -* Modeless bitmaps:: - - -File: tds.info, Node: Introduction, Next: General, Prev: Top, Up: Top - -1 Introduction -************** - -TeX is a powerful, flexible typesetting system used by many people -around the world. It is extremely portable and runs on virtually all -operating systems. One unfortunate side effect of TeX's flexibility, -however, is that there has been no single "right" way to install it. -This has resulted in many sites having different installed arrangements. - - The primary purpose of this document is to describe a standard TeX -Directory Structure (TDS): a directory hierarchy for macros, fonts, and -the other implementation-independent TeX system files. As a matter of -practicality, this document also suggests ways to incorporate the rest -of the TeX files into a single structure. The TDS has been designed to -work on all modern systems. In particular, the Technical Working Group -(TWG) believes it is usable under MacOS, MS-DOS, OS/2, Unix, VMS, and -Windows NT. We hope that administrators and developers of both free -and commercial TeX implementations will adopt this standard. - - This document is intended both for the TeX system administrator at a -site and for people preparing TeX distributions--everything from a -complete runnable system to a single macro or style file. It may also -help TeX users find their way around systems organized this way. It is -not a tutorial: we necessarily assume knowledge of the many parts of a -working TeX system. If you are unfamiliar with any of the programs or -file formats we refer to, consult the references in Appendix *Note -Related references::. - -* Menu: - -* History:: -* The role of the TDS:: -* Conventions:: - - -File: tds.info, Node: History, Next: The role of the TDS, Up: Introduction - -1.1 History -=========== - -Version 1.0 of the TDS was released in February 2003. - - Version 1.1 was released in June 2004, with the following -non-editorial changes: - - * Inputs for TeX extensions included under `tex', instead of - in their own top-level directories (Section *Note Extensions::) - - * New top-level directory `scripts' (Section *Note Scripts::). - - * New subdirectories `lig', `opentype', `truetype', and - `type3' under `fonts' (Section *Note Fonts::). - - * `enc', `lig', and `map' all use `SYNTAX/PACKAGE' - subdirectories (Section *Note Fonts::). - - * `pfm' files specified to go under `type1', and `inf' files - under `afm' (Section *Note Fonts::). - - -File: tds.info, Node: The role of the TDS, Next: Conventions, Prev: History, Up: Introduction - -1.2 The role of the TDS -======================= - -The role of the TDS is to stabilize the organization of TeX-related -software packages that are installed and in use, possibly on multiple -platforms simultaneously. - - At first glance, it may seem that the Comprehensive TeX Archive -Network (CTAN) fulfills at least part of this role, but this is not the -case. The role of CTAN is to simplify archiving and distribution, not -installation and use. - - In fact, the roles of the TDS and CTAN are frequently in conflict, -as we will see. For distribution, many different types of files must -be combined into a single unit; for use, it is traditional to segregate -files (even similar files) from a single package into separate, -occasionally distant, directories. - - -File: tds.info, Node: Conventions, Prev: The role of the TDS, Up: Introduction - -1.3 Conventions -=============== - -In this document, `/' is used to separate filename components; for -example, `texmf/fonts'. This is the Unix convention but the ideas are -in no way Unix-specific. - - In this document, "TeX" generally means the TeX system, including -Metafont, DVI drivers, utilities, etc., not just the TeX program itself. - - The word "package" in this document has its usual meaning: a set of -related files distributed, installed, and maintained as a unit. This is -_not_ a LaTeX2e package, which is a style file supplementing a document -class. - - We use the following typographic conventions: - - * `literal' Literal text such as `filename' is typeset in typewriter - type. - - * `REPLACEABLE' Replaceable text such as `PACKAGE', identifying a - class of things, is typeset in italics inside angle brackets. - - - -File: tds.info, Node: General, Next: Top-level directories, Prev: Introduction, Up: Top - -2 General -********* - -This section describes common properties throughout the TDS tree. - -* Menu: - -* Subdirectory searching:: -* Rooting the tree:: -* Local additions:: -* Duplicate filenames:: - - -File: tds.info, Node: Subdirectory searching, Next: Rooting the tree, Up: General - -2.1 Subdirectory searching -========================== - -Older TeX installations store large numbers of related files in single -directories, for example, all `TFM' files and/or all TeX input files. - - This monolithic arrangement hinders maintenance of a TeX system: it -is difficult to determine what files are used by what packages, what -files need to be updated when a new version is installed, or what files -should be deleted if a package is removed. It is also a source of error -if two or more packages happen to have input files with the same name. - - Therefore, the TWG felt each package should be in a separate -directory. But we recognized that explicitly listing all directories to -be searched would be unbearable. A site may wish to install dozens of -packages. Aside from anything else, listing that many directories would -produce search paths many thousands of characters long, overflowing the -available space on some systems. - - Also, if all directories are explicitly listed, installing or -removing a new package would mean changing a path as well as installing -or removing the actual files. This would be a time-consuming and -error-prone operation, even with implementations that provide some way -to specify the directories to search at runtime. On systems without -runtime configuration, it would require recompiling software, an -intolerable burden. - - As a result, the TWG concluded that a comprehensive TDS requires -implementations to support some form of implicit subdirectory -searching. More precisely, implementations must make it possible to -specify that TeX, Metafont, and their companion utilities search in both -a specified directory and recursively through all subdirectories of that -directory when looking for an input file. Other forms of subdirectory -searching, for example recursive-to-one-level searches, may also be -provided. We encourage implementors to provide subdirectory searching -at the option of the installer and user for all paths. - - The TDS does not specify a syntax for specifying recursive -searching, but we encourage implementors to provide interoperability -(see Section *Note More on subdirectory searching::). - - -File: tds.info, Node: Rooting the tree, Next: Local additions, Prev: Subdirectory searching, Up: General - -2.2 Rooting the tree -==================== - -In this document, we shall designate the root TDS directory by `texmf' -(for "TeX and Metafont"). We recommend using that name where possible, -but the actual name of the directory is up to the installer. On PC -networks, for example, this could map to a logical drive specification -such as `T:'. - - Similarly, the location of this directory on the system is -site-dependent. It may be at the root of the file system; on Unix -systems, `/usr/local/share', `/usr/local', `/usr/local/lib', and `/opt' -are common choices. - - The name `texmf' was chosen for several reasons: it reflects the fact -that the directory contains files pertaining to an entire TeX system -(including Metafont, MetaPost, BibTeX, etc.), not just TeX itself; and -it is descriptive of a generic installation rather than a particular -implementation. - - A site may choose to have more than one TDS hierarchy installed (for -example, when installing an upgrade). This is perfectly legitimate. - - -File: tds.info, Node: Local additions, Next: Duplicate filenames, Prev: Rooting the tree, Up: General - -2.3 Local additions -=================== - -The TDS cannot specify precisely when a package is or is not a "local -addition". Each site must determine this according to its own -conventions. At the two extremes, one site might wish to consider -"nonlocal" all files not acquired as part of the installed TeX -distribution; another site might consider "local" only those files that -were actually developed at the local site and not distributed elsewhere. - - We recognize two common methods for local additions to a distributed -`texmf' tree. Both have their place; in fact, some sites employ both -simultaneously: - - 1. A completely separate tree which is a TDS structure itself; for - example, `/usr/local/umbtex' at the University of Massachusetts at - Boston. This is another example of the multiple `texmf' - hierarchies mentioned in the previous section. - - 2. A directory named `local' at any appropriate level, for example, - in the `FORMAT', `PACKAGE', and `SUPPLIER' directories discussed - in the following sections. The TDS reserves the directory name - `local' for this purpose. - - We recommend using `local' for site-adapted configuration files, - such as `language.dat' for the Babel package or `graphics.cfg' for - the graphics package. Unmodified configuration files from a - package should remain in the package directory. The intent is to - separate locally modified or created files from distribution - files, to ease installing new releases. - - - One common case of local additions is dynamically generated files, -e.g., PK fonts by the `mktexpk' script (which originated in Dvips as -`MakeTeXPK'). A site may store the generated files directly in any of: - * their standard location in the main TDS tree (if it can be made - globally writable); - - * an alternative location in the main TDS tree (for example, under - `texmf/fonts/tmp'); - - * a second complete TDS tree (as outlined above); - - * any other convenient directory (perhaps under `/var', for example - `/var/spool/fonts'). - - - No one solution will be appropriate for all sites. - - -File: tds.info, Node: Duplicate filenames, Prev: Local additions, Up: General - -2.4 Duplicate filenames -======================= - -Different files by the same name may exist in a TDS tree. The TDS -generally leaves unspecified which of two files by the same name in a -search path will be found, so generally the only way to reliably find a -given file is for it to have a unique name. However, the TDS requires -implementations to support the following exceptions: - - * Names of TeX input files must be unique within each first-level - subdirectory of `texmf/tex' and `texmf/tex/generic', but not - within all of `texmf/tex'; i.e., different TeX formats may have - files by the same name. (Section *Note Macros:: discusses this - further.) Thus, no single format-independent path specification, - such as a recursive search beginning at `texmf/tex' specifying no - other directories, suffices. So implementations must provide - format-dependent path specifications, for example via wrapper - scripts or configuration files. - - * Many font files will have the same name (e.g., `cmr10.pk'), as - discussed in Section *Note Valid font bitmaps::. Implementations - must distinguish these files by mode and resolution. - - - All implementations we know of already have these capabilities. - - One place where duplicate names are likely to occur is not an -exception: - - * Names of Metafont input files (as opposed to bitmaps) must be - unique within all of `texmf/fonts'. In practice, this is a problem - with some variants of Computer Modern which contain slightly - modified files named `punct.mf', `romanl.mf', and so on. We - believe the only feasible solution is to rename the derivative - files to be unique. - - - -File: tds.info, Node: Top-level directories, Next: Summary, Prev: General, Up: Top - -3 Top-level directories -*********************** - -The directories under the `texmf' root identify the major components of -a TeX system (see Section *Note Summary:: for a summary). A site may -omit any unneeded directories. - - Although the TDS by its nature can specify precise locations only -for implementation-independent files, we recognize that installers may -well wish to place other files under `texmf' to simplify administration -of the TeX tree, especially if it is maintained by someone other than -the system administrator. Therefore, additional top-level directories -may be present. - - The top-level directories specified by the TDS are: - - * `tex' for TeX files (Section *Note Macros::). - - * `fonts' for font-related files (Section *Note Fonts::). - - * `metafont' for Metafont files which are not fonts (Section *Note - Non-font Metafont files::). - - * `metapost' for MetaPost files (Section *Note MetaPost::). - - * `bibtex' for BibTeX files (Section *Note BibTeX::). - - * `scripts' for platform-independent executables (Section *Note - Scripts::). - - * `doc' for user documentation (Section *Note Documentation::). - - * `source' for sources. This includes both traditional program - sources (for example, Web2C sources go in `texmf/source/web2c') - and, e.g., LaTeX `dtx' sources (which go in `texmf/source/latex'). - The TDS leaves unspecified any structure under `source'. - - `source' is intended for files which are not needed at runtime by - any TeX program; it should not be included in any search path. For - example, `plain.tex' does not belong under `texmf/source', even - though it is a "source file" in the sense of not being derived - from another file. (It goes in `texmf/tex/plain/base', as explained - in Section *Note Macros::). - - * `IMPLEMENTATION' for implementations (examples: `emtex', `vtex', - `web2c'), to be used for whatever purpose deemed suitable by the - implementor or TeX administrator. That is, files that cannot be - shared between implementations, such as pool files (`tex.pool') - and memory dump files (`plain.fmt') go here, in addition to - implementation-wide configuration files. See Section *Note - Example implementation-specific trees:: for examples of real - `IMPLEMENTATION' trees. - - Such implementation-specific configuration files should _not_ be - located using the main TeX input search path (e.g., `TEXINPUTS'). - This must be reserved for files actually read by a TeX engine. - See Section *Note Extensions::. - - * `PROGRAM' for program-specific input and configuration files for - any TeX-related programs (examples: `mft', `dvips'). In fact, the - `tex', `metafont', `metapost', and `bibtex' items above may all be - seen as instances of this case. - - -* Menu: - -* Macros:: -* Fonts:: -* Non-font Metafont files:: -* MetaPost:: -* BibTeX:: -* Scripts:: -* Documentation:: - - -File: tds.info, Node: Macros, Next: Fonts, Up: Top-level directories - -3.1 Macros -========== - -TeX macro files shall be stored in separate directories, segregated by -TeX format and package name (we use `format' in its traditional TeX -sense to mean a usefully `\dump'-able package): - texmf/tex/FORMAT/PACKAGE/ - - * `FORMAT' is a format name (examples: `amstex', `latex', `plain', - `texinfo'). - - The TDS allows distributions that can be used as either formats or - packages (e.g., Texinfo, Eplain) to be stored at either level, at - the option of the format author or TeX administrator. We recommend - that packages used as formats at a particular site be stored at the - `FORMAT' level: by adjusting the TeX inputs search path, it will - be straightforward to use them as macro packages under another - format, whereas placing them in another tree completely obscures - their use as a format. - - The TDS reserves the following `FORMAT' names: - - * `generic', for input files that are useful across a wide - range of formats (examples: `null.tex', `path.sty'). - Generally, this means any format that uses the category codes - of Plain TeX and does not rely on any particular format. - This is in contrast to those files which are useful only with - Plain TeX (which go under `texmf/tex/plain'), e.g., - `testfont.tex' and `plain.tex' itself. - - * `local', for local additions. See Section *Note Local - additions::. - - - Thus, for almost every format, it is necessary to search at least - the `FORMAT' directory and then the `generic' directory (in that - order). Other directories may need to be searched as well, - depending on the format. When using AMS-TeX, for example, the - `amstex', `plain', and `generic' directories should be searched, - because AMS-TeX is compatible with Plain. - - * `PACKAGE' is a TeX package name (examples: `babel', `texdraw'). - - In the case where a format consists of only a single file and has - no auxiliary packages, that file can simply be placed in the - `FORMAT' directory, instead of `FORMAT/base'. For example, - Texinfo may go in `texmf/tex/texinfo/texinfo.tex', not - `texmf/tex/texinfo/base/texinfo.tex'. - - The TDS reserves the following `PACKAGE' names: - - * `base', for the base distribution of each format, including - files used by INITEX when dumping format files. For example, - in the standard LaTeX distribution, the `ltx' files created - during the build process. Another example: the `.ini' driver - files for formats used by TeX Live and other distributions. - - * `hyphen', for hyphenation patterns, including the original - American English `hyphen.tex'. These are typically used only - by INITEX. In most situations, this directory need exist - only under the `generic' format. - - * `images', for image input files, such as Encapsulated - PostScript figures. Although it is somewhat non-intuitive for - these to be under a directory named `tex', TeX needs to read - these files to glean bounding box or other information. A - mechanism for sharing image inputs between TeX and other - typesetting programs (e.g., Interleaf, FrameMaker) is beyond - the scope of the TDS. In most situations, this directory need - exist only under the `generic' format. - - * `local', for local additions and configuration files. See - Section *Note Local additions::. - - * `misc', for packages that consist of a single file. An - administrator or package maintainer may create directories for - single-file packages at their discretion, instead of using - `misc'. - - - -* Menu: - -* Extensions:: - - -File: tds.info, Node: Extensions, Up: Macros - -3.1.1 Extensions ----------------- - -TeX has spawned many companion and successor programs ("engines"), such -as PDFTeX, Omega, and others. The TDS specifies that the input files -for such programs (using a TeX-like syntax) be placed within the -top-level `tex' directory, either at the top level or within a format -subdirectory, even though the original TeX program may not be able to -read them. For example: - - texmf/tex/aleph - texmf/tex/enctex - - This is a change from TDS 1.0, which specified top-level `EXTENSION' -directories for each such program. We felt the new approach is -preferable, because: - - * Authors of relevant packages typically make their code detect the - engine being used, and issue error messages or adapt to - circumstances appropriately. Furthermore, as a package matures, - it may support multiple engines. Thus, a package could - conceivably be placed in any of several top-level directories, at - different times. Putting all packages under the top-level `tex' - directory provides a stable location over time. - - * Users need to be able to switch between engines, and configuring - different search paths for each engine is difficult and - error-prone. - - - Thus, in practice, having different top-level directories caused -difficulties for everyone involved--users, package authors, site -administrators, and system distributors. - - Please contrast this approach with the `IMPLEMENTATION' top-level -subdirectory (Section *Note Top-level directories::), which is to be -used for configuration files that (presumably) do not use TeX syntax -and in any case should not be found along the main TeX input search -path. - - -File: tds.info, Node: Fonts, Next: Non-font Metafont files, Prev: Macros, Up: Top-level directories - -3.2 Fonts -========= - -Font files are stored in separate directories, segregated by file type, -and then (in most cases) font supplier and typeface. PK and GF files -need additional structure, as detailed in the next section. - - texmf/fonts/TYPE/SUPPLIER/TYPEFACE/ - texmf/fonts/enc,lig,map/SUBPATH/ - - * `TYPE' is the type of font file. The TDS reserves the following - `TYPE' names for common TeX file types: - - * `afm', for Adobe font metrics, and `inf' files. - - * `gf', for generic font bitmap files. - - * `opentype', for OpenType fonts. - - * `pk', for packed bitmap files. - - * `source', for font sources (Metafont files, property lists, - etc.). - - * `tfm', for TeX font metric files. - - * `truetype', for TrueType fonts. - - * `type1', for PostScript Type 1 fonts (in `pfa', `pfb', - or any other format), and `pfm' files. - - * `type3', for PostScript Type 3 fonts. - - * `vf', for virtual fonts. - - The TDS also reserves the names `enc', `lig', and `map' for font - encoding, ligature, and mapping files, respectively. All of these - directories are structured the same way, with `SYNTAX' - subdirectories, and then `PACKAGE' subsubdirectories. Each of - these file types is intended to be searched along its own - recursively-searched path. The names of the actual files must be - unique within their subtree, as usual. Examples: - fonts/map/dvipdfm/updmap/dvipdfm.map - fonts/map/dvips/lm/lm.map - fonts/enc/dvips/base/8r.enc - - The Fontname and Dvips packages have more examples of the `enc' and - `map' types. The `afm2pl' program uses `lig' files. - - `pfm' files are included in the `type1' directory, instead of - being given their own directory, for two reasons: 1) a `.pfm' file - is always an adjunct to a given `.pfb' file; 2) they must be - installed from the same directory for Windows programs other than - TeX to use them. - - `inf' files are included in the `afm' directory, since an `inf' - and `afm' file can be used to generate a `pfm'. (Unfortunately, - Adobe Type Manager and perhaps other software requires that the - `pfb' be in the same directory as `afm' and `inf' for - installation.) - - As usual, a site may omit any of these directories that are - unnecessary. `gf' is a particularly likely candidate for omission. - - * `SUPPLIER' is a name identifying font source (examples: `adobe', - `ams', `public'). The TDS reserves the following `SUPPLIER' names: - - * `ams', for the American Mathematical Society's AMS-fonts - collection. - - * `local', for local additions. See Section *Note Local - additions::. - - * `public', for freely redistributable fonts where the supplier - neither (1) requested their own directory (e.g., `ams'), nor - (2) also made proprietary fonts (e.g., `adobe'). It does not - contain all extant freely distributable fonts, nor are all - files therein necessarily strictly public domain. - - * `tmp', for dynamically-generated fonts, as is traditional on - some systems. It may be omitted if unnecessary, as usual. - - - * `TYPEFACE' is the name of a typeface family (examples: `cm', - `euler', `times'). The TDS reserves the following `TYPEFACE' names: - - * `cm' (within `public'), for the 75 fonts defined in - `Computers and Typesetting, Volume E'. - - * `latex' (within `public'), for those fonts distributed with - LaTeX in the base distribution. - - * `local', for local additions. See Section *Note Local - additions::. - - - - Some concrete examples: - texmf/fonts/source/public/pandora/pnr10.mf - texmf/fonts/tfm/public/cm/cmr10.tfm - texmf/fonts/type1/adobe/utopia/putr.pfa - - For complete supplier and typeface name lists, consult `Filenames -for TeX fonts' (see Appendix *Note Related references::). - -* Menu: - -* Font bitmaps:: -* Valid font bitmaps:: - - -File: tds.info, Node: Font bitmaps, Next: Valid font bitmaps, Up: Fonts - -3.2.1 Font bitmaps ------------------- - -Font bitmap files require two characteristics in addition to the above -to be uniquely identifiable: (1) the type of device (i.e., mode) for -which the font was created; (2) the resolution of the bitmap. - - Following common practice, the TDS segregates fonts with different -device types into separate directories. See `modes.mf' in -Appendix *Note Related references:: for recommended mode names. - - Some printers operate at more than one resolution (e.g., at 300dpi -and 600dpi), but each such resolution will necessarily have a different -mode name. Nothing further is needed, since implicit in the TeX system -is the assumption of a single target resolution. - - Two naming strategies are commonly used to identify the resolution of -bitmap font files. On systems that allow long filenames (and in the -original Metafont program itself), the resolution is included in the -filename (e.g., `cmr10.300pk'). On systems which do not support long -filenames, fonts are generally segregated into directories by -resolution (e.g., `dpi300/cmr10.pk'). - - Because the TDS cannot require long filenames, we must use the -latter scheme for naming fonts. So we have two more subdirectory levels -under `pk' and `gf': - - texmf/fonts/pk/MODE/SUPPLIER/TYPEFACE/dpiNNN/ - texmf/fonts/gf/MODE/SUPPLIER/TYPEFACE/dpiNNN/ - - * `MODE' is a name which identifies the device type (examples: `cx', - `ljfour', `modeless'). Usually, this is the name of the Metafont - mode used to build the PK file. For fonts rendered as bitmaps by - a program that does not distinguish between different output - devices, the `MODE' name shall be simply `modeless'. The `MODE' - level shall not be omitted, even if only a single mode happens to - be in use. - - * `dpiNNN' specifies the resolution of the font (examples: `dpi300', - `dpi329'). `dpi' stands for dots per inch, i.e., pixels per inch. - We recognize that pixels per millimeter is used in many parts of - the world, but dpi is too traditional in the TeX world to consider - changing now. - - The integer `NNN' is to be calculated as if using Metafont - arithmetic and then rounded; i.e., it is the integer Metafont uses - in its output `gf' filename. We recognize small differences in the - resolution are a common cause of frustration among users, however, - and recommend implementors follow the level 0 DVI driver standard - (see Appendix *Note Related references::) in bitmap font searches - by allowing a fuzz of +-0.2% (with a minimum of 1) in the `DPI'. - - - Implementations may provide extensions to the basic naming scheme, -such as long filenames (as in the original Metafont) and font library -files (as in emTeX's `.fli' files), provided that the basic scheme is -also supported. - - -File: tds.info, Node: Valid font bitmaps, Prev: Font bitmaps, Up: Fonts - -3.2.2 Valid font bitmaps ------------------------- - -The TWG recognizes that the use of short filenames has many -disadvantages. The most vexing is that it results in the creation of -dozens of different files with the same name. At a typical site, -`cmr10.pk' will be the filename for Computer Modern Roman 10pt at 5-10 -magnifications for 2-3 modes. (Section *Note Duplicate filenames:: -discusses duplicate filenames in general.) - - To minimize this problem, we strongly recommend that PK files -contain enough information to identify precisely how they were created: -at least the mode, base resolution, and magnification used to create the -font. - - This information is easy to supply: a simple addition to the local -modes used for building the fonts with Metafont will automatically -provide the required information. If you have been using a local modes -file derived from (or that is simply) `modes.mf' (see Appendix *Note -Related references::), the required information is already in your PK -files. If not, a simple addition based on the code found in `modes.mf' -can be made to your local modes file and the PK files rebuilt. - - -File: tds.info, Node: Non-font Metafont files, Next: MetaPost, Prev: Fonts, Up: Top-level directories - -3.3 Non-font Metafont files -=========================== - -Most Metafont input files are font programs or parts of font programs -and are thus covered by the previous section. However, a few non-font -input files do exist. Such files shall be stored in: - - texmf/metafont/PACKAGE/ - - `PACKAGE' is the name of a Metafont package (for example, `mfpic'). - - The TDS reserves the following `PACKAGE' names: - - * `base', for the standard Metafont macro files as described in `The - Metafontbook', such as `plain.mf' and `expr.mf'. - - * `local', for local additions. See Section *Note Local additions::. - - * `misc', for Metafont packages consisting of only a single file - (for example, `modes.mf'). An administrator or package maintainer - may create directories for single-file packages at their - discretion, instead of using `misc'. - - - -File: tds.info, Node: MetaPost, Next: BibTeX, Prev: Non-font Metafont files, Up: Top-level directories - -3.4 MetaPost -============ - -MetaPost is a picture-drawing language developed by John Hobby, derived -from Knuth's Metafont. Its primary purpose is to output Encapsulated -PostScript instead of bitmaps. - - MetaPost input files and the support files for MetaPost-related -utilities shall be stored in: - - texmf/metapost/PACKAGE/ - - `PACKAGE' is the name of a MetaPost package. At the present writing -none exist, but the TWG thought it prudent to leave room for -contributed packages that might be written in the future. - - The TDS reserves the following `PACKAGE' names: - - * `base', for the standard MetaPost macro files, such as `plain.mp', - `mfplain.mp', `boxes.mp', and `graph.mp'. This includes files - used by INIMP when dumping mem files containing preloaded macro - definitions. - - * `local', for local additions. See Section *Note Local additions::. - - * `misc', for MetaPost packages consisting of only a single file. - An administrator or package maintainer may create directories for - single-file packages at their discretion, instead of using `misc'. - - * `support', for additional input files required by MetaPost utility - programs, including a font map, a character adjustment table, and - a subdirectory containing low-level MetaPost programs for rendering - some special characters. - - - -File: tds.info, Node: BibTeX, Next: Scripts, Prev: MetaPost, Up: Top-level directories - -3.5 BibTeX -========== - -BibTeX-related files shall be stored in: - - texmf/bibtex/bib/PACKAGE/ - texmf/bibtex/bst/PACKAGE/ - - The `bib' directory is for BibTeX database (`.bib') files, the `bst' -directory for style (`.bst') files. - - `PACKAGE' is the name of a BibTeX package. The TDS reserves the -following `PACKAGE' names (the same names are reserved under both `bib' -and `bst'): - - * `base', for the standard BibTeX databases and styles, such as - `xampl.bib', `plain.bst'. - - * `local', for local additions. See Section *Note Local additions::. - - * `misc', for BibTeX packages consisting of only a single file. An - administrator or package maintainer may create directories for - single-file packages at their discretion, instead of using `misc'. - - - -File: tds.info, Node: Scripts, Next: Documentation, Prev: BibTeX, Up: Top-level directories - -3.6 Scripts -=========== - -The top-level `scripts' directory is for platform-independent -executables, such as Perl, Python, and shell scripts, and Java class -files. Subdirectories under `scripts' are package names. This eases -creating distributions, by providing a common place for such -platform-independent programs. - - The intent is not for all such directories to be added to a user's -command search path, which would be quite impractical. Rather, these -executables are primarily for the benefit of wrapper scripts in whatever -executable directory a distribution may provide (which is not specified -by the TDS). - - Truly auxiliary scripts which are invoked directly by other programs, -rather than wrapper scripts, may also be placed here. That is, -`scripts' also serves as a platform-independent analog of the standard -Unix `libexec' directory. - - We recommend using extensions specifying the language (such as -`.pl', `.py', `.sh') on these files, to help uniquely identify the -name. Since the intent of the TDS is for programs in `scripts' not to -be invoked directly by users, this poses no inconvenience. - - For example, in the TeX Live distribution, the ConTeXt user-level -program `texexec' can exist as a small wrapper script in each -`bin/PLATFORM/texexec' (which is outside the `texmf' tree), which -merely finds and calls `texmf/scripts/context/perl/texexec.pl'. - - Examples: - scripts/context/perl/texexec.pl - scripts/context/ruby/examplex.rb - scripts/thumbpdf/thumbpdf.pl - - The TDS does not specify a location for platform-dependent binary -executables, whether auxiliary or user-level. - - -File: tds.info, Node: Documentation, Prev: Scripts, Up: Top-level directories - -3.7 Documentation -================= - -Most packages come with some form of documentation: user manuals, -example files, programming guides, etc. In addition, many independent -files not part of any macro or other package have been created to -describe various aspects of the TeX system. - - The TDS specifies that these additional documentation files shall be -stored in a structure that parallels to some extent the `fonts' and -`tex' directories, as follows: - - texmf/doc/CATEGORY/... - - `CATEGORY' identifies the general topic of documentation that -resides below it; for example, a TeX format name (`latex'), program -name (`bibtex', `tex'), language (`french', `german'), a file format -(`info', `man'), or other system components (`web', `fonts'). - - One possible arrangement is to organize `doc' by language, with all -the other category types below that. This helps users find -documentation in the language(s) in which they are fluent. Neither this -nor any other particular arrangement is required, however. - - Within each `CATEGORY' tree for a TeX format, the directory `base' -is reserved for base documentation distributed by the format's -maintainers. - - The TDS reserves the following category names: - - * `general', for standalone documents not specific to any particular - program (for example, Joachim Schrod's `Components of TeX'). - - * `help', for meta-information, such as FAQ's, the TeX Catalogue, - etc. - - * `info', for processed Texinfo documents. (Info files, like - anything else, may also be stored outside the TDS, at the - installer's option.) - - * `local', for local additions. See Section *Note Local additions::. - - - The `doc' directory is intended for implementation-independent and -operating system-independent documentation files. -Implementation-dependent files are best stored elsewhere, as provided -for by the implementation and/or TeX administrator (for example, VMS -help files under `texmf/vms/help'). - - The documentation directories may contain TeX sources, DVI files, -PostScript files, text files, example input files, or any other useful -documentation format(s). - - See Section *Note Documentation tree summary:: for a summary. - - -File: tds.info, Node: Summary, Next: Unspecified pieces, Prev: Top-level directories, Up: Top - -4 Summary -********* - -A skeleton of a TDS `texmf' directory tree. This is not to imply these -are the only entries allowed. For example, `local' may occur at any -level. - - bibtex/ BibTeX input files - bib/ BibTeX databases - base/ base distribution (e.g., `xampl.bib') - misc/ single-file databases - <package>/ name of a package - bst/ BibTeX style files - base/ base distribution (e.g., `plain.bst', `acm.bst') - misc/ single-file styles - <package>/ name of a package - doc/ see Section *Note Documentation:: and the summary below - fonts/ font-related files - <type>/ file type (e.g., `pk') - <mode>/ type of output device (for `pk' and `gf' only) - <supplier>/ name of a font supplier (e.g., `public') - <typeface>/ name of a typeface (e.g., `cm') - dpi<nnn>/ font resolution (for `pk' and `gf' only) - <implementation>/ TeX implementations, by name (e.g., `emtex') - local/ files created or modified at the local site - metafont/ Metafont (non-font) input files - base/ base distribution (e.g., `plain.mf') - misc/ single-file packages (e.g., `modes.mf') - <package>/ name of a package (e.g., `mfpic') - metapost/ MetaPost input and support files - base/ base distribution (e.g., `plain.mp') - misc/ single-file packages - <package>/ name of a package - support/ support files for MetaPost-related utilities - mft/ `MFT' inputs (e.g., `plain.mft') - <program>/ TeX-related programs, by name (e.g., `dvips') - source/ program source code by name (e.g., `latex', `web2c') - tex/ TeX input files - <engine>/ name of an engine (e.g., `aleph'); can also be lower - <format>/ name of a format (e.g., `plain') - base/ base distribution for format (e.g., `plain.tex') - misc/ single-file packages (e.g., `webmac.tex') - local/ local additions to or local configuration files for `FORMAT' - <package>/ name of a package (e.g., `graphics', `mfnfss') - generic/ format-independent packages - hyphen/ hyphenation patterns (e.g., `hyphen.tex') - images/ image input files (e.g., Encapsulated PostScript) - misc/ single-file format-independent packages (e.g., `null.tex'). - <package>/ name of a package (e.g., `babel') - -* Menu: - -* Documentation tree summary:: - - -File: tds.info, Node: Documentation tree summary, Up: Summary - -4.1 Documentation tree summary -============================== - -An example skeleton of a TDS directory tree under `texmf/doc'. This is -not to imply these are the only entries allowed, or that this structure -must be followed precisely for the entries listed. - - As mentioned, the `texmf/doc' tree may be organized by language, so -that all documentation in French, say, is in a `french' subdirectory. -In that case, the example structure here would be in a given language -directory. - - ams/ - amsfonts/ `amsfonts.faq', `amfndoc' - amslatex/ `amslatex.faq', `amsldoc' - amstex/ `amsguide', `joyerr' - bibtex/ BibTeX - base/ `btxdoc.tex' - fonts/ - fontname/ `Filenames for TeX fonts' - oldgerm/ `corkpapr' - <format>/ name of a TeX format (e.g., `generic', `latex') - base/ for the base distribution - misc/ for contributed single-file package documentation - <package>/ for _package_ - general/ across programs, generalities - errata/ `errata', `errata[1-8]' - texcomp/ `Components of TeX' - help/ meta-information - ctan/ info about CTAN mirror sites - faq/ FAQs of `comp.text.tex', etc. - info/ GNU Info files, made from Texinfo sources - latex/ example of `FORMAT' - base/ `ltnews*', `*guide', etc. - graphics/ `grfguide' - local/ site-specific documentation - man/ Unix man pages - <program>/ TeX-related programs, by name (examples follow) - metafont/ `mfbook.tex', `metafont-for-beginners', etc. - metapost/ `mpman', `manfig', etc. - tex/ `texbook.tex', `A Gentle Introduction to TeX', etc. - web/ `webman', `cwebman' - - -File: tds.info, Node: Unspecified pieces, Next: Implementation issues, Prev: Summary, Up: Top - -Appendix A Unspecified pieces -***************************** - -The TDS cannot address the following aspects of a functioning TeX -system: - - 1. The location of executable programs: this is too site-dependent - even to recommend a location, let alone require one. A site may - place executables outside the `texmf' tree altogether (e.g., - `/usr/local/bin'), in a platform-dependent directory within - `texmf', or elsewhere. - - 2. Upgrading packages when new releases are made: we could find no - way of introducing version specifiers into `texmf' that would do - more good than harm, or that would be practical for even a - plurality of installations. - - 3. The location of implementation-specific files (e.g., TeX `.fmt' - files): by their nature, these must be left to the implementor or - TeX maintainer. See Section *Note Example implementation-specific - trees::. - - 4. Precisely when a package or file should be considered "local", and - where such local files are installed. See Section *Note Local - additions:: for more discussion. - - -* Menu: - -* Portable filenames:: - - -File: tds.info, Node: Portable filenames, Up: Unspecified pieces - -A.1 Portable filenames -====================== - -The TDS cannot require any particular restriction on filenames in the -tree, since the names of many existing TeX files conform to no standard -scheme. For the benefit of people who wish to make a portable TeX -distribution or installation, however, we outline here the necessary -restrictions. The TDS specifications themselves are compatible with -these. - - ISO-9660 is the only universally acceptable file system format for -CD-ROMs. A subset thereof meets the stringent limitations of all -operating systems in use today. It specifies the following: - - * File and directory names, not including any directory path or - extension part, may not exceed eight characters. - - * Filenames may have a single extension. Extensions may not exceed - three characters. Directory names may not have an extension. - - * Names and extensions may consist of _only_ the characters `A'-`Z', - `0'-`9', and underscore. Lowercase letters are excluded. - - * A period separates the filename from the extension and is always - present, even if the name or extension is missing (e.g., - `FILENAME.' or `.EXT'). - - * A version number, ranging from 1-32767, is appended to the file - extension, separated by a semicolon (e.g., `FILENAME.EXT;1'). - - * Only eight directory levels are allowed, including the top-level - (mounted) directory (see Section *Note Rooting the tree::). Thus, - the deepest valid ISO-9660 path is: - texmf/L2/L3/L4/L5/L6/L7/L8/FOO.BAR;1 - 1 2 3 4 5 6 7 8 - The deepest TDS path needs only seven levels: - texmf/fonts/pk/cx/public/cm/dpi300/cmr10.pk - 1 2 3 4 5 6 7 - - - Some systems display a modified format of ISO-9660 names, mapping -alphabetic characters to lowercase, removing version numbers and -trailing periods, etc. - - Before the December 1996 release, LaTeX used mixed-case names for -font descriptor files. Fortunately, it never relied on case alone to -distinguish among the files. Nowadays, it uses only monocase names. - - -File: tds.info, Node: Implementation issues, Next: Is there a better way?, Prev: Unspecified pieces, Up: Top - -Appendix B Implementation issues -******************************** - -We believe that the TDS can bring a great deal of order to the current -anarchic state of many TeX installations. In addition, by providing a -common frame of reference, it will ease the burden of documenting -administrative tasks. Finally, it is a necessary part of any -reasonable system of true "drop-in" distribution packages for TeX. - -* Menu: - -* Adoption of the TDS:: -* More on subdirectory searching:: -* Example implementation-specific trees:: - - -File: tds.info, Node: Adoption of the TDS, Next: More on subdirectory searching, Up: Implementation issues - -B.1 Adoption of the TDS -======================= - -[This section is retained for historical purposes; the TDS is now quite -firmly entrenched in most TeX distributions.] - - We recognize that adoption of the TDS will not be immediate or -universal. Most TeX administrators will not be inclined to make the -final switch until: - - * Clear and demonstrable benefits can be shown for the TDS. - - * TDS-compliant versions of all key programs are available in - ported, well-tested forms. - - * A "settling" period has taken place, to flush out problems. The - public release of the first draft of this document was the first - step in this process. - - Consequently, most of the first trials of the TDS will be made by -members of the TDS committee and/or developers of TeX-related software. -This has already taken place during the course of our deliberations -(see Appendix *Note Related references:: for a sample tree available -electronically). They will certainly result in the production of a -substantial number of TDS-compliant packages. Indeed, the teTeX and -TeX Live distributions are TDS-compliant and in use now at many sites. - - Once installable forms of key TDS-compliant packages are more -widespread, some TeX administrators will set up TDS-compliant trees, -possibly in parallel to existing production directories. This testing -will likely flush out problems that were not obvious in the confined -settings of the developers' sites; for example, it should help to -resolve system and package dependencies, package interdependencies, and -other details not addressed by this TDS version. - - After most of the dust has settled, hopefully even conservative TeX -administrators will begin to adopt the TDS. Eventually, most TeX sites -will have adopted the common structure, and most packages will be -readily available in TDS-compliant form. - - We believe that this process will occur relatively quickly. The TDS -committee spans a wide range of interests in the TeX community. -Consequently, we believe that most of the key issues involved in -defining a workable TDS definition have been covered, often in detail. -TeX developers have been consulted about implementation issues, and -have been trying out the TDS arrangement. Thus, we hope for few -surprises as implementations mature. - - Finally, there are several (current or prospective) publishers of TeX -CD-ROMs. These publishers are highly motivated to work out details of -TDS implementation, and their products will provide inexpensive and -convenient ways for experimentally-minded TeX administrators to -experiment with the TDS. - - -File: tds.info, Node: More on subdirectory searching, Next: Example implementation-specific trees, Prev: Adoption of the TDS, Up: Implementation issues - -B.2 More on subdirectory searching -================================== - -Recursive subdirectory searching is the ability to specify a search not -only of a specified directory `D', but recursively of all directories -below `D'. - - Since the TDS specifies precise locations for most files, with no -extra levels of subdirectories allowed, true recursive searching is not -actually required for a TDS-compliant implementation. We do, however, -strongly recommend recursive searching as the most user-friendly and -natural approach to the problem, rather than convoluted methods to -specify paths without recursion. - - This feature is already supported by many implementations of TeX and -companion utilities, for example DECUS TeX for VMS, Dvips(k), emTeX -(and its drivers), PubliC TeX, Web2C, Xdvi(k), and Y&YTeX. The -Kpathsea library is a reusable implementation of subdirectory searching -for TeX, used in a number of the above programs. - - Even if your TeX implementation does not directly support -subdirectory searching, you may find it useful to adopt the structure if -you do not use many fonts or packages. For instance, if you only use -Computer Modern and AMS fonts, it would be feasible to store them in -the TDS layout and list the directories individually in configuration -files or environment variables. - - The TWG recognizes that subdirectory searching places an extra -burden on the system and may be the source of performance bottlenecks, -particularly on slower machines. Nevertheless, we feel that -subdirectory searching is imperative for a well-organized TDS, for the -reasons stated in Section *Note Subdirectory searching::. Implementors -are encouraged to provide enhancements to the basic principle of -subdirectory searching to avoid performance problems, e.g., the use of -a filename cache (this can be as simple as a recursive directory -listing) that is consulted before disk searching begins. If a match is -found in the database, subdirectory searching is not required, and -performance is thus independent of the number of subdirectories present -on the system. - - Different implementations specify subdirectory searching differently. -In the interest of typographic clarity, the examples here do not use the -`REPLACEABLE' font. - - * Dvips: via a separate `TEXFONTS_SUBDIR' environment variable. - - * emTeX: `t:\subdir!!'; `t:\subdir!' for a single level of searching. - - * Kpathsea: `texmf/subdir//' - - * VMS: `texmf:[subdir...]' - - * Xdvi (patchlevel 20): `texmf/subdir/**'; `texmf/subdir/*' for a - single level of searching. Version 20.50 and above support the - `//' notation. - - * Y&Y TeX: `t:/subdir//' or `t:\subdir\\'. - - - -File: tds.info, Node: Example implementation-specific trees, Prev: More on subdirectory searching, Up: Implementation issues - -B.3 Example implementation-specific trees -========================================= - -The TDS cannot specify a precise location for implementation-specific -files, such as `texmf/ini', because a site may have multiple TeX -implementations. - - Nevertheless, for informative purposes, we provide here the default -locations for some implementations. Please contact us with additions or -corrections. These paths are not definitive, may not match anything at -your site, and may change without warning. - - We recommend all implementations have default search paths that start -with the current directory (e.g., `.'). Allowing users to include the -parent directory (e.g., `..') is also helpful. - -* Menu: - -* AmiWeb2c 2.0:: -* Public DECUS TeX:: -* Web2c 7:: - - -File: tds.info, Node: AmiWeb2c 2.0, Next: Public DECUS TeX, Up: Example implementation-specific trees - -B.3.1 AmiWeb2c 2.0 ------------------- - -(Email <scherer@physik.rwth-aachen.de> to contact the maintainer of -this implementation.) - - AmiWeb2c 2 is compatible with Web2c 7 to the greatest possible -extent, so only the very few differences are described in this section. -Detailed information about the basic concepts is given in the section -for Web2c 7 below. - - Thanks to the `SELFAUTO' mechanism of Kpathsea 3.0 no specific -location for the installation of AmiWeb2c is required as long as the -general structure of the distribution is preserved. - - In addition to Kpathsea's `//' notation recursive path search may -also be started by `DEVICE:/', e.g., `TeXMF:/' will scan this specific -device completely. - - Binaries coming with the AmiWeb2c distribution are installed in the -directory `bin/amiweb2c/' outside the common TDS tree `share/texmf/'. -In addition to the set of AmiWeb2c binaries you will find two -subdirectories `local/' and `pastex/' with auxiliary programs. - - A stripped version of the PasTeX system (used by kind permission of -Georg Hessmann) is coming with AmiWeb2c, pre-installed in its own -`share/texmf/amiweb2c/pastex/' directory. If you want to use PasTeX -you have to `assign' the name `TeX:' to this place. - - Documentation files in AmigaGuide format should be stored at -`doc/guide/' similar to `doc/info/'. - - -File: tds.info, Node: Public DECUS TeX, Next: Web2c 7, Prev: AmiWeb2c 2.0, Up: Example implementation-specific trees - -B.3.2 Public DECUS TeX ----------------------- - -If another VMS implementation besides Public DECUS TeX appears, the top -level implementation directory name will be modified to something more -specific (e.g., `vms_decus'). - - texmf/ - vms/ VMS implementation specific files - exe/ end-user commands - common/ command procedures, command definition files, etc. - axp/ binary executables for Alpha AXP - vax/ binary executables for VAX - formats/ pool files, formats, bases - help/ VMS help library, and miscellaneous help sources - mgr/ command procedures, programs, docs, etc., for system management - - -File: tds.info, Node: Web2c 7, Prev: Public DECUS TeX, Up: Example implementation-specific trees - -B.3.3 Web2c 7 -------------- - -All implementation-dependent TeX system files (`.pool', `.fmt', -`.base', `.mem') are stored by default directly in `texmf/web2c'. The -configuration file `texmf.cnf' and various subsidiary `MakeTeX...' -scripts used as subroutines are also stored there. - - Non-TeX specific files are stored following the GNU coding -standards. Given a root directory `PREFIX' (`/usr/local' by default), -we have default locations as follows: - - <prefix>/ installation root (`/usr/local' by default) - bin/ executables - man/ man pages - info/ info files - lib/ libraries (`libkpathsea.*') - share/ architecture-independent files - texmf/ TDS root - web2c/ implementation-dependent files (`.pool', `.fmt', `texmf.cnf', etc.) - - See `http://www.gnu.org/prep/standards_toc.html' for the rationale -behind and descriptions of this arrangement. A site may of course -override these defaults; for example, it may put everything under a -single directory such as `/usr/local/texmf'. - - -File: tds.info, Node: Is there a better way?, Next: Related references, Prev: Implementation issues, Up: Top - -Appendix C Is there a better way? -********************************* - -Defining the TDS required many compromises. Both the overall structure -and the details of the individual directories were arrived at by -finding common ground among many opinions. The driving forces were -feasibility (in terms of what could technically be done and what could -reasonably be expected from developers) and regularity (files grouped -together in an arrangement that "made sense"). - - Some interesting ideas could not be applied due to implementations -lacking the necessary support: - - * Path searching control at the TeX level. If documents could - restrict subdirectory searching to a subdirectory via some portable - syntax in file names, restrictions on uniqueness of filenames - could be relaxed considerably (with the cooperation of the - formats), and the TeX search path would not need to depend on the - format. - - * Multiple logical `texmf' trees. For example, a site might have one - (read-only) location for stable files, and a different (writable) - location for dynamically-created fonts or other files. It would be - reasonable for two such trees to be logically merged when - searching. See Michael Downes' article in the references for how - this can work in practice with Web2C. - - -* Menu: - -* Macro structure:: -* Font structure:: -* Documentation structure:: - - -File: tds.info, Node: Macro structure, Next: Font structure, Up: Is there a better way? - -C.1 Macro structure -=================== - -The TWG settled on the `FORMAT/PACKAGE' arrangement after long -discussion about how best to arrange the files. - - The primary alternative to this arrangement was a scheme which -reversed the order of these directories: `PACKAGE/FORMAT'. This -reversed arrangement has a strong appeal: it keeps all of the files -related to a particular package in a single place. The arrangement -actually adopted tends to spread files out into two or three places -(macros, documentation, and fonts, for example, are spread into -different sections of the tree right at the top level). - - Nevertheless, the `FORMAT/PACKAGE' structure won for a couple of -reasons: - - * It is closer to current practice; in fact, several members of the - TWG have already implemented the TDS hierarchy. The alternative - is not in use at any known site, and the TWG felt it wrong to - mandate something with which there is no practical experience. - - * The alternative arrangement increases the number of top-level - directories, so the files that must be found using subdirectory - searching are spread out in a wide, shallow tree. This could have - a profound impact on the efficiency of subdirectory searching. - - - -File: tds.info, Node: Font structure, Next: Documentation structure, Prev: Macro structure, Up: Is there a better way? - -C.2 Font structure -================== - -The TWG struggled more with the font directory structure than anything -else. This is not surprising; the need to use the proliferation of -PostScript fonts with TeX is what made the previous arrangement with -all files in a single directory untenable, and therefore what initiated -the TDS effort. - -* Menu: - -* Font file type location:: -* Mode and resolution location:: -* Modeless bitmaps:: - - -File: tds.info, Node: Font file type location, Next: Mode and resolution location, Up: Font structure - -C.2.1 Font file type location ------------------------------ - -We considered the supplier-first arrangement in use at many sites: - - texmf/fonts/SUPPLIER/TYPEFACE/TYPE/ - - This improves the maintainability of the font tree, since all files -comprising a given typeface are in one place, but unless all the -programs that search this tree employ some form of caching, there are -serious performance concerns. For example, in order to find a `TFM' -file, the simplest implementation would require TeX to search through -all the directories that contain PK files in all modes and at all -resolutions. - - In the end, a poll of developers revealed considerable resistance to -implementing sufficient caching mechanisms, so this arrangement was -abandoned. The TDS arrangement allows the search tree to be restricted -to the correct type of file, at least. Concerns about efficiency -remain, but there seems to be no more we can do without abandoning -subdirectory searching entirely. - - We also considered segregating all font-related files strictly by -file type, so that Metafont sources would be in a directory -`texmf/fonts/mf', property list files in `texmf/fonts/pl', the various -forms of Type 1 fonts separated, and so on. Although more blindly -consistent, we felt that the drawback of more complicated path -constructions outweighed this. The TDS merges file types (`mf' and `pl' -under `source', `pfa' and `pfb' and `gsf' under `type1') where we felt -this was beneficial. - - -File: tds.info, Node: Mode and resolution location, Next: Modeless bitmaps, Prev: Font file type location, Up: Font structure - -C.2.2 Mode and resolution location ----------------------------------- - -We considered having the `mode' at the bottom of the font tree: - texmf/fonts/pk/SUPPLIER/TYPEFACE/MODE/DPI/ - - In this case, however, it is difficult to limit subdirectory -searching to the mode required for a particular device. - - We then considered moving the `dpiNNN' up to below the mode: - texmf/fonts/pk/MODE/DPI/SUPPLIER/TYPEFACE/ - - But then it is not feasible to omit the `dpiNNN' level altogether on -systems which can and do choose to use long filenames. - - -File: tds.info, Node: Modeless bitmaps, Prev: Mode and resolution location, Up: Font structure - -C.2.3 Modeless bitmaps ----------------------- - -The TDS specifies using a single directory `modeless/' as the mode name -for those utilities which generate bitmaps, e.g., -`texmf/fonts/modeless/times/'. This has the considerable advantage of -not requiring each such directory name to be listed in a search path. - - An alternative was to use the utility name below which all such -directories could be gathered. That has the advantage of separating, -say, `gsftopk'-generated bitmaps from `ps2pk'-generated ones. However, -we decided this was not necessary; most sites will use only one program -for the purpose. Also, PK and GF fonts generally identify their -creator in the font comment following the `PK_ID' byte. - - We are making an implicit assumption that Metafont is the only -program producing mode-dependent bitmaps. If this becomes false we -could add an abbreviation for the program to mode names, as in `mfcx' -vs. `xyzcx' for a hypothetical program Xyz, or we could at that time -add an additional program name level uniformly to the tree. It seemed -more important to concisely represent the current situation than to -worry about hypothetical possibilities that may never happen. - - -File: tds.info, Node: Documentation structure, Prev: Font structure, Up: Is there a better way? - -C.3 Documentation structure -=========================== - -We considered placing additional documentation files in the same -directory as the source files for the packages, but we felt that users -should be able to find documentation separately from sources, since most -users have no interest in sources. - - We hope that a separate, but parallel, structure for documentation -would (1) keep the documentation together and (2) make it as -straightforward as possible for users to find the particular -documentation they were after. - - -File: tds.info, Node: Related references, Next: Contributors, Prev: Is there a better way?, Up: Top - -Appendix D Related references -***************************** - -This appendix gives pointers to related files and other documents. For -CTAN references, we use `http://www.ctan.org' as the top-level domain -only to make the links be live in this document. See -`http://www.ctan.org/tex-archive/CTAN.sites' for a complete list of -CTAN sites; there are mirrors worldwide. - - * This document, in many formats (tex, dvi, info, pdf): - `http://tug.org/tds/' - - * The TDS mailing list archives: - `http://tug.org/mail-archives/twg-tds/' - - * The level 0 DVI driver standard: - `http://www.ctan.org/tex-archive/dviware/driv-standard/level-0/' - - * `Filenames for TeX fonts', with lists of recommended supplier and - typeface names: - `http://tug.org/fontname/' - - * ISO-9660 CD-ROM file system standard: - `http://www.iso.ch/cate/cat.html' - - * `Components of TeX', a paper by Joachim Schrod: - `http://www.ctan.org/tex-archive/documentation/components-of-TeX/' - - * `Managing Multiple TDS trees', an article by Michael Downes: - `http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf' - - * A complete set of Metafont modes: - `http://www.ctan.org/tex-archive/fonts/modes/modes.mf' - - * A large collection of BibTeX databases and styles: - `ftp://ftp.math.utah.edu/pub/tex/bib/' - - - -File: tds.info, Node: Contributors, Prev: Related references, Up: Top - -Appendix E Contributors -*********************** - -The TWG has had no physical meetings; electronic mail was the -communication medium. - - Sebastian Rahtz is the TeX Users Group Technical Council liaison. -Norman Walsh was the original committee chair. Karl Berry is the -current editor. - - The list of contributors has grown too large to fairly include, as -some would surely be inadvertently omitted. Please consider the -archives of the <tds@tug.org> and <tex-live@tug.org> mailing lists as -the record of contributions. - - - -Tag Table: -Node: Top198 -Node: Introduction2185 -Node: History3846 -Node: The role of the TDS4648 -Node: Conventions5508 -Node: General6429 -Node: Subdirectory searching6714 -Node: Rooting the tree8968 -Node: Local additions10080 -Node: Duplicate filenames12293 -Node: Top-level directories14054 -Node: Macros17062 -Node: Extensions20919 -Node: Fonts22645 -Node: Font bitmaps26786 -Node: Valid font bitmaps29674 -Node: Non-font Metafont files30882 -Node: MetaPost31842 -Node: BibTeX33286 -Node: Scripts34155 -Node: Documentation35872 -Node: Summary38145 -Node: Documentation tree summary41031 -Node: Unspecified pieces43056 -Node: Portable filenames44267 -Node: Implementation issues46409 -Node: Adoption of the TDS47041 -Node: More on subdirectory searching49753 -Node: Example implementation-specific trees52568 -Node: AmiWeb2c 2.053447 -Node: Public DECUS TeX54889 -Node: Web2c 755752 -Node: Is there a better way?56974 -Node: Macro structure58480 -Node: Font structure59816 -Node: Font file type location60369 -Node: Mode and resolution location61946 -Node: Modeless bitmaps62625 -Node: Documentation structure63915 -Node: Related references64543 -Node: Contributors65959 - -End Tag Table diff --git a/tds/tds.pdf b/tds/tds.pdf Binary files differdeleted file mode 100644 index bb2a2a46d3..0000000000 --- a/tds/tds.pdf +++ /dev/null diff --git a/tds/tds.sed b/tds/tds.sed deleted file mode 100644 index fb7f30f13c..0000000000 --- a/tds/tds.sed +++ /dev/null @@ -1,14 +0,0 @@ -# $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}. diff --git a/tds/tds.tex b/tds/tds.tex deleted file mode 100644 index 55c1b4ddcc..0000000000 --- a/tds/tds.tex +++ /dev/null @@ -1,1585 +0,0 @@ -%&latex -% $Id: tds.tex,v 1.43 2004/06/23 17:24:42 karl Exp $ -\NeedsTeXFormat{LaTeX2e} % compatibility with 2.09 is too painful -\documentclass{tdsguide} - -\tdsVersion{1.1} - -\title{A Directory Structure for \TeX{} Files} -\author{TUG Working Group on a \TeX{} Directory Structure (TWG-TDS)} - -\begin{document} - -\maketitle - -\begin{legalnotice} - -Copyright {\copyright} 1994, 1995, 1996, 1997, 1998, 1999, 2003, 2004 -\TeX{} Users Group. - -Permission to use, copy, and distribute this document \emphasis{without -modification} for any purpose and without fee is hereby granted, -provided that this notice appears in all copies. It is provided ``as -is'' without expressed or implied warranty. - -Permission is granted to copy and distribute modified versions of this -document under the conditions for verbatim copying, provided that the -modifications are clearly marked and the document is not represented as -the official one. - -This document is available on any \abbr{ctan} host -(see Appendix~\ref{sec:Related references}). -Please send questions or suggestions by email to -\email|tds@tug.org|. We welcome all comments. This is version -\the\tdsVersion. - -\end{legalnotice} - - -\tableofcontents - - -\newpage -\section{Introduction} - -\TeX{} is a powerful, flexible typesetting system used by many people -around the world. It is extremely portable and runs on virtually all -operating systems. One unfortunate side effect of \TeX{}'s flexibility, -however, is that there has been no single ``right'' way to install it. -This has resulted in many sites having different installed arrangements. - -The primary purpose of this document is to describe a standard \TeX{} -Directory Structure (\abbr{TDS}): a directory hierarchy for macros, -fonts, and the other implementation-independent \TeX{} system files. As -a matter of practicality, this document also suggests ways to -incorporate the rest of the \TeX{} files into a single structure. The -\abbr{TDS} has been designed to work on all modern systems. In -particular, the Technical Working Group (\abbr{TWG}) believes it is usable -under Mac\abbr{OS}, \abbr{ms-dos}, \abbr{os/2}, Unix, \abbr{vms}, and -Windows \abbr{nt}\@. We hope that administrators and developers of both -free and commercial \TeX{} implementations will adopt this standard. - -This document is intended both for the \TeX{} system administrator at a -site and for people preparing \TeX{} distributions---everything from a -complete runnable system to a single macro or style file. It may also -help \TeX{} users find their way around systems organized this way. It -is not a tutorial: we necessarily assume knowledge of the many parts of -a working \TeX{} system. If you are unfamiliar with any of the programs -or file formats we refer to, consult the references in -Appendix~\ref{sec:Related references}. - - -\subsection{History} - -Version 1.0 of the \abbr{TDS} was released in February 2003. - -Version 1.1 was released in June 2004, with the following non-editorial -changes: - -\begin{itemize-squeeze} -\item Inputs for \TeX{} extensions included under \path|tex|, instead - of in their own top-level directories (Section~\ref{sec:Extensions}) -\item New top-level directory \path|scripts| (Section~\ref{sec:Scripts}). -\item New subdirectories \path|lig|, \path|opentype|, - \path|truetype|, and \path|type3| under \path|fonts| - (Section~\ref{sec:Fonts}). -\item \path|enc|, \path|lig|, and \path|map| all use - \replaceable{syntax}\path|/|\replaceable{package} subdirectories - (Section~\ref{sec:Fonts}). -\item \path|pfm| files specified to go under \path|type1|, and - \path|inf| files under \path|afm| (Section~\ref{sec:Fonts}). -\end{itemize-squeeze} - - -\subsection{The role of the \abbr{TDS}} - -The role of the \abbr{TDS} is to stabilize the organization of -\TeX{}-related software packages that are installed and in use, possibly -on multiple platforms simultaneously. - -At first glance, it may seem that the Comprehensive \TeX{} Archive -Network (\abbr{ctan}) fulfills at least part of this role, but this is -not the case. The role of \abbr{ctan} is to simplify archiving and -distribution, not installation and use. - -In fact, the roles of the \abbr{TDS} and \abbr{ctan} are frequently in -conflict, as we will see. For distribution, many different types of -files must be combined into a single unit; for use, it is traditional to -segregate files (even similar files) from a single package into -separate, occasionally distant, directories. - - -\subsection{Conventions} - -In this document, ``\path|/|'' is used to separate filename components; -for example, \path|texmf/fonts|. This is the Unix convention but the -ideas are in no way Unix-specific. - -In this document, ``\TeX{}'' generally means the \TeX{} system, including -\MF{}, \abbr{DVI} drivers, utilities, etc., not just the \TeX{} -program itself. - -The word ``package'' in this document has its usual meaning: a set of -related files distributed, installed, and maintained as a unit. This is -\emphasis{not} a \LaTeXe{} package, which is a style file supplementing -a document class. - -We use the following typographic conventions: - -\begin{description} - -\item[\literal{literal}] Literal text such as \literal{filename} is -typeset in typewriter type. - -\item[\replaceable{replaceable}] Replaceable text such as -\replaceable{package}, identifying a class of things, is typeset in -italics inside angle brackets. - -\end{description} - - -\section{General} - -This section describes common properties throughout the \abbr{TDS} tree. - -\subsection{Subdirectory searching} -\label{sec:Subdirectory searching} - -Older \TeX{} installations store large numbers of related files in single -directories, for example, all \path|TFM| files and\slash or all \TeX{} -input files. - -This monolithic arrangement hinders maintenance of a \TeX{} system: it -is difficult to determine what files are used by what packages, what -files need to be updated when a new version is installed, or what files -should be deleted if a package is removed. It is also a source of error -if two or more packages happen to have input files with the same name. - -Therefore, the \abbr{TWG} felt each package should be in a separate -directory. But we recognized that explicitly listing all directories to -be searched would be unbearable. A site may wish to install dozens of -packages. Aside from anything else, listing that many directories would -produce search paths many thousands of characters long, overflowing the -available space on some systems. - -Also, if all directories are explicitly listed, installing or removing a -new package would mean changing a path as well as installing or removing -the actual files. This would be a time-consuming and error-prone -operation, even with implementations that provide some way to specify -the directories to search at runtime. On systems without runtime -configuration, it would require recompiling software, an intolerable -burden. - -As a result, the \abbr{TWG} concluded that a comprehensive \abbr{TDS} -requires implementations to support some form of implicit subdirectory -searching. More precisely, implementations must make it possible to -specify that \TeX{}, \MF{}, and their companion utilities search in both -a specified directory and recursively through all subdirectories of that -directory when looking for an input file. Other forms of subdirectory -searching, for example recursive-to-one-level searches, may also be -provided. We encourage implementors to provide subdirectory searching -at the option of the installer and user for all paths. - -The \abbr{TDS} does not specify a syntax for specifying recursive -searching, but we encourage implementors to provide interoperability -(see Section~\ref{sec:More on subdirectory searching}). - - -\subsection{Rooting the tree} -\label{sec:Rooting the tree} - -In this document, we shall designate the root \abbr{TDS} directory by -`\texmf{}' (for ``\TeX{} and \MF{}''). We recommend using that name -where possible, but the actual name of the directory is up to the -installer. On \abbr{pc} networks, for example, this could map to a -logical drive specification such as \path|T:|. - -Similarly, the location of this directory on the system is -site-dependent. It may be at the root of the file system; on Unix -systems, \path|/usr/local/share|, \path|/usr/local|, -\path|/usr/local/lib|, and \path|/opt| are common choices. - -The name \texmf{} was chosen for several reasons: it reflects the fact -that the directory contains files pertaining to an entire \TeX{} system -(including \MF{}, \MP{}, \BibTeX{}, etc.), not just \TeX{} itself; and it -is descriptive of a generic installation rather than a particular -implementation. - -A site may choose to have more than one \abbr{TDS} hierarchy installed -(for example, when installing an upgrade). This is perfectly legitimate. - - -\subsection{Local additions} -\label{sec:Local additions} - -The \abbr{TDS} cannot specify precisely when a package is or is not a -``local addition''. Each site must determine this according to its own -conventions. At the two extremes, one site might wish to consider -``nonlocal'' all files not acquired as part of the installed \TeX{} -distribution; another site might consider ``local'' only those files -that were actually developed at the local site and not distributed -elsewhere. - -We recognize two common methods for local additions to a distributed -\texmf{} tree. Both have their place; in fact, some sites employ -both simultaneously: - -\begin{enumerate} - -\item A completely separate tree which is a \abbr{TDS} structure -itself; for example, \path|/usr/local/umbtex| at the University of -Massachusetts at Boston. This is another example of the multiple -\texmf{} hierarchies mentioned in the previous section. - -\item A directory named `\path|local|' at any appropriate level, for -example, in the \replaceable{format}, \replaceable{package}, and -\replaceable{supplier} directories discussed in the following sections. -The \abbr{TDS} reserves the directory name \path|local| for this -purpose. - -We recommend using \path|local| for site-adapted configuration files, -such as \path|language.dat| for the Babel package or \path|graphics.cfg| -for the graphics package. Unmodified configuration files from a package -should remain in the package directory. The intent is to separate -locally modified or created files from distribution files, to ease -installing new releases. - -\end{enumerate} - -One common case of local additions is dynamically generated files, e.g., -\abbr{PK} fonts by the \path|mktexpk| script (which originated in -\application{Dvips} as \path|MakeTeXPK|). A site may store the -generated files directly in any of: -\begin{itemize-squeeze} -\item their standard location in the main \abbr{TDS} tree (if it can be -made globally writable); - -\item an alternative location in the main \abbr{TDS} tree (for -example, under \path|texmf/fonts/tmp|); - -\item a second complete \abbr{TDS} tree (as outlined above); - -\item any other convenient directory (perhaps under -\path|/var|, for example \path|/var/spool/fonts|). - -\end{itemize-squeeze} - -No one solution will be appropriate for all sites. - - -\subsection{Duplicate filenames} -\label{sec:Duplicate filenames} - -Different files by the same name may exist in a \abbr{TDS} tree. The -\abbr{TDS} generally leaves unspecified which of two files by the same -name in a search path will be found, so generally the only way to -reliably find a given file is for it to have a unique name. However, -the \abbr{TDS} requires implementations to support the following -exceptions: - -\begin{itemize} - -\item Names of \TeX{} input files must be unique within each first-level -subdirectory of \path|texmf/tex| and \path|texmf/tex/generic|, but not -within all of \path|texmf/tex|; i.e., different \TeX{} formats may have -files by the same name. (Section~\ref{sec:Macros} discusses this -further.) Thus, no single format-independent path specification, such -as a recursive search beginning at \path|texmf/tex| specifying no other -directories, suffices. So implementations must provide format-dependent -path specifications, for example via wrapper scripts or configuration -files. - -\item Many font files will have the same name (e.g., \path|cmr10.pk|), -as discussed in Section~\ref{sec:Valid font bitmaps}. Implementations -must distinguish these files by mode and resolution. - -\end{itemize} - -All implementations we know of already have these capabilities. - -One place where duplicate names are likely to occur is not an exception: - -\begin{itemize} - -\item Names of \MF{} input files (as opposed to bitmaps) must be unique -within all of \path|texmf/fonts|. In practice, this is a problem with -some variants of Computer Modern which contain slightly modified files -named \path|punct.mf|, \path|romanl.mf|, and so on. We believe the only -feasible solution is to rename the derivative files to be -unique. - -\end{itemize} - - -\section{Top-level directories} -\label{sec:Top-level directories} - -The directories under the \texmf{} root identify the major components of -a \TeX{} system (see Section~\ref{sec:Summary} for a summary). A site -may omit any unneeded directories. - -Although the \abbr{TDS} by its nature can specify precise locations only -for implementation-independent files, we recognize that installers may -well wish to place other files under \texmf{} to simplify administration -of the \TeX{} tree, especially if it is maintained by someone other than -the system administrator. Therefore, additional top-level directories -may be present. - -The top-level directories specified by the \abbr{TDS} are: - -\begin{description} -\item[\path|tex|] -for \TeX{} files (Section~\ref{sec:Macros}). - -\item[\path|fonts|] -for font-related files (Section~\ref{sec:Fonts}). - -\item[\path|metafont|] -for \MF{} files which are not fonts (Section~\ref{sec:Non-font MF files}). - -\item[\path|metapost|] -for \MP{} files (Section~\ref{sec:MetaPost}). - -\item[\path|bibtex|] -for \BibTeX{} files (Section~\ref{sec:BibTeX}). - -\item[\path|scripts|] -for platform-independent executables (Section~\ref{sec:Scripts}). - -\item[\path|doc|] -for user documentation (Section~\ref{sec:Documentation}). - -\item[\path|source|] for sources. This includes both traditional -program sources (for example, \application{Web2C} sources go in -\path|texmf/source/web2c|) and, e.g., \LaTeX{} \path|dtx| sources (which -go in \path|texmf/source/latex|). The \abbr{TDS} leaves unspecified any -structure under \path|source|. - -\path|source| is intended for files which are not needed at runtime by -any \TeX{} program; it should not be included in any search path. For -example, \path|plain.tex| does not belong under \path|texmf/source|, -even though it is a ``source file'' in the sense of not being derived -from another file. (It goes in \path|texmf/tex/plain/base|, as explained -in Section~\ref{sec:Macros}). - -\item[\replaceable{implementation}] for implementations (examples: -\path|emtex|, \path|vtex|, \path|web2c|), to be used for whatever -purpose deemed suitable by the implementor or \TeX{} administrator. -That is, files that cannot be shared between implementations, such as -pool files (\path|tex.pool|) and memory dump files (\path|plain.fmt|) go -here, in addition to implementation-wide configuration files. See -Section~\ref{sec:Example implementation-specific trees} for examples of -real \replaceable{implementation} trees. - -Such implementation-specific configuration files should \emphasis{not} -be located using the main \TeX{} input search path (e.g., -\path|TEXINPUTS|). This must be reserved for files actually read by a -\TeX{} engine. See Section~\ref{sec:Extensions}. - -\item[\replaceable{program}] for program-specific input and -configuration files for any \TeX{}-related programs (examples: -\path|mft|, \path|dvips|). In fact, the \path|tex|, \path|metafont|, -\path|metapost|, and \path|bibtex| items above may all be seen as -instances of this case. - -\end{description} - - -\subsection{Macros} -\label{sec:Macros} - -\TeX{} macro files shall be stored in separate directories, segregated -by \TeX{} format and package name (we use `format' in its traditional -\TeX{} sense to mean a usefully \path|\dump|-able package): -\begin{ttdisplay} -texmf/tex/\replaceable{format}/\replaceable{package}/ -\end{ttdisplay} - -\begin{description} - -\item[\replaceable{format}] is a format name (examples: \path|amstex|, -\path|latex|, \path|plain|, \path|texinfo|). - -The \abbr{TDS} allows distributions that can be used as either formats or -packages (e.g., Texinfo, Eplain) to be stored at either level, at the -option of the format author or \TeX{} administrator. We recommend that -packages used as formats at a particular site be stored at the -\replaceable{format} level: by adjusting the \TeX{} inputs search path, -it will be straightforward to use them as macro packages under another -format, whereas placing them in another tree completely obscures their -use as a format. - -The \abbr{TDS} reserves the following \replaceable{format} names: - -\begin{itemize} - -\item \path|generic|, for input files that are useful across a wide -range of formats (examples: \path|null.tex|, \path|path.sty|). -Generally, this means any format that uses the category codes of Plain -\TeX{} and does not rely on any particular format. This is in contrast -to those files which are useful only with Plain \TeX{} (which go under -\path|texmf/tex/plain|), e.g., \path|testfont.tex| and \path|plain.tex| -itself. - -\item \path|local|, for local additions. See Section~\ref{sec:Local -additions}. - -\end{itemize} - -Thus, for almost every format, it is necessary to search at least the -\replaceable{format} directory and then the \path|generic| directory (in -that order). Other directories may need to be searched as well, -depending on the format. When using \AMSTeX{}, for example, the -\path|amstex|, \path|plain|, and \path|generic| directories should be -searched, because \AMSTeX{} is compatible with Plain. - -\item[\replaceable{package}] is a \TeX{} package name (examples: -\path|babel|, \path|texdraw|). - -In the case where a format consists of only a single file and has no -auxiliary packages, that file can simply be placed in the -\replaceable{format} directory, instead of -\replaceable{format}\path|/base|. For example, Texinfo may go in -\path|texmf/tex/texinfo/texinfo.tex|, not -\path|texmf/tex/texinfo/base/texinfo.tex|. - -The \abbr{TDS} reserves the following \replaceable{package} names: - -\begin{itemize} - -\item \path|base|, for the base distribution of each format, -including files used by \iniTeX{} when dumping format files. For -example, in the standard \LaTeX{} distribution, the \path|ltx| files -created during the build process. Another example: the \path|.ini| -driver files for formats used by \TeX{} Live and other distributions. - -\item \path|hyphen|, for hyphenation patterns, including the original -American English \path|hyphen.tex|. These are typically used only by -\iniTeX{}. In most situations, this directory need exist only under the -\literal{generic} format. - -\item \path|images|, for image input files, such as Encapsulated -PostScript figures. Although it is somewhat non-intuitive for these to -be under a directory named ``\path|tex|'', \TeX{} needs to read these -files to glean bounding box or other information. A mechanism for -sharing image inputs between \TeX{} and other typesetting programs -(e.g., Interleaf, FrameMaker) is beyond the scope of the -\abbr{TDS}\@. In most situations, this directory need exist only under -the \literal{generic} format. - -\item \path|local|, for local additions and configuration files. See -Section~\ref{sec:Local additions}. - -\item \path|misc|, for packages that consist of a single file. An -administrator or package maintainer may create directories for -single-file packages at their discretion, instead of using \path|misc|. - -\end{itemize} - -\end{description} - - -\subsubsection{Extensions} -\label{sec:Extensions} - -\TeX{} has spawned many companion and successor programs (``engines''), -such as \abbr{PDF}\TeX{}, Omega, and others. The \abbr{TDS} specifies -that the input files for such programs (using a \TeX{}-like syntax) be -placed within the top-level \path|tex| directory, either at the top -level or within a format subdirectory, even though the original \TeX{} -program may not be able to read them. For example: - -\begin{ttdisplay} -texmf/tex/aleph -texmf/tex/enctex -\end{ttdisplay} - -This is a change from \abbr{TDS}~1.0, which specified top-level -\replaceable{extension} directories for each such program. We felt the -new approach is preferable, because: - -\begin{itemize} - -\item Authors of relevant packages typically make their code detect the -engine being used, and issue error messages or adapt to circumstances -appropriately. Furthermore, as a package matures, it may support -multiple engines. Thus, a package could conceivably be placed in any of -several top-level directories, at different times. Putting all packages -under the top-level \path|tex| directory provides a stable location over -time. - -\item Users need to be able to switch between engines, and configuring -different search paths for each engine is difficult and error-prone. - -\end{itemize} - -Thus, in practice, having different top-level directories caused -difficulties for everyone involved---users, package authors, site -administrators, and system distributors. - -Please contrast this approach with the \replaceable{implementation} -top-level subdirectory (Section~\ref{sec:Top-level directories}), which -is to be used for configuration files that (presumably) do not use -\TeX{} syntax and in any case should not be found along the main \TeX{} -input search path. - - -\subsection{Fonts} -\label{sec:Fonts} - -Font files are stored in separate directories, segregated by file type, -and then (in most cases) font supplier and typeface. \abbr{PK} and -\abbr{GF} files need additional structure, as detailed in the next -section. - -\begin{ttdisplay} -texmf/fonts/\replaceable{type}/\replaceable{supplier}/\replaceable{typeface}/ -texmf/fonts/enc,lig,map/\replaceable{subpath}/ -\end{ttdisplay} - -\begin{description} - -\item[\replaceable{type}] is the type of font file. The \abbr{TDS} -reserves the following \replaceable{type} names for common \TeX{} file -types: - -\begin{itemize-squeeze} -\item \path|afm|, for Adobe font metrics, and \path|inf| files. -\item \path|gf|, for generic font bitmap files. -\item \path|opentype|, for OpenType fonts. -\item \path|pk|, for packed bitmap files. -\item \path|source|, for font sources (\MF{} files, property lists, etc.). -\item \path|tfm|, for \TeX{} font metric files. -\item \path|truetype|, for TrueType fonts. -\item \path|type1|, for PostScript Type 1 fonts (in \path|pfa|, - \path|pfb|, or any other format), and \path|pfm| files. -\item \path|type3|, for PostScript Type 3 fonts. -\item \path|vf|, for virtual fonts. -\end{itemize-squeeze} - -The \abbr{TDS} also reserves the names \path|enc|, \path|lig|, and -\path|map| for font encoding, ligature, and mapping files, respectively. -All of these directories are structured the same way, with -\replaceable{syntax} subdirectories, and then \replaceable{package} -subsubdirectories. Each of these file types is intended to be searched -along its own recursively-searched path. The names of the actual files -must be unique within their subtree, as usual. Examples: -\begin{ttdisplay} -fonts/map/dvipdfm/updmap/dvipdfm.map -fonts/map/dvips/lm/lm.map -fonts/enc/dvips/base/8r.enc -\end{ttdisplay} - -The Fontname and Dvips packages have more examples of the \path|enc| and -\path|map| types. The \path|afm2pl| program uses \path|lig| files. - -\path|pfm| files are included in the \path|type1| directory, instead of -being given their own directory, for two reasons: 1)~a \path|.pfm| file -is always an adjunct to a given \path|.pfb| file; 2)~they must be -installed from the same directory for Windows programs other than \TeX{} -to use them. - -\path|inf| files are included in the \path|afm| directory, since -an \path|inf| and \path|afm| file can be used to generate a \path|pfm|. -(Unfortunately, Adobe Type Manager and perhaps other software requires -that the \path|pfb| be in the same directory as \path|afm| and -\path|inf| for installation.) - -As usual, a site may omit any of these directories that are unnecessary. -\path|gf| is a particularly likely candidate for omission. - -\item[\replaceable{supplier}] is a name identifying font source -(examples: \path|adobe|, \path|ams|, \path|public|). The \abbr{TDS} -reserves the following \replaceable{supplier} names: - -\begin{itemize} - -\item \path|ams|, for the American Mathematical Society's \AmS{}-fonts -collection. - -\item \path|local|, for local additions. See Section~\ref{sec:Local additions}. - -\item \path|public|, for freely redistributable fonts where the supplier -neither (1)~requested their own directory (e.g., \path|ams|), nor -(2)~also made proprietary fonts (e.g., \path|adobe|). It does not -contain all extant freely distributable fonts, nor are all files therein -necessarily strictly public domain. - -\item \path|tmp|, for dynamically-generated fonts, as is traditional on -some systems. It may be omitted if unnecessary, as usual. - -\end{itemize} - - -\item[\replaceable{typeface}] is the name of a typeface family -(examples: \path|cm|, \path|euler|, \path|times|). The \abbr{TDS} -reserves the following \replaceable{typeface} names: - -\begin{itemize} - -\item \path|cm| (within \path|public|), for the 75 fonts defined in -\citetitle{Computers and Typesetting, Volume~E}. - -\item \path|latex| (within \path|public|), for those fonts distributed -with \LaTeX{} in the base distribution. - -\item \path|local|, for local additions. See Section~\ref{sec:Local additions}. - -\end{itemize} - -\end{description} - -Some concrete examples: -\begin{ttdisplay} -texmf/fonts/source/public/pandora/pnr10.mf -texmf/fonts/tfm/public/cm/cmr10.tfm -texmf/fonts/type1/adobe/utopia/putr.pfa -\end{ttdisplay} - -For complete supplier and typeface name lists, consult -\citetitle{Filenames for \TeX{} fonts} (see Appendix~\ref{sec:Related -references}). - -\subsubsection{Font bitmaps} - -Font bitmap files require two characteristics in addition to the above -to be uniquely identifiable: (1)~the type of device (i.e., mode) for -which the font was created; (2)~the resolution of the bitmap. - -Following common practice, the \abbr{TDS} segregates fonts with -different device types into separate directories. See \path|modes.mf| -in Appendix~\ref{sec:Related references} for recommended mode names. - -Some printers operate at more than one resolution (e.g., at 300\,dpi and -600\,dpi), but each such resolution will necessarily have a different -mode name. Nothing further is needed, since implicit in the \TeX{} -system is the assumption of a single target resolution. - -Two naming strategies are commonly used to identify the resolution of -bitmap font files. On systems that allow long filenames (and in the -original \MF{} program itself), the resolution is included in the -filename (e.g., \path|cmr10.300pk|). On systems which do not support -long filenames, fonts are generally segregated into directories by -resolution (e.g., \path|dpi300/cmr10.pk|). - -Because the \abbr{TDS} cannot require long filenames, we must use the -latter scheme for naming fonts. So we have two more subdirectory -levels under \path|pk| and \path|gf|: - -\begin{ttdisplay} -texmf/fonts/pk/\replaceable{mode}/\replaceable{supplier}/\replaceable{typeface}/dpi\replaceable{nnn}/ -texmf/fonts/gf/\replaceable{mode}/\replaceable{supplier}/\replaceable{typeface}/dpi\replaceable{nnn}/ -\end{ttdisplay} - -\begin{description} - -\item[\replaceable{mode}] is a name which identifies the device type -(examples: \path|cx|, \path|ljfour|, \path|modeless|). Usually, this is -the name of the \MF{} mode used to build the \abbr{PK} file. For fonts -rendered as bitmaps by a program that does not distinguish between -different output devices, the \replaceable{mode} name shall be simply -\path|modeless|. The \replaceable{mode} level shall not be omitted, -even if only a single mode happens to be in use. - -\item[\path|dpi|\replaceable{nnn}] specifies the resolution of the font -(examples: \path|dpi300|, \path|dpi329|). `\literal{dpi}' stands for -dots per inch, i.e., pixels per inch. We recognize that pixels per -millimeter is used in many parts of the world, but dpi is too -traditional in the \TeX{} world to consider changing now. - -The integer \replaceable{nnn} is to be calculated as if using \MF{} -arithmetic and then rounded; i.e., it is the integer \MF{} uses in its -output \path|gf| filename. We recognize small differences in the -resolution are a common cause of frustration among users, however, and -recommend implementors follow the level~0 \abbr{DVI} driver standard -(see Appendix~\ref{sec:Related references}) in bitmap font searches by -allowing a fuzz of $\pm0.2$\% (with a minimum of $1$) in the -\replaceable{dpi}. - -\end{description} - -Implementations may provide extensions to the basic naming scheme, such -as long filenames (as in the original \MF{}) and font library files (as -in em\TeX{}'s \path|.fli| files), provided that the basic scheme is also -supported. - -\subsubsection{Valid font bitmaps} -\label{sec:Valid font bitmaps} - -The \abbr{TWG} recognizes that the use of short filenames has many -disadvantages. The most vexing is that it results in the creation of -dozens of different files with the same name. At a typical site, -\path|cmr10.pk| will be the filename for Computer Modern Roman 10\,pt at -5--10 magnifications for 2--3 modes. (Section~\ref{sec:Duplicate -filenames} discusses duplicate filenames in general.) - -To minimize this problem, we strongly recommend that \abbr{PK} files -contain enough information to identify precisely how they were created: -at least the mode, base resolution, and magnification used to create the -font. - -This information is easy to supply: a simple addition to the local modes -used for building the fonts with \MF{} will automatically provide the -required information. If you have been using a local modes file derived -from (or that is simply) \path|modes.mf| (see Appendix~\ref{sec:Related -references}), the required information is already in your \abbr{PK} -files. If not, a simple addition based on the code found in -\path|modes.mf| can be made to your local modes file and the \abbr{PK} -files rebuilt. - - -\subsection{Non-font \MF{} files} -\label{sec:Non-font MF files} - -Most \MF{} input files are font programs or parts of font programs and -are thus covered by the previous section. However, a few non-font input -files do exist. Such files shall be stored in: - -\begin{ttdisplay} -texmf/metafont/\replaceable{package}/ -\end{ttdisplay} - -\replaceable{package} is the name of a -\MF{} package (for example, \path|mfpic|). - -The \abbr{TDS} reserves the following \replaceable{package} names: - -\begin{itemize} - -\item \path|base|, for the standard \MF{} macro files as described in -\citetitle{The \MF{}book}, such as \path|plain.mf| and \path|expr.mf|. - -\item \path|local|, for local additions. See Section~\ref{sec:Local additions}. - -\item \path|misc|, for \MF{} packages consisting of only a single file -(for example, \path|modes.mf|). An administrator or package maintainer -may create directories for single-file packages at their discretion, -instead of using \path|misc|. - -\end{itemize} - - -\subsection{\MP{}} -\label{sec:MetaPost} - -\MP{} is a picture-drawing language developed by John Hobby, derived -from Knuth's \MF{}. Its primary purpose is to output Encapsulated \PS{} -instead of bitmaps. - -\MP{} input files and the support files for \MP{}-related utilities -shall be stored in: - -\begin{ttdisplay} -texmf/metapost/\replaceable{package}/ -\end{ttdisplay} - -\replaceable{package} is the name of a \MP{} package. At the present -writing none exist, but the \abbr{TWG} thought it prudent to leave room -for contributed packages that might be written in the future. - -The \abbr{TDS} reserves the following \replaceable{package} names: - -\begin{itemize} - -\item \path|base|, for the standard \MP{} macro files, such as -\path|plain.mp|, \path|mfplain.mp|, \path|boxes.mp|, and -\path|graph.mp|. This includes files used by \iniMP{} when dumping mem -files containing preloaded macro definitions. - -\item \path|local|, for local additions. See Section~\ref{sec:Local -additions}. - -\item \path|misc|, for \MP{} packages consisting of only a single file. -An administrator or package maintainer may create directories for -single-file packages at their discretion, instead of using \path|misc|. - -\item \path|support|, for additional input files required by \MP{} -utility programs, including a font map, a character adjustment table, -and a subdirectory containing low-level \MP{} programs for rendering -some special characters. - -\end{itemize} - - -\subsection{\BibTeX{}} -\label{sec:BibTeX} - -\BibTeX{}-related files shall be stored in: - -\begin{ttdisplay} -texmf/bibtex/bib/\replaceable{package}/ -texmf/bibtex/bst/\replaceable{package}/ -\end{ttdisplay} - -The \path|bib| directory is for \BibTeX{} database (\path|.bib|) files, -the \path|bst| directory for style (\path|.bst|) files. - -\replaceable{package} is the name of a \BibTeX{} package. The -\abbr{TDS} reserves the following \replaceable{package} names (the same -names are reserved under both \path|bib| and \path|bst|): - -\begin{itemize} - -\item \path|base|, for the standard \BibTeX{} databases and styles, such -as \path|xampl.bib|, \path|plain.bst|. - -\item \path|local|, for local additions. See Section~\ref{sec:Local -additions}. - -\item \path|misc|, for \BibTeX{} packages consisting of only a single -file. An administrator or package maintainer may create directories for -single-file packages at their discretion, instead of using \path|misc|. - -\end{itemize} - - -\subsection{Scripts} -\label{sec:Scripts} - -The top-level \path|scripts| directory is for platform-independent -executables, such as Perl, Python, and shell scripts, and Java class -files. Subdirectories under \path|scripts| are package names. This -eases creating distributions, by providing a common place for such -platform-independent programs. - -The intent is not for all such directories to be added to a user's -command search path, which would be quite impractical. Rather, these -executables are primarily for the benefit of wrapper scripts in whatever -executable directory a distribution may provide (which is not specified -by the \abbr{TDS}). - -Truly auxiliary scripts which are invoked directly by other programs, -rather than wrapper scripts, may also be placed here. That is, -\path|scripts| also serves as a platform-independent analog of the -standard Unix \path|libexec| directory. - -We recommend using extensions specifying the language (such as -\path|.pl|, \path|.py|, \path|.sh|) on these files, to help uniquely -identify the name. Since the intent of the \abbr{TDS} is for programs -in \path|scripts| not to be invoked directly by users, this poses no -inconvenience. - -For example, in the \TeX{} Live distribution, the Con\TeX{}t user-level -program \path|texexec| can exist as a small wrapper script in each -\path|bin/|\replaceable{platform}\path|/texexec| (which is outside the -\path|texmf| tree), which merely finds and calls -\path|texmf/scripts/context/perl/texexec.pl|. - -Examples: -\begin{ttdisplay} -scripts/context/perl/texexec.pl -scripts/context/ruby/examplex.rb -scripts/thumbpdf/thumbpdf.pl -\end{ttdisplay} - -The \abbr{TDS} does not specify a location for platform-dependent -binary executables, whether auxiliary or user-level. - - -\subsection{Documentation} -\label{sec:Documentation} - -Most packages come with some form of documentation: user manuals, -example files, programming guides, etc. In addition, many independent -files not part of any macro or other package have been created to -describe various aspects of the \TeX{} system. - -The \abbr{TDS} specifies that these additional documentation files shall -be stored in a structure that parallels to some extent the -\path|fonts| and \path|tex| directories, as follows: - -\begin{ttdisplay} -texmf/doc/\replaceable{category}/... -\end{ttdisplay} - -\replaceable{category} identifies the general topic of documentation -that resides below it; for example, a \TeX{} format name (\path|latex|), -program name (\path|bibtex|, \path|tex|), language (\path|french|, -\path|german|), a file format (\path|info|, \path|man|), or other system -components (\path|web|, \path|fonts|). - -One possible arrangement is to organize \path|doc| by language, with all -the other category types below that. This helps users find -documentation in the language(s) in which they are fluent. Neither this -nor any other particular arrangement is required, however. - -Within each \replaceable{category} tree for a \TeX{} format, the -directory \path|base| is reserved for base documentation distributed by -the format's maintainers. - -The \abbr{TDS} reserves the following category names: - -\begin{itemize} - -\item \path|general|, for standalone documents not specific to any -particular program (for example, Joachim Schrod's \citetitle{Components -of \TeX{}}). - -\item \path|help|, for meta-information, such as \abbr{faq}'s, -the \TeX{} Catalogue, etc. - -\item \path|info|, for processed Texinfo documents. (Info files, like -anything else, may also be stored outside the \abbr{TDS}, at the -installer's option.) - -\item \path|local|, for local additions. See Section~\ref{sec:Local -additions}. - -\end{itemize} - -The \path|doc| directory is intended for implementation-independent and -operating system-independent documentation -files. Implementation-dependent files are best stored elsewhere, as -provided for by the implementation and/or \TeX{} administrator (for -example, \abbr{VMS} help files under \path|texmf/vms/help|). - -The documentation directories may contain \TeX{} sources, \abbr{DVI} -files, \PS{} files, text files, example input files, or any other useful -documentation format(s). - -See Section~\ref{sec:Documentation tree summary} for a summary. - - -\newpage -\section{Summary} -\label{sec:Summary} - -A skeleton of a \abbr{TDS} \texmf{} directory tree. This is not to -imply these are the only entries allowed. For example, \path|local| may -occur at any level. - -\begin{tdsSummary} - bibtex/ \BibTeX{} input files - . bib/ \BibTeX{} databases - . . base/ base distribution (e.g., \path|xampl.bib|) - . . misc/ single-file databases - . <package>/ name of a package - . bst/ \BibTeX{} style files - . . base/ base distribution (e.g., \path|plain.bst|, \path|acm.bst|) - . . misc/ single-file styles - . <package>/ name of a package - doc/ see Section~\ref{sec:Documentation} and the summary below - fonts/ font-related files - . <type>/ file type (e.g., \path|pk|) - . . <mode>/ type of output device (for \path|pk| and \path|gf| only) - . . . <supplier>/ name of a font supplier (e.g., \path|public|) - . . . . <typeface>/ name of a typeface (e.g., \path|cm|) - . . . . . dpi<nnn>/ font resolution (for \path|pk| and \path|gf| only) - <implementation>/ \TeX{} implementations, by name (e.g., \path|emtex|) - local/ files created or modified at the local site - metafont/ \MF{} (non-font) input files - . base/ base distribution (e.g., \path|plain.mf|) - . misc/ single-file packages (e.g., \path|modes.mf|) - . <package>/ name of a package (e.g., \path|mfpic|) - metapost/ \MP{} input and support files - . base/ base distribution (e.g., \path|plain.mp|) - . misc/ single-file packages - . <package>/ name of a package - . support/ support files for \MP{}-related utilities - mft/ \path|MFT| inputs (e.g., \path|plain.mft|) - <program>/ \TeX{}-related programs, by name (e.g., \path|dvips|) - source/ program source code by name (e.g., \path|latex|, \path|web2c|) - tex/ \TeX{} input files - . <engine>/ name of an engine (e.g., \path|aleph|); can also be lower - . <format>/ name of a format (e.g., \path|plain|) - . . base/ base distribution for format (e.g., \path|plain.tex|) - . . misc/ single-file packages (e.g., \path|webmac.tex|) - . . local/ local additions to or local configuration files for \replaceable{format} - . . <package>/ name of a package (e.g., \path|graphics|, \path|mfnfss|) - . generic/ format-independent packages - . . hyphen/ hyphenation patterns (e.g., \path|hyphen.tex|) - . . images/ image input files (e.g., Encapsulated PostScript) - . . misc/ single-file format-independent packages (e.g., \path|null.tex|). - . . <package>/ name of a package (e.g., \path|babel|) -\end{tdsSummary} - - -\newpage -\subsection{Documentation tree summary} -\label{sec:Documentation tree summary} - -An example skeleton of a \abbr{TDS} directory tree under -\path|texmf/doc|. This is not to imply these are the only entries -allowed, or that this structure must be followed precisely for the -entries listed. - -As mentioned, the \path|texmf/doc| tree may be organized by language, so -that all documentation in French, say, is in a \path|french| -subdirectory. In that case, the example structure here would be in a -given language directory. - -\begin{tdsSummary} - ams/ - . amsfonts/ \path|amsfonts.faq|, \path|amfndoc| - . amslatex/ \path|amslatex.faq|, \path|amsldoc| - . amstex/ \path|amsguide|, \path|joyerr| - bibtex/ \BibTeX{} - . base/ \path|btxdoc.tex| - fonts/ - . fontname/ \citetitle{Filenames for \TeX{} fonts} - . oldgerm/ \path|corkpapr| - <format>/ name of a \TeX{} format (e.g., \path|generic|, \path|latex|) - . base/ for the base distribution - . misc/ for contributed single-file package documentation - . <package>/ for \emphasis{package} - general/ across programs, generalities - . errata/ \path|errata|, \path|errata[1-8]| - . texcomp/ \citetitle{Components of \TeX{}} - help/ meta-information - . ctan/ info about \abbr{ctan} mirror sites - . faq/ \abbr{faq}s of \path|comp.text.tex|, etc. - info/ \abbr{gnu} Info files, made from Texinfo sources - latex/ example of \replaceable{format} - . base/ \path|ltnews*|, \path|*guide|, etc. - . graphics/ \path|grfguide| - local/ site-specific documentation - man/ Unix man pages - <program>/ \TeX{}-related programs, by name (examples follow) - metafont/ \path|mfbook.tex|, \path|metafont-for-beginners|, etc. - metapost/ \path|mpman|, \path|manfig|, etc. - tex/ \path|texbook.tex|, \citetitle{A Gentle Introduction to \TeX{}}, etc. - web/ \path|webman|, \path|cwebman| -\end{tdsSummary} - - -\newpage -\appendix - -\section{Unspecified pieces} - -The \abbr{TDS} cannot address the following aspects of a functioning -\TeX{} system: - -\begin{enumerate} - -\item The location of executable programs: this is too site-dependent -even to recommend a location, let alone require one. A site may place -executables outside the \texmf{} tree altogether (e.g., -\path|/usr/local/bin|), in a platform-dependent directory within -\texmf{}, or elsewhere. - -\item Upgrading packages when new releases are made: we could find no -way of introducing version specifiers into \texmf{} that would do more -good than harm, or that would be practical for even a plurality of -installations. - -\item The location of implementation-specific files (e.g., \TeX{} -\path|.fmt| files): by their nature, these must be left to the -implementor or \TeX{} maintainer. See Section~\ref{sec:Example -implementation-specific trees}. - -\item Precisely when a package or file should be considered ``local'', -and where such local files are installed. See Section~\ref{sec:Local -additions} for more discussion. - -\end{enumerate} - - -\subsection{Portable filenames} -\label{sec:Portable filenames} - -The \abbr{TDS} cannot require any particular restriction on filenames in -the tree, since the names of many existing \TeX{} files conform to no -standard scheme. For the benefit of people who wish to make a portable -\TeX{} distribution or installation, however, we outline here the -necessary restrictions. The \abbr{TDS} specifications themselves are -compatible with these. - -\abbr{ISO}-9660 is the only universally acceptable file system format -for \abbr{CD-ROM}s. A subset thereof meets the stringent limitations of -all operating systems in use today. It specifies the following: - -\begin{itemize-squeeze} - -\item File and directory names, not including any directory path or -extension part, may not exceed eight characters. - -\item Filenames may have a single extension. Extensions may not exceed -three characters. Directory names may not have an extension. - -\item Names and extensions may consist of \emphasis{only} the characters -\literal{A}--\literal{Z}, \literal{0}--\literal{9}, and underscore. -Lowercase letters are excluded. - -\item A period separates the filename from the extension and is always -present, even if the name or extension is missing (e.g., -\path|FILENAME.| or \path|.EXT|). - -\item A version number, ranging from 1--32767, is appended to the file -extension, separated by a semicolon (e.g., \path|FILENAME.EXT;1|). - -\item Only eight directory levels are allowed, including the top-level -(mounted) directory (see Section~\ref{sec:Rooting the tree}). Thus, the -deepest valid \abbr{ISO}-9660 path is: -\begin{ttdisplay} -texmf/L2/L3/L4/L5/L6/L7/L8/FOO.BAR;1 -1 2 3 4 5 6 7 8 -\end{ttdisplay} -The deepest \abbr{TDS} path needs only seven levels: -\begin{ttdisplay} -texmf/fonts/pk/cx/public/cm/dpi300/cmr10.pk -1 2 3 4 5 6 7 -\end{ttdisplay} - -\end{itemize-squeeze} - -Some systems display a modified format of \abbr{ISO}-9660 names, -mapping alphabetic characters to lowercase, removing version numbers and -trailing periods, etc. - -Before the December 1996 release, \LaTeX{} used mixed-case names for -font descriptor files. Fortunately, it never relied on case alone to -distinguish among the files. Nowadays, it uses only monocase names. - -\section{Implementation issues} - -We believe that the \abbr{TDS} can bring a great deal of order to the -current anarchic state of many \TeX{} installations. In addition, by -providing a common frame of reference, it will ease the burden of -documenting administrative tasks. Finally, it is a necessary part of -any reasonable system of true ``drop-in'' distribution packages for -\TeX{}. - - -\subsection{Adoption of the \abbr{TDS}} - -[This section is retained for historical purposes; the \abbr{TDS} -is now quite firmly entrenched in most \TeX{} distributions.] - -We recognize that adoption of the \abbr{TDS} will not be immediate or -universal. Most \TeX{} administrators will not be inclined to make the -final switch until: - -\begin{itemize-squeeze} -\item Clear and demonstrable benefits can be shown for the \abbr{TDS}. -\item \abbr{TDS}-compliant versions of all key programs are available -in ported, well-tested forms. -\item A ``settling'' period has taken place, to flush out problems. The -public release of the first draft of this document was the first step in -this process. -\end{itemize-squeeze} - -Consequently, most of the first trials of the \abbr{TDS} will be made by -members of the \abbr{TDS} committee and/or developers of \TeX{}-related -software. This has already taken place during the course of our -deliberations (see Appendix~\ref{sec:Related references} for a sample -tree available electronically). They will certainly result in the -production of a substantial number of \abbr{TDS}-compliant packages. -Indeed, the \application{te\TeX{}} and \application{\TeX{} Live} -distributions are \abbr{TDS}-compliant and in use now at many sites. - -Once installable forms of key \abbr{TDS}-compliant packages are more -widespread, some \TeX{} administrators will set up \abbr{TDS}-compliant -trees, possibly in parallel to existing production directories. This -testing will likely flush out problems that were not obvious in the -confined settings of the developers' sites; for example, it should help -to resolve system and package dependencies, package interdependencies, and -other details not addressed by this \abbr{TDS} version. - -After most of the dust has settled, hopefully even conservative \TeX{} -administrators will begin to adopt the \abbr{TDS}. Eventually, most -\TeX{} sites will have adopted the common structure, and most packages -will be readily available in \abbr{TDS}-compliant form. - -We believe that this process will occur relatively quickly. The -\abbr{TDS} committee spans a wide range of interests in the \TeX{} -community. Consequently, we believe that most of the key issues -involved in defining a workable \abbr{TDS} definition have been covered, -often in detail. \TeX{} developers have been consulted about -implementation issues, and have been trying out the \abbr{TDS} -arrangement. Thus, we hope for few surprises as implementations mature. - -Finally, there are several (current or prospective) publishers of \TeX{} -\abbr{CD-ROM}s. These publishers are highly motivated to work out -details of \abbr{TDS} implementation, and their products will provide -inexpensive and convenient ways for experimentally-minded \TeX{} -administrators to experiment with the \abbr{TDS}. - - -\subsection{More on subdirectory searching} -\label{sec:More on subdirectory searching} - -Recursive subdirectory searching is the ability to specify a search not -only of a specified directory \replaceable{d}, but recursively of all -directories below \replaceable{d}. - -Since the \abbr{TDS} specifies precise locations for most files, with no -extra levels of subdirectories allowed, true recursive searching is not -actually required for a \abbr{TDS}-compliant implementation. We do, -however, strongly recommend recursive searching as the most -user-friendly and natural approach to the problem, rather than -convoluted methods to specify paths without recursion. - -This feature is already supported by many implementations of \TeX{} and -companion utilities, for example \abbr{DECUS} \TeX{} for \abbr{VMS}, -\application{Dvips(k)}, \application{em\TeX{}} (and its drivers), -\application{PubliC \TeX{}}, \application{Web2C}, \application{Xdvi(k)}, -and \application{Y\&Y\TeX{}}. The Kpathsea library is a reusable -implementation of subdirectory searching for \TeX{}, used in a number of -the above programs. - -Even if your \TeX{} implementation does not directly support -subdirectory searching, you may find it useful to adopt the structure if -you do not use many fonts or packages. For instance, if you only use -Computer Modern and \abbr{ams} fonts, it would be feasible to store them -in the \abbr{TDS} layout and list the directories individually in -configuration files or environment variables. - -The \abbr{TWG} recognizes that subdirectory searching places an extra -burden on the system and may be the source of performance bottlenecks, -particularly on slower machines. Nevertheless, we feel that -subdirectory searching is imperative for a well-organized \abbr{TDS}, -for the reasons stated in Section~\ref{sec:Subdirectory searching}. -Implementors are encouraged to provide enhancements to the basic -principle of subdirectory searching to avoid performance problems, e.g., -the use of a filename cache (this can be as simple as a recursive -directory listing) that is consulted before disk searching begins. If a -match is found in the database, subdirectory searching is not required, -and performance is thus independent of the number of subdirectories -present on the system. - -Different implementations specify subdirectory searching differently. -In the interest of typographic clarity, the examples here do not use the -\replaceable{replaceable} font. - -\begin{description-squeeze} - -\item[\application{Dvips}:] via a separate -\systemitem{ENVIRONVAR}{TEXFONTS\_SUBDIR} environment variable. - -\item[\application{em\TeX{}}:] \path|t:\subdir!!|; \path|t:\subdir!| for -a single level of searching. - -\item[\application{Kpathsea}:] \path|texmf/subdir//| - -\item[\abbr{VMS}:] \path|texmf:[subdir...]| - -\item[\application{Xdvi} (patchlevel 20):] \path|texmf/subdir/**|; -\path|texmf/subdir/*| for a single level of searching. Version 20.50 -and above support the \path|//| notation. - -\item[\application{Y\&Y \TeX{}}:] \path|t:/subdir//| or -\path|t:\subdir\\|. - -\end{description-squeeze} - - -\subsection{Example implementation-specific trees} -\label{sec:Example implementation-specific trees} - -The \abbr{TDS} cannot specify a precise location for -implementation-specific files, such as \path|texmf/ini|, because a site -may have multiple \TeX{} implementations. - -Nevertheless, for informative purposes, we provide here the default -locations for some implementations. Please contact us with additions or -corrections. These paths are not definitive, may not match anything at -your site, and may change without warning. - -We recommend all implementations have default search paths that start -with the current directory (e.g., `\path|.|'). Allowing users to -include the parent directory (e.g., `\path|..|') is also helpful. - - -\subsubsection{AmiWeb2c 2.0} - -(Email \email|scherer@physik.rwth-aachen.de| to contact the maintainer -of this implementation.) - -AmiWeb2c 2 is compatible with Web2c 7 to the greatest possible -extent, so only the very few differences are described in this -section. Detailed information about the basic concepts is given in -the section for Web2c 7 below. - -Thanks to the \path|SELFAUTO| mechanism of Kpathsea 3.0 no specific -location for the installation of AmiWeb2c is required as long as the -general structure of the distribution is preserved. - -In addition to Kpathsea's \path|//| notation recursive path search may -also be started by \replaceable{DEVICE}\path|:/|, e.g., \path|TeXMF:/| -will scan this specific device completely. - -Binaries coming with the AmiWeb2c distribution are installed in the -directory \path|bin/amiweb2c/| outside the common \abbr{TDS} tree -\path|share/texmf/|. In addition to the set of AmiWeb2c binaries -you will find two subdirectories \path|local/| and \path|pastex/| -with auxiliary programs. - -A stripped version of the Pas\TeX{} system (used by kind permission of -Georg He\ss{}mann) is coming with AmiWeb2c, pre-installed in its own -\path|share/texmf/amiweb2c/pastex/| directory. If you want to use -Pas\TeX{} you have to \path|assign| the name \path|TeX:| to this place. - -Documentation files in AmigaGuide format should be stored at -\path|doc/guide/| similar to \path|doc/info/|. - - -\subsubsection{Public \abbr{DECUS} \TeX{}} - -If another \abbr{VMS} implementation besides Public \abbr{DECUS} \TeX{} -appears, the top level implementation directory name will be modified to -something more specific (e.g., \path|vms_decus|). - -\begin{tdsSummary} - texmf/ - . vms/ \abbr{VMS} implementation specific files - . . exe/ end-user commands - . . . common/ command procedures, command definition files, etc. - . . . axp/ binary executables for Alpha \abbr{AXP} - . . . vax/ binary executables for \abbr{VAX} - . . formats/ pool files, formats, bases - . . help/ \abbr{VMS} help library, and miscellaneous help sources - . . mgr/ command procedures, programs, docs, etc., for system management -\end{tdsSummary} - - -\subsubsection{Web2c 7} - -All implementation-dependent \TeX{} system files (\path|.pool|, -\path|.fmt|, \path|.base|, \path|.mem|) are stored by default directly -in \path|texmf/web2c|. The configuration file \path|texmf.cnf| and -various subsidiary \path|MakeTeX...| scripts used as subroutines are -also stored there. - -Non-\TeX{} specific files are stored following the \abbr{GNU} coding -standards. Given a root directory \replaceable{prefix} -(\path|/usr/local| by default), we have default locations as follows: - -\begin{tdsSummary} - <prefix>/ installation root (\path|/usr/local| by default) - . bin/ executables - . man/ man pages - . info/ info files - . lib/ libraries (\path|libkpathsea.*|) - . share/ architecture-independent files - . . texmf/ \abbr{TDS} root - . . . web2c/ implementation-dependent files (\path|.pool|, \path|.fmt|, \path|texmf.cnf|, etc.) -\end{tdsSummary} - -See \url|http://www.gnu.org/prep/standards_toc.html| for the -rationale behind and descriptions of this arrangement. A site may of -course override these defaults; for example, it may put everything under -a single directory such as \path|/usr/local/texmf|. - - -\section{Is there a better way?} - -Defining the \abbr{TDS} required many compromises. Both the overall -structure and the details of the individual directories were arrived at -by finding common ground among many opinions. The driving forces were -feasibility (in terms of what could technically be done and what could -reasonably be expected from developers) and regularity (files grouped -together in an arrangement that ``made sense''). - -Some interesting ideas could not be applied due to implementations -lacking the necessary support: - -\begin{itemize} - -\item Path searching control at the \TeX{} level. If documents could -restrict subdirectory searching to a subdirectory via some portable -syntax in file names, restrictions on uniqueness of filenames could be -relaxed considerably (with the cooperation of the formats), and the -\TeX{} search path would not need to depend on the format. - -\item Multiple logical \texmf{} trees. For example, a site might have -one (read-only) location for stable files, and a different (writable) -location for dynamically-created fonts or other files. It would be -reasonable for two such trees to be logically merged when searching. -See Michael Downes' article in the references for how this can work in -practice with Web2C. - -\end{itemize} - -\subsection{Macro structure} - -The \abbr{TWG} settled on the -\replaceable{format}\path|/|\replaceable{package} arrangement after long -discussion about how best to arrange the files. - -The primary alternative to this arrangement was a scheme which reversed -the order of these directories: -\replaceable{package}\path|/|\replaceable{format}. This reversed -arrangement has a strong appeal: it keeps all of the files related to a -particular package in a single place. The arrangement actually adopted -tends to spread files out into two or three places (macros, -documentation, and fonts, for example, are spread into different -sections of the tree right at the top level). - -Nevertheless, the \replaceable{format}\path|/|\replaceable{package} -structure won for a couple of reasons: - -\begin{itemize-squeeze} -\item It is closer to current practice; in fact, several members of the -\abbr{TWG} have already implemented the \abbr{TDS} hierarchy. The -alternative is not in use at any known site, and the \abbr{TWG} felt it -wrong to mandate something with which there is no practical experience. - -\item The alternative arrangement increases the number of top-level -directories, so the files that must be found using subdirectory -searching are spread out in a wide, shallow tree. This could have a -profound impact on the efficiency of subdirectory searching. - -\end{itemize-squeeze} - - -\subsection{Font structure} - -The \abbr{TWG} struggled more with the font directory structure than -anything else. This is not surprising; the need to use the proliferation -of PostScript fonts with \TeX{} is what made the previous arrangement -with all files in a single directory untenable, and therefore what -initiated the \abbr{TDS} effort. - - -\subsubsection{Font file type location} - -We considered the supplier-first arrangement in use at many sites: - -\begin{ttdisplay} -texmf/fonts/\replaceable{supplier}/\replaceable{typeface}/\replaceable{type}/ -\end{ttdisplay} - -This improves the maintainability of the font tree, since all files -comprising a given typeface are in one place, but unless all the -programs that search this tree employ some form of caching, there are -serious performance concerns. For example, in order to find a -\path|TFM| file, the simplest implementation would require \TeX{} to -search through all the directories that contain \abbr{PK} files in all -modes and at all resolutions. - -In the end, a poll of developers revealed considerable resistance to -implementing sufficient caching mechanisms, so this arrangement was -abandoned. The \abbr{TDS} arrangement allows the search tree to be -restricted to the correct type of file, at least. Concerns about -efficiency remain, but there seems to be no more we can do without -abandoning subdirectory searching entirely. - -We also considered segregating all font-related files strictly by file -type, so that \MF{} sources would be in a directory -\path|texmf/fonts/mf|, property list files in \path|texmf/fonts/pl|, the -various forms of Type~1 fonts separated, and so on. Although more -blindly consistent, we felt that the drawback of more complicated path -constructions outweighed this. The \abbr{TDS} merges file types -(\path|mf| and \path|pl| under \path|source|, \path|pfa| and \path|pfb| -and \path|gsf| under \path|type1|) where we felt this was beneficial. - - -\subsubsection{Mode and resolution location} - -We considered having the \path|mode| at the bottom of the font tree: -\begin{ttdisplay} -texmf/fonts/pk/\replaceable{supplier}/\replaceable{typeface}/\replaceable{mode}/\replaceable{dpi}/ -\end{ttdisplay} - -In this case, however, it is difficult to limit subdirectory searching -to the mode required for a particular device. - -We then considered moving the \path|dpi|\replaceable{nnn} up to below -the mode: -\begin{ttdisplay} -texmf/fonts/pk/\replaceable{mode}/\replaceable{dpi}/\replaceable{supplier}/\replaceable{typeface}/ -\end{ttdisplay} - -But then it is not feasible to omit the \path|dpi|\replaceable{nnn} -level altogether on systems which can and do choose to use long -filenames. - - -\subsubsection{Modeless bitmaps} - -The \abbr{TDS} specifies using a single directory \path|modeless/| as -the mode name for those utilities which generate bitmaps, e.g., -\path|texmf/fonts/modeless/times/|. This has the considerable advantage -of not requiring each such directory name to be listed in a search path. - -An alternative was to use the utility name below which all such -directories could be gathered. That has the advantage of separating, -say, \path|gsftopk|-generated bitmaps from \path|ps2pk|-generated ones. -However, we decided this was not necessary; most sites will use only one -program for the purpose. Also, \abbr{PK} and \abbr{GF} fonts generally -identify their creator in the font comment following the \path|PK_ID| -byte. - -We are making an implicit assumption that \MF{} is the only program -producing mode-dependent bitmaps. If this becomes false we could add an -abbreviation for the program to mode names, as in \path|mfcx| vs.\ -\path|xyzcx| for a hypothetical program \application{Xyz}, or we could -at that time add an additional program name level uniformly to the tree. -It seemed more important to concisely represent the current situation -than to worry about hypothetical possibilities that may never~happen. - - -\subsection{Documentation structure} - -We considered placing additional documentation files in the same -directory as the source files for the packages, but we felt that users -should be able to find documentation separately from sources, since most -users have no interest in sources. - -We hope that a separate, but parallel, structure for documentation would -(1)~keep the documentation together and (2)~make it as straightforward -as possible for users to find the particular documentation they were -after. - - -\section{Related references} -\label{sec:Related references} - -This appendix gives pointers to related files and other documents. For -\abbr{CTAN} references, we use \path|http://www.ctan.org| as the -top-level domain only to make the links be live in this document. See -\url|http://www.ctan.org/tex-archive/CTAN.sites| for a complete list of -\abbr{ctan} sites; there are mirrors worldwide. - -\begin{itemize-squeeze} - -\item This document, in many formats (tex, dvi, info, pdf):\\ \hspace*{1em} -\url|http://tug.org/tds/| - -\item The \abbr{TDS} mailing list archives:\\ \hspace*{1em} -\url|http://tug.org/mail-archives/twg-tds/| - -\item The level~0 \abbr{DVI} driver standard:\\ \hspace*{1em} -\url|http://www.ctan.org/tex-archive/dviware/driv-standard/level-0/| - -\item \citetitle{Filenames for \TeX{} fonts}, with lists of recommended -supplier and typeface names:\\ \hspace*{1em} -\url|http://tug.org/fontname/| - -\item \abbr{ISO}-9660 \abbr{CD-ROM} file system standard:\\ \hspace*{1em} -\url|http://www.iso.ch/cate/cat.html| - -\item \citetitle{Components of \TeX{}}, a paper by Joachim -Schrod:\\ \hspace*{1em} -\url|http://www.ctan.org/tex-archive/documentation/components-of-TeX/| - -\item \citetitle{Managing Multiple TDS trees}, an article by Michael -Downes:\\ \hspace*{1em} -\url|http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf| - -\item A complete set of \MF{} modes:\\ \hspace*{1em} -\url|http://www.ctan.org/tex-archive/fonts/modes/modes.mf| - -\item A large collection of \BibTeX{} databases and styles:\\ \hspace*{1em} -\url|ftp://ftp.math.utah.edu/pub/tex/bib/| - -\end{itemize-squeeze} - - -\section{Contributors} - -The \abbr{TWG} has had no physical meetings; electronic mail was the -communication medium. - -Sebastian Rahtz is the \TeX{} Users Group Technical Council liaison. -Norman Walsh was the original committee chair. Karl Berry is the -current editor. - -The list of contributors has grown too large to fairly include, as some -would surely be inadvertently omitted. Please consider the archives of -the \email|tds@tug.org| and \email|tex-live@tug.org| mailing lists as -the record of contributions. - - -\end{document} diff --git a/tds/tds2texi.el b/tds/tds2texi.el deleted file mode 100644 index de87d40430..0000000000 --- a/tds/tds2texi.el +++ /dev/null @@ -1,577 +0,0 @@ -;;; 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@thphy.uni-duesseldorf.de> -;; Maintainer: karl@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@chapter \\1") - )) - (save-excursion - (save-restriction - (narrow-to-region - (search-forward "\\appendix" nil t) (point-max)) - (tds2texi-regexp-replace - "\\\\section{\\([^}]+\\)}[ ]*" "@node \\1\n@appendix \\1") - )) - - ;; @section and @subsection are just shifted a level up - (tds2texi-regexp-replace - "\\\\subsection{\\([^}]+\\)}[ ]*" "@node \\1\n@section \\1") - (tds2texi-regexp-replace - "\\\\subsubsection{\\([^}]+\\)}[ ]*" "@node \\1\n@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@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@top " title-string "\n\n") - - ;; insert contents of `legalnotice' copied above - (yank) ; should include a "\n\n" at the end - - (insert "@menu\n@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@contents\n@end iftex\n@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 diff --git a/tds/tdsguide.cls b/tds/tdsguide.cls deleted file mode 100644 index 4526776258..0000000000 --- a/tds/tdsguide.cls +++ /dev/null @@ -1,845 +0,0 @@ -% $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@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@reduced@size{% - \dimen@\f@size\p@ - \advance \dimen@ -\p@ % dimen@ = font_size - 1 - \ifdim \dimen@ >12\p@ - \@font@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@fontsfalse - \fontsize{\the\dimen@}\z@ - \selectfont - } -\def\abbr#1{{\tds@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@skip % no skip before env - \parskip\z@skip - \relax - }% - \item\relax - \parshape\z@ - %% code below is copied from alltt.dtx. - \leftskip\@totalleftmargin - \@tempswafalse - \def\par{% - \if@tempswa - \leavevmode\null\@@par\penalty\interlinepenalty - \else - \@tempswatrue - \ifhmode - \@@par - \penalty\interlinepenalty - \fi - \fi - }% - \obeylines - \verbatim@font - \let\org@prime~% - \@noligs - \everymath \expandafter{\the\everymath \let~\org@prime}% - \everydisplay \expandafter{\the\everydisplay \let~\org@prime}% - \let\org@dospecials\dospecials - \g@remfrom@specials{\\}% - \g@remfrom@specials{\{}% - \g@remfrom@specials{\}}% - \let\do\@makeother \dospecials - \let\dospecials\org@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@remfrom@specials#1{% - \def\@new@specials{}% - \def\@remove##1{% - \ifx ##1#1% - \else - \g@addto@macro\@new@specials{\do ##1}% - \fi - }% - \let\do\@remove \dospecials - \let\dospecials\@new@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@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@smsize{% - $\m@th$% % force math size calculation - \csname S@\f@size\endcsname - \fontsize\sf@size\z@ - \math@fontsfalse \selectfont - } - -\def\BibTeX{B\kern-.05em{\tds@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@skip - \itemize - }{% - \enditemize - } - -% Ditto, for description. - -\newenvironment{description-squeeze} - {% - \parsep\z@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@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@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@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@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@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@section[2]{% - \ifnum \c@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@xt@\@pnumwidth{\hss #2}\par - \endgroup - \fi} -\def\l@section#1#2{% - \ifnum \c@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@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@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: |