\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) collections: 21 out of 30, disk space required: 163955 kB systems: 1 out of 20, disk space required: 7946 kB total disk space required: 171901 kB directories: TEXDIR = /usr/local options: [ ] alternate directory for automatically generated fonts [ ] create symlinks in standard directories Other commands: start installation, help, 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 metapost [recommended] 1280 kB latex [recommended] 28333 kB plain [recommended] 756 kB texlive [recommended] 56523 kB SUM: 163955 kB ================================================== global commands: select one / asic / rcommended / ll for all collections return to platform menu 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 ============================================================================== no packages basic packages [ 2007 kB] basic + recommended packages [ 21862 kB] all packages [ 34303 kB] ============================================================================== return to collection menu 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 || 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 ... > 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 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, ... . 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 [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|