Debian Codegraph @

texmf-dist/doc/texlive/texlive-en/archive/live-tl7.tex

raw
1 %
2 % change history (started May 13th 2002)
3 % 2002/05/13: added tex-langafrican to list of collections
4 % 2002/05/14: corrected example files, other small errors noted by Volker
5 % 2002/05/18: win32 updates, by Fabrice
6 % 2002/05/25: remove mention of sizes, and bsr-interpolated; add Gutenberg
7 \documentclass{article}
8 \advance\textwidth by 1in
9 \advance\oddsidemargin by -1in
10 \advance\evensidemargin by -1in
11 \newsavebox{\warnbox}
12 \def\Q#1{\par\vskip6pt\leftline{#1}\par}
13 \setcounter{tocdepth}{2}
14 \pretolerance=1000
15 \tolerance=1500
16 \hbadness=3000
17 \vbadness=3000
18 \hyphenpenalty=400
19 \renewcommand{\topfraction}{0.85}
20 \renewcommand{\floatpagefraction}{0.86}
21 \renewcommand{\textfraction}{0.1}
22 \setcounter{topnumber}{5}
23 \setcounter{totalnumber}{5}
24 \def\eTeX{$\varepsilon$-\TeX}
25 \def\Dash{---}
26 \def\hyph{-}
27 \def\OMEGA{$\Omega$}
28 \def\bs{{\protect\normalfont\ttfamily\char'134}}
29 \DeclareRobustCommand{\cs}[1]{{\normalfont\ttfamily\char`\\#1}}
30 \def\La{La}
31 \let\textsl\textit
32 \let\sl\it
33 \let\slfamily\itfamily
34 \def\ttdefault{cmtt}
35 \usepackage{tex-live}
36 \begin{document}
37 %\makeatletter\@ifundefined{HRestore}{}{\HRestore\noalign}\makeatother
38 \author{Sebastian Rahtz\\
39 \texttt{[email protected]}
40 %Michel Goossens\\
41 %\texttt{[email protected]}
42 }
43 \title{The \protect\TeX\ Live Guide, 7th edition}
44 \date{May 2002}
45 \maketitle
46 \begin{multicols}{2}
47 \tableofcontents
48 \listoftables
49 \end{multicols}
50 \section{Introduction}\label{sec:intro}
51 This documentation describes the
52 main features of the \TeXLive{} 7 \CD{}\Dash a \TeX{}/\LaTeX{}
53 distribution for Unix, Linux, MacOSX, and Windows32 systems that includes
54 \TeX{}, \LaTeXe{}, \MF, \MP, \cmdname{Makeindex}, and \BibTeX{}; and
55 a wide-ranging set of macros, fonts and documentation conforming to
56 the \emph{\TeX{} Directory Standard} (\TDS{})\Dash which can be used
57 with nearly every \TeX{} setup.
58
59 This \TeX{} package uses the \Webc{} version 7.3.7
60 implementation of the programs, which tries to make \TeX{}ing as
61 easy as possible, and takes full advantage of the efficient and
62 highly customizable \KPS{} library from Karl Berry and Olaf Weber.
63 It can be run either directly from the \CD{} or installed on a hard
64 disk.
65
66 Most of the runnable systems on the \CD{} include a large set of
67 drivers and support programs for \TeX, including \cmdname{dvips}
68 (PostScript driver), \cmdname{dvipdfm} (dvi to PDF),
69 \cmdname{xdvi} (X Windows previewer),
70 \cmdname{dvilj} (HP LaserJet driver), \cmdname{lacheck} (\LaTeX{}
71 syntax checker), \cmdname{tex4ht} (\TeX{} to HTML converter),
72 \cmdname{dviconcat} and \cmdname{dviselect}, \cmdname{dv2dt} and
73 \cmdname{dt2dv} (\texttt{dvi} to ASCII and vice versa), and Angus
74 Duggan's PostScript utilities.
75
76 \subsection{Extensions to \TeX}
77
78 The \TeXLive{} runnable systems contain three extended versions of
79 standard \TeX:
80 \begin{enumerate}
81 \item \eTeX, which adds a small but powerful set of new primitives,
82 and the \TeXXeT{} extensions for left to right typesetting; in
83 default mode, \eTeX{} is 100\% compatible with ordinary \TeX. See
84 \OnCD{texmf/doc/etex/base/etex_man.pdf} on the \CD{} for details.
85 \item pdf\TeX, which can optionally write Acrobat PDF format instead
86 of \dvi{}. You will find the user manual in
87 \OnCD{texmf/doc/pdftex/pdftex-l.pdf}. The
88 file \OnCD{texmf/doc/pdftex/samplepdf/samplepdf.tex} shows how it is
89 used. The \LaTeX{} \pkgname{hyperref} package has an option
90 `\optname{pdftex}', which turns on all the program features.
91 \item \OMEGA{} (Omega), which works internally with 16-bit characters,
92 using Unicode; this allows it to directly work with almost all the
93 world's scripts simultaneously. It also supports dynamically loaded
94 `\OMEGA{} Translation Processes' (\acro{OTP}s), which allow the user
95 to define complex transformations to be performed on arbitrary
96 streams of input. See \OnCD{texmf/doc/omega/base/doc-1.8.tex} for some
97 (not necessarily up to date) documentation.
98 \end{enumerate}
99 \eTeX{} (version 2.1) is stable, although subsequent releases will add
100 new functionality. pdf\TeX{} (version 1.00b) is also stable,
101 but is still being improved.
102 \OMEGA{} (version 1.23) is under development; the version
103 on this \CD{} is that current as of May 2002.
104
105
106 \section[Structure and contents of the CD-ROM]{Structure
107 and contents of the \protect\CD{}}
108 The important \CD{} top-level directories are listed below.
109 \begin{description}
110 \item[bin] The \TeX{} family programs, arranged in separate platform
111 directories.
112 \item[Books] Examples related to some books about \TeX.
113 \item[FAQ] Frequently Asked Questions, in English, French, and German.
114 \item[MacOSX] Support programs for MacOSX users
115 \item[info] Documentation in \acro{GNU} `info' format for the \TeX{}
116 system.
117 \item[man] Documentation in the form of Unix man pages for the \TeX{}
118 system.
119 \item[setupw32] directory contains material for installation and use
120 under Windows (see section \ref{sec:wintex} on p.~\pageref{sec:wintex}).
121 \item[source] The source of all programs, including the main \Webc{}
122 \TeX{} and \MF{} distributions. These are stored in a bzip2-compressed
123 tar archive.
124 \item[support] Various bits of \TeX-related software which are
125 \emph{not} installed by default, support programs, and a complete
126 distribution of \cmdname{Ghostscript} version 7.05.
127 You can find here some other programs (editors, \TeX\ shells), which
128 are usually absent from Windows installations, dedicated for beginners.
129 They can be installed with the \texttt{TeXSetup.exe} Windows installation
130 program.
131 \item[texmf] The main support tree of macros, fonts and documentation;
132 \item[usergrps] Material about \TeX\ User Groups.
133 \end{description}
134
135 There are also two installation scripts for Unix systems,
136 \texttt{install-cd.sh} and \texttt{install-pkg.sh}; we discuss
137 them on in section \ref{sec:install} on p.~\pageref{sec:install}.
138
139 \subsection[Packages and collections]{Packages and collections}
140 \label{packages}
141 The \TeXLive{} \texttt{texmf} tree consists of various `collections',
142 each of which refers to a set of `packages', of which there are over 700
143 on the \CD{}. Normal installation allows the
144 user to copy all of a collection to a local hard disk from the \CD{}, but
145 it is also possible to install just one package of a collection.
146
147 The collections add functionality to a \TeX\ system. One of them, named
148 `tex-basic', is necessary for almost all \TeX\ tasks,
149 and two others, called `tex-latex' and `tex-pdftex' are highly
150 recommended for most users. All others are optional.
151 The collections (defined by XML files in \texttt{texmf/tpm/collections})
152 and their short descriptions are listed below.
153
154 \begin{description}
155 \item[tex-basic]
156 These files are regarded as basic for any \TeX\ system, covering
157 plain \TeX\ macros, Computer Modern fonts, and configuration for common
158 drivers.
159 \item[tex-bibtexextra]
160 Additional, extensive libraries of BibTeX styles and bibliographies.
161 \item[tex-chemistry]
162 Essential chemistry
163 \item[tex-context]
164 Hans Hagen's powerful macro package, ConText
165 \item[tex-documentation]
166 Assorted useful documentation and guides
167 \item[tex-etex]
168 Support files for an extended \TeX\
169 \item[tex-extrabin]
170 Various useful, but non-essential, support programs. Includes
171 programs and macros for texinfo system; programs for dvi file
172 manipulation, etc.
173 \item[tex-fontbin]
174 Programs for conversion between font formats, testing fonts
175 (virtual fonts stuff, .gf and .pk manipulation,
176 mft, fontinst, etc.)
177 \item[tex-fontsextra]
178 All sorts of extra fonts
179 \item[tex-formatsextra]
180 A collection of \TeX\ `formats', ie large-scale
181 macro packages designed to be dumped into .fmt file
182 \item[tex-games]
183 Setups for typesetting various board games, including chess
184 \item[tex-genericextra]
185 This is a mixed bag of macro packages and fonts which do not seem
186 to belong elsewhere
187 \item[tex-htmlxml]
188 Packages to convert \LaTeX\ to XML/HTML, and typeset XML/SGML
189 \item[tex-langafrican]
190 Support for some African scripts
191 \item[tex-langarmenian]
192 Essential armenian
193 \item[tex-langcjk]
194 Essential CJK (Chinese, Japanese, Korean) macros and fonts
195 \item[tex-langcroatian]
196 Essential croatian
197 \item[tex-langcyrillic]
198 Fonts and macro packages to typeset Cyrillic texts.
199 \item[tex-langczechslovak]
200 Pick this if you want Czech/Slovak fonts and other packages
201 \item[tex-langdanish]
202 Essential Danish
203 \item[tex-langdutch]
204 Essential Dutch
205 \item[tex-langfinnish]
206 Essential Finnish
207 \item[tex-langfrench]
208 Essential French
209 \item[tex-langgerman]
210 Essential German
211 \item[tex-langgreek]
212 Essential Greek
213 \item[tex-langhungarian]
214 Essential Hungarian
215 \item[tex-langindic]
216 Essential Indic
217 \item[tex-langitalian]
218 Essential Italian
219 \item[tex-langlatin]
220 Essential Latin
221 \item[tex-langmanju]
222 Essential Manju
223 \item[tex-langmongolian]
224 Essential mongolian
225 \item[tex-langnorwegian]
226 Essential Norwegian
227 \item[tex-langother]
228 Other languages
229 \item[tex-langpolish]
230 Pick this if you want Polish fonts and other packages
231 \item[tex-langportuguese]
232 Essential Portuguese
233 \item[tex-langspanish]
234 Essential Spanish
235 \item[tex-langswedish]
236 Essential Swedish
237 \item[tex-langtibetan]
238 Fonts and support for typesetting Tibetan
239 \item[tex-langukenglish]
240 Essential UK English
241 \item[tex-langvietnamese]
242 Essential Vietnamese
243 \item[tex-latex]
244 These packages are either mandated by the core \LaTeX\ team,
245 or very commonly recommended
246 \item[tex-latexextra]
247 A large collection of add-on packages for \LaTeX\
248 \item[tex-mathextra]
249 Extra math
250 \item[tex-metapost]
251 MetaPost (and MetaFont) drawing packages
252 \item[tex-music]
253 Music typesetting packages
254 \item[tex-omega]
255 Omega, a 16-bit extended \TeX\ by John Plaice and Yannis Haralambous
256 \item[tex-pdftex]
257 Support files for Han The Thanh's variant of \TeX\ which can
258 generate PDF output
259 \item[tex-pictures]
260 Essential graphics
261 \item[tex-plainextra]
262 Plain \TeX\ extra macros
263 \item[tex-psfonts]
264 Essential psfonts
265 \item[tex-psutils]
266 Utilities to manipulate PostScript files
267 \item[tex-publishers]
268 Essential publishers
269 \item[tex-t1utils]
270 Utilities to manipulate Type1 fonts
271 \item[tex-texbooks]
272 Examples and other material from various books about TeX/LaTeX.
273 \item[tex-theses]
274 Macro packages from various Universities for their thesis styles
275 \item[tex-ttfutils]
276 Utilities to manipulate TrueType fonts
277 \item[win32-support]
278 You can choose individual tools from this collection.
279 There are many \TeX\ oriented editors, graphics files
280 toolsets, etc.
281 \end{description}
282
283 The directory \texttt{texmf/tpm/packages} contains lists
284 of all files in each package (used by the installation programs).
285
286 \section{Installation and use under Unix}
287 \label{sec:install}
288 You can use the \TeXLive{} \CD{} in three ways:
289 \begin{enumerate}
290 \item You can mount the \CD{} on your file system, run
291 the \texttt{install-cd.sh} script, and select the option \verb|<R>|
292 (`do not install files, set up to run off CD-ROM'),
293 and run everything off the \CD; this takes very
294 little disk space, and gives you immediate access to everything on
295 the \CD; although the performance will not be optimal, it is
296 perfectly acceptable on, for instance, PCs running Linux. You could
297 also copy the entire CD contents to your hard disk and work in this way.
298 \item You can install all or part of the system to your local hard
299 disk; this is the best method for many people, if they have enough
300 disk space to spare (a minimum of about 100 megabytes, or 300
301 megabytes for a recommended good-sized system).
302 \item You can install selected packages to work either with your
303 existing \TeX{} system or a \TeXLive{} system you installed earlier.
304 \end{enumerate}
305 Each of these methods is described in more detail in the following
306 sections.
307
308 \ifSingleColumn
309 \begin{figure*}
310 \begin{center}
311 \leavevmode
312 \fi
313 \begin{warningbox}
314 \textbf{Warning: } This \CD{} is in ISO 9660 (High Sierra) format,
315 with Rock Ridge and Joliet extensions. In order to take full advantage
316 of the \CD{} on a Unix system, your system needs to be able to use
317 the Rock Ridge extensions. Please consult the documentation for your
318 \cmdname{mount} command to see if it is possible. If you have several
319 different machines on a local network, see if you can mount the
320 \CD{} on one which \emph{does} support Rock Ridge, and use this with
321 the others.
322
323 \leavevmode\quad
324 Linux, FreeBSD, Sun, SGI and DEC Alpha systems should be able to use
325 the \CD{} with no problems. We would appreciate receiving detailed advice
326 from other system users who also succeed, for future versions of this
327 documentation.
328
329 \leavevmode\quad
330 The discussion below about installation assumes you have been able to mount
331 the \CD{} with full Rock Ridge compatibility.
332 \end{warningbox}
333 \ifSingleColumn
334 \end{center}
335 \end{figure*}
336 \fi
337
338 %\begin{addbymb}
339 \subsection[Pre-installation procedure for MacOSX users]
340 {Pre-installation procedure for MacOSX users}
341 If you do not run MacOSX, you should skip this section.
342
343 The \texttt{install-cd.sh} script is a \emph{sh} script (begins with
344 ``\verb=#!/bin/sh=''), but
345 on MacOSX \cmdname{sh} is unable to run it because
346 \cmdname{sh} is
347 emulated. However, \cmdname{bash} will run it. Unfortunately (again)
348 \cmdname{bash} is not
349 installed by default on MacOSX\footnote{there are some suggestions this will
350 change in the future and even
351 that \cmdname{bash} will be used to emulate \cmdname{sh},
352 in which case it might be true
353 that in future versions of MacOSX, the script will just work.}.
354 \begin{enumerate}
355 \item\label{test-bash} (optional) See if \path|bash| is already installed.
356 Launch \path|Terminal|
357 (\path|/Applications/utilities/Terminal|) and type in a window
358 \begin{alltt}
359 >> \Ucom{rehash; which bash}
360 \end{alltt}
361 the answer will be:
362 \begin{itemize}
363 \item the bash location (e.g. \path|/bin/bash| or \path|/usr/local/bin/bash|) if installed;
364 \item \texttt{bash: command not found} if not installed.
365 \end{itemize}
366
367 If bash is already installed, skip to \ref{std-install}
368
369 \item bash installation:
370 \begin{description}
371 \item[Mac friendly procedure]
372 Look in the \path|MacOSX| directory of the \CD{}
373 for an image disk named \path|bash.dmg|. mount that
374 file by double-clicking it. The disk image (volume) will be mounted.
375 Then start the \path|i-Installer| application on that volume. You will be asked
376 to authenticate, if you have never seen that before, you might not have
377 enough privileges to install. Just enter your own user name and
378 password. Hit install. \path|bash| will be installed on your system.
379 \item[Terminal procedure]
380 \begin{enumerate}
381 \item Log in as an admin user, at least a user with Admin privileges or
382 sudo user or as the System Administrator.
383 \item Open the \path|MacOSX| directory on the \CD{} and copy
384 \path|bash.tar.gz|
385 to your home directory (\texttt{\~{}/})
386 \item Then launch \path|Terminal| and type or copy/paste the
387 line below in a Terminal window):
388 \begin{alltt}
389 >> \Ucom{(cd /usr/local/; sudo tar xvzf ~/bash.tar.gz)}
390 \end{alltt}
391 type a carriage-return: you will be asked for your password, and
392 \path|bash| will be
393 installed.
394 \item Quit \path|Terminal|.
395 \end{enumerate}
396 \end{description}
397 \item Now after using either install method, goto \ref{test-bash}:
398 you must obtain \path|/usr/local/bin/bash|\ldots{} (if not, try to log out and in).
399 \item\label{std-install} The installation procedure is the
400 same on MacOSX than on other UNIX platforms (as MacOSX is UNIX,
401 that's quite normal!). Nevertheless, you should read what follows:
402 \begin{itemize}
403 \item Note that in all commands of the following sections,
404 \cmdname{sh} must be replaced by \texttt{sudo bash}:
405 \begin{alltt}
406 >> \Ucom{sh install-cd.sh}
407 \end{alltt}
408 becomes
409 \begin{alltt}
410 >> \Ucom{sudo bash install-cd.sh}
411 \end{alltt}
412 etc.
413 \item On MacOSX, cd are auto-mounted: you \emph{don't} need to use
414 \texttt{mount}. The \CD{} will be mounted in the \path|/Volumes/|
415 directory: in order to make it the current directory, you just have to
416 type in \path|Terminal|:
417 \begin{alltt}
418 >> \Ucom{cd /Volumes/TeXLive-7...}
419 \end{alltt}
420 (complete this line with the real name of the \CD{}: using
421 ``auto completion'' by pressing the \texttt{<tab>}
422 key will do it).
423 \end{itemize}
424 \end{enumerate}
425 %\end{addbymb}
426
427 \subsection[Running \protect\TeXLive{} from the CD-ROM]{Running \protect\TeXLive{} from the \protect\CD}
428 The organisation of \Webc{} means that you can run programs simply by
429 adding the appropriate directory under \path|bin| on the \CD{} to
430 your \texttt{PATH}, and the support files will all be found with no further
431 ado. The following shows the list of available systems and the
432 corresponding directories. \textbf{Only x86 Linux, Mac OSX, and
433 Windows are available on the default CD. You need to ask
434 for the Unix CD if you need the other systems.}
435
436 \begin{flushleft}
437 \begin{tabular}{@{}l>{\ttfamily}ll}
438 Compaq Alpha Linux & alpha-linux & CD2\\
439 Compaq Alphaev5 OSF 4.0d & alphaev5-osf4.0d & CD2\\
440 HP9000 HPUX 10.20 & hppa2.0-hpux10.20 & CD2\\
441 IBM RS 6000 AIX 4.2.* & rs6000-aix4.2.1.0 & CD2\\
442 Intel x86 Solaris 2.8 & i386-solaris2.8 & CD2\\
443 Intel x86 with GNU/Linux & i386-linux & CD1\\
444 Mac OSX & powerpc-darwin5.3 & CD1\\
445 Sun Sparc Solaris 2.7 & sparc-solaris2.7 & CD2\\
446 Windows 9X/ME/NT/2K/XP & win32 & CD1\\
447 \end{tabular}
448 \end{flushleft}
449
450 You may worry that when you subsequently make fonts or change
451 configuration, things will go wrong because you cannot change files on
452 the \CD{}. However, you can maintain a parallel, writeable, \TeX{}
453 tree on your hard disk; this is searched before the main tree on the
454 \CD{}. The default location is \path|texmf-var| on the CD
455 (which does not exist!), so you \emph{must} override this by setting
456 the \texttt{VARTEXMF} environment variable.
457
458
459 Thus \emph{sh} or \emph{bash} users on an Intel PC
460 running Linux can mount the \TeXLive{} \CD{} on
461 \file{/mnt/cdrom} by issuing the command:
462
463 \begin{alltt}
464 >> \Ucom{mount -t iso9660 /dev/cdrom /mnt/cdrom}
465 \end{alltt}
466 Then they should change the current directory to \path|/mnt/cdrom|, run
467 \begin{alltt}
468 >> \Ucom{sh install-cd.sh}
469 \end{alltt}
470 and select the option \verb|<R>| (\emph{do not install files, set up to run
471 off CD-ROM}). After that, they should include the directory containing
472 the binaries for the given architecture into the search path
473 by updating the \texttt{PATH} variable.
474 \begin{verbatim}
475 PATH=/mnt/cdrom/bin/i386-linux:$PATH
476 export PATH
477 VARTEXMF=/usr/TeX/texmf-var
478 export VARTEXMF
479 \end{verbatim}
480 %\begin{addbymb}
481 \begin{description}
482 \item[MacOSX users] On MacOSX, the default shell is \texttt{tcsh}:
483 \begin{verbatim}
484 setenv PATH /Volumes/<cd-name>/bin/powerpc-darwin5.3:${PATH}
485 setenv VARTEXMF /usr/TeX/texmf-var
486 \end{verbatim}
487 \end{description}
488 %\end{addbymb}
489 For convenience, these statements can also be entered into the
490 \texttt{.profile} script.
491 %\begin{addbymb}
492 (for \texttt{tcsh} on MacOSX,
493 \verb=~/Library/init/tcsh/rc.mine=).
494 %\end{addbymb}
495
496 If in doubt, ask your local system support guru to help you work out
497 how to mount your \CD{} or which directory to use for your system.
498
499 Appropriate support files will be installed on your hard disk the
500 first time you need them. You can edit and change local configuration
501 files which are stored to the directory designated
502 by \texttt{\$VARTEXMF}. Any format file that is needed
503 will be generated and stored here.
504
505 %------------------------------------------------
506 \subsection{Installing \protect\TeXLive{} to a hard disk}
507 All of the necessary steps to install all or part of the distribution
508 on your hard disk are achieved by mounting the \CD{}, changing to the
509 top-level directory, and typing:
510 \begin{alltt}
511 >> \Ucom{sh install-cd.sh}
512 \end{alltt}
513 (On some Unix systems, you may need to use \cmdname{sh5} or
514 \cmdname{bash}.) This script works by accessing lists of collections
515 and packages from the \CD{}, and trying to guess what sort of computer
516 system you are on. It should start by displaying the following:
517 \verbatiminput{../examples/ex1.tex}
518 It will then show the main control screen
519 (Figure~\ref{ins1}), which lets you change five
520 things:
521 \begin{enumerate}
522 \item the type of system you are on, or want to install for;
523 \item the \emph{installation scheme} you want to use (eg full,
524 recommended, basic etc)
525 \item the collections you want to change from
526 the installation scheme (they are organised into two sets:
527 \emph{standard collections} and \emph{language collections});
528 \item the location on your hard disk to put the files;
529 \item some runtime behaviour features.
530 \end{enumerate}
531
532 \begin{figure*}
533 \begin{center}
534 \ifnum\Status=2
535 \boxedverbatiminput{../examples/ex2.tex}
536 \else
537 \begin{minipage}{0.8\textwidth}
538 \boxedverbatiminput{../examples/ex2.tex}
539 \end{minipage}
540 \fi
541 \caption{Main control screen}\label{ins1}
542 \end{center}
543 \end{figure*}
544
545 You choose options by typing a letter or number and pressing `return'.
546 In the example, a Linux GNU/Linux system has been detected, the
547 default set of collections will be installed, and
548 the default installation directory is \path|/usr/TeX|; note
549 that the disk space required for the current installation
550 configuration is also displayed. If you make a suggested setup, you
551 need about 60 megabytes of disk free; however, the basic setup will
552 only take about 30 megabytes, and you can enhance it with selected
553 packages as you need them.
554
555 %\begin{addbymb}
556 \begin{description}
557 \item[MacOSX users] Most frontends (\emph{TeXShop},
558 \emph{ITeXMac}\ldots) use the \teTeX{} default location
559 which is \path|/usr/local/teTeX|, so, Mac users could find interest
560 in installing \TeXLive{} in \path|/usr/local/teTeX|
561 rather than in \path|/usr/TeX|.
562 \end{description}
563 %\end{addbymb}
564
565 Under the directory you choose for installation, the installation
566 script will put the binaries in a subdirectory of \path|bin|, and the
567 support tree in \path|texmf|. An additional tree \path|texmf-var|
568 will contain copies of configuration files (except the main
569 \path|texmf.cnf|), which are to be modified by \path|texconfig| program.
570 This tree will also store generated format files for \TeX, \MF, etc.
571
572 \begin{figure*}
573 \begin{center}
574 \ifnum\Status=2
575 \boxedverbatiminput{../examples/ex3.tex}
576 \else
577 \begin{minipage}{.80\linewidth}
578 \footnotesize
579 \boxedverbatiminput{../examples/ex3.tex}
580 \end{minipage}
581 \fi
582 \caption{Selecting standard collections}\label{ins2}
583 \end{center}
584 \end{figure*}
585
586 \begin{figure*}
587 \begin{center}
588 \ifnum\Status=2
589 \boxedverbatiminput{../examples/ex4.tex}
590 \else
591 \begin{minipage}{.80\linewidth}
592 \footnotesize
593 \boxedverbatiminput{../examples/ex4.tex}
594 \end{minipage}
595 \fi
596 \caption{Selecting language collections}\label{ins3}
597 \end{center}
598 \end{figure*}
599
600 When you choose |<C>| for \emph{standard collections}, you will see
601 the display of available collections (Figure \ref{ins2}). Each
602 collection --- TeX macro files, Metafont font families, and so on ---
603 consists of several packages. You can toggle their inclusion on or
604 off by pressing the key. Note that the selection letter keys are case
605 sensitive.
606
607 When you choose |<L>| for \emph{language collections}, you will see
608 the display of available language support collections (Figure
609 \ref{ins3}). Each collection consists of several packages, which
610 provide features like hyphenation files and fonts.
611
612 The |<O>| for \emph{options} item lets you decide whether to make new fonts
613 be created in another location (if you want the main package mounted
614 read-only for most users), and whether to make symbolic links for the
615 binaries, \cmdname{man} and \acro{GNU} \cmdname{info} pages in the `standard'
616 locations; you'll need `root' permissions for tasks to do this, of course.
617
618 When you are finished, return to the main screen, and ask the
619 installation to start. It will take each of the collections and
620 systems that you requested, consult the list of files on the \CD{},
621 and build a master list of files to transfer. These will then be
622 copied to your hard disk. If you installed a system,
623 an initialization sequence is now run
624 (creating format files, etc.). When this has finished, all you need do
625 is add the correct subdirectory of \texttt{bin} in the \TeX{}
626 installation to your path, and start using \TeX. If you want, you can
627 move the binaries up one level, e.g.\ from
628 \path|/usr/local/bin/alpha-osf3.2|
629 to \path|/usr/local/bin|; if you do this, however, you must
630 edit \path|texmf/web2c/texmf.cnf| (see Appendix~\ref{app:texmf.cnf})
631 and change the line near the start which reads
632 \begin{verbatim}
633 TEXMFMAIN = $SELFAUTOPARENT
634 \end{verbatim}
635 to
636 \begin{verbatim}
637 TEXMFMAIN = $SELFAUTODIR
638 \end{verbatim}
639
640 If you move the whole installation to another directory tree entirely, you
641 need to edit \envname{TEXMFMAIN} to specify the support tree explicitly, and
642 set \envname{TEXMFCNF} in your environment to \path|$TEXMFMAIN/texmf/web2c|.
643
644 %------------------------------------------------
645
646 \subsection{Installing individual packages from \protect\TeXLive{} to a hard
647 disk} You may want to use the \TeXLive{} \CD{} to either update an
648 existing setup, or add features to an earlier installation from the
649 \CD{}. The main installation program is intended for the first time
650 only, and subsequently you should use the \texttt{install-pkg.sh}
651 script on the \CD{}. Run this by mounting the \CD{}, changing to
652 the mounted directory, and typing
653
654 \begin{alltt}
655 >> \Ucom{sh install-pkg.sh \emph{options}}
656 \end{alltt}
657
658
659 The script supports nine options; the first four let you set the
660 individual package you want to install, the whole collection (i.e.,
661 \texttt{tex-mathextra}), the name of the mounted \CD{} directory, and
662 the name of the directory containing the list files (normally these
663 latter two will be set automatically):
664
665 \begin{tabular}{ll}
666 \texttt{-{}-package=}\emph{name} & \\
667 \texttt{-{}-collection=}\emph{name} & \\
668 \texttt{-{}-cddir=}\emph{name} & \\
669 \texttt{-{}-listdir=}\emph{name} & \\
670 \end{tabular}
671
672 What actually happens is controlled by four more switches; the first
673 two allow you to exclude documentation or source files from the
674 installation, the third stops the default action of running
675 \texttt{mktexlsr} on completion to rebuild the file database, and
676 the last does nothing but list the files that would be installed:
677
678 \begin{tabular}{ll}
679 \texttt{-{}-nodoc} & \\
680 \texttt{-{}-nosrc} & \\
681 \texttt{-{}-nohash} & \\
682 \texttt{-{}-listonly} & \\
683 \end{tabular}
684
685 Finally, you can specify that, instead of installing the files, the script
686 should make a \cmdname{tar} archive in a specified location:
687
688 \begin{tabular}{ll}
689 \texttt{-{}-archive=}\emph{name} & \\
690 \end{tabular}
691
692 Thus, if we simply wanted to see the files that make up the package
693 \pkgname{fancyhdr} before we installed it, our command and output would be
694 as follows:
695
696 \begin{alltt}
697 \ifSingleColumn>> \Ucom{sh install-pkg.sh --package=fancyhdr --listonly}
698 \else>> \Ucom{sh install-pkg.sh -{}-package=fancyhdr \bs}
699 >> \Ucom{-{}-listonly}
700 \fi{}
701 texmf/doc/latex/fancyhdr/fancyhdr.dvi
702 texmf/doc/latex/fancyhdr/fancyhdr.tex
703 texmf/lists/fancyhdr
704 texmf/source/latex/fancyhdr/README
705 texmf/source/latex/fancyhdr/fancyheadings.new
706 texmf/tex/latex/fancyhdr/extramarks.sty
707 texmf/tex/latex/fancyhdr/fancyhdr.sty
708 texmf/tex/latex/fancyhdr/fixmarks.sty
709 \end{alltt}
710 Other examples of usage are:
711 \begin{itemize}
712 \item Install the \LaTeX{} package \texttt{natbib}:
713 \begin{alltt}
714 >> \Ucom{sh install-pkg.sh --package=natbib}
715 \end{alltt}
716 \item Install the \LaTeX{} package \texttt{alg} with no source files and no
717 documentation:
718 \begin{alltt}
719 \ifSingleColumn>> \Ucom{sh install-pkg.sh --package=alg --nosrc --nodoc}
720 \else>> \Ucom{sh install-pkg.sh -{}-package=alg \bs}
721 >> \Ucom{-{}-nosrc -{}-nodoc}
722 \fi\end{alltt}
723 \item Install all the packages available in the collection containing additional
724 Plain \TeX\ macros:
725 \begin{alltt}
726 >> \Ucom{sh install-pkg.sh --collection=tex-plainextra}
727 \end{alltt}
728 \item Place all files which are needed for PSTricks
729 in a \cmdname{tar} file in \path|/tmp|:
730 \begin{alltt}
731 \ifSingleColumn>> \Ucom{sh install-pkg.sh --package=pstricks --archive=/tmp/pstricks.tar}
732 \else
733 >> \Ucom{sh install-pkg.sh -{}-package=pstricks \bs}
734 >> \Ucom{-{}-archive=/tmp/pstricks.tar}
735 \fi\end{alltt}
736 \end{itemize}
737
738 \subsection{The texconfig program}
739 \label{ssec:tex}
740
741 After the installation program has copied all files to their final
742 locations, you can use a program called \cmdname{texconfig} that
743 allows you to configure the system to fit your local needs. This can
744 be called at any other time to change your setup, with a full-screen
745 (which requires the \cmdname{dialog} program, included as part of the
746 binary packages) or command-line interface.
747 It should be used for all maintenance, such as changes of installed
748 printers, or rebuilding the file database. Both modes have help text
749 to guide you through the facilities.
750
751 \section{Installation and use under Windows}
752 \label{sec:wintex}
753 This section only applies to systems running Windows 9x, \acro{ME},
754 \acro{NT}, \acro{2K} or \acro{XP}.
755
756 It is also necessary to have your Windows set up so that it uses the
757 Microsoft Joliet extensions for reading \CD s; simply look at the
758 \CD{} in Explorer and see whether it shows long, mixed-case, file
759 names. If it does not, you cannot use the ready-to-run system on the
760 \CD.
761
762 This Win32 \TeX{} systems includes a \texttt{dvi} previewer,
763 \textsf{Windvi}, which is similar in usage to the established Unix
764 \textsf{xdvi}. The documentation can be found in
765 \OnCD{texmf/doc/html/windvi/windvi.html}.
766
767 \subsection[The TeXLive.exe program]{The \texttt{TeXLive.exe} program}
768
769 \begin{figure*}
770 \begin{center}
771 \ifnum \Status=1
772 \includegraphics[width=.7\textwidth]{../pictures/Welcome-to-TeXLive}
773 \else
774 \ifnum \Status=2
775 \includegraphics[bb=20 20 575 432]{../pictures/Welcome-to-TeXLive.gif}
776 \else
777 \includegraphics[width=.7\textwidth]{../pictures/Welcome-to-TeXLive}
778 \fi
779 \fi
780 \end{center}
781 \caption{``Welcome to \TeXLive'' window}\label{graph:welcome}
782 \end{figure*}
783
784 If your computer is configured to let the \CD{} autostart, then a
785 dialog box with a menu bar will popup on the screen, and you will have several choices
786 from there:
787 \begin{itemize}
788 \item Install \TeX{} on your hard disk,
789 \item Install TeX-oriented editors on your hard disk,
790 \item Install support packages on your hard disk (Ghostscript, NetPBM,
791 \ldots)
792 \item Do some maintenance on you \TeX{} system,
793 \item Remove the \TeX{} system,
794 \item Use \TeX{} off the \CD{},
795 \item Cleanup the temporary files created on your hard disk when using
796 \TeX{} off the \CD{},
797 \item Update some of the DLLs on your system,
798 \item Browse some documentation: \TeXLive{} documentation, TUG web
799 pages, \fpTeX web pages,
800 \item Run the \cmdname{TeXdocTK} application to find specific documentation.
801 \end{itemize}
802
803 If your \CD{} does not autostart, you can explicitly run the program
804 by double clicking on \path|bin/win32/TeXLive.exe| on the \CD{} from
805 the explorer window.
806
807 \subsection[Running \protect\TeXLive{} from the CD-ROM]{Running from
808 the \protect\CD{}}
809 You can run all the \TeX{} programs directly off the \CD, and have
810 access to all the macros and fonts immediately, at the price of a
811 slower performance than if you install on the hard disk.
812 To work effectively, one needs to modify
813 environment variables and to create some small auxiliary directories on a
814 hard disk. These directories will contain necessary configuration files
815 allowing the user to modify programs settings and to generate a necessary
816 format file. Moreover, automatically generated font files will be stored
817 there too.
818
819 Should you want to run \TeX{} this way, you will have to follow these
820 steps:
821 \begin{enumerate}
822 \item from the menu, chose \verb|Explore CD-Rom|, then
823 \verb|Select a text editor|, a dialog box will open to select some \path|.exe|
824 program.
825
826 This program needs to be a \TeX{} oriented editor. It must be able
827 to run the \TeX{} compiler, previewer and any other needed tool. If
828 you don't have one already installed on your system, you can install
829 one from the \CD{}, details section~{\ref{sec:texlive-install}}.
830
831 \emph{There is no way we can guess if the program you will
832 select is actually a text editor, so be careful}.
833 Here is a list of frequently used \TeX{} editors:
834 \begin{center}
835 \begin{tabular}[ht]{ll}
836 GNU Emacs & \path|c:\Program Files\NTEmacs\bin\runemacs.exe| \\
837 XEmacs & \path|c:\Program Files\XEmacs\XEmacs-21.2\i586-pc-win32\xemacs.exe| \\
838 WinShell & \path|c:\Program Files\WinShell\WinShell.exe| \\
839 WinEdt & \path|c:\Program Files\WinEdt Team\WinEdt\WinEdt.exe|\\
840 TeXnicCenter & \path|c:\Program Files\TeXnicCenter\TEXCNTR.exe|
841 \end{tabular}
842 \end{center}
843 The program
844 selected will be memorized as the editor to use for future runs.
845
846 \item from the menu, chose \verb|Explore CD-Rom|, then
847 \verb|Run TeX off CD-Rom|. The environment will be modified, a small
848 temporary directory created and some configuration files copied
849 there. Then, the selected editor selected will be launched, and you
850 will be able to type in some text, let \TeX{} typeset it and the
851 view it or print it.
852
853 If Ghostscript is not detected on your machine, you will be warned
854 that rendering your DVI files might fail. You can install it from
855 the \path|Install|, \path|Support| menu item. See
856 section~\ref{sec:texlive-install} for details.
857
858 \item you can select a different text editor any time you want.
859
860 \item if you chose \verb|Cleanup CD-Rom setup|, everything \TeX{}
861 needed will be removed, comprised the selection of your text
862 editor, but not the extra packages you may have downloaded and
863 installed. If you installed \cmdname{WinShell} or \cmdname{NTEmacs},
864 they won't be removed.
865 \end{enumerate}
866
867 The editor is run inside a modified environment. A temporary TDS
868 compliant texmf tree is build in the temporary area of your computer.
869 It is needed to store files that may be build on the fly like pk font
870 files or format files. Configuration files are copied from the \CD{}
871 to this texmf tree, so that you can edit them if needed. The \path|ls-R|
872 database is computed for this texmf tree.
873 Then the \texttt{PATH} and \texttt{TEXMFCNF} environment
874 variables are set locally, and the editor is run in
875 this local environment. From within your editor\footnote{Actually, you can
876 state any other program than a text editor, and select your command
877 processor for example. You will then get a console with the right
878 settings to use \TeX{} from the \CD{}.}, you have access to a full
879 \TeXLive{} environment, all files referenced on the \CD{}.
880
881
882 \smallskip {\small\noindent \textbf{[For advanced users:]} You can
883 also use the small batch file \path|mkloctex.bat| to be called in a
884 directory \path|setupw32| of the \CD. From the Start menu select
885 `Run', then browse CD drive and select \path|mkloctex.bat|. Before
886 starting it, you should add two parameters separated by a space: the
887 letter of your CD drive and the letter of the hard disk where you
888 want to install the \TeX\ directory. The whole line should read,
889 e.g., \verb+d:\setupw32\mkloctex.bat d c+. When installation is
890 complete, please read carefully the information on screen. If you
891 are running Windows 9x/ME, then you will have to restart Windows. }
892
893 \subsection{Installing editors or support packages}
894 \label{sec:texlive-install}
895
896 You can already use the \path|TeXSetup.exe| program to install a
897 single, not \TeX{} dependent package. This might be either an editor
898 like \cmdname{WinShell} or \cmdname{NTEmacs},
899 or also a support package like \cmdname{NetPBM}
900 (graphics formats conversion) or \cmdname{Ghostscript}.
901
902 Some of the packages are not free, or not with the same meaning as for
903 the rest of the \CD{}. These packages have been made available through
904 the Internet. You need to enable an Internet connection in order to
905 install them. Chosing the \path|Enable Internet access| subitem will
906 search your system for an active Internet connection, or start one if
907 possible. \emph{If your computer is not connected to the Internet,
908 then the timeout might be long, 30s or more}. So try to enable it
909 only if you know you have a connection.
910
911 Only a few packages are available from the \CD{}, but the most
912 important of them: \cmdname{NTEmacs} and \cmdname{WinShell} for the
913 editors, \cmdname{Ghostscript} and \cmdname{NetPBM} for the other
914 support packages. \cmdname{NetPBM} is needed for running \TeX{}4ht.
915
916 The downloadable packages are sometimes huge: \cmdname{Perl} is 10Mb,
917 \cmdname{XEmacs} is 50Mb, so be warned that it can take a lot of time
918 to install such things. \path|TeXSetup.exe| does not yet provide an
919 estimation of the time needed to complete the download.
920
921 When installing these packages, \path|TeXSetup| is working in
922 unattended mode. However, the programs that have their own installer
923 like WinEdt or Ghostscript for example will require human interaction.
924
925 Those packages who have no specific installer will be unpacked and configured
926 for your system. You will be required to select some directory where
927 they will be installed. The directory to select should be the root
928 directory of the whole installation. Assuming you want to install
929 NTEmacs and NetPBM, the archive files already contain the
930 \path|NTEmacs\| and \path|NetPBM\| part, so the directory you have to
931 select is something like \path|c:\Local| or \path|c:\Program Files|.
932
933 \subsection{Installing to your hard disk}
934
935 Installation is started by letting the CD autostart, and
936 selecting the item \verb|Install| from the menu, then the subitem
937 \verb|TeXLive|. This will invoke the \path|TeXSetup.exe|. You can also find
938 it in the \path|bin/win32| directory and run it. \path|TeXSetup.exe|
939 is a Windows wizard and it will display several pages while running.
940
941 \begin{description}
942 \item[Welcome Page]
943 You can choose a \emph{quick} installation from
944 there, in this case, the installation will run without any human
945 assistance from beginning to end, with all the default settings
946 (Figure~\ref{graph:setup-src},
947 \ifnum \Status = 1
948 on the left%
949 \else\ifnum \Status=2
950 at the top%
951 \else
952 on the left%
953 \fi\fi
954 ). However, if you chose to install any support program that has its
955 own installer like WinEdt or Ghostscript, your intervention might be required.
956 If you have enough privileges (administrator or power user rights)
957 under a Windows version where it is applicable, then you can decide
958 to install the \TeXLive{} for all users or for yourself only by
959 checking the appropriate box.
960
961 \begin{figure*}[!htb]
962 The \cmdname{TeXSetup} Wizard\hfill
963 Source directories for the \TeXLive{} files
964
965 \begin{center}
966 \ifnum \Status=1
967 \includegraphics[width=.48\textwidth]{../pictures/setup-wizard.jpg}\hfill%
968 \includegraphics[width=.48\textwidth]{../pictures/source-for-texlive.jpg}
969 \else
970 \ifnum \Status=2
971 \includegraphics[bb=0 0 506 403]{../pictures/setup-wizard.gif}
972 \includegraphics[bb=0 0 506 403]{../pictures/source-for-texlive.gif}
973 \else
974 \includegraphics[width=.48\textwidth]{../pictures/setup-wizard}%
975 \hfill%
976 \includegraphics[width=.48\textwidth]{../pictures/source-for-texlive}
977 \fi
978 \fi
979 \caption{The \TeXLive{} setup wizard}\label{graph:setup-src}
980 \end{center}
981 \end{figure*}
982 \item[Source Page]
983 This page is a bit complex. It will allow you to select two source
984 directories for your \TeXLive{} system
985 (Figure~\ref{graph:setup-src},
986 \ifnum \Status = 1
987 on the right%
988 \else\ifnum \Status=2
989 at the bottom%
990 \else
991 on the right%
992 \fi\fi
993 ). You will need a \emph{local
994 source directory} and possibly a \emph{remote source directory}.
995
996 Why do we need both these directories? The very files of the
997 \TeXLive{} system are on the \CD{}, but some other packages useful
998 under a Win32 system are not, either because of space lacking or
999 because their license was not compatible with the \TeXLive{}'s one.
1000 You need to enable Internet downloading if you want to install these
1001 support packages.
1002
1003 However, don't panic: the default parameters of the setup will allow
1004 you to install a full system using the \CD{} only. Simply, you won't
1005 have \file{WinEdt} for example, but you will be able to install it
1006 later.
1007
1008 So you can take your files from:
1009 \begin{itemize}
1010 \item the \CD{} or any similar flat tree of files, available through
1011 some standard directory (this means the \CD{} can be mounted on
1012 some remote machine and be made available through network
1013 sharing),
1014 \item a set of \file{.zip} files (this is the case when you are
1015 installing the
1016 \fpTeX{} distribution),
1017 \item the Internet, in this case, the program takes care of
1018 downloading the \file{.zip} files it needs for you.
1019 \end{itemize}
1020 This option is available only if you enable Internet file
1021 downloading in the right part of the page. You also need to
1022 configure this Internet access by selecting to connect either using
1023 Internet Explorer~5 \file{wininet.dll}, or using a direct connection (\texttt{ftp},
1024 \texttt{http}).
1025 % or using a proxy server.
1026 % Last, you can be assisted in defining the \emph{local source
1027 % directory} and \emph{remote source directory} which will be used
1028 % to copy the files onto your hard disk. The \texttt{browse} buttons
1029 % allow to select a directory for the former, and an url among a list
1030 % of mirrors for the latter.
1031 \item[Root Page]
1032 On this page, you will tell where you want the files to be
1033 installed (Figure~\ref{graph:root-schm},
1034 \ifnum \Status = 1
1035 on the left%
1036 \else\ifnum \Status=2
1037 at the top%
1038 \else
1039 on the left%
1040 \fi\fi
1041 ). Only the root directory really matters, the other ones
1042 are set according to the root one. You may want to make
1043 \path|$TEXMFEXTRA| point to some TDS compliant directory with other
1044 \TeX{} files or assign a different value to
1045 \path|$HOMETEXMF|, which is set by default to whatever Windows think
1046 is your `HOME' location.
1047 \begin{figure*}[!htb]
1048 Root and directories\hfill%
1049 Scheme selection
1050 \begin{center}
1051 \ifnum \Status=1
1052 \includegraphics[width=.46\textwidth]{../pictures/root-of-installation.jpg}\hfill%
1053 \includegraphics[width=.46\textwidth]{../pictures/scheme-selection.jpg}
1054 \else
1055 \ifnum \Status=2
1056 \includegraphics[bb=0 0 506 403]{../pictures/root-of-installation.gif}
1057 \includegraphics[bb=0 0 506 403]{../pictures/scheme-selection.gif}
1058 \else
1059 \includegraphics[width=.46\textwidth]{../pictures/root-of-installation}%
1060 \hfill%
1061 \includegraphics[width=.46\textwidth]{../pictures/scheme-selection}
1062 \fi
1063 \fi
1064 \caption{\TeXLive-Setup: Root and directories / Schemes}\label{graph:root-schm}
1065 \end{center}
1066 \end{figure*}
1067 \item[Get TPM Page]
1068 This page does not require any manual intervention. The \file{.tpm}
1069 files which describe collections and packages are retrieved
1070 (possibly from the Internet), unzipped if needed and parsed.
1071 \item[Schemes Page]
1072 On this page, you will select the global scheme of your
1073 installation (Figure~\ref{graph:root-schm},
1074 \ifnum \Status = 1
1075 on the right%
1076 \else\ifnum \Status=2
1077 at the bottom%
1078 \else
1079 on the right%
1080 \fi\fi
1081 ). A scheme is a large set of files targeted at some kind
1082 of usage. There are 3 generic schemes for basic, recommended and
1083 full installation. The other ones are devoted to LUGs (what GUST or
1084 GUTenberg propose for their members) or applications (XML and
1085 \TeX{}).
1086 When a scheme is selected, it is still possible to refine the
1087 selection by checking the appropriate box. If doing so, you will be
1088 presented the packages page to change your selection, else you will
1089 jump to the review page.
1090 \item[Packages Page]
1091 Collections and packages are presented in a tree form
1092 (Figure~\ref{graph:win32-support},
1093 \ifnum \Status = 1
1094 on the left%
1095 \else\ifnum \Status=2
1096 at the top%
1097 \else
1098 on the left%
1099 \fi\fi
1100 ). The links
1101 in the tree are dependency links. Collections \emph{depend on}
1102 packages and maybe other collections, and it is the same for each
1103 package. You can select any package or collection individually, but
1104 your request will be granted only if the object is not requested by
1105 another one which is selected. For example, you can't deselect
1106 \texttt{tex-basic} without deselecting all the collections that
1107 request it.
1108
1109 The \texttt{win32-support} collection displayed on the picture is Win32 specific. It
1110 holds a number of bonus packages (Figure~\ref{graph:win32-support},
1111 \ifnum \Status = 1
1112 on the right%
1113 \else\ifnum \Status=2
1114 at the bottom%
1115 \else
1116 on the right%
1117 \fi\fi
1118 ) which can be installed
1119 automatically and individually: Ghostscript, the PostScript
1120 interpreter, \TeX{} oriented editors, tools like Perl,
1121 \LaTeX{}2HTML, etc. \emph{None of these packages are selected by
1122 default}. Some of them have an Internet Explorer icon on their
1123 right, this means that they are not on the \CD{} and they will be
1124 available only if you previously enabled Internet
1125 downloading. \emph{This collection cannot be selected entirely at
1126 once: you need to select the packages individually}. This is to
1127 avoid unwanted downloads of huge files.
1128
1129 On this page, you also have the information about disk space
1130 needed, for each object, and for the set of those who are selected,
1131 and also the disk space available on the partition selected for the
1132 installation. Last, you can choose to install or not the
1133 documentation files and source files associated with each package.
1134 \item[Review Page]
1135 You will find there a summary of your choices
1136 (Figure~\ref{graph:review},
1137 \ifnum \Status = 1
1138 on the left%
1139 \else\ifnum \Status=2
1140 at the top%
1141 \else
1142 on the left%
1143 \fi\fi
1144 ). It is still time to
1145 go back to change them.
1146 \begin{figure*}[!htb]
1147 Packages Page\hfill%
1148 Win32 Support
1149 \begin{center}
1150 \ifnum \Status=1
1151 \includegraphics[width=.48\textwidth]{../pictures/package-selection}\hfill%
1152 \includegraphics[width=.48\textwidth]{../pictures/win32-support}
1153 \else
1154 \ifnum \Status=2
1155 \includegraphics[bb=0 0 506 403]{../pictures/package-selection.gif}\hfill%
1156 \includegraphics[bb=0 0 506 403]{../pictures/win32-support.gif}
1157 \else
1158 \includegraphics[width=.48\textwidth]{../pictures/package-selection}%
1159 \hfill%
1160 \includegraphics[width=.48\textwidth]{../pictures/win32-support}
1161 \fi
1162 \fi
1163 \end{center}
1164 \caption{Packages Page / Win32 goodies}
1165 \label{graph:win32-support}
1166 \end{figure*}
1167 \item[Files Copy Page]
1168 The selected files are copied on your hard disk (Figure~\ref{graph:file-copy},
1169 \ifnum \Status = 1
1170 on the right%
1171 \else\ifnum \Status=2
1172 at the bottom%
1173 \else
1174 on the right%
1175 \fi\fi
1176 ). All the files not
1177 yet available on your local disk are first downloaded from the
1178 remote source directory on the Internet. Then every package is
1179 unpacked (if \path|.zip| files), or copied from the \CD{}.
1180 \item[Configuration Page] Several packages need some configuration
1181 step to make them usable (Figure~\ref{graph:configuration},
1182 \ifnum \Status = 1
1183 on the left%
1184 \else\ifnum \Status=2
1185 at the top%
1186 \else
1187 on the left%
1188 \fi\fi
1189 ). Also the \TeXLive{} system needs some post-processing step
1190 (format files generation, ls-R databases generation, environment
1191 variables, etc.). All these operations are done there, some of them
1192 can be lengthy.
1193 \begin{figure*}[!htb]
1194 \textbf{Review Page}\hfill%
1195 \textbf{File Copy Page}
1196 \begin{center}
1197 \ifnum \Status=1
1198 \includegraphics[width=.48\textwidth]{../pictures/review-settings}\hfill%
1199 \includegraphics[width=.48\textwidth]{../pictures/file-copy}
1200 \else
1201 \ifnum \Status=2
1202 \includegraphics[bb=0 0 506 403]{../pictures/review-settings.gif}\hfill%
1203 \includegraphics[bb=0 0 506 403]{../pictures/file-copy.gif}
1204 \else
1205 \includegraphics[width=.48\textwidth]{../pictures/review-settings}\hfill%
1206 \includegraphics[width=.48\textwidth]{../pictures/file-copy}%
1207 \fi
1208 \fi
1209 \end{center}
1210 \caption{Review Page / File Copy Page}
1211 \label{graph:review}\label{graph:file-copy}
1212 \end{figure*}
1213 \item[Final Page] The installation being over, you may want to display
1214 the Windows specific documentation (HTML format) and / or the log
1215 file of the setup process (Figure~\ref{graph:final}
1216 \ifnum \Status = 1
1217 on the right%
1218 \else\ifnum \Status=2
1219 at the bottom%
1220 \else
1221 on the right%
1222 \fi\fi
1223 ). If it is needed (Win9x/WinME), you will
1224 be asked to reboot your computer.
1225 \end{description}
1226
1227 \begin{figure*}[!htb]
1228 \textbf{Configuration Page}\hfill%
1229 \textbf{Final Page}
1230 \begin{center}
1231 \ifnum \Status=1
1232 \includegraphics[width=.48\textwidth]{../pictures/configuration}\hfill%
1233 \includegraphics[width=.48\textwidth]{../pictures/congratulations}
1234 \else
1235 \ifnum \Status=2
1236 \includegraphics[bb=0 0 506 403]{../pictures/configuration.gif}\hfill%
1237 \includegraphics[bb=0 0 506 403]{../pictures/congratulations.gif}
1238 \else
1239 \includegraphics[width=.48\textwidth]{../pictures/configuration}\hfill%
1240 \includegraphics[width=.48\textwidth]{../pictures/congratulations}%
1241 \fi
1242 \fi
1243 \end{center}
1244 \caption{Configuration Page / Final page}
1245 \label{graph:configuration}\label{graph:final}
1246 \end{figure*}
1247
1248 Please be aware that the choice of cluster size on DOS disk
1249 partitions can radically affect the size of your \TeX\
1250 installation. The support tree has hundreds of small files, and it is
1251 not unusual for a complete installation to take up to 4 times the
1252 amount of space used on the \CD.
1253
1254
1255 \section[Maintenance and other aspects of the \protect\TeXLive{}
1256 installation under Windows]{Maintenance and other aspects of the \protect\TeXLive{}
1257 installation under Windows}
1258
1259 \subsection{What's different under Win32 from the standard \Webc ?}
1260 The Win32 version of \Webc{} has some specific features that need to
1261 be noticed.
1262
1263 \begin{description}
1264 \item[\KPS{}] the hash-tables that \KPS{} builds are quite large for
1265 the \TeXLive{}. In order to cut down the starting time of any
1266 \KPS{}-enabled program, these hash-tables have been put in shared
1267 memory. This way, when you chain the execution of several such
1268 programs, like \path|tex| calling \path|mpost| calling \path|tex|,
1269 the overhead when starting each of the programs but the first will
1270 be reduced. This change is hidden to the user, except if you set the
1271 debug flag of kpathsea to the \path|-1| value: you will then trace
1272 access to the shared memory, which is not what you want (it is
1273 accessed very often!). What is useful in a log trace of the shared
1274 memory access is still to be defined, so the situation might evolve
1275 in the future.
1276 \item[\cmdname{kpsecheck}] this command provides some option that did
1277 not fit well into \cmdname{kpsewhich}. It will allow you to list all
1278 the files that occur multiple times across your texmf trees. This
1279 could be handy, but most of the time you will also get unwanted
1280 output (like dozens of \path|README| files)\footnote{It is noticeable
1281 that all these files result in clashes inside the \KPS{}-hashing
1282 mechanism, fortunately, \KPS{} never look for these files.}. For
1283 this reason, you can combine the \path|-multiple-occurences| with 2
1284 other options for including or excluding any filename that match
1285 some pattern (you can request for several patterns).
1286
1287 The \cmdname{kpsecheck} command will also report the status of
1288 shared memory: in use or not used. That might be useful to know
1289 because if the status reported is ``in use'', that means one or
1290 several processes are working, and the effect of any
1291 \cmdname{mktexlsr} command will be delayed until the next time where
1292 no \KPS{} linked process will be running.
1293
1294 Last, this same command will report about the location it thinks
1295 Ghostscript can be found. Under Win32, for many programs, it is
1296 easier to use the Ghostscript dll, and find it by using the
1297 Ghostscript registry key than to change the \path|PATH|, which has a
1298 limited length anyway.
1299 \item[\Webc{}] the engines have a few more options than the ones from regular
1300 \Webc{}, and one option with a different behaviour:
1301 \begin{itemize}
1302 \item the \path|-fmt| option behaves differently. Previously and
1303 with the regular \Webc{} distribution, this option has 2 different
1304 meanings when you are in ``ini'' or ``vir'' mode. Under Win32, it
1305 has the same meaning: preload the format file specified with the
1306 argument. The meaning of building a format of such name in ``ini''
1307 mode is obtained by the new \path|-job-name| option.
1308 \item \path|-job-name| option: allows to set the name of the file
1309 resulting from the compilation process. In normal mode, it will
1310 change the base name of all files produced (\path|.dvi|,
1311 \path|.aux|, etc.), while in ``ini'' mode, it will set the name of
1312 the format file written.
1313 \item \path|-halt-on-error| stop the compilation at the first error.
1314 \item \path|-job-time| set the job time to the same timestamp as the
1315 file given in argument.
1316 \item \path|-output-directory| allow to write all the output files in the
1317 specified directory.
1318 \item \path|-time-statistics| print statistics about the job run
1319 time. It is to be noted that Win9x not being a true multitasking
1320 operating system, it has no reliable timer for short periods, so
1321 the value printed is an approximation. Under NT/2K/XP, the result
1322 is quite accurate with user time and system time values allocated
1323 for this run. For Unix
1324 users: the \path|time| command is not usually available to Windows
1325 users.
1326 \end{itemize}
1327 \end{description}
1328
1329 \subsection{Adding packages to your installation}
1330
1331 You will find an option in the \texttt{TeXLive} menu (or go to
1332 \texttt{Start -> Programs -> TeXLive -> Add TeX package} menu) to run again
1333 \file{TeXSetup.exe}, but in maintenance mode this time. The steps you
1334 will go through are almost identical to the ones the first time you
1335 run it.
1336
1337 The only different step is about the packages selection page. In
1338 maintenance mode, the list of installed packages is compared to the
1339 list of packages available from your source directories. Packages that
1340 are not installed will be displayed in green, out of date packages
1341 will be displayed in red and up to date, installed packages are
1342 displayed in black.
1343
1344 This way, you can choose to add or upgrade components, either from
1345 your \CD{} or from the
1346 Internet, where you are likely to find some more recent version of
1347 your packages.
1348
1349 It is up to you to select which ones of the packages you want to
1350 install. The rest of the process is similar to the first installation.
1351
1352 If you want to add files that are not provided by the \TeXLive{} (or
1353 \fpTeX{}) distribution, it is recommended to put them in the
1354 \path|$TEXMFLOCAL| directory. This way, you will be safe against
1355 upgrades of the \TeXLive{} software.
1356
1357 The directory pointed to by \path|$TEXMFLOCAL| is initially empty. If
1358 you want to add there the support file for Maple (symbolic computation
1359 program) for example, you will have to put the style files in:\\
1360 \path|c:\Program Files\TeXLive\texmf-local\tex\latex\maple\|\\
1361 and the documentation files in:\\
1362 \path|c:\Program Files\TeXLive\texmf-local\doc\latex\maple\|
1363
1364 Next, \textbf{do not forget to rebuild the ls-R databases files},
1365 either by using the right menu (Start -> Programs -> TeXLive
1366 -> Maintenance), either by manually running the \file{mktexlsr}
1367 command.
1368
1369 \subsection[Removing \protect\TeXLive{} from your hard disk]{Removing
1370 \protect\TeXLive{} from your hard disk}
1371
1372 The uninstall procedure is available either from the
1373 \file{TeXLive.exe} program, from the \path|TeXLive| menu or from the
1374 control panel (Start menu -> Control Panel, Add/Remove Programs
1375 option). This procedure will cleanup your hard disk of most of the
1376 \TeXLive{} files. However, \TeX{} is a system that is creating files
1377 and there is no mechanism to keep track of all of them. Moreover,
1378 Win32 support packages have their own uninstall procedure, which you
1379 will have to run separately (provided you want to get rid of them). Last,
1380 the files you may have stored in \path|$TEXMFLOCAL| won't be
1381 removed. So, even if the vast majority of files are automatically
1382 removed by the uninstall procedure, you will have to do some manual
1383 cleanup to actually remove all of them.
1384
1385 \subsection{Running \texttt{TeXSetup.exe} from the command line}
1386
1387 The \path|TeXSetup.exe| program has a number of other interesting
1388 options. You can get the list by running:
1389 \begin{verbatim}
1390 c:\>TeXSetup --help
1391 \end{verbatim}
1392
1393 Here is the description:
1394 \begin{description}
1395 \item[\path|--automatic-reboot|] reboot without waiting user
1396 confirmation once installation is over;
1397 \item[\path|--dry-run|] do nothing, just log everything that will be
1398 done without this option;
1399 \item[\path|--quick|] use the recommended installation and default
1400 directories, ask nothing up to rebooting;
1401 \item[\path|--net-method (=ie5/direct)|] enable to download components with
1402 restricted licenses from the Internet (either using direct
1403 connection of Internet Explorer 5 DLLs): you need to have an available
1404 network connection and some of the packages are huge;
1405 \item[\path|--remote-source-directory <url>|] this is the base url for the remote packages;
1406 \item[\path|--local-source-directory <dir>|] by default, \path|TeXSetup.exe|
1407 will guess the root directory of the set of files you want it to act on, if you ever
1408 upgrade \path|TeXSetup.exe|, you won't be able to copy the new version
1409 onto your \CD{}, so you will need to use this option to specify the
1410 root of the \CD{};
1411 \item[\path|--installation-directory <dir>|] this is the root of your
1412 installation, all files will be copied under this location. The
1413 default value is \verb+c:\Program Files\TeXLive+;
1414 \item[\path|--texmfmain-directory <dir>|]
1415 \item[\path|--texmflocal-directory <dir>|]
1416 \item[\path|--texmfextra-directory <dir>|]
1417 \item[\path|--texmfhome-directory <dir>|]
1418 \item[\path|--vartexmf-directory <dir>|]
1419 \item[\path|--vartexfonts-directory <dir>|] these are the directories
1420 used to configure the location of your files. They map directly to
1421 the \path|texmf.cnf| variables.
1422 \item[\path|--with-source-files(=yes/no)|] copy the source files
1423 for \TeX{} packages, default value is no;
1424 \item[\path|--with-documentation-files(=yes/no)|] copy documentation files for \TeX{}
1425 packages. Default value is yes. Beware: this is only documentation about specific
1426 packages, general documentation will be installed anyway;
1427 \item[\path|--program-folder <folder>|] the name of the folder under
1428 which you will find the menus;
1429 \item[\path|--add-package <pkg>|] this is used to add or update a specific
1430 package after a first regular installation;
1431 \item[\path|--scheme <pkg>|] install the named scheme instead of the
1432 default \path|texlive-recommended| scheme;
1433 \item[\path|--maintenance|] mostly the same as \path|--add-package|
1434 without specifying a package to add;
1435 \item[\path|--uninstall|] this option will remove anything \TeX{} related coming from
1436 the \CD{}, which means there can be files left if you added style
1437 files or format files, and also that supplementary tools will not be
1438 removed\footnote{This option is still a bit crude as of \today};
1439 \item[\path|--help|] this option opens up a box with the list of options.
1440 \end{description}
1441
1442 \subsection{Network installation}
1443
1444 \KPS{} knows about UNC names, so you can use them to get your TEXMF
1445 tree from the network. But there is better than this.
1446 All the support files and configuration files, everything except the files in the
1447 \path|bin/win32| are shareable with a \teTeX{} or Unix \TeXLive{} installation. That means
1448 you can use Samba either to mount from an NT server to a Unix
1449 workstation or the converse. Several strategies are possible:
1450 \begin{itemize}
1451 \item Put everything on the server. Just add each set of files for the os and
1452 architecture you want to use in the \path|bin| directory. That means
1453 for example \path|bin/win32| and \path|bin/i386-linux|. Next configure
1454 your main variables. You can use UNC names to
1455 point to the right directories under Win32.
1456 \item Install a local copy for the binaries and format files. In this
1457 case, assign \path|$TEXMFMAIN| to the main \path|texmf| tree that
1458 will be accessed remotely. Set \path|$VARTEXMF| to be a local
1459 directory which will hold local configuration files and on-the-fly
1460 generated files.
1461 \end{itemize}
1462
1463 \subsection{Personal Configurations}
1464
1465 \subsubsection{\cmdname{WinShell}}
1466 \label{sec:winshell}
1467
1468 Start this program from the Start menu or from the Desktop shortcut.
1469 Go to \textbf{Options} \verb+->+ \textbf{Program Calls}.
1470
1471 \begin{itemize}\itemsep 0pt
1472 \item In the DVIWin tab, if the filename is \textbf{yap}, replace it
1473 with \textbf{windvi.exe}.
1474 \item In Ghostview tab, make sure it gives the correct path for
1475 gsview32.exe:\\
1476 \hspace*{1em} \verb+C:\ghostgum\gsview\gsview32.exe+ (for 3.6, the
1477 current version)\\
1478 or \\
1479 \hspace*{1em} \verb+C:\gstools\gsview\gsview32.exe+ (for the older
1480 version)
1481
1482 \end{itemize}
1483
1484 Click \textbf{OK}.
1485
1486 Note that the install process sets all files with the \texttt{.tex}
1487 extension to open with \cmdname{WinShell}. Unless you plan to use another editor
1488 (such as WinEdt or Emacs), this is appropriate.
1489
1490 Unfortunately, \cmdname{WinShell} does not have a spell-checking feature.
1491 However, if you have installed the \path|tex-extrabin| collection,
1492 your installation includes \textbf{Ispell} (a spell checking program
1493 found on most Unix systems). The executable is in your PATH so
1494 \verb+ispell.exe+ will be found if you invoke it from a DOS window.
1495 If you installed documentation, look
1496 at\\
1497 \verb+C:\Program Files\TeXLive\texmf\doc\html\manpages\ispell.html+\\
1498 for information on Ispell. (Otherwise, you can find
1499 \verb+ispell.html+ on the CD.) If you rely on spell checking, you may
1500 want to add an Ispell icon to \cmdname{WinShell}. See
1501 subsection~\ref{winshell:ispell} of this document for how to do that.
1502
1503 For an excellent commercial (but inexpensive) spelling checker,
1504 see \url{http://www.microspell.com}.
1505
1506 %Appendix B also contains other information about using \cmdname{WinShell}, such as:
1507 %
1508 %\begin{itemize}
1509 %\item How to apply a bug fix you probably need
1510 %\item How to print directly from \cmdname{WinShell}
1511 %\item How to use the Project feature for multiple-file documents
1512 %\end{itemize}
1513
1514 \cmdname{WinShell} also has on-line help, which you can access via the
1515 $\textbf{\underbar{?}}$ on the menu bar.
1516
1517 Other information about using \cmdname{WinShell} can be found in
1518 section \ref{winshell:more} on p.~\pageref{winshell:more}.
1519
1520 \subsubsection{Dvips}
1521
1522 The configuration file for dvips can be found in\\
1523 \verb+C:\Program Files\TeXLive\texmf-var\dvips\config\config.ps+\\
1524 You may open it with any editor (\cmdname{WinShell} will do fine) and change
1525 some parameters:
1526
1527 \begin{description}
1528 \item [fonts] you can change the default printer \MF{} mode or printer
1529 resolution in case dvips needs to generate PK fonts. By default it
1530 is configured to use type1 versions of the CM fonts, so it should
1531 not call \cmdname{mktexpk} too often;
1532 \item[printer] you can tell dvips where you want to print by
1533 default. If the `o' option is not followed by a printer name, then a
1534 \file{.ps} PostScript file is written. You can give dvips a printer
1535 name such as:
1536 \begin{verbatim}
1537 o lpt1:
1538 % o | lpr -S server -P myprinter
1539 % o \\server\myprinter
1540 \end{verbatim}
1541 \item[paper] Next, you might want
1542 to change the paper size from European (A4) to US letter
1543 by making the US letter the first paper size mentioned in the file.
1544 Scroll to the group of lines beginning with ``@''. Move
1545 the appropriate lines so that this section begins with the lines:\\
1546 \hspace*{1em} @ letterSize 8.5in 11in\\
1547 \hspace*{1em} @ letter 8.5in 11in\\
1548 \hspace*{1em} @+ \%\%BeginPaperSize: Letter\\
1549 \hspace*{1em} @+ letter\\
1550 \hspace*{1em} @+ \%\%EndPaperSize
1551 \end{description}
1552
1553 \textbf{Note:} The current \TeXLive{} distribution has implemented (for
1554 the first time!) the procedure of making always up-to-date fontmaps files
1555 for Dvips and Pdftex. This is done by \cmdname{updmap} program
1556 during installation, as well as during any font package addition.
1557 If you add new packages by hand, edit the file \verb+updmap.cfg+
1558 in \path|$VARTEXMF/web2c|.
1559
1560 \subsubsection{Pdftex}
1561 If you want to use the program pdf{}latex to convert directly to
1562 pdf format, and you are using US letter file, edit the file\\
1563 \verb+C:\Program Files\TeXLive\texmf-var\pdftex\config\pdftex.cfg+\\
1564 and change ``page\_width'' and ``page\_height'' to specify letter-size paper.
1565 These entries should read:\\
1566 \hspace*{1em} page\_width 8.5 true in\\
1567 \hspace*{1em} page\_height 11 true in\\[6pt]
1568 Save the file and exit the editor.
1569
1570 \subsubsection{GSView}
1571 Starting from versions compatible with Ghostscript 6.50, GSView is not
1572 free anymore, but shareware. So it is not on the \CD{} anymore.
1573
1574 You may want to change the papersize to US letter size. If so,
1575 open GSView from the Start menu. \\
1576 From the \textbf{Media} menu, select \textbf{Letter}.
1577
1578 Also, there are menu settings that are supposed to give you the
1579 most readable screen image:\\[4pt]
1580 From \textbf{Media} \verb+->+ \textbf{Display Settings},
1581 set \textbf{Text Alpha}
1582 and \textbf{Graphics Alpha} both to 4 bits.
1583
1584 Note that the installation process has set all .ps and .eps files
1585 to automatically open with GSView.
1586
1587 For printing instructions, see section~\ref{printing} below.
1588
1589 \subsubsection{WinDvi}
1590 \label{sub:windvi}
1591
1592 The \file{TeXSetup.exe} program takes care of associating the files
1593 with the \file{.dvi} extension with \file{Windvi}.
1594
1595 Open it from the Start menu (Programs \verb+->+ TeXLive \verb+->+ DVI Viewer).
1596 You can set it for US letter paper by going to \textbf{View} \verb+->+ \textbf{Options}
1597 and next to \textbf{Papertype},
1598 selecting US (8.5\verb+"+ x 11\verb+"+).
1599 Click \textbf{OK}.
1600 Exit Windvi.
1601 You can change other parameters from there, like the ability to
1602 execute commands included in path|\special{}|.
1603 Also, the first time you
1604 view any .dvi file, you may find the magnification too large. Zoom out
1605 until you get an appropriate size.
1606
1607 %There are two important parameters related to printing that can't yet
1608 %be set from the dialog boxes, namely the resolution and the \MF{} mode
1609 %for the printer. You can set them once for all by specifying them on
1610 %the command line:
1611 %\begin{verbatim}
1612 %c:\>windvi -p 360 -mfmode canonbjc foo.dvi
1613 %\end{verbatim}
1614 %When you will exit Windvi, these parameters will be stored in the
1615 %configuration file. The available modes are found in this file:\\
1616 %\path|c:\Program Files\TeXLive\texmf\metafont\misc\modes.mf|
1617
1618 All the configuration for Windvi is stored in the
1619 \path|$HOME/windvi.cnf| file. You can find it by running this command
1620 at the prompt:
1621 \begin{verbatim}
1622 c:\>kpsewhich --expand-var $HOME/windvi.cnf
1623 \end{verbatim}
1624
1625 Should you have problems with Windvi, please remove the configuration
1626 file and test your problem against a vanilla configuration.
1627
1628 \subsection{Testing}
1629
1630 You can test \cmdname{WinShell} by opening the file \verb+sample2e.tex+, found in
1631 \path|C:\Local\TeX\texmf\tex\latex\base|. The \LaTeX\ source should appear
1632 on the screen. Process it by clicking on the \LaTeX\ icon on the toolbar,
1633 then view it by clicking on the Preview (Windvi) icon.
1634
1635 At first, when you preview files with Windvi, it will create fonts because
1636 screen fonts were not installed. After a while, you will have created most
1637 of the fonts you use, and you will rarely see the font-creation window.
1638 Return to \cmdname{WinShell} and try dvips, then GSView.
1639
1640 \textbf{Hint for the future:} If a \LaTeX\ run stops because \LaTeX\
1641 cannot find a file, you can press \textbf{Ctrl-z} to quit.
1642
1643 \subsection{Printing}\label{printing}
1644
1645 It is possible to print from Windvi. In this case, printing will
1646 be done using the Windows unified printer driver. By definition, it
1647 is compatible with all printers. However, there is some drawback: it
1648 can generate some huge spool files, and some (older) versions of Windows just
1649 don't like them. The advantage is that you can use features like
1650 embedding BMP or WMF images. You also need to make sure that the
1651 printer parameters are correctly set (subsection~\ref{sub:windvi}),
1652 else you will get scaled printing (printing at 600dpi on a 300dpi
1653 printer will give you only one quadrant of your page).
1654
1655
1656 Printing is faster and more reliable if you run dvips to make a
1657 .ps file and then print from GSView. To print from GSView, first select
1658 \textbf{Print...} from the \textbf{File} menu. A Print window will appear.
1659
1660 If you will be using a PostScript printer, \textit{be sure to select
1661 \textbf{PostScript Printer}}. In the newer version this is done in
1662 the ``Print Method'' box at the bottom left of the Print window. You
1663 can then select any of the printers that you have previously installed
1664 on your PC. If you fail to check the box for PostScript Printer,
1665 printing will not work.
1666
1667 If you will be using your own non-PostScript printer, select
1668 \textbf{Ghostscript device} in the ``Print Method'' box, then click on
1669 the button to the right labelled \textbf{djet500} and select your
1670 printer type from the list that pops up. (In the older version of
1671 GSView, make sure PostScript Printer is \textit{not} selected, then
1672 select your printer type from the ``Device'' list.)
1673
1674 If you use \cmdname{WinShell} and a PostScript printer, probably the most
1675 convenient way to print is to add an icon to the \cmdname{WinShell} toolbar that
1676 invokes dvips in a way that sends the output directly to a default
1677 printer. For detailed instructions on how to do this, see
1678 \ref{winshell:print} on p.~\pageref{winshell:print}
1679 (\textit{More About \cmdname{WinShell}}).
1680
1681 \subsection{More About \cmdname{WinShell}}\label{winshell:more}
1682 \subsubsection{Installing Bug Fixes}
1683
1684 \cmdname{WinShell}'s author (\href{mailto:[email protected]}{Ingo de Boer},
1685 thanks to him) sometimes releases beta versions of the next \cmdname{WinShell}
1686 version which are also bug fixes. You can grab them from
1687 \url{http://www.winshell.de}. Usually they are \file{.zip} files that
1688 only require to be unpacked in \cmdname{WinShell} directory (\path|c:\Program
1689 Files\WinShell| by default), either using WinZip or a similar tool, or
1690 by using \file{unzip} on the command line. If you got some
1691 \file{winshellbugfix.zip} file and that you saved it in the \cmdname{WinShell}
1692 directory, then you need to run:
1693 \begin{verbatim}
1694 c:\>cd c:\"Program Files"\WinShell
1695 c:\>c:\local\bin\unzip winshellbugfix.zip
1696 \end{verbatim}
1697 Say `yes' if you are asked if some files should be overwritten. The
1698 \path|unzip.exe| programme can be found in the
1699 \path|support/gnu-utils| package. If you
1700 do not have it on your machine, you can use any archiver tool like
1701 WinZip to achieve the same effect.
1702
1703 \subsubsection{Using the Project Feature}
1704 If your document is split into several files
1705 (for example a thesis), look into \cmdname{WinShell}'s ``Project'' feature. From the
1706 \textbf{Project} menu, you give the project a name (e.g., Thesis),
1707 supply the name of the main (or root) file, and then ``add'' other
1708 files. These filenames display on the left of the screen where you can
1709 double click the names to view and switch between them. Clicking
1710 the \textbf{\LaTeX} icon always processes the main file.
1711
1712 Note the icons on the toolbar for toggling the project space (on the left)
1713 and the log space (at the bottom). If you are not using the Project
1714 feature, you may want to toggle off the space on the left, using the full
1715 screen width to display your file.
1716
1717 \subsubsection{Printing from \cmdname{WinShell} to a PostScript Printer}
1718 \label{winshell:print}
1719
1720 The Dvips icon on the \cmdname{WinShell} toolbar puts the PostScript output in a file,
1721 which you can then view with GSView and print from there if you choose.
1722 However, it's convenient to add a \cmdname{WinShell} ``program call'' to dvips which
1723 sends the output directly to a designated PostScript printer. The steps
1724 below show how to do this for the printer \textbf{vclw}; you should
1725 substitute the name of your most frequently-used printer for \textbf{vclw}.
1726 \begin{enumerate}
1727 \item Make the program aware of the printer:
1728 \begin{itemize}
1729
1730 \item Open \cmdname{WinShell}, go to \textbf{Options} \verb+->+
1731 \textbf{Program Calls} \verb+->+ \textbf{User defined}.
1732
1733 \item Click on \textbf{Tool 1} in the list on the right and fill in the
1734 fields to the left as follows:\vspace{-6pt}
1735 \begin{quote}
1736 Name: \verb+Print+\\
1737 exe file: \verb+dvips+\\
1738 cmd-line: \verb+ -D600 %m -o vclw+\\
1739 Uncheck the box for ``DVIPS first''
1740 \end{quote}%\vspace{-12pt}
1741 \item Click \textbf{OK}
1742 \end{itemize}
1743 \item Add Print to the toolbar:
1744 \begin{itemize}
1745 \item Go to \textbf{Options} \verb+->+ \textbf{View} \verb+->+ \textbf{Customize}.
1746 \item In the Category box, select \textbf{User-Programs}.
1747 \item Select \textbf{Print} and drag it to the toolbar, placing it just to
1748 the right of the GSView icon.
1749 \item You then have a choice of ``Image only'', ``Text only'', or ``Image and
1750 Text''. The easiest is to select ``Text only'' and click \textbf{OK}.
1751 You should then see \textbf{Print} on the toolbar. (If you prefer, you can
1752 select ``Image only'', then ``Edit'', and edit the displayed picture to your
1753 satisfaction.)
1754 \end{itemize}
1755 \end{enumerate}
1756 Now, to print a \LaTeX\ document, just click on the \textbf{Print} icon to
1757 send to your selected printer. To use a different printer, you will need to
1758 click on the \textbf{Dvips} icon to print to a file. Then click on the
1759 GSView icon and use GSView to send to any printer you have installed on
1760 your PC.
1761
1762 \subsubsection{Adding Ispell to \cmdname{WinShell}}
1763 \label{winshell:ispell}
1764 \begin{enumerate}
1765 \item Add Ispell to User Tools:
1766 \begin{itemize}
1767 \item Open \cmdname{WinShell}, go to \textbf{Options} \verb+->+
1768 \textbf{Program Calls} \verb+->+ \textbf{User defined}.
1769 \item In the list on the right, click on \textbf{Tool 1} (or \textbf{Tool
1770 2} if you have already used \textbf{Tool 1}) and fill in the
1771 fields to the left as follows:\vspace{-6pt}
1772 \begin{quote}
1773 Name: \verb+Ispell+\\
1774 exe file: \verb+ispell+\\
1775 cmd-line: \verb+ -t -d american %c.tex+\\
1776 Uncheck the boxes for ``LaTeX first'' and ``DVIPS first''
1777 \end{quote}%\vspace{-12pt}
1778 \item Click \textbf{OK}
1779 \end{itemize}
1780
1781 \item Add Ispell to the toolbar: %\vspace{-14pt}
1782 \begin{itemize}\itemsep 0pt
1783 \item Go to \textbf{Options} \verb+->+ \textbf{View} \verb+->+ \textbf{Customize}.
1784 \item In the Category box, select \textbf{User-Programs}.
1785 \item Select \textbf{Ispell} and drag it to the toolbar, placing it just to
1786 the right of the GSView icon (or the last icon you added).
1787 \item You then have a choice of ``Image only'', ``Text only'', or ``Image and
1788 Text''. The easiest is to select ``Text only'' and click \textbf{OK}.
1789 You should then see \textbf{Ispell} on the toolbar. (If you prefer, you can
1790 select ``Image only'', then ``Edit'', and edit the displayed picture to your
1791 satisfaction.)
1792 \end{itemize}
1793 \end{enumerate}
1794 Now, when you have a \LaTeX\ document open, you can click on
1795 \textbf{Ispell} to perform spell checking. Ispell will open another window
1796 and display the first misspelled word on the left with the filename on the
1797 right. Below that you will see the context in which the misspelling appears;
1798 often several suggestions for replacements are also displayed. To replace
1799 the word, enter the number corresponding to the desired replacement. Other
1800 possible responses are listed below; for example, you can press the space
1801 bar to ignore the misspelled word. For more information on Ispell, read the
1802 manual page: \verb+C:\Program Files\TeXLive\texmf\doc\html\manpages\ispell.html+.
1803
1804 Note that when you replace a word, you will not see the correction in your
1805 \cmdname{WinShell} window until you close the file (click the X in the upper right
1806 corner) and then open it again (use the File menu).
1807
1808 \subsection{Tips and tricks about the Win32 platform}
1809
1810 \subsubsection{Different flavors of Win32}
1811
1812 What we call Win32 is not an operating system by itself. It is a set
1813 of functions -- and a large one\footnote{Around 12000 functions in the
1814 header files of the Microsoft SDK} -- that you can use to write
1815 programs for different operating systems of the Windows family.
1816
1817 Windows comes in different flavors:
1818 \begin{itemize}
1819 \item Win95, Win98 and WinME, which \emph{are not true multitasking,
1820 multithreading} environments. They are the latest -- and hopefully
1821 last -- metamorphosis of DOS. This can be more or less proven by the
1822 fact that when booting, the PC will load the \path|command.com|
1823 interpreter, and if you stop the boot process at this point, you can
1824 ask for the current (DOS) version and it will answer something like
1825 'MS-DOS 7.0' (at least for the old versions of Win9x);
1826 \item Windows NT, which is a new operating system written from scratch,
1827 capable of
1828 true multitasking behaviour, and loaded with high level features;
1829 \item Windows 2K, written on an NT basis, with all the bells and
1830 whistles of Win98.
1831 \item Windows XP, which comes with Personal and Pro flavors. This is
1832 the last step in merging both lines of products (Win9x based and NT
1833 based). XP is written on an NT basis.
1834 \end{itemize}
1835
1836 Win9x are able to run 32~bits programs and 16~bits programs
1837 concurrently. But the operating system by itself is not entirely
1838 written in 32~bits mode, and does not support memory protection: 16bits
1839 applications can overwrite parts of the operating system memory! Some
1840 parts of the system like the GDI (Graphical Device Interface) manage
1841 limited resources like bitmaps, fonts, pens and so on for the set of
1842 all programs that run concurrently. All the bitmaps headers available
1843 at the same time can't amount for more than 64kb. This explains the
1844 performance tool and the fact that you can put your system on his
1845 knees by making intensive use of graphic objects for example.
1846
1847 NT, 2K and XP do not suffer from these limitations, and neither from
1848 other Win9x limitations. They are true multitasking environments, with
1849 protected memory. They are much more responsive than Win9x because
1850 of better memory management, better file system and so on.
1851
1852 \subsubsection{Command line prompt}
1853
1854 You will wonder: ``why would I need to use a command line prompt when
1855 I have Windows?''.
1856
1857 Good question. The problem is of very general nature. Not all
1858 operations can be done easily using only a GUI. Command line gives you
1859 programming power -- assuming a clever command interpreter.
1860
1861 But the problem here is more fundamental: \TeX{} is \emph{a batch}
1862 tool. Not an interactive one. \TeX{} needs to compute the best
1863 layout for each page, resolve cross-references and so on. This can be
1864 done only by a global processing of the document. It is not (yet) a
1865 task that can be done interactively.
1866
1867 This means that you should use \TeX{} from a command line. In fact the
1868 situation is not so bad. There is an advantage to write command line
1869 tools for complex processing: they are better debugged, because not
1870 tied to GUI problems, and GUI tools can be designed to interface the
1871 command line tools. This is the case for \TeX{} where you will
1872 interact with it most of the time through a GUI text editor -- see
1873 section~\ref{sec:winshell} for example.
1874
1875 However, you may need to use the command line prompt in a number of
1876 situations, by example in case of problems and you want to debug your
1877 setup -- see
1878 section~\ref{sec:troubleshooting}.
1879
1880 \begin{description}
1881 \item[Win9x] You will open a command line prompt by looking either
1882 for the MS-DOS icon in the ``Start->Programs'' menu, either by
1883 choosing ``Start->Run'' menu and typing in \path|command.com|
1884 \item[NT, 2K, XP] You will open a command line prompt by looking
1885 for the ``Command Prompt'' in the ``Start->Accessories''
1886 menu\footnote{These locations may change across different OS
1887 versions.}. You can also choose the ``Start->Run'' menu and type
1888 in \path|cmd.exe|, which is the name of the brand new command
1889 interpreter for NT\footnote{Which explains why it is untrue to
1890 call this a \emph{DOS} box under NT!}.
1891 \end{description}
1892
1893 \subsubsection{Path separators}
1894
1895 The Win32 API understands both \path|/| and \path|\| characters as
1896 PATH separators. But the command interpreters do not! So whenever a
1897 path name is used programmatically, you can use both separators, and
1898 even mix them up in the same path name. But on the command line, you
1899 must type \path|\| as path separator. The reason is compatibility:
1900 the command processor used the \path|/| to introduce arguments to
1901 commands.
1902
1903 All this to say: do not be surprised to read path names written using
1904 the Unix convention; \fpTeX{} is a port of \Webc, and aims to be compatible
1905 across platforms. For this reason, all the configuration files that
1906 need to specify path names use the Unix convention.
1907
1908 \subsubsection{File systems}
1909 \label{sec:clusters}
1910
1911 The worse feature of Win9x with regard to \TeX{} is probably the
1912 so-called FAT file system. \TeX{} uses many many small files, with
1913 size around 1kb -- 3kb. The FAT file system is old, and predates by
1914 far the multi-gigabytes hard disks we have today. It means it can't
1915 manage efficiently the 30000 \TeX{} files found on the \CD{}. The FAT
1916 file system will allocate a minimum of 32kb for \emph{any} file on a
1917 huge partition. It means that \TeX{} will use much more disk space
1918 than it actually needs.
1919
1920 The other, more modern, file systems available -- namely FAT32 and
1921 NTFS -- do not have this drawback. They manage clusters of 4kb
1922 only\footnote{You can lower the limit to 512 bytes on NTFS}.
1923
1924 \subsubsection{How to add some directory to your PATH}
1925
1926 There are pairs of variables and values which behave much like global
1927 variables inside your programs. The set of those variables is called the
1928 environment. Each program is initialized with a copy of the
1929 environment when it is run. It can request and change the
1930 value of any variable. The changes happen in the copy of the
1931 environment, and is not at all propagated to the other running
1932 programs.
1933
1934 Your PATH is a special environment variable used to search for
1935 programs you want to run.
1936 There is a different procedure to change it for Win9x, WinME and NT/2K/XP:
1937
1938 \begin{description}
1939 \item[Windows 95/98] Edit your \path|autoexec.bat|. In this file should be a line
1940 starting with \texttt{PATH=} and followed by a list of directories separated
1941 by \path|;|. Please add the directory with the executables in this line.
1942 After this, this line could look as follows:
1943 \begin{verbatim}
1944 PATH=c:\windows;c:\windows\system;c:\"Program Files"\TeXLive\bin\win32
1945 \end{verbatim}
1946 \item[Windows ME] You need to run the special program
1947 \path|c:\windows\system\msconfig.exe| to be able to change any
1948 environment variable. From this program, select the `Environment'
1949 tab, and then add or modify the variable you want. You will be asked to reboot the
1950 machine upon any change.
1951 \item[Windows NT/2K/XP]
1952 Click left on \texttt{Start --> Settings --> Control Panel}. Now the window
1953 with the control panel icons opens. Double click on System. The
1954 System Properties window opens. Click on the tab
1955 \textsf{Environment} or look for a button named `Environment
1956 Variables' among the dialog boxes. Now
1957 you can change the environment variables for your user account. Note:
1958 There are also displayed the environment settings for the system.
1959 Normally, you can't change the system variables unless you have
1960 administrator rights on your machine. If you want to change the \texttt{PATH}
1961 for all users, you will have to contact your system administrator or
1962 be the system administrator yourself--in the later case you should
1963 know what you are doing.
1964
1965 If there is already a \texttt{PATH} setting for your user account,
1966 left click on \texttt{PATH}. In the field \textsf{Variable} appears
1967 \texttt{PATH} while the field Value shows the current setting of
1968 \texttt{PATH} as a list of directories separated by \path|;|. Add
1969 the directory where the executables are located (e.g.
1970 \path|c:\Program Files\TeXLive\bin\win32|). If there isn't a \texttt{PATH} variable
1971 for your user account, simply click in the field Variable and type
1972 in \texttt{PATH}, click in the field \textsf{Value}
1973 and type in the directory with the executables. Important: Click on
1974 the \textsf{Apply} button before clicking \textsf{Ok}, otherwise the
1975 changes to \texttt{PATH} won't apply to your system. Be careful when
1976 changing the environment settings.
1977 \end{description}
1978
1979 The best way to be sure that a variable has been properly set is to
1980 open a console and type:
1981 \begin{verbatim}
1982 set VARIABLE
1983 \end{verbatim}
1984 which should return the corresponding value.
1985
1986 \subsubsection{\TeX{} engines}
1987
1988 If you have a look at the \Webc{} documentation, you will read that all
1989 the various \TeX{} derived programs use the same base engine. For
1990 example, \path|tex.exe| and \path|latex.exe| are exact copies of the
1991 same program, but each one will use a different format file, based on
1992 its calling name.
1993
1994 Under Unix, this feature is implemented through \emph{symbolic
1995 links}. It saves up a bit of disk space, because some engines are
1996 used with many different format files.
1997
1998 The Win32 API does not know about file links. So to save up almost
1999 the same amount of memory, all the \TeX{} base engines have been put
2000 in DLLs (\emph{Dynamic Linked Library}). This means that you will have
2001 the following layout:
2002 \begin{alltt}
2003 13/05/2002 17:06 3 584 latex.exe
2004 13/05/2002 17:06 266 240 tex.dll
2005 13/05/2002 17:06 3 584 tex.exe
2006 \end{alltt}
2007 and the \path|latex.exe| file is nothing but a rough copy of
2008 \path|tex.exe| using the same core \path|tex.dll|.
2009 The same trick has been used for the \path|mktex*.exe| family of programs which are
2010 linked to the \path|mktex.dll| library.
2011
2012 In fact, a generic tool called \path|lnexe.exe| is provided to build the
2013 equivalent of Unix hard links for executable files only under Win32.
2014
2015 \subsection{In case of problems}
2016 \label{sec:troubleshooting}
2017
2018 \subsubsection{What to do if \texttt{latex} does not
2019 find your files?}
2020
2021 \begin{itemize}
2022 \item \cmdname{kpsewhich} is the tool of choice to debug any
2023 problem. Unfortunately, kpsewhich outputs debug information to
2024 stderr, and the Windows console does not know how to redirect stderr
2025 to a file\footnote{Well, NT and Win2k consoles know how to do
2026 that. But the trick will work for any console.}.
2027 For diagnostic purposes you can temporarily set an
2028 environment variable (in DOS box):
2029 \begin{verbatim}
2030 SET KPATHSEA_DEBUG_OUTPUT=err.log
2031 \end{verbatim}
2032 You can also set the debug level:
2033 \begin{verbatim}
2034 SET KPATHSEA_DEBUG=-1
2035 \end{verbatim}
2036
2037 If you want to redirect stderr to stdout, which is not possible under
2038 either W9x or NT/2K/XP, then just do:
2039 \begin{verbatim}
2040 SET KPATHSEA_DEBUG_OUTPUT=con:
2041 \end{verbatim}
2042 This way you can capture both stdout and stderr in the same file.
2043
2044 \item Assuming the installation has been done in \path|c:/Program Files/TeXLive|, check
2045 the following values: \\
2046 {\small
2047 \begin{tabular}{ll}
2048 \path|kpsewhich -expand-path $SELFAUTOPARENT| & \path|c:/Program Files/TeXLive| \\
2049 \path|kpsewhich -expand-path $TEXMF| & \path|c:/Program Files/TeXLive/texmf| \\
2050 \path|kpsewhich -expand-path $TEXMFCNF| &
2051 \path|.;c:/Program Files/TeXLive/texmf/web2c;| \\
2052 & \path|c:/Program Files/TeXLive/bin/win32;| \\
2053 & \path|c:/Program Files/TeXLive/bin;| \\
2054 & \path|c:/Program Files/TeXLive| \\
2055 \path|kpsewhich -expand-var $TEXINPUTS| & \path|.;c:/Program Files/TeXLive/texmf/tex//|
2056 \end{tabular}
2057 }
2058 \item If you have other \TeX{}-related values already set in your
2059 environment, please, remove them. They are overriding the ones in
2060 texmf.cnf.
2061 \item Check the values from:\\
2062 {\small
2063 \begin{tabular}{ll}
2064 \texttt{kpsewhich cmr10.tfm} & \path|c:/Program Files/TeXLive/texmf/fonts/tfm/public/cm/cmr10.tfm|\\
2065 \texttt{kpsewhich latex.fmt}& \path|c:/Program Files/TeXLive/texmf/web2c/latex.fmt|
2066 \end{tabular}
2067 }
2068 \item At this point, if everything is correct, \path|tex.exe| and
2069 co. should work. If it is not the case, you will need to play with
2070 the \path|-debug=n| option from \path|kpsewhich|, and check back all
2071 the values. Try to identify and report the problem.
2072 \end{itemize}
2073
2074 \subsubsection{What to do if your setup still does not work as expected?}
2075
2076 There are several questions to ask about:
2077 \begin{enumerate}
2078 \item Is \file{tex.exe} on my \path|PATH|?
2079 \item Is the \path|TEXMFCNF| variable correctly set to
2080 \path|c:/Program Files/TeXLive/texmf-var/web2c| (default value)?
2081 \item Are there any errors in the log file generated by the
2082 \file{TeXSetup.exe} program? Errors are flagged with the sequence
2083 \path|Error|.
2084 % \item If everything seems correct up there, then you need to read the
2085 % documentation in \path|texmf/doc/fptex/fptex.pdf| or
2086 % \path|texmf/doc/html/fptex/fptex.html| for a more detailed procedure
2087 % (available on your hard disk or on the \CD{}).
2088 \item One can also go to \url{http://www.tug.org/tex-live.html} and
2089 check for any bug fix.
2090 \item The Windows distribution on the \CD{} is no more no less than
2091 the \fpTeX{} distribution, so you can also go to the Web pages at
2092 \url{http://www.fptex.org}, or consider subscribing to the \fpTeX{}
2093 mailing-list by consulting
2094 \url{http://www.tug.org/mailman/listinfo/fptex} .
2095 \end{enumerate}
2096
2097
2098 The \TeXLive{} software is complex and made of more than 250 programs
2099 and around 40000 files from various sources. It is quite difficult to
2100 predict all possible causes for problems. Nevertheless, we will do our
2101 best to help you in every case.
2102
2103
2104 \subsection{Compiling the source files}
2105
2106 You have the whole set of source files, comprised for
2107 Windows in the \path|source/source.tar.bz2| archive available on the
2108 \CD{}. To be able to compile the whole distribution for Windows, you
2109 will need:
2110 \begin{itemize}
2111 \item Windows 2K/XP
2112 \item Microsoft Visual Studio .Net
2113 \item a set of Unix tools (\texttt{sed},
2114 \texttt{grep}, \texttt{gawk}, etc.) and also Perl, Flex and Bison,
2115 \item to adjust the paths in the
2116 \path|win32/make/common.mak| file according to your installation
2117 \item adjust the paths in the Perl script file
2118 \path|win32/perl/build.pl|,
2119 \item run the compilation from the \path|win32/| directory using this
2120 command:
2121 \begin{verbatim}
2122 c:\texlive\source\win32>perl ./perl/build.pl --install --log=install.log
2123 \end{verbatim}
2124 \end{itemize}
2125
2126 There is a lot of work to do to make this process easier and cleaner.
2127
2128 \subsection{Where to get more information?}
2129
2130 The Win32 \TeX{} distribution on the \CD{} is also known as
2131 \fpTeX. Only the packaging differs, but \fpTeX{} is no more no less
2132 than the current \TeXLive\ release for Windows.
2133
2134 The \fpTeX home on the Web is at:\\
2135 \url{http://www.fptex.org/}
2136
2137 The current \fpTeX release is available from any
2138 \href{http://www.ctan.org}{CTAN} %(see also the section
2139 %\ref{sec:ctan})
2140 site in the directory~:\\
2141 \noindent\url{ftp://ctan.tug.org/tex-archive/systems/win32/fptex/}.
2142
2143 The main ftp site for \fpTeX\ is \url{ftp://ftp.dante.de/pub/fptex/} from
2144 where beta versions of \fpTeX\ and additionnal tools are available.
2145 This main site is (partially) mirrored daily by the CTAN backbones in their
2146 \path|systems/win32/fptex| directory.
2147
2148 % You can reach me at my email address:
2149 % \url{mailto:[email protected]}.
2150
2151 The \TeX{} Users Group is kindly hosting a mailing-list dedicated to
2152 \fpTeX. This is a very low volume one. It is used for announcements,
2153 bugs reports or as well to discuss about improvements or various users
2154 problems. To subscribe, read the page at
2155 \url{http://www.tug.org/mailman/listinfo/fptex}. The mailing list
2156 address is \EmailURL{[email protected]}.
2157
2158 \section{Building on a new Unix platform}
2159 If you have a platform for which we have not provided binary sources,
2160 you will need to compile \TeX{} and friends from scratch. This is not
2161 as hard as it sounds. What you need is all in the directory
2162 \texttt{source} on the \CD{}.
2163
2164 You should first install the support tree from the \TeXLive{} \CD{} (do
2165 a basic install, with no system binaries chosen).
2166
2167 \subsection{Prerequisites}
2168 You will need about 100 megabytes of disk space to compile all of
2169 \TeX{} and its support programs. You'll also need an \acro{ANSI} C
2170 compiler, a \cmdname{make} utility, a lexical scanner, and a parser
2171 generator. The \acro{GNU} utilities (\cmdname{gcc}, \acro{GNU}
2172 \cmdname{make}, \cmdname{m4}, \cmdname{flex}, \cmdname{bison}) are the
2173 most widely tested on different platforms. \cmdname{gcc}-2.7.*
2174 \cmdname{flex}-2.4.7 and \acro{GNU}\,\cmdname{make}-3.72.1 or newer
2175 should work well. You may be able to work with other C compilers and
2176 \cmdname{make} programs, but you will need a good understanding of
2177 building Unix programs to sort out problems. The command
2178 \texttt{uname} must return a sensible value.
2179
2180
2181
2182 \subsection{Configuration}
2183 First, unpack the source from the compressed
2184 \texttt{tar} file in the directory \dirname{source} to your disk and change
2185 directory to where you placed it. Decide where the `root' of the
2186 installation will be, e.g.\ \path|/usr/local| or
2187 \path|/usr/local/TeX|. Obviously you should use the same location
2188 that you specified when you installed the support tree.
2189
2190 Now, start the build process by running \textsf{configure} with
2191 a command-line like
2192 \begin{alltt}
2193 >> \Ucom{./configure -prefix=/usr/local/TeX}
2194 \end{alltt}
2195
2196 The `prefix' directory is the one where you installed the support
2197 tree; the directory layout that will be used is as follows (where
2198 \$TEXDIR stands for the directory you chose):
2199
2200 \noindent
2201 \begin{tabular}{>{\ttfamily}ll@{}}
2202 \dirname{$TEXDIR/man} & Unix manual pages\\
2203 \dirname{$TEXDIR/share/texmf} & main tree with fonts,\\
2204 & \qquad macros, etc\\
2205 \dirname{$TEXDIR/info} & \acro{GNU} style info manuals\\
2206 \dirname{$TEXDIR/bin/$PLATFORM} & binaries\\
2207 \end{tabular}
2208 %$
2209
2210 You can omit the use of `\dirname{share/}' part for the
2211 \dirname{texmf} directory if you want, as
2212 \dirname{$TEXDIR/share/texmf} and \dirname{$TEXDIR/texmf} are
2213 auto-detected by configure. If you choose something different, you
2214 have to specify that directory with the \verb|--datadir| option of
2215 \textsf{configure}.
2216
2217
2218 If you want to leave out the \dirname{$PLATFORM} directory level
2219 (i.e.\ put the binaries directly into \dirname{$TEXDIR/bin}), specify
2220 the \verb|--disable-multiplatform| option for \textsf{configure}.
2221
2222
2223 Have a look at the output of \texttt{./configure --help} for more
2224 options you can use (such as omitting optional packages such as \OMEGA\
2225 or \eTeX).
2226
2227 \subsection{Running \textsf{make}}
2228 Make sure the shell variable \texttt{noclobber} is not set, and
2229 then type
2230 \begin{alltt}
2231 >> \Ucom{make world}
2232 \end{alltt}
2233 and relax\ldots.
2234
2235 It could also be useful to log all the output, e.g.\ by
2236 typing
2237 \begin{alltt}
2238 >> \Ucom{sh -c "make world >world.log 2>\&1" \&}
2239 \end{alltt}
2240 Before you think that everything is ok, please check the log file for
2241 errors (\acro{GNU} \cmdname{make} always uses the string
2242 ``\texttt{Error:}'' whenever a command returns an error code) and
2243 check if all binaries are built:
2244 \begin{alltt}
2245 >> \Ucom{cd /usr/local/TeX/bin/i686-pc-linux-gnu}
2246 >> \Ucom{ls | wc}
2247 \end{alltt}
2248 The result should be 209.
2249
2250 If you need special privileges for \texttt{make install}, you can
2251 run two \cmdname{make} jobs in separate runs:
2252 \begin{alltt}
2253 >> \Ucom{make all}
2254 >> \Ucom{su}
2255 >> \Ucom{make install strip}
2256 \end{alltt}
2257
2258 \subsection{Final configuration steps}
2259 Set up your \envname{PATH} to include the directory containing the
2260 just-installed binaries (e.g.\
2261 \dirname{/usr/local/TeX/bin/mips-sgi-irix6.5}); similarly,
2262 \envname{MANPATH} and \envname{INFOPATH} to include the relevant newly
2263 installed subdirectories, i.e.\ \dirname{$TEXDIR/man} and
2264 \dirname{$TEXDIR/info}.
2265
2266 The program \textsf{texconfig} allows you to set the defaults for
2267 hyphenation, paper size, print command, \MF{} mode, etc. You can
2268 run this command interactively and see what options it offers, or type
2269 \begin{alltt}
2270 >> \Ucom{texconfig help}
2271 \end{alltt}
2272
2273 For example, if you are not using A4 format paper, you can make
2274 `lettersize' the default using:
2275 \begin{alltt}
2276 >> \Ucom{texconfig dvips paper letter}
2277 >> \Ucom{texconfig xdvi paper us}
2278 \end{alltt}
2279
2280 \section{A user's guide to the \protect\Webc{} system}
2281
2282 %--------------------------------------------------------
2283
2284 \Webc{} contains a set of \TeX-related programs, i.e., \TeX{} itself,
2285 \MF{}, \MP, \BibTeX{}, etc. The original implementation was by Tomas
2286 Rokicki who, in 1987, developed a first \TeX{}-to-C system adapting
2287 change files under Unix, which were primarily the work of Howard
2288 Trickey and Pavel Curtis. Tim Morgan became the maintainer of the
2289 system, and during this period the name changed to Web-to-C\@. In
2290 1990, Karl Berry took over the work, assisted by dozens of additional
2291 contributors, and in 1997 he handed the baton to Olaf Weber. The
2292 latest result is \Webc{} Version 7.3, which was released in March
2293 1999. Our version has some updates for the forthcoming new release,
2294 and identifies itself as 7.3.7
2295
2296 The \Webc{} 7.3 system runs on Unix, Windows 3.1, 9x/ME/\acro{NT}/\acro{2K}/\acro{XP},
2297 \acro{DOS}, and other operating systems. It uses Knuth's
2298 original sources for \TeX{} and other basic programs written in \web{}
2299 and translates them into C source code. Moreover, the system offers a
2300 large set of macros and functions developed to augment the original
2301 \TeX{} software. The core \TeX{} family components are:
2302
2303 \begin{description}
2304 \renewcommand{\makelabel}[1]{\descriptionlabel{\mdseries\cmdname{#1}}}
2305 \item[bibtex] Maintaining bibliographies.
2306 \item[dmp] \cmdname{troff} to MPX (\MP{} pictures).
2307 \item[dvicopy] Produces modified copy of \dvi{} file.
2308 \item[dvitomp] \dvi{} to MPX (MetaPost pictures).
2309 \item[dvitype] \dvi{} to human-readable text.
2310 \item[gftodvi] Generic font proofsheets.
2311 \item[gftopk] Generic to packed fonts.
2312 \item[gftype] GF to human-readable text.
2313 \item[makempx] \MP{} label typesetting.
2314 \item[mf] Creating typeface families.
2315 \item[mft] Prettyprinting \MF{} source.
2316 \item[mpost] Creating technical diagrams.
2317 \item[mpto] MetaPost label extraction.
2318 \item[newer] Compare modification times.
2319 \item[patgen] Creating hyphenation patterns.
2320 \item[pktogf] Packed to generic fonts.
2321 \item[pktype] PK to human-readable text.
2322 \item[pltotf] Property list to TFM.
2323 \item[pooltype] Display \web{} pool files.
2324 \item[tangle] \web{} to Pascal.
2325 \item[tex] Typesetting.
2326 \item[tftopl] TFM to property list.
2327 \item[vftovp] Virtual font to virtual property list
2328 \item[vptovf] Virtual property list to virtual font.
2329 \item[weave] \web{} to \TeX.
2330 \end{description}
2331 \noindent The precise functions and syntax of these programs are described in
2332 the documentation of the individual packages or of \Webc{} itself.
2333 However, knowing a few principles governing the whole family of
2334 programs will help you to benefit optimally from your \Webc{}
2335 installation.
2336
2337 All programs honor the standard \acro{GNU} options:
2338 \begin{description}
2339 \item[\texttt{-{}-help\ \ \ }] print basic usage summary.
2340 \item[\texttt{-{}-verbose}] print detailed progress report.
2341 \item[\texttt{-{}-version}] print version information, then exit.
2342 \end{description}
2343
2344 For locating files the \Webc{} programs use the path searching library
2345 \KPS{}. This library uses a combination of environment variables and a
2346 few configuration files to optimize searching the \TeX{} directory
2347 tree. \Webc{} can handle more than one directory tree
2348 simultaneously, which is useful if one wants to maintain \TeX's
2349 standard distribution and local extensions in two distinct trees. To
2350 speed up file searches the root of each tree has a file \file{ls-R},
2351 containing an entry showing the name and relative pathname for all
2352 files ``hanging'' under that root.
2353
2354 \subsection{\protect\KPS\ path searching}
2355
2356 Let us first describe the generic path searching mechanism of the \KPS{}
2357 library.
2358
2359 We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list
2360 of \emph{path elements}, which are basically directory names. A
2361 search path can come from (a combination of) many sources. To look up
2362 a file \samp{my-file} along a path \samp{.:/dir}, \KPS{} checks each
2363 element of the path in turn: first \file{./my-file}, then
2364 \file{/dir/my-file}, returning the first match (or possibly all
2365 matches).
2366
2367 In order to adapt optimally to all operating systems' conventions, on
2368 non-Unix systems \KPS{} can use filename separators different from
2369 ``colon'' (\samp{:}) and ``slash'' (\samp{/}).
2370
2371 To check a particular path element \var{p}, \KPS{} first checks if a
2372 prebuilt database (see ``Filename data\-base'' on
2373 page~\pageref{Filename-database}) applies to \var{p}, i.e., if the database
2374 is in a directory that is a prefix of \var{p}. If so, the path
2375 specification is matched against the contents of the database.
2376
2377 If the database does not exist, or does not apply to this path
2378 element, or contains no matches, the filesystem is searched (if this
2379 was not forbidden by a specification starting with \samp{!!}\ and if
2380 the file being searched for must exist). \KPS{} constructs the list
2381 of directories that correspond to this path element, and then checks
2382 in each for the file being sought.
2383
2384 The ``file must exist'' condition comes into play with \samp{.vf} files and
2385 input files read by \TeX's \cs{openin} command. Such files may not
2386 exist (e.g., \file{cmr10.vf}), and so it would be wrong to search the
2387 disk for them. Therefore, if you fail to update \file{ls-R} when you
2388 install a new \samp{.vf} file, it will never be found.
2389 Each path element is checked in turn: first the database, then the
2390 disk. If a match is found, the search stops and the result is
2391 returned.
2392
2393 Although the simplest and most common path element is a directory
2394 name, \KPS{} supports additional features in search paths: layered
2395 default values, environment variable names, config file values, users'
2396 home directories, and recursive subdirectory searching. Thus, we say
2397 that \KPS{} \emph{expands} a path element, meaning it transforms all
2398 the specifications into basic directory name or names. This is
2399 described in the following sections in the same order as it takes
2400 place.
2401
2402 Note that if the filename being searched for is absolute or explicitly
2403 relative, i.e., starts with \samp{/} or \samp{./} or \samp{../},
2404 \KPS{} simply checks if that file exists.
2405
2406 \ifSingleColumn
2407 \else
2408 \begin{figure*}
2409 \verbatiminput{../examples/ex5.tex}
2410 \setlength{\abovecaptionskip}{0pt}
2411 \caption{An illustrative configuration file sample}
2412 \label{fig:config-sample}
2413 \end{figure*}
2414 \fi
2415
2416 \subsubsection{Path sources}
2417 \label{Path-sources}
2418
2419 A search path can come from many sources. In the order in which
2420 \KPS{} uses them:
2421
2422 \begin{enumerate}
2423 \item
2424 A user-set environment variable, for instance, \envname{TEXINPUTS}\@.
2425 Environment variables with a period and a program name appended
2426 override; e.g., if \samp{latex} is the name of the program being run,
2427 then \envname{TEXINPUTS.latex} will override \envname{TEXINPUTS}.
2428 \item
2429 A program-specific configuration file, for exam\-ple, a line
2430 ``\texttt{S /a:/b}'' in \cmdname{dvips}'s \file{config.ps}.
2431 \item A \KPS{} configuration file \file{texmf.cnf}, containing a line like
2432 \samp{TEXINPUTS=/c:/d} (see below).
2433 \item The compile-time default.
2434 \end{enumerate}
2435 \noindent You can see each of these values for a given
2436 search path by using the debugging options (see ``Debugging actions''
2437 on page~\pageref{Debugging}).
2438
2439 \subsubsection{Config files}
2440
2441 \tolerance=3500
2442 \KPS{} reads \emph{runtime configuration files} named \file{texmf.cnf}
2443 for search path and other definitions. The search path used to look
2444 for these files is named \envname{TEXMFCNF} (by default such a file lives
2445 in the \file{texmf/web2c} subdirectory). \emph{All}
2446 \file{texmf.cnf} files in the search path will be read and definitions
2447 in earlier files override those in later files. Thus, with a search
2448 path of \verb|.:$TEXMF|, values from \file{./texmf.cnf} override those
2449 from \verb|$TEXMF/texmf.cnf|.
2450
2451 \tolerance=1500
2452
2453 While reading the description of the format of the file
2454 \file{texmf.cnf} below, please also refer to
2455 appendix~\ref{app:texmf.cnf}, starting on
2456 page~\pageref{app:texmf.cnf}, which lists the \file{texmf.cnf} file on
2457 the \CD.
2458
2459 \begin{itemize}
2460 \item
2461 Comments start with ``\texttt{\%}'' and continue to the end of the line.
2462 \item
2463 Blank lines are ignored.
2464 \item
2465 A \bs{} at the end of a line acts as a continuation character,
2466 i.e., the next line is appended. Whitespace at the beginning of
2467 continuation lines is not ignored.
2468 \item
2469 Each remaining line has the form:
2470 \begin{alltt}
2471 \emph{variable}[.\emph{progname}] [=] \emph{value}
2472 \end{alltt}%
2473 where the \samp{=} and surrounding whitespace are optional.
2474 \item
2475 The ``\texttt{\var{variable}}'' name may contain any character other
2476 than whitespace, \samp{=}, or \samp{.}, but sticking to
2477 \samp{A-Za-z\_} is safest.
2478 \item
2479 If ``\texttt{.\var{progname}}'' is present, the definition only
2480 applies if the program that is running is named
2481 \texttt{\var{progname}} or \texttt{\var{progname}.exe}. This allows
2482 different flavors of \TeX{} to have different search paths, for
2483 example.
2484 \item ``\texttt{\var{value}}'' may contain any characters except
2485 ``\texttt{\%}'' and \samp{@}. The
2486 ``\texttt{\$\var{var}.\var{prog}}'' feature is not available on the
2487 right-hand side; instead, you must use an additional variable. A
2488 \samp{;}\ in ``\texttt{\var{value}}'' is translated to \samp{:}\ if
2489 running under Unix; this is useful to be able to have a single
2490 \file{texmf.cnf} for Unix, MSDOS and Windows systems.
2491 \item
2492 All definitions are read before anything is expanded, so
2493 variables can be referenced before they are defined.
2494 \end{itemize}
2495 A configuration file fragment illustrating most of these points is
2496 \ifSingleColumn
2497 shown below:
2498
2499 \verbatiminput{../examples/ex5.tex}
2500 \else
2501 shown in Figure~\ref{fig:config-sample}.
2502 \fi
2503
2504 \subsubsection{Path expansion}
2505 \label{Path-expansion}
2506
2507
2508 \KPS{} recognizes certain special characters and constructions in
2509 search paths, similar to those available in Unix shells. As a
2510 general example, the complex path,
2511 \verb+~$USER/{foo,bar}//baz+, expands to all subdirectories under
2512 directories \file{foo} and \file{bar} in \texttt{\$USER}'s home
2513 directory that contain a directory or file \file{baz}. These
2514 expansions are explained in the sections below.
2515 %$
2516 \subsubsection{Default expansion}
2517 \label{Default-expansion}
2518
2519 \tolerance=2500
2520 If the highest-priority search path (see ``Path sources'' on
2521 page~\pageref{Path-sources}) contains an \emph{extra colon} (i.e.,
2522 leading, trailing, or doubled), \KPS{} inserts at that point the
2523 next-highest-prio\-rity search path that is defined. If that inserted
2524 path has an extra colon, the same happens with the next highest. For
2525 example, given an environment variable setting
2526
2527 \tolerance=1500
2528
2529 \begin{alltt}
2530 >> \Ucom{setenv TEXINPUTS /home/karl:}
2531 \end{alltt}
2532 and a \code{TEXINPUTS} value from \file{texmf.cnf} of
2533
2534 \begin{alltt}
2535 .:\$TEXMF//tex
2536 \end{alltt}
2537 then the final value used for searching will be:
2538
2539 \begin{alltt}
2540 /home/karl:.:\$TEXMF//tex
2541 \end{alltt}
2542
2543 Since it would be useless to insert the default value in more than one
2544 place, \KPS{} changes only one extra \samp{:}\ and leaves any others in
2545 place: it checks first for a leading \samp{:}, then a trailing
2546 \samp{:}, then a doubled \samp{:}.
2547
2548 \subsubsection{Brace expansion}
2549
2550 A useful feature is brace expansion, which means that, for instance,
2551 \verb+v{a,b}w+ expands to \verb+vaw:vbw+. Nesting is allowed.
2552 This can be used to implement multiple \TeX{} hierarchies, by
2553 assigning a brace list to \code{\$TEXMF}.
2554 For example, in \file{texmf.cnf}, you find
2555 the following definition:
2556 \begin{verbatim}
2557 TEXMF = {$HOMETEXMF,$TEXMFLOCAL,!!$VARTEXMF,!!$TEXMFMAIN}
2558 \end{verbatim}
2559 Using this you can then write something like
2560 \begin{verbatim}
2561 TEXINPUTS = .;$TEXMF/tex//
2562 \end{verbatim}
2563 %$
2564 which means that, after looking in the current directory, the
2565 \code{\$HOMETEXMF/tex}, \code{\$TEXMFLOCAL/tex}, \code{\$VARTEXMF/tex}
2566 and \code{\$TEXMFMAIN/tex} trees \emph{only}) will be searched (the
2567 last two use using \file{ls-R} data base files). It is a convenient
2568 way for running two parallel \TeX{} structures, one ``frozen'' (on a
2569 \CD, for instance) and the other being continuously updated with new
2570 versions as they become available. By using the \code{\$TEXMF}
2571 variable in all definitions, one is sure to always search the
2572 up-to-date tree first.
2573
2574 \subsubsection{Subdirectory expansion}
2575 \label{Subdirectory-expansion}
2576
2577 Two or more consecutive slashes in a path element following a directory
2578 \var{d} is replaced by all subdirectories of \var{d}: first those
2579 subdirectories directly under \var{d}, then the subsubdirectories under
2580 those, and so on. At each level, the order in which the directories are
2581 searched is \emph{unspecified}.
2582
2583 If you specify any filename components after the \samp{//}, only
2584 subdirectories with matching components are included. For example,
2585 \samp{/a//b} expands into directories \file{/a/1/b}, \file{/a/2/b},
2586 \file{/a/1/1/b}, and so on, but not \file{/a/b/c} or \file{/a/1}.
2587
2588 Multiple \samp{//} constructs in a path are possible, but
2589 \samp{//} at the beginning of a path is ignored.
2590
2591 \subsubsection{List of special characters and their meaning: a summary}
2592
2593 The following list summarises the meaning of special characters
2594 in \KPS{} configuration files.
2595
2596 \newcommand{\CODE}[1]{\makebox[2.2em][l]{\code{#1}}}
2597 \begin{description}
2598 \item[\CODE{:}] Separator in path specification; at the beginning or
2599 the end of a path it substitutes the default path expansion.
2600 \item[\CODE{;}] Separator on non-Unix systems (acts like \code{:}).
2601 \item[\CODE{\$}] Variable expansion.
2602 \item[\CODE{\string~}] Represents the user's home directory.
2603 \item[\CODE{\char`\{\dots\char`\}}] Brace expansion, e.g.,
2604 \verb+a{1,2}b+ will become \verb+a1b:a2b+.
2605 \item[\CODE{//}] Subdirectory expansion (can occur anywhere in
2606 a path, except at its beginning).
2607 \item[\CODE{\%}] Start of comment.
2608 \item[\CODE{\bs}] Continuation character (allows multi-line entries).
2609 \item[\CODE{!!}] Search \emph{only} database to locate file, \emph{do
2610 not} search the disk.
2611 \end{description}
2612
2613
2614 \subsection{Filename databases}
2615 \label{Filename-database}
2616
2617
2618 \KPS{} goes to some lengths to minimize disk accesses for searches.
2619 Nevertheless, at installations with enough directories, searching each
2620 possible directory for a given file can take an excessively long time
2621 (this is especially true if many hundreds of font directories have to
2622 be traversed.) Therefore, \KPS{} can use an externally-built
2623 ``database'' file named \file{ls-R} that maps files to directories,
2624 thus avoiding the need to exhaustively search the disk.
2625
2626 A second database file \file{aliases} allows you to give additional
2627 names to the files listed in \file{ls-R}. This can be helpful to
2628 adapt to DOS-like ``8.3'' filename conventions in source files.
2629
2630 \subsubsection{The filename database}
2631 \label{ls-R}
2632
2633 As explained above, the name of the main filename database must be
2634 \file{ls-R}. You can put one at the root of each \TeX{} hierarchy in
2635 your installation that you wish to be searched (\code{\$TEXMF} by
2636 default); most sites have only one hierarchy. \KPS{} looks for
2637 \file{ls-R} files along the \code{TEXMFDBS} path.
2638
2639 The recommended way to create and maintain \samp{ls-R} is to run the
2640 \code{mktexlsr} script included with the distribution. It is invoked
2641 by the various \samp{mktex}\dots\ scripts. In principle, this script
2642 just runs the command
2643 \begin{alltt}
2644 cd \var{/your/texmf/root} && ls -LAR ./ >ls-R
2645 \end{alltt}
2646 presuming your system's \code{ls} produces the right output format
2647 (\acro{GNU}'s \code{ls} is all right). To ensure that the database is always
2648 up to date, it is easiest to rebuild it regularly via \code{cron}, so
2649 that for changes in the installed files\Dash perhaps after installing or
2650 updating a \LaTeX{} package\Dash the file \file{ls-R} is automatically
2651 updated.
2652
2653 If a file is not found in the database, by default \KPS{} goes ahead
2654 and searches the disk. If a particular path element begins with
2655 \samp{!!}, however, \emph{only} the database will be searched for that
2656 element, never the disk.
2657
2658
2659 \subsubsection{kpsewhich: Standalone path searching}
2660 \label{Invoking-kpsewhich}
2661
2662 The \texttt{kpsewhich} program exercises path searching independent of any
2663 particular application. This can be useful as a sort of \code{find}
2664 program to locate files in \TeX{} hierarchies (this is used heavily in
2665 the distributed \samp{mktex}\dots\ scripts).
2666
2667 \begin{alltt}
2668 >> \Ucom{kpsewhich \var{option}\dots{} \var{filename}\dots{}}
2669 \end{alltt}
2670 The options specified in ``\texttt{\var{option}}'' can start with either \samp{-}
2671 or \samp{-{}-}, and any unambiguous abbreviation is accepted.
2672
2673 \KPS{} looks up each non-option argument on the command line as a
2674 filename, and returns the first file found. There is no option to
2675 return all the files with a particular name (you can run the Unix
2676 \samp{find} utility for that).
2677
2678 The more important options are described next.
2679
2680 \begin{description}
2681 \item[\texttt{-{}-dpi=\var{num}}]\mbox{}
2682 Set the resolution to ``\texttt{\var{num}}''; this only affects \samp{gf}
2683 and \samp{pk} lookups. \samp{-D} is a synonym, for compatibility
2684 with \cmdname{dvips}. Default is 600.
2685 \item[\texttt{-{}-format=\var{name}}]\mbox{}\\
2686 Set the format for lookup to ``\texttt{\var{name}}''. By default, the
2687 format is guessed from the filename. For formats which do not have
2688 an associated unambiguous suffix, such as \MP{} support files and
2689 \cmdname{dvips} configuration files, you have to specify the name as
2690 found in the first column of Table~\ref{TABKpathsea}, which lists
2691 currently recognized names, a description,
2692 associated environment variables%,
2693 \footnote{You can find definitions for these environment variables
2694 in the file \file{texmf.cnf} (page~\pageref{app:texmf.cnf})}, and
2695 possible file extensions.
2696 \end{description}
2697
2698
2699 \def\KpathKey#1#2#3#4#5{% name, number, description, variables,
2700 % suffixes
2701 \SetRowColor#1 & #3 & #4 & #5\\}
2702 \def\HEAD#1{\multicolumn{1}{l}{\emph{#1}}}
2703 %
2704 \begin{small}
2705 % a footnoterule immediately under a bottom-of-page rule looks dead
2706 % silly, so we suppress it
2707 \renewcommand\footnoterule{\relax}
2708 %
2709 \begin{longtable}{@{}%
2710 >{\ttfamily}P{.16\textwidth}% Col.1
2711 P{.3\textwidth}% Col 2
2712 >{\ttfamily\footnotesize}P{.29\textwidth}% Col 3
2713 >{\ttfamily}P{.14\textwidth}% Col 4
2714 @{}}
2715 \caption{Kpathsea file types}\label{TABKpathsea}\\
2716 \emph{Name} & \HEAD{Description} & \HEAD{Variables}
2717 & \HEAD{Suffixes}\\
2718 \hline
2719 \endfirsthead
2720 \multicolumn{3}{l}{Kpathsea file types \emph{continued}}\\
2721 \emph{Name} & \HEAD{Description} & \HEAD{Variables}
2722 & \HEAD{Suffixes}\\
2723 \hline
2724 \noalign{\vspace{2pt}}
2725 \endhead
2726 \mbox{}\\
2727 \hline
2728 \endfoot
2729 \KpathKey
2730 {afm}
2731 {4}
2732 {Adobe font metrics}
2733 {AFMFONTS}
2734 {.afm}
2735 \KpathKey
2736 {base}
2737 {5}
2738 {Metafont memory dump}
2739 {MFBASES, TEXMFINI}
2740 {.base}
2741 \KpathKey
2742 {bib}
2743 {6}
2744 {\BibTeX{} bibliography source}
2745 {BIBINPUTS, TEXBIB}
2746 {.bib}
2747 \KpathKey
2748 {}
2749 {2}
2750 {bitmap fonts}
2751 {GLYPHFONTS, TEXFONTS}
2752 {}
2753 \KpathKey
2754 {bst}
2755 {7}
2756 {\BibTeX{} style files}
2757 {BSTINPUTS}
2758 {.bst}
2759 \KpathKey
2760 {cnf}
2761 {8}
2762 {Runtime configuration files}
2763 {TEXMFCNF}
2764 {.cnf}
2765 \KpathKey
2766 {dvips config}
2767 {34}
2768 {\textsf{dvips} configuration files, e.g., \file{config.ps}
2769 and \file{psfonts.map}}
2770 {TEXCONFIG}
2771 {.map}
2772 \KpathKey
2773 {fmt}
2774 {10}
2775 {\TeX{} memory dump}
2776 {TEXFORMATS, TEXMFINI}
2777 {.fmt, .efmt, .efm}
2778 \KpathKey
2779 {gf}
2780 {0}
2781 {generic font bitmap}
2782 {GFFONTS}
2783 {.gf}
2784 \KpathKey
2785 {graphic/figure}
2786 {25}
2787 {Encapsulated PostScript figures}
2788 {TEXPICTS, TEXINPUTS}
2789 {.eps, .epsi}
2790 \KpathKey
2791 {ist}
2792 {35}
2793 {\textsf{makeindex} style files}
2794 {TEXINDEXSTYLE, INDEXSTYLE}
2795 {.ist}
2796 \KpathKey
2797 {ls-R}
2798 {9}
2799 {Filename databases}
2800 {TEXMFDBS}
2801 {}
2802 \KpathKey
2803 {map}
2804 {11}
2805 {Fontmaps}
2806 {TEXFONTMAPS}
2807 {.map}
2808 \KpathKey
2809 {mem}
2810 {12}
2811 {MetaPost memory dump}
2812 {MPMEMS, TEXMFINI}
2813 {.mem}
2814 \KpathKey
2815 {mf}
2816 {13}
2817 {Metafont source}
2818 {MFINPUTS}
2819 {.mf}
2820 \KpathKey
2821 {mfpool}
2822 {14}
2823 {Metafont program strings}
2824 {MFPOOL, TEXMFINI}
2825 {.pool}
2826 \KpathKey
2827 {mft}
2828 {15}
2829 {MFT style file}
2830 {MFTINPUTS}
2831 {.mft}
2832 \KpathKey
2833 {}
2834 {41}
2835 {miscellaneous fonts}
2836 {MISCFONTS}
2837 {}
2838 \KpathKey
2839 {mp}
2840 {16}
2841 {MetaPost source}
2842 {MPINPUTS}
2843 {.mp}
2844 \KpathKey
2845 {mppool}
2846 {17}
2847 {MetaPost program strings}
2848 {MPPOOL, TEXMFINI}
2849 {.pool}
2850 \KpathKey
2851 {MetaPost support}
2852 {18}
2853 {MetaPost support files, used by DMP}
2854 {MPSUPPORT}
2855 {}
2856 \KpathKey
2857 {ocp}
2858 {19}
2859 {\OMEGA{} compiled process files}
2860 {OCPINPUTS}
2861 {.ocp}
2862 \KpathKey
2863 {ofm}
2864 {20}
2865 {\OMEGA{} font metrics}
2866 {OFMFONTS, TEXFONTS}
2867 {.ofm, .tfm}
2868 \KpathKey
2869 {opl}
2870 {21}
2871 {\OMEGA{} property lists}
2872 {OPLFONTS, TEXFONTS}
2873 {.opl}
2874 \KpathKey
2875 {otp}
2876 {22}
2877 {\OMEGA{} translation process files}
2878 {OTPINPUTS}
2879 {.otp}
2880 \KpathKey
2881 {ovf}
2882 {23}
2883 {\OMEGA{} virtual fonts}
2884 {OVFFONTS, TEXFONTS}
2885 {.ovf}
2886 \KpathKey
2887 {ovp}
2888 {24}
2889 {\OMEGA{} virtual property lists}
2890 {OVPFONTS, TEXFONTS}
2891 {.ovp}
2892 \KpathKey
2893 {pk}
2894 {1}
2895 {packed bitmap fonts}
2896 {\emph{program}FONTS \textrm{(\texttt{\emph{program}} being
2897 \textsmaller{\cmdname{XDVI}},
2898 etc.)}, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS}
2899 {.pk}
2900 \KpathKey
2901 {PostScript header}
2902 {30}
2903 {downloadable PostScript}
2904 {TEXPSHEADERS, PSHEADERS}
2905 {.pro, .enc}
2906 \KpathKey
2907 {tex}
2908 {26}
2909 {\TeX{} source}
2910 {TEXINPUTS}
2911 {.tex, .cls, .sty, .clo, .def}
2912 \KpathKey
2913 {TeX system documentation}
2914 {27}
2915 {Documentation files for the \TeX{} system}
2916 {TEXDOCS}
2917 {}
2918 \KpathKey
2919 {TeX system sources}
2920 {29}
2921 {Source files for the \TeX{} system}
2922 {TEXSOURCES}
2923 {}
2924 \KpathKey
2925 {texpool}
2926 {28}
2927 {\TeX{} program strings}
2928 {TEXPOOL, TEXMFINI}
2929 {.pool}
2930 \KpathKey
2931 {tfm}
2932 {3}
2933 {\TeX{} font metrics}
2934 {TFMFONTS, TEXFONTS}
2935 {.tfm}
2936 \KpathKey
2937 {Troff fonts}
2938 {31}
2939 {Troff fonts, used by DMP}
2940 {TRFONTS}
2941 {}
2942 \KpathKey
2943 {truetype fonts}
2944 {36}
2945 {TrueType outline fonts}
2946 {TTFONTS}
2947 {.ttf, .ttc}
2948 \KpathKey
2949 {type1 fonts}
2950 {32}
2951 {Type 1 PostScript outline fonts}
2952 {T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS}
2953 {.pfa, .pfb}
2954 \KpathKey
2955 {type42 fonts}
2956 {37}
2957 {Type 42 PostScript outline fonts}
2958 {T42FONTS}
2959 {}
2960 \KpathKey
2961 {vf}
2962 {33}
2963 {virtual fonts}
2964 {VFFONTS, TEXFONTS}
2965 {.vf}
2966 \KpathKey
2967 {web2c files}
2968 {38}
2969 {\Webc{} support files}
2970 {WEB2C}
2971 {}
2972 \KpathKey
2973 {other text files}
2974 {39}
2975 {text files used by `\textsf{foo}'}
2976 {FOOINPUTS}
2977 {}
2978 \KpathKey
2979 {other binary files}
2980 {40}
2981 {binary files used by `\textsf{foo}'}
2982 {FOOINPUTS}
2983 {}
2984 \end{longtable}
2985 \end{small}
2986
2987
2988 \begin{multicols}{2}
2989
2990 \begin{description}
2991 \item[] The last two entries in Table~\ref{TABKpathsea} are special
2992 cases, where the paths and environment variables depend on the name
2993 of the program: the variable name is constructed by converting the
2994 program name to upper case, and then appending \texttt{INPUTS}.
2995
2996 The environment variables are set by default in the configuration
2997 file \file{texmf.cnf}. It is only when you want to override one or
2998 more of the values specified in that file that you might want to set
2999 them explicitly in your execution environment.
3000
3001 Note that the \samp{-{}-format} and \samp{-{}-path} options are mutually
3002 exclusive.
3003 \item[\texttt{-{}-mode=\var{string}}]\mbox{}\\
3004 Set the mode name to ``\texttt{\var{string}}''; this only affects \samp{gf}
3005 and \samp{pk} lookups. No default: any mode will be found.
3006 \item[\texttt{-{}-must-exist}]\mbox{}\\
3007 Do everything possible to find the files, notably including
3008 searching the disk. By default, only the \file{ls-R} database is
3009 checked, in the interest of efficiency.
3010 \item[\texttt{-{}-path=\var{string}}]\mbox{}\\
3011 Search along the path ``\texttt{\var{string}}'' (colon-%
3012 separated as usual),
3013 instead of guessing the search path from the filename. \samp{//}
3014 and all the usual expansions are supported.
3015 The options \samp{-{}-path} and \samp{-{}-format} are mutually
3016 exclusive.
3017 \item[\texttt{-{}-progname=\var{name}}]\mbox{}\\
3018 Set the program name to ``\texttt{\var{name}}''.
3019 This can affect the search paths via the ``\texttt{.\var{prognam}}''
3020 feature in configuration files.
3021 The default is \samp{kpsewhich}.
3022 \item[\texttt{-{}-show-path=\var{name}}]\mbox{}\\
3023 shows the path used for file lookups of file type ``\texttt{\var{name}}''.
3024 Either a filename extension (\samp{.pk}, \samp{.vf}, etc.) or a
3025 name can be used, just as with \samp{-{}-format} option.
3026 \item[\texttt{-{}-debug=\var{num}}]\mbox{}\\
3027 sets the debugging options to ``\texttt{\var{num}}''.
3028 \end{description}
3029
3030
3031 \subsubsection{Examples of use}
3032 \label{SExamplesofuse}
3033
3034 Let us now have a look at \KPS{} in action.
3035
3036 \begin{alltt}
3037 >> \Ucom{kpsewhich article.cls}
3038 /usr/local/texmf/tex/latex/base/article.cls
3039 \end{alltt}
3040 We are looking for the file \file{article.cls}. Since the \samp{.cls}
3041 suffix is unambiguous we do not need to specify that we want to look for a
3042 file of type ``tex'' (\TeX{} source file directories). We find it in
3043 the subdirectory \file{tex/latex/base} below the \samp{TEXMF} root
3044 directory. Similarly, all of the following are found without problems
3045 thanks to their unambiguous suffix.
3046 \begin{alltt}
3047 >> \Ucom{kpsewhich array.sty}
3048 /usr/local/texmf/tex/latex/tools/array.sty
3049 >> \Ucom{kpsewhich latin1.def}
3050 /usr/local/texmf/tex/latex/base/latin1.def
3051 >> \Ucom{kpsewhich size10.clo}
3052 /usr/local/texmf/tex/latex/base/size10.clo
3053 >> \Ucom{kpsewhich small2e.tex}
3054 /usr/local/texmf/tex/latex/base/small2e.tex
3055 >> \Ucom{kpsewhich tugboat.bib}
3056 /usr/local/texmf/bibtex/bib/beebe/tugboat.bib
3057 \end{alltt}
3058
3059 The latter is a \BibTeX{} bibliography database for \textsl{TUGBoat} articles.
3060
3061 \begin{alltt}
3062 >> \Ucom{kpsewhich cmr10.pk}
3063 \end{alltt}
3064 Font bitmap glyph files of type \file{.pk} are used by display
3065 programs like \cmdname{dvips} and \cmdname{xdvi}. Nothing is returned in
3066 this case since there are no pre-generated Computer Modern \samp{.pk}
3067 files on our system (since we use the Type1 versions on the \CD{}).
3068 \begin{alltt}
3069 >> \Ucom{kpsewhich ecrm1000.pk}
3070 \ifSingleColumn /usr/local/texmf/fonts/pk/ljfour/jknappen/ec/ecrm1000.600pk
3071 \else
3072 /usr/local/texmf/fonts/pk/ljfour/jknappen/
3073 ... ec/ecrm1000.600pk
3074 \fi\end{alltt}
3075 For the extended Computer Modern files we had to generate \samp{.pk}
3076 files, and since the default \MF{} mode on our installation is
3077 \texttt{ljfour} with a base resolution of 600 dpi (dots per inch),
3078 this instantiation is returned.
3079 \begin{alltt}
3080 >> \Ucom{kpsewhich -dpi=300 ecrm1000.pk}
3081 \end{alltt}
3082 In this case, when specifying that we are interested in a resolution
3083 of 300dpi (\texttt{-dpi=300}) we see that no such font is available on
3084 the system. In fact, a program like \cmdname{dvips} or \cmdname{xdvi} would
3085 go off and actually build the \texttt{.pk} files at the required
3086 resolution using the script \cmdname{mktexpk}.
3087
3088 Next we turn our attention to \cmdname{dvips}'s header and configuration
3089 files. We first look at one of the commonly used files, the general
3090 prolog \file{tex.pro} for \TeX{} support, before turning our attention
3091 to the generic configuration file (\file{config.ps}) and the
3092 PostScript font map \file{psfonts.map}. As the \samp{.ps} suffix is
3093 ambiguous we have to specify explicitly which type we are considering
3094 (``\texttt{dvips config}'') for the file \texttt{config.ps}.
3095 \begin{alltt}
3096 >> \Ucom{kpsewhich tex.pro}
3097 /usr/local/texmf/dvips/base/tex.pro
3098 >> \Ucom{kpsewhich --format="dvips config" config.ps}
3099 /usr/local/texmf/config/config.ps
3100 >> \Ucom{kpsewhich psfonts.map}
3101 /usr/local/texmf/dvips/base/psfonts.map
3102 \end{alltt}
3103
3104 We now take a closer look at the URW Times PostScript support files.
3105 The name for these in Berry's font naming scheme is ``\texttt{utm}''.
3106 The first file we look at is the configuration file, which contains
3107 the name of the map file:
3108 \begin{alltt}
3109 >> \Ucom{kpsewhich --format="dvips config" config.utm}
3110 /usr/local/texmf/dvips/psnfss/config.utm
3111 \end{alltt}
3112 The contents of that file is
3113 \begin{alltt}
3114 p +utm.map
3115 \end{alltt}
3116 which points to the file \file{utm.map}, which we want to
3117 locate next.
3118 \begin{alltt}
3119 >> \Ucom{kpsewhich --format="dvips config" utm.map}
3120 /usr/local/texmf/dvips/psnfss/utm.map
3121 \end{alltt}
3122 This map file defines the file names of the Type1 PostScript fonts in
3123 the URW collection. Its contents look like (we only show part of the
3124 lines):
3125 \begin{alltt}
3126 utmb8r NimbusRomNo9L-Medi ... <utmb8a.pfb
3127 utmbi8r NimbusRomNo9L-MediItal... <utmbi8a.pfb
3128 utmr8r NimbusRomNo9L-Regu ... <utmr8a.pfb
3129 utmri8r NimbusRomNo9L-ReguItal... <utmri8a.pfb
3130 utmbo8r NimbusRomNo9L-Medi ... <utmb8a.pfb
3131 utmro8r NimbusRomNo9L-Regu ... <utmr8a.pfb
3132 \end{alltt}
3133 Let us, for instance, take the Times Regular instance
3134 \file{utmr8a.pfb} and find its position in the \file{texmf} directory
3135 tree by using a search for Type1 font files:
3136 \begin{alltt}
3137 >> \Ucom{kpsewhich utmr8a.pfb}
3138 \ifSingleColumn /usr/local/texmf/fonts/type1/urw/utm/utmr8a.pfb
3139 \else /usr/local/texmf/fonts/type1/
3140 ... urw/utm/utmr8a.pfb
3141 \fi\end{alltt}
3142
3143 It should be evident from these few examples how you can easily locate
3144 the whereabouts of a given file. This is especially important if you
3145 suspect that the wrong version of a file is picked up somehow, since
3146 \cmdname{kpsewhich} will show you the first file encountered.
3147
3148 \subsubsection{Debugging actions}
3149 \label{Debugging}
3150
3151 Sometimes it is necessary to investigate how a program resolves
3152 file references. To make this feasible in a convenient way \KPS{}
3153 offers various debug levels:
3154 \begin{itemize}
3155 \item[\texttt{\ 1}] \texttt{stat} calls (file tests). When running
3156 with an up-to-date \file{ls-R} database this should almost give no
3157 output.
3158 \item[\texttt{\ 2}] References to hash tables (like \file{ls-R}
3159 database, map files, configuration files).
3160 \item[\texttt{\ 4}] File open and close operations.
3161 \item[\texttt{\ 8}] General path information for file types
3162 searched by \KPS. This is useful to find out where a particular
3163 path for the file was defined.
3164 \item[\texttt{16}] Directory list for each path element (only relevant
3165 for searches on disk).
3166 \item[\texttt{32}] File searches.
3167 \end{itemize}
3168 A value of \texttt{-1} will set all the above options; in practice you
3169 will probably always use these levels if you need any debugging.
3170
3171 Similarly, with the \cmdname{dvips} program, by setting a
3172 combination of debug switches, one can follow in detail where files are being picked
3173 up from. Alternatively, when a file is not found, the debug trace
3174 shows in which directories the program looks for the given file, so
3175 that one can get an indication what the problem~is.
3176
3177 Generally speaking, as most programs call the \KPS{} library
3178 internally, one can select a debug option by using the
3179 \envname{KPATHSEA\_DEBUG} environment variable, and setting it to (a
3180 combination of) values as described in the above list.
3181
3182 (Note for Windows users: it is not easy to redirect
3183 all messages to a file in this system. For diagnostic purposes
3184 you can temporarily \texttt{SET KPATHSEA\_DEBUG\_OUTPUT=err.log}).
3185
3186 Let us consider, as an example, a small \LaTeX{} source file,
3187 \file{hello-world.tex}, which contains the following input.
3188 \begin{verbatim}
3189 \documentclass{article}
3190 \begin{document}
3191 Hello World!
3192 \end{document}
3193 \end{verbatim}
3194 This little file only uses the font \file{cmr10}, so let us look
3195 how \cmdname{dvips} prepares the PostScript file (we want to use the Type1
3196 version of the Computer Modern fonts, hence the option \texttt{-Pcms}).
3197 \begin{alltt}
3198 >> \Ucom{dvips -d4100 hello-world -Pcms -o}
3199 \end{alltt}
3200 In this case we have combined \cmdname{dvips}'s debug class 4 (font
3201 paths) with \KPS's path element expansion (see \cmdname{dvips} Reference
3202 Manual, \OnCD{texmf/doc/html/dvips/dvips_toc.html}).
3203 %\ifSingleColumn
3204 %We get something
3205 %like the following (we have rearranged the output for easier display):
3206 %\begin{alltt}\small
3207 %\input{../examples/ex6.tex}
3208 %\end{alltt}
3209 %\else
3210 The output (slightly rearranged) appears in
3211 Figure~\ref{fig:dvipsdbga}.
3212 \begin{figure*}[tp]
3213 \centering
3214 \input{../examples/ex6a.tex}
3215 \caption{Finding configuration files}\label{fig:dvipsdbga}
3216
3217 \bigskip
3218
3219 \input{../examples/ex6b.tex}
3220 \caption{Finding the prolog file}\label{fig:dvipsdbgb}
3221
3222 \bigskip
3223
3224 \input{../examples/ex6c.tex}
3225 \caption{Finding the font file}\label{fig:dvipsdbgc}
3226 \end{figure*}
3227 \cmdname{dvips} starts by locating its working files. First,
3228 \file{texmf.cnf} is found, which gives the definitions of the search
3229 paths for the other files, then the file database \file{ls-R} (to
3230 optimize file searching) and the file \file{aliases}, which makes it
3231 possible to declare several names (e.g., a short \acro{DOS}-like ``8.3'' and
3232 a more natural longer version) for the same file. Then \cmdname{dvips}
3233 goes on to find the generic configuration file \file{config.ps}
3234 before looking for the customization file \file{.dvipsrc} (which, in
3235 this case is \emph{not found}). Finally, \cmdname{dvips} locates the
3236 config file for the Computer Modern PostScript fonts \file{config.cms}
3237 (this was initiated with the \texttt{-Pcms} option on the \cmdname{dvips}
3238 command). This file contains the list of the ``map'' files which
3239 define the relation between the \TeX{}, PostScript and file system
3240 names of the fonts.
3241 \begin{alltt}
3242 >> \Ucom{more /usr/local/texmf/dvips/cms/config.cms}
3243 p +ams.map
3244 p +cms.map
3245 p +cmbkm.map
3246 p +amsbkm.map
3247 \end{alltt}
3248 \cmdname{dvips} thus goes on to find all these files, plus the generic
3249 map file \file{psfonts.map}, which is always loaded (it contains
3250 declarations for commonly used PostScript fonts; see the last part of
3251 Section \ref{SExamplesofuse} for more details about PostScript map
3252 file handling).
3253
3254 At this point \cmdname{dvips} identifies itself to the user\ldots
3255 \begin{alltt}\ifSingleColumn
3256 This is dvips 5.78 Copyright 1998 Radical Eye Software (www.radicaleye.com)
3257 \else\small{}This is dvips 5.78 Copyright 1998 Radical Eye...
3258 \fi\end{alltt}% decided to accept slight overrun in tub case
3259 \ifSingleColumn
3260 \ldots and then goes on to look for the prolog file \file{texc.pro},
3261 \begin{alltt}\small
3262 kdebug:start search(file=texc.pro, must\_exist=0, find\_all=0,
3263 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
3264 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
3265 kdebug:search(texc.pro) => /usr/local/texmf/dvips/base/texc.pro
3266 \end{alltt}
3267 \else
3268 then goes on to look for the prolog file \file{texc.pro} (see
3269 Figure~\ref{fig:dvipsdbgb}).
3270
3271 \fi
3272 After having found the file in question, \cmdname{dvips} outputs
3273 date and time, and informs us that it will generate the
3274 file \file{hello-world.ps}, then that it needs the font file
3275 \file{cmr10}, and that the latter is declared as ``resident'':
3276 \begin{alltt}\small
3277 TeX output 1998.02.26:1204' -> hello-world.ps
3278 Defining font () cmr10 at 10.0pt
3279 Font cmr10 <CMR10> is resident.
3280 \end{alltt}
3281 Now the search is on for the file \file{cmr10.tfm}, which is found,
3282 then a few more prolog files (not shown) are referenced, and finally
3283 the Type1 instance \file{cmr10.pfb} of the font is located and
3284 included in the output file (see last line).
3285 \begin{alltt}\small
3286 kdebug:start search(file=cmr10.tfm, must\_exist=1, find\_all=0,
3287 path=.:~/tex/fonts/tfm//:!!/usr/local/texmf/fonts/tfm//:
3288 /var/tex/fonts/tfm//).
3289 kdebug:search(cmr10.tfm) => /usr/local/texmf/fonts/tfm/public/cm/cmr10.tfm
3290 kdebug:start search(file=texps.pro, must\_exist=0, find\_all=0,
3291 ...
3292 <texps.pro>
3293 kdebug:start search(file=cmr10.pfb, must\_exist=0, find\_all=0,
3294 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
3295 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
3296 kdebug:search(cmr10.pfb) => /usr/local/texmf/fonts/type1/public/cm/cmr10.pfb
3297 <cmr10.pfb>[1]
3298 \end{alltt}
3299
3300 \subsection{Runtime options}
3301
3302 Another of the nice features of \Webc{} is its possibility to
3303 control a number of memory parameters (in particular, array sizes) via
3304 the runtime file \file{texmf.cnf} read by \KPS{}. The listing of
3305 \file{texmf.cnf} is shown in Appendix~\ref{app:texmf.cnf}, starting on
3306 page~\pageref{app:texmf.cnf}; the settings of all parameters can be
3307 found in Part 3 of that file. The more important control variables are:
3308 \begin{description}
3309 \item[\texttt{main\_memory}]
3310 Total words of memory available, for
3311 \TeX{}, \MF{} and \MP. You must make a new format file for each
3312 different setting. For instance, you could generate a ``huge''
3313 version of \TeX{}, and call the format file \texttt{hugetex.fmt}.
3314 Using the standard way of specifying the program name used by \KPS{},
3315 the particular value of the \texttt{main\_memory} variable will then
3316 be read from \file{texmf.cnf} (compare the generic value
3317 and the ``huge'' one instantiated by \texttt{hugetex},
3318 etc.).
3319 \item[\texttt{extra\_mem\_bot}]
3320 Extra space for ``large'' \TeX{} data structures:
3321 boxes, glue, breakpoints, etc. Especially useful if you use
3322 \PiCTeX{}.
3323 \item[\texttt{font\_mem\_size}]
3324 Number of words for font information available for \TeX. This
3325 is more or less the total size of all TFM files read.
3326 \item[\texttt{hash\_extra}]
3327 Additional space for the hash table of control sequence names.
3328 Approximately 10,000 control sequences can be stored in the main
3329 hash table; if you have a large book with numerous cross-references,
3330 this might not be enough. You can see that both the
3331 \cmdname{hugetex} and \cmdname{pdflatex} program invocations ask for
3332 an extra 15,000 control sequences (the default value of
3333 \texttt{hash\_extra} is zero).
3334 \end{description}
3335 Of course, this facility is no substitute for truly dynamic arrays and
3336 memory allocation, but since this is extremely difficult to implement
3337 in present \TeX, these runtime parameters provide a practical compromise
3338 allowing some flexibility.
3339
3340 %--------------------------------------------------------
3341
3342
3343 \section{Acknowledgements}\label{sec:acknowl}
3344 This edition of TeXLive is edited by Sebastian Rahtz, with the
3345 major contributors being Fabrice Popineau, who has worked away
3346 unceasingly at the Win32 part of the package (especially the setup!)
3347 and contributed in many different ways with ideas, advice and code;
3348 and Staszek Wawrykiewicz, who provided great checking feedback, and
3349 co-ordinated the Polish contributions. Kaja Christiansen performed a
3350 vital role in endless recompilations on assorted Unix platforms, and
3351 Robin Laakso coordinated production for TUG. Vladimir Volovich
3352 did great work on cleaning the source and making other improvements,
3353 while Gerben Wierda did all the work for MacOSX.
3354
3355 We are very grateful for past and present help from
3356 \begin{itemize}
3357 \item The German-speaking \TeX{} Users (DANTE e.V.), who provided a machine
3358 on which the master of the CD-ROM is developed and maintained; and Rainer
3359 Sch\"opf and Reinhard Zierke who look after it;
3360 \item The Perforce company, for providing a free copy of their
3361 excellent change management system, which we have used to
3362 manage the CD-ROM
3363 contents;
3364 \item Karl Berry, who provided the original \Webc{} distribution, and
3365 has continued to give invaluable advice, encouragement, and help;
3366 \item Mimi Burbank, who arranged access
3367 at the Florida State University School of Computational Science
3368 and Information Technology
3369 to a slew of different
3370 computers to compile \TeX{} on, and acted as an essential guinea-pig
3371 whenever asked;
3372 \item Kaja Christiansen, who provided essential feedback, compilation, and
3373 documentation preparation;
3374 \item Thomas Esser, without whose marvellous \teTeX{} package this
3375 \CD{} would certainly not exist, and whose continual help makes it a
3376 better product;
3377 \item Michel Goossens, who co-authored the documentation;
3378 \item Eitan Gurari, whose \TeX4ht was used to create the \HTML{}
3379 version of this documentation, and who worked tirelessly to improve
3380 it at short notice;
3381 \item Art Ogawa and Pat Monohon, who coordinated releases for TUG;
3382 \item Petr Olsak, who coordinated and checked all the Czech/Slovak
3383 material very carefully;
3384 \item Olaf Weber, for his patient assembly and maintenance of Web2c;
3385 \item Graham Williams, on whose work the catalogue of packages depends.
3386 \end{itemize}
3387
3388 Gerhard Wilhelms, Volker Schaa, Fabrice Popineau, Janka
3389 Chleb\'\i{}kov\'a, Staszek Wawrykiewicz, Erik Frambach, and Ulrik
3390 Vieth kindly translated documentation at various times into their
3391 respective languages, checked other documentation, and provided very
3392 welcome feedback.
3393
3394
3395 \section{History}
3396
3397 This \CD{} distribution is a joint effort by many \TeX{} Users
3398 Groups, including those from Germany, the Netherlands, the UK, France,
3399 the Czech Republic/Slovakia, India, Poland and Russia, as well as
3400 the international TUG.
3401 Discussion began in late 1993 when the Dutch \TeX{} Users Group was
3402 starting work on its 4All\TeX{} \CD{} for \acro{MS-DOS} users, and it was
3403 hoped at that time to issue a single, rational, \CD{} for all
3404 systems. This was far too ambitious a target, but it did spawn not
3405 only the very successful 4All\TeX{} \CD{}, but also the \acro{TUG}
3406 Technical Council working group on a \emph{\TeX{} Directory
3407 Structure}, which specified how to create consistent and manageable
3408 collections of \TeX{} support files. The final draft of the \TDS{} was
3409 published in the December 1995 issue of \textsl{TUGboat}, and it was clear from
3410 an early stage that one desirable product would be a model structure
3411 on \CD{}. The \CD{} you now have is a very direct result of the
3412 working group's deliberations. It was also clear that the success of
3413 the 4All\TeX{} \CD{} showed that Unix users would benefit from a
3414 similarly easy system, and this is the other main strand of \TeXLive.
3415
3416 We undertook to make a new Unix-based \TDS{} \CD{} in the autumn of
3417 1995, and quickly identified Thomas Esser's \teTeX{} as the ideal
3418 setup, as it already had multi-platform support and was built with
3419 portability across file systems in mind. Thomas agreed to help, and
3420 work began seriously at the start of 1996. The first edition was
3421 released in May 1996. At the start of 1997, Karl Berry completed a
3422 major new release of his \Webc{} package, which included nearly all
3423 the features which Thomas Esser had added in \teTeX, and we decided to
3424 base the 2nd edition of the \CD{} on the standard \Webc, with the
3425 addition of \teTeX's \texttt{texconfig} script. The 3rd edition of the
3426 \CD{} was based on a major revision of \Webc, 7.2, by Olaf Weber; at the
3427 same time, a new revision of \teTeX was being made,
3428 and \TeXLive{} shares almost all of its features. The 4th edition
3429 followed the same pattern, using a new version of te\TeX, and a new
3430 release of \Webc{} (7.3). The system now included a complete Windows setup.
3431
3432 For the 5th edition (March 2000) many parts of the \CD{} were revised
3433 and checked, updating hundreds of packages. Package details were
3434 stored in XML files. But the major change for \TeX\ Live 5 was that
3435 all non-free software was removed. Everything on this \CD{} should be
3436 compatible with the Debian Free Software Guidelines
3437 (\url{http://www.debian.org/intro/free}); we have done our best to
3438 check the license conditions of all packages, but we would very much
3439 appreciate hearing of any mistakes.
3440
3441 The 6th edition (July 2001) had a lot material updated. The major
3442 change was a new install concept: the user could select a more exact set
3443 of needed collections. Language-related collections were completely
3444 reorganized, so selecting any of them installs not only macros, fonts,
3445 etc., but also prepares an appropriate \texttt{language.dat}.
3446
3447 The 7th edition of 2002 had as a major addition a setup
3448 for MacOSX, and the usual myriad of updates to all sorts
3449 of packages and programs. An important goal was integration
3450 of the source back with teTeX, to correct the drift apart
3451 in versions 5 and 6.
3452
3453 \section{Future versions}
3454
3455 \emph{This \CD{} is not a perfect product!} We plan to re-issue it
3456 once a year, and would like to provide more help material, more
3457 utilities, more installation programs, and (of course) an
3458 ever-improved and checked tree of macros and fonts. This work is all
3459 done by hard-pressed volunteers in their limited spare time, and a
3460 great deal remains to be done. If you can help, don't hesitate to put
3461 your name forward!
3462
3463 Corrections, suggestions and additions for future revisions
3464 should be sent to:\hfill\null
3465 \begin{quote}
3466 Sebastian Rahtz\\
3467 {}7 Stratfield Road\\
3468 Oxford OX2 7BG\\
3469 United Kingdom\\
3470 \EmailURL{[email protected]}
3471 \end{quote}
3472
3473
3474 Updates, notes, and suggestions will be made available on \CTAN{}
3475 in \path|info/texlive|. A \acro{WWW} page for
3476 information and ordering details is at
3477 \url{http://www.tug.org/tex-live.html}.
3478
3479 \end{multicols}
3480
3481 \Section{The texmf.cnf file}
3482 \label{app:texmf.cnf}
3483 \begin{small}
3484 \listinginput{1}{../examples/texmf.cnf}
3485 \end{small}
3486
3487 \end{document}
3488
3489
3490
3491 Notes on Nicolle Zellner's problems:
3492 ------------------------------------
3493 - autoexec.bat gave error, ``too many parameters''.
3494 fix: in setvars.bat file, put "" around %PATH% to take care of spaces.
3495
3496 - ``out of environment space'' when rebooting meant that autoexec.bat was
3497 not executing properly-- path and texmfhome variable were not being set.
3498 fix: put in config.sys file the line: shell=c:\command.com /e:1024 /p
3499 (and reboot probably)
3500
3501 [Note: alternative advice written by Pat:
3502 The environment space is an area of memory in which the OS stores
3503 variables such as path. To increase the memory size do the following:
3504
3505 Open a MS-DOS window. Click on the Properties icon (looks like a hand
3506 holding a sheet of paper). Click on the Memory tab in the Properties
3507 window. Change the value under Initial Environment: to 4096. Apply the
3508 properties. Click OK on the warning about needing to restart your computer.
3509 The new environment memory will be in effect after the reboot.]
3510
3511 - windvi did not retain settings.
3512 fix: in setvars.bat file, add command: set Home=c:\Home and also create
3513 the directory c:\Home.
3514 copy windvi.cnf to c:\Home\
3515 reboot
3516
3517 -ispell doesn't work (can't write to c:\tmp, can't create dictionary)
3518 In addition to the the c:\Home addition above, create the folder:
3519 d:\tmp\ (d: is where the files are that she is using.)
3520 Now ispell should work from the command line.
3521 Still can't get it to work from within \cmdname{WinShell}. (change cmd line to %c.tex,
3522 it was reading the project main file)
3523
3524
3525
3526 Notes on installing WinEdt:
3527 ---------------------------
3528 If you choose to install WinEdt, you will be asked for a folder name: any
3529 folder name will do, as this is for temporary storage. An acceptable
3530 choice is \verb+C:\Winedt+. Click \textbf{unzip}, then \textbf{OK},
3531 and finally \textbf{Close}.
3532 ---
3533
3534 later, to complete WinEdt installation:
3535
3536 Run "winedt5.exe" and complete the setup procedure.
3537
3538 Get from ftp://ftp.dante.de/pub/fptex/supplementary/
3539 30/08/2000 20:17 70 844 winedt5-cnf.zip
3540 10/09/2000 10:43 839 086 winedt5-patch4.zip
3541
3542 then unpack (use unzip or winzip with subdir creation enabled, NOT pkunzkip)
3543 "winedt5-patch4.zip" inside the "c:\program files\winedt" directory
3544 then at last unpack "winedt5-cnf.zip".
3545
3546 When this is done, go inside the 'Options->Configurations' menu,
3547 choose the "fpTeX Direct" option.
3548
3549 If windvi previewer doesn't work, go to options->menu setup-> accessories
3550 and change the Menu Setup so the call for DVI Preview is analogous to
3551 the call for Dvips-- i.e., don't use "DVIVIEW" in the command line,
3552 but rather fptex-bin and dviwin.exe.
3553
3554