summaryrefslogtreecommitdiff
path: root/usergrps/uktug/baskervi/6_6/tex-live.tex
diff options
context:
space:
mode:
Diffstat (limited to 'usergrps/uktug/baskervi/6_6/tex-live.tex')
-rw-r--r--usergrps/uktug/baskervi/6_6/tex-live.tex1562
1 files changed, 1562 insertions, 0 deletions
diff --git a/usergrps/uktug/baskervi/6_6/tex-live.tex b/usergrps/uktug/baskervi/6_6/tex-live.tex
new file mode 100644
index 0000000000..5660597ec9
--- /dev/null
+++ b/usergrps/uktug/baskervi/6_6/tex-live.tex
@@ -0,0 +1,1562 @@
+\def\href#1#2{#2}
+\def\filedate{1997/05/23}
+\def\fileversion{3.1}
+\section{Introduction}
+This documentation describes the main features of the \TeXLive{}
+\CDROM{}, a \TeX{}/\LaTeX{} distribution for Unix, Windows32, Amiga and
+NeXT systems, that includes \TeX{}, \LaTeXe{}, \MF{}, \MP, many other
+programs such as Makeindex, dvips, xdvi and \BibTeX{}; and a very
+complete set of macros, fonts and documentation conforming to the
+\emph{\TeX{} Directory Standard} which can be used with nearly every
+\TeX{} setup.
+
+This \TeX{} package uses the \Webc{} implementation of the programs,
+which tries to make \TeX{}ing as easy as possible, and takes full
+advantage of the efficient and highly customizable Kpathsea library
+from Karl Berry. It can be run either directly from the \CDROM{}, or
+installed on a hard disk.
+
+The \TeXLive{} runnable systems contain two experimental extensions to
+normal \TeX:
+\begin{enumerate}
+\item \eTeX, which adds a small but powerful set of new primitives,
+ and the \TeXXeT{} extensions for left to right typesetting; in
+ default mode, \eTeX{} is 100\% compatible with ordinary \TeX. See
+ \path|share/texmf/doc/html/e-tex/etex.htm| on the \CDROM{} for details.
+\item pdf\TeX, which can optionally write Acrobat PDF format instead
+ of \texttt{dvi}; there is no formal documentation for this yet, but the
+ file \path|share/texmf/tex/pdftex/example.tex| shows how it is
+ used. The \LaTeX{} \texttt{hyperref} package has an option `pdftex'
+ which turns on all the program features.
+\end{enumerate}
+While \eTeX{} is stable, pdf\TeX{} is under continual development; the
+version on the \CDROM{} may not be stable. Most platforms have version
+0.11 of May 7th, but some have a slightly earlier one of May 5th,
+which may have problems including PNG files.
+
+The entire GUTenberg distribution for Windows is
+included on the \CDROM{}, ready to install, as are the following
+complete packages:
+\begin{itemize}
+\item \OzTeX{} 3.0 for Macintosh
+\item CMacTeX 2.6 for Macintosh
+\item Macintosh utilities (Alpha, Excalibur, etc.)
+\item MikTeX for Windows 95
+\item emTeX for MSDOS and OS/2
+\item \TeX{} shells for Windows
+ and DOS (Winedt, e4t, TeXtelmExtel, emTeXgi)
+\end{itemize}
+These are provided unchanged from \CTAN{}, and have not been integrated
+in any way with the rest of the \CDROM{}.
+
+\subsection{History and acknowledgements}
+
+This \CDROM{} distribution is a joint effort by the \TeX{} Users
+Group, the UK \TeX{} Users Group, and the French \TeX{} Users (GUTenberg),
+with the support of the Dutch, German and Czech/Slovak user groups.
+Discussion began in late 1993 when the Dutch \TeX{} Users Group was
+starting work on its 4All\TeX{} \CDROM{} for MSDOS users, and it was
+hoped at that time to issue a single, rational, \CDROM{} for all
+systems. This was far too ambitious a target, but it did spawn not
+only the very successful 4All\TeX{} \CDROM{}, but also the TUG
+Technical Council working group on a \emph{\TeX{} Directory
+ Structure}, which specified how to create consistent and manageable
+collections of \TeX{} support files. The final draft of the TDS was
+published in the December 1995 issue of \TUB{}, and it was clear from
+an early stage that one desirable product would be a model structure
+on \CDROM{}. The \CDROM{} you now have is a very direct result of the
+working group's deliberations. It was also clear that the success of
+the 4All\TeX{} \CDROM{} meant that Unix users would benefit from a
+similarly easy system, and this is the other main strand of \TeXLive.
+
+We undertook to make a new Unix-based TDS \CDROM{} in the autumn of 1995,
+and quickly identified Thomas Esser's \teTeX{} as the ideal setup, as
+it already had multi-platform support and was built with portability
+across file systems in mind. Thomas agreed to help, and work began
+seriously at the start of 1996. The first edition was released in May
+1996. At the start of 1997, Karl Berry completed a major new release of
+his \Webc{} package, which included nearly all the features which Thomas
+Esser had added in \teTeX, and we decided to base the 2nd edition of the
+\CDROM{} on the standard \Webc, with the addition of \teTeX's
+\texttt{texconfig} script.
+
+We are particularly grateful to: Karl Berry for extra advice,
+encouragement, and (of course) for providing the \Webc{}
+distribution; Thomas Esser, without whose marvellous \teTeX{} package
+this \CDROM{} would certainly not exist, and whose continual
+help makes it a better product; and Ulrik Vieth, for checking
+many assumptions at the start, and providing a great deal of extra
+material for the documentation tree.
+
+Fabrice Popineau did the excellent port of \Webc{} 7.0 to Windows 95/NT
+and provided much help; Andreas Scherer contributed the Amiga
+compilation; Gregor Hoffleit contributed the TeXview material
+for NextStep users, and the NextStep binaries. At Florida State
+University Supercomputer Research Institute, Mimi Burbank arranged
+access to a slew of different computers to compile \TeX{} on, and
+acted as an essential guinea-pig whenever asked. Michel Goossens
+provided access to computers at CERN, and Robin Fairbairns stepped in
+to provide an Alpha running Linux at Cambridge.
+
+Some of this documentation is drawn from the \teTeX{} guide by Thomas
+Esser and Dirk Hillbrecht; the catalogue of packages depends very much
+on the ongoing work of Graham Williams
+(\url{mailto:Graham.Williams@cbr.dit.csiro.au}), who kindly agreed to
+allow us to use it here. Mimi Burbank, Robin
+Fairbairns and Ulrik Vieth worked hard to improve this text.
+
+\subsection{Future versions}
+
+\emph{This \CDROM{} is not a perfect product!} We plan to re-issue it
+once a year, and would like to provide more help material, more
+utilities, more installation programs, and (of course) an
+ever-improved and checked tree of macros and fonts. This work is all
+done by hard-pressed volunteers in their limited spare time, and a
+great deal remains to be done. If you can help, don't hesitate to put
+your name forward!
+
+Corrections, suggestions and additions for future revisions
+should be sent to:
+\begin{quote}
+Sebastian Rahtz\\
+{}7 Stratfield Road\\
+Oxford OX2 7BG\\
+United Kingdom\\
+\url{mailto:s.rahtz@elsevier.co.uk}
+\end{quote}
+
+Updates, notes, and suggestions will be made available on \CTAN{}
+in \path|info/texlive|. A \acro{WWW} page for
+information and ordering details is at
+\url{http://www.tug.org/tex-live.html}.
+
+\section{Structure and contents of the \CDROM{}}
+The \CDROM{} top level directories are:
+\begin{description}
+\item[bin] The \TeX{} family programs, arranged in separate platform
+directories;
+\item[info] Documentation in \acro{GNU} `info' format for the \TeX{} system;
+\item[macintosh] The \OzTeX{} and CMacTeX packages ready to install, plus
+ some other utilities;
+\item[man] Documentation in Unix man pages for the \TeX{} system;
+\item[msdos] DOS \TeX{} packages\Dash emTeX, and three \TeX{}
+ shells;
+\item[support] The source of all programs, including the main
+\Webc{} \TeX{} and \MF{} distribution; this directory also
+includes various bits of \TeX-related software which are \emph{not}
+installed by default, such as Musix\TeX{} support programs, and
+a complete set of Ghostscript;
+\item[share] The main support tree of macros, fonts and documentation;
+\item[wingut] The GUTenberg distribution for Windows;
+this consists of compressed archives which must be unpacked and
+installed on a hard disk. Please see the detailed instructions in
+French;
+\item[win32] \TeX{} packages for Windows 95 and NT users (MikTeX, and
+ the original package of the Win32 port of \Webc).
+\end{description}
+
+There are also two installation scripts for Unix systems,
+\texttt{install-cd.sh} and \texttt{install-pkg.sh}; we discuss
+them on p.~\pageref{sec:install}.
+
+\subsection{The TDS tree}
+The \TeXLive{} \texttt{share/texmf} tree consists of various `collections',
+each of which has a set of `packages', of which there are over 400
+on the \CDROM{}. Normal installation allows the
+user to copy all of a collection to a local hard disk from the \CDROM{}, but
+it is also possible to install just one package of a collection.
+Each of the collections is divided into \emph{basic} (1),
+\emph{recommended} (2) and \emph{other} (3). The
+collections are:
+
+
+\begin{description}
+\item[ams] The American Mathematical Society macro packages and fonts
+\item[bibtex] \BibTeX{} styles and databases
+\item[doc] General guides and documentation in various formats, including HTML
+ and PDF
+\item[dvips] Support for Rokicki's dvi to PostScript driver
+\item[fonts] Font sources, metrics, PostScript and bitmap forms
+\item[formats] Eplain, Rev\TeX, physxx, texsis, alatex, text1, lollipop, etc.
+\item[generic] Extra macros for use with any format
+\item[graphics] Macro packages for graphics
+\item[lang] Support for non-English languages
+\item[latex] \LaTeX, including official tools and all \LaTeXe\
+ contributed packages
+\item[metapost] Support for \MP
+\item[plain] Macros for plain \TeX
+\item[systems] Binaries for Unix platforms
+\item[texlive] Basic material for the distribution
+\end{description}
+The appendix starting on p.~\pageref{cat} lists all the packages in alphabetical order with
+the collection they are found in, and a brief description. Thus all
+packages in collection \texttt{latex1} are what one must have to get
+started with \LaTeX, packages in \texttt{latex2} are recommended for
+most users, and \texttt{latex3} contains optional packages. The
+directory \texttt{share/texmf/lists} contains lists of all files in
+each package (used by the installation package).
+
+%\section{Installing and using the \CDROM{} under Unix}
+\section{Installation and use under Unix}
+\label{sec:install}
+You can use the \TeXLive{} \CDROM{} in three ways:
+\begin{enumerate}
+\item You can mount the \CDROM{} on your file system, adjust your
+ \texttt{PATH}, and run everything off the \CDROM; this takes very
+ little disk space, and gives you immediate access to everything on
+ the \CDROM; although the performance will not be optimal, it is
+ perfectly acceptable on, for instance, PCs running Linux;
+\item You can install all or part of the system to your local hard
+disk; this is the best method for many people, if they have enough
+disk space to spare (a minimum of about 10 megabytes, or 100 megabytes
+for a recommended good-sized system);
+\item You can install selected packages to work either with your
+existing \TeX{} system or a \TeXLive{} system you installed earlier.
+\end{enumerate}
+Each of these methods is described in more detail in the following
+sections.
+
+\begin{lrbox}{\warnbox}
+\begin{minipage}{.46\textwidth}
+\textbf{Warning: } This \CDROM{} is in ISO 9660 (High Sierra) format, with Rock Ridge
+extensions. In order to take full advantage of the
+\CDROM{} on a Unix system, your system needs to be able to use the
+Rock Ridge extensions. Please consult the documentation for your
+\emph{mount} command to see if it is possible.
+If you have several different machines on a local network, see
+if you can mount the \CDROM{} on one which \emph{does} support Rock Ridge,
+and use it from the others.
+
+\leavevmode\quad
+Linux, FreeBSD, Sun, SGI and DEC Alpha systems should be able to use
+the \CDROM{} with no problems. We would appreciate receiving detailed advice
+from other system users who also succeed, for future versions of this
+documentation.
+
+\leavevmode\quad
+The discussion below about installation assumes you have been able to mount
+the \CDROM{} with full Rock Ridge compatibility.
+\end{minipage}
+\end{lrbox}
+\centerline{\fbox{\usebox{\warnbox}}}
+
+\subsection{Running \TeXLive{} from the \CDROM}
+The organisation of \Webc{} means that you can run programs simply by
+adding the appropriate directory under \path|bin| on the \CDROM{} to
+your \texttt{PATH}, and the support files will all be found with no further
+ado. The following table shows the list of available directories and
+the systems they apply to.
+
+
+\begin{tabbing}
+xxxxxxxxxxxxxxxxxx\=xxxx\kill
+alpha-linux \> DEC Alpha Linux\\
+alpha-osf3.2 \> DEC Alpha OS 3.2\\
+amiweb2c \> Amiga\\
+hppa11-hpux9.05 \> HP9000 HPUX 9.05\\
+hppa11-hpux10.20 \> HP9000 HPUX 10.20\\
+i386-linux \> Intel PC with Linux (ELF)\\
+i586-freebsd2.2 \> Intel PC with Free BSD\\
+i686-linux \> Intel Pentium Pro with Linux\\
+mab-nextstep3 \> NextStep 3\\
+mips-irix4.0.5 \> SGI IRIX 4.0.5\\
+mips-irix5.3 \> SGI IRIX 5.3\\
+mips-irix6.3 \> SGI IRIX 6.3\\
+mips-ultrix4.4 \> DECstation Ultrix 4.4\\
+rs6000-aix3.2.5 \> IBM RS 6000 AIX 3.2.5\\
+rs6000-aix4.1.1 \> IBM RS 6000 AIX 4.1.1\\
+sparc-sunos4.1.3 \> Sun Sparc Sunos 4.1.3\\
+sparc-solaris2.5 \> Sun Sparc Solaris 2.5\\
+sparc-solaris2.4 \> Sun Sparc Solaris 2.4\\
+sparc-linux \> Sun Sparc Linux\\
+win32 \> Windows 95 or NT\\
+\end{tabbing}
+
+You may worry that when you subsequently make fonts or change
+configuration, things will go wrong because you cannot change files on
+the \CDROM{}. However, you can maintain a parallel, writeable, \TeX{}
+tree on your hard disk; this is searched before the main tree on the
+\CDROM{}. The default location is \path|/usr/local/texmf|, but you can
+override this by setting the \texttt{TEXMFLOCAL} environment variable.
+
+Thus \emph{sh} or \emph{bash} users on an Intel PC
+running Linux who mount the \TeXLive{} \CDROM{} on
+\file{/cdrom} by issuing the command:
+\begin{verbatim}
+mount -t iso9660 /dev/cdrom /cdrom
+\end{verbatim}
+might add the following to their \texttt{.profile} script:
+\begin{verbatim}
+PATH=/cdrom/bin/i386-linux:$PATH
+export PATH
+\end{verbatim}
+If in doubt, ask your local system support guru to help you work out
+how to mount your \CDROM{} or which directory to use for your system.
+
+Appropriate support files will be installed on your hard disk the
+first time you need them. It is a good idea to immediately run the
+\texttt{texconfig} script to initialize things, and check it all
+works.
+
+%------------------------------------------------
+\subsection{Installing \TeXLive{} to a hard disk}
+All of the necessary steps to install all or part of the distribution
+on your hard disk are achieved by mounting the \CDROM{}, changing to the
+top-level directory, and typing:
+\begin{verbatim}
+sh install-cd.sh
+\end{verbatim}
+(On some Unix systems, you may need to use \texttt{sh5} or \texttt{bsh}).
+This works by accessing lists of collections and packages from the \CDROM{},
+and trying to guess what sort of computer system you are on; it should
+start by displaying the following:
+\begin{verbatim}
+Initializing collections... Done.
+Counting selected collections... Done.
+Calculating disk space requirements for
+ collections...Done.
+Initializing system packages... Done.
+\end{verbatim}
+It will then show the main control screen
+(Figure~\ref{ins1}), which lets you change four
+things:
+\begin{enumerate}
+\item the type of system you are on, or want to install for;
+\item the collections you want to install, at \emph{basic},
+\emph{recommended} or \emph{other} level;
+\item the location on your hard disk to put the files;
+\item some runtime behaviour features.
+\end{enumerate}
+You choose options by typing a letter or number and pressing return.
+In the example, a Linux ELF system has been detected, the
+default of all collections to recommended level has been chosen, and
+the default installation directory is \path|/usr/local|; note
+that the disk space required for the current installation
+configuration is also displayed. If you make a suggested setup, you
+need about 100 megabytes of disk free; however, the basic setup will
+only take about 10 megabytes, and you can enhance it with selected
+packages as you need them.
+
+Under the directory you choose for installation, the installation
+script will put the binaries in a subdirectory of \path|bin|, and the
+support tree in \path|share/texmf|.
+
+\newsavebox{\figbox}
+\begin{figure*}[p]
+\vspace{-\baselineskip}
+\begin{lrbox}{\figbox}
+\begin{minipage}{.9\textwidth}
+\begin{sverbatim}
+===================> TeX Live installation procedure <==========
+===> Note: Letters/digits in brackets indicate menu items <===
+===> for commands or configurable options <===
+ Detected system: Intel PC with Linux (ELF)
+ <C> collections: 21 out of 30, disk space required: 163955 kB
+ <S> systems: 1 out of 20, disk space required: 7946 kB
+ total disk space required: 171901 kB
+ <D> directories:
+ TEXDIR = /usr/local
+ <O> options:
+ [ ] alternate directory for automatically generated fonts
+ [ ] create symlinks in standard directories
+ Other commands:
+ <I> start installation, <H> help, <Q> quit
+Enter command:
+\end{sverbatim}
+\end{minipage}
+\end{lrbox}
+\centerline{\fbox{\usebox{\figbox}}}
+\caption{Installation screen, example 1}\label{ins1}
+\vspace{\baselineskip}
+\begin{lrbox}{\figbox}
+\begin{minipage}{.9\textwidth}
+\begin{sverbatim}
+Current collections setup: total size : 171901 kB
+=============================================================
+ name selection size
+ <1> ams [recommended] 6359 kB
+ <2> bibtex [recommended] 6584 kB
+ <3> doc [recommended] 26531 kB
+ <4> dvips [recommended] 563 kB
+ <5> fonts [recommended] 21862 kB
+ <6> formats [recommended] 1003 kB
+ <7> generic [recommended] 501 kB
+ <8> graphics [recommended] 10373 kB
+ <9> lang [recommended] 3287 kB
+ <W> metapost [recommended] 1280 kB
+ <X> latex [recommended] 28333 kB
+ <Y> plain [recommended] 756 kB
+ <Z> texlive [recommended] 56523 kB
+ SUM: 163955 kB
+==================================================
+ global commands: select <n>one / <b>asic / r<e>commended / <a>ll
+ for all collections
+ <R> return to platform menu
+ <Q> quit
+Enter command to modify current selection:
+\end{sverbatim}
+\end{minipage}
+\end{lrbox}
+\centerline{\fbox{\usebox{\figbox}}}
+\caption{Installation screen, example 2}\label{ins2}
+\vspace{\baselineskip}
+\begin{lrbox}{\figbox}
+\begin{minipage}{.9\textwidth}
+\begin{sverbatim}
+Collection: Fonts
+==============================================================================
+Fonts, including metrics, virtual fonts and sources
+==============================================================================
+ <N> no packages
+ <B> basic packages [ 2007 kB]
+ <E> basic + recommended packages [ 21862 kB]
+ <A> all packages [ 34303 kB]
+==============================================================================
+ <R> return to collection menu
+ <Q> quit
+Enter command:
+\end{sverbatim}
+\end{minipage}\end{lrbox}
+\centerline{\fbox{\usebox{\figbox}}}
+\caption{Installation screen, example 3}\label{ins3}
+\end{figure*}
+The \texttt{options} item lets you decide whether to make new fonts be
+created in another location (if you want the main package mounted
+read-only for most users), and whether to make symbolic links for the
+\emph{man} and \acro{GNU} \emph{info} pages in the `standard' locations.
+
+When you choose |<C>| for collections, you will see the display of
+available collections, the level of installation selected, and the
+disk space required (Figure \ref{ins2}).
+You can set alternative levels of installation for each collection,
+ranging from \emph{none} to \emph{all}. You can either set this for
+all collections at once, or choose a particular collection and set its
+level (Figure \ref{ins3}).
+
+When you are finished, return to the main screen, and ask the
+installation to start. It will take each of the collections and
+systems that you requested, consult the list of files on the \CDROM{},
+and build a master list of files to transfer. These will then be
+copied to your hard disk, and the initialization sequence run
+(creating format files etc.). When this has finished, all you need do
+is add the correct subdirectory of \texttt{bin} in the \TeX{}
+installation to your path, and start using \TeX. If you want to move
+the binaries up one level, e.g. from
+\path|/usr/local/bin/alpha-osf3.2|
+to \path|/usr/local/bin|, you need to edit
+\path|share/texmf/web2c/texmf.cnf| and change
+the line
+\begin{verbatim}
+prefix = $SELFAUTOPARENT
+\end{verbatim}
+to
+\begin{verbatim}
+prefix = $SELFAUTODIR
+\end{verbatim}
+You can of course change the value of \texttt{prefix} to any directory
+you like, and move the support directory there.
+
+%------------------------------------------------
+\subsection{Installing individual packages from \TeXLive{} to a hard
+ disk} You may want to use the \TeXLive{} \CDROM{} to either update an
+existing setup, or add features to an earlier installation from the
+\CDROM{}. The main installation program is intended for the first time
+only, and subsequently you should use the \texttt{install-pkg.sh}
+script on the \CDROM{}. Run this by mounting the \CDROM{}, changing to
+the mounted directory, and typing
+
+\begin{small}\begin{alltt}
+sh install-pkg.sh \emph{options}
+\end{alltt}\end{small}
+
+
+The script supports nine options; the first four let you set the
+individual package you want to install, the whole collection (i.e.,
+\texttt{ams2}), the name of the mounted \CDROM{} directory, and the name of
+the directory containing the list files (normally these latter two
+will be set automatically):
+
+\begin{tabular}{ll}
+\texttt{-{}-package=}\emph{name} & \\
+\texttt{-{}-collection=}\emph{name} & \\
+\texttt{-{}-cddir=}\emph{name} & \\
+\texttt{-{}-listdir=}\emph{name} & \\
+\end{tabular}
+
+What actually happens is controlled by four more switches; the first
+two allow you to exclude documentation or source files from the
+installation; the third stops the default action of running
+\texttt{MakeTeXls-R} on completion to rebuild the file database, and
+the last does nothing but list the files that would be installed:
+
+\begin{tabular}{ll}
+\texttt{-{}-nodoc} & \\
+\texttt{-{}-nosrc} & \\
+\texttt{-{}-nohash} & \\
+\texttt{-{}-listonly} & \\
+\end{tabular}
+
+Finally, you can specify that instead of installing the files, the script
+should make a \emph{tar} archive in a specified location:
+
+\begin{tabular}{ll}
+\texttt{-{}-archive=}\emph{name} & \\
+\end{tabular}
+
+Thus, if we simply wanted to see the files that make up the package
+\texttt{fancyhdr} before we installed, our command and output would be
+as follows:
+
+\begin{small}\begin{alltt}
+\Ucom{sh install-pkg.sh --package=fancyhdr --listonly}
+texmf/doc/latex/fancyhdr/fancyhdr.dvi
+texmf/doc/latex/fancyhdr/fancyhdr.tex
+texmf/lists/latex3/fancyhdr
+texmf/source/latex/fancyhdr/README
+texmf/source/latex/fancyhdr/fancyheadings.new
+texmf/tex/latex/fancyhdr/extramarks.sty
+texmf/tex/latex/fancyhdr/fancyhdr.sty
+texmf/tex/latex/fancyhdr/fixmarks.sty
+\end{alltt}\end{small}
+Other examples of usage are:
+\begin{itemize}
+\item Install the \LaTeX{} package \texttt{arseneau}:
+\begin{verbatim}
+install-pkg.sh --package=arseneau
+\end{verbatim}
+\item Install the \LaTeX{} package \texttt{alg} with no source files and no
+documentation:
+\begin{verbatim}
+install-pkg.sh \
+ --package=alg --nosrc --nodoc
+\end{verbatim}
+\item Install all the packages available in the `extra' Plain \TeX\ collection:
+\begin{verbatim}
+install-pkg.sh --collection=plain3
+\end{verbatim}
+\item Place all files which are need for PSTricks
+in a tar file in \path|/tmp|:
+\begin{verbatim}
+install-pkg.sh --package=pstricks \
+ --archive=/tmp/pstricks.tar
+\end{verbatim}
+\end{itemize}
+
+\subsection{\texttt{texconfig}}
+\label{ssec:tex}
+
+After the installation program has copied all files to their final
+locations, you can call a program called \texttt{texconfig} that
+allows you to configure the system to fit your local needs. This can
+be called at any other time to change your setup, with a full-screen
+(which requires the \prog{dialog} program) or command-line interface.
+It should be used for all maintenance, like changes of installed
+printers, or rebuilding of the file database. Both modes have help text
+to guide you through the facilities.
+
+\subsection{Building on a new platform}
+If you have a platform for which we have not provided binary sources,
+you will need to compile \TeX{} and friends from scratch. This is not
+as hard as it sounds. What you need is all in the directory
+\texttt{support/texk-7.0} on the \CDROM{}.
+
+To compile \TeX, you should get gcc, flex and a recent version of \acro{GNU}\,make.
+gcc-2.5.8, flex-2.4.7 and \acro{GNU}\,make-3.72.1 or newer should be fine. You
+may be able to work with other C compilers and Make programs, but
+you will need a good understanding of building Unix programs to sort
+out problems.
+
+You should first install the support tree from the \TeXLive{} \CDROM{} (do
+a basic install, with no system binaries chosen). Then copy the
+\texttt{texk-7.0} directory to your disk, and run
+\begin{alltt}
+ configure -prefix=\$TEXMF
+\end{alltt}
+where \texttt{\$TEXMF}
+is the place where you installed \TeXLive.
+
+Now type \texttt{make install-exec} and relax\ldots
+
+
+\section{A user's guide to the \Webc{} system}
+
+%--------------------------------------------------------
+\begingroup% Sanitizing a few characters for web2c
+\catcode`\_=12
+\catcode`\$=12
+%--------------------------------------------------------
+
+\Webc{} contains a set of \TeX-related programs, i.e., \TeX{} itself,
+\MF{}, \MP, \BibTeX{}, etc. The original implementation was by Tomas
+Rokicki, who in 1987 developed a first \TeX{}-to-C system adapting
+change files under Unix, which were primarily the work of Howard
+Trickey and Pavel Curtis. Tim Morgan became the maintainer of the
+system, and during this period the name changed to Web-to-C\@. In 1990,
+Karl Berry took over the work, assisted by dozens of additional
+contributors. The latest result is \Webc{} Version 7, which was
+released in February 1997, and forms the basis of the present
+\TeXLive{} \CDROM{}.
+
+The \Webc{} 7.0 system runs on Unix, Windows 95/NT, DOS, Amiga, and
+other operating systems. It uses Knuth's original sources for \TeX{}
+and other basic programs written in \texttt{web} and translates them
+into C source code. Moreover, the system offers a large set of macros
+and functions developed to augment the original \TeX{} software. The
+most commonly used components are:
+
+\begin{description}
+\item[\prog{bibtex}] Maintaining bibliographies.
+\item[\prog{dmp}] \prog{troff} to MPX (\MP{} pictures).
+\item[\prog{dvicopy}] Virtual font expansion.
+\item[\prog{dvitomp}] DVI to MPX (MetaPost pictures).
+\item[\prog{dvitype}] DVI to human-readable text.
+\item[\prog{gftodvi}] Generic font proofsheets.
+\item[\prog{gftopk}] Generic to packed fonts.
+\item[\prog{gftype}] GF to human-readable text.
+\item[\prog{makempx}] \MP{} label typesetting.
+\item[\prog{mf}] Creating typeface families.
+\item[\prog{mft}] Prettyprinting \MF{} source.
+\item[\prog{mpost}] Creating technical diagrams.
+\item[\prog{mpto}] MetaPost label extraction.
+\item[\prog{newer}] Compare modification times.
+\item[\prog{patgen}] Creating hyphenation patterns.
+\item[\prog{pktogf}] Packed to generic fonts.
+\item[\prog{pktype}] PK to human-readable text.
+\item[\prog{pltotf}] Property list to TFM.
+\item[\prog{pooltype}] Display WEB pool files.
+\item[\prog{tangle}] WEB to Pascal.
+\item[\prog{tex}] Typesetting.
+\item[\prog{tftopl}] TFM to property list.
+\item[\prog{vftovp}] Virtual font to virtual property list
+\item[\prog{vptovf}] Virtual property list to virtual font.
+\item[\prog{weave}] WEB to \TeX.
+\end{description}
+
+The precise functions and syntax of these programs are described in
+the documentation of the individual packages or of \Webc{} itself.
+However, knowing a few principles governing the whole family of
+programs will help you to benefit optimally from your \Webc{}
+installation.
+
+All programs honor the standard \acro{GNU} options:
+\begin{description}
+\item[\texttt{--help\ \ \ }] print basic usage summary.
+\item[\texttt{--verbose}] print detailed progress report.
+\item[\texttt{--version}] print version information, then exit.
+\end{description}
+
+For locating files the \Webc{} programs use the path searching library
+\KPS{}. This library uses a combination of environment variables and a
+few configuration files to optimize searching the \TeX{} directory
+tree. \Webc{} 7.0 can handle more than one directory tree
+simultaneously, which is useful if one wants to maintain \TeX's
+standard distribution and local extensions in two distinct trees. To
+speed up file searches the root of each tree has a file \file{ls-R},
+containing an entry showing the name and relative pathname for all
+files ``hanging'' under that root.
+
+\subsection{\prog{Kpathsea} path searching}
+
+Let us first describe the generic path searching mechanism of the \KPS{}
+library.
+
+We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list
+of \emph{path elements}, which are basically directory names. A
+search path can come from (a combination of) many sources. To look up
+a file \samp{my_file} along a path \samp{.:/dir}, \KPS{} checks each
+element of the path in turn: first \file{./my_file}, then
+\file{/dir/my_file}, returning the first match (or possibly all
+matches).
+
+In order to adapt optimally to all operating systems' conventions, on
+non-Unix systems \KPS{} can use filename separators different from
+``colon'' (\samp{:}) and ``slash'' (\samp{/}).
+
+To check a particular path element \var{p}, \KPS{} first checks if a
+prebuilt database (see ``Filename data\-base'' on
+p.~\pageref{Filename-database}) applies to \var{p}, i.e., if the database
+is in a directory that is a prefix of \var{p}. If so, the path
+specification is matched against the contents of the database.
+
+If the database does not exist, or does not apply to this path
+element, or contains no matches, the filesystem is searched (if this
+was not forbidden by a specification starting with \samp{!!}\ and if
+the file being searched for must exist). \KPS{} constructs the list
+of directories that correspond to this path element, and then checks
+in each for the file being searched for.
+
+The ``file must exist'' condition comes into play with VF files and
+input files read by \TeX's \cs{openin} command. Such files may not
+exist (e.g., \file{cmr10.vf}), and so it would be wrong to search the
+disk for them. Therefore, if you fail to update \file{ls-R} when you
+install a new VF file, it will never be found.
+
+Each path element is checked in turn: first the database, then the
+disk. If a match is found, the search stops and the result is
+returned.
+
+Although the simplest and most common path element is a directory
+name, \KPS{} supports additional features in search paths: layered
+default values, environment variable names, config file values, users'
+home directories, and recursive subdirectory searching. Thus, we say
+that \KPS{} \emph{expands} a path element, meaning transforming all
+the specifications into basic directory name or names. This is
+described in the following sections in the same order as it takes
+place.
+%described in the same order as it takes place in the following
+%sections.
+
+Note that if the filename being searched for is absolute or explicitly
+relative, i.e., starts with \samp{/} or \samp{./} or \samp{../},
+\KPS{} simply checks if that file exists.
+
+\subsubsection{Path sources}
+\label{Path-sources}
+
+A search path can come from many sources. In the order in which
+\KPS{} uses them:
+
+\begin{enumerate}
+\item
+ A user-set environment variable, for instance, \code{TEXINPUTS}\@.
+ Environment variables with a period and a program name appended
+ override; e.g., if \samp{latex} is the name of the program being run,
+ then \code{TEXINPUTS.latex} will override \code{TEXINPUTS}.
+\item
+ A program-specific configuration file, for exam\-ple, a line
+ \samp{S /a:/b} in \prog{dvips}' \file{config.ps}.
+\item
+ A \KPS{} configuration file \file{texmf.cnf}, containing a line like
+ \samp{TEXINPUTS=/c:/d} (see below).
+\item
+ The compile-time default.
+\end{enumerate}
+
+You can see each of these values for a given search path by using the
+debugging options (see ``Debugging actions'' on
+p.~\pageref{Debugging}).
+
+\subsubsection{Config files}
+
+\tolerance=3500
+\KPS{} reads \emph{runtime configuration files} named \file{texmf.cnf}
+for search path and other definitions. The search path used to look
+for these files is named \code{TEXMFCNF} (by default such a file lives
+in the \file{share/texmf/web2c} subdirectory). \emph{All}
+\file{texmf.cnf} files in the search path will be read and definitions
+in earlier files override those in later files. Thus, with a search
+path of \samp{.:$TEXMF}, values from \file{./texmf.cnf} override those
+from \file{$TEXMF/texmf.cnf}.
+
+\tolerance=1500
+
+While reading the description of the format of the file
+\file{texmf.cnf} below, please also refer to p.~\pageref{sec:texmfcnf},
+which lists the \file{texmf.cnf} file on the \CDROM.
+
+\begin{itemize}
+\item
+ Comments start with \samp{\%} and continue to the end of the line.
+\item
+ Blank lines are ignored.
+\item
+ A \bs{} at the end of a line acts as a continuation character,
+ i.e., the next line is appended. Whitespace at the beginning of
+ continuation lines is not ignored.
+\item
+ Each remaining line must look like
+ \begin{alltt}
+ \emph{variable}[.\emph{progname}] [=] \emph{value}
+ \end{alltt}%
+ where the ``\texttt{=}'' and surrounding whitespace is optional.
+%% bb -- there's a blank line after the verbatim line; i've put in
+%% a % after \end{alltt} to try to get rid of it.
+\item
+ The \var{variable} name may contain any character other than whitespace,
+ \samp{=}, or \samp{.}, but sticking to \samp{A-Za-z_} is safest.
+\item
+ If \samp{.\var{progname}} is present, the definition only
+ applies if the program that is running is named
+ \file{\var{progname}} or \file{\var{progname}.exe}. This allows
+ different flavors of \TeX{} to have different search paths, for
+ example.
+\item
+ \var{value} may contain any characters except \samp{\%} and
+ \samp{@}. The \samp{$\var{var}.\var{prog}} feature is not available
+ on the right-hand side; instead, you must use an additional variable
+ (see the definition of the variable \texttt{latex2e_inputs}
+ for example). A \samp{;}\ in \var{value} is translated to
+ \samp{:}\ if running under Unix; this is useful to write a single
+ \file{texmf.cnf} which can be used under both Unix and NT.
+\item
+ All definitions are read before anything is expanded, so you can
+ use variables before they are defined.
+\end{itemize}
+A configuration file fragment illustrating most of these
+points is shown below:
+
+\begin{verbatim}
+% TeX input files -- i.e.,
+% anything found by \input or \openin ...
+latex209_inputs = \
+ .:$TEXMF/tex/latex209//:$TEXMF/tex//
+latex2e_inputs = \
+ .:$TEXMF/tex/latex//:$TEXMF/tex//
+TEXINPUTS = .:$TEXMF/tex//
+TEXINPUTS.latex209 = $latex209_inputs
+TEXINPUTS.latex2e = $latex2e_inputs
+TEXINPUTS.latex = $latex2e_inputs
+\end{verbatim}
+
+\subsubsection{Path expansion}
+\label{Path-expansion}
+
+
+\KPS{} recognizes certain special characters and constructions in
+search paths, similar to that in Unix shells. As an general example, the
+following complex path: \verb!~$USER/{foo,bar}//baz! expands to all
+subdirectories under directories \file{foo} and \file{bar} in
+\texttt{$USER}'s home directory that contain a directory or file
+\file{baz}. These expansions are explained in the sections below.
+
+\subsubsection{Default expansion}
+\label{Default-expansion}
+
+\tolerance=2500
+If the highest-priority search path (see ``Path sources'' on
+p.~\pageref{Path-sources}) contains an \emph{extra colon} (i.e.,
+leading, trailing, or doubled), \KPS{} inserts at that point the
+next-highest-prio\-rity search path that is defined. If that inserted
+path has an extra colon, the same happens with the next-highest. For
+example, given an environment variable setting
+
+\tolerance=1500
+
+\begin{alltt}
+setenv TEXINPUTS /home/karl:
+\end{alltt}
+and a \code{TEXINPUTS} value from \file{texmf.cnf} of
+
+\begin{alltt}
+.:$TEXMF//tex
+\end{alltt}
+then the final value used for searching will be:
+
+\begin{alltt}
+/home/karl:.:$TEXMF//tex
+\end{alltt}
+
+Since it would be useless to insert the default value in more than one
+place, \KPS{} changes only one extra \samp{:}\ and leaves any others in
+place: it checks first for a leading \samp{:}, then a trailing
+\samp{:}, then a doubled \samp{:}.
+
+\subsubsection{Brace expansion}
+
+A useful feature is brace expansion, which means that, for instance,
+\verb!v{a,b}w! expands to \verb!vaw:vbw!. Nesting is allowed.
+This can be used to implement multiple \TeX{} hierarchies, by
+assigning a brace list to \code{$TEXMF}.
+
+For example, in \file{texmf.cnf}, you find the
+following definition:
+\begin{alltt}
+texdir = {$TEXMFLOCAL/tex,!!$TEXMFMAIN/tex}
+\end{alltt}
+Then you can write something like:
+\begin{alltt}
+TEXINPUTS = .;$texdir//
+\end{alltt}
+which means that after looking in the current directory, first the
+full \code{$TEXMFLOCAL/tex} directory tree (on disk) and then the
+\code{!!$TEXMFMAIN/tex} tree (using the data base file \file{ls-R}
+\emph{only}) will be searched. It is a convenient way for running two
+parallel \TeX{} structures, one ``frozen'' (like on a \CDROM) and the
+other being continuously updated with new versions as they become
+available. By using the \code{$texdir} variable in all definitions,
+one is sure to always search the up-to-date tree first.
+
+\subsubsection{Subdirectory expansion}
+\label{Subdirectory-expansion}
+
+Two or more consecutive slashes in a path element following a directory
+\var{d} is replaced by all subdirectories of \var{d}: first those
+subdirectories directly under \var{d}, then the subsubdirectories under
+those, and so on. At each level, the order in which the directories are
+searched is \emph{unspecified}.
+
+If you specify any filename components after the \samp{//}, only
+subdirectories with matching components are included. For example,
+\samp{/a//b} expands into directories \file{/a/1/b}, \file{/a/2/b},
+\file{/a/1/1/b}, and so on, but not \file{/a/b/c} or \file{/a/1}.
+
+Multiple \samp{//} constructs in a path are possible, but
+\samp{//} at the beginning of a path is ignored.
+
+\subsubsection{List of special characters and their meaning: a summary}
+
+The following list summarises the meaning of special characters
+in \KPS{} configuration files.
+\begin{description}
+\item[\code{:}] Separator in path specification; at the beginning or
+ the end of a path it substitutes the ``default'' path expansion.
+\item[\code{;}] Separator on non-Unix systems (acts like \code{:}).
+\item[\code{\$}] Variable expansion.
+\item[\code{\string~}] Represents the user's home directory.
+\item[\code{\{\dots\}}] Brace expansion, e.g., \verb!a{1,2}b! will become
+ \verb!a1b:a2b!.
+\item[\code{//}] Subdirectory expansion. It can occur in the middle or
+ at the end of a path (not at the beginning).
+\item[\code{\%}] Start of comment.
+\item[\code{\bs}] Continuation character (allows multi-line entries).
+\item[\code{!!}] Search \emph{only} database to locate file, \emph{do
+ not} search the disk.
+\end{description}
+
+\subsection{Filename databases}
+\label{Filename-database}
+
+
+\KPS{} goes to some lengths to minimize disk accesses for searches.
+Nevertheless, at installations with enough directories, searching each
+possible directory for a given file can take an excessively long time
+(this is especially true if many hundreds of font directories have to
+be traversed.) Therefore, \KPS{} can use an externally-built
+``database'' file named \file{ls-R} that maps files to directories,
+thus avoiding the need to exhaustively search the disk.
+
+A second database file \file{aliases} allows you to give additional
+names to the files listed in \file{ls-R}. This can be helpful to adapt
+to ``8.3'' filename conventions in source files.
+
+\subsubsection{\texttt{ls-R} filename database}
+\label{ls-R}
+
+As explained above, the name of the main filename database must be
+\file{ls-R}. You can put one at the root of each \TeX{} installation
+hierarchy you wish to search (\code{$TEXMF} by default); most sites
+have only one hierarchy. \KPS{} looks for \file{ls-R} files along the
+\code{TEXMFDBS} path.
+
+The recommended way to create and maintain \samp{ls-R} is to run the
+\code{MakeTeXls-R} script coming with the distribution. It is invoked
+by the various \samp{MakeTeX\dots} scripts. In principle, this script
+just runs the command
+\begin{alltt}
+cd \var{/your/texmf/root} && ls -LAR ./ >ls-R
+\end{alltt}
+presuming your system's \code{ls} produces the right output format
+(\acro{GNU}'s \code{ls} is all right). To ensure that the database is always
+up to date, it is easiest to rebuild it regularly via \code{cron}, so
+that for changes in the installed files\Dash perhaps after installing or
+updating a \LaTeX{} package\Dash the file \file{ls-R} is automatically
+updated.
+
+If a file is not found in the database, by default \KPS{} goes ahead
+and searches the disk. If a particular path element begins with
+\samp{!!}, however, \emph{only} the database will be searched for that
+element, never the disk.
+
+
+\subsubsection{\texttt{kpsewhich}: Standalone path searching}
+\label{Invoking-kpsewhich}
+
+The \texttt{kpsewhich} program exercises path searching independent of any
+particular application. This can be useful as a sort of \code{find}
+program to locate files in \TeX{} hierarchies (this is used heavily in
+the distributed \samp{MakeTeX\dots} scripts).
+
+\begin{alltt}
+kpsewhich \var{option}\dots{} \var{filename}\dots{}
+\end{alltt}
+
+Options can start with either \samp{-} or \samp{-{}-}, and any unambiguous
+abbreviation is accepted.
+
+\KPS{} looks up each non-option argument on the command line as a
+filename, and returns the first file found. There is no option to
+return all the files with a particular name (you can run the Unix
+\samp{find} utility for that).
+
+The more important options are described next.
+
+\begin{description}
+\item[\texttt{--dpi=\var{num}}]\mbox{} Set the resolution to \var{num};
+ this only affects \samp{gf} and \samp{pk} lookups. \samp{-D} is a
+ synonym, for compatibility with \prog{dvips}. Default is 600.
+\item[\texttt{--format=\var{name}}]\mbox{}\\
+ Set the format for lookup to \var{name}. By default, the format is
+ guessed from the filename. In fact, the recognized filename
+ extensions and the allowable \var{name}s (including any leading
+ \samp{.})\ are the same.
+
+ You can also specify an integer for \var{name}; this is the only way
+ to specify formats that don't have an associated suffix, such as
+ \MP{} support files and \prog{dvips} configuration files. It's also
+ somewhat faster, since no unused formats need to be initialized.
+ The integers appear in the output of \samp{--help}. Currently
+ recognized file type numbers, with their description, possible file
+ extensions, and the corresponding environment variables (between
+ parentheses%
+ \footnote{You can find definitions for these environment variables
+ in the file \file{texmf.cnf} (p.~\pageref{sec:texmfcnf})})
+as follows:
+\begin{small}
+ \begin{alltt}
+ 0 \textrm{Generic font files}
+ .gf (GFFONTS, GLYPHFONTS,
+ TEXFONTS)
+ 1 \textrm{packed font files}
+ .pk (PKFONTS, TEXPKS,
+ GLYPHFONTS, TEXFONTS)
+ 2 \textrm{\TeX{} bitmap font}
+ (GLYPHFONTS)
+ 3 \textrm{Adobe PostScript font metrics}
+ .afm (AFMFONTS)
+ 4 \textrm{\MF{} memory dump}
+ .base (MFBASES, TEXMFINI)
+ 5 \textrm{\BibTeX{} bibliography database}
+ .bib (BIBINPUTS, TEXBIB)
+ 6 \textrm{\BibTeX{} styles}
+ .bst (BSTINPUTS)
+ 7 \textrm{Runtime configuration files}
+ .cnf (TEXMFCNF)
+ 8 \textrm{\Webc{} filename database}
+ ls-R (TEXMFDBS)
+ 9 \textrm{\TeX{} memory dump}
+ .fmt (TEXFORMATS, TEXMFINI)
+ 10 \textrm{\TeX{} generic font maps}
+ .map (TEXFONTMAPS)
+ 11 \textrm{\MP{} memory dump}
+ .mem (MPMEMS, TEXMFINI)
+ 12 \textrm{\MF{} source files}
+ .mf (MFINPUTS)
+ 13 \textrm{\MF{} program strings}
+ .pool (MFPOOL, TEXMFINI)
+ 14 \textrm{\MF{} prettyprinter style files}
+ .mft (MFTINPUTS)
+ 15 \textrm{\MP{} sources}
+ .mp (MPINPUTS)
+ 16 \textrm{\MP{} program strings}
+ .pool (MPPOOL, TEXMFINI)
+ 17 \textrm{\MP{} support files}
+ (MPSUPPORT)
+ 18 \textrm{\OMEGA{} compiled process}
+ .ocp (OCPINPUTS)
+ 19 \textrm{\OMEGA{} font metrics}
+ .ofm (OFMFONTS, TEXFONTS)
+ 20 \textrm{\OMEGA{} property list}
+ .opl (OPLFONTS, TEXFONTS)
+ 21 \textrm{\OMEGA{} tranlation process files}
+ .otp (OTPINPUTS)
+ 22 \textrm{\OMEGA{} virtual fonts}
+ .ovf (OVFFONTS, TEXFONTS)
+ 23 \textrm{\OMEGA{} virtual property lists}
+ .ovp (OVPFONTS, TEXFONTS)
+ 24 \textrm{graphics/figure}
+ .eps .epsi (TEXPICTS, TEXINPUTS)
+ 25 \textrm{Source input files read by \TeX{}}
+ .tex .ltx .dtx .texi .texinfo
+ .txi .cls .sty .eps .epsi
+ (TEXINPUTS)
+ 26 \textrm{\TeX{} documentation}
+ .ps .pdf .doc .txt (TEXDOCS)
+ 27 \textrm{\TeX{} program strings}
+ .pool (TEXPOOL, TEXMFINI)
+ 28 \textrm{\TeX{} system package sources}
+ .dtx .ins (TEXSOURCES)
+ 29 \textrm{PostScript header/font}
+ .pro (TEXPSHEADERS, PSHEADERS)
+ 30 Troff \textrm{fonts}
+ (TRFONTS)
+ 31 \textrm{\TeX{} font metric files}
+ .tfm (TFMFONTS, TEXFONTS)
+ 32 \textrm{PostScript type1 fonts}
+ .pfa .pfb (T1FONTS, T1INPUTS,
+ TEXPSHEADERS, PSHEADERS)
+ 33 \textrm{virtual fonts}
+ .vf (VFFONTS, TEXFONTS)
+ 34 dvips \textrm{configuration files}
+ config.\emph{xxx}, \emph{xxx}.map (TEXCONFIG)
+ 35 MakeIndex \textrm{style files}
+ .ist (TEXIDXSTYLE, INDEXSTYLE)
+\end{alltt}
+\end{small}
+
+These environment variables are set by default in the configuration
+file \file{texmf.cnf}. It is only when you want to override one or
+more of the values specified in that file that you might want to set
+them explicitly in your execution environment.
+
+Note that the \samp{--format} and \samp{--path} options are mutually
+exclusive.
+\item[\texttt{--mode=\var{string}}]\mbox{}\\
+ Set the mode name to \var{string}; this also only affects \samp{gf}
+ and \samp{pk} lookups. No default: any mode will be found.
+\item[\texttt{--must-exist}]\mbox{}\\
+ Do everything possible to find the files, notably including
+ searching the disk. By default, only the \file{ls-R} database is
+ checked, in the interest of efficiency.
+\item[\texttt{--path=\var{string}}]\mbox{}\\
+ Search along the path \var{string} (colon-separated as usual),
+ instead of guessing the search path from the filename. \samp{//}
+ and all the usual expansions are supported.
+ The options \samp{--path} and \samp{--format} are mutually
+ exclusive.
+\item[\texttt{--progname=\var{name}}]\mbox{}\\
+ Set the program name to \var{name}.
+ This can affect the search paths via the \samp{.\var{prognam}}
+ feature in configuration files.
+ The default is \samp{kpsewhich}.
+\item[\texttt{--show-path=\var{name}}]\mbox{}\\
+ shows the path used for file lookups of file type \var{name}.
+ Either a filename extension (\samp{.pk}, \samp{.vf}, etc.) or an
+ integer can be used, just as with \samp{--format} option.
+\item[\texttt{--debug=\var{num}}]\mbox{}\\
+ sets the debugging options to \var{num}.
+\end{description}
+
+
+\subsubsection{Examples of use}
+
+Let us now have a look at \KPS{} in action.
+
+\begin{alltt}
+>> kpsewhich -format=.tex article.cls
+\footnotesize/usr/local/share/texmf/tex/latex/base/article.cls
+\end{alltt}
+We are looking for the file \file{article.cls} in the \TeX{} source
+file directories (type \texttt{.tex},
+format type 25). We find it in the subdirectory
+\file{tex/latex/base} below the \samp{TEXMF} root directory. To save
+space, in the following examples we will denote with \texttt{\dots}
+the repetitive part \file{/usr/local/share/texmf} preceding each file path.
+\begin{alltt}
+>> kpsewhich tugboat.bib
+\footnotesize.../bibtex/bib/beebe/tugboat.bib
+\end{alltt}
+\BibTeX{} bibliography databases correspond to format type
+\texttt{.bib}.
+Here we located file \file{tugboat.bib}.
+
+\begin{alltt}
+>> kpsewhich cmr10.pk
+{\footnotesize.../fonts/pk/ljfour/public/cm/cmr10.600pk}
+
+>> kpsewhich -dpi=300 cmr10.pk
+
+>> kpsewhich ptmb8r.pk
+{\footnotesize.../fonts/pk/modeless/dpi597/ptmb8r.pk}
+
+>> kpsewhich -dpi=300 ptmb8r.pk
+{\footnotesize.../fonts/pk/modeless/dpi300/ptmb8r.pk}
+\end{alltt}
+Font bitmap glyph files of type \file{.pk} correspond to format type
+2. They are used by visualization programs like \prog{dvips} and
+\prog{xdvi}. On our system we found the Computer Modern file
+\file{cmr10} for the mode \texttt{ljfour}, at a base resolution of 600
+dpi (dots per inch). However, when specifying that we are only
+interested in a resolution of 300dpi (\texttt{-dpi=300}) we are told
+there is no such font available on the system. In fact, a program like
+\prog{dvips} or \prog{xdvi} would go off and actually build the
+\texttt{.pk} files at the required resolution using the script
+\prog{MakeTeXPK}. The last two commands look for a file
+\file{ptmb8r.pk}. When specifying no explicit resolution the system
+returns one (at 597 dpi) which is closest to the ``default'' set in
+the \file{MakeTeXPK} script (600 dpi). However, when specifying the
+desired resolution (300 dpi) the full path name of the relevant target
+file is shown.
+
+Next we turn our attention to \prog{dvips}'s header (format type 29)
+and configuration files (format type 34).
+\begin{alltt}
+>> kpsewhich tex.pro
+{\small.../dvips/base/tex.pro}
+
+>> kpsewhich -format=34 psfonts.map
+{\small.../dvips/base/psfonts.map}
+
+>> kpsewhich -format=.map config.ps
+{\small.../dvips/config/config.ps}
+
+\end{alltt}
+We first look at a few of the commonly used files, namely the general
+prolog \file{tex.pro} for \TeX{} support, before turning our
+attention to the generic configuration file (\file{config.ps}) and the
+PostScript font map \file{psfonts.map}. Note how we fool the system by
+asking for \file{config.ps} as if it had a suffix of \texttt{.map}.
+
+We now look a little closer at the URW Times PostScript support files.
+The name for these in Berry's font naming scheme is ``\texttt{utm}''.
+The first file we look at is the configuration file, which contains
+the name of the map file.
+\begin{alltt}
+>> kpsewhich -format=34 config.utm
+{\small.../dvips/config/config.utm}
+\end{alltt}
+The contents of that file is
+\begin{alltt}
+{\small{}p +utm.map}
+\end{alltt}
+which points to the file \file{utm.map}, which we want to
+locate next.
+\begin{alltt}
+>> kpsewhich utm.map
+{\small.../dvips/urw/utm.map}
+\end{alltt}
+In this map file, which resides in \prog{dvips}'s \file{urw}
+subdirectory, the file names of the Type1
+PostScript fonts referenced are defined.
+The contents looks like (we only show part of the lines):
+\begin{alltt}
+\small{}utmb8r NimbusRomNo9L-Medi ... <utmb8a.pfb
+utmbi8r NimbusRomNo9L-MediItal... <utmbi8a.pfb
+utmr8r NimbusRomNo9L-Regu ... <utmr8a.pfb
+utmri8r NimbusRomNo9L-ReguItal... <utmri8a.pfb
+utmbo8r NimbusRomNo9L-Medi " ... <utmb8a.pfb
+utmro8r NimbusRomNo9L-Regu " ... <utmr8a.pfb
+\end{alltt}
+%% bb -- i'm pretty sure of this, but thought i should mark it anyhow.
+%Let's, for instance take the Time Regular instance
+Let's, for instance take the Times Regular instance
+\file{utmr8a.pfb}, and find its position in the \file{texmf} directory
+tree by using a search with format type 32.
+\begin{alltt}
+>> kpsewhich utmr8a.pfb
+\footnotesize.../fonts/type1/urw/utm/utmr8a.pfb
+\end{alltt}
+
+It should be evident from these few examples how one can easily locate
+the whereabouts of a given file. This is especially important if you
+suspect that the wrong version of a file is picked up somehow, since
+\prog{kpsewhich} will show you the first file encountered.
+
+\subsubsection{Debugging actions}
+\label{Debugging}
+
+Sometimes it is necessary to really investigate how a program resolves
+file references. To make this feasible in a convenient way \KPS{}
+offers various debug levels:
+\begin{itemize}
+\item[\texttt{\ 1}] \texttt{stat} calls (file tests). When running
+ with an up-to-date \file{ls-R} database this should almost give no
+ output.
+\item[\texttt{\ 2}] References to hash tables (like \file{ls-R}
+ database, map files, configuration files).
+\item[\texttt{\ 4}] File open and close operations.
+\item[\texttt{\ 8}] General path information for file types
+ searched by \KPS. This is useful to find out where a particular
+ path for the file was defined.
+\item[\texttt{16}] Directory list for each path element (only relevant
+ for searches on disk).
+\item[\texttt{32}] File searches.
+\end{itemize}
+A value of \texttt{-1} will set all the above options; in practice you
+will probably always use these levels if you need any debugging.
+
+Similarly, with the \prog{dvips} program one can, by setting some
+debug switches, follow in detail where files are picked up from.
+Alternatively, when a file is not found, the debug trace shows in
+which directories the program looks for the given file, so that one
+can get an indication what the problem is.
+
+Generally speaking, as most programs call the \KPS{} library
+internally, you can select a debug option by using the
+\code{KPATHSEA_DEBUG} environment variable, and setting it to (a
+combination of) values as described in the above list.
+
+Let us consider, as an example, a small \LaTeX{} source file,
+\file{hello_world.tex}, which contains the following input.
+\begin{verbatim}
+\documentclass{article}
+\begin{document}
+Hello World!
+\end{document}
+\end{verbatim}
+This little file only used the font \file{cmr10}, so let us look
+how \prog{dvips} prepares the PostScript file.
+\begin{alltt}
+>> dvips -d4100 hello_world -o
+\end{alltt}
+In this case we have combined \prog{dvips}'s debug class 4 (font
+paths) with \KPS's path element expansion (see \prog{dvips} Reference
+Manual). We get something like shown below (we have rearranged the
+output for easier display).
+\begin{alltt}\footnotesize
+debug:start search(file=texmf.cnf, must_exist=1,
+ find_all=1,
+ path=.:/usr/local/bin/texlive:/usr/local/bin:
+ /usr/local/bin/share/texmf/web2c:/usr/local:
+ /usr/local/share/texmf/web2c:
+ /.:/./teTeX/TeX/share/texmf/web2c:).
+kdebug:start search(file=ls-R, must_exist=1,
+ find_all=1,
+ path=/usr/local/texmf:/usr/local/share/texmf).
+kdebug:search(ls-R) =>/usr/local/share/texmf/ls-R
+kdebug:start search(file=aliases, must_exist=1,
+ find_all=1,
+ path=/usr/local/texmf:/usr/local/share/texmf).
+kdebug:search(aliases) =>
+kdebug:start search(file=config.ps, must_exist=0,
+ find_all=0,
+ path=.:/usr/local/texmf/dvips//:
+ !!/usr/local/share/texmf/dvips//).
+kdebug:search(config.ps) =>
+ /usr/local/share/texmf/dvips/config/config.ps
+kdebug:start search(file=/root/.dvipsrc,
+ must_exist=0, find_all=0,
+ path=.:/usr/local/texmf/dvips//:
+ !!/usr/local/share/texmf/dvips//).
+kdebug:search($HOME/.dvipsrc) =>
+ ...
+kdebug:start search(file=psfonts.map, must_exist=0,
+ find_all=0,
+ path=.:/usr/local/texmf/dvips//:
+ !!/usr/local/share/texmf/dvips//).
+kdebug:search(psfonts.map) =>
+ /usr/local/share/texmf/dvips/base/psfonts.map
+\end{alltt}
+First \prog{dvips} locates its working files. It first found
+\file{texmf.cnf} (with the definitions of the paths of the other
+files), then the file data base \file{ls-R} (to optimize file
+searching). It goes on to find the generic configuration file
+\file{config.ps}, and then looks for the customization file
+\file{.dvipsrc} (which, in this case is \emph{not found}).
+Finally \prog{dvips} locates the generic map file for PostScript fonts
+\file{psfonts.map} (defining the relation between the internal and
+external names for the PostScript fonts).
+
+At this point \prog{dvips} identifies itself to the user:
+\begin{alltt}\footnotesize
+dvipsk 5.66a Copyright 1986-97 Radical Eye Software
+ (www.radicaleye.com)
+\end{alltt}
+then goes on to look for the prolog file \file{texc.pro},
+\begin{alltt}\footnotesize
+kdebug:start search(file=texc.pro, must_exist=0,
+ find_all=0,
+ path=.:/usr/local/texmf/dvips//:
+ !!/usr/local/share/texmf/dvips//:
+ /usr/local/texmf/fonts//type1//:
+ !!/usr/local/share/texmf/fonts//type1//).
+kdebug:search(texc.pro) =>
+ /usr/local/share/texmf/dvips/base/texc.pro
+\end{alltt}
+After having found the file, \prog{dvips} outputs
+date and time, and informs us that it will generate the
+file \file{hello_world.ps}, then that it needs the font file
+\file{cmr10}, and that the latter is declared as ``resident''
+\begin{alltt}\footnotesize
+' TeX output 1997.05.01:1316' -> hello_world.ps
+Defining font () cmr10 at 10.0pt
+Font cmr10 <CMR10> is resident.
+\end{alltt}
+Now the search is on for the file \file{cmr10.tfm}, which is found,
+then a few more prolog files (not shown), and finally for the
+Type1 instance \file{cmr10.pfb} of the font (which is found) and
+included in the output file (see last line).
+\begin{alltt}\footnotesize
+kdebug:start search(file=cmr10.tfm, must_exist=1,
+ find_all=0,
+ path=.:/usr/local/texmf/fonts/tfm//:
+ !!/usr/local/share/texmf/fonts/tfm//:
+ /var/tex/fonts/tfm//).
+kdebug:search(cmr10.tfm) =>
+/usr/local/share/texmf/fonts/tfm/public/cm/cmr10.tfm
+kdebug:start search(file=texps.pro, must_exist=0,
+ find_all=0,
+ ...
+<texps.pro>.
+
+kdebug:start search(file=cmr10.pfb, must_exist=0,
+ find_all=0,
+ path=.:/usr/local/texmf/dvips//:
+ !!/usr/local/share/texmf/dvips//:
+ /usr/local/texmf/fonts//type1//:
+ !!/usr/local/share/texmf/fonts//type1//).
+kdebug:search(cmr10.pfb) =>
+/usr/local/share/texmf/fonts/type1/public/cm/cmr10.pfb
+<cmr10.pfb>[1]
+\end{alltt}
+
+\subsection{Runtime options}
+
+Another of the nice features of \Webc{} 7.0 is its possibility to
+control a number of memory parameters (in particular, array sizes) via
+the runtime file \file{texmf.cnf} read by \KPS{}. A detailed list of
+all set-table parameters can be found in that file (see
+p.~\pageref{sec:texmfcnf}, Part 3 starting at line 261). The most
+interesting values are:
+
+\begin{description}
+\item[\texttt{main_memory}]
+ Total words of memory available, for \TeX{}, \MF, and \MP. You must
+ make a new format file for each different setting. For instance, you
+ could generate a ``huge'' version of \TeX{}, and call the format
+ file \texttt{hugetex.fmt}. Using the standard way of specifying the
+ program name used by \KPS{} the particular value of the
+ \texttt{main_memory} variable will then be read from
+ \file{texmf.cnf} (See p.~\pageref{sec:texmfcnf}, line 280 for the
+ generic value and line 281 for the ``huge'' one instantiated by
+ \texttt{hugetex}).
+\item[\texttt{extra_mem_bot}]
+ Extra space for ``large'' \TeX{} data structures:
+ boxes, glue, breakpoints, etc. Especially useful if you use \PiCTeX.
+\item[\texttt{font_mem_size}]
+ Number of words for font information available for \TeX. This
+ is more or less the total size of all TFM files read.
+\item[\texttt{hash_extra}]
+ Additional space for the hash table of control sequence names.
+ Approximately 10,000 control sequences can be stored in the main
+ hash table; if you have a large book with numerous cross-references,
+ this might not be enough. On line 297 and 298 of file \file{texmf.cnf} as
+ shown in p.~\pageref{sec:texmfcnf} you see that both the
+ \texttt{hugetex} and \texttt{pdftex} program invocations ask for
+ an extra 10,000 control sequences (the default value of
+ \texttt{hash_extra} is zero, as seen on line 296).
+\end{description}
+Of course, this facility is no substitute for truly dynamic arrays and
+memory allocation, but since this is extremely difficult to implement
+in present \TeX, these runtime parameters provide a practical compromise
+allowing some flexibility.
+
+%--------------------------------------------------------
+\endgroup%%% for web2c special characters
+%--------------------------------------------------------
+
+\section{Other packages on the \CDROM}
+While the main portion of \TeXLive{}
+(the fonts, macros and documentation) can be used on any
+\TeX{} system, the set of runnable binaries is not suitable for
+everyone. To make the disk as widely useful as possible, we have
+included the original distributions of four complete \TeX{} systems,
+two for Macintosh, one for Windows 95, and one for DOS and
+OS/2. Windows 3.1 users should look at the GUTenberg distribution on
+the \CDROM.
+
+\subsection[\protect\OzTeX]{\OzTeX\footnote{This section was written by Andrew
+Trevorrow.}}
+
+\OzTeX\ is a Macintosh \TeX\ system created by Andrew Trevorrow.
+The \OzTeX\ application includes \TeX, \initex, a DVI previewer,
+a DVI-to-PostScript translator (Tom Rokicki's \dvips) and a driver
+for QuickDraw printers.
+\OzTeX{} also includes \dvidvi, \dvicopy, and Angus Duggan's
+PostScript utilities: \psbook, \psnup, \psselect\ and \pstops.
+
+The version of \dvips\ included in \OzTeX\ supports Hyper\TeX\ and
+the partial downloading of PostScript fonts.
+It has also been enhanced for Mac users in a number of ways:
+Standard Mac PostScript fonts (LWFN files) can be downloaded,
+fully or partially.
+All \OzTeX-specific \verb|\special| commands are supported,
+such as the inclusion of PICT/PNTG/EPSF files.
+The \dvips\ output can be sent directly to the current printer.
+
+\OzTeX's previewer has lots of features to make it easy to
+proofread DVI files. It can handle PK and PostScript fonts.
+Anti-aliasing is supported. Virtual fonts are processed on the fly.
+The previewer supports most of the \verb|\special| commands generated
+by \LaTeX's {\tt color}, {\tt graphics}/{\tt x} and {\tt hyperref}
+packages. It recognizes all \dvips-specific \verb|\special|s and
+those it cannot handle (like rotation) are silently ignored.
+
+\OzTeX\ includes all the most popular formats and macro packages.
+Plain \TeX, \LaTeX, AMS-\TeX, AMS-\LaTeX\ and REV\TeX\ are
+all installed and ready to run.
+
+\OzTeX\ is easy to extend and customize.
+A default configuration file is read when \OzTeX\ starts up;
+it contains a host of parameters for setting up search paths,
+telling \TeX\ how much memory to allocate for various arrays,
+specifying which TFMs are for PostScript fonts, etc.
+A Config menu makes it easy to load other config files at any time.
+And for even more flexibility, \OzTeX\ can automatically load a
+specified config file just before typesetting, previewing or printing.
+
+
+\subsubsection{Additional programs}
+
+The usual assortment of \TeX-related programs are provided with
+\OzTeX, including \OzMF, a Mac implementation of \mf,
+and \OzMP, a Mac port of John Hobby's \MP{} program
+for producing PostScript pictures using a \mf-like language.
+
+The following programs are also distributed with \OzTeX,
+courtesy of their authors;
+Bib\TeX\ by Vince Darley; MakeIndex by Rick Zaccone;
+Excalibur, a \TeX/\LaTeX\ spelling checker, by Rick Zaccone
+and Robert Gottshall; and
+AlphaLite, a \TeX/\LaTeX-savvy text editor, by Pete Keleher.
+
+For the latest information about \OzTeX, keep an eye on the Web page
+at the URL \url{http://www.kagi.com/authors/akt/oztex.html}.
+
+An even better way to keep up-to-date is to join the {\tt oztex-info}
+mailing list. To subscribe, send some e-mail to
+\begin{verbatim}
+ majordomo@maths.adelaide.edu.au
+\end{verbatim}
+with the following line in the \emph{body} of the message:
+\begin{verbatim}
+ subscribe oztex-info
+\end{verbatim}
+
+
+\OzTeX\ is distributed as shareware, so you are welcome to try it out
+before paying the registration fee.
+The individual fee is US\$30 and the site fee is US\$300.
+See the ``Shareware Fee'' item in \OzTeX's Help menu for details on
+how to pay. E-mail support is provided to registered users.
+Send all queries and comments to Andrew Trevorrow ({\tt akt@kagi.com}).
+
+\subsection[CMacTeX]{CMacTeX\footnote{This section is taken from the CMacTeX
+documentation.} }
+CMacTeX is an implementation of \TeX{} for the Macintosh
+by Thomas Kiffe (\url{mailto:tkiffe@math.tamu.edu}). It includes the three
+main parts of any \TeX{} installation\Dash \TeX, \MF{} and dvips. It also
+includes two dvi previewers, a utility for printing dvi files on a non
+PostScript printer, a PostScript previewer and numerous utilities for
+manipulating \TeX{} fonts. Full support for the automatic generation of pk font
+files is an integral part of the distribution. CMacTeX can be configured to
+work in an integrated fashion with BBEdit, Alpha, and MPW\@. It will run on
+any Macintosh with 8 MB of RAM and System 7.
+
+CMacTeX is shareware. The registration fee is US\$35 for a single-user license
+and US\$150 for a site license.
+
+Installation instructions can be found in the file
+\path|/macintosh/cmactex/ReadMeFirst|
+
+\tolerance=2500
+
+\subsection[MiKTeX]{MiKTeX\footnote{This section is drawn
+from the documentation.}}
+MiKTeX 1.07 is an implementation by Christian Schenk
+(\url{mailto:cschenk@berlin.snafu.de}) of \TeX{} and \MF{} related
+utilities for Windows NT and Windows 95. The MiKTeX distribution
+includes \TeX; \LaTeXe{} Dec'96 including standard packages; \MF; \MP;
+dvips MakeIndex; \BibTeX; YAP (Yet Another Previewer); TeXware
+(dvitype etc.); \MF ware (gftopk etc.); psutils (psselect, pstops etc.);
+and DVIcopy.
+
+
+Installation instructions can be found in the file
+\path|/win32/miktex/README.TXT|
+
+
+
+\subsection{emTeX}
+%The emTeX distribution wriiten by Eberhard Mattes
+%(\url{mailto:mattes@azu.informatik.uni-stuttgart.de}) is for DOS and OS/2.
+%%% reworded so as to try to get a better line break
+ The emTeX distribution for DOS and OS/2 is wriiten by Eberhard Mattes
+(\url{mailto:mattes@azu.informatik.uni-stuttgart.de}).
+It includes the \TeX{} typesetter, the \MF{} font generation program,
+printer drivers, screen previewers, and tools like \BibTeX{} and
+MakeIndex. It also includes the macro packages \LaTeX\,2.09 and
+\LaTeXe. Fonts are included as pixel files and \MF{} source files.
+
+Installation instructions can be found in the file
+\path|/msdos/emtex/README.ENG|
+