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