From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- usergrps/uktug/baskervi/6_6/tex-live.tex | 1562 ++++++++++++++++++++++++++++++ 1 file changed, 1562 insertions(+) create mode 100644 usergrps/uktug/baskervi/6_6/tex-live.tex (limited to 'usergrps/uktug/baskervi/6_6/tex-live.tex') diff --git a/usergrps/uktug/baskervi/6_6/tex-live.tex b/usergrps/uktug/baskervi/6_6/tex-live.tex new file mode 100644 index 0000000000..5660597ec9 --- /dev/null +++ b/usergrps/uktug/baskervi/6_6/tex-live.tex @@ -0,0 +1,1562 @@ +\def\href#1#2{#2} +\def\filedate{1997/05/23} +\def\fileversion{3.1} +\section{Introduction} +This documentation describes the main features of the \TeXLive{} +\CDROM{}, a \TeX{}/\LaTeX{} distribution for Unix, Windows32, Amiga and +NeXT systems, that includes \TeX{}, \LaTeXe{}, \MF{}, \MP, many other +programs such as Makeindex, dvips, xdvi and \BibTeX{}; and a very +complete set of macros, fonts and documentation conforming to the +\emph{\TeX{} Directory Standard} which can be used with nearly every +\TeX{} setup. + +This \TeX{} package uses the \Webc{} implementation of the programs, +which tries to make \TeX{}ing as easy as possible, and takes full +advantage of the efficient and highly customizable Kpathsea library +from Karl Berry. It can be run either directly from the \CDROM{}, or +installed on a hard disk. + +The \TeXLive{} runnable systems contain two experimental extensions to +normal \TeX: +\begin{enumerate} +\item \eTeX, which adds a small but powerful set of new primitives, + and the \TeXXeT{} extensions for left to right typesetting; in + default mode, \eTeX{} is 100\% compatible with ordinary \TeX. See + \path|share/texmf/doc/html/e-tex/etex.htm| on the \CDROM{} for details. +\item pdf\TeX, which can optionally write Acrobat PDF format instead + of \texttt{dvi}; there is no formal documentation for this yet, but the + file \path|share/texmf/tex/pdftex/example.tex| shows how it is + used. The \LaTeX{} \texttt{hyperref} package has an option `pdftex' + which turns on all the program features. +\end{enumerate} +While \eTeX{} is stable, pdf\TeX{} is under continual development; the +version on the \CDROM{} may not be stable. Most platforms have version +0.11 of May 7th, but some have a slightly earlier one of May 5th, +which may have problems including PNG files. + +The entire GUTenberg distribution for Windows is +included on the \CDROM{}, ready to install, as are the following +complete packages: +\begin{itemize} +\item \OzTeX{} 3.0 for Macintosh +\item CMacTeX 2.6 for Macintosh +\item Macintosh utilities (Alpha, Excalibur, etc.) +\item MikTeX for Windows 95 +\item emTeX for MSDOS and OS/2 +\item \TeX{} shells for Windows + and DOS (Winedt, e4t, TeXtelmExtel, emTeXgi) +\end{itemize} +These are provided unchanged from \CTAN{}, and have not been integrated +in any way with the rest of the \CDROM{}. + +\subsection{History and acknowledgements} + +This \CDROM{} distribution is a joint effort by the \TeX{} Users +Group, the UK \TeX{} Users Group, and the French \TeX{} Users (GUTenberg), +with the support of the Dutch, German and Czech/Slovak user groups. +Discussion began in late 1993 when the Dutch \TeX{} Users Group was +starting work on its 4All\TeX{} \CDROM{} for MSDOS users, and it was +hoped at that time to issue a single, rational, \CDROM{} for all +systems. This was far too ambitious a target, but it did spawn not +only the very successful 4All\TeX{} \CDROM{}, but also the TUG +Technical Council working group on a \emph{\TeX{} Directory + Structure}, which specified how to create consistent and manageable +collections of \TeX{} support files. The final draft of the TDS was +published in the December 1995 issue of \TUB{}, and it was clear from +an early stage that one desirable product would be a model structure +on \CDROM{}. The \CDROM{} you now have is a very direct result of the +working group's deliberations. It was also clear that the success of +the 4All\TeX{} \CDROM{} meant that Unix users would benefit from a +similarly easy system, and this is the other main strand of \TeXLive. + +We undertook to make a new Unix-based TDS \CDROM{} in the autumn of 1995, +and quickly identified Thomas Esser's \teTeX{} as the ideal setup, as +it already had multi-platform support and was built with portability +across file systems in mind. Thomas agreed to help, and work began +seriously at the start of 1996. The first edition was released in May +1996. At the start of 1997, Karl Berry completed a major new release of +his \Webc{} package, which included nearly all the features which Thomas +Esser had added in \teTeX, and we decided to base the 2nd edition of the +\CDROM{} on the standard \Webc, with the addition of \teTeX's +\texttt{texconfig} script. + +We are particularly grateful to: Karl Berry for extra advice, +encouragement, and (of course) for providing the \Webc{} +distribution; Thomas Esser, without whose marvellous \teTeX{} package +this \CDROM{} would certainly not exist, and whose continual +help makes it a better product; and Ulrik Vieth, for checking +many assumptions at the start, and providing a great deal of extra +material for the documentation tree. + +Fabrice Popineau did the excellent port of \Webc{} 7.0 to Windows 95/NT +and provided much help; Andreas Scherer contributed the Amiga +compilation; Gregor Hoffleit contributed the TeXview material +for NextStep users, and the NextStep binaries. At Florida State +University Supercomputer Research Institute, Mimi Burbank arranged +access to a slew of different computers to compile \TeX{} on, and +acted as an essential guinea-pig whenever asked. Michel Goossens +provided access to computers at CERN, and Robin Fairbairns stepped in +to provide an Alpha running Linux at Cambridge. + +Some of this documentation is drawn from the \teTeX{} guide by Thomas +Esser and Dirk Hillbrecht; the catalogue of packages depends very much +on the ongoing work of Graham Williams +(\url{mailto:Graham.Williams@cbr.dit.csiro.au}), who kindly agreed to +allow us to use it here. Mimi Burbank, Robin +Fairbairns and Ulrik Vieth worked hard to improve this text. + +\subsection{Future versions} + +\emph{This \CDROM{} is not a perfect product!} We plan to re-issue it +once a year, and would like to provide more help material, more +utilities, more installation programs, and (of course) an +ever-improved and checked tree of macros and fonts. This work is all +done by hard-pressed volunteers in their limited spare time, and a +great deal remains to be done. If you can help, don't hesitate to put +your name forward! + +Corrections, suggestions and additions for future revisions +should be sent to: +\begin{quote} +Sebastian Rahtz\\ +{}7 Stratfield Road\\ +Oxford OX2 7BG\\ +United Kingdom\\ +\url{mailto:s.rahtz@elsevier.co.uk} +\end{quote} + +Updates, notes, and suggestions will be made available on \CTAN{} +in \path|info/texlive|. A \acro{WWW} page for +information and ordering details is at +\url{http://www.tug.org/tex-live.html}. + +\section{Structure and contents of the \CDROM{}} +The \CDROM{} top level directories are: +\begin{description} +\item[bin] The \TeX{} family programs, arranged in separate platform +directories; +\item[info] Documentation in \acro{GNU} `info' format for the \TeX{} system; +\item[macintosh] The \OzTeX{} and CMacTeX packages ready to install, plus + some other utilities; +\item[man] Documentation in Unix man pages for the \TeX{} system; +\item[msdos] DOS \TeX{} packages\Dash emTeX, and three \TeX{} + shells; +\item[support] The source of all programs, including the main +\Webc{} \TeX{} and \MF{} distribution; this directory also +includes various bits of \TeX-related software which are \emph{not} +installed by default, such as Musix\TeX{} support programs, and +a complete set of Ghostscript; +\item[share] The main support tree of macros, fonts and documentation; +\item[wingut] The GUTenberg distribution for Windows; +this consists of compressed archives which must be unpacked and +installed on a hard disk. Please see the detailed instructions in +French; +\item[win32] \TeX{} packages for Windows 95 and NT users (MikTeX, and + the original package of the Win32 port of \Webc). +\end{description} + +There are also two installation scripts for Unix systems, +\texttt{install-cd.sh} and \texttt{install-pkg.sh}; we discuss +them on p.~\pageref{sec:install}. + +\subsection{The TDS tree} +The \TeXLive{} \texttt{share/texmf} tree consists of various `collections', +each of which has a set of `packages', of which there are over 400 +on the \CDROM{}. Normal installation allows the +user to copy all of a collection to a local hard disk from the \CDROM{}, but +it is also possible to install just one package of a collection. +Each of the collections is divided into \emph{basic} (1), +\emph{recommended} (2) and \emph{other} (3). The +collections are: + + +\begin{description} +\item[ams] The American Mathematical Society macro packages and fonts +\item[bibtex] \BibTeX{} styles and databases +\item[doc] General guides and documentation in various formats, including HTML + and PDF +\item[dvips] Support for Rokicki's dvi to PostScript driver +\item[fonts] Font sources, metrics, PostScript and bitmap forms +\item[formats] Eplain, Rev\TeX, physxx, texsis, alatex, text1, lollipop, etc. +\item[generic] Extra macros for use with any format +\item[graphics] Macro packages for graphics +\item[lang] Support for non-English languages +\item[latex] \LaTeX, including official tools and all \LaTeXe\ + contributed packages +\item[metapost] Support for \MP +\item[plain] Macros for plain \TeX +\item[systems] Binaries for Unix platforms +\item[texlive] Basic material for the distribution +\end{description} +The appendix starting on p.~\pageref{cat} lists all the packages in alphabetical order with +the collection they are found in, and a brief description. Thus all +packages in collection \texttt{latex1} are what one must have to get +started with \LaTeX, packages in \texttt{latex2} are recommended for +most users, and \texttt{latex3} contains optional packages. The +directory \texttt{share/texmf/lists} contains lists of all files in +each package (used by the installation package). + +%\section{Installing and using the \CDROM{} under Unix} +\section{Installation and use under Unix} +\label{sec:install} +You can use the \TeXLive{} \CDROM{} in three ways: +\begin{enumerate} +\item You can mount the \CDROM{} on your file system, adjust your + \texttt{PATH}, and run everything off the \CDROM; this takes very + little disk space, and gives you immediate access to everything on + the \CDROM; although the performance will not be optimal, it is + perfectly acceptable on, for instance, PCs running Linux; +\item You can install all or part of the system to your local hard +disk; this is the best method for many people, if they have enough +disk space to spare (a minimum of about 10 megabytes, or 100 megabytes +for a recommended good-sized system); +\item You can install selected packages to work either with your +existing \TeX{} system or a \TeXLive{} system you installed earlier. +\end{enumerate} +Each of these methods is described in more detail in the following +sections. + +\begin{lrbox}{\warnbox} +\begin{minipage}{.46\textwidth} +\textbf{Warning: } This \CDROM{} is in ISO 9660 (High Sierra) format, with Rock Ridge +extensions. In order to take full advantage of the +\CDROM{} on a Unix system, your system needs to be able to use the +Rock Ridge extensions. Please consult the documentation for your +\emph{mount} command to see if it is possible. +If you have several different machines on a local network, see +if you can mount the \CDROM{} on one which \emph{does} support Rock Ridge, +and use it from the others. + +\leavevmode\quad +Linux, FreeBSD, Sun, SGI and DEC Alpha systems should be able to use +the \CDROM{} with no problems. We would appreciate receiving detailed advice +from other system users who also succeed, for future versions of this +documentation. + +\leavevmode\quad +The discussion below about installation assumes you have been able to mount +the \CDROM{} with full Rock Ridge compatibility. +\end{minipage} +\end{lrbox} +\centerline{\fbox{\usebox{\warnbox}}} + +\subsection{Running \TeXLive{} from the \CDROM} +The organisation of \Webc{} means that you can run programs simply by +adding the appropriate directory under \path|bin| on the \CDROM{} to +your \texttt{PATH}, and the support files will all be found with no further +ado. The following table shows the list of available directories and +the systems they apply to. + + +\begin{tabbing} +xxxxxxxxxxxxxxxxxx\=xxxx\kill +alpha-linux \> DEC Alpha Linux\\ +alpha-osf3.2 \> DEC Alpha OS 3.2\\ +amiweb2c \> Amiga\\ +hppa11-hpux9.05 \> HP9000 HPUX 9.05\\ +hppa11-hpux10.20 \> HP9000 HPUX 10.20\\ +i386-linux \> Intel PC with Linux (ELF)\\ +i586-freebsd2.2 \> Intel PC with Free BSD\\ +i686-linux \> Intel Pentium Pro with Linux\\ +mab-nextstep3 \> NextStep 3\\ +mips-irix4.0.5 \> SGI IRIX 4.0.5\\ +mips-irix5.3 \> SGI IRIX 5.3\\ +mips-irix6.3 \> SGI IRIX 6.3\\ +mips-ultrix4.4 \> DECstation Ultrix 4.4\\ +rs6000-aix3.2.5 \> IBM RS 6000 AIX 3.2.5\\ +rs6000-aix4.1.1 \> IBM RS 6000 AIX 4.1.1\\ +sparc-sunos4.1.3 \> Sun Sparc Sunos 4.1.3\\ +sparc-solaris2.5 \> Sun Sparc Solaris 2.5\\ +sparc-solaris2.4 \> Sun Sparc Solaris 2.4\\ +sparc-linux \> Sun Sparc Linux\\ +win32 \> Windows 95 or NT\\ +\end{tabbing} + +You may worry that when you subsequently make fonts or change +configuration, things will go wrong because you cannot change files on +the \CDROM{}. However, you can maintain a parallel, writeable, \TeX{} +tree on your hard disk; this is searched before the main tree on the +\CDROM{}. The default location is \path|/usr/local/texmf|, but you can +override this by setting the \texttt{TEXMFLOCAL} environment variable. + +Thus \emph{sh} or \emph{bash} users on an Intel PC +running Linux who mount the \TeXLive{} \CDROM{} on +\file{/cdrom} by issuing the command: +\begin{verbatim} +mount -t iso9660 /dev/cdrom /cdrom +\end{verbatim} +might add the following to their \texttt{.profile} script: +\begin{verbatim} +PATH=/cdrom/bin/i386-linux:$PATH +export PATH +\end{verbatim} +If in doubt, ask your local system support guru to help you work out +how to mount your \CDROM{} or which directory to use for your system. + +Appropriate support files will be installed on your hard disk the +first time you need them. It is a good idea to immediately run the +\texttt{texconfig} script to initialize things, and check it all +works. + +%------------------------------------------------ +\subsection{Installing \TeXLive{} to a hard disk} +All of the necessary steps to install all or part of the distribution +on your hard disk are achieved by mounting the \CDROM{}, changing to the +top-level directory, and typing: +\begin{verbatim} +sh install-cd.sh +\end{verbatim} +(On some Unix systems, you may need to use \texttt{sh5} or \texttt{bsh}). +This works by accessing lists of collections and packages from the \CDROM{}, +and trying to guess what sort of computer system you are on; it should +start by displaying the following: +\begin{verbatim} +Initializing collections... Done. +Counting selected collections... Done. +Calculating disk space requirements for + collections...Done. +Initializing system packages... Done. +\end{verbatim} +It will then show the main control screen +(Figure~\ref{ins1}), which lets you change four +things: +\begin{enumerate} +\item the type of system you are on, or want to install for; +\item the collections you want to install, at \emph{basic}, +\emph{recommended} or \emph{other} level; +\item the location on your hard disk to put the files; +\item some runtime behaviour features. +\end{enumerate} +You choose options by typing a letter or number and pressing return. +In the example, a Linux ELF system has been detected, the +default of all collections to recommended level has been chosen, and +the default installation directory is \path|/usr/local|; note +that the disk space required for the current installation +configuration is also displayed. If you make a suggested setup, you +need about 100 megabytes of disk free; however, the basic setup will +only take about 10 megabytes, and you can enhance it with selected +packages as you need them. + +Under the directory you choose for installation, the installation +script will put the binaries in a subdirectory of \path|bin|, and the +support tree in \path|share/texmf|. + +\newsavebox{\figbox} +\begin{figure*}[p] +\vspace{-\baselineskip} +\begin{lrbox}{\figbox} +\begin{minipage}{.9\textwidth} +\begin{sverbatim} +===================> TeX Live installation procedure <========== +===> Note: Letters/digits in brackets indicate menu items <=== +===> for commands or configurable options <=== + Detected system: Intel PC with Linux (ELF) + 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| + -- cgit v1.2.3