diff options
Diffstat (limited to 'Master/texmf-dist/doc/texlive/texlive-en/archive/live-tl7.tex')
-rw-r--r-- | Master/texmf-dist/doc/texlive/texlive-en/archive/live-tl7.tex | 3554 |
1 files changed, 3554 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/texlive/texlive-en/archive/live-tl7.tex b/Master/texmf-dist/doc/texlive/texlive-en/archive/live-tl7.tex new file mode 100644 index 00000000000..1e8ee77312b --- /dev/null +++ b/Master/texmf-dist/doc/texlive/texlive-en/archive/live-tl7.tex @@ -0,0 +1,3554 @@ +% +% change history (started May 13th 2002) +% 2002/05/13: added tex-langafrican to list of collections +% 2002/05/14: corrected example files, other small errors noted by Volker +% 2002/05/18: win32 updates, by Fabrice +% 2002/05/25: remove mention of sizes, and bsr-interpolated; add Gutenberg +\documentclass{article} +\advance\textwidth by 1in +\advance\oddsidemargin by -1in +\advance\evensidemargin by -1in +\newsavebox{\warnbox} +\def\Q#1{\par\vskip6pt\leftline{#1}\par} +\setcounter{tocdepth}{2} +\pretolerance=1000 +\tolerance=1500 +\hbadness=3000 +\vbadness=3000 +\hyphenpenalty=400 +\renewcommand{\topfraction}{0.85} +\renewcommand{\floatpagefraction}{0.86} +\renewcommand{\textfraction}{0.1} +\setcounter{topnumber}{5} +\setcounter{totalnumber}{5} +\def\eTeX{$\varepsilon$-\TeX} +\def\Dash{---} +\def\hyph{-} +\def\OMEGA{$\Omega$} +\def\bs{{\protect\normalfont\ttfamily\char'134}} +\DeclareRobustCommand{\cs}[1]{{\normalfont\ttfamily\char`\\#1}} +\def\La{La} +\let\textsl\textit +\let\sl\it +\let\slfamily\itfamily +\def\ttdefault{cmtt} +\usepackage{tex-live} +\begin{document} +%\makeatletter\@ifundefined{HRestore}{}{\HRestore\noalign}\makeatother +\author{Sebastian Rahtz\\ +\texttt{sebastian.rahtz@oucs.ox.ac.uk} +%Michel Goossens\\ +%\texttt{m.goossens@cern.ch} +} +\title{The \protect\TeX\ Live Guide, 7th edition} +\date{May 2002} +\maketitle +\begin{multicols}{2} +\tableofcontents +\listoftables +\end{multicols} +\section{Introduction}\label{sec:intro} +This documentation describes the + main features of the \TeXLive{} 7 \CD{}\Dash a \TeX{}/\LaTeX{} + distribution for Unix, Linux, MacOSX, and Windows32 systems that includes + \TeX{}, \LaTeXe{}, \MF, \MP, \cmdname{Makeindex}, and \BibTeX{}; and + a wide-ranging set of macros, fonts and documentation conforming to + the \emph{\TeX{} Directory Standard} (\TDS{})\Dash which can be used + with nearly every \TeX{} setup. + + This \TeX{} package uses the \Webc{} version 7.3.7 + implementation of the programs, which tries to make \TeX{}ing as + easy as possible, and takes full advantage of the efficient and + highly customizable \KPS{} library from Karl Berry and Olaf Weber. + It can be run either directly from the \CD{} or installed on a hard + disk. + +Most of the runnable systems on the \CD{} include a large set of +drivers and support programs for \TeX, including \cmdname{dvips} +(PostScript driver), \cmdname{dvipdfm} (dvi to PDF), +\cmdname{xdvi} (X Windows previewer), +\cmdname{dvilj} (HP LaserJet driver), \cmdname{lacheck} (\LaTeX{} +syntax checker), \cmdname{tex4ht} (\TeX{} to HTML converter), +\cmdname{dviconcat} and \cmdname{dviselect}, \cmdname{dv2dt} and + \cmdname{dt2dv} (\texttt{dvi} to ASCII and vice versa), and Angus + Duggan's PostScript utilities. + +\subsection{Extensions to \TeX} + +The \TeXLive{} runnable systems contain three extended versions of +standard \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 + \OnCD{texmf/doc/etex/base/etex_man.pdf} on the \CD{} for details. +\item pdf\TeX, which can optionally write Acrobat PDF format instead + of \dvi{}. You will find the user manual in + \OnCD{texmf/doc/pdftex/pdftex-l.pdf}. The + file \OnCD{texmf/doc/pdftex/samplepdf/samplepdf.tex} shows how it is + used. The \LaTeX{} \pkgname{hyperref} package has an option + `\optname{pdftex}', which turns on all the program features. +\item \OMEGA{} (Omega), which works internally with 16-bit characters, + using Unicode; this allows it to directly work with almost all the + world's scripts simultaneously. It also supports dynamically loaded + `\OMEGA{} Translation Processes' (\acro{OTP}s), which allow the user + to define complex transformations to be performed on arbitrary + streams of input. See \OnCD{texmf/doc/omega/base/doc-1.8.tex} for some + (not necessarily up to date) documentation. +\end{enumerate} +\eTeX{} (version 2.1) is stable, although subsequent releases will add +new functionality. pdf\TeX{} (version 1.00b) is also stable, +but is still being improved. +\OMEGA{} (version 1.23) is under development; the version +on this \CD{} is that current as of May 2002. + + +\section[Structure and contents of the CD-ROM]{Structure + and contents of the \protect\CD{}} +The important \CD{} top-level directories are listed below. +\begin{description} +\item[bin] The \TeX{} family programs, arranged in separate platform + directories. +\item[Books] Examples related to some books about \TeX. +\item[FAQ] Frequently Asked Questions, in English, French, and German. +\item[MacOSX] Support programs for MacOSX users +\item[info] Documentation in \acro{GNU} `info' format for the \TeX{} + system. +\item[man] Documentation in the form of Unix man pages for the \TeX{} + system. +\item[setupw32] directory contains material for installation and use + under Windows (see section \ref{sec:wintex} on p.~\pageref{sec:wintex}). +\item[source] The source of all programs, including the main \Webc{} + \TeX{} and \MF{} distributions. These are stored in a bzip2-compressed + tar archive. +\item[support] Various bits of \TeX-related software which are + \emph{not} installed by default, support programs, and a complete + distribution of \cmdname{Ghostscript} version 7.05. + You can find here some other programs (editors, \TeX\ shells), which + are usually absent from Windows installations, dedicated for beginners. + They can be installed with the \texttt{TeXSetup.exe} Windows installation + program. +\item[texmf] The main support tree of macros, fonts and documentation; +\item[usergrps] Material about \TeX\ User Groups. +\end{description} + +There are also two installation scripts for Unix systems, +\texttt{install-cd.sh} and \texttt{install-pkg.sh}; we discuss +them on in section \ref{sec:install} on p.~\pageref{sec:install}. + +\subsection[Packages and collections]{Packages and collections} +\label{packages} +The \TeXLive{} \texttt{texmf} tree consists of various `collections', +each of which refers to a set of `packages', of which there are over 700 +on the \CD{}. Normal installation allows the +user to copy all of a collection to a local hard disk from the \CD{}, but +it is also possible to install just one package of a collection. + +The collections add functionality to a \TeX\ system. One of them, named +`tex-basic', is necessary for almost all \TeX\ tasks, +and two others, called `tex-latex' and `tex-pdftex' are highly +recommended for most users. All others are optional. +The collections (defined by XML files in \texttt{texmf/tpm/collections}) +and their short descriptions are listed below. + +\begin{description} + \item[tex-basic] + These files are regarded as basic for any \TeX\ system, covering +plain \TeX\ macros, Computer Modern fonts, and configuration for common +drivers. + \item[tex-bibtexextra] + Additional, extensive libraries of BibTeX styles and bibliographies. + \item[tex-chemistry] + Essential chemistry + \item[tex-context] + Hans Hagen's powerful macro package, ConText + \item[tex-documentation] + Assorted useful documentation and guides + \item[tex-etex] + Support files for an extended \TeX\ + \item[tex-extrabin] + Various useful, but non-essential, support programs. Includes + programs and macros for texinfo system; programs for dvi file + manipulation, etc. + \item[tex-fontbin] + Programs for conversion between font formats, testing fonts + (virtual fonts stuff, .gf and .pk manipulation, + mft, fontinst, etc.) + \item[tex-fontsextra] + All sorts of extra fonts + \item[tex-formatsextra] + A collection of \TeX\ `formats', ie large-scale +macro packages designed to be dumped into .fmt file + \item[tex-games] + Setups for typesetting various board games, including chess + \item[tex-genericextra] + This is a mixed bag of macro packages and fonts which do not seem +to belong elsewhere + \item[tex-htmlxml] + Packages to convert \LaTeX\ to XML/HTML, and typeset XML/SGML + \item[tex-langafrican] + Support for some African scripts + \item[tex-langarmenian] + Essential armenian + \item[tex-langcjk] +Essential CJK (Chinese, Japanese, Korean) macros and fonts + \item[tex-langcroatian] + Essential croatian + \item[tex-langcyrillic] + Fonts and macro packages to typeset Cyrillic texts. + \item[tex-langczechslovak] + Pick this if you want Czech/Slovak fonts and other packages + \item[tex-langdanish] + Essential Danish + \item[tex-langdutch] + Essential Dutch + \item[tex-langfinnish] + Essential Finnish + \item[tex-langfrench] + Essential French + \item[tex-langgerman] + Essential German + \item[tex-langgreek] + Essential Greek + \item[tex-langhungarian] + Essential Hungarian + \item[tex-langindic] + Essential Indic + \item[tex-langitalian] + Essential Italian + \item[tex-langlatin] + Essential Latin + \item[tex-langmanju] + Essential Manju + \item[tex-langmongolian] + Essential mongolian + \item[tex-langnorwegian] + Essential Norwegian + \item[tex-langother] + Other languages + \item[tex-langpolish] + Pick this if you want Polish fonts and other packages + \item[tex-langportuguese] + Essential Portuguese + \item[tex-langspanish] + Essential Spanish + \item[tex-langswedish] + Essential Swedish + \item[tex-langtibetan] + Fonts and support for typesetting Tibetan + \item[tex-langukenglish] + Essential UK English + \item[tex-langvietnamese] + Essential Vietnamese + \item[tex-latex] + These packages are either mandated by the core \LaTeX\ team, +or very commonly recommended + \item[tex-latexextra] + A large collection of add-on packages for \LaTeX\ + \item[tex-mathextra] + Extra math + \item[tex-metapost] + MetaPost (and MetaFont) drawing packages + \item[tex-music] + Music typesetting packages + \item[tex-omega] + Omega, a 16-bit extended \TeX\ by John Plaice and Yannis Haralambous + \item[tex-pdftex] + Support files for Han The Thanh's variant of \TeX\ which can +generate PDF output + \item[tex-pictures] + Essential graphics + \item[tex-plainextra] + Plain \TeX\ extra macros + \item[tex-psfonts] + Essential psfonts + \item[tex-psutils] + Utilities to manipulate PostScript files + \item[tex-publishers] + Essential publishers + \item[tex-t1utils] + Utilities to manipulate Type1 fonts + \item[tex-texbooks] + Examples and other material from various books about TeX/LaTeX. + \item[tex-theses] + Macro packages from various Universities for their thesis styles + \item[tex-ttfutils] + Utilities to manipulate TrueType fonts + \item[win32-support] + You can choose individual tools from this collection. + There are many \TeX\ oriented editors, graphics files + toolsets, etc. +\end{description} + +The directory \texttt{texmf/tpm/packages} contains lists +of all files in each package (used by the installation programs). + +\section{Installation and use under Unix} +\label{sec:install} +You can use the \TeXLive{} \CD{} in three ways: +\begin{enumerate} +\item You can mount the \CD{} on your file system, run +the \texttt{install-cd.sh} script, and select the option \verb|<R>| + (`do not install files, set up to run off CD-ROM'), + and run everything off the \CD; this takes very + little disk space, and gives you immediate access to everything on + the \CD; although the performance will not be optimal, it is + perfectly acceptable on, for instance, PCs running Linux. You could + also copy the entire CD contents to your hard disk and work in this way. +\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 100 megabytes, or 300 + 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. + +\ifSingleColumn +\begin{figure*} + \begin{center} + \leavevmode +\fi +\begin{warningbox} +\textbf{Warning: } This \CD{} is in ISO 9660 (High Sierra) format, +with Rock Ridge and Joliet extensions. In order to take full advantage +of the \CD{} on a Unix system, your system needs to be able to use +the Rock Ridge extensions. Please consult the documentation for your +\cmdname{mount} command to see if it is possible. If you have several +different machines on a local network, see if you can mount the +\CD{} on one which \emph{does} support Rock Ridge, and use this with +the others. + +\leavevmode\quad +Linux, FreeBSD, Sun, SGI and DEC Alpha systems should be able to use +the \CD{} 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 \CD{} with full Rock Ridge compatibility. +\end{warningbox} +\ifSingleColumn + \end{center} +\end{figure*} +\fi + +%\begin{addbymb} +\subsection[Pre-installation procedure for MacOSX users] +{Pre-installation procedure for MacOSX users} +If you do not run MacOSX, you should skip this section. + +The \texttt{install-cd.sh} script is a \emph{sh} script (begins with +``\verb=#!/bin/sh=''), but +on MacOSX \cmdname{sh} is unable to run it because +\cmdname{sh} is +emulated. However, \cmdname{bash} will run it. Unfortunately (again) +\cmdname{bash} is not +installed by default on MacOSX\footnote{there are some suggestions this will +change in the future and even +that \cmdname{bash} will be used to emulate \cmdname{sh}, +in which case it might be true +that in future versions of MacOSX, the script will just work.}. +\begin{enumerate} +\item\label{test-bash} (optional) See if \path|bash| is already installed. +Launch \path|Terminal| +(\path|/Applications/utilities/Terminal|) and type in a window +\begin{alltt} +>> \Ucom{rehash; which bash} +\end{alltt} +the answer will be: +\begin{itemize} +\item the bash location (e.g. \path|/bin/bash| or \path|/usr/local/bin/bash|) if installed; +\item \texttt{bash: command not found} if not installed. +\end{itemize} + +If bash is already installed, skip to \ref{std-install} + +\item bash installation: +\begin{description} +\item[Mac friendly procedure] +Look in the \path|MacOSX| directory of the \CD{} +for an image disk named \path|bash.dmg|. mount that +file by double-clicking it. The disk image (volume) will be mounted. +Then start the \path|i-Installer| application on that volume. You will be asked +to authenticate, if you have never seen that before, you might not have +enough privileges to install. Just enter your own user name and +password. Hit install. \path|bash| will be installed on your system. +\item[Terminal procedure] +\begin{enumerate} +\item Log in as an admin user, at least a user with Admin privileges or +sudo user or as the System Administrator. +\item Open the \path|MacOSX| directory on the \CD{} and copy +\path|bash.tar.gz| +to your home directory (\texttt{\~{}/}) +\item Then launch \path|Terminal| and type or copy/paste the +line below in a Terminal window): +\begin{alltt} +>> \Ucom{(cd /usr/local/; sudo tar xvzf ~/bash.tar.gz)} +\end{alltt} +type a carriage-return: you will be asked for your password, and +\path|bash| will be +installed. +\item Quit \path|Terminal|. +\end{enumerate} +\end{description} +\item Now after using either install method, goto \ref{test-bash}: +you must obtain \path|/usr/local/bin/bash|\ldots{} (if not, try to log out and in). +\item\label{std-install} The installation procedure is the +same on MacOSX than on other UNIX platforms (as MacOSX is UNIX, +that's quite normal!). Nevertheless, you should read what follows: +\begin{itemize} + \item Note that in all commands of the following sections, +\cmdname{sh} must be replaced by \texttt{sudo bash}: +\begin{alltt} +>> \Ucom{sh install-cd.sh} +\end{alltt} +becomes +\begin{alltt} +>> \Ucom{sudo bash install-cd.sh} +\end{alltt} +etc. +\item On MacOSX, cd are auto-mounted: you \emph{don't} need to use +\texttt{mount}. The \CD{} will be mounted in the \path|/Volumes/| +directory: in order to make it the current directory, you just have to +type in \path|Terminal|: +\begin{alltt} +>> \Ucom{cd /Volumes/TeXLive-7...} +\end{alltt} +(complete this line with the real name of the \CD{}: using +``auto completion'' by pressing the \texttt{<tab>} +key will do it). +\end{itemize} +\end{enumerate} +%\end{addbymb} + +\subsection[Running \protect\TeXLive{} from the CD-ROM]{Running \protect\TeXLive{} from the \protect\CD} +The organisation of \Webc{} means that you can run programs simply by +adding the appropriate directory under \path|bin| on the \CD{} to +your \texttt{PATH}, and the support files will all be found with no further +ado. The following shows the list of available systems and the +corresponding directories. \textbf{Only x86 Linux, Mac OSX, and + Windows are available on the default CD. You need to ask +for the Unix CD if you need the other systems.} + +\begin{flushleft} +\begin{tabular}{@{}l>{\ttfamily}ll} +Compaq Alpha Linux & alpha-linux & CD2\\ +Compaq Alphaev5 OSF 4.0d & alphaev5-osf4.0d & CD2\\ +HP9000 HPUX 10.20 & hppa2.0-hpux10.20 & CD2\\ +IBM RS 6000 AIX 4.2.* & rs6000-aix4.2.1.0 & CD2\\ +Intel x86 Solaris 2.8 & i386-solaris2.8 & CD2\\ +Intel x86 with GNU/Linux & i386-linux & CD1\\ +Mac OSX & powerpc-darwin5.3 & CD1\\ +Sun Sparc Solaris 2.7 & sparc-solaris2.7 & CD2\\ +Windows 9X/ME/NT/2K/XP & win32 & CD1\\ +\end{tabular} +\end{flushleft} + +You may worry that when you subsequently make fonts or change +configuration, things will go wrong because you cannot change files on +the \CD{}. However, you can maintain a parallel, writeable, \TeX{} +tree on your hard disk; this is searched before the main tree on the +\CD{}. The default location is \path|texmf-var| on the CD +(which does not exist!), so you \emph{must} override this by setting +the \texttt{VARTEXMF} environment variable. + + +Thus \emph{sh} or \emph{bash} users on an Intel PC +running Linux can mount the \TeXLive{} \CD{} on +\file{/mnt/cdrom} by issuing the command: + +\begin{alltt} +>> \Ucom{mount -t iso9660 /dev/cdrom /mnt/cdrom} +\end{alltt} +Then they should change the current directory to \path|/mnt/cdrom|, run +\begin{alltt} +>> \Ucom{sh install-cd.sh} +\end{alltt} +and select the option \verb|<R>| (\emph{do not install files, set up to run +off CD-ROM}). After that, they should include the directory containing +the binaries for the given architecture into the search path +by updating the \texttt{PATH} variable. +\begin{verbatim} +PATH=/mnt/cdrom/bin/i386-linux:$PATH +export PATH +VARTEXMF=/usr/TeX/texmf-var +export VARTEXMF +\end{verbatim} +%\begin{addbymb} +\begin{description} + \item[MacOSX users] On MacOSX, the default shell is \texttt{tcsh}: +\begin{verbatim} +setenv PATH /Volumes/<cd-name>/bin/powerpc-darwin5.3:${PATH} +setenv VARTEXMF /usr/TeX/texmf-var +\end{verbatim} +\end{description} +%\end{addbymb} +For convenience, these statements can also be entered into the +\texttt{.profile} script. +%\begin{addbymb} +(for \texttt{tcsh} on MacOSX, +\verb=~/Library/init/tcsh/rc.mine=). +%\end{addbymb} + +If in doubt, ask your local system support guru to help you work out +how to mount your \CD{} or which directory to use for your system. + +Appropriate support files will be installed on your hard disk the +first time you need them. You can edit and change local configuration +files which are stored to the directory designated +by \texttt{\$VARTEXMF}. Any format file that is needed +will be generated and stored here. + +%------------------------------------------------ +\subsection{Installing \protect\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 \CD{}, changing to the +top-level directory, and typing: +\begin{alltt} +>> \Ucom{sh install-cd.sh} +\end{alltt} +(On some Unix systems, you may need to use \cmdname{sh5} or +\cmdname{bash}.) This script works by accessing lists of collections +and packages from the \CD{}, and trying to guess what sort of computer +system you are on. It should start by displaying the following: +\verbatiminput{../examples/ex1.tex} +It will then show the main control screen +(Figure~\ref{ins1}), which lets you change five +things: +\begin{enumerate} +\item the type of system you are on, or want to install for; +\item the \emph{installation scheme} you want to use (eg full, + recommended, basic etc) +\item the collections you want to change from +the installation scheme (they are organised into two sets: +\emph{standard collections} and \emph{language collections}); +\item the location on your hard disk to put the files; +\item some runtime behaviour features. +\end{enumerate} + +\begin{figure*} +\begin{center} +\ifnum\Status=2 +\boxedverbatiminput{../examples/ex2.tex} +\else +\begin{minipage}{0.8\textwidth} +\boxedverbatiminput{../examples/ex2.tex} +\end{minipage} +\fi +\caption{Main control screen}\label{ins1} +\end{center} +\end{figure*} + +You choose options by typing a letter or number and pressing `return'. +In the example, a Linux GNU/Linux system has been detected, the +default set of collections will be installed, and +the default installation directory is \path|/usr/TeX|; note +that the disk space required for the current installation +configuration is also displayed. If you make a suggested setup, you +need about 60 megabytes of disk free; however, the basic setup will +only take about 30 megabytes, and you can enhance it with selected +packages as you need them. + +%\begin{addbymb} +\begin{description} + \item[MacOSX users] Most frontends (\emph{TeXShop}, + \emph{ITeXMac}\ldots) use the \teTeX{} default location + which is \path|/usr/local/teTeX|, so, Mac users could find interest + in installing \TeXLive{} in \path|/usr/local/teTeX| +rather than in \path|/usr/TeX|. +\end{description} +%\end{addbymb} + +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|texmf|. An additional tree \path|texmf-var| +will contain copies of configuration files (except the main +\path|texmf.cnf|), which are to be modified by \path|texconfig| program. +This tree will also store generated format files for \TeX, \MF, etc. + +\begin{figure*} +\begin{center} +\ifnum\Status=2 +\boxedverbatiminput{../examples/ex3.tex} +\else +\begin{minipage}{.80\linewidth} +\footnotesize +\boxedverbatiminput{../examples/ex3.tex} +\end{minipage} +\fi +\caption{Selecting standard collections}\label{ins2} +\end{center} +\end{figure*} + +\begin{figure*} +\begin{center} +\ifnum\Status=2 +\boxedverbatiminput{../examples/ex4.tex} +\else +\begin{minipage}{.80\linewidth} +\footnotesize +\boxedverbatiminput{../examples/ex4.tex} +\end{minipage} +\fi +\caption{Selecting language collections}\label{ins3} +\end{center} +\end{figure*} + +When you choose |<C>| for \emph{standard collections}, you will see +the display of available collections (Figure \ref{ins2}). Each +collection --- TeX macro files, Metafont font families, and so on --- +consists of several packages. You can toggle their inclusion on or +off by pressing the key. Note that the selection letter keys are case +sensitive. + +When you choose |<L>| for \emph{language collections}, you will see +the display of available language support collections (Figure +\ref{ins3}). Each collection consists of several packages, which +provide features like hyphenation files and fonts. + +The |<O>| for \emph{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 +binaries, \cmdname{man} and \acro{GNU} \cmdname{info} pages in the `standard' +locations; you'll need `root' permissions for tasks to do this, of course. + +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 \CD{}, +and build a master list of files to transfer. These will then be +copied to your hard disk. If you installed a system, +an initialization sequence is now 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, you can +move the binaries up one level, e.g.\ from +\path|/usr/local/bin/alpha-osf3.2| +to \path|/usr/local/bin|; if you do this, however, you must +edit \path|texmf/web2c/texmf.cnf| (see Appendix~\ref{app:texmf.cnf}) +and change the line near the start which reads +\begin{verbatim} + TEXMFMAIN = $SELFAUTOPARENT +\end{verbatim} +to +\begin{verbatim} + TEXMFMAIN = $SELFAUTODIR +\end{verbatim} + +If you move the whole installation to another directory tree entirely, you +need to edit \envname{TEXMFMAIN} to specify the support tree explicitly, and +set \envname{TEXMFCNF} in your environment to \path|$TEXMFMAIN/texmf/web2c|. + +%------------------------------------------------ + +\subsection{Installing individual packages from \protect\TeXLive{} to a hard + disk} You may want to use the \TeXLive{} \CD{} to either update an +existing setup, or add features to an earlier installation from the +\CD{}. The main installation program is intended for the first time +only, and subsequently you should use the \texttt{install-pkg.sh} +script on the \CD{}. Run this by mounting the \CD{}, changing to +the mounted directory, and typing + +\begin{alltt} +>> \Ucom{sh install-pkg.sh \emph{options}} +\end{alltt} + + +The script supports nine options; the first four let you set the +individual package you want to install, the whole collection (i.e., +\texttt{tex-mathextra}), the name of the mounted \CD{} 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{mktexlsr} 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 \cmdname{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 +\pkgname{fancyhdr} before we installed it, our command and output would be +as follows: + +\begin{alltt} +\ifSingleColumn>> \Ucom{sh install-pkg.sh --package=fancyhdr --listonly} +\else>> \Ucom{sh install-pkg.sh -{}-package=fancyhdr \bs} +>> \Ucom{-{}-listonly} +\fi{} +texmf/doc/latex/fancyhdr/fancyhdr.dvi +texmf/doc/latex/fancyhdr/fancyhdr.tex +texmf/lists/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} +Other examples of usage are: +\begin{itemize} +\item Install the \LaTeX{} package \texttt{natbib}: +\begin{alltt} +>> \Ucom{sh install-pkg.sh --package=natbib} +\end{alltt} +\item Install the \LaTeX{} package \texttt{alg} with no source files and no +documentation: +\begin{alltt} +\ifSingleColumn>> \Ucom{sh install-pkg.sh --package=alg --nosrc --nodoc} +\else>> \Ucom{sh install-pkg.sh -{}-package=alg \bs} +>> \Ucom{-{}-nosrc -{}-nodoc} +\fi\end{alltt} +\item Install all the packages available in the collection containing additional +Plain \TeX\ macros: +\begin{alltt} +>> \Ucom{sh install-pkg.sh --collection=tex-plainextra} +\end{alltt} +\item Place all files which are needed for PSTricks +in a \cmdname{tar} file in \path|/tmp|: +\begin{alltt} +\ifSingleColumn>> \Ucom{sh install-pkg.sh --package=pstricks --archive=/tmp/pstricks.tar} +\else +>> \Ucom{sh install-pkg.sh -{}-package=pstricks \bs} +>> \Ucom{-{}-archive=/tmp/pstricks.tar} +\fi\end{alltt} +\end{itemize} + +\subsection{The texconfig program} +\label{ssec:tex} + +After the installation program has copied all files to their final +locations, you can use a program called \cmdname{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 \cmdname{dialog} program, included as part of the +binary packages) or command-line interface. +It should be used for all maintenance, such as changes of installed +printers, or rebuilding the file database. Both modes have help text +to guide you through the facilities. + +\section{Installation and use under Windows} +\label{sec:wintex} +This section only applies to systems running Windows 9x, \acro{ME}, +\acro{NT}, \acro{2K} or \acro{XP}. + +It is also necessary to have your Windows set up so that it uses the +Microsoft Joliet extensions for reading \CD s; simply look at the +\CD{} in Explorer and see whether it shows long, mixed-case, file +names. If it does not, you cannot use the ready-to-run system on the +\CD. + +This Win32 \TeX{} systems includes a \texttt{dvi} previewer, +\textsf{Windvi}, which is similar in usage to the established Unix +\textsf{xdvi}. The documentation can be found in +\OnCD{texmf/doc/html/windvi/windvi.html}. + +\subsection[The TeXLive.exe program]{The \texttt{TeXLive.exe} program} + +\begin{figure*} + \begin{center} + \ifnum \Status=1 + \includegraphics[width=.7\textwidth]{../pictures/Welcome-to-TeXLive} + \else + \ifnum \Status=2 +\includegraphics[bb=20 20 575 432]{../pictures/Welcome-to-TeXLive.gif} + \else + \includegraphics[width=.7\textwidth]{../pictures/Welcome-to-TeXLive} + \fi + \fi + \end{center} + \caption{``Welcome to \TeXLive'' window}\label{graph:welcome} +\end{figure*} + +If your computer is configured to let the \CD{} autostart, then a +dialog box with a menu bar will popup on the screen, and you will have several choices +from there: +\begin{itemize} +\item Install \TeX{} on your hard disk, +\item Install TeX-oriented editors on your hard disk, +\item Install support packages on your hard disk (Ghostscript, NetPBM, + \ldots) +\item Do some maintenance on you \TeX{} system, +\item Remove the \TeX{} system, +\item Use \TeX{} off the \CD{}, +\item Cleanup the temporary files created on your hard disk when using + \TeX{} off the \CD{}, +\item Update some of the DLLs on your system, +\item Browse some documentation: \TeXLive{} documentation, TUG web + pages, \fpTeX web pages, +\item Run the \cmdname{TeXdocTK} application to find specific documentation. +\end{itemize} + +If your \CD{} does not autostart, you can explicitly run the program +by double clicking on \path|bin/win32/TeXLive.exe| on the \CD{} from +the explorer window. + +\subsection[Running \protect\TeXLive{} from the CD-ROM]{Running from +the \protect\CD{}} +You can run all the \TeX{} programs directly off the \CD, and have +access to all the macros and fonts immediately, at the price of a +slower performance than if you install on the hard disk. +To work effectively, one needs to modify +environment variables and to create some small auxiliary directories on a +hard disk. These directories will contain necessary configuration files +allowing the user to modify programs settings and to generate a necessary +format file. Moreover, automatically generated font files will be stored +there too. + +Should you want to run \TeX{} this way, you will have to follow these +steps: +\begin{enumerate} +\item from the menu, chose \verb|Explore CD-Rom|, then + \verb|Select a text editor|, a dialog box will open to select some \path|.exe| + program. + + This program needs to be a \TeX{} oriented editor. It must be able + to run the \TeX{} compiler, previewer and any other needed tool. If + you don't have one already installed on your system, you can install + one from the \CD{}, details section~{\ref{sec:texlive-install}}. + + \emph{There is no way we can guess if the program you will + select is actually a text editor, so be careful}. + Here is a list of frequently used \TeX{} editors: +\begin{center} + \begin{tabular}[ht]{ll} + GNU Emacs & \path|c:\Program Files\NTEmacs\bin\runemacs.exe| \\ + XEmacs & \path|c:\Program Files\XEmacs\XEmacs-21.2\i586-pc-win32\xemacs.exe| \\ + WinShell & \path|c:\Program Files\WinShell\WinShell.exe| \\ + WinEdt & \path|c:\Program Files\WinEdt Team\WinEdt\WinEdt.exe|\\ + TeXnicCenter & \path|c:\Program Files\TeXnicCenter\TEXCNTR.exe| + \end{tabular} +\end{center} + The program + selected will be memorized as the editor to use for future runs. + +\item from the menu, chose \verb|Explore CD-Rom|, then + \verb|Run TeX off CD-Rom|. The environment will be modified, a small + temporary directory created and some configuration files copied + there. Then, the selected editor selected will be launched, and you + will be able to type in some text, let \TeX{} typeset it and the + view it or print it. + + If Ghostscript is not detected on your machine, you will be warned + that rendering your DVI files might fail. You can install it from + the \path|Install|, \path|Support| menu item. See + section~\ref{sec:texlive-install} for details. + +\item you can select a different text editor any time you want. + +\item if you chose \verb|Cleanup CD-Rom setup|, everything \TeX{} + needed will be removed, comprised the selection of your text + editor, but not the extra packages you may have downloaded and + installed. If you installed \cmdname{WinShell} or \cmdname{NTEmacs}, +they won't be removed. +\end{enumerate} + +The editor is run inside a modified environment. A temporary TDS +compliant texmf tree is build in the temporary area of your computer. +It is needed to store files that may be build on the fly like pk font +files or format files. Configuration files are copied from the \CD{} +to this texmf tree, so that you can edit them if needed. The \path|ls-R| +database is computed for this texmf tree. +Then the \texttt{PATH} and \texttt{TEXMFCNF} environment +variables are set locally, and the editor is run in +this local environment. From within your editor\footnote{Actually, you can + state any other program than a text editor, and select your command + processor for example. You will then get a console with the right + settings to use \TeX{} from the \CD{}.}, you have access to a full +\TeXLive{} environment, all files referenced on the \CD{}. + + +\smallskip {\small\noindent \textbf{[For advanced users:]} You can + also use the small batch file \path|mkloctex.bat| to be called in a + directory \path|setupw32| of the \CD. From the Start menu select + `Run', then browse CD drive and select \path|mkloctex.bat|. Before + starting it, you should add two parameters separated by a space: the + letter of your CD drive and the letter of the hard disk where you + want to install the \TeX\ directory. The whole line should read, + e.g., \verb+d:\setupw32\mkloctex.bat d c+. When installation is + complete, please read carefully the information on screen. If you + are running Windows 9x/ME, then you will have to restart Windows. } + +\subsection{Installing editors or support packages} +\label{sec:texlive-install} + +You can already use the \path|TeXSetup.exe| program to install a +single, not \TeX{} dependent package. This might be either an editor +like \cmdname{WinShell} or \cmdname{NTEmacs}, +or also a support package like \cmdname{NetPBM} +(graphics formats conversion) or \cmdname{Ghostscript}. + +Some of the packages are not free, or not with the same meaning as for +the rest of the \CD{}. These packages have been made available through +the Internet. You need to enable an Internet connection in order to +install them. Chosing the \path|Enable Internet access| subitem will +search your system for an active Internet connection, or start one if +possible. \emph{If your computer is not connected to the Internet, + then the timeout might be long, 30s or more}. So try to enable it +only if you know you have a connection. + +Only a few packages are available from the \CD{}, but the most +important of them: \cmdname{NTEmacs} and \cmdname{WinShell} for the +editors, \cmdname{Ghostscript} and \cmdname{NetPBM} for the other +support packages. \cmdname{NetPBM} is needed for running \TeX{}4ht. + +The downloadable packages are sometimes huge: \cmdname{Perl} is 10Mb, +\cmdname{XEmacs} is 50Mb, so be warned that it can take a lot of time +to install such things. \path|TeXSetup.exe| does not yet provide an +estimation of the time needed to complete the download. + +When installing these packages, \path|TeXSetup| is working in +unattended mode. However, the programs that have their own installer +like WinEdt or Ghostscript for example will require human interaction. + +Those packages who have no specific installer will be unpacked and configured +for your system. You will be required to select some directory where +they will be installed. The directory to select should be the root +directory of the whole installation. Assuming you want to install +NTEmacs and NetPBM, the archive files already contain the +\path|NTEmacs\| and \path|NetPBM\| part, so the directory you have to +select is something like \path|c:\Local| or \path|c:\Program Files|. + +\subsection{Installing to your hard disk} + +Installation is started by letting the CD autostart, and +selecting the item \verb|Install| from the menu, then the subitem +\verb|TeXLive|. This will invoke the \path|TeXSetup.exe|. You can also find +it in the \path|bin/win32| directory and run it. \path|TeXSetup.exe| +is a Windows wizard and it will display several pages while running. + +\begin{description} +\item[Welcome Page] + You can choose a \emph{quick} installation from + there, in this case, the installation will run without any human + assistance from beginning to end, with all the default settings + (Figure~\ref{graph:setup-src}, + \ifnum \Status = 1 + on the left% + \else\ifnum \Status=2 + at the top% + \else + on the left% + \fi\fi + ). However, if you chose to install any support program that has its + own installer like WinEdt or Ghostscript, your intervention might be required. + If you have enough privileges (administrator or power user rights) + under a Windows version where it is applicable, then you can decide + to install the \TeXLive{} for all users or for yourself only by + checking the appropriate box. + + \begin{figure*}[!htb] + The \cmdname{TeXSetup} Wizard\hfill + Source directories for the \TeXLive{} files + + \begin{center} + \ifnum \Status=1 + \includegraphics[width=.48\textwidth]{../pictures/setup-wizard.jpg}\hfill% + \includegraphics[width=.48\textwidth]{../pictures/source-for-texlive.jpg} + \else + \ifnum \Status=2 +\includegraphics[bb=0 0 506 403]{../pictures/setup-wizard.gif} +\includegraphics[bb=0 0 506 403]{../pictures/source-for-texlive.gif} + \else + \includegraphics[width=.48\textwidth]{../pictures/setup-wizard}% + \hfill% + \includegraphics[width=.48\textwidth]{../pictures/source-for-texlive} + \fi + \fi + \caption{The \TeXLive{} setup wizard}\label{graph:setup-src} + \end{center} +\end{figure*} +\item[Source Page] + This page is a bit complex. It will allow you to select two source + directories for your \TeXLive{} system + (Figure~\ref{graph:setup-src}, + \ifnum \Status = 1 + on the right% + \else\ifnum \Status=2 + at the bottom% + \else + on the right% + \fi\fi + ). You will need a \emph{local + source directory} and possibly a \emph{remote source directory}. + + Why do we need both these directories? The very files of the + \TeXLive{} system are on the \CD{}, but some other packages useful + under a Win32 system are not, either because of space lacking or + because their license was not compatible with the \TeXLive{}'s one. + You need to enable Internet downloading if you want to install these + support packages. + + However, don't panic: the default parameters of the setup will allow + you to install a full system using the \CD{} only. Simply, you won't + have \file{WinEdt} for example, but you will be able to install it + later. + + So you can take your files from: + \begin{itemize} + \item the \CD{} or any similar flat tree of files, available through + some standard directory (this means the \CD{} can be mounted on + some remote machine and be made available through network + sharing), + \item a set of \file{.zip} files (this is the case when you are + installing the + \fpTeX{} distribution), + \item the Internet, in this case, the program takes care of + downloading the \file{.zip} files it needs for you. + \end{itemize} + This option is available only if you enable Internet file + downloading in the right part of the page. You also need to + configure this Internet access by selecting to connect either using + Internet Explorer~5 \file{wininet.dll}, or using a direct connection (\texttt{ftp}, + \texttt{http}). +% or using a proxy server. +% Last, you can be assisted in defining the \emph{local source +% directory} and \emph{remote source directory} which will be used +% to copy the files onto your hard disk. The \texttt{browse} buttons +% allow to select a directory for the former, and an url among a list +% of mirrors for the latter. +\item[Root Page] + On this page, you will tell where you want the files to be + installed (Figure~\ref{graph:root-schm}, + \ifnum \Status = 1 + on the left% + \else\ifnum \Status=2 + at the top% + \else + on the left% + \fi\fi + ). Only the root directory really matters, the other ones + are set according to the root one. You may want to make + \path|$TEXMFEXTRA| point to some TDS compliant directory with other + \TeX{} files or assign a different value to + \path|$HOMETEXMF|, which is set by default to whatever Windows think + is your `HOME' location. +\begin{figure*}[!htb] + Root and directories\hfill% + Scheme selection + \begin{center} + \ifnum \Status=1 + \includegraphics[width=.46\textwidth]{../pictures/root-of-installation.jpg}\hfill% + \includegraphics[width=.46\textwidth]{../pictures/scheme-selection.jpg} + \else + \ifnum \Status=2 +\includegraphics[bb=0 0 506 403]{../pictures/root-of-installation.gif} +\includegraphics[bb=0 0 506 403]{../pictures/scheme-selection.gif} + \else + \includegraphics[width=.46\textwidth]{../pictures/root-of-installation}% + \hfill% + \includegraphics[width=.46\textwidth]{../pictures/scheme-selection} + \fi + \fi + \caption{\TeXLive-Setup: Root and directories / Schemes}\label{graph:root-schm} + \end{center} +\end{figure*} +\item[Get TPM Page] + This page does not require any manual intervention. The \file{.tpm} + files which describe collections and packages are retrieved + (possibly from the Internet), unzipped if needed and parsed. +\item[Schemes Page] + On this page, you will select the global scheme of your + installation (Figure~\ref{graph:root-schm}, + \ifnum \Status = 1 + on the right% + \else\ifnum \Status=2 + at the bottom% + \else + on the right% + \fi\fi + ). A scheme is a large set of files targeted at some kind + of usage. There are 3 generic schemes for basic, recommended and + full installation. The other ones are devoted to LUGs (what GUST or + GUTenberg propose for their members) or applications (XML and + \TeX{}). + When a scheme is selected, it is still possible to refine the + selection by checking the appropriate box. If doing so, you will be + presented the packages page to change your selection, else you will + jump to the review page. +\item[Packages Page] + Collections and packages are presented in a tree form + (Figure~\ref{graph:win32-support}, + \ifnum \Status = 1 + on the left% + \else\ifnum \Status=2 + at the top% + \else + on the left% + \fi\fi + ). The links + in the tree are dependency links. Collections \emph{depend on} + packages and maybe other collections, and it is the same for each + package. You can select any package or collection individually, but + your request will be granted only if the object is not requested by + another one which is selected. For example, you can't deselect + \texttt{tex-basic} without deselecting all the collections that + request it. + + The \texttt{win32-support} collection displayed on the picture is Win32 specific. It + holds a number of bonus packages (Figure~\ref{graph:win32-support}, + \ifnum \Status = 1 + on the right% + \else\ifnum \Status=2 + at the bottom% + \else + on the right% + \fi\fi + ) which can be installed + automatically and individually: Ghostscript, the PostScript + interpreter, \TeX{} oriented editors, tools like Perl, + \LaTeX{}2HTML, etc. \emph{None of these packages are selected by + default}. Some of them have an Internet Explorer icon on their + right, this means that they are not on the \CD{} and they will be + available only if you previously enabled Internet + downloading. \emph{This collection cannot be selected entirely at + once: you need to select the packages individually}. This is to + avoid unwanted downloads of huge files. + + On this page, you also have the information about disk space + needed, for each object, and for the set of those who are selected, + and also the disk space available on the partition selected for the + installation. Last, you can choose to install or not the + documentation files and source files associated with each package. +\item[Review Page] + You will find there a summary of your choices + (Figure~\ref{graph:review}, + \ifnum \Status = 1 + on the left% + \else\ifnum \Status=2 + at the top% + \else + on the left% + \fi\fi + ). It is still time to + go back to change them. +\begin{figure*}[!htb] + Packages Page\hfill% + Win32 Support + \begin{center} + \ifnum \Status=1 + \includegraphics[width=.48\textwidth]{../pictures/package-selection}\hfill% + \includegraphics[width=.48\textwidth]{../pictures/win32-support} + \else + \ifnum \Status=2 +\includegraphics[bb=0 0 506 403]{../pictures/package-selection.gif}\hfill% +\includegraphics[bb=0 0 506 403]{../pictures/win32-support.gif} + \else + \includegraphics[width=.48\textwidth]{../pictures/package-selection}% + \hfill% + \includegraphics[width=.48\textwidth]{../pictures/win32-support} + \fi + \fi + \end{center} + \caption{Packages Page / Win32 goodies} + \label{graph:win32-support} +\end{figure*} +\item[Files Copy Page] + The selected files are copied on your hard disk (Figure~\ref{graph:file-copy}, + \ifnum \Status = 1 + on the right% + \else\ifnum \Status=2 + at the bottom% + \else + on the right% + \fi\fi + ). All the files not + yet available on your local disk are first downloaded from the + remote source directory on the Internet. Then every package is + unpacked (if \path|.zip| files), or copied from the \CD{}. +\item[Configuration Page] Several packages need some configuration + step to make them usable (Figure~\ref{graph:configuration}, + \ifnum \Status = 1 + on the left% + \else\ifnum \Status=2 + at the top% + \else + on the left% + \fi\fi + ). Also the \TeXLive{} system needs some post-processing step + (format files generation, ls-R databases generation, environment + variables, etc.). All these operations are done there, some of them + can be lengthy. +\begin{figure*}[!htb] + \textbf{Review Page}\hfill% + \textbf{File Copy Page} + \begin{center} + \ifnum \Status=1 + \includegraphics[width=.48\textwidth]{../pictures/review-settings}\hfill% + \includegraphics[width=.48\textwidth]{../pictures/file-copy} + \else + \ifnum \Status=2 + \includegraphics[bb=0 0 506 403]{../pictures/review-settings.gif}\hfill% + \includegraphics[bb=0 0 506 403]{../pictures/file-copy.gif} + \else + \includegraphics[width=.48\textwidth]{../pictures/review-settings}\hfill% + \includegraphics[width=.48\textwidth]{../pictures/file-copy}% + \fi + \fi + \end{center} + \caption{Review Page / File Copy Page} + \label{graph:review}\label{graph:file-copy} +\end{figure*} +\item[Final Page] The installation being over, you may want to display + the Windows specific documentation (HTML format) and / or the log + file of the setup process (Figure~\ref{graph:final} + \ifnum \Status = 1 + on the right% + \else\ifnum \Status=2 + at the bottom% + \else + on the right% + \fi\fi + ). If it is needed (Win9x/WinME), you will + be asked to reboot your computer. +\end{description} + +\begin{figure*}[!htb] + \textbf{Configuration Page}\hfill% + \textbf{Final Page} + \begin{center} + \ifnum \Status=1 + \includegraphics[width=.48\textwidth]{../pictures/configuration}\hfill% + \includegraphics[width=.48\textwidth]{../pictures/congratulations} + \else + \ifnum \Status=2 + \includegraphics[bb=0 0 506 403]{../pictures/configuration.gif}\hfill% + \includegraphics[bb=0 0 506 403]{../pictures/congratulations.gif} + \else + \includegraphics[width=.48\textwidth]{../pictures/configuration}\hfill% + \includegraphics[width=.48\textwidth]{../pictures/congratulations}% + \fi + \fi + \end{center} + \caption{Configuration Page / Final page} +\label{graph:configuration}\label{graph:final} +\end{figure*} + +Please be aware that the choice of cluster size on DOS disk +partitions can radically affect the size of your \TeX\ +installation. The support tree has hundreds of small files, and it is +not unusual for a complete installation to take up to 4 times the +amount of space used on the \CD. + + +\section[Maintenance and other aspects of the \protect\TeXLive{} +installation under Windows]{Maintenance and other aspects of the \protect\TeXLive{} +installation under Windows} + +\subsection{What's different under Win32 from the standard \Webc ?} +The Win32 version of \Webc{} has some specific features that need to +be noticed. + +\begin{description} +\item[\KPS{}] the hash-tables that \KPS{} builds are quite large for + the \TeXLive{}. In order to cut down the starting time of any + \KPS{}-enabled program, these hash-tables have been put in shared + memory. This way, when you chain the execution of several such + programs, like \path|tex| calling \path|mpost| calling \path|tex|, + the overhead when starting each of the programs but the first will + be reduced. This change is hidden to the user, except if you set the + debug flag of kpathsea to the \path|-1| value: you will then trace + access to the shared memory, which is not what you want (it is + accessed very often!). What is useful in a log trace of the shared + memory access is still to be defined, so the situation might evolve + in the future. +\item[\cmdname{kpsecheck}] this command provides some option that did + not fit well into \cmdname{kpsewhich}. It will allow you to list all + the files that occur multiple times across your texmf trees. This + could be handy, but most of the time you will also get unwanted + output (like dozens of \path|README| files)\footnote{It is noticeable + that all these files result in clashes inside the \KPS{}-hashing + mechanism, fortunately, \KPS{} never look for these files.}. For + this reason, you can combine the \path|-multiple-occurences| with 2 + other options for including or excluding any filename that match + some pattern (you can request for several patterns). + + The \cmdname{kpsecheck} command will also report the status of + shared memory: in use or not used. That might be useful to know + because if the status reported is ``in use'', that means one or + several processes are working, and the effect of any + \cmdname{mktexlsr} command will be delayed until the next time where + no \KPS{} linked process will be running. + + Last, this same command will report about the location it thinks + Ghostscript can be found. Under Win32, for many programs, it is + easier to use the Ghostscript dll, and find it by using the + Ghostscript registry key than to change the \path|PATH|, which has a + limited length anyway. +\item[\Webc{}] the engines have a few more options than the ones from regular + \Webc{}, and one option with a different behaviour: + \begin{itemize} + \item the \path|-fmt| option behaves differently. Previously and + with the regular \Webc{} distribution, this option has 2 different + meanings when you are in ``ini'' or ``vir'' mode. Under Win32, it + has the same meaning: preload the format file specified with the + argument. The meaning of building a format of such name in ``ini'' + mode is obtained by the new \path|-job-name| option. + \item \path|-job-name| option: allows to set the name of the file + resulting from the compilation process. In normal mode, it will + change the base name of all files produced (\path|.dvi|, + \path|.aux|, etc.), while in ``ini'' mode, it will set the name of + the format file written. + \item \path|-halt-on-error| stop the compilation at the first error. + \item \path|-job-time| set the job time to the same timestamp as the + file given in argument. + \item \path|-output-directory| allow to write all the output files in the + specified directory. + \item \path|-time-statistics| print statistics about the job run + time. It is to be noted that Win9x not being a true multitasking + operating system, it has no reliable timer for short periods, so + the value printed is an approximation. Under NT/2K/XP, the result + is quite accurate with user time and system time values allocated + for this run. For Unix + users: the \path|time| command is not usually available to Windows + users. + \end{itemize} +\end{description} + +\subsection{Adding packages to your installation} + +You will find an option in the \texttt{TeXLive} menu (or go to +\texttt{Start -> Programs -> TeXLive -> Add TeX package} menu) to run again +\file{TeXSetup.exe}, but in maintenance mode this time. The steps you +will go through are almost identical to the ones the first time you +run it. + +The only different step is about the packages selection page. In +maintenance mode, the list of installed packages is compared to the +list of packages available from your source directories. Packages that +are not installed will be displayed in green, out of date packages +will be displayed in red and up to date, installed packages are +displayed in black. + +This way, you can choose to add or upgrade components, either from +your \CD{} or from the +Internet, where you are likely to find some more recent version of +your packages. + +It is up to you to select which ones of the packages you want to +install. The rest of the process is similar to the first installation. + +If you want to add files that are not provided by the \TeXLive{} (or +\fpTeX{}) distribution, it is recommended to put them in the +\path|$TEXMFLOCAL| directory. This way, you will be safe against +upgrades of the \TeXLive{} software. + +The directory pointed to by \path|$TEXMFLOCAL| is initially empty. If +you want to add there the support file for Maple (symbolic computation +program) for example, you will have to put the style files in:\\ +\path|c:\Program Files\TeXLive\texmf-local\tex\latex\maple\|\\ +and the documentation files in:\\ +\path|c:\Program Files\TeXLive\texmf-local\doc\latex\maple\| + +Next, \textbf{do not forget to rebuild the ls-R databases files}, +either by using the right menu (Start -> Programs -> TeXLive + -> Maintenance), either by manually running the \file{mktexlsr} + command. + +\subsection[Removing \protect\TeXLive{} from your hard disk]{Removing + \protect\TeXLive{} from your hard disk} + +The uninstall procedure is available either from the +\file{TeXLive.exe} program, from the \path|TeXLive| menu or from the +control panel (Start menu -> Control Panel, Add/Remove Programs +option). This procedure will cleanup your hard disk of most of the +\TeXLive{} files. However, \TeX{} is a system that is creating files +and there is no mechanism to keep track of all of them. Moreover, +Win32 support packages have their own uninstall procedure, which you +will have to run separately (provided you want to get rid of them). Last, +the files you may have stored in \path|$TEXMFLOCAL| won't be +removed. So, even if the vast majority of files are automatically +removed by the uninstall procedure, you will have to do some manual +cleanup to actually remove all of them. + +\subsection{Running \texttt{TeXSetup.exe} from the command line} + +The \path|TeXSetup.exe| program has a number of other interesting +options. You can get the list by running: +\begin{verbatim} +c:\>TeXSetup --help +\end{verbatim} + +Here is the description: +\begin{description} +\item[\path|--automatic-reboot|] reboot without waiting user + confirmation once installation is over; +\item[\path|--dry-run|] do nothing, just log everything that will be + done without this option; +\item[\path|--quick|] use the recommended installation and default + directories, ask nothing up to rebooting; +\item[\path|--net-method (=ie5/direct)|] enable to download components with + restricted licenses from the Internet (either using direct + connection of Internet Explorer 5 DLLs): you need to have an available + network connection and some of the packages are huge; +\item[\path|--remote-source-directory <url>|] this is the base url for the remote packages; +\item[\path|--local-source-directory <dir>|] by default, \path|TeXSetup.exe| + will guess the root directory of the set of files you want it to act on, if you ever + upgrade \path|TeXSetup.exe|, you won't be able to copy the new version + onto your \CD{}, so you will need to use this option to specify the + root of the \CD{}; +\item[\path|--installation-directory <dir>|] this is the root of your + installation, all files will be copied under this location. The + default value is \verb+c:\Program Files\TeXLive+; +\item[\path|--texmfmain-directory <dir>|] +\item[\path|--texmflocal-directory <dir>|] +\item[\path|--texmfextra-directory <dir>|] +\item[\path|--texmfhome-directory <dir>|] +\item[\path|--vartexmf-directory <dir>|] +\item[\path|--vartexfonts-directory <dir>|] these are the directories + used to configure the location of your files. They map directly to + the \path|texmf.cnf| variables. +\item[\path|--with-source-files(=yes/no)|] copy the source files + for \TeX{} packages, default value is no; +\item[\path|--with-documentation-files(=yes/no)|] copy documentation files for \TeX{} + packages. Default value is yes. Beware: this is only documentation about specific + packages, general documentation will be installed anyway; +\item[\path|--program-folder <folder>|] the name of the folder under + which you will find the menus; +\item[\path|--add-package <pkg>|] this is used to add or update a specific + package after a first regular installation; +\item[\path|--scheme <pkg>|] install the named scheme instead of the + default \path|texlive-recommended| scheme; +\item[\path|--maintenance|] mostly the same as \path|--add-package| + without specifying a package to add; +\item[\path|--uninstall|] this option will remove anything \TeX{} related coming from + the \CD{}, which means there can be files left if you added style + files or format files, and also that supplementary tools will not be + removed\footnote{This option is still a bit crude as of \today}; +\item[\path|--help|] this option opens up a box with the list of options. +\end{description} + +\subsection{Network installation} + +\KPS{} knows about UNC names, so you can use them to get your TEXMF +tree from the network. But there is better than this. +All the support files and configuration files, everything except the files in the +\path|bin/win32| are shareable with a \teTeX{} or Unix \TeXLive{} installation. That means +you can use Samba either to mount from an NT server to a Unix +workstation or the converse. Several strategies are possible: +\begin{itemize} +\item Put everything on the server. Just add each set of files for the os and +architecture you want to use in the \path|bin| directory. That means +for example \path|bin/win32| and \path|bin/i386-linux|. Next configure +your main variables. You can use UNC names to +point to the right directories under Win32. +\item Install a local copy for the binaries and format files. In this + case, assign \path|$TEXMFMAIN| to the main \path|texmf| tree that + will be accessed remotely. Set \path|$VARTEXMF| to be a local + directory which will hold local configuration files and on-the-fly + generated files. +\end{itemize} + +\subsection{Personal Configurations} + +\subsubsection{\cmdname{WinShell}} +\label{sec:winshell} + +Start this program from the Start menu or from the Desktop shortcut. +Go to \textbf{Options} \verb+->+ \textbf{Program Calls}. + +\begin{itemize}\itemsep 0pt +\item In the DVIWin tab, if the filename is \textbf{yap}, replace it +with \textbf{windvi.exe}. +\item In Ghostview tab, make sure it gives the correct path for +gsview32.exe:\\ +\hspace*{1em} \verb+C:\ghostgum\gsview\gsview32.exe+ (for 3.6, the +current version)\\ +or \\ +\hspace*{1em} \verb+C:\gstools\gsview\gsview32.exe+ (for the older +version) + +\end{itemize} + +Click \textbf{OK}. + +Note that the install process sets all files with the \texttt{.tex} +extension to open with \cmdname{WinShell}. Unless you plan to use another editor +(such as WinEdt or Emacs), this is appropriate. + +Unfortunately, \cmdname{WinShell} does not have a spell-checking feature. +However, if you have installed the \path|tex-extrabin| collection, +your installation includes \textbf{Ispell} (a spell checking program +found on most Unix systems). The executable is in your PATH so +\verb+ispell.exe+ will be found if you invoke it from a DOS window. +If you installed documentation, look +at\\ +\verb+C:\Program Files\TeXLive\texmf\doc\html\manpages\ispell.html+\\ +for information on Ispell. (Otherwise, you can find +\verb+ispell.html+ on the CD.) If you rely on spell checking, you may +want to add an Ispell icon to \cmdname{WinShell}. See +subsection~\ref{winshell:ispell} of this document for how to do that. + +For an excellent commercial (but inexpensive) spelling checker, +see \url{http://www.microspell.com}. + +%Appendix B also contains other information about using \cmdname{WinShell}, such as: +% +%\begin{itemize} +%\item How to apply a bug fix you probably need +%\item How to print directly from \cmdname{WinShell} +%\item How to use the Project feature for multiple-file documents +%\end{itemize} + +\cmdname{WinShell} also has on-line help, which you can access via the +$\textbf{\underbar{?}}$ on the menu bar. + +Other information about using \cmdname{WinShell} can be found in +section \ref{winshell:more} on p.~\pageref{winshell:more}. + +\subsubsection{Dvips} + +The configuration file for dvips can be found in\\ +\verb+C:\Program Files\TeXLive\texmf-var\dvips\config\config.ps+\\ +You may open it with any editor (\cmdname{WinShell} will do fine) and change +some parameters: + +\begin{description} +\item [fonts] you can change the default printer \MF{} mode or printer + resolution in case dvips needs to generate PK fonts. By default it + is configured to use type1 versions of the CM fonts, so it should + not call \cmdname{mktexpk} too often; +\item[printer] you can tell dvips where you want to print by + default. If the `o' option is not followed by a printer name, then a + \file{.ps} PostScript file is written. You can give dvips a printer + name such as: +\begin{verbatim} +o lpt1: +% o | lpr -S server -P myprinter +% o \\server\myprinter +\end{verbatim} +\item[paper] Next, you might want + to change the paper size from European (A4) to US letter + by making the US letter the first paper size mentioned in the file. + Scroll to the group of lines beginning with ``@''. Move + the appropriate lines so that this section begins with the lines:\\ +\hspace*{1em} @ letterSize 8.5in 11in\\ +\hspace*{1em} @ letter 8.5in 11in\\ +\hspace*{1em} @+ \%\%BeginPaperSize: Letter\\ +\hspace*{1em} @+ letter\\ +\hspace*{1em} @+ \%\%EndPaperSize +\end{description} + +\textbf{Note:} The current \TeXLive{} distribution has implemented (for +the first time!) the procedure of making always up-to-date fontmaps files +for Dvips and Pdftex. This is done by \cmdname{updmap} program +during installation, as well as during any font package addition. +If you add new packages by hand, edit the file \verb+updmap.cfg+ +in \path|$VARTEXMF/web2c|. + +\subsubsection{Pdftex} +If you want to use the program pdf{}latex to convert directly to +pdf format, and you are using US letter file, edit the file\\ +\verb+C:\Program Files\TeXLive\texmf-var\pdftex\config\pdftex.cfg+\\ +and change ``page\_width'' and ``page\_height'' to specify letter-size paper. +These entries should read:\\ +\hspace*{1em} page\_width 8.5 true in\\ +\hspace*{1em} page\_height 11 true in\\[6pt] +Save the file and exit the editor. + +\subsubsection{GSView} +Starting from versions compatible with Ghostscript 6.50, GSView is not +free anymore, but shareware. So it is not on the \CD{} anymore. + +You may want to change the papersize to US letter size. If so, +open GSView from the Start menu. \\ +From the \textbf{Media} menu, select \textbf{Letter}. + +Also, there are menu settings that are supposed to give you the +most readable screen image:\\[4pt] + From \textbf{Media} \verb+->+ \textbf{Display Settings}, +set \textbf{Text Alpha} +and \textbf{Graphics Alpha} both to 4 bits. + +Note that the installation process has set all .ps and .eps files +to automatically open with GSView. + +For printing instructions, see section~\ref{printing} below. + +\subsubsection{WinDvi} +\label{sub:windvi} + +The \file{TeXSetup.exe} program takes care of associating the files +with the \file{.dvi} extension with \file{Windvi}. + +Open it from the Start menu (Programs \verb+->+ TeXLive \verb+->+ DVI Viewer). +You can set it for US letter paper by going to \textbf{View} \verb+->+ \textbf{Options} +and next to \textbf{Papertype}, +selecting US (8.5\verb+"+ x 11\verb+"+). +Click \textbf{OK}. +Exit Windvi. +You can change other parameters from there, like the ability to +execute commands included in path|\special{}|. +Also, the first time you +view any .dvi file, you may find the magnification too large. Zoom out +until you get an appropriate size. + +%There are two important parameters related to printing that can't yet +%be set from the dialog boxes, namely the resolution and the \MF{} mode +%for the printer. You can set them once for all by specifying them on +%the command line: +%\begin{verbatim} +%c:\>windvi -p 360 -mfmode canonbjc foo.dvi +%\end{verbatim} +%When you will exit Windvi, these parameters will be stored in the +%configuration file. The available modes are found in this file:\\ +%\path|c:\Program Files\TeXLive\texmf\metafont\misc\modes.mf| + +All the configuration for Windvi is stored in the +\path|$HOME/windvi.cnf| file. You can find it by running this command +at the prompt: +\begin{verbatim} +c:\>kpsewhich --expand-var $HOME/windvi.cnf +\end{verbatim} + +Should you have problems with Windvi, please remove the configuration +file and test your problem against a vanilla configuration. + +\subsection{Testing} + +You can test \cmdname{WinShell} by opening the file \verb+sample2e.tex+, found in +\path|C:\Local\TeX\texmf\tex\latex\base|. The \LaTeX\ source should appear +on the screen. Process it by clicking on the \LaTeX\ icon on the toolbar, +then view it by clicking on the Preview (Windvi) icon. + +At first, when you preview files with Windvi, it will create fonts because +screen fonts were not installed. After a while, you will have created most +of the fonts you use, and you will rarely see the font-creation window. +Return to \cmdname{WinShell} and try dvips, then GSView. + +\textbf{Hint for the future:} If a \LaTeX\ run stops because \LaTeX\ +cannot find a file, you can press \textbf{Ctrl-z} to quit. + +\subsection{Printing}\label{printing} + +It is possible to print from Windvi. In this case, printing will +be done using the Windows unified printer driver. By definition, it +is compatible with all printers. However, there is some drawback: it +can generate some huge spool files, and some (older) versions of Windows just +don't like them. The advantage is that you can use features like +embedding BMP or WMF images. You also need to make sure that the +printer parameters are correctly set (subsection~\ref{sub:windvi}), +else you will get scaled printing (printing at 600dpi on a 300dpi +printer will give you only one quadrant of your page). + + +Printing is faster and more reliable if you run dvips to make a +.ps file and then print from GSView. To print from GSView, first select +\textbf{Print...} from the \textbf{File} menu. A Print window will appear. + +If you will be using a PostScript printer, \textit{be sure to select +\textbf{PostScript Printer}}. In the newer version this is done in +the ``Print Method'' box at the bottom left of the Print window. You +can then select any of the printers that you have previously installed +on your PC. If you fail to check the box for PostScript Printer, +printing will not work. + +If you will be using your own non-PostScript printer, select +\textbf{Ghostscript device} in the ``Print Method'' box, then click on +the button to the right labelled \textbf{djet500} and select your +printer type from the list that pops up. (In the older version of +GSView, make sure PostScript Printer is \textit{not} selected, then +select your printer type from the ``Device'' list.) + +If you use \cmdname{WinShell} and a PostScript printer, probably the most +convenient way to print is to add an icon to the \cmdname{WinShell} toolbar that +invokes dvips in a way that sends the output directly to a default +printer. For detailed instructions on how to do this, see +\ref{winshell:print} on p.~\pageref{winshell:print} +(\textit{More About \cmdname{WinShell}}). + +\subsection{More About \cmdname{WinShell}}\label{winshell:more} +\subsubsection{Installing Bug Fixes} + +\cmdname{WinShell}'s author (\href{mailto:idb@winshell.de}{Ingo de Boer}, +thanks to him) sometimes releases beta versions of the next \cmdname{WinShell} +version which are also bug fixes. You can grab them from +\url{http://www.winshell.de}. Usually they are \file{.zip} files that +only require to be unpacked in \cmdname{WinShell} directory (\path|c:\Program +Files\WinShell| by default), either using WinZip or a similar tool, or +by using \file{unzip} on the command line. If you got some +\file{winshellbugfix.zip} file and that you saved it in the \cmdname{WinShell} +directory, then you need to run: +\begin{verbatim} +c:\>cd c:\"Program Files"\WinShell +c:\>c:\local\bin\unzip winshellbugfix.zip +\end{verbatim} +Say `yes' if you are asked if some files should be overwritten. The +\path|unzip.exe| programme can be found in the +\path|support/gnu-utils| package. If you +do not have it on your machine, you can use any archiver tool like +WinZip to achieve the same effect. + +\subsubsection{Using the Project Feature} +If your document is split into several files +(for example a thesis), look into \cmdname{WinShell}'s ``Project'' feature. From the +\textbf{Project} menu, you give the project a name (e.g., Thesis), +supply the name of the main (or root) file, and then ``add'' other +files. These filenames display on the left of the screen where you can +double click the names to view and switch between them. Clicking +the \textbf{\LaTeX} icon always processes the main file. + +Note the icons on the toolbar for toggling the project space (on the left) +and the log space (at the bottom). If you are not using the Project +feature, you may want to toggle off the space on the left, using the full +screen width to display your file. + +\subsubsection{Printing from \cmdname{WinShell} to a PostScript Printer} +\label{winshell:print} + +The Dvips icon on the \cmdname{WinShell} toolbar puts the PostScript output in a file, +which you can then view with GSView and print from there if you choose. +However, it's convenient to add a \cmdname{WinShell} ``program call'' to dvips which +sends the output directly to a designated PostScript printer. The steps +below show how to do this for the printer \textbf{vclw}; you should +substitute the name of your most frequently-used printer for \textbf{vclw}. +\begin{enumerate} +\item Make the program aware of the printer: +\begin{itemize} + +\item Open \cmdname{WinShell}, go to \textbf{Options} \verb+->+ +\textbf{Program Calls} \verb+->+ \textbf{User defined}. + +\item Click on \textbf{Tool 1} in the list on the right and fill in the +fields to the left as follows:\vspace{-6pt} +\begin{quote} +Name: \verb+Print+\\ +exe file: \verb+dvips+\\ +cmd-line: \verb+ -D600 %m -o vclw+\\ +Uncheck the box for ``DVIPS first'' +\end{quote}%\vspace{-12pt} +\item Click \textbf{OK} +\end{itemize} +\item Add Print to the toolbar: +\begin{itemize} +\item Go to \textbf{Options} \verb+->+ \textbf{View} \verb+->+ \textbf{Customize}. +\item In the Category box, select \textbf{User-Programs}. +\item Select \textbf{Print} and drag it to the toolbar, placing it just to + the right of the GSView icon. +\item You then have a choice of ``Image only'', ``Text only'', or ``Image and +Text''. The easiest is to select ``Text only'' and click \textbf{OK}. +You should then see \textbf{Print} on the toolbar. (If you prefer, you can +select ``Image only'', then ``Edit'', and edit the displayed picture to your +satisfaction.) +\end{itemize} +\end{enumerate} +Now, to print a \LaTeX\ document, just click on the \textbf{Print} icon to +send to your selected printer. To use a different printer, you will need to +click on the \textbf{Dvips} icon to print to a file. Then click on the +GSView icon and use GSView to send to any printer you have installed on +your PC. + +\subsubsection{Adding Ispell to \cmdname{WinShell}} +\label{winshell:ispell} +\begin{enumerate} +\item Add Ispell to User Tools: +\begin{itemize} +\item Open \cmdname{WinShell}, go to \textbf{Options} \verb+->+ +\textbf{Program Calls} \verb+->+ \textbf{User defined}. +\item In the list on the right, click on \textbf{Tool 1} (or \textbf{Tool + 2} if you have already used \textbf{Tool 1}) and fill in the +fields to the left as follows:\vspace{-6pt} +\begin{quote} +Name: \verb+Ispell+\\ +exe file: \verb+ispell+\\ +cmd-line: \verb+ -t -d american %c.tex+\\ +Uncheck the boxes for ``LaTeX first'' and ``DVIPS first'' +\end{quote}%\vspace{-12pt} +\item Click \textbf{OK} +\end{itemize} + +\item Add Ispell to the toolbar: %\vspace{-14pt} +\begin{itemize}\itemsep 0pt +\item Go to \textbf{Options} \verb+->+ \textbf{View} \verb+->+ \textbf{Customize}. +\item In the Category box, select \textbf{User-Programs}. +\item Select \textbf{Ispell} and drag it to the toolbar, placing it just to + the right of the GSView icon (or the last icon you added). +\item You then have a choice of ``Image only'', ``Text only'', or ``Image and +Text''. The easiest is to select ``Text only'' and click \textbf{OK}. +You should then see \textbf{Ispell} on the toolbar. (If you prefer, you can +select ``Image only'', then ``Edit'', and edit the displayed picture to your +satisfaction.) +\end{itemize} +\end{enumerate} +Now, when you have a \LaTeX\ document open, you can click on +\textbf{Ispell} to perform spell checking. Ispell will open another window +and display the first misspelled word on the left with the filename on the +right. Below that you will see the context in which the misspelling appears; +often several suggestions for replacements are also displayed. To replace +the word, enter the number corresponding to the desired replacement. Other +possible responses are listed below; for example, you can press the space +bar to ignore the misspelled word. For more information on Ispell, read the +manual page: \verb+C:\Program Files\TeXLive\texmf\doc\html\manpages\ispell.html+. + +Note that when you replace a word, you will not see the correction in your +\cmdname{WinShell} window until you close the file (click the X in the upper right +corner) and then open it again (use the File menu). + +\subsection{Tips and tricks about the Win32 platform} + +\subsubsection{Different flavors of Win32} + +What we call Win32 is not an operating system by itself. It is a set +of functions -- and a large one\footnote{Around 12000 functions in the + header files of the Microsoft SDK} -- that you can use to write +programs for different operating systems of the Windows family. + +Windows comes in different flavors: +\begin{itemize} +\item Win95, Win98 and WinME, which \emph{are not true multitasking, + multithreading} environments. They are the latest -- and hopefully + last -- metamorphosis of DOS. This can be more or less proven by the + fact that when booting, the PC will load the \path|command.com| + interpreter, and if you stop the boot process at this point, you can + ask for the current (DOS) version and it will answer something like + 'MS-DOS 7.0' (at least for the old versions of Win9x); +\item Windows NT, which is a new operating system written from scratch, + capable of + true multitasking behaviour, and loaded with high level features; +\item Windows 2K, written on an NT basis, with all the bells and + whistles of Win98. +\item Windows XP, which comes with Personal and Pro flavors. This is + the last step in merging both lines of products (Win9x based and NT + based). XP is written on an NT basis. +\end{itemize} + +Win9x are able to run 32~bits programs and 16~bits programs +concurrently. But the operating system by itself is not entirely +written in 32~bits mode, and does not support memory protection: 16bits +applications can overwrite parts of the operating system memory! Some +parts of the system like the GDI (Graphical Device Interface) manage +limited resources like bitmaps, fonts, pens and so on for the set of +all programs that run concurrently. All the bitmaps headers available +at the same time can't amount for more than 64kb. This explains the +performance tool and the fact that you can put your system on his +knees by making intensive use of graphic objects for example. + +NT, 2K and XP do not suffer from these limitations, and neither from +other Win9x limitations. They are true multitasking environments, with +protected memory. They are much more responsive than Win9x because +of better memory management, better file system and so on. + +\subsubsection{Command line prompt} + +You will wonder: ``why would I need to use a command line prompt when +I have Windows?''. + +Good question. The problem is of very general nature. Not all +operations can be done easily using only a GUI. Command line gives you +programming power -- assuming a clever command interpreter. + +But the problem here is more fundamental: \TeX{} is \emph{a batch} +tool. Not an interactive one. \TeX{} needs to compute the best +layout for each page, resolve cross-references and so on. This can be +done only by a global processing of the document. It is not (yet) a +task that can be done interactively. + +This means that you should use \TeX{} from a command line. In fact the +situation is not so bad. There is an advantage to write command line +tools for complex processing: they are better debugged, because not +tied to GUI problems, and GUI tools can be designed to interface the +command line tools. This is the case for \TeX{} where you will +interact with it most of the time through a GUI text editor -- see +section~\ref{sec:winshell} for example. + +However, you may need to use the command line prompt in a number of +situations, by example in case of problems and you want to debug your +setup -- see + section~\ref{sec:troubleshooting}. + + \begin{description} + \item[Win9x] You will open a command line prompt by looking either + for the MS-DOS icon in the ``Start->Programs'' menu, either by + choosing ``Start->Run'' menu and typing in \path|command.com| + \item[NT, 2K, XP] You will open a command line prompt by looking + for the ``Command Prompt'' in the ``Start->Accessories'' + menu\footnote{These locations may change across different OS + versions.}. You can also choose the ``Start->Run'' menu and type + in \path|cmd.exe|, which is the name of the brand new command + interpreter for NT\footnote{Which explains why it is untrue to + call this a \emph{DOS} box under NT!}. +\end{description} + +\subsubsection{Path separators} + +The Win32 API understands both \path|/| and \path|\| characters as +PATH separators. But the command interpreters do not! So whenever a +path name is used programmatically, you can use both separators, and +even mix them up in the same path name. But on the command line, you +must type \path|\| as path separator. The reason is compatibility: +the command processor used the \path|/| to introduce arguments to +commands. + +All this to say: do not be surprised to read path names written using +the Unix convention; \fpTeX{} is a port of \Webc, and aims to be compatible +across platforms. For this reason, all the configuration files that +need to specify path names use the Unix convention. + +\subsubsection{File systems} +\label{sec:clusters} + +The worse feature of Win9x with regard to \TeX{} is probably the +so-called FAT file system. \TeX{} uses many many small files, with +size around 1kb -- 3kb. The FAT file system is old, and predates by +far the multi-gigabytes hard disks we have today. It means it can't +manage efficiently the 30000 \TeX{} files found on the \CD{}. The FAT +file system will allocate a minimum of 32kb for \emph{any} file on a +huge partition. It means that \TeX{} will use much more disk space +than it actually needs. + +The other, more modern, file systems available -- namely FAT32 and +NTFS -- do not have this drawback. They manage clusters of 4kb +only\footnote{You can lower the limit to 512 bytes on NTFS}. + +\subsubsection{How to add some directory to your PATH} + +There are pairs of variables and values which behave much like global +variables inside your programs. The set of those variables is called the +environment. Each program is initialized with a copy of the +environment when it is run. It can request and change the +value of any variable. The changes happen in the copy of the +environment, and is not at all propagated to the other running +programs. + +Your PATH is a special environment variable used to search for +programs you want to run. +There is a different procedure to change it for Win9x, WinME and NT/2K/XP: + +\begin{description} +\item[Windows 95/98] Edit your \path|autoexec.bat|. In this file should be a line + starting with \texttt{PATH=} and followed by a list of directories separated + by \path|;|. Please add the directory with the executables in this line. + After this, this line could look as follows: +\begin{verbatim} +PATH=c:\windows;c:\windows\system;c:\"Program Files"\TeXLive\bin\win32 +\end{verbatim} +\item[Windows ME] You need to run the special program + \path|c:\windows\system\msconfig.exe| to be able to change any + environment variable. From this program, select the `Environment' + tab, and then add or modify the variable you want. You will be asked to reboot the + machine upon any change. +\item[Windows NT/2K/XP] + Click left on \texttt{Start --> Settings --> Control Panel}. Now the window + with the control panel icons opens. Double click on System. The + System Properties window opens. Click on the tab + \textsf{Environment} or look for a button named `Environment + Variables' among the dialog boxes. Now + you can change the environment variables for your user account. Note: + There are also displayed the environment settings for the system. + Normally, you can't change the system variables unless you have + administrator rights on your machine. If you want to change the \texttt{PATH} + for all users, you will have to contact your system administrator or + be the system administrator yourself--in the later case you should + know what you are doing. + + If there is already a \texttt{PATH} setting for your user account, + left click on \texttt{PATH}. In the field \textsf{Variable} appears + \texttt{PATH} while the field Value shows the current setting of + \texttt{PATH} as a list of directories separated by \path|;|. Add + the directory where the executables are located (e.g. + \path|c:\Program Files\TeXLive\bin\win32|). If there isn't a \texttt{PATH} variable + for your user account, simply click in the field Variable and type + in \texttt{PATH}, click in the field \textsf{Value} + and type in the directory with the executables. Important: Click on + the \textsf{Apply} button before clicking \textsf{Ok}, otherwise the + changes to \texttt{PATH} won't apply to your system. Be careful when + changing the environment settings. +\end{description} + +The best way to be sure that a variable has been properly set is to +open a console and type: +\begin{verbatim} +set VARIABLE +\end{verbatim} +which should return the corresponding value. + +\subsubsection{\TeX{} engines} + +If you have a look at the \Webc{} documentation, you will read that all +the various \TeX{} derived programs use the same base engine. For +example, \path|tex.exe| and \path|latex.exe| are exact copies of the +same program, but each one will use a different format file, based on +its calling name. + +Under Unix, this feature is implemented through \emph{symbolic + links}. It saves up a bit of disk space, because some engines are +used with many different format files. + +The Win32 API does not know about file links. So to save up almost +the same amount of memory, all the \TeX{} base engines have been put +in DLLs (\emph{Dynamic Linked Library}). This means that you will have +the following layout: +\begin{alltt} +13/05/2002 17:06 3 584 latex.exe +13/05/2002 17:06 266 240 tex.dll +13/05/2002 17:06 3 584 tex.exe +\end{alltt} +and the \path|latex.exe| file is nothing but a rough copy of +\path|tex.exe| using the same core \path|tex.dll|. +The same trick has been used for the \path|mktex*.exe| family of programs which are +linked to the \path|mktex.dll| library. + +In fact, a generic tool called \path|lnexe.exe| is provided to build the +equivalent of Unix hard links for executable files only under Win32. + +\subsection{In case of problems} +\label{sec:troubleshooting} + +\subsubsection{What to do if \texttt{latex} does not + find your files?} + +\begin{itemize} +\item \cmdname{kpsewhich} is the tool of choice to debug any +problem. Unfortunately, kpsewhich outputs debug information to +stderr, and the Windows console does not know how to redirect stderr +to a file\footnote{Well, NT and Win2k consoles know how to do + that. But the trick will work for any console.}. +For diagnostic purposes you can temporarily set an +environment variable (in DOS box): +\begin{verbatim} +SET KPATHSEA_DEBUG_OUTPUT=err.log +\end{verbatim} +You can also set the debug level: +\begin{verbatim} +SET KPATHSEA_DEBUG=-1 +\end{verbatim} + +If you want to redirect stderr to stdout, which is not possible under +either W9x or NT/2K/XP, then just do: +\begin{verbatim} +SET KPATHSEA_DEBUG_OUTPUT=con: +\end{verbatim} +This way you can capture both stdout and stderr in the same file. + +\item Assuming the installation has been done in \path|c:/Program Files/TeXLive|, check + the following values: \\ + {\small + \begin{tabular}{ll} + \path|kpsewhich -expand-path $SELFAUTOPARENT| & \path|c:/Program Files/TeXLive| \\ + \path|kpsewhich -expand-path $TEXMF| & \path|c:/Program Files/TeXLive/texmf| \\ + \path|kpsewhich -expand-path $TEXMFCNF| & + \path|.;c:/Program Files/TeXLive/texmf/web2c;| \\ + & \path|c:/Program Files/TeXLive/bin/win32;| \\ + & \path|c:/Program Files/TeXLive/bin;| \\ + & \path|c:/Program Files/TeXLive| \\ + \path|kpsewhich -expand-var $TEXINPUTS| & \path|.;c:/Program Files/TeXLive/texmf/tex//| + \end{tabular} +} +\item If you have other \TeX{}-related values already set in your + environment, please, remove them. They are overriding the ones in + texmf.cnf. +\item Check the values from:\\ +{\small + \begin{tabular}{ll} + \texttt{kpsewhich cmr10.tfm} & \path|c:/Program Files/TeXLive/texmf/fonts/tfm/public/cm/cmr10.tfm|\\ + \texttt{kpsewhich latex.fmt}& \path|c:/Program Files/TeXLive/texmf/web2c/latex.fmt| + \end{tabular} +} +\item At this point, if everything is correct, \path|tex.exe| and + co. should work. If it is not the case, you will need to play with + the \path|-debug=n| option from \path|kpsewhich|, and check back all + the values. Try to identify and report the problem. +\end{itemize} + +\subsubsection{What to do if your setup still does not work as expected?} + +There are several questions to ask about: +\begin{enumerate} +\item Is \file{tex.exe} on my \path|PATH|? +\item Is the \path|TEXMFCNF| variable correctly set to + \path|c:/Program Files/TeXLive/texmf-var/web2c| (default value)? +\item Are there any errors in the log file generated by the + \file{TeXSetup.exe} program? Errors are flagged with the sequence + \path|Error|. +% \item If everything seems correct up there, then you need to read the +% documentation in \path|texmf/doc/fptex/fptex.pdf| or +% \path|texmf/doc/html/fptex/fptex.html| for a more detailed procedure +% (available on your hard disk or on the \CD{}). +\item One can also go to \url{http://www.tug.org/tex-live.html} and + check for any bug fix. +\item The Windows distribution on the \CD{} is no more no less than + the \fpTeX{} distribution, so you can also go to the Web pages at + \url{http://www.fptex.org}, or consider subscribing to the \fpTeX{} + mailing-list by consulting + \url{http://www.tug.org/mailman/listinfo/fptex} . +\end{enumerate} + + +The \TeXLive{} software is complex and made of more than 250 programs +and around 40000 files from various sources. It is quite difficult to +predict all possible causes for problems. Nevertheless, we will do our +best to help you in every case. + + +\subsection{Compiling the source files} + +You have the whole set of source files, comprised for +Windows in the \path|source/source.tar.bz2| archive available on the +\CD{}. To be able to compile the whole distribution for Windows, you +will need: +\begin{itemize} +\item Windows 2K/XP +\item Microsoft Visual Studio .Net +\item a set of Unix tools (\texttt{sed}, + \texttt{grep}, \texttt{gawk}, etc.) and also Perl, Flex and Bison, +\item to adjust the paths in the + \path|win32/make/common.mak| file according to your installation +\item adjust the paths in the Perl script file + \path|win32/perl/build.pl|, +\item run the compilation from the \path|win32/| directory using this + command: +\begin{verbatim} +c:\texlive\source\win32>perl ./perl/build.pl --install --log=install.log +\end{verbatim} +\end{itemize} + +There is a lot of work to do to make this process easier and cleaner. + +\subsection{Where to get more information?} + +The Win32 \TeX{} distribution on the \CD{} is also known as +\fpTeX. Only the packaging differs, but \fpTeX{} is no more no less +than the current \TeXLive\ release for Windows. + +The \fpTeX home on the Web is at:\\ +\url{http://www.fptex.org/} + +The current \fpTeX release is available from any +\href{http://www.ctan.org}{CTAN} %(see also the section +%\ref{sec:ctan}) +site in the directory~:\\ +\noindent\url{ftp://ctan.tug.org/tex-archive/systems/win32/fptex/}. + +The main ftp site for \fpTeX\ is \url{ftp://ftp.dante.de/pub/fptex/} from +where beta versions of \fpTeX\ and additionnal tools are available. +This main site is (partially) mirrored daily by the CTAN backbones in their +\path|systems/win32/fptex| directory. + +% You can reach me at my email address: +% \url{mailto:Fabrice.Popineau@supelec.fr}. + +The \TeX{} Users Group is kindly hosting a mailing-list dedicated to +\fpTeX. This is a very low volume one. It is used for announcements, +bugs reports or as well to discuss about improvements or various users +problems. To subscribe, read the page at +\url{http://www.tug.org/mailman/listinfo/fptex}. The mailing list +address is \EmailURL{fptex@tug.org}. + +\section{Building on a new Unix 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{source} on the \CD{}. + +You should first install the support tree from the \TeXLive{} \CD{} (do +a basic install, with no system binaries chosen). + +\subsection{Prerequisites} +You will need about 100 megabytes of disk space to compile all of +\TeX{} and its support programs. You'll also need an \acro{ANSI} C +compiler, a \cmdname{make} utility, a lexical scanner, and a parser +generator. The \acro{GNU} utilities (\cmdname{gcc}, \acro{GNU} +\cmdname{make}, \cmdname{m4}, \cmdname{flex}, \cmdname{bison}) are the +most widely tested on different platforms. \cmdname{gcc}-2.7.* +\cmdname{flex}-2.4.7 and \acro{GNU}\,\cmdname{make}-3.72.1 or newer +should work well. You may be able to work with other C compilers and +\cmdname{make} programs, but you will need a good understanding of +building Unix programs to sort out problems. The command +\texttt{uname} must return a sensible value. + + + +\subsection{Configuration} +First, unpack the source from the compressed +\texttt{tar} file in the directory \dirname{source} to your disk and change +directory to where you placed it. Decide where the `root' of the +installation will be, e.g.\ \path|/usr/local| or +\path|/usr/local/TeX|. Obviously you should use the same location +that you specified when you installed the support tree. + +Now, start the build process by running \textsf{configure} with +a command-line like +\begin{alltt} +>> \Ucom{./configure -prefix=/usr/local/TeX} +\end{alltt} + +The `prefix' directory is the one where you installed the support +tree; the directory layout that will be used is as follows (where +\$TEXDIR stands for the directory you chose): + +\noindent +\begin{tabular}{>{\ttfamily}ll@{}} + \dirname{$TEXDIR/man} & Unix manual pages\\ + \dirname{$TEXDIR/share/texmf} & main tree with fonts,\\ + & \qquad macros, etc\\ + \dirname{$TEXDIR/info} & \acro{GNU} style info manuals\\ + \dirname{$TEXDIR/bin/$PLATFORM} & binaries\\ +\end{tabular} +%$ + +You can omit the use of `\dirname{share/}' part for the +\dirname{texmf} directory if you want, as +\dirname{$TEXDIR/share/texmf} and \dirname{$TEXDIR/texmf} are +auto-detected by configure. If you choose something different, you +have to specify that directory with the \verb|--datadir| option of +\textsf{configure}. + + +If you want to leave out the \dirname{$PLATFORM} directory level +(i.e.\ put the binaries directly into \dirname{$TEXDIR/bin}), specify +the \verb|--disable-multiplatform| option for \textsf{configure}. + + +Have a look at the output of \texttt{./configure --help} for more +options you can use (such as omitting optional packages such as \OMEGA\ +or \eTeX). + +\subsection{Running \textsf{make}} +Make sure the shell variable \texttt{noclobber} is not set, and +then type +\begin{alltt} +>> \Ucom{make world} +\end{alltt} +and relax\ldots. + +It could also be useful to log all the output, e.g.\ by +typing +\begin{alltt} +>> \Ucom{sh -c "make world >world.log 2>\&1" \&} +\end{alltt} +Before you think that everything is ok, please check the log file for +errors (\acro{GNU} \cmdname{make} always uses the string +``\texttt{Error:}'' whenever a command returns an error code) and +check if all binaries are built: +\begin{alltt} +>> \Ucom{cd /usr/local/TeX/bin/i686-pc-linux-gnu} +>> \Ucom{ls | wc} +\end{alltt} +The result should be 209. + +If you need special privileges for \texttt{make install}, you can +run two \cmdname{make} jobs in separate runs: +\begin{alltt} +>> \Ucom{make all} +>> \Ucom{su} +>> \Ucom{make install strip} +\end{alltt} + +\subsection{Final configuration steps} +Set up your \envname{PATH} to include the directory containing the +just-installed binaries (e.g.\ +\dirname{/usr/local/TeX/bin/mips-sgi-irix6.5}); similarly, +\envname{MANPATH} and \envname{INFOPATH} to include the relevant newly +installed subdirectories, i.e.\ \dirname{$TEXDIR/man} and +\dirname{$TEXDIR/info}. + +The program \textsf{texconfig} allows you to set the defaults for +hyphenation, paper size, print command, \MF{} mode, etc. You can +run this command interactively and see what options it offers, or type +\begin{alltt} +>> \Ucom{texconfig help} +\end{alltt} + +For example, if you are not using A4 format paper, you can make +`lettersize' the default using: +\begin{alltt} +>> \Ucom{texconfig dvips paper letter} +>> \Ucom{texconfig xdvi paper us} +\end{alltt} + +\section{A user's guide to the \protect\Webc{} system} + +%-------------------------------------------------------- + +\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, and in 1997 he handed the baton to Olaf Weber. The +latest result is \Webc{} Version 7.3, which was released in March +1999. Our version has some updates for the forthcoming new release, +and identifies itself as 7.3.7 + +The \Webc{} 7.3 system runs on Unix, Windows 3.1, 9x/ME/\acro{NT}/\acro{2K}/\acro{XP}, +\acro{DOS}, and other operating systems. It uses Knuth's +original sources for \TeX{} and other basic programs written in \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 core \TeX{} family components are: + +\begin{description} +\renewcommand{\makelabel}[1]{\descriptionlabel{\mdseries\cmdname{#1}}} +\item[bibtex] Maintaining bibliographies. +\item[dmp] \cmdname{troff} to MPX (\MP{} pictures). +\item[dvicopy] Produces modified copy of \dvi{} file. +\item[dvitomp] \dvi{} to MPX (MetaPost pictures). +\item[dvitype] \dvi{} to human-readable text. +\item[gftodvi] Generic font proofsheets. +\item[gftopk] Generic to packed fonts. +\item[gftype] GF to human-readable text. +\item[makempx] \MP{} label typesetting. +\item[mf] Creating typeface families. +\item[mft] Prettyprinting \MF{} source. +\item[mpost] Creating technical diagrams. +\item[mpto] MetaPost label extraction. +\item[newer] Compare modification times. +\item[patgen] Creating hyphenation patterns. +\item[pktogf] Packed to generic fonts. +\item[pktype] PK to human-readable text. +\item[pltotf] Property list to TFM. +\item[pooltype] Display \web{} pool files. +\item[tangle] \web{} to Pascal. +\item[tex] Typesetting. +\item[tftopl] TFM to property list. +\item[vftovp] Virtual font to virtual property list +\item[vptovf] Virtual property list to virtual font. +\item[weave] \web{} to \TeX. +\end{description} +\noindent 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{} 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{\protect\KPS\ 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 +page~\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 sought. + +The ``file must exist'' condition comes into play with \samp{.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 \samp{.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 it transforms all +the specifications into basic directory name or names. This is +described in the following sections in the same order as it takes +place. + +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. + +\ifSingleColumn +\else +\begin{figure*} +\verbatiminput{../examples/ex5.tex} +\setlength{\abovecaptionskip}{0pt} + \caption{An illustrative configuration file sample} + \label{fig:config-sample} +\end{figure*} +\fi + +\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, \envname{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 \envname{TEXINPUTS.latex} will override \envname{TEXINPUTS}. +\item + A program-specific configuration file, for exam\-ple, a line + ``\texttt{S /a:/b}'' in \cmdname{dvips}'s \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} +\noindent You can see each of these values for a given +search path by using the debugging options (see ``Debugging actions'' +on page~\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 \envname{TEXMFCNF} (by default such a file lives +in the \file{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 \verb|.:$TEXMF|, values from \file{./texmf.cnf} override those +from \verb|$TEXMF/texmf.cnf|. + +\tolerance=1500 + +While reading the description of the format of the file +\file{texmf.cnf} below, please also refer to +appendix~\ref{app:texmf.cnf}, starting on +page~\pageref{app:texmf.cnf}, which lists the \file{texmf.cnf} file on +the \CD. + +\begin{itemize} +\item + Comments start with ``\texttt{\%}'' 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 has the form: +\begin{alltt} + \emph{variable}[.\emph{progname}] [=] \emph{value} +\end{alltt}% + where the \samp{=} and surrounding whitespace are optional. +\item + The ``\texttt{\var{variable}}'' name may contain any character other + than whitespace, \samp{=}, or \samp{.}, but sticking to + \samp{A-Za-z\_} is safest. +\item + If ``\texttt{.\var{progname}}'' is present, the definition only + applies if the program that is running is named + \texttt{\var{progname}} or \texttt{\var{progname}.exe}. This allows + different flavors of \TeX{} to have different search paths, for + example. +\item ``\texttt{\var{value}}'' may contain any characters except + ``\texttt{\%}'' and \samp{@}. The + ``\texttt{\$\var{var}.\var{prog}}'' feature is not available on the + right-hand side; instead, you must use an additional variable. A + \samp{;}\ in ``\texttt{\var{value}}'' is translated to \samp{:}\ if + running under Unix; this is useful to be able to have a single + \file{texmf.cnf} for Unix, MSDOS and Windows systems. +\item + All definitions are read before anything is expanded, so + variables can be referenced before they are defined. +\end{itemize} +A configuration file fragment illustrating most of these points is +\ifSingleColumn +shown below: + +\verbatiminput{../examples/ex5.tex} +\else +shown in Figure~\ref{fig:config-sample}. +\fi + +\subsubsection{Path expansion} +\label{Path-expansion} + + +\KPS{} recognizes certain special characters and constructions in +search paths, similar to those available in Unix shells. As a +general example, the 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 +page~\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} +>> \Ucom{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{verbatim} + TEXMF = {$HOMETEXMF,$TEXMFLOCAL,!!$VARTEXMF,!!$TEXMFMAIN} +\end{verbatim} +Using this you can then write something like +\begin{verbatim} + TEXINPUTS = .;$TEXMF/tex// +\end{verbatim} +%$ +which means that, after looking in the current directory, the +\code{\$HOMETEXMF/tex}, \code{\$TEXMFLOCAL/tex}, \code{\$VARTEXMF/tex} +and \code{\$TEXMFMAIN/tex} trees \emph{only}) will be searched (the +last two use using \file{ls-R} data base files). It is a convenient +way for running two parallel \TeX{} structures, one ``frozen'' (on a +\CD, for instance) and the other being continuously updated with new +versions as they become available. By using the \code{\$TEXMF} +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. + +\newcommand{\CODE}[1]{\makebox[2.2em][l]{\code{#1}}} +\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{\char`\{\dots\char`\}}] Brace expansion, e.g., + \verb+a{1,2}b+ will become \verb+a1b:a2b+. +\item[\CODE{//}] Subdirectory expansion (can occur anywhere in + a path, except at its 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 DOS-like ``8.3'' filename conventions in source files. + +\subsubsection{The 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{} hierarchy in +your installation that you wish to be searched (\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{mktexlsr} script included with the distribution. It is invoked +by the various \samp{mktex}\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{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{mktex}\dots\ scripts). + +\begin{alltt} +>> \Ucom{kpsewhich \var{option}\dots{} \var{filename}\dots{}} +\end{alltt} +The options specified in ``\texttt{\var{option}}'' 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 ``\texttt{\var{num}}''; this only affects \samp{gf} + and \samp{pk} lookups. \samp{-D} is a synonym, for compatibility + with \cmdname{dvips}. Default is 600. +\item[\texttt{-{}-format=\var{name}}]\mbox{}\\ + Set the format for lookup to ``\texttt{\var{name}}''. By default, the + format is guessed from the filename. For formats which do not have + an associated unambiguous suffix, such as \MP{} support files and + \cmdname{dvips} configuration files, you have to specify the name as + found in the first column of Table~\ref{TABKpathsea}, which lists + currently recognized names, a description, + associated environment variables%, + \footnote{You can find definitions for these environment variables + in the file \file{texmf.cnf} (page~\pageref{app:texmf.cnf})}, and + possible file extensions. +\end{description} + + +\def\KpathKey#1#2#3#4#5{% name, number, description, variables, + % suffixes +\SetRowColor#1 & #3 & #4 & #5\\} +\def\HEAD#1{\multicolumn{1}{l}{\emph{#1}}} +% +\begin{small} +% a footnoterule immediately under a bottom-of-page rule looks dead +% silly, so we suppress it +\renewcommand\footnoterule{\relax} +% +\begin{longtable}{@{}% + >{\ttfamily}P{.16\textwidth}% Col.1 + P{.3\textwidth}% Col 2 + >{\ttfamily\footnotesize}P{.29\textwidth}% Col 3 + >{\ttfamily}P{.14\textwidth}% Col 4 +@{}} +\caption{Kpathsea file types}\label{TABKpathsea}\\ +\emph{Name} & \HEAD{Description} & \HEAD{Variables} +& \HEAD{Suffixes}\\ +\hline +\endfirsthead +\multicolumn{3}{l}{Kpathsea file types \emph{continued}}\\ +\emph{Name} & \HEAD{Description} & \HEAD{Variables} +& \HEAD{Suffixes}\\ +\hline +\noalign{\vspace{2pt}} +\endhead +\mbox{}\\ +\hline +\endfoot +\KpathKey + {afm} + {4} + {Adobe font metrics} + {AFMFONTS} + {.afm} +\KpathKey + {base} + {5} + {Metafont memory dump} + {MFBASES, TEXMFINI} + {.base} +\KpathKey + {bib} + {6} + {\BibTeX{} bibliography source} + {BIBINPUTS, TEXBIB} + {.bib} +\KpathKey + {} + {2} + {bitmap fonts} + {GLYPHFONTS, TEXFONTS} + {} +\KpathKey + {bst} + {7} + {\BibTeX{} style files} + {BSTINPUTS} + {.bst} +\KpathKey + {cnf} + {8} + {Runtime configuration files} + {TEXMFCNF} + {.cnf} +\KpathKey + {dvips config} + {34} + {\textsf{dvips} configuration files, e.g., \file{config.ps} + and \file{psfonts.map}} + {TEXCONFIG} + {.map} +\KpathKey + {fmt} + {10} + {\TeX{} memory dump} + {TEXFORMATS, TEXMFINI} + {.fmt, .efmt, .efm} +\KpathKey + {gf} + {0} + {generic font bitmap} + {GFFONTS} + {.gf} +\KpathKey + {graphic/figure} + {25} + {Encapsulated PostScript figures} + {TEXPICTS, TEXINPUTS} + {.eps, .epsi} +\KpathKey + {ist} + {35} + {\textsf{makeindex} style files} + {TEXINDEXSTYLE, INDEXSTYLE} + {.ist} +\KpathKey + {ls-R} + {9} + {Filename databases} + {TEXMFDBS} + {} +\KpathKey + {map} + {11} + {Fontmaps} + {TEXFONTMAPS} + {.map} +\KpathKey + {mem} + {12} + {MetaPost memory dump} + {MPMEMS, TEXMFINI} + {.mem} +\KpathKey + {mf} + {13} + {Metafont source} + {MFINPUTS} + {.mf} +\KpathKey + {mfpool} + {14} + {Metafont program strings} + {MFPOOL, TEXMFINI} + {.pool} +\KpathKey + {mft} + {15} + {MFT style file} + {MFTINPUTS} + {.mft} +\KpathKey + {} + {41} + {miscellaneous fonts} + {MISCFONTS} + {} +\KpathKey + {mp} + {16} + {MetaPost source} + {MPINPUTS} + {.mp} +\KpathKey + {mppool} + {17} + {MetaPost program strings} + {MPPOOL, TEXMFINI} + {.pool} +\KpathKey + {MetaPost support} + {18} + {MetaPost support files, used by DMP} + {MPSUPPORT} + {} +\KpathKey + {ocp} + {19} + {\OMEGA{} compiled process files} + {OCPINPUTS} + {.ocp} +\KpathKey + {ofm} + {20} + {\OMEGA{} font metrics} + {OFMFONTS, TEXFONTS} + {.ofm, .tfm} +\KpathKey + {opl} + {21} + {\OMEGA{} property lists} + {OPLFONTS, TEXFONTS} + {.opl} +\KpathKey + {otp} + {22} + {\OMEGA{} translation process files} + {OTPINPUTS} + {.otp} +\KpathKey + {ovf} + {23} + {\OMEGA{} virtual fonts} + {OVFFONTS, TEXFONTS} + {.ovf} +\KpathKey + {ovp} + {24} + {\OMEGA{} virtual property lists} + {OVPFONTS, TEXFONTS} + {.ovp} +\KpathKey + {pk} + {1} + {packed bitmap fonts} + {\emph{program}FONTS \textrm{(\texttt{\emph{program}} being + \textsmaller{\cmdname{XDVI}}, + etc.)}, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS} + {.pk} +\KpathKey + {PostScript header} + {30} + {downloadable PostScript} + {TEXPSHEADERS, PSHEADERS} + {.pro, .enc} +\KpathKey + {tex} + {26} + {\TeX{} source} + {TEXINPUTS} + {.tex, .cls, .sty, .clo, .def} +\KpathKey + {TeX system documentation} + {27} + {Documentation files for the \TeX{} system} + {TEXDOCS} + {} +\KpathKey + {TeX system sources} + {29} + {Source files for the \TeX{} system} + {TEXSOURCES} + {} +\KpathKey + {texpool} + {28} + {\TeX{} program strings} + {TEXPOOL, TEXMFINI} + {.pool} +\KpathKey + {tfm} + {3} + {\TeX{} font metrics} + {TFMFONTS, TEXFONTS} + {.tfm} +\KpathKey + {Troff fonts} + {31} + {Troff fonts, used by DMP} + {TRFONTS} + {} +\KpathKey + {truetype fonts} + {36} + {TrueType outline fonts} + {TTFONTS} + {.ttf, .ttc} +\KpathKey + {type1 fonts} + {32} + {Type 1 PostScript outline fonts} + {T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS} + {.pfa, .pfb} +\KpathKey + {type42 fonts} + {37} + {Type 42 PostScript outline fonts} + {T42FONTS} + {} +\KpathKey + {vf} + {33} + {virtual fonts} + {VFFONTS, TEXFONTS} + {.vf} +\KpathKey + {web2c files} + {38} + {\Webc{} support files} + {WEB2C} + {} +\KpathKey + {other text files} + {39} + {text files used by `\textsf{foo}'} + {FOOINPUTS} + {} +\KpathKey + {other binary files} + {40} + {binary files used by `\textsf{foo}'} + {FOOINPUTS} + {} +\end{longtable} +\end{small} + + +\begin{multicols}{2} + +\begin{description} +\item[] The last two entries in Table~\ref{TABKpathsea} are special + cases, where the paths and environment variables depend on the name + of the program: the variable name is constructed by converting the + program name to upper case, and then appending \texttt{INPUTS}. + + The 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 ``\texttt{\var{string}}''; this 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 ``\texttt{\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 ``\texttt{\var{name}}''. + This can affect the search paths via the ``\texttt{.\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 ``\texttt{\var{name}}''. + Either a filename extension (\samp{.pk}, \samp{.vf}, etc.) or a + name can be used, just as with \samp{-{}-format} option. +\item[\texttt{-{}-debug=\var{num}}]\mbox{}\\ + sets the debugging options to ``\texttt{\var{num}}''. +\end{description} + + +\subsubsection{Examples of use} +\label{SExamplesofuse} + +Let us now have a look at \KPS{} in action. + +\begin{alltt} +>> \Ucom{kpsewhich article.cls} +/usr/local/texmf/tex/latex/base/article.cls +\end{alltt} +We are looking for the file \file{article.cls}. Since the \samp{.cls} +suffix is unambiguous we do not need to specify that we want to look for a +file of type ``tex'' (\TeX{} source file directories). We find it in +the subdirectory \file{tex/latex/base} below the \samp{TEXMF} root +directory. Similarly, all of the following are found without problems +thanks to their unambiguous suffix. +\begin{alltt} +>> \Ucom{kpsewhich array.sty} + /usr/local/texmf/tex/latex/tools/array.sty +>> \Ucom{kpsewhich latin1.def} + /usr/local/texmf/tex/latex/base/latin1.def +>> \Ucom{kpsewhich size10.clo} + /usr/local/texmf/tex/latex/base/size10.clo +>> \Ucom{kpsewhich small2e.tex} + /usr/local/texmf/tex/latex/base/small2e.tex +>> \Ucom{kpsewhich tugboat.bib} + /usr/local/texmf/bibtex/bib/beebe/tugboat.bib +\end{alltt} + +The latter is a \BibTeX{} bibliography database for \textsl{TUGBoat} articles. + +\begin{alltt} +>> \Ucom{kpsewhich cmr10.pk} +\end{alltt} +Font bitmap glyph files of type \file{.pk} are used by display +programs like \cmdname{dvips} and \cmdname{xdvi}. Nothing is returned in +this case since there are no pre-generated Computer Modern \samp{.pk} +files on our system (since we use the Type1 versions on the \CD{}). +\begin{alltt} +>> \Ucom{kpsewhich ecrm1000.pk} +\ifSingleColumn /usr/local/texmf/fonts/pk/ljfour/jknappen/ec/ecrm1000.600pk +\else +/usr/local/texmf/fonts/pk/ljfour/jknappen/ +... ec/ecrm1000.600pk +\fi\end{alltt} +For the extended Computer Modern files we had to generate \samp{.pk} +files, and since the default \MF{} mode on our installation is +\texttt{ljfour} with a base resolution of 600 dpi (dots per inch), +this instantiation is returned. +\begin{alltt} +>> \Ucom{kpsewhich -dpi=300 ecrm1000.pk} +\end{alltt} +In this case, when specifying that we are interested in a resolution +of 300dpi (\texttt{-dpi=300}) we see that no such font is available on +the system. In fact, a program like \cmdname{dvips} or \cmdname{xdvi} would +go off and actually build the \texttt{.pk} files at the required +resolution using the script \cmdname{mktexpk}. + +Next we turn our attention to \cmdname{dvips}'s header and configuration +files. We first look at one of the commonly used files, 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}. As the \samp{.ps} suffix is +ambiguous we have to specify explicitly which type we are considering +(``\texttt{dvips config}'') for the file \texttt{config.ps}. +\begin{alltt} +>> \Ucom{kpsewhich tex.pro} + /usr/local/texmf/dvips/base/tex.pro +>> \Ucom{kpsewhich --format="dvips config" config.ps} + /usr/local/texmf/config/config.ps +>> \Ucom{kpsewhich psfonts.map} + /usr/local/texmf/dvips/base/psfonts.map +\end{alltt} + +We now take a closer look 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} +>> \Ucom{kpsewhich --format="dvips config" config.utm} +/usr/local/texmf/dvips/psnfss/config.utm +\end{alltt} +The contents of that file is +\begin{alltt} + p +utm.map +\end{alltt} +which points to the file \file{utm.map}, which we want to +locate next. +\begin{alltt} +>> \Ucom{kpsewhich --format="dvips config" utm.map} + /usr/local/texmf/dvips/psnfss/utm.map +\end{alltt} +This map file defines the file names of the Type1 PostScript fonts in +the URW collection. Its contents look like (we only show part of the +lines): +\begin{alltt} + utmb8r NimbusRomNo9L-Medi ... <utmb8a.pfb + utmbi8r NimbusRomNo9L-MediItal... <utmbi8a.pfb + utmr8r NimbusRomNo9L-Regu ... <utmr8a.pfb + utmri8r NimbusRomNo9L-ReguItal... <utmri8a.pfb + utmbo8r NimbusRomNo9L-Medi ... <utmb8a.pfb + utmro8r NimbusRomNo9L-Regu ... <utmr8a.pfb +\end{alltt} +Let us, for instance, take the Times Regular instance +\file{utmr8a.pfb} and find its position in the \file{texmf} directory +tree by using a search for Type1 font files: +\begin{alltt} +>> \Ucom{kpsewhich utmr8a.pfb} +\ifSingleColumn /usr/local/texmf/fonts/type1/urw/utm/utmr8a.pfb +\else /usr/local/texmf/fonts/type1/ +... urw/utm/utmr8a.pfb +\fi\end{alltt} + +It should be evident from these few examples how you 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 +\cmdname{kpsewhich} will show you the first file encountered. + +\subsubsection{Debugging actions} +\label{Debugging} + +Sometimes it is necessary to 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 \cmdname{dvips} program, by setting a +combination of debug switches, one can follow in detail where files are being 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, one can select a debug option by using the +\envname{KPATHSEA\_DEBUG} environment variable, and setting it to (a +combination of) values as described in the above list. + +(Note for Windows users: it is not easy to redirect +all messages to a file in this system. For diagnostic purposes +you can temporarily \texttt{SET KPATHSEA\_DEBUG\_OUTPUT=err.log}). + +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 uses the font \file{cmr10}, so let us look +how \cmdname{dvips} prepares the PostScript file (we want to use the Type1 +version of the Computer Modern fonts, hence the option \texttt{-Pcms}). +\begin{alltt} +>> \Ucom{dvips -d4100 hello-world -Pcms -o} +\end{alltt} +In this case we have combined \cmdname{dvips}'s debug class 4 (font +paths) with \KPS's path element expansion (see \cmdname{dvips} Reference +Manual, \OnCD{texmf/doc/html/dvips/dvips_toc.html}). +%\ifSingleColumn +%We get something +%like the following (we have rearranged the output for easier display): +%\begin{alltt}\small +%\input{../examples/ex6.tex} +%\end{alltt} +%\else +The output (slightly rearranged) appears in +Figure~\ref{fig:dvipsdbga}. +\begin{figure*}[tp] +\centering +\input{../examples/ex6a.tex} +\caption{Finding configuration files}\label{fig:dvipsdbga} + +\bigskip + +\input{../examples/ex6b.tex} +\caption{Finding the prolog file}\label{fig:dvipsdbgb} + +\bigskip + +\input{../examples/ex6c.tex} +\caption{Finding the font file}\label{fig:dvipsdbgc} +\end{figure*} +\cmdname{dvips} starts by locating its working files. First, +\file{texmf.cnf} is found, which gives the definitions of the search +paths for the other files, then the file database \file{ls-R} (to +optimize file searching) and the file \file{aliases}, which makes it +possible to declare several names (e.g., a short \acro{DOS}-like ``8.3'' and +a more natural longer version) for the same file. Then \cmdname{dvips} +goes on to find the generic configuration file \file{config.ps} +before looking for the customization file \file{.dvipsrc} (which, in +this case is \emph{not found}). Finally, \cmdname{dvips} locates the +config file for the Computer Modern PostScript fonts \file{config.cms} +(this was initiated with the \texttt{-Pcms} option on the \cmdname{dvips} +command). This file contains the list of the ``map'' files which +define the relation between the \TeX{}, PostScript and file system +names of the fonts. +\begin{alltt} +>> \Ucom{more /usr/local/texmf/dvips/cms/config.cms} + p +ams.map + p +cms.map + p +cmbkm.map + p +amsbkm.map +\end{alltt} +\cmdname{dvips} thus goes on to find all these files, plus the generic +map file \file{psfonts.map}, which is always loaded (it contains +declarations for commonly used PostScript fonts; see the last part of +Section \ref{SExamplesofuse} for more details about PostScript map +file handling). + +At this point \cmdname{dvips} identifies itself to the user\ldots +\begin{alltt}\ifSingleColumn +This is dvips 5.78 Copyright 1998 Radical Eye Software (www.radicaleye.com) +\else\small{}This is dvips 5.78 Copyright 1998 Radical Eye... +\fi\end{alltt}% decided to accept slight overrun in tub case +\ifSingleColumn +\ldots and then goes on to look for the prolog file \file{texc.pro}, +\begin{alltt}\small +kdebug:start search(file=texc.pro, must\_exist=0, find\_all=0, + path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//: + ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//). +kdebug:search(texc.pro) => /usr/local/texmf/dvips/base/texc.pro +\end{alltt} +\else +then goes on to look for the prolog file \file{texc.pro} (see +Figure~\ref{fig:dvipsdbgb}). + +\fi +After having found the file in question, \cmdname{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}\small +TeX output 1998.02.26:1204' -> hello-world.ps +Defining font () cmr10 at 10.0pt +Font cmr10 <CMR10> is resident. +\end{alltt} +Now the search is on for the file \file{cmr10.tfm}, which is found, +then a few more prolog files (not shown) are referenced, and finally +the Type1 instance \file{cmr10.pfb} of the font is located and +included in the output file (see last line). +\begin{alltt}\small +kdebug:start search(file=cmr10.tfm, must\_exist=1, find\_all=0, + path=.:~/tex/fonts/tfm//:!!/usr/local/texmf/fonts/tfm//: + /var/tex/fonts/tfm//). +kdebug:search(cmr10.tfm) => /usr/local/texmf/fonts/tfm/public/cm/cmr10.tfm +kdebug:start search(file=texps.pro, must\_exist=0, find\_all=0, + ... +<texps.pro> +kdebug:start search(file=cmr10.pfb, must\_exist=0, find\_all=0, + path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//: + ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//). +kdebug:search(cmr10.pfb) => /usr/local/texmf/fonts/type1/public/cm/cmr10.pfb +<cmr10.pfb>[1] +\end{alltt} + +\subsection{Runtime options} + +Another of the nice features of \Webc{} is its possibility to +control a number of memory parameters (in particular, array sizes) via +the runtime file \file{texmf.cnf} read by \KPS{}. The listing of +\file{texmf.cnf} is shown in Appendix~\ref{app:texmf.cnf}, starting on +page~\pageref{app:texmf.cnf}; the settings of all parameters can be +found in Part 3 of that file. The more important control variables 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} (compare the generic value + and the ``huge'' one instantiated by \texttt{hugetex}, + etc.). +\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. You can see that both the + \cmdname{hugetex} and \cmdname{pdflatex} program invocations ask for + an extra 15,000 control sequences (the default value of + \texttt{hash\_extra} is zero). +\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. + +%-------------------------------------------------------- + + +\section{Acknowledgements}\label{sec:acknowl} +This edition of TeXLive is edited by Sebastian Rahtz, with the +major contributors being Fabrice Popineau, who has worked away +unceasingly at the Win32 part of the package (especially the setup!) +and contributed in many different ways with ideas, advice and code; +and Staszek Wawrykiewicz, who provided great checking feedback, and +co-ordinated the Polish contributions. Kaja Christiansen performed a +vital role in endless recompilations on assorted Unix platforms, and +Robin Laakso coordinated production for TUG. Vladimir Volovich +did great work on cleaning the source and making other improvements, +while Gerben Wierda did all the work for MacOSX. + +We are very grateful for past and present help from +\begin{itemize} +\item The German-speaking \TeX{} Users (DANTE e.V.), who provided a machine + on which the master of the CD-ROM is developed and maintained; and Rainer +Sch\"opf and Reinhard Zierke who look after it; +\item The Perforce company, for providing a free copy of their +excellent change management system, which we have used to + manage the CD-ROM +contents; +\item Karl Berry, who provided the original \Webc{} distribution, and + has continued to give invaluable advice, encouragement, and help; +\item Mimi Burbank, who arranged access + at the Florida State University School of Computational Science + and Information Technology + to a slew of different + computers to compile \TeX{} on, and acted as an essential guinea-pig + whenever asked; +\item Kaja Christiansen, who provided essential feedback, compilation, and + documentation preparation; +\item Thomas Esser, without whose marvellous \teTeX{} package this + \CD{} would certainly not exist, and whose continual help makes it a + better product; +\item Michel Goossens, who co-authored the documentation; +\item Eitan Gurari, whose \TeX4ht was used to create the \HTML{} + version of this documentation, and who worked tirelessly to improve + it at short notice; +\item Art Ogawa and Pat Monohon, who coordinated releases for TUG; +\item Petr Olsak, who coordinated and checked all the Czech/Slovak + material very carefully; +\item Olaf Weber, for his patient assembly and maintenance of Web2c; +\item Graham Williams, on whose work the catalogue of packages depends. +\end{itemize} + +Gerhard Wilhelms, Volker Schaa, Fabrice Popineau, Janka +Chleb\'\i{}kov\'a, Staszek Wawrykiewicz, Erik Frambach, and Ulrik +Vieth kindly translated documentation at various times into their +respective languages, checked other documentation, and provided very +welcome feedback. + + +\section{History} + +This \CD{} distribution is a joint effort by many \TeX{} Users +Groups, including those from Germany, the Netherlands, the UK, France, +the Czech Republic/Slovakia, India, Poland and Russia, as well as +the international TUG. +Discussion began in late 1993 when the Dutch \TeX{} Users Group was +starting work on its 4All\TeX{} \CD{} for \acro{MS-DOS} users, and it was +hoped at that time to issue a single, rational, \CD{} for all +systems. This was far too ambitious a target, but it did spawn not +only the very successful 4All\TeX{} \CD{}, but also the \acro{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 \textsl{TUGboat}, and it was clear from +an early stage that one desirable product would be a model structure +on \CD{}. The \CD{} 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{} \CD{} showed 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{} \CD{} 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 \CD{} on the standard \Webc, with the +addition of \teTeX's \texttt{texconfig} script. The 3rd edition of the +\CD{} was based on a major revision of \Webc, 7.2, by Olaf Weber; at the +same time, a new revision of \teTeX was being made, +and \TeXLive{} shares almost all of its features. The 4th edition +followed the same pattern, using a new version of te\TeX, and a new +release of \Webc{} (7.3). The system now included a complete Windows setup. + +For the 5th edition (March 2000) many parts of the \CD{} were revised +and checked, updating hundreds of packages. Package details were +stored in XML files. But the major change for \TeX\ Live 5 was that +all non-free software was removed. Everything on this \CD{} should be +compatible with the Debian Free Software Guidelines +(\url{http://www.debian.org/intro/free}); we have done our best to +check the license conditions of all packages, but we would very much +appreciate hearing of any mistakes. + +The 6th edition (July 2001) had a lot material updated. The major +change was a new install concept: the user could select a more exact set +of needed collections. Language-related collections were completely +reorganized, so selecting any of them installs not only macros, fonts, +etc., but also prepares an appropriate \texttt{language.dat}. + +The 7th edition of 2002 had as a major addition a setup +for MacOSX, and the usual myriad of updates to all sorts +of packages and programs. An important goal was integration +of the source back with teTeX, to correct the drift apart +in versions 5 and 6. + +\section{Future versions} + +\emph{This \CD{} 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:\hfill\null +\begin{quote} +Sebastian Rahtz\\ +{}7 Stratfield Road\\ +Oxford OX2 7BG\\ +United Kingdom\\ +\EmailURL{rahtz@tug.org} +\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}. + +\end{multicols} + +\Section{The texmf.cnf file} +\label{app:texmf.cnf} +\begin{small} +\listinginput{1}{../examples/texmf.cnf} +\end{small} + +\end{document} + + + +Notes on Nicolle Zellner's problems: +------------------------------------ +- autoexec.bat gave error, ``too many parameters''. +fix: in setvars.bat file, put "" around %PATH% to take care of spaces. + +- ``out of environment space'' when rebooting meant that autoexec.bat was +not executing properly-- path and texmfhome variable were not being set. +fix: put in config.sys file the line: shell=c:\command.com /e:1024 /p +(and reboot probably) + +[Note: alternative advice written by Pat: + The environment space is an area of memory in which the OS stores + variables such as path. To increase the memory size do the following: + + Open a MS-DOS window. Click on the Properties icon (looks like a hand + holding a sheet of paper). Click on the Memory tab in the Properties + window. Change the value under Initial Environment: to 4096. Apply the + properties. Click OK on the warning about needing to restart your computer. + The new environment memory will be in effect after the reboot.] + +- windvi did not retain settings. +fix: in setvars.bat file, add command: set Home=c:\Home and also create +the directory c:\Home. +copy windvi.cnf to c:\Home\ +reboot + +-ispell doesn't work (can't write to c:\tmp, can't create dictionary) +In addition to the the c:\Home addition above, create the folder: +d:\tmp\ (d: is where the files are that she is using.) +Now ispell should work from the command line. +Still can't get it to work from within \cmdname{WinShell}. (change cmd line to %c.tex, +it was reading the project main file) + + + +Notes on installing WinEdt: +--------------------------- +If you choose to install WinEdt, you will be asked for a folder name: any +folder name will do, as this is for temporary storage. An acceptable +choice is \verb+C:\Winedt+. Click \textbf{unzip}, then \textbf{OK}, +and finally \textbf{Close}. +--- + +later, to complete WinEdt installation: + +Run "winedt5.exe" and complete the setup procedure. + +Get from ftp://ftp.dante.de/pub/fptex/supplementary/ +30/08/2000 20:17 70 844 winedt5-cnf.zip +10/09/2000 10:43 839 086 winedt5-patch4.zip + +then unpack (use unzip or winzip with subdir creation enabled, NOT pkunzkip) + "winedt5-patch4.zip" inside the "c:\program files\winedt" directory +then at last unpack "winedt5-cnf.zip". + +When this is done, go inside the 'Options->Configurations' menu, +choose the "fpTeX Direct" option. + +If windvi previewer doesn't work, go to options->menu setup-> accessories +and change the Menu Setup so the call for DVI Preview is analogous to +the call for Dvips-- i.e., don't use "DVIVIEW" in the command line, +but rather fptex-bin and dviwin.exe. + + |