\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|

