Debian Codegraph @

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

raw
1 % $Id: live-2004.tex 1513 2006-02-13 00:22:35Z karl $
2 % TeX Live documentation. Originally written by Sebastian Rahtz and
3 % Michel Goossens, now maintained by Karl Berry and others.
4 % Public domain.
5 %
6 \documentclass{article}
7 \let\tldocenglish=1 % for live4ht.cfg
8 \usepackage{tex-live}
9 \begin{document}
10
11 \title{%
12 {\huge \textit{The \protect\TL{} Guide}\\\strut}
13 {\LARGE \textsf{\TK{} 2004}}
14 }
15
16 \author{Sebastian Rahtz \& Karl Berry, editors \\[3mm]
17 \url{http://tug.org/texlive/}
18 }
19
20 \date{November 2004}
21
22 \maketitle
23
24 \begin{multicols}{2}
25 \tableofcontents
26 \listoftables
27 \end{multicols}
28
29 \section{Introduction}
30 \label{sec:intro}
31
32 This document describes the main features of the \TL{} software
33 distribution\Dash a \TeX{} and \LaTeX{} distribution for Linux and other
34 Unix flavors, \MacOSX, and (32-bit) Windows systems. (Warning: it is
35 not especially useful for older Mac or \acro{MS-DOS} systems.)
36
37 \TL{} includes precompiled binaries for \TeX{}, \LaTeXe{}, \MF, \MP,
38 \BibTeX{} and many other programs; an extensive collection of macros,
39 fonts and documentation; and support for typesetting in many different
40 scripts from around the world. It is part of the even larger \TK{}
41 (briefly described below in section~\ref{sec:struct-tl},
42 \p.\pageref{sec:struct-tl}), a cooperative effort by the \TeX\ user
43 groups.
44
45 For newer versions of the packages included here, please check
46 \acro{CTAN}: \url{http://www.ctan.org}
47
48 For a brief summary of the major changes in this edition of \TL{},
49 see section~\ref{sec:history} (\p.\pageref{sec:history}).
50
51
52 \subsection{Basic usage of \protect\TL{}}
53 \label{sec:basic}
54
55 You can use \TL{} in three principal ways:
56
57 \begin{enumerate}
58
59 \item You can run \TL{} directly from the \DVD
60 (see section~\ref{sec:multiple-dist}, \p.\pageref{sec:multiple-dist}).
61 This takes almost no disk space, as you might expect, and gives you
62 immediate access to everything in \TL{}. Of course performance
63 will be worse than running on local disk, but you may well find it
64 acceptable.
65
66 \item You can install all or part of \TL{} to a local disk. This
67 is the most common use of \TL. You will need (approximately) a
68 minimum of 100 megabytes, 310 megabytes for a recommended system, and
69 730 megabytes for a full system.
70
71 \item You can integrate a particular package or collection into your
72 existing \TeX{} system, either a \TL{} system you installed
73 earlier, or a different system.
74
75 \end{enumerate}
76
77 \noindent All of these are described in detail in the \acro{OS}-specific
78 installation sections following, but here is a quick start:
79
80 \begin{itemize*}
81
82 \item The main installation script for Unix and \MacOSX{} is
83 \texttt{install-tl.sh};
84
85 \item The single package installation script is \texttt{install-pkg.sh}.
86
87 \item Unfortunately, this version of \TL{} has no Windows installer, due
88 to technical difficulties. See section~\ref{sec:win-install} below
89 for more information.
90
91 \end{itemize*}
92
93
94 \subsection{Getting help}
95 \label{sec:help}
96
97 The \TeX{} community is both active and friendly, and virtually all
98 serious questions end up getting answered. However, the support is
99 informal, done by volunteers and casual readers, so it's especially
100 important that you do your homework before asking. (If you prefer
101 guaranteed commercial support, you can forego \TL{} completely and
102 purchase a vendor's system; \url{http://tug.org/interest.html#vendors}
103 has a list.)
104
105 Here is a list of resources, approximately in the order we recommend
106 using them:
107
108 \begin{description}
109 \item [Getting Started] If you are new to \TeX, the web page
110 \url{http://tug.org/begin.html} gives a brief introduction to the system.
111
112 \item [\TeX{} \acro{FAQ}] The \TeX{} \acro{FAQ} is a huge compendium of
113 answers to all sorts of questions, from the most basic to the most
114 arcane. It is included on \TL{} in \OnCD{texmf-doc/doc/english/FAQ-en}, and is
115 available on the Internet through \url{http://www.tex.ac.uk/faq}.
116 Please check here first.
117
118 \item [\TeX{} Catalogue] If you are looking for a specific package,
119 font, program, etc., the \TeX{} Catalogue is the place to look. It is a
120 huge list of all \TeX{}-related items. See
121 \OnCD{texmf-doc/doc/english/catalogue}, or
122 \url{http://www.ctan.org/tex-archive/help/Catalogue}.
123
124 \item [\TeX{} Web Resources] The web page
125 \url{http://tug.org/interest.html} has many \TeX{}-related links, in
126 particular for numerous books, manuals, and articles on all aspects of
127 the system.
128
129 \item [support archives] The two principal support forums are the
130 Usenet newsgroup \url{news:comp.text.tex} and the mailing list
131 \email{[email protected]}. Their archives have years of past
132 questions and answers for your searching pleasure, via
133 \url{http://groups.google.com/groups?group=comp.text.tex} and
134 \url{http://tug.org/mail-archives/texhax}, respectively. And a general web
135 search, for example on \url{http://google.com}, never hurts.
136
137 \item [asking questions] If you cannot find an answer, you can post to
138 \dirname{comp.text.tex} through Google or your newsreader, or to
139 \email{[email protected]} through email. But before you post,
140 \emph{please} read this \acro{FAQ} entry for advice on asking questions
141 in such a way that you're most likely to get an answer:
142 \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=askquestion}.
143
144 \item [\TL{} support] If you want to report a bug or have
145 suggestions or comments on the \TL{} distribution, installation, or
146 documentation, the mailing list is \email{[email protected]}. However,
147 if your question is about how to use a particular program included in
148 \TL{}, you are better off writing to that program's maintainer or
149 mailing list.
150
151 \end{description}
152
153 The other side of the coin is helping others who have questions. Both
154 \dirname{comp.text.tex} and \code{texhax} are open to anyone, so feel
155 free to join, start reading, and help out where you can. Welcome to
156 \TeX{}!
157
158
159 % don't use \TL so the \uppercase in the headline works. Also so
160 % tex4ht ends up with the right TeX. Likewise the \protect's.
161 \section{Structure of \protect\TeX\protect\ Live}
162 \label{sec:struct-tl}
163
164 This section describes the structure and contents of \TL{} and the
165 \TK{} of which it is a part.
166
167 \subsection{Multiple distributions: \protect\pkgname{live},
168 \protect\pkgname{inst},
169 \protect\pkgname{protext}}
170 \label{sec:multiple-dist}
171
172 Space limitations of \acro{CD-ROM} format have forced us to divide
173 \TK{} into several distributions, as follows.
174
175 \begin{description}
176
177 \item [live] A complete system on \acro{DVD}; it is too large
178 for \acro{CD}. It can be run live or installed to disk. It also
179 includes a snapshot of the \CTAN{} repository, entirely independent of
180 \TL{}, as well as assorted other packages in a
181 \texttt{texmf-extra} directory.
182
183 Unfortunately, this release of \TL{} does not include a Windows
184 installer, due to technical difficulties. (We hope there will be an
185 installer again in a few months.) Therefore, when the \DVD{} is mounted
186 on Windows, the setup program offers to start the \pkgname{protext}
187 installation (see below), and also mentions \CTAN{} and \TL{}, which are
188 in subdirectories of the top level of the \DVD{}.
189
190 \CTAN{} and \texttt{texmf-extra} do not follow the same copying
191 conditions as \TL{}, so be careful when redistributing or
192 modifying.
193
194 \item [inst(allable)] A complete system on \CD; in order to make this fit,
195 the packages and programs are compressed. Therefore, it is not possible
196 to run \TeX\ directly from the installable \CD, you have to install it
197 to disk (hence its name). Furthermore, it can only be installed on Unix
198 (including Linux, \MacOSX, etc.)\ systems, not Windows, although a set
199 of experimental Windows binaries is included (for sharing across
200 platforms). Installation is described in subsequent sections.
201
202 \item [protext] An enhancement of the \MIKTEX\ system, for Windows.
203 \ProTeXt\ adds a few extra tools to \MIKTEX, and simplifies
204 installation. It is entirely independent of \TL{}, and has its own
205 installation instructions. It can be run live, or installed to disk.
206 The \ProTeXt\ home page is \url{http://tug.org/protext}.
207
208 \ProTeXt\ is provided as both the top level of the \pkgname{live} \DVD\
209 and on its own \CD\ (for those who cannot use the \DVD).
210
211 \end{description}
212
213 \noindent You can tell which type of distribution you're in by looking
214 for a \texttt{00\var{type}.TL} file at the top of the \TL{} directory.
215 This file also contains the \TL{} release date.
216
217 Naturally, each user group chooses what to distribute, at its own
218 discretion. (\acro{TUG} is sending all three discs above to all of its
219 members.)
220
221
222 \subsection{Top level directories}
223 \label{sec:tld}
224
225 Here is a brief listing and description of the top level directories in
226 the \TL{} distribution. This has changed considerably in 2004: the
227 single \texttt{texmf} tree has been split into several smaller trees.
228
229 Also, on the \pkgname{live} \DVD, the entire \TL{} hierarchy is in a
230 subdirectory \dirname{texlive2004}, not at the top level of the disc.
231
232 \smallskip
233 \begingroup
234 \renewcommand{\arraystretch}{1.3} % open up interrow spacing
235 \begin{tabular}{>{\ttfamily}lp{.78\hsize}}
236 bin & The \TeX{} system programs, arranged by platform. \\
237 MacOSX & Supporting software for \MacOSX (see
238 section~\ref{sec:mac-install}, \p.\pageref{sec:mac-install}). \\
239 source & The source of all programs, including the main \Webc{}
240 \TeX{} and \MF{} distributions. These are stored in a
241 \cmdname{bzip2}-compressed tar archive. \\
242 support & Assorted auxiliary packages and programs. These are
243 \emph{not} installed automatically. This includes
244 assorted editors and \TeX\ shells. \\
245 texmf & Tree for the programs, along with their support files and
246 documentation. Does not include \TeX\ formats and packages. \\
247 texmf-dist & The main tree of formats and packages. \\
248 texmf-doc & Tree for self-contained pure documentation, with no other
249 installed files.\hfil\break Arranged by language. \\
250 texmf-var & Tree for files automatically generated and stored. \\
251 xemtex & The \cmdname{XEmacs} editor and other support programs for
252 Windows.
253 These programs generally come pre-installed on Unix systems, or are
254 at least easy to compile. \\
255 \end{tabular}
256 \endgroup
257
258 \smallskip
259
260 In addition to the directories above, the installation scripts and
261 \filename{README} files (in various languages) are at the top level of
262 the distribution.
263
264 The (new) \dirname{texmf-doc} directory contains only documentation, but
265 it does not contain all the documentation. The documentation for the
266 programs (manuals, man pages, Info files) is in \dirname{texmf/doc},
267 since the programs are in \dirname{texmf}. Similarly, the documentation
268 for \TeX\ packages and formats is in \dirname{texmf-dist/doc}. You can
269 use the \cmdname{texdoc} or \cmdname{texdoctk} programs to find any
270 documentation wherever it's located. The comprehensive links in the
271 top-level file \OnCD{doc.html} may also be helpful.
272
273
274 \subsection{Extensions to \protect\TeX}
275 \label{sec:tex-extensions}
276
277 \TL{} contains several extended versions of \TeX:
278
279 \begin{description}
280
281 \item [\eTeX] adds a small but powerful set of new primitives
282 \label{text:etex} (related to macro expansion, character scanning,
283 classes of marks, additional debugging features, and more) and the
284 \TeXXeT{} extensions for bidirectional typesetting. In default mode,
285 \eTeX{} is 100\% compatible with ordinary \TeX. See
286 \OnCD{texmf-dist/doc/etex/base/etex_man.pdf}.
287
288 \item [pdf\TeX] writes Acrobat \acro{PDF} format as well as \dvi{}. The
289 \LaTeX{} \pkgname{hyperref} package has an option `\optname{pdftex}'
290 which turns on all the program features. See
291 \OnCD{texmf/doc/pdftex/manual/pdftex-a.pdf} (A4 paper) or
292 \OnCD{texmf/doc/pdftex/manual/pdftex-l.pdf} (letter paper), and
293 \OnCD{texmf/doc/pdftex/examples/example.tex}.
294
295 \item [pdfe\TeX] combines the pdf\TeX\ and \eTeX\ extensions. This is
296 the default program for all formats except plain \TeX.
297 See above for documentation.
298
299 \item [\OMEGA\ (Omega)] is based on Unicode (16-bit characters), thus
300 supports working with almost all the world's scripts simultaneously. It
301 also supports so-called `\OMEGA{} Translation Processes' (\acro{OTP}s),
302 for performing complex transformations on arbitrary input. See
303 \OnCD{texmf-dist/doc/omega/base/doc-1.8.tex} (not completely up-to-date).
304
305 \item [Aleph] combines the \OMEGA\ and \eTeX\ extensions.
306 See \OnCD{texmf-dist/doc/aleph/base} for some minimal documentation.
307
308 \end{description}
309
310
311 \subsection{Other notable programs in \protect\TL}
312
313 Here are a few other commonly-used programs included in \TL{}:
314
315 \begin{cmddescription}
316
317 \item [bibtex] bibliography support.
318
319 \item [makeindex] index support.
320
321 \item [dvips] convert \dvi{} to \PS{}.
322
323 \item [xdvi] \dvi{} previewer for the X Window System.
324
325 \item [dvilj] \dvi{} drive for the HP LaserJet family.
326
327 \item [dv2dt, dt2dv] convert \dvi{} to/from plain text.
328
329 \item [dviconcat, dviselect] cut and paste pages
330 from \dvi{} files.
331
332 \item [dvipdfm] convert \dvi{} to \acro{PDF}, an alternative approach
333 to pdf\TeX\ (mentioned above). See the \pkgname{ps4pdf} and
334 \pkgname{pdftricks} packages for still more alternatives.
335
336 \item [psselect, psnup, \ldots] \PS{}
337 utilities.
338
339 \item [lacheck] \LaTeX{} syntax checker.
340
341 \item [texexec] Con\TeX{}t and \acro{PDF} processor.
342
343 \item [tex4ht] \TeX{} to \acro{HTML} converter.
344
345 \end{cmddescription}
346
347
348 \section{Unix installation}
349 \label{sec:unix-install}
350
351 As introduced in section~\ref{sec:basic} (\p.\pageref{sec:basic}),
352 \TL{} has three principal uses:
353
354 \begin{enumerate}
355 \item Run directly from media.
356 \item Install to disk.
357 \item Integrate a particular package or collection into your existing
358 \TeX{} installation.
359 \end{enumerate}
360
361 \noindent The following sections describes the Unix-specific procedures
362 for each of these.
363
364 \ifSingleColumn \begin{figure}[ht]\noindent \fi
365 \begin{warningbox}
366 \textbf{Warning: } The \TK{} \CD{}s and \DVD{} are in ISO 9660 (High Sierra)
367 format, \emph{with} Rock Ridge (and Joliet, for Windows)
368 extensions. Therefore, in order to take full advantage of the \TK{}
369 under Unix, your system needs to be able to use the Rock Ridge
370 extensions. Please consult the documentation for your \cmdname{mount}
371 command to see how to do this. If you have several different machines
372 on a local network, you may be able to mount the \CD{}s on one which
373 does support Rock Ridge, and use this with the others.
374
375 \leavevmode\quad Linux, \acro{BSD}, Sun, and \acro{SGI}
376 systems should be able to use the \CD{}s without problems. We
377 would appreciate receiving detailed advice from users on other systems
378 who succeed, for future versions of this documentation.
379
380 \leavevmode\quad
381 The discussion below assumes you have been able to mount
382 the \CD{}s with full Rock Ridge compatibility.
383 \end{warningbox}
384 \ifSingleColumn\end{figure}\fi
385
386
387 %
388 \subsection{Running \protect\TL{} directly from media (Unix)}
389
390 \def\runlive{% text repeated in windows section
391 It is possible to use the \TeX{} system directly from the \pkgname{live}
392 \DVD{}, without installing the distribution to disk. (Thus the name
393 \TeX\ `Live', in fact.) It is \emph{not} possible to run \TeX{}
394 directly from the other \CD s (see section~\ref{sec:multiple-dist},
395 \p.\pageref{sec:multiple-dist}).
396 }
397
398 \def\startinst{% repeated in other subsections
399 To start, you mount the \CD{} or \DVD{}, with Rock Ridge extensions
400 enabled. The exact command to do this varies from system to system; the
401 following works under Linux, except the name of the device
402 (\filename{/dev/cdrom}, here) may vary. (All our examples will use
403 \texttt{>} as the shell prompt; user input is
404 \Ucom{\texttt{underlined}}.)
405 \begin{alltt}
406 > \Ucom{mount -t iso9660 /dev/cdrom /mnt/cdrom}
407 \end{alltt}
408
409 \noindent Change the current directory to the mount point:
410 \begin{alltt}
411 > \Ucom{cd /mnt/cdrom}
412 \end{alltt}
413
414 \noindent Under \MacOSX, the directory is typically under
415 \dirname{/Volumes}, and the media will be mounted automatically.
416
417 Run the installation script \filename{install-tl.sh}:
418 \begin{alltt}
419 > \Ucom{sh install-tl.sh}\\
420 Welcome to TeX Live...
421 \end{alltt}
422
423 \noindent After various greeting messages and a list of the main menu
424 options, the installation will ask you to enter a command. Do this by
425 typing the desired character and hitting return; don't type the angle
426 brackets. Either uppercase or lowercase is ok; we'll use lowercase in
427 our examples.
428 }
429
430 \runlive
431 \startinst
432
433 For running live, our first command will be \Ucom{d} and then the
434 subcommand \Ucom{1} to set directories. Even in this case, we must
435 choose a directory on the local disk to place files that the \TeX{}
436 system itself generates, such as fonts and formats, and also to provide
437 a place for updated configuration files, if need be. We'll use
438 \dirname{/usr/local/texmf-local} in this example. (If the default value
439 of \dirname{/usr/TeX} works for you, then you can skip this step.)
440 \begin{alltt}
441 Enter command: \Ucom{d}
442 Current directories setup:
443 <1> TEXDIR: /usr/TeX
444 ...
445 Enter command: \Ucom{1}
446 New value for TEXDIR [/usr/TeX]: \Ucom{/usr/local/texmf-local}
447 ...
448 Enter command: \Ucom{r}
449 \end{alltt}
450
451 \noindent Back at the main menu, our second and last command is
452 \Ucom{r}, to set up for running live off the media without installing
453 to disk:
454 \begin{alltt}
455 Enter command: \Ucom{r}
456 Preparing destination directories...
457 ...
458 Welcome to TeX Live!
459 >
460 \end{alltt}
461
462 \noindent And we are back at the system prompt, as shown.
463
464 Next, it is necessary to alter two environment variables:
465 \envname{PATH}, to an architecture-dependent value (so that we can run
466 the programs), and \envname{VARTEXMF}, to the value specified above. See
467 table~\ref{tab:archlist} for a list of the architecture names for the
468 different systems.
469
470
471 \def\textruntexconfig{%
472 After the main installation has completed, and environment variables
473 have been set, the last step is to run \cmdname{texconfig} to customize
474 your installation for your needs. This is explained in
475 section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig}.
476 }
477 \textruntexconfig
478
479 \begin{table*}[ht]
480 \caption[Supported system architectures.]{Supported system
481 architectures. In addition to the version-specific names listed here,
482 there are generic names without the version numbers. For instance,
483 \texttt{sparc-solaris} links to \texttt{sparc-solaris2.7}. The generic
484 names can be used to protect against the version numbers changing in the
485 future, if you wish.}
486 \label{tab:archlist}
487 \begin{tabular}{>{\ttfamily}ll}
488 alpha-linux & HP Alpha GNU/Linux \\
489 %alphaev5-osf4.0d & HP Alphaev5 OSF \\
490 %hppa2.0-hpux10.20 & HP9000 HPUX 10.20 \\
491 i386-freebsd4.10 & Intel x86 FreeBSD \\
492 i386-linux & Intel x86 GNU/Linux \\
493 %i386-openbsd3.3 & Intel x86 OpenBSD \\
494 %i386-solaris2.8 & Intel x86 Solaris \\
495 mips-irix6.5 & SGI IRIX \\
496 powerpc-aix4.3.3.0 & IBM RS/6000 AIX \\
497 powerpc-darwin6.8 & \MacOSX \\
498 sparc-solaris2.7 & Sun Sparc Solaris \\
499 sparc64-linux & Sun Sparc GNU/Linux \\
500 win32 & Windows (32-bit) \\
501 x86\_64-linux & Intel/AMD 64-bit GNU/Linux \\
502 \hline
503 \end{tabular}
504 \end{table*}
505
506 \label{text:path}
507 The syntax for setting the environment variables, and the initialization
508 file to put them in, depends on the shell you use. If you use a
509 Bourne-compatible shell (\cmdname{sh}, \cmdname{bash}, \cmdname{ksh}, et
510 al.), put the following into your \filename{$HOME/.profile} file:
511 \begin{alltt}
512 PATH=/mnt/cdrom/bin/\var{archname}:$PATH; export PATH
513 VARTEXMF=/usr/local/texmf-local/texmf-var; export VARTEXMF
514 \end{alltt}
515
516 \noindent For C shell-compatible shells (\cmdname{csh}, \cmdname{tcsh}),
517 put the following into your \filename{$HOME/.cshrc} file:
518 \begin{alltt}
519 setenv PATH /mnt/cdrom/bin/\var{archname}:$PATH
520 setenv VARTEXMF /usr/local/texmf-local/texmf-var
521 \end{alltt}
522
523 \noindent Then log out, log back in, and test your installation
524 (see section~\ref{sec:test-install}, \p.\pageref{sec:test-install}).
525
526 \def\textifindoubt{%
527 If in doubt, please ask any local system gurus to help you with
528 problems; for example, the way to mount the \TL{} media, which
529 directory or directories to use, and precise details of the changes to
530 your personal initialization files can and do vary from site to site.
531 }
532 \textifindoubt
533
534
535 %
536 \subsection{Installing \protect\TeX\protect\ Live to disk}
537 \label{sec:unix-install-disk}
538
539 It is possible, indeed typical, to install the \TeX{} system from the
540 \TL{} to disk. This can be done either from any of the \TK{} discs.
541 (See section~\ref{sec:multiple-dist}, \p.\pageref{sec:multiple-dist},
542 for an explanation of the different distributions.)
543
544 \startinst
545
546 Table~\ref{tab:main-menu-options} briefly lists the options in the main
547 menu. The order in which you select the options makes little
548 difference, except that \Ucom{i} must be last. It's reasonable to go
549 through them in the order presented here.
550
551 % apparently here.sty [H] doesn't support table*.
552 \begin{table}[H]
553 \caption{Main menu options for the installation.}
554 \label{tab:main-menu-options}
555 \begin{tabular}{>{\ttfamily}ll}
556 p & The platform you are running on.\\
557 b & The architectures for which to install binaries.\\
558 s & The base installation scheme to use (minimal, recommended,
559 full, etc.)\\
560 c & Override the base scheme for individual collections.\\
561 l & Override for language collections.\\
562 d & Directories in which to install.\\
563 o & Other options.\\
564 i & Perform the installation.\\
565 \end{tabular}
566 \end{table}
567
568 Here are further details on each option.
569
570 \textbf{\optname{p} -- Current platform.} Since the installation script
571 automatically guesses which platform you're running on, it is generally
572 unnecessary to use this option. It's there in case you need to override
573 the automatic detection.
574
575 \textbf{\optname{b} -- Binary architectures.} By default, only the
576 binaries for your current platform will be installed. From this menu,
577 you can select installation of binaries for other architectures as well
578 (or not install the current platforms). This can be useful if you are
579 sharing a \TeX\ tree across a network of heterogenous machines. For a
580 list of the supported architectures, see table~\ref{tab:archlist},
581 \p.\pageref{tab:archlist}.
582
583 \textbf{\optname{s} -- Base installation scheme.} From this menu, you
584 can choose an overall common set of packages, called a ``scheme''. The
585 default \optname{recommended} scheme suffices for typical needs, but you
586 can also choose the \optname{basic} scheme if you are low on disk space,
587 or \optname{full} to get absolutely everything. There are also specific
588 sets for Omega and \acro{XML}.
589
590 \textbf{\optname{c} -- Individual collections.} From this menu, you can
591 override the base scheme's set of collections to install. Collections
592 are one level lower than schemes\Dash collections consist of
593 one or more packages, where packages (the lowest level grouping in \TL)
594 contain the actual \TeX\ macro files, font families, and so on.
595 In this menu, selection letters are case-sensitive.
596
597 \textbf{\optname{l} -- Language collections}. This menu has the same
598 basic purpose as \Ucom{c}, to override the base scheme. In this case,
599 the collections are specifically for different languages. Selection
600 letters are case-sensitive here. Here is a list of the language
601 collections in \TL:
602
603 % xx really should generate list from texmf/tpm/collection/tex-lang*
604 % a la install-tl.sh.
605 \begin{tabbing}
606 \hspace{.25\linewidth} \=
607 \hspace{.25\linewidth} \=
608 \hspace{.25\linewidth} \=
609 \hspace{.25\linewidth} \kill
610 (some) African scripts \>
611 Arabic \>
612 Armenian \>
613 Chinese\,Japanese\,Korean \\
614 Croatian \>
615 Cyrillic \>
616 Czech/Slovak \>
617 Danish \\
618 Dutch \>
619 Finnish \>
620 French \>
621 German \\
622 Greek \>
623 Hungarian \>
624 Indic \>
625 Italian \\
626 Latin \>
627 Manju \>
628 Mongolian \>
629 Norwegian \\
630 Polish \>
631 Portuguese \>
632 Spanish \>
633 Swedish \\
634 Tibetan \>
635 \acro{UK} English \>
636 Vietnamese \\
637 \end{tabbing}
638
639 \noindent Language collections typically include fonts, macros,
640 hyphenation patterns, and other support files. (For instance,
641 \pkgname{frenchle.sty} is installed if you select the \optname{French}
642 collection.) In addition, installing a language collection will alter
643 the \filename{language.dat} configuration file controlling which
644 hyphenation patterns are loaded.
645
646 \textbf{\optname{d} -- Installation directories}. Three directories can
647 be changed here:
648 \label{text:instdir}
649
650 \begin{ttdescription}
651 \item [TEXDIR] The top-level directory under which
652 everything else will be installed. The default value is
653 \dirname{/usr/TeX}, and is often changed. For example, changing to a
654 value such as \dirname{/usr/local/texlive2003} would make it possible to
655 keep different releases of \TL{} separate. (You may then wish to make
656 \dirname{/usr/local/texlive} a symbolic link, after testing the new
657 release.)
658
659 Under \MacOSX, the usual frontends look for \TeX{} in
660 \dirname{/usr/local/teTeX}, so you may wish to install \TL{} there.
661
662 \item [TEXMFLOCAL] This tree is where the \TeX{} system (not as part of
663 installation, but rather over time) puts non-version-specific files,
664 primarily fonts. The default value is \dirname{TEXDIR/texmf-local}.
665 However, it's also the recommended location to put any local packages or
666 configuration settings. Therefore, it's desirable to change it to a
667 location independent of the current \TL{} release; for example,
668 \dirname{/usr/local/texmf-local}.
669
670 \item [VARTEXMF] This tree is where the system puts files that
671 \emph{are} version-specific, primarily format files and the
672 configuration files which are modified by \cmdname{texconfig} (see
673 section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig}). The default
674 value is \dirname{TEXDIR/texmf-var}, and there's generally no reason to
675 change it.
676
677 \end{ttdescription}
678
679 \textbf{\optname{o} -- Other options.} From this menu, you can select
680 the following general options:
681
682 \begin{ttdescription}
683 \item [a] Specify an alternate directory for generated fonts.
684 The default is to use the \envname{VARTEXMF} tree, as explained above.
685 Setting this is useful if you plan to mount the main tree read-only, and
686 therefore you need another location (perhaps host-specific) for
687 dynamically created fonts.
688
689 \item [l] Create symbolic links for the binaries, man pages,
690 and\slash or \acro{GNU} Info files in other locations. For example, you may
691 wish to make the man pages available under \dirname{/usr/local/man} and
692 the Info files available under \dirname{/usr/local/info}. (Of course
693 you need appropriate privileges to write in the specified directories.)
694
695 It is not advisable to overwrite a \TeX\ system that came with your
696 system with this option. It's intended more for having the links in
697 standard directories known to users, such as \dirname{/usr/local/bin},
698 which don't already contain any \TeX\ files.
699
700 \item [d] Skip installation of the font/macro documentation tree.
701 This is useful if you need to save space, or if you've previously
702 installed the documentation elsewhere.
703
704 \item [s] Skip installation of the main font/macro source
705 tree. This is useful if you are arranging to share that tree between
706 machines and\slash or architectures in some other way, such as \acro{NFS}.
707
708 \end{ttdescription}
709
710 \textbf{i -- Perform installation.} When you're satisfied with your
711 configuration options, enter \Ucom{i} to actually do the installation
712 from the media to your chosen locations.
713
714 % text is similar to above, but no VARTEXMF, so we have to write out.
715 After the installation completes, your next step is to include the
716 architecture-specific subdirectory of \dirname{TEXDIR/bin} in your
717 \envname{PATH}, so the newly-installed programs can be found. The
718 architecture names are listed in table~\ref{tab:archlist},
719 \p.\pageref{tab:archlist}, or you can simply list the directory
720 \dirname{TEXDIR/bin}.
721
722 The syntax for doing this, and the initialization file to use, depends
723 on your shell. If you use a Bourne-compatible shell (\cmdname{sh},
724 \cmdname{bash}, \cmdname{ksh}, et al.), put the following into your
725 \filename{$HOME/.profile} file:
726
727 \begin{alltt}
728 PATH=/mnt/cdrom/bin/\var{archname}:$PATH; export PATH
729 \end{alltt}
730
731 \noindent For C shell-compatible shells (\cmdname{csh}, \cmdname{tcsh}),
732 put the following into your \filename{$HOME/.cshrc} file:
733 \begin{alltt}
734 setenv PATH /mnt/cdrom/bin/\var{archname}:$PATH
735 \end{alltt}
736
737 \textruntexconfig
738
739 Here is a brief annotated example which selects a full installation,
740 with binaries for the current system only, with directory changes as
741 recommended above. The prompts and \acro{RETURN}s are omitted for
742 brevity.
743
744 \begin{alltt}
745 > \Ucom{sh install-tl.sh}
746 \Ucom{s} \Ucom{b} \Ucom{r} # scheme, full, return to main
747 \Ucom{d} # change directories
748 \Ucom{1} \Ucom{/usr/local/texlive2003} # top-level dir
749 \Ucom{2} \Ucom{/usr/local/texmf-local} # TEXMFLOCAL outside TEXDIR
750 \Ucom{r} # return to main
751 \Ucom{i} # perform installation
752 > \Ucom{texconfig} ...
753 # New PATH, with Linux as the example:
754 > \Ucom{PATH=/usr/local/texlive2003/bin/i386-linux:$PATH; export PATH}
755 \end{alltt}
756
757 \textifindoubt
758
759
760 %
761 \subsection{Installing individual packages to disk}
762
763 You can add individual packages or collections from the current
764 distribution to an existing non-\TL{} setup, or an earlier
765 \TL{} installation.
766
767 \startinst
768
769 Run the installation script \filename{install-pkg.sh} (not
770 \filename{install-tl.sh}, which is intended for complete installations
771 only):
772 \begin{alltt}
773 > \Ucom{sh install-pkg.sh \var{options}}
774 \end{alltt}
775
776 The first set of options controls what gets read:
777
778 \begin{ttdescription}
779 \item [-{}-package=\var{pkgname}] The individual package to work on.
780
781 \item [-{}-collection=\var{colname}] The individual collection to work on.
782
783 \item [-{}-nodoc] Exclude documentation files from the operation.
784
785 \item [-{}-nosrc] Exclude source files from the operation.
786
787 \item [-{}-cddir=\var{dir}] Source directory to read from; defaults
788 to the current directory. If you followed the instructions above, that
789 will be the distribution directory, and won't need to be changed.
790
791 \item [-{}-listdir=\var{dir}] The so-called `lists' directory within
792 \var{cddir} from which to read the package information. The only
793 reason to change the default is if you're making changes to \TL{}
794 yourself.
795
796 \end{ttdescription}
797
798 What actually happens is controlled by the following options. If
799 neither of these are specified, the default action is to install the
800 selected files. The main destination tree is found by expanding
801 \envname{\$TEXMFMAIN} with \cmdname{kpsewhich}. You can override it by
802 setting either the environment variable \envname{TEXMFMAIN} or
803 \envname{TEXMF}.
804
805 \begin{ttdescription}
806 \item [-{}-listonly] List the files that would be installed, but don't
807 actually install anything.
808
809 \item [-{}-archive=\var{tarfile}] Instead of installing the files into
810 the \TeX{} system, make a \cmdname{tar} archive.
811
812 \end{ttdescription}
813
814 Additional options:
815
816 \begin{ttdescription}
817
818 \item [-{}-config] After installation, run \code{texconfig init}.
819
820 \item [-{}-nohash] After installation, don't run \cmdname{mktexlsr} to
821 rebuild the filename database.
822
823 \item [-{}-verbose] Give more information as the script runs.
824
825 \end{ttdescription}
826
827 Here are some usage examples:
828
829 \begin{enumerate}
830
831 \item To see the files in the package \pkgname{fancyhdr} without
832 installing it:
833
834 \begin{alltt}
835 \ifSingleColumn> \Ucom{sh install-pkg.sh --package=fancyhdr --listonly}
836 \else> \Ucom{sh install-pkg.sh --package=fancyhdr \bs}
837 > \Ucom{--listonly}
838 \fi{}
839 texmf/doc/latex/fancyhdr/README
840 texmf/doc/latex/fancyhdr/fancyhdr.dvi
841 texmf/doc/latex/fancyhdr/fancyhdr.pdf
842 ...
843 \end{alltt}
844
845 \item Install the \LaTeX{} package \pkgname{natbib}:
846 \begin{alltt}
847 > \Ucom{sh install-pkg.sh --package=natbib}
848 \end{alltt}
849
850 \item Install the \LaTeX{} package \pkgname{alg} without source files or
851 documentation:
852 \begin{alltt}
853 \ifSingleColumn> \Ucom{sh install-pkg.sh --package=alg --nosrc --nodoc}
854 \else> \Ucom{sh install-pkg.sh -{}-package=alg \bs}
855 > \Ucom{-{}-nosrc -{}-nodoc}
856 \fi\end{alltt}
857
858 \item Install all the packages in the collection of additional
859 plain \TeX\ macros:
860 \begin{alltt}
861 > \Ucom{sh install-pkg.sh --collection=tex-plainextra}
862 \end{alltt}
863
864 \item Write all files in the \pkgname{pstricks} package to a
865 \cmdname{tar} file in \path|/tmp|:
866 \begin{alltt}
867 \ifSingleColumn> \Ucom{sh install-pkg.sh --package=pstricks --archive=/tmp/pstricks.tar}
868 \else
869 > \Ucom{sh install-pkg.sh -{}-package=pstricks \bs}
870 > \Ucom{-{}-archive=/tmp/pstricks.tar}
871 \fi\end{alltt}
872
873 \end{enumerate}
874
875 \textifindoubt
876
877
878 %
879 \section{Post-installation}
880 \label{sec:postinstall}
881
882 After the main installation is done, for any operating system, the
883 remaining steps are to configure the system for your local needs, and
884 perform some basic tests.
885
886 Another sort of post-installation is to acquire packages, fonts, or
887 programs that were not included in \TL{}. The basic idea is to
888 install such additions in the \envname{TEXMFLOCAL} tree (if you
889 installed to disk), or \envname{VARTEXMF} (if you are running live).
890 See the ``Installation directories'' option on \p.\pageref{text:instdir}.
891
892 Unfortunately, the details can and do vary widely, and so we do not attempt to
893 address them here. Here are some external links to descriptions:
894 \begin{itemize*}
895 \item
896 \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=instpackages}
897 \item
898 \url{http://www.ctan.org/installationadvice}
899 \item
900 \url{http://www.ctan.org/tex-archive/info/beginlatex/html/chapter5.html#pkginst}
901 \item
902 \url{http://www.ctan.org/tex-archive/info/Type1fonts} for font creation
903 and installation information in particular.
904 \end{itemize*}
905
906
907 \subsection{The \protect\cmdname{texconfig} program}
908 \label{sec:texconfig}
909
910 At any time after installation, you can and should use the program
911 \cmdname{texconfig} to configure the system to fit your local needs. It
912 is installed in the architecture-specific subdirectory
913 \texttt{TEXDIR/bin/\var{arch}} along with everything else.
914
915 If you run it without arguments, it will enter full-screen mode and
916 allow you to view and change options interactively.
917
918 You can also run it with various command-line options. Here are some of
919 the most common (a \TL{} installation is configured for the A4 paper
920 size by default):
921
922 \begin{ttdescription}
923
924 \item [texconfig paper letter] Set default paper size for
925 various programs and drivers (\cmdname{pdftex}, \cmdname{dvips},
926 \cmdname{dvipdfm}, \cmdname{xdvi}) to be \acro{US} letter. The other
927 allowable size is \optname{a4}, which is the default.
928
929 \item [texconfig localsetup] Verify that paths are set ok.
930
931 \item [texconfig rehash] Update all the \TeX{} system filename databases.
932
933 \item [texconfig faq] Show the \teTeX{} \acro{FAQ}.
934 (See also the main \TeX{} \acro{FAQ} in \OnCD{texmf-doc/doc/english/FAQ-en}.)
935
936 \item [texconfig help] Output help information for \cmdname{texconfig}.
937
938 \end{ttdescription}
939
940 Of course, \cmdname{texconfig} can only support changing a few of the
941 many options and configuration parameters in a \TeX{} system. The main
942 configuration file for the base \Webc{} programs is named
943 \filename{texmf.cnf}. You can find its location by running
944 \samp{kpsewhich texmf.cnf}; it contains many comments explaining the
945 default settings and useful alternatives.
946
947
948 \subsection{Testing the installation}
949 \label{sec:test-install}
950
951 After installing \TL{} as best you can, you naturally want to test
952 it out, so you can start creating beautiful documents and\slash or fonts.
953
954 This section gives some basic procedures for testing that the new system
955 is functional. We give Unix commands; under \MacOSX{} and Windows,
956 you're more likely to run the tests through a graphical interface, but
957 the principles are the same.
958
959 \begin{enumerate}
960
961 \item Make sure that you can run the \cmdname{tex} program in the first
962 place:
963
964 \begin{alltt}
965 > \Ucom{tex -{}-version}
966 TeX 3.141592 (Web2C 7.5.3)
967 kpathsea version 3.5.3
968 Copyright (C) 1997-2004 D.E. Knuth.
969 ...
970 \end{alltt}
971 If this comes back with `command not found' instead of version and
972 copyright information, most likely you don't have the correct
973 \dirname{bin} subdirectory in your \envname{PATH}. See
974 the environment-setting information on \p.\pageref{text:path}.
975
976 \item Process a basic \LaTeX{} file:
977 \begin{alltt}
978 > \Ucom{latex sample2e.tex}
979 This is pdfeTeXk, Version 3.141592...
980 ...
981 Output written on sample2e.dvi (3 pages, 7496 bytes).
982 Transcript written on sample2e.log.
983 \end{alltt}
984 If this fails to find \filename{sample2e.tex} or other files, perhaps
985 you have interference from old environment variables or configuration
986 files. For a deep analysis, you can always ask \TeX{} to report on
987 exactly what it is searching for, and finding; see ``Debugging actions''
988 on page~\pageref{Debugging}.
989
990 \item Preview the result online:
991 \begin{alltt}
992 > \Ucom{xdvi sample2e.dvi}
993 \end{alltt}
994 (Under Windows, the analogous command is \cmdname{windvi}.) You should
995 see a new window with a nice document explaining some of the basics of
996 \LaTeX{}. (Well worth reading, by the way if you're new to the system.)
997 You do have to be running under X for \cmdname{xdvi} to work; if you're
998 not, or your \envname{DISPLAY} environment variable is set incorrectly,
999 you'll get an error \samp{Can't open display}.
1000
1001 \item Create a \PS{} file for printing or display:
1002 \begin{alltt}
1003 > \Ucom{dvips sample2e.dvi -o sample2e.ps}
1004 \end{alltt}
1005
1006 \item Create a \acro{PDF} file instead of \dvi{}; this processes the
1007 \filename{.tex} file and writes \acro{PDF} directly:
1008 \begin{alltt}
1009 > \Ucom{pdflatex sample2e.tex}
1010 \end{alltt}
1011
1012 \item Preview the \acro{PDF} file:
1013 \begin{alltt}
1014 > \Ucom{gv sample2e.pdf}
1015 \textrm{or:}
1016 > \Ucom{xpdf sample2e.pdf}
1017 \end{alltt}
1018 Unfortunately neither \cmdname{gv} nor \cmdname{xpdf} are currently
1019 included in \TL{}, so you must install them separately. See
1020 \url{http://wwwthep.physik.uni-mainz.de/~plass/gv} and
1021 \url{http://www.foolabs.com/xpdf}, respectively.
1022
1023 \item Other standard test files you may find useful:
1024
1025 \begin{ttdescription}
1026 \item [small2e.tex] A simpler document than \filename{sample2e}, to
1027 reduce the input size if you're having troubles.
1028 \item [testpage.tex] Test if your printer introduces any offsets.
1029 \item [nfssfont.tex] For printing font tables and tests.
1030 \item [testfont.tex] Also for font tables, but using plain \TeX{}.
1031 \item [story.tex] The most canonical (plain) \TeX{} test file of all.
1032 You must type \samp{\bs bye} to the \code{*} prompt after \samp{tex
1033 story.tex}.
1034 \end{ttdescription}
1035 You can process these in the same way as we did with
1036 \filename{sample2e.tex}.
1037
1038 \end{enumerate}
1039
1040 If you are new to \TeX{}, or otherwise need help with actually
1041 constructing \TeX{} or \LaTeX{} documents, please visit
1042 \url{http://tug.org/begin.html}. We especially recommend the
1043 \textsl{Formatting Information} manual by Peter Flynn, available at
1044 \url{http://www.ctan.org/tex-archive/documentation/beginlatex}.
1045
1046
1047 \section{\MacOSX{} installation}
1048 \label{sec:mac-install}
1049
1050 \TL{} supports \MacOSX, but no prior Macintosh versions. (If you
1051 are running an older Mac version, you can view the files by installing
1052 the Joliet system extension available from
1053 \url{http://www.tempel.org/joliet}; however, the \TL{} binaries
1054 will not run.)
1055
1056 Installation of \TeX{} under \MacOSX{} can be done in two ways:
1057
1058 \begin{enumerate}
1059 \item With the \filename{install*} scripts, as with Unix.
1060 \item With the \cmdname{i-Installer} included in
1061 \filename{MacOSX/II2.dmg}.
1062 \end{enumerate}
1063
1064 \noindent Each of these is described in a following section.
1065
1066 In addition, \TeX{} under \MacOSX\ typically uses a ``frontend''. This
1067 is also described below.
1068
1069
1070 \subsection{\protect\cmdname{i-Installer}: Internet installation}
1071 \label{sec:i-Installer}
1072
1073 The \cmdname{i-Installer} is included in the \TL{} distribution as
1074 an alternative to normal installation. It does not use the contents of
1075 the \TL{} distribution at all; instead, the system (approximately
1076 70 megabytes) is downloaded over the Internet.
1077
1078 One advantage of \cmdname{i-Installer} is that it makes updates
1079 relatively painless. If you are interested, please see the
1080 \cmdname{i-Installer} \TeX{} home page at \url{http://www.rna.nl/tex.html}.
1081
1082 To use it, mount \filename{./MacOSX/II2.dmg}. Read the documentation,
1083 launch it, and install at least \texttt{TeX Foundation} and \texttt{TeX
1084 Programs}. The first will finish without configuration, as soon as the
1085 second is installed you will be presented with a graphical interface to
1086 setting up your \TeX{} system.
1087
1088 The \cmdname{i-Installer} distribution uses the \teTeX{} \dirname{texmf}
1089 tree with some additions. Due to differences between \TL{} and
1090 \teTeX{} you cannot update a \TL{} installation with an
1091 \cmdname{i-Installer} \texttt{TeX Programs} i-Package.
1092
1093
1094 \subsection{\protect\cmdname{install*.sh}: \protect\TL{} installation}
1095
1096 In order to run the installation scripts under \MacOSX, you need to have
1097 the \cmdname{bash} shell installed. If you are running \MacOSX~10.2
1098 or later, you have \cmdname{bash}, and can proceed. If you're running
1099 an earlier \MacOSX{} version, however, the default shell is
1100 \cmdname{zsh}, which won't work; you'll need to get \cmdname{bash} from
1101 the Internet, or more likely upgrade your system.
1102
1103 Once you have \cmdname{bash}, the Unix installation documentation in the
1104 previous section can be followed. See section~\ref{sec:unix-install} on
1105 \p.\pageref{sec:unix-install}; \MacOSX-specific notes are included there
1106 where needed.
1107
1108
1109 \subsection{\MacOSX{} frontends}
1110
1111 Using \TeX{} on a Macintosh typically goes through a front end program,
1112 comprising an execution shell, editor, previewer, and other facilities,
1113 with a graphical interface. Here are the principal frontends:
1114
1115 \begin{cmddescription}
1116 \item [TeXShop] Included in \TL{} as \filename{./MacOSX/texshop.dmg}.
1117 \\See \url{http://www.uoregon.edu/~koch/texshop/texshop.html}.
1118
1119 \item [ITeXMac] Included in \TL{} as \filename{./MacOSX/iTM-*.dmg}.
1120 \\See \url{http://itexmac.sourceforge.net}.
1121
1122 \item [Mac-emacs] A port of Emacs to \MacOSX{}, integrating \pkgname{AucTeX}.
1123 \\See \url{http://www.cs.man.ac.uk/~franconi/mac-emacs}.
1124
1125 \end{cmddescription}
1126
1127 The frontends use \dirname{/usr/local/teTeX} as the default location;
1128 therefore, you must either install \TL{} there, or change the
1129 configuration of the frontend.
1130
1131
1132 \section{Windows installation}
1133 \label{sec:win-install}
1134
1135 Unfortunately, this release of \TL{} does not include a Windows
1136 installer, due to technical difficulties. We hope that an installer
1137 will be available again in a few months. (It is being completely
1138 rewritten to use standard Microsoft libraries, instead of the homegrown
1139 \filename{TeXSetup.exe}.)
1140
1141 A set of experimental Windows binaries is included, nevertheless. You
1142 can install them with the Unix \filename{install-tl.sh} script: select
1143 the \optname{win32} system from the \optname{S} option of the top-level
1144 menu. The \pkgname{XEmacs} package is not included, however, due to
1145 space.
1146
1147 (Meanwhile, if you are an experienced Windows programmer and would like
1148 to help with the project, email us!)
1149
1150
1151 \begin{comment}
1152 \TL{} can be installed on systems running Windows 9x, \acro{ME},
1153 \acro{NT}, \acro{2K} or \acro{XP}. Older versions of Windows (3.1x)
1154 and \acro{MS-DOS} are not supported.
1155
1156 It is necessary to have your Windows set up so that it uses the
1157 Microsoft Joliet extensions for reading \CD{}s; simply look at the \CD{}
1158 in Explorer and see whether it shows long, mixed-case, file names. If it
1159 does not, you must install the Joliet extensions.
1160
1161 The Windows \TeX{} system included in \TL{} is no more and no less
1162 than the \fpTeX{} distribution. It includes a \texttt{dvi} previewer,
1163 \textsf{Windvi}, which is similar in usage to the established Unix
1164 \textsf{xdvi}. The documentation can be found in
1165 \OnCD{texmf/doc/html/windvi/windvi.html}.
1166
1167 \subsection{The \texttt{TeXLive.exe} program}
1168
1169 \begin{figure*}
1170 \begin{center}
1171 \ifnum \Status=1
1172 \includegraphics[width=.7\textwidth]{pictures/Welcome-to-TeXLive}
1173 \else
1174 \ifnum \Status=2
1175 \includegraphics[bb=0 0 551 534]{pictures/Welcome-to-TeXLive.jpg}
1176 \else
1177 \includegraphics[width=.7\textwidth]{pictures/Welcome-to-TeXLive}
1178 \fi
1179 \fi
1180 \end{center}
1181 \caption{``Welcome to \TL'' window}\label{graph:welcome}
1182 \end{figure*}
1183
1184 If your computer is configured to let the \CD{} autostart, then a dialog
1185 box with a menu bar will popup on the screen, and you will have several
1186 choices from there:
1187
1188 \begin{itemize*}
1189 \item Install \TeX{} on your hard disk
1190 \item Do maintenance on your \TeX{} system.
1191 \item Remove the \TeX{} system.
1192 \item Use \TeX{} off the \TL{} \CD{} or \DVD{}.
1193 \item Browse documentation: \TL{} documentation, TUG web
1194 pages, \fpTeX web pages.
1195 \item Run the \cmdname{TeXdocTK} application to find specific documentation.
1196 \end{itemize*}
1197
1198 If your \CD{} does not autostart, you can explicitly run the program
1199 by double clicking on \path|bin/win32/TeXLive.exe| on the \CD{} from
1200 the explorer window.
1201
1202 \subsection{Running \protect\TL{} directly from media (Windows)}
1203
1204 \runlive
1205
1206 To run live under Windows, from the menu, chose \verb|Explore CD-Rom|, then
1207 \verb|Run TeX off CD-Rom|. This will launch the \cmdname{XEmacs} editor.
1208
1209 XEmacs startup file will set the environment variables needed. XEmacs will also
1210 setup a temporary \acro{TDS} compliant texmf tree in the temporary area of your
1211 computer. It is needed to store files that may be built on the fly, such as
1212 \path|pk| bitmap fonts, or format files. Configuration files are copied from
1213 the \CD{} to this texmf tree, so that you can edit them if needed. The
1214 \path|ls-R| database is computed for this texmf tree. The AUC-\TeX{} mode will
1215 be entered Whenever you will visit or create a \TeX{} file, providing all the
1216 bells and whistles for \TeX{} support XEmacs is capable of.
1217
1218 If you run 'M-x shell' within XEmacs, then you will have access to all the TeXLive
1219 tools from the command line provided by XEmacs.
1220
1221 \smallskip {\small\noindent \textbf{[For advanced users:]} You can also
1222 use the small batch file \path|mkloctex.bat| to be called in a
1223 directory \path|bin\win32| of the \CD. From the Start menu select
1224 `Run', then browse the \acro{CD} drive and select
1225 \path|mkloctex.bat|. Before starting it, you should add two parameters
1226 separated by a space: the letter of your \acro{CD} drive and the
1227 letter of the drive where you want to install the \TeX\ directory.
1228 The whole line should read, e.g., \verb+d:\bin\win32\mkloctex.bat d c+.
1229 When installation is complete, please read carefully the information
1230 on screen. If you are running Windows 9x/\acro{ME}, then you will have to
1231 restart Windows.}
1232
1233 \subsection{Support packages for Windows}
1234 \label{sec:win-xemtex}
1235
1236 To be complete, a \TL installation needs support packages that are not
1237 commonly found on a Windows machine.
1238 Many scripts are written using the Perl language. Some important tools require
1239 the Ghostscript \PS{} interpreter to render or to convert files. A graphic
1240 file toolbox is also needed in some cases. Last but not least, a \TeX-oriented
1241 editor makes it easy to type in your \TeX{} files.
1242
1243 All these tools are quite easy to find for Windows, but in order to try to make
1244 your life even easier, we have put such a set of tools on \TL:
1245 \begin{itemize*}
1246 \item \cmdname{Ghostscript} 7.07
1247 \item a minimal \cmdname{Perl} 5.8, sufficient to run all the \TL{}
1248 Perl scripts
1249 \item a subset of \cmdname{ImageMagick} 5.5.6
1250 \item the \cmdname{ISpell} checker
1251 \item \cmdname{XEmacs} 21.5.14 with a selection of packages to support
1252 \TeX{} typesetting.
1253 \end{itemize*}
1254
1255 These packages should be installed only all at once. The bundle is
1256 known as the \XEmTeX{} bundle.
1257
1258 If you didn't install \XEmTeX{}, \cmdname{Perl} and \cmdname{Ghostscript} are
1259 installed anyway if they are not detected on your machine. This is because they are
1260 required by many important tools. The \envname{PERL5LIB} and \verb|GS_LIB|
1261 environment variables will be set too.
1262
1263 When you are under
1264 \cmdname{XEmacs}, the tools provided shadow any other version you might
1265 have installed previously. The point here is that \path|TeXSetup.exe|
1266 will not install anything outside of the \TL location, neither will
1267 it run foreign installers, nor will it try to autodetect installed
1268 products using unreliable rules of thumb. The \XEmTeX{} bundle is
1269 standalone and is meant to evolve in the future. The reference site is
1270 \url{http://www.fptex.org/xemtex/}.
1271
1272 If you don't want to install this bundle, then you are on your own to
1273 install the required tools to complete your \TL{} system. Here is a
1274 list of places to get those tools:
1275
1276 \begin{description}
1277 \item[Ghostscript] \url{http://www.cs.wisc.edu/~ghost/}
1278 \item[Perl] \url{http://www.activestate.com/} (but you might need some
1279 supplementary packages from CPAN: \url{http://www.cpan.org/})
1280 \item[ImageMagick] \url{http://www.imagemagick.com}
1281 \item[NetPBM] alternatively, you could use NetPBM instead of ImageMagick to
1282 process or convert your graphic files. NetPBM home page is
1283 \url{http://netpbm.sourceforge.net/}
1284 \item[\TeX-oriented editors] There is a wide choice, and it is a matter of the
1285 user's taste. Here is a selection:
1286 \begin{itemize*}
1287 \item \cmdname{GNU Emacs} is available natively under Windows, the
1288 reference url is
1289 \url{http://www.gnu.org/software/emacs/windows/ntemacs.html}
1290 \item \cmdname{XEmacs} is available natively under Windows, the
1291 reference url is \url{http://www.xemacs.org/}
1292 \item \cmdname{WinShell} is available on \TL in the \path|support|
1293 directory, the reference url is \url{http://www.winshell.de}
1294 \item \cmdname{WinEdt} is shareware available from \url{http://www.winedt.com}
1295 \item TeXnicCenter is available from\\
1296 \url{http://www.toolscenter.org}
1297 \item \cmdname{Vim} is available on \TL{} in the
1298 \path|support\vim| directory and the
1299 reference site is \url{http://www.vim.org}
1300 \item \cmdname{SciTE} is available from \url{http://www.scintilla.org/SciTE.html}
1301 \end{itemize*}
1302 \end{description}
1303
1304 You might want to install other tools that are not free\footnote{Not
1305 free, that is, in the sense of freedom to modify and redistribute,
1306 following free software guidelines. This does not mean you can't acquire
1307 them for no money.} and therefore not included on \TL{}, such as
1308 \cmdname{GSView}, the \cmdname{Ghostscript} companion to more
1309 conveniently view PS/PDF files. \cmdname{GSView} is available from
1310 \url{http://www.cs.wisc.edu/~ghost/gsview/} or any \acro{CTAN} site.
1311
1312 \subsection{Installing \protect\TeX\protect\ Live to disk}
1313
1314 \textbf{Warning: Win9x users must ensure they have enough environment
1315 space before undertaking installation. The \cmdname{TeXSetup.exe}
1316 program won't change the environment size for them. A few environment
1317 variables will be created and it is possible you run out of
1318 environment space. Add \texttt{SHELL=<path>COMMAND.COM /E:4096 /P} in the
1319 config.sys file in order to increase your environment size.}
1320
1321 Installation is started by letting the media autostart. The program run
1322 is \path|TeXSetup.exe| if you are using the inst disk. If you are using
1323 the live or the demo disk, you will have to select the item
1324 \path|TeXLive Software| from the menu, then the subitem \path|Install on
1325 Hard Disk|. This will invoke \path|TeXSetup.exe|. You can also find it
1326 in the \path|bin/win32| directory and run it, if the autostart fails for
1327 any reason. \path|TeXSetup.exe| is a Windows wizard and it will display
1328 several pages while running.
1329
1330 \begin{description}
1331 \item[Welcome Page]
1332 You can choose a \emph{quick} installation from
1333 here. In this case, the installation will run without any human
1334 assistance from beginning to end, with all the default settings
1335 (Figure~\ref{graph:setup-src},
1336 \ifnum \Status = 1
1337 on the left%
1338 \else\ifnum \Status=2
1339 at the top%
1340 \else
1341 on the left%
1342 \fi\fi
1343 ). If you have enough privileges (administrator or power user
1344 rights) under a Windows version where this is applicable, then you can
1345 decide to install the \TL{} for all users or for yourself only by
1346 checking the appropriate box.
1347 For installing the whole \XEmTeX{} bundle (XEmacs, Ghost\-script,
1348 Perl, ImageMagick and Ispell) you can check \emph{Install XEmTeX
1349 Support} box.
1350 \begin{figure*}[!htb]
1351 The \cmdname{TeXSetup} Wizard\hfill
1352 Source directories for the \TL{} files
1353
1354 \begin{center}
1355 \ifnum \Status=1
1356 \includegraphics[width=.48\textwidth]{pictures/setup-wizard.jpg}\hfill%
1357 \includegraphics[width=.48\textwidth]{pictures/source-for-texlive.jpg}
1358 \else
1359 \ifnum \Status=2
1360 \includegraphics[bb=0 0 506 403]{pictures/setup-wizard.jpg}
1361 \includegraphics[bb=0 0 506 403]{pictures/source-for-texlive.jpg}
1362 \else
1363 \includegraphics[width=.48\textwidth]{pictures/setup-wizard}%
1364 \hfill%
1365 \includegraphics[width=.48\textwidth]{pictures/source-for-texlive}
1366 \fi
1367 \fi
1368 \caption{The \TL{} setup wizard}\label{graph:setup-src}
1369 \end{center}
1370 \end{figure*}
1371 \item[Source Page]
1372 This page is a bit complex. It will allow you to select two source
1373 directories for your \TL{} system
1374 (Figure~\ref{graph:setup-src},
1375 \ifnum \Status = 1
1376 on the right%
1377 \else\ifnum \Status=2
1378 at the bottom%
1379 \else
1380 on the right%
1381 \fi\fi
1382 ). You will need a \emph{local
1383 source directory} and possibly a \emph{remote source directory}.
1384
1385 Why do we need both these directories? The files consisting of the
1386 \TL{} system are on the \CD{}, of course, but some other useful
1387 packages are not, either because of space lacking or because their
1388 license was not compatible with \TL{}. You need to enable Internet
1389 downloading if you want to install these packages that are marked with a
1390 specific ``remote'' icon.
1391
1392 However, don't panic: the default parameters of the setup will allow
1393 you to install a full system using the \CD{} only. Simply, you won't
1394 have \file{WinEdt} (for example), but you will be able to install it
1395 later.
1396
1397 So you can take your files from:
1398 \begin{itemize}
1399 \item the \CD{} or any similar flat tree of files, available through
1400 some standard directory (this means the \CD{} can be mounted on
1401 some remote machine and be made available through network
1402 sharing),
1403 \item a set of \file{.zip} files (this is the case when you are
1404 installing from the demo \CD{} or the \fpTeX{} distribution),
1405 \item the Internet; in this case, the program takes care of
1406 downloading the \file{.zip} files it needs for you.
1407 \end{itemize}
1408 This option is available only if you enable Internet file
1409 downloading in the right part of the page. You also need to
1410 configure this Internet access by selecting to connect either using
1411 Internet Explorer~5 \file{wininet.dll}, or using a direct connection (\texttt{ftp},
1412 \texttt{http}).
1413 % or using a proxy server.
1414 % Last, you can be assisted in defining the \emph{local source
1415 % directory} and \emph{remote source directory} which will be used
1416 % to copy the files onto your hard disk. The \texttt{browse} buttons
1417 % allow to select a directory for the former, and an url among a list
1418 % of mirrors for the latter.
1419 \item[Root Page]
1420 On this page, you will tell where you want the files to be
1421 installed (Figure~\ref{graph:root-schm},
1422 \ifnum \Status = 1
1423 on the left%
1424 \else\ifnum \Status=2
1425 at the top%
1426 \else
1427 on the left%
1428 \fi\fi
1429 ). Only the root directory really matters, the other ones
1430 are set according to the root one. You may want to make
1431 \path|$TEXMFEXTRA| point to some TDS compliant directory with other
1432 \TeX{} files or assign a different value to
1433 \path|$HOMETEXMF|, which is set by default to whatever Windows think
1434 is your `HOME' location.
1435 \begin{figure*}[!htb]
1436 Root and directories\hfill%
1437 Scheme selection
1438 \begin{center}
1439 \ifnum \Status=1
1440 \includegraphics[width=.46\textwidth]{pictures/root-of-installation.jpg}\hfill%
1441 \includegraphics[width=.46\textwidth]{pictures/scheme-selection.jpg}
1442 \else
1443 \ifnum \Status=2
1444 \includegraphics[bb=0 0 506 403]{pictures/root-of-installation.jpg}
1445 \includegraphics[bb=0 0 506 403]{pictures/scheme-selection.jpg}
1446 \else
1447 \includegraphics[width=.46\textwidth]{pictures/root-of-installation}%
1448 \hfill%
1449 \includegraphics[width=.46\textwidth]{pictures/scheme-selection}
1450 \fi
1451 \fi
1452 \caption{\TL-Setup: Root and directories / Schemes}\label{graph:root-schm}
1453 \end{center}
1454 \end{figure*}
1455 \item[Get TPM Page]
1456 This page does not require any manual intervention. The \file{.tpm}
1457 files which describe collections and packages are retrieved
1458 (possibly from the Internet), unzipped if needed and parsed.
1459 \item[Schemes Page]
1460 On this page, you will select the global scheme of your
1461 installation (Figure~\ref{graph:root-schm},
1462 \ifnum \Status = 1
1463 on the right%
1464 \else\ifnum \Status=2
1465 at the bottom%
1466 \else
1467 on the right%
1468 \fi\fi
1469 ). A scheme is a large set of files targeted at some kind
1470 of usage. There are 3 generic schemes for basic, recommended and
1471 full installation. The other ones are devoted to LUGs (what GUST or
1472 GUTenberg propose for their members) or applications (XML and
1473 \TeX{}).
1474 When a scheme is selected, it is still possible to refine the
1475 selection by checking the appropriate box. If doing so, you will be
1476 presented the packages page to change your selection, else you will
1477 jump to the review page.
1478 \item[Packages Page]
1479 Collections and packages are presented in a tree form
1480 (Figure~\ref{graph:win32-support},
1481 \ifnum \Status = 1
1482 on the left%
1483 \else\ifnum \Status=2
1484 at the top%
1485 \else
1486 on the left%
1487 \fi\fi
1488 ). The links
1489 in the tree are dependency links. Collections \emph{depend on}
1490 packages and maybe other collections, and it is the same for each
1491 package. You can select any package or collection individually, but
1492 your request will be granted only if the object is not requested by
1493 another one which is selected. For example, you can't deselect
1494 \texttt{tex-basic} without deselecting all the collections that
1495 request it.
1496
1497 The \texttt{tex-xemtex} collection displayed on the picture is Win32 specific. It
1498 holds a number of bonus packages (Figure~\ref{graph:win32-support},
1499 \ifnum \Status = 1
1500 on the right%
1501 \else\ifnum \Status=2
1502 at the bottom%
1503 \else
1504 on the right%
1505 \fi\fi
1506 ) which can be installed
1507 automatically and individually: Ghostscript (the \PS{}
1508 interpreter), XEmacs editor preconfigured for \TeX{}, tools like Perl,
1509 ImageMagick, Ispell. \emph{None of these packages are selected by
1510 default}.
1511
1512 On this page, you also have the information about disk space
1513 needed, for each object, and for the set of those who are selected,
1514 and also the disk space available on the partition selected for the
1515 installation. Last, you can choose to install or not the
1516 documentation files and source files associated with each package.
1517 \item[Review Page]
1518 You will find there a summary of your choices
1519 (Figure~\ref{graph:review},
1520 \ifnum \Status = 1
1521 on the left%
1522 \else\ifnum \Status=2
1523 at the top%
1524 \else
1525 on the left%
1526 \fi\fi
1527 ). It is still possible to
1528 go back to change them.
1529 \begin{figure*}[!htb]
1530 Packages Page\hfill%
1531 Win32 Support
1532 \begin{center}
1533 \ifnum \Status=1
1534 \includegraphics[width=.48\textwidth]{pictures/package-selection}\hfill%
1535 \includegraphics[width=.48\textwidth]{pictures/win32-support}
1536 \else
1537 \ifnum \Status=2
1538 \includegraphics[bb=0 0 506 403]{pictures/package-selection.jpg}\hfill%
1539 \includegraphics[bb=0 0 506 403]{pictures/win32-support.jpg}
1540 \else
1541 \includegraphics[width=.48\textwidth]{pictures/package-selection}%
1542 \hfill%
1543 \includegraphics[width=.48\textwidth]{pictures/win32-support}
1544 \fi
1545 \fi
1546 \end{center}
1547 \caption{Packages Page / Win32 goodies}
1548 \label{graph:win32-support}
1549 \end{figure*}
1550 \item[Files Copy Page]
1551 The selected files are copied on your hard disk (Figure~\ref{graph:file-copy},
1552 \ifnum \Status = 1
1553 on the right%
1554 \else\ifnum \Status=2
1555 at the bottom%
1556 \else
1557 on the right%
1558 \fi\fi
1559 ). All the files not
1560 yet available on your local disk are first downloaded from the
1561 remote source directory on the Internet. Then every package is
1562 unpacked (if \path|.zip| files), or copied from the \CD{}.
1563 \item[Configuration Page] Several packages need some configuration
1564 step to make them usable (Figure~\ref{graph:configuration},
1565 \ifnum \Status = 1
1566 on the left%
1567 \else\ifnum \Status=2
1568 at the top%
1569 \else
1570 on the left%
1571 \fi\fi
1572 ). Also the \TL{} system needs some post-processing step
1573 (format files generation, ls-R databases generation, environment
1574 variables, etc.). All these operations are done there, some of them
1575 can be lengthy.
1576 \begin{figure*}[!htb]
1577 \textbf{Review Page}\hfill%
1578 \textbf{File Copy Page}
1579 \begin{center}
1580 \ifnum \Status=1
1581 \includegraphics[width=.48\textwidth]{pictures/review-settings}\hfill%
1582 \includegraphics[width=.48\textwidth]{pictures/file-copy}
1583 \else
1584 \ifnum \Status=2
1585 \includegraphics[bb=0 0 506 403]{pictures/review-settings.jpg}\hfill%
1586 \includegraphics[bb=0 0 506 403]{pictures/file-copy.jpg}
1587 \else
1588 \includegraphics[width=.48\textwidth]{pictures/review-settings}\hfill%
1589 \includegraphics[width=.48\textwidth]{pictures/file-copy}%
1590 \fi
1591 \fi
1592 \end{center}
1593 \caption{Review Page / File Copy Page}
1594 \label{graph:review}\label{graph:file-copy}
1595 \end{figure*}
1596 \item[Final Page] The installation being over, you may want to display
1597 the Windows specific documentation (HTML format) and / or the log
1598 file of the setup process (Figure~\ref{graph:final}
1599 \ifnum \Status = 1
1600 on the right%
1601 \else\ifnum \Status=2
1602 at the bottom%
1603 \else
1604 on the right%
1605 \fi\fi
1606 ). If it is needed (Win9x/WinME), you will
1607 be asked to reboot your computer.
1608 \end{description}
1609
1610 \begin{figure*}[!htb]
1611 \textbf{Configuration Page}\hfill%
1612 \textbf{Final Page}
1613 \begin{center}
1614 \ifnum \Status=1
1615 \includegraphics[width=.48\textwidth]{pictures/configuration}\hfill%
1616 \includegraphics[width=.48\textwidth]{pictures/congratulations}
1617 \else
1618 \ifnum \Status=2
1619 \includegraphics[bb=0 0 506 403]{pictures/configuration.jpg}\hfill%
1620 \includegraphics[bb=0 0 506 403]{pictures/congratulations.jpg}
1621 \else
1622 \includegraphics[width=.48\textwidth]{pictures/configuration}\hfill%
1623 \includegraphics[width=.48\textwidth]{pictures/congratulations}%
1624 \fi
1625 \fi
1626 \end{center}
1627 \caption{Configuration Page / Final page}
1628 \label{graph:configuration}\label{graph:final}
1629 \end{figure*}
1630
1631 Please be aware that the choice of cluster size on DOS disk
1632 partitions can radically affect the size of your \TeX\
1633 installation. The support tree has hundreds of small files, and it is
1634 not unusual for a complete installation to take up to four times the
1635 amount of space used on the \CD.
1636
1637 \end{comment}
1638
1639
1640 \section{Windows maintenance and post-installation}
1641
1642 Although this version of \TL{} cannot be installed on Windows, enough of
1643 this section is relevant to existing installations or cross-mounted
1644 installations that it seemed worth leaving in.
1645
1646 It will be thoroughly updated when a complete \TL{} Windows distribution
1647 is released. For now, please ignore references to
1648 \filename{TeXSetup.exe}, etc.
1649
1650
1651 \subsection{What's different in Windows?}
1652
1653 The Windows version of \Webc{} has some specific features that should be
1654 pointed out.
1655
1656 \begin{description}
1657 \item[\KPS{}] The hash-tables that \KPS{} builds are quite large for
1658 the \TL{}. In order to cut down the starting time of any
1659 \KPS{}-enabled program, these hash-tables have been put in shared
1660 memory. This way, when you chain the execution of several such
1661 programs, like \path|tex| calling \path|mpost| calling \path|tex|,
1662 the overhead when starting each of the subprograms is
1663 reduced. This change is hidden to the user, except if you set the
1664 debug flag of kpathsea to the \path|-1| value: you will then trace
1665 access to the shared memory, which is not what you want (it is
1666 accessed very often!). What is useful in a log trace of the shared
1667 memory access is still to be defined, so the situation might evolve
1668 in the future.
1669 \item[\cmdname{kpsecheck}] This command provides some options that did
1670 not fit well into \cmdname{kpsewhich}. It will allow you to list all
1671 the files that occur multiple times across your texmf trees. This
1672 could be handy, but most of the time you will also get unwanted
1673 output (like dozens of \path|README| files)\footnote{It is noticeable
1674 that all these files result in clashes inside the \KPS{}-hashing
1675 mechanism; fortunately, \KPS{} never looks for these files.}. For
1676 this reason, you can combine the \path|-multiple-occurrences| with 2
1677 other options for including or excluding any filename that match
1678 some pattern (you can request for several patterns).
1679
1680 The \cmdname{kpsecheck} command will also report the status of shared
1681 memory: in use or not used. That might be useful to know because if
1682 the status reported is \samp{in use}, that means one or several
1683 processes are working, and the effect of any \cmdname{mktexlsr}
1684 command will be delayed until the next time where no \KPS{} linked
1685 process will be running.
1686
1687 Last, this same command will report about the location it thinks
1688 Ghostscript can be found. Under Win32, for many programs, it is
1689 easier to use the Ghostscript dll, and find it by using the
1690 Ghostscript registry key than to change the \path|PATH|, which has a
1691 limited length anyway.
1692 \item[\Webc{}] The engines have a few more options than in Unix
1693 \Webc{}, and one option with a different behavior:
1694 \begin{itemize}
1695 \item \path|-halt-on-error| stop the compilation at the first error.
1696 \item \path|-job-time| set the job time to the same timestamp as the
1697 file given in argument.
1698 \item \path|-oem| use the DOS codepage for console output.
1699 \item \path|-output-directory| allow to write all the output files in the
1700 specified directory.
1701 \item \path|-time-statistics| print statistics about the job run
1702 time. It is to be noted that Win9x not being a true multitasking
1703 operating system, it has no reliable timer for short periods, so
1704 the value printed is an approximation. Under NT/2K/XP, the result
1705 is quite accurate with user time and system time values allocated
1706 for this run. For Unix
1707 users: the \path|time| command is not usually available to Windows
1708 users.
1709 \end{itemize}
1710 \end{description}
1711
1712 \subsection{Adding packages to your installation}
1713
1714 You will find an option in the \guiseq{TeXLive} menu (or go to
1715 \guiseq{Start\arw Programs \arw TeXLive \arw Add TeX package} menu) to
1716 run \file{TeXSetup.exe} in maintenance mode. The steps are almost the
1717 same as in the initial installation.
1718
1719 We'll discuss differences below, but first, whatever changes you make,
1720 \textbf{do not forget to rebuild the ls-R database files}. Otherwise,
1721 your new files will not be found. You can do this either via the
1722 \acro{GUI} (\guiseq{Start \arw Programs \arw TeXLive \arw Maintenance
1723 \arw Rebuild ls-R}), or manually running the \file{mktexlsr} command.
1724
1725 The main difference is in the packages selection page. In maintenance
1726 mode, the list of installed packages is compared to the list of packages
1727 available from your source directories. Packages that are not installed
1728 will be displayed in green, out of date packages will be displayed in
1729 red and up-to-date, installed packages are displayed in black.
1730
1731 This way, you can choose to add or upgrade components, either from
1732 \TL{} or from the Internet, where you are likely to find some more
1733 recent version of your packages.
1734
1735 It is up to you to select which packages you want to install. The rest
1736 of the process is similar to the first installation.
1737
1738 If you want to add files that are not provided by the \TL{} (or
1739 \fpTeX{}) distribution, it is recommended to put them in the
1740 \path|$TEXMFLOCAL| directory. This way, you will be safe against
1741 upgrades of the \TL{} software.
1742
1743 The directory pointed to by \path|$TEXMFLOCAL| is initially empty. If,
1744 for example, you want to add the support file for the Maple symbolic
1745 computation program, you will have to put the style files in:\\
1746 \path|c:\Program Files\TeXLive\texmf-local\tex\latex\maple\|\\ and the
1747 documentation files in:\\ \path|c:\Program
1748 Files\TeXLive\texmf-local\doc\latex\maple\|
1749
1750 \subsection{Uninstalling \protect\TL{}}
1751
1752 The uninstall procedure is available either from the \file{TeXLive.exe}
1753 program, from the \path|TeXLive| menu or from the control panel
1754 (\guiseq{Start \arw Control Panel, Add/Remove Programs}). This procedure
1755 will cleanup your hard disk of most of the \TL{} files. However,
1756 \TeX{} is a system that is creating files and there is no mechanism to
1757 keep track of all of them. Moreover, Win32 support packages have their
1758 own uninstall procedure, which you will have to run separately (provided
1759 you want to get rid of them). Last, the files you may have stored in
1760 \path|$TEXMFLOCAL| won't be removed. So, even if the vast majority of
1761 files are automatically removed by the uninstall procedure, you will
1762 have to do some manual cleanup to actually remove all of them.
1763
1764 \subsection{Running \texttt{TeXSetup.exe} from the command line}
1765
1766 The \path|TeXSetup.exe| program has a number of other useful
1767 options. You can get the list by running:
1768 \begin{verbatim}
1769 c:\>TeXSetup --help
1770 \end{verbatim}
1771
1772 Here is the description:
1773 \begin{description}
1774 \item[\path|--automatic-reboot|] reboot without waiting user
1775 confirmation once installation is over;
1776 \item[\path|--dry-run|] do nothing, just log everything that will be
1777 done without this option;
1778 \item[\path|--quick|] use the recommended installation and default
1779 directories, ask nothing up to rebooting;
1780 \item[\path|--with-xemtex|] selects the \XEmTeX{} bundle;
1781 \item[\path|--net-method (=ie5/direct)|] enable to download components with
1782 restricted licenses from the Internet (either using direct
1783 connection of Internet Explorer 5 DLLs): you need to have an available
1784 network connection and some of the packages are huge;
1785 \item[\path|--remote-source-directory <url>|] this is the base url for the remote packages;
1786 \item[\path|--local-source-directory <dir>|] by default, \path|TeXSetup.exe|
1787 will guess the root directory of the set of files you want it to act on, if you ever
1788 upgrade \path|TeXSetup.exe|, you won't be able to copy the new version
1789 onto your \CD{}, so you will need to use this option to specify the
1790 root of the \CD{};
1791 \item[\path|--installation-directory <dir>|] this is the root of your
1792 installation, all files will be copied under this location. The
1793 default value is \verb+c:\Program Files\TL+;
1794 \item[\path|--texmfmain-directory <dir>|]
1795 \item[\path|--texmflocal-directory <dir>|]
1796 \item[\path|--texmfextra-directory <dir>|]
1797 \item[\path|--texmfhome-directory <dir>|]
1798 \item[\path|--vartexmf-directory <dir>|]
1799 \item[\path|--vartexfonts-directory <dir>|] these are the directories
1800 used to configure the location of your files. They map directly to
1801 the \path|texmf.cnf| variables.
1802 \item[\path|--with-source-files(=yes/no)|] copy the source files
1803 for \TeX{} packages, default value is no;
1804 \item[\path|--with-documentation-files(=yes/no)|] copy documentation files for \TeX{}
1805 packages. Default value is yes. Beware: this is only documentation about specific
1806 packages, general documentation will be installed anyway;
1807 \item[\path|--program-folder <folder>|] the name of the folder under
1808 which you will find the menus;
1809 \item[\path|--add-package <pkg>|] this is used to add or update a specific
1810 package after a first regular installation;
1811 \item[\path|--scheme <pkg>|] install the named scheme instead of the
1812 default \path|texlive-recommended| scheme;
1813 \item[\path|--maintenance|] mostly the same as \path|--add-package|
1814 without specifying a package to add;
1815 \item[\path|--uninstall|] this option will remove anything \TeX{} related coming from
1816 the \CD{}, which means there can be files left if you added style
1817 files or format files, and also that supplementary tools will not be
1818 removed. This option is still a bit crude in this release;
1819 \item[\path|--help|] this option opens up a box with the list of options.
1820 \end{description}
1821
1822 \subsection{Network installation}
1823
1824 \KPS{} knows about UNC names, so you can use them to get your TEXMF
1825 tree from the network. But there is better than this.
1826 All the support files and configuration files, everything except the files in the
1827 \path|bin/win32| are shareable with a \teTeX{} or Unix \TL{} installation. That means
1828 you can use Samba either to mount from an NT server to a Unix
1829 workstation or the converse. Several strategies are possible:
1830 \begin{itemize}
1831 \item Put everything on the server. Just add each set of files for the os and
1832 architecture you want to use in the \path|bin| directory. That means
1833 for example \path|bin/win32| and \path|bin/i386-linux|. Next configure
1834 your main variables. You can use UNC names to
1835 point to the right directories under Win32.
1836 \item Install a local copy for the binaries and format files. In this
1837 case, assign \path|$TEXMFMAIN| to the main \path|texmf| tree that
1838 will be accessed remotely. Set \path|$VARTEXMF| to be a local
1839 directory which will hold local configuration files and on-the-fly
1840 generated files.
1841 \end{itemize}
1842
1843 \subsection{Personal configurations}
1844
1845 \subsubsection{Dvips}
1846
1847 The configuration file for dvips can be found in\\
1848 \verb+C:\Program Files\TeXLive\texmf-var\dvips\config\config.ps+\\
1849 You may open it with any editor
1850 %(\cmdname{WinShell} will do fine)
1851 and change some parameters:
1852
1853 \begin{description}
1854 \item [fonts] you can change the default printer \MF{} mode or printer
1855 resolution in case \cmdname{dvips} needs to generate PK fonts. By default it
1856 is configured to use Type~1 versions of the CM fonts, so it should
1857 not call \cmdname{mktexpk} too often;
1858 \item[printer] you can tell dvips where you want to print by default. If
1859 the \optname{o} option is not followed by a printer name, then a
1860 \file{.ps} \PS{} file is written. You can give dvips a printer
1861 name such as:
1862 \begin{verbatim}
1863 o lpt1:
1864 % o | lpr -S server -P myprinter
1865 % o \\server\myprinter
1866 \end{verbatim}
1867 \item[paper] Next, you might want
1868 to change the paper size from European (A4) to US letter
1869 by making the US letter the first paper size mentioned in the file.
1870 Scroll to the group of lines beginning with \code{@}. Move
1871 the appropriate lines so that this section begins with the lines:\\
1872 \hspace*{1em} @ letterSize 8.5in 11in\\
1873 \hspace*{1em} @ letter 8.5in 11in\\
1874 \hspace*{1em} @+ \%\%BeginPaperSize: Letter\\
1875 \hspace*{1em} @+ letter\\
1876 \hspace*{1em} @+ \%\%EndPaperSize
1877 \end{description}
1878
1879 The current \TL{} distribution implements the procedure of making
1880 always up-to-date fontmaps files for Dvips and Pdftex. This is done by
1881 the \cmdname{updmap} program during installation, as well as during any
1882 font package addition. If you add new packages by hand, edit the file
1883 \verb+updmap.cfg+ in \path|$VARTEXMF/web2c|.
1884
1885 \subsubsection{Pdftex}
1886
1887 If you use the program pdf{}latex to write \acro{PDF} format directly,
1888 and you are using \acro{US} letter-size paper, edit the file
1889 \verb+C:\Program Files\TeXLive\texmf-var\tex\generic\config\pdftexconfig.tex+ and
1890 change \samp{\bs pdfpagewidth} and \samp{\bs pdfpageheight}. These entries should read:
1891 \begin{alltt}
1892 \bs{}pdfpagewidth=8.5 true in
1893 \bs{}pdfpageheight=11 true in
1894 \end{alltt}
1895 Save the file and exit the editor.
1896
1897 \subsubsection{GSView}
1898 GSView is now distributed under the Aladdin License, and therefore is no longer included in
1899 \TL{}.
1900
1901 If you may want to change the page size to US letter size. If so, open
1902 GSView from the \guiseq{Start} menu, and select \guiseq{Media\arw Letter}.
1903
1904 Also, there are menu settings that are supposed to give you the most
1905 readable screen image. On \guiseq{Media \arw Display Settings}, set both
1906 \optname{Text Alpha} and \optname{Graphics Alpha} to 4~bits.
1907
1908 Note that the installation process has set all \code{.ps} and
1909 \code{.eps} files to automatically open with \cmdname{GSView}.
1910
1911 For printing instructions, see section~\ref{printing} below.
1912
1913 \subsubsection{WinDvi}
1914 \label{sub:windvi}
1915
1916 The \file{TeXSetup.exe} program takes care of associating the files
1917 with the \file{.dvi} extension with \file{Windvi}.
1918
1919 Open it with \guiseq{Start\arw Programs\arw TeXLive\arw DVI Viewer}.
1920
1921 You can set it for US letter-size paper by going to \guiseq{View\arw
1922 Options\arw Papertype} and selecting US (8.5\verb+"+ x 11\verb+"+) (and
1923 then \optname{OK}. Exit \cmdname{windvi}.
1924
1925 You can change other parameters from there as well, such as the ability
1926 to execute system commands specified by the document (disabled by
1927 default for security reasons). Also, the first time you view any .dvi
1928 file, you may find the magnification too large. Zoom out until you get
1929 an appropriate size.
1930
1931 %There are two important parameters related to printing that can't yet
1932 %be set from the dialog boxes, namely the resolution and the \MF{} mode
1933 %for the printer. You can set them once for all by specifying them on
1934 %the command line:
1935 %\begin{verbatim}
1936 %c:\>windvi -p 360 -mfmode canonbjc foo.dvi
1937 %\end{verbatim}
1938 %When you will exit Windvi, these parameters will be stored in the
1939 %configuration file. The available modes are found in this file:\\
1940 %\path|c:\Program Files\TeXLive\texmf\metafont\misc\modes.mf|
1941
1942 All configuration settings for \cmdname{Windvi} are stored in a file
1943 named \path|windvi.cnf| file. You can find it by running this command at
1944 the prompt:
1945 \begin{verbatim}
1946 c:\>kpsewhich --expand-var $HOME/windvi.cnf
1947 \end{verbatim}
1948
1949 Should you have problems with \cmdname{Windvi}, please remove the configuration
1950 file and test your problem against a vanilla configuration.
1951
1952 \subsection{Testing}
1953
1954 For generic verification procedures, see section~\ref{sec:test-install}
1955 (\p.\pageref{sec:test-install}). This section describes
1956 Windows-specific tests.
1957
1958 Open the file \verb+sample2e.tex+ in your editor (Xemacs, WinShell),
1959 found in \path|C:\Local\TeX\texmf\tex\latex\base|. The \LaTeX\ source
1960 should appear on the screen. Process it by clicking on the
1961 \guiseq{Command\arw LaTeX} menu (XEmacs) or \LaTeX\ icon on the toolbar
1962 (WinShell), then view it by clicking on the \guiseq{Command\arw View DVI}
1963 menu (XEmacs) or Preview (Windvi) icon (WinShell).
1964
1965 At first, when you preview files with Windvi, it will create fonts because
1966 screen fonts were not installed. After a while, you will have created most
1967 of the fonts you use, and you will rarely see the font-creation window.
1968
1969 \textbf{Hint for the future:} If a \LaTeX\ run stops because \LaTeX\
1970 cannot find a file, you can press Ctrl-z to quit.
1971
1972
1973 \subsection{Printing}
1974 \label{printing}
1975
1976 It is possible to print from Windvi. In this case, printing will be done
1977 using the Windows unified printer driver. By definition, it is
1978 compatible with all printers. However, there is some drawback: it can
1979 generate some huge spool files, and some (older) versions of Windows
1980 just don't like them. The advantage is that you can use features like
1981 embedding BMP or WMF images. You also need to make sure that the printer
1982 parameters are correctly set (subsection~\ref{sub:windvi}), else you
1983 will get scaled printing (printing at 600\dpi{} on a 300\dpi{} printer
1984 will give you only one quadrant of your page).
1985
1986
1987 Printing is faster and more reliable if you run \cmdname{dvips} to make
1988 a \filename{.ps} file and then print from \cmdname{GSView}. In
1989 \cmdname{GSview}, select \guiseq{File\arw Print\ldots}. A \guiseq{Print}
1990 window will appear.
1991
1992 If you are using a \PS{} printer, \textit{be sure to select
1993 \guiseq{\PS{} Printer}}. This is done in the \guiseq{Print Method} box
1994 at the bottom left of the \guiseq{Print} window. You can then select any
1995 of the printers that you have previously installed. If you fail to
1996 check the box for \optname{\PS{} Printer}, printing will not work.
1997
1998 If you will be using your own non-\PS{} printer, select
1999 \guiseq{Ghostscript device} in the \guiseq{Print Method} box, then click
2000 on the button to the right labelled \guiseq{djet500} and select your
2001 printer type from the list that pops up. (In the older version of
2002 \cmdname{GSView}, make sure \optname{\PS{} Printer} is \textit{not}
2003 selected, then select your printer type from the \guiseq{Device} list.)
2004
2005 \subsection{Tips and tricks for Win32}
2006
2007 \subsubsection{Different flavors of Win32}
2008
2009 What we call Win32 is not an operating system by itself. It is a large
2010 set of functions (around 12,000 in the header files of the Microsoft
2011 \acro{SDK}) that you can use to write programs for different operating
2012 systems of the Windows family.
2013
2014 Windows comes in different flavors:
2015 \begin{itemize}
2016 \item Win95, Win98 and Win\acro{ME}, which \emph{are not true multitasking,
2017 multithreading} environments. They are the latest\Dash and hopefully
2018 last\Dash metamorphosis of \acro{DOS}. This can be more or less proven
2019 by the fact that when booting, the PC will load the \path|command.com|
2020 interpreter, and if you stop the boot process at this point, you can
2021 ask for the current (\acro{DOS}) version and it will answer something
2022 like \samp{MS-DOS 7.0} (at least for the old versions of Win9x).
2023 \item Windows \acro{NT}, which is a new operating system written from
2024 scratch, capable of true multitasking behavior, and including many
2025 high level features.
2026 \item Windows 2000, based on \acro{NT}, with all the bells and
2027 whistles of Win98.
2028 \item Windows \acro{XP}, which comes with Personal and Pro flavors. This is
2029 the last step in merging both lines of products (Win9x based and
2030 \acro{NT} based). \acro{XP} is based on \acro{NT}.
2031 \end{itemize}
2032
2033 Win9x are able to run 32~bits programs and 16~bits programs
2034 concurrently. But the operating system by itself is not entirely
2035 written in 32~bits mode, and does not support memory protection: 16bits
2036 applications can overwrite parts of the operating system memory! Some
2037 parts of the system like the \acro{GDI} (Graphical Device Interface)
2038 manage limited resources like bitmaps, fonts, pens and so on for the set
2039 of all programs that run concurrently. All the bitmaps headers available
2040 at the same time can't amount for more than 64kB. This explains the
2041 performance tool and the fact that you can put your system on his knees
2042 by making intensive use of graphic objects for example.
2043
2044 NT, 2K and XP do not suffer from these limitations, and neither from
2045 other Win9x limitations. They are true multitasking environments, with
2046 protected memory. They are much more responsive than Win9x because
2047 of better memory management, better file system and so on.
2048
2049 \subsubsection{Command line prompt}
2050
2051 You may wonder, ``Why would I need to use a command line prompt when
2052 I have Windows?''
2053
2054 Good question. The problem is of very general nature. Not all operations
2055 can be done easily using only a \acro{GUI}. Command line gives you
2056 programming power\Dash assuming a clever command interpreter.
2057
2058 But the problem here is more fundamental: \TeX{} is \emph{a batch}
2059 tool. Not an interactive one. \TeX{} needs to compute the best
2060 layout for each page, resolve cross-references and so on. This can be
2061 done only by a global processing of the document. It is not (yet) a
2062 task that can be done interactively.
2063
2064 This means that you should use \TeX{} from a command line. In fact the
2065 situation is not so bad. There is an advantage to write command line
2066 tools for complex processing: they are better debugged, because they are
2067 independent of any \acro{GUI} problems, and \acro{GUI} tools can be
2068 designed to interface to the command line tools. This is the case for
2069 \TeX{}, where you will mostly interact with it through a \acro{GUI} text
2070 editor.
2071
2072 However, you may need to use the command line prompt in a number of
2073 situations. One is when you are having difficulties and want to debug
2074 your setup.
2075
2076 \begin{description}
2077 \item[Win9x] You can open a command line prompt by looking either for
2078 the \acro{MS-DOS} icon in the \guiseq{Start\arw Programs} menu,
2079 or by choosing \guiseq{Start\arw Run} menu typing in
2080 \path|command.com| as the progrm name.
2081 \item[NT, 2K, XP] You can open a command line prompt by looking for
2082 \guiseq{Command Prompt} in the \guiseq{Start\arw Accessories} menu.
2083 You can also choose \guiseq{Start\arw Run} and type in
2084 \path|cmd.exe|, which is the name of the brand new command
2085 interpreter for \acro{NT} (thus, it is untrue to call this a
2086 \emph{DOS} box!).
2087 \end{description}
2088
2089 These locations may change across different Windows versions.
2090
2091
2092 \subsubsection{Path separators}
2093
2094 The Win32 API understands both \path|/| and \path|\| characters as PATH
2095 separators. But the command interpreters do not! So whenever a path name
2096 is used programmatically, you can use both separators, and even mix them
2097 up in the same path name. But on the command line, you must type
2098 \path|\| as path separator. The reason is compatibility: the command
2099 processor used \samp{/} to introduce arguments to commands.
2100
2101 All this to say: do not be surprised to read path names written using
2102 the Unix convention; \fpTeX{} is a port of \Webc, and aims to be compatible
2103 across platforms. For this reason, all the configuration files that
2104 need to specify path names use the Unix convention.
2105
2106 \subsubsection{File systems}
2107 \label{sec:clusters}
2108
2109 The worst feature of Win9x with regard to \TeX{} is probably the
2110 so-called FAT file system. \TeX{} uses very many small files, with size
2111 around 1--3kB. The \acro{FAT} file system is old, and predates by
2112 decades the multi-gigabytes hard disks we have today. As a result, it
2113 cannot manage efficiently the tens of thousands of \TeX{} files found in
2114 \TL{}. The \acro{FAT} file system allocates a minimum of 32kB for
2115 \emph{any} file on a huge partition. It means that \TeX{} will use much
2116 more disk space than it actually needs.
2117
2118 The other, more modern, file systems available, \acro{FAT32} and
2119 \acro{NTFS}, do not have this drawback. They manage clusters of 4kB
2120 only. (You can lower the limit to 512 bytes on \acro{NTFS}.)
2121
2122 \subsubsection{How to add some directory to your PATH}
2123
2124 There are pairs of variables and values which behave much like global
2125 variables inside your programs. The set of those variables is called the
2126 environment. Each program is initialized with a copy of the
2127 environment when it is run. It can request and change the
2128 value of any variable. The changes happen in the copy of the
2129 environment, and is not at all propagated to the other running
2130 programs.
2131
2132 Your PATH is a special environment variable used to search for
2133 programs you want to run.
2134 There is a different procedure to change it for Win9x, WinME and NT/2K/XP:
2135
2136 \begin{description}
2137 \item[Windows 95/98] Edit your \path|autoexec.bat|. In this file should be a line
2138 starting with \texttt{PATH=} and followed by a list of directories separated
2139 by \path|;|. Please add the directory with the executables in this line.
2140 After this, this line could look as follows:
2141 \begin{verbatim}
2142 PATH=c:\windows;c:\windows\system;c:\"Program Files"\TL\bin\win32
2143 \end{verbatim}
2144 \item[Windows ME] You need to run the special program
2145 \path|c:\windows\system\msconfig.exe| to be able to change any
2146 environment variable. From this program, select the `Environment'
2147 tab, and then add or modify the variable you want. You will be asked to reboot the
2148 machine upon any change.
2149 \item[Windows NT/2K/XP]
2150 Click left on \guiseq{Start \arw Settings \arw Control Panel}. Now the
2151 window with the control panel icons opens. Double click on System. The
2152 System Properties window opens. Click on the tab \textsf{Environment}
2153 or look for a button named \guiseq{Environment Variables} among the
2154 dialog boxes. Now you can change the environment variables for your
2155 user account. Note: There are also displayed the environment settings
2156 for the system. Normally, you can't change the system variables
2157 unless you have administrator rights on your machine. If you want to
2158 change the \texttt{PATH} for all users, you will have to contact your
2159 system administrator or be the system administrator yourself\Dash in
2160 the latter case you should know what you are doing.
2161
2162 If there is already a \texttt{PATH} setting for your user account,
2163 left click on \texttt{PATH}. In the field \textsf{Variable} appears
2164 \texttt{PATH} while the field Value shows the current setting of
2165 \texttt{PATH} as a list of directories separated by \path|;|. Add
2166 the directory where the executables are located (e.g.
2167 \path|c:\Program Files\TeXLive\bin\win32|). If there isn't a \texttt{PATH} variable
2168 for your user account, simply click in the field Variable and type
2169 in \texttt{PATH}, click in the field \textsf{Value}
2170 and type in the directory with the executables. Important: Click on
2171 the \textsf{Apply} button before clicking \textsf{Ok}, otherwise the
2172 changes to \texttt{PATH} won't apply to your system. Be careful when
2173 changing the environment settings.
2174 \end{description}
2175
2176 The best way to be sure that a variable has been properly set is to
2177 open a console and type:
2178 \begin{verbatim}
2179 set VARIABLE
2180 \end{verbatim}
2181 which should return the corresponding value.
2182
2183 \subsubsection{\TeX{} engines}
2184
2185 If you have a look at the \Webc{} documentation, you will read that all
2186 the various \TeX{} derived programs use the same base engine. For
2187 example, \path|tex.exe| and \path|latex.exe| are exact copies of the
2188 same program, but each one will use a different format file, based on
2189 its calling name.
2190
2191 Under Unix, this feature is implemented through \emph{symbolic
2192 links}. It saves up a bit of disk space, because some engines are
2193 used with many different format files.
2194
2195 The Win32 API does not know about file links. So to save up almost
2196 the same amount of memory, all the \TeX{} base engines have been put
2197 in DLLs (\emph{Dynamic Linked Library}). This means that you will have
2198 the following layout:
2199 \begin{alltt}
2200 13/05/2002 17:06 3 584 latex.exe
2201 13/05/2002 17:06 266 240 tex.dll
2202 13/05/2002 17:06 3 584 tex.exe
2203 \end{alltt}
2204 and the \path|latex.exe| file is nothing but a rough copy of
2205 \path|tex.exe| using the same core \path|tex.dll|.
2206 The same trick has been used for the \path|mktex*.exe| family of programs which are
2207 linked to the \path|mktex.dll| library.
2208
2209 In fact, a generic tool called \path|lnexe.exe| is provided to build the
2210 equivalent of Unix hard links for executable files only under Win32.
2211
2212 \subsection{In case of problems}
2213 \label{sec:troubleshooting}
2214
2215 \subsubsection{What to do if \texttt{latex} does not find your files?}
2216
2217 \begin{itemize}
2218
2219 \item \cmdname{kpsewhich} is the tool of choice to debug any
2220 problem. Unfortunately, \cmdname{kpsewhich} outputs debug information
2221 to stderr, and the Windows console does not know how to redirect stderr
2222 to a file\footnote{Well, NT and Win2k consoles know how to do that. But
2223 the trick will work for any console.}. For diagnostic purposes you can
2224 temporarily set an environment variable (in a \acro{DOS} box):
2225
2226 \begin{verbatim}
2227 SET KPATHSEA_DEBUG_OUTPUT=err.log
2228 \end{verbatim}
2229 You can also set the debug level:
2230 \begin{verbatim}
2231 SET KPATHSEA_DEBUG=-1
2232 \end{verbatim}
2233
2234 If you want to redirect stderr to stdout, which is not possible
2235 Windows, then do:
2236 \begin{verbatim}
2237 SET KPATHSEA_DEBUG_OUTPUT=con:
2238 \end{verbatim}
2239 This way you can capture both stdout and stderr in the same file.
2240
2241 \item Assuming the installation has been done in \path|c:/Program Files/TeXLive|, check
2242 the following values: \\
2243 {\small
2244 \begin{tabular}{ll}
2245 \path|kpsewhich -expand-path $SELFAUTOPARENT| & \path|c:/Program Files/TeXLive| \\
2246 \path|kpsewhich -expand-path $TEXMF| & \path|c:/Program Files/TeXLive/texmf| \\
2247 \path|kpsewhich -expand-path $TEXMFCNF| &
2248 \path|.;c:/Program Files/TeXLive/texmf/web2c;| \\
2249 & \path|c:/Program Files/TeXLive/bin/win32;| \\
2250 & \path|c:/Program Files/TeXLive/bin;| \\
2251 & \path|c:/Program Files/TeXLive| \\
2252 \path|kpsewhich -expand-var $TEXINPUTS| & \path|.;c:/Program Files/TeXLive/texmf/tex//|
2253 \end{tabular}
2254 }
2255 \item If you have other \TeX{}-related values already set in your
2256 environment, please, remove them. They are overriding the ones in
2257 texmf.cnf.
2258 \item Check the values from:\\
2259 {\small
2260 \begin{tabular}{ll}
2261 \texttt{kpsewhich cmr10.tfm} & \path|c:/Program Files/TeXLive/texmf/fonts/tfm/public/cm/cmr10.tfm|\\
2262 \texttt{kpsewhich latex.fmt}& \path|c:/Program Files/TeXLive/texmf/web2c/latex.fmt|
2263 \end{tabular}
2264 }
2265 \item At this point, if everything is correct, \TeX{} and friends
2266 should work. If it is not the case, you will need to play with
2267 the \path|-debug=n| option from \path|kpsewhich|, and check back all
2268 the values. Try to identify and report the problem.
2269 \end{itemize}
2270
2271 \subsubsection{What to do if your setup still does not work as expected?}
2272
2273 Here are several questions to investigate:
2274
2275 \begin{enumerate}
2276 \item Is \file{tex.exe} in my \path|PATH|?
2277
2278 \item Is the \path|TEXMFCNF| variable correctly set to
2279 \path|c:/Program Files/TeXLive/texmf-var/web2c| (default value)?
2280
2281 \item Are there any errors in the log file generated by the
2282 \file{TeXSetup.exe} program? You can find this by searching for the
2283 string \samp{Error}.
2284
2285 \item Are there any relevant bug fixes at \url{http://tug.org/texlive/}?
2286 (Unlikely, but it doesn't hurt to check.)
2287
2288 \item Check the web pages at
2289 \url{http://www.fptex.org/}, or consider subscribing to the \fpTeX{}
2290 mailing list, via \url{http://tug.org/mailman/listinfo/fptex}.
2291
2292 \end{enumerate}
2293
2294
2295 The \TL{} software consists of hundreds of programs and tens of
2296 thousands of files, all from varying sources. So it is quite difficult to
2297 predict all possible causes for problems. Nevertheless, we will do our
2298 best to help you. (See section~\ref{sec:help}, \p.\pageref{sec:help}.)
2299
2300
2301 \subsection{Compiling the source files}
2302
2303 The whole set of source files is available in the distribution as the
2304 \path|source/source.tar.bz2| archive, together with a separate source
2305 archive for Windows. To be able to compile the whole distribution for
2306 Windows, you will need:
2307
2308 \begin{itemize*}
2309 \item Windows 2K/XP
2310 \item Microsoft Visual Studio .Net 2003
2311 \item a set of Unix tools (\texttt{sed},
2312 \texttt{grep}, \texttt{gawk}, etc.) and also Perl, Flex and Bison,
2313 \item to adjust the paths in the
2314 \path|win32/make/common.mak| file according to your installation
2315 \item to adjust the paths in the Perl script file
2316 \path|win32/perl/build.pl|,
2317 \item run the compilation from the \path|mswin32/| directory using this
2318 command:
2319 \begin{verbatim}
2320 c:\texlive\source\mswin32>perl ./perl/build.pl --install --log=install.log
2321 \end{verbatim}
2322 \end{itemize*}
2323
2324 There is a lot of work to do to make this process easier and cleaner.
2325
2326 \subsection{Where to get more information}
2327
2328 The Windows \TeX{} system included on \TL{} is also known as
2329 \fpTeX. The packaging differs, but \fpTeX{} is no more no less than the
2330 current \TL\ release for Windows.
2331
2332 The \fpTeX{} home page is \url{http://www.fptex.org}.
2333
2334 The current \fpTeX release is available from any \CTAN site in
2335 \url{htp://www.ctan.org/tex-archive/systems/win32/fptex}.
2336
2337 The main ftp site for \fpTeX\ is \url{ftp://ftp.dante.de/pub/fptex/}
2338 from where beta versions of \fpTeX\ and additionnal tools are available.
2339 This main site is (partially) mirrored daily by all \CTAN{} sites at
2340 \path|systems/win32/fptex|.
2341
2342 The \TeX{} Users Group is kindly hosting a mailing list dedicated to
2343 \fpTeX. It is used for announcements, bug reports, enhancement requests,
2344 and general discussion about \fpTeX. To subscribe, visit
2345 \url{http://tug.org/mailman/listinfo/fptex}. The mailing list
2346 address is \email{[email protected]}.
2347
2348
2349 % don't use \Webc so the \uppercase in the headline works.
2350 \section{A user's guide to Web2C}
2351
2352 \Webc{} is an integrated collection of \TeX-related programs: \TeX{}
2353 itself, \MF{}, \MP, \BibTeX{}, etc. It is the heart of \TL{}.
2354
2355 A bit of history: The original implementation was by Tomas Rokicki who,
2356 in 1987, developed a first \TeX{}-to-C system based on change files
2357 under Unix, which were primarily the original work of Howard Trickey and
2358 Pavel Curtis. Tim Morgan became the maintainer of the system, and
2359 during this period the name changed to Web-to-C\@. In 1990, Karl Berry
2360 took over the work, assisted by dozens of additional contributors, and
2361 in 1997 he handed the baton to Olaf Weber.
2362
2363 The \Webc{} system runs on Unix, 32-bit Windows systems, \MacOSX{}, and
2364 other operating systems. It uses Knuth's original sources for \TeX{} and
2365 other basic programs written in \web{} and translates them into C source
2366 code. The core \TeX{} programs are:
2367
2368 \begin{cmddescription}
2369 \item[bibtex] Maintaining bibliographies.
2370 \item[dmp] \cmdname{troff} to MPX (\MP{} pictures).
2371 \item[dvicopy] Expands virtual font references in \dvi{} files.
2372 \item[dvitomp] \dvi{} to MPX (MetaPost pictures).
2373 \item[dvitype] \dvi{} to human-readable text.
2374 \item[gftodvi] Generic font proofsheets.
2375 \item[gftopk] Generic to packed fonts.
2376 \item[gftype] GF to human-readable text.
2377 \item[makempx] \MP{} label typesetting.
2378 \item[mf] Creating typeface families.
2379 \item[mft] Prettyprinting \MF{} source.
2380 \item[mpost] Creating technical diagrams.
2381 \item[mpto] MetaPost label extraction.
2382 \item[newer] Compare modification times.
2383 \item[patgen] Creating hyphenation patterns.
2384 \item[pktogf] Packed to generic fonts.
2385 \item[pktype] PK to human-readable text.
2386 \item[pltotf] Plain text property list to TFM.
2387 \item[pooltype] Display \web{} pool files.
2388 \item[tangle] \web{} to Pascal.
2389 \item[tex] Typesetting.
2390 \item[tftopl] TFM to plain text property list.
2391 \item[vftovp] Virtual font to virtual property list.
2392 \item[vptovf] Virtual property list to virtual font.
2393 \item[weave] \web{} to \TeX.
2394 \end{cmddescription}
2395
2396 \noindent The precise functions and syntax of these programs are
2397 described in the documentation of the individual packages and of \Webc{}
2398 itself. However, knowing a few principles governing the whole family of
2399 programs will help you take advantage of your \Webc{} installation.
2400
2401 All programs honor these standard \acro{GNU} options:
2402 \begin{ttdescription}
2403 \item[-{}-help] print basic usage summary.
2404 \item[-{}-verbose] print detailed progress report.
2405 \item[-{}-version] print version information, then exit.
2406 \end{ttdescription}
2407
2408 For locating files the \Webc{} programs use the path searching library
2409 \KPS{}. This library uses a combination of environment variables and a
2410 configuration files to optimize searching the (huge) collection of
2411 \TeX{} files. \Webc{} can look at more than one directory tree
2412 simultaneously, which is useful in maintaining \TeX's standard
2413 distribution and local extensions in two distinct trees. To speed up
2414 file searches the root of each tree has a file \file{ls-R}, containing
2415 an entry showing the name and relative pathname for all files under that
2416 root.
2417
2418 \subsection{Kpathsea path searching}
2419
2420 Let us first describe the generic path searching mechanism of the \KPS{}
2421 library.
2422
2423 We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list
2424 of \emph{path elements}, which are basically directory names. A
2425 search path can come from (a combination of) many sources. To look up
2426 a file \samp{my-file} along a path \samp{.:/dir}, \KPS{} checks each
2427 element of the path in turn: first \file{./my-file}, then
2428 \file{/dir/my-file}, returning the first match (or possibly all
2429 matches).
2430
2431 In order to adapt optimally to all operating systems' conventions, on
2432 non-Unix systems \KPS{} can use filename separators different from
2433 colon (\samp{:}) and slash (\samp{/}).
2434
2435 To check a particular path element \var{p}, \KPS{} first checks if a
2436 prebuilt database (see ``Filename data\-base'' on
2437 page~\pageref{Filename-database}) applies to \var{p}, i.e., if the database
2438 is in a directory that is a prefix of \var{p}. If so, the path
2439 specification is matched against the contents of the database.
2440
2441 If the database does not exist, or does not apply to this path
2442 element, or contains no matches, the filesystem is searched (if this
2443 was not forbidden by a specification starting with \samp{!!}\ and if
2444 the file being searched for must exist). \KPS{} constructs the list
2445 of directories that correspond to this path element, and then checks
2446 in each for the file being sought.
2447
2448 The ``file must exist'' condition comes into play with \samp{.vf} files and
2449 input files read by \TeX's \cs{openin} command. Such files may not
2450 exist (e.g., \file{cmr10.vf}), and so it would be wrong to search the
2451 disk for them. Therefore, if you fail to update \file{ls-R} when you
2452 install a new \samp{.vf} file, it will never be found.
2453 Each path element is checked in turn: first the database, then the
2454 disk. If a match is found, the search stops and the result is
2455 returned.
2456
2457 Although the simplest and most common path element is a directory
2458 name, \KPS{} supports additional features in search paths: layered
2459 default values, environment variable names, config file values, users'
2460 home directories, and recursive subdirectory searching. Thus, we say
2461 that \KPS{} \emph{expands} a path element, meaning it transforms all
2462 the specifications into basic directory name or names. This is
2463 described in the following sections in the same order as it takes
2464 place.
2465
2466 Note that if the filename being searched for is absolute or explicitly
2467 relative, i.e., starts with \samp{/} or \samp{./} or \samp{../},
2468 \KPS{} simply checks if that file exists.
2469
2470 \ifSingleColumn
2471 \else
2472 \begin{figure*}
2473 \verbatiminput{examples/ex5.tex}
2474 \setlength{\abovecaptionskip}{0pt}
2475 \caption{An illustrative configuration file sample}
2476 \label{fig:config-sample}
2477 \end{figure*}
2478 \fi
2479
2480 \subsubsection{Path sources}
2481 \label{Path-sources}
2482
2483 A search path can come from many sources. In the order in which
2484 \KPS{} uses them:
2485
2486 \begin{enumerate}
2487 \item
2488 A user-set environment variable, for instance, \envname{TEXINPUTS}\@.
2489 Environment variables with a period and a program name appended
2490 override; e.g., if \samp{latex} is the name of the program being run,
2491 then \envname{TEXINPUTS.latex} will override \envname{TEXINPUTS}.
2492 \item
2493 A program-specific configuration file, for exam\-ple, a line
2494 \samp{S /a:/b} in \cmdname{dvips}'s \file{config.ps}.
2495 \item A \KPS{} configuration file \file{texmf.cnf}, containing a line like
2496 \samp{TEXINPUTS=/c:/d} (see below).
2497 \item The compile-time default.
2498 \end{enumerate}
2499 \noindent You can see each of these values for a given
2500 search path by using the debugging options (see ``Debugging actions''
2501 on page~\pageref{Debugging}).
2502
2503 \subsubsection{Config files}
2504
2505 \begingroup\tolerance=3500
2506 \KPS{} reads \emph{runtime configuration files} named \file{texmf.cnf}
2507 for search path and other definitions. The search path used to look
2508 for these files is named \envname{TEXMFCNF} (by default such a file lives
2509 in the \file{texmf/web2c} subdirectory). \emph{All}
2510 \file{texmf.cnf} files in the search path will be read and definitions
2511 in earlier files override those in later files. Thus, with a search
2512 path of \verb|.:$TEXMF|, values from \file{./texmf.cnf} override those
2513 from \verb|$TEXMF/texmf.cnf|.
2514 \endgroup
2515
2516 \begin{itemize}
2517 \item
2518 Comments start with \code{\%} and continue to the end of the line.
2519 \item
2520 Blank lines are ignored.
2521 \item
2522 A \bs{} at the end of a line acts as a continuation character,
2523 i.e., the next line is appended. Whitespace at the beginning of
2524 continuation lines is not ignored.
2525 \item
2526 Each remaining line has the form:
2527 \begin{alltt}
2528 \var{variable}[.\var{progname}] [=] \var{value}
2529 \end{alltt}%
2530 where the \samp{=} and surrounding whitespace are optional.
2531 \item
2532 The \ttvar{variable} name may contain any character other
2533 than whitespace, \samp{=}, or \samp{.}, but sticking to
2534 \samp{A-Za-z\_} is safest.
2535 \item
2536 If \samp{.\var{progname}} is present, the definition only
2537 applies if the program that is running is named
2538 \texttt{\var{progname}} or \texttt{\var{progname}.exe}. This allows
2539 different flavors of \TeX{} to have different search paths, for
2540 example.
2541 \item \var{value} may contain any characters except
2542 \code{\%} and \samp{@}. The
2543 \code{\$\var{var}.\var{prog}} feature is not available on the
2544 right-hand side; instead, you must use an additional variable. A
2545 \samp{;}\ in \var{value} is translated to \samp{:}\ if
2546 running under Unix; this is useful to be able to have a single
2547 \file{texmf.cnf} for Unix, \acro{MS-DOS} and Windows systems.
2548 \item
2549 All definitions are read before anything is expanded, so
2550 variables can be referenced before they are defined.
2551 \end{itemize}
2552 A configuration file fragment illustrating most of these points is
2553 \ifSingleColumn
2554 shown below:
2555
2556 \verbatiminput{examples/ex5.tex}
2557 \else
2558 shown in Figure~\ref{fig:config-sample}.
2559 \fi
2560
2561 \subsubsection{Path expansion}
2562 \label{Path-expansion}
2563
2564
2565 \KPS{} recognizes certain special characters and constructions in
2566 search paths, similar to those available in Unix shells. As a
2567 general example, the complex path,
2568 \verb+~$USER/{foo,bar}//baz+, expands to all subdirectories under
2569 directories \file{foo} and \file{bar} in \texttt{\$USER}'s home
2570 directory that contain a directory or file \file{baz}. These
2571 expansions are explained in the sections below.
2572 %$
2573 \subsubsection{Default expansion}
2574 \label{Default-expansion}
2575
2576 \tolerance=2500
2577 If the highest-priority search path (see ``Path sources'' on
2578 page~\pageref{Path-sources}) contains an \emph{extra colon} (i.e.,
2579 leading, trailing, or doubled), \KPS{} inserts at that point the
2580 next-highest-prio\-rity search path that is defined. If that inserted
2581 path has an extra colon, the same happens with the next highest. For
2582 example, given an environment variable setting
2583
2584 \tolerance=1500
2585
2586 \begin{alltt}
2587 > \Ucom{setenv TEXINPUTS /home/karl:}
2588 \end{alltt}
2589 and a \code{TEXINPUTS} value from \file{texmf.cnf} of
2590
2591 \begin{alltt}
2592 .:\$TEXMF//tex
2593 \end{alltt}
2594 then the final value used for searching will be:
2595
2596 \begin{alltt}
2597 /home/karl:.:\$TEXMF//tex
2598 \end{alltt}
2599
2600 Since it would be useless to insert the default value in more than one
2601 place, \KPS{} changes only one extra \samp{:}\ and leaves any others in
2602 place. It checks first for a leading \samp{:}, then a trailing
2603 \samp{:}, then a doubled \samp{:}.
2604
2605 \subsubsection{Brace expansion}
2606
2607 A useful feature is brace expansion, which means that, for instance,
2608 \verb+v{a,b}w+ expands to \verb+vaw:vbw+. Nesting is allowed.
2609 This can be used to implement multiple \TeX{} hierarchies, by
2610 assigning a brace list to \code{\$TEXMF}.
2611 For example, in \file{texmf.cnf}, you find
2612 the following definition:
2613 \begin{verbatim}
2614 TEXMF = {$HOMETEXMF,$TEXMFLOCAL,!!$VARTEXMF,!!$TEXMFMAIN}
2615 \end{verbatim}
2616 Using this you can then write something like
2617 \begin{verbatim}
2618 TEXINPUTS = .;$TEXMF/tex//
2619 \end{verbatim}
2620 %$
2621 which means that, after looking in the current directory, the
2622 \code{\$HOMETEXMF/tex}, \code{\$TEXMFLOCAL/tex}, \code{\$VARTEXMF/tex}
2623 and \code{\$TEXMFMAIN/tex} trees \emph{only}) will be searched (the
2624 last two use using \file{ls-R} data base files). It is a convenient
2625 way for running two parallel \TeX{} structures, one ``frozen'' (on a
2626 \CD, for instance) and the other being continuously updated with new
2627 versions as they become available. By using the \code{\$TEXMF}
2628 variable in all definitions, one is sure to always search the
2629 up-to-date tree first.
2630
2631 \subsubsection{Subdirectory expansion}
2632 \label{Subdirectory-expansion}
2633
2634 Two or more consecutive slashes in a path element following a directory
2635 \var{d} is replaced by all subdirectories of \var{d}: first those
2636 subdirectories directly under \var{d}, then the subsubdirectories under
2637 those, and so on. At each level, the order in which the directories are
2638 searched is \emph{unspecified}.
2639
2640 If you specify any filename components after the \samp{//}, only
2641 subdirectories with matching components are included. For example,
2642 \samp{/a//b} expands into directories \file{/a/1/b}, \file{/a/2/b},
2643 \file{/a/1/1/b}, and so on, but not \file{/a/b/c} or \file{/a/1}.
2644
2645 Multiple \samp{//} constructs in a path are possible, but
2646 \samp{//} at the beginning of a path is ignored.
2647
2648 \subsubsection{List of special characters and their meaning: a summary}
2649
2650 The following list summarizes the special characters in \KPS{}
2651 configuration files.
2652
2653 % need a wider space for the item labels here.
2654 \newcommand{\CODE}[1]{\makebox[3em][l]{\code{#1}}}
2655 \begin{ttdescription}
2656 \item[\CODE{:}] Separator in path specification; at the beginning or
2657 the end of a path it substitutes the default path expansion.\par
2658 \item[\CODE{;}] Separator on non-Unix systems (acts like \code{:}).
2659 \item[\CODE{\$}] Variable expansion.
2660 \item[\CODE{\string~}] Represents the user's home directory.
2661 \item[\CODE{\char`\{...\char`\}}] Brace expansion.
2662 \item[\CODE{//}] Subdirectory expansion (can occur anywhere in
2663 a path, except at its beginning).
2664 \item[\CODE{\%}] Start of comment.
2665 \item[\CODE{\bs}] Continuation character (allows multi-line entries).
2666 \item[\CODE{!!}] Search \emph{only} database to locate file, \emph{do
2667 not} search the disk.
2668 \end{ttdescription}
2669
2670
2671 \subsection{Filename databases}
2672 \label{Filename-database}
2673
2674 \KPS{} goes to some lengths to minimize disk accesses for searches.
2675 Nevertheless, at installations with enough directories, searching each
2676 possible directory for a given file can take an excessively long time
2677 (this is especially true if many hundreds of font directories have to
2678 be traversed.) Therefore, \KPS{} can use an externally-built plain text
2679 ``database'' file named \file{ls-R} that maps files to directories,
2680 thus avoiding the need to exhaustively search the disk.
2681
2682 A second database file \file{aliases} allows you to give additional
2683 names to the files listed in \file{ls-R}. This can be helpful to
2684 confirm to \acro{DOS} 8.3 filename conventions in source files.
2685
2686 \subsubsection{The filename database}
2687 \label{ls-R}
2688
2689 As explained above, the name of the main filename database must be
2690 \file{ls-R}. You can put one at the root of each \TeX{} hierarchy in
2691 your installation that you wish to be searched (\code{\$TEXMF} by
2692 default); most sites have only one hierarchy. \KPS{} looks for
2693 \file{ls-R} files along the \code{TEXMFDBS} path.
2694
2695 The recommended way to create and maintain \samp{ls-R} is to run the
2696 \code{mktexlsr} script included with the distribution. It is invoked
2697 by the various \samp{mktex}\dots\ scripts. In principle, this script
2698 just runs the command
2699 \begin{alltt}
2700 cd \var{/your/texmf/root} && \path|\|ls -1LAR ./ >ls-R
2701 \end{alltt}
2702 presuming your system's \code{ls} produces the right output format
2703 (\acro{GNU} \code{ls} is all right). To ensure that the database is
2704 always up-to-date, it is easiest to rebuild it regularly via
2705 \code{cron}, so that it is automatically updated when the installed
2706 files change, such as after installing or updating a \LaTeX{} package.
2707
2708 If a file is not found in the database, by default \KPS{} goes ahead
2709 and searches the disk. If a particular path element begins with
2710 \samp{!!}, however, \emph{only} the database will be searched for that
2711 element, never the disk.
2712
2713
2714 \subsubsection{kpsewhich: Standalone path searching}
2715 \label{Invoking-kpsewhich}
2716
2717 The \texttt{kpsewhich} program exercises path searching independent of any
2718 particular application. This can be useful as a sort of \code{find}
2719 program to locate files in \TeX{} hierarchies (this is used heavily in
2720 the distributed \samp{mktex}\dots\ scripts).
2721
2722 \begin{alltt}
2723 > \Ucom{kpsewhich \var{option}\dots{} \var{filename}\dots{}}
2724 \end{alltt}
2725 The options specified in \ttvar{option} start with either \samp{-}
2726 or \samp{-{}-}, and any unambiguous abbreviation is accepted.
2727
2728 \KPS{} looks up each non-option argument on the command line as a
2729 filename, and returns the first file found. There is no option to
2730 return all the files with a particular name (you can run the Unix
2731 \samp{find} utility for that).
2732
2733 The more important options are described next.
2734
2735 \begin{ttdescription}
2736 \item[\texttt{-{}-dpi=\var{num}}]\mbox{}
2737 Set the resolution to \ttvar{num}; this only affects \samp{gf}
2738 and \samp{pk} lookups. \samp{-D} is a synonym, for compatibility
2739 with \cmdname{dvips}. Default is 600.
2740
2741 \item[\texttt{-{}-format=\var{name}}]\mbox{}\\
2742 Set the format for lookup to \ttvar{name}. By default, the
2743 format is guessed from the filename. For formats which do not have
2744 an associated unambiguous suffix, such as \MP{} support files and
2745 \cmdname{dvips} configuration files, you have to specify the name as
2746 found in the first column of table~\ref{tab:kpathsea}, which lists
2747 currently recognized names, a description, possible file extensions,
2748 and associated environment variables.
2749 \end{ttdescription}
2750
2751
2752 \def\KpathKey#1#2#3#4#5{% name, number, description, variables,
2753 % suffixes
2754 \SetRowColor#1 & #3 & #4 & #5\\}
2755 \def\HEAD#1{\multicolumn{1}{l}{\emph{#1}}}
2756 %
2757 \begin{small}
2758 % a footnoterule immediately under a bottom-of-page rule looks dead
2759 % silly, so we suppress it
2760 \renewcommand\footnoterule{\relax}
2761 %
2762 \begin{longtable}{@{}%
2763 >{\ttfamily}P{.16\textwidth}% Col.1
2764 P{.3\textwidth}% Col 2
2765 >{\ttfamily\footnotesize}P{.29\textwidth}% Col 3
2766 >{\ttfamily}P{.14\textwidth}% Col 4
2767 @{}}
2768 \caption{Kpathsea file types.}\label{tab:kpathsea}\\
2769 \emph{Name} & \HEAD{Description} & \HEAD{Variables}
2770 & \HEAD{Suffixes}\\
2771 \hline
2772 \endfirsthead
2773 \multicolumn{3}{l}{Kpathsea file types \emph{continued}}\\
2774 \emph{Name} & \HEAD{Description} & \HEAD{Variables}
2775 & \HEAD{Suffixes}\\
2776 \hline
2777 \noalign{\vspace{2pt}}
2778 \endhead
2779 \mbox{}\\
2780 \hline
2781 \endfoot
2782 \KpathKey
2783 {afm}
2784 {4}
2785 {Adobe font metrics}
2786 {AFMFONTS}
2787 {.afm}
2788 \KpathKey
2789 {base}
2790 {5}
2791 {Metafont memory dump}
2792 {MFBASES, TEXMFINI}
2793 {.base}
2794 \KpathKey
2795 {bib}
2796 {6}
2797 {\BibTeX{} bibliography source}
2798 {BIBINPUTS, TEXBIB}
2799 {.bib}
2800 \KpathKey
2801 {}
2802 {2}
2803 {bitmap fonts}
2804 {GLYPHFONTS, TEXFONTS}
2805 {}
2806 \KpathKey
2807 {bst}
2808 {7}
2809 {\BibTeX{} style files}
2810 {BSTINPUTS}
2811 {.bst}
2812 \KpathKey
2813 {cnf}
2814 {8}
2815 {Runtime configuration files}
2816 {TEXMFCNF}
2817 {.cnf}
2818 \KpathKey
2819 {dvips config}
2820 {34}
2821 {\textsf{dvips} configuration files, e.g., \file{config.ps}}
2822 {TEXCONFIG}
2823 {}
2824 \KpathKey
2825 {enc}
2826 {34}
2827 {Font encoding files}
2828 {ENCFONTS}
2829 {.enc}
2830 \KpathKey
2831 {fmt}
2832 {10}
2833 {\TeX{} memory dump}
2834 {TEXFORMATS, TEXMFINI}
2835 {.fmt, .efmt, .efm}
2836 \KpathKey
2837 {gf}
2838 {0}
2839 {generic font bitmap}
2840 {GFFONTS}
2841 {.gf}
2842 \KpathKey
2843 {graphic/figure}
2844 {25}
2845 {Encapsulated \PS{} figures}
2846 {TEXPICTS, TEXINPUTS}
2847 {.eps, .epsi}
2848 \KpathKey
2849 {ist}
2850 {35}
2851 {\textsf{makeindex} style files}
2852 {TEXINDEXSTYLE, INDEXSTYLE}
2853 {.ist}
2854 \KpathKey
2855 {ls-R}
2856 {9}
2857 {Filename databases}
2858 {TEXMFDBS}
2859 {}
2860 \KpathKey
2861 {map}
2862 {11}
2863 {Fontmaps}
2864 {TEXFONTMAPS}
2865 {.map}
2866 \KpathKey
2867 {mem}
2868 {12}
2869 {MetaPost memory dump}
2870 {MPMEMS, TEXMFINI}
2871 {.mem}
2872 \KpathKey
2873 {mf}
2874 {13}
2875 {Metafont source}
2876 {MFINPUTS}
2877 {.mf}
2878 \KpathKey
2879 {mfpool}
2880 {14}
2881 {Metafont program strings}
2882 {MFPOOL, TEXMFINI}
2883 {.pool}
2884 \KpathKey
2885 {mft}
2886 {15}
2887 {MFT style file}
2888 {MFTINPUTS}
2889 {.mft}
2890 \KpathKey
2891 {}
2892 {41}
2893 {miscellaneous fonts}
2894 {MISCFONTS}
2895 {}
2896 \KpathKey
2897 {mp}
2898 {16}
2899 {MetaPost source}
2900 {MPINPUTS}
2901 {.mp}
2902 \KpathKey
2903 {mppool}
2904 {17}
2905 {MetaPost program strings}
2906 {MPPOOL, TEXMFINI}
2907 {.pool}
2908 \KpathKey
2909 {MetaPost support}
2910 {18}
2911 {MetaPost support files, used by DMP}
2912 {MPSUPPORT}
2913 {}
2914 \KpathKey
2915 {ocp}
2916 {19}
2917 {\OMEGA{} compiled process files}
2918 {OCPINPUTS}
2919 {.ocp}
2920 \KpathKey
2921 {ofm}
2922 {20}
2923 {\OMEGA{} font metrics}
2924 {OFMFONTS, TEXFONTS}
2925 {.ofm, .tfm}
2926 \KpathKey
2927 {opl}
2928 {21}
2929 {\OMEGA{} property lists}
2930 {OPLFONTS, TEXFONTS}
2931 {.opl}
2932 \KpathKey
2933 {otp}
2934 {22}
2935 {\OMEGA{} translation process files}
2936 {OTPINPUTS}
2937 {.otp}
2938 \KpathKey
2939 {ovf}
2940 {23}
2941 {\OMEGA{} virtual fonts}
2942 {OVFFONTS, TEXFONTS}
2943 {.ovf}
2944 \KpathKey
2945 {ovp}
2946 {24}
2947 {\OMEGA{} virtual property lists}
2948 {OVPFONTS, TEXFONTS}
2949 {.ovp}
2950 \KpathKey
2951 {pdftex config}
2952 {18}
2953 {\textsf{pdftex} configuration files}
2954 {PDFTEXCONFIG}
2955 {}
2956 \KpathKey
2957 {pk}
2958 {1}
2959 {packed bitmap fonts}
2960 {\var{program}FONTS \textrm{(\texttt{\var{program}} being
2961 \textsmaller{\cmdname{XDVI}},
2962 etc.)}, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS}
2963 {.pk}
2964 \KpathKey
2965 {\PS{} header}
2966 {30}
2967 {downloadable \PS{}}
2968 {TEXPSHEADERS, PSHEADERS}
2969 {.pro, .enc}
2970 \KpathKey
2971 {tex}
2972 {26}
2973 {\TeX{} source}
2974 {TEXINPUTS}
2975 {.tex, .cls, .sty, .clo, .def}
2976 \KpathKey
2977 {texmfscripts}
2978 {20}
2979 {Scripts distributed in the \file{texmf} tree}
2980 {TEXMFSCRIPTS}
2981 {}
2982 \KpathKey
2983 {TeX system documentation}
2984 {27}
2985 {Documentation files for the \TeX{} system}
2986 {TEXDOCS}
2987 {}
2988 \KpathKey
2989 {TeX system sources}
2990 {29}
2991 {Source files for the \TeX{} system}
2992 {TEXSOURCES}
2993 {}
2994 \KpathKey
2995 {texpool}
2996 {28}
2997 {\TeX{} program strings}
2998 {TEXPOOL, TEXMFINI}
2999 {.pool}
3000 \KpathKey
3001 {tfm}
3002 {3}
3003 {\TeX{} font metrics}
3004 {TFMFONTS, TEXFONTS}
3005 {.tfm}
3006 \KpathKey
3007 {Troff fonts}
3008 {31}
3009 {Troff fonts, used by DMP}
3010 {TRFONTS}
3011 {}
3012 \KpathKey
3013 {truetype fonts}
3014 {36}
3015 {TrueType outline fonts}
3016 {TTFONTS}
3017 {.ttf, .ttc}
3018 \KpathKey
3019 {Type~1 fonts}
3020 {32}
3021 {Type 1 \PS{} outline fonts}
3022 {T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS}
3023 {.pfa, .pfb}
3024 \KpathKey
3025 {type42 fonts}
3026 {37}
3027 {Type 42 \PS{} outline fonts}
3028 {T42FONTS}
3029 {}
3030 \KpathKey
3031 {vf}
3032 {33}
3033 {virtual fonts}
3034 {VFFONTS, TEXFONTS}
3035 {.vf}
3036 \KpathKey
3037 {web2c files}
3038 {38}
3039 {\Webc{} support files}
3040 {WEB2C}
3041 {}
3042 \KpathKey
3043 {other text files}
3044 {39}
3045 {text files used by `\textsf{foo}'}
3046 {FOOINPUTS}
3047 {}
3048 \KpathKey
3049 {other binary files}
3050 {40}
3051 {binary files used by `\textsf{foo}'}
3052 {FOOINPUTS}
3053 {}
3054 \end{longtable}
3055 \end{small}
3056
3057
3058 \begin{multicols}{2}
3059
3060 The last two entries in table~\ref{tab:kpathsea} are special
3061 cases, where the paths and environment variables depend on the name
3062 of the program: the variable name is constructed by converting the
3063 program name to upper case, and then appending \texttt{INPUTS}.
3064
3065 The environment variables are set by default in the configuration
3066 file \file{texmf.cnf}. It is only when you want to override one or
3067 more of the values specified in that file that you might want to set
3068 them explicitly in your execution environment.
3069
3070 The \samp{-{}-format} and \samp{-{}-path} options are mutually
3071 exclusive.
3072
3073 \begin{ttdescription}
3074
3075 \item[\texttt{-{}-mode=\var{string}}]\mbox{}\\
3076 Set the mode name to \ttvar{string}; this only affects \samp{gf}
3077 and \samp{pk} lookups. No default: any mode will be found.
3078 \item[\texttt{-{}-must-exist}]\mbox{}\\
3079 Do everything possible to find the files, notably including
3080 searching the disk. By default, only the \file{ls-R} database is
3081 checked, in the interest of efficiency.
3082 \item[\texttt{-{}-path=\var{string}}]\mbox{}\\
3083 Search along the path \ttvar{string} (colon-separated as usual),
3084 instead of guessing the search path from the filename. \samp{//} and
3085 all the usual expansions are supported. The options \samp{-{}-path}
3086 and \samp{-{}-format} are mutually exclusive.
3087 \item[\texttt{-{}-progname=\var{name}}]\mbox{}\\
3088 Set the program name to \texttt{\var{name}}.
3089 This can affect the search paths via the \texttt{.\var{progname}}
3090 feature.
3091 The default is \cmdname{kpsewhich}.
3092 \item[\texttt{-{}-show-path=\var{name}}]\mbox{}\\
3093 shows the path used for file lookups of file type \texttt{\var{name}}.
3094 Either a filename extension (\code{.pk}, \code{.vf}, etc.) or a
3095 name can be used, just as with \samp{-{}-format} option.
3096 \item[\texttt{-{}-debug=\var{num}}]\mbox{}\\
3097 sets the debugging options to \texttt{\var{num}}.
3098 \end{ttdescription}
3099
3100
3101 \subsubsection{Examples of use}
3102 \label{SExamplesofuse}
3103
3104 Let us now have a look at \KPS{} in action. Here's a straightforward search:
3105
3106 \begin{alltt}
3107 > \Ucom{kpsewhich article.cls}
3108 /usr/local/texmf-dist/tex/latex/base/article.cls
3109 \end{alltt}
3110 We are looking for the file \file{article.cls}. Since the \samp{.cls}
3111 suffix is unambiguous we do not need to specify that we want to look for a
3112 file of type \optname{tex} (\TeX{} source file directories). We find it in
3113 the subdirectory \file{tex/latex/base} below the \samp{texmf-dist} \TL\
3114 directory. Similarly, all of the following are found without problems
3115 thanks to their unambiguous suffix.
3116 \begin{alltt}
3117 > \Ucom{kpsewhich array.sty}
3118 /usr/local/texmf-dist/tex/latex/tools/array.sty
3119 > \Ucom{kpsewhich latin1.def}
3120 /usr/local/texmf-dist/tex/latex/base/latin1.def
3121 > \Ucom{kpsewhich size10.clo}
3122 /usr/local/texmf-dist/tex/latex/base/size10.clo
3123 > \Ucom{kpsewhich small2e.tex}
3124 /usr/local/texmf-dist/tex/latex/base/small2e.tex
3125 > \Ucom{kpsewhich tugboat.bib}
3126 /usr/local/texmf-dist/bibtex/bib/beebe/tugboat.bib
3127 \end{alltt}
3128
3129 That last is a \BibTeX{} bibliography database for \textsl{TUGBoat} articles.
3130
3131 \begin{alltt}
3132 > \Ucom{kpsewhich cmr10.pk}
3133 \end{alltt}
3134 Font bitmap glyph files of type \file{.pk} are used by display
3135 programs like \cmdname{dvips} and \cmdname{xdvi}. Nothing is returned in
3136 this case since there are no pre-generated Computer Modern \samp{.pk}
3137 files in \TL{}\Dash the Type~1 variants are used by default.
3138 \begin{alltt}
3139 > \Ucom{kpsewhich wsuipa10.pk}
3140 \ifSingleColumn /usr/local/texmf-var/fonts/pk/ljfour/public/wsuipa/wsuipa10.600pk
3141 \else /usr/local/texmf-var/fonts/pk/ljfour/public/
3142 ... wsuipa/wsuipa10.600pk
3143 \fi\end{alltt}
3144
3145 For these fonts (a phonetic alphabet from the University of Washington)
3146 we had to generate \samp{.pk} files, and since the default \MF{} mode on
3147 our installation is \texttt{ljfour} with a base resolution of 600\dpi{}
3148 (dots per inch), this instantiation is returned.
3149 \begin{alltt}
3150 > \Ucom{kpsewhich -dpi=300 wsuipa10.pk}
3151 \end{alltt}
3152 In this case, when specifying that we are interested in a resolution
3153 of 300\dpi{} (\texttt{-dpi=300}) we see that no such font is available on
3154 the system. A program like \cmdname{dvips} or \cmdname{xdvi} would
3155 go off and actually build the required \texttt{.pk} files
3156 using the script \cmdname{mktexpk}.
3157
3158 Next we turn our attention to \cmdname{dvips}'s header and configuration
3159 files. We first look at one of the commonly used files, the general
3160 prolog \file{tex.pro} for \TeX{} support, before turning our attention
3161 to the generic configuration file (\file{config.ps}) and the \PS{} font
3162 map \file{psfonts.map}\Dash as of 2004, map and encoding files have
3163 their own search paths and new location in \dirname{texmf} trees. As
3164 the \samp{.ps} suffix is ambiguous we have to specify explicitly which
3165 type we are considering (\optname{dvips config}) for the file
3166 \texttt{config.ps}.
3167 \begin{alltt}
3168 > \Ucom{kpsewhich tex.pro}
3169 /usr/local/texmf/dvips/base/tex.pro
3170 > \Ucom{kpsewhich --format="dvips config" config.ps}
3171 /usr/local/texmf/dvips/config/config.ps
3172 > \Ucom{kpsewhich psfonts.map}
3173 /usr/local/texmf/fonts/map/dvips/updmap/psfonts.map
3174 \end{alltt}
3175
3176 We now take a closer look at the \acro{URW} Times \PS{} support
3177 files. The prefix for these in the standard font naming scheme is
3178 \samp{utm}. The first file we look at is the configuration file,
3179 which contains the name of the map file:
3180 \begin{alltt}
3181 > \Ucom{kpsewhich --format="dvips config" config.utm}
3182 /usr/local/texmf-dist/dvips/psnfss/config.utm
3183 \end{alltt}
3184 The contents of that file is
3185 \begin{alltt}
3186 p +utm.map
3187 \end{alltt}
3188 which points to the file \file{utm.map}, which we want to
3189 locate next.
3190 \begin{alltt}
3191 > \Ucom{kpsewhich utm.map}
3192 /usr/local/texmf-dist/fonts/map/dvips/times/utm.map
3193 \end{alltt}
3194 This map file defines the file names of the Type~1 \PS{} fonts in
3195 the URW collection. Its contents look like (we only show part of the
3196 lines):
3197 \begin{alltt}
3198 utmb8r NimbusRomNo9L-Medi ... <utmb8a.pfb
3199 utmbi8r NimbusRomNo9L-MediItal... <utmbi8a.pfb
3200 utmr8r NimbusRomNo9L-Regu ... <utmr8a.pfb
3201 utmri8r NimbusRomNo9L-ReguItal... <utmri8a.pfb
3202 utmbo8r NimbusRomNo9L-Medi ... <utmb8a.pfb
3203 utmro8r NimbusRomNo9L-Regu ... <utmr8a.pfb
3204 \end{alltt}
3205 Let us, for instance, take the Times Roman instance
3206 \file{utmr8a.pfb} and find its position in the \file{texmf} directory
3207 tree with a search for Type~1 font files:
3208 \begin{alltt}
3209 > \Ucom{kpsewhich utmr8a.pfb}
3210 \ifSingleColumn /usr/local/texmf-dist/fonts/type1/urw/times/utmr8a.pfb
3211 \else /usr/local/texmf-dist/fonts/type1/
3212 ... urw/utm/utmr8a.pfb
3213 \fi\end{alltt}
3214
3215 It should be evident from these examples how you can easily locate the
3216 whereabouts of a given file. This is especially important if you suspect
3217 that the wrong version of a file is picked up somehow, since
3218 \cmdname{kpsewhich} will show you the first file encountered.
3219
3220 \subsubsection{Debugging actions}
3221 \label{Debugging}
3222
3223 Sometimes it is necessary to investigate how a program resolves file
3224 references. To make this practical, \KPS{} offers various levels of
3225 debugging output:
3226
3227 \begin{ttdescription}
3228 \item[\texttt{\ 1}] \texttt{stat} calls (disk lookups). When running
3229 with an up-to-date \file{ls-R} database this should almost give no
3230 output.
3231 \item[\texttt{\ 2}] References to hash tables (such as \file{ls-R}
3232 databases, map files, configuration files).
3233 \item[\texttt{\ 4}] File open and close operations.
3234 \item[\texttt{\ 8}] General path information for file types
3235 searched by \KPS. This is useful to find out where a particular
3236 path for the file was defined.
3237 \item[\texttt{16}] Directory list for each path element (only relevant
3238 for searches on disk).
3239 \item[\texttt{32}] File searches.
3240 \end{ttdescription}
3241 A value of \texttt{-1} will set all the above options; in practice,
3242 this is usually the most convenient.
3243
3244 Similarly, with the \cmdname{dvips} program, by setting a combination of
3245 debug switches, one can follow in detail where files are being picked up
3246 from. Alternatively, when a file is not found, the debug trace shows in
3247 which directories the program looks for the given file, so that one can
3248 get an indication what the problem~is.
3249
3250 Generally speaking, as most programs call the \KPS{} library
3251 internally, one can select a debug option by using the
3252 \envname{KPATHSEA\_DEBUG} environment variable, and setting it to (a
3253 combination of) values as described in the above list.
3254
3255 (Note for Windows users: it is not easy to redirect
3256 all messages to a file in this system. For diagnostic purposes
3257 you can temporarily \texttt{SET KPATHSEA\_DEBUG\_OUTPUT=err.log}).
3258
3259 Let us consider, as an example, a small \LaTeX{} source file,
3260 \file{hello-world.tex}, which contains the following input.
3261 \begin{verbatim}
3262 \documentclass{article}
3263 \begin{document}
3264 Hello World!
3265 \end{document}
3266 \end{verbatim}
3267 This little file only uses the font \file{cmr10}, so let us look
3268 how \cmdname{dvips} prepares the \PS{} file (we want to use the Type~1
3269 version of the Computer Modern fonts, hence the option \texttt{-Pcms}).
3270 \begin{alltt}
3271 > \Ucom{dvips -d4100 hello-world -Pcms -o}
3272 \end{alltt}
3273 In this case we have combined \cmdname{dvips}'s debug class 4 (font
3274 paths) with \KPS's path element expansion (see \cmdname{dvips} Reference
3275 Manual, \OnCD{texmf/doc/html/dvips/dvips_toc.html}).
3276 The output (slightly rearranged) appears in
3277 Figure~\ref{fig:dvipsdbga}.
3278 \begin{figure*}[tp]
3279 \centering
3280 \input{examples/ex6a.tex}
3281 \caption{Finding configuration files}\label{fig:dvipsdbga}
3282
3283 \bigskip
3284
3285 \input{examples/ex6b.tex}
3286 \caption{Finding the prolog file}\label{fig:dvipsdbgb}
3287
3288 \bigskip
3289
3290 \input{examples/ex6c.tex}
3291 \caption{Finding the font file}\label{fig:dvipsdbgc}
3292 \end{figure*}
3293
3294 \cmdname{dvips} starts by locating its working files. First,
3295 \file{texmf.cnf} is found, which gives the definitions of the search
3296 paths for the other files, then the file database \file{ls-R} (to
3297 optimize file searching) and the file \file{aliases}, which makes it
3298 possible to declare several names (e.g., a short \acro{DOS}-like 8.3 and
3299 a more natural longer version) for the same file. Then \cmdname{dvips}
3300 goes on to find the generic configuration file \file{config.ps}
3301 before looking for the customization file \file{.dvipsrc} (which, in
3302 this case is \emph{not found}). Finally, \cmdname{dvips} locates the
3303 config file for the Computer Modern \PS{} fonts \file{config.cms}
3304 (this was initiated with the \texttt{-Pcms} option on the \cmdname{dvips}
3305 command). This file contains the list of the map files which
3306 define the relation between the \TeX{}, \PS{} and file system
3307 names of the fonts.
3308 \begin{alltt}
3309 > \Ucom{more /usr/local/texmf/dvips/cms/config.cms}
3310 p +ams.map
3311 p +cms.map
3312 p +cmbkm.map
3313 p +amsbkm.map
3314 \end{alltt}
3315 \cmdname{dvips} thus goes on to find all these files, plus the generic
3316 map file \file{psfonts.map}, which is always loaded (it contains
3317 declarations for commonly used \PS{} fonts; see the last part of
3318 Section \ref{SExamplesofuse} for more details about \PS{} map
3319 file handling).
3320
3321 At this point \cmdname{dvips} identifies itself to the user:
3322 \begin{alltt}
3323 This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com)
3324 \end{alltt}
3325 \ifSingleColumn
3326 Then it goes on to look for the prolog file \file{texc.pro}:
3327 \begin{alltt}\small
3328 kdebug:start search(file=texc.pro, must\_exist=0, find\_all=0,
3329 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
3330 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
3331 kdebug:search(texc.pro) => /usr/local/texmf/dvips/base/texc.pro
3332 \end{alltt}
3333 \else
3334 Then it goes on to look for the prolog file \file{texc.pro} (see
3335 Figure~\ref{fig:dvipsdbgb}).
3336 \fi
3337
3338 After having found the file in question, \cmdname{dvips} outputs
3339 date and time, and informs us that it will generate the
3340 file \file{hello-world.ps}, then that it needs the font file
3341 \file{cmr10}, and that the latter is declared as ``resident'' (no
3342 bitmaps needed):
3343 \begin{alltt}\small
3344 TeX output 1998.02.26:1204' -> hello-world.ps
3345 Defining font () cmr10 at 10.0pt
3346 Font cmr10 <CMR10> is resident.
3347 \end{alltt}
3348 Now the search is on for the file \file{cmr10.tfm}, which is found,
3349 then a few more prolog files (not shown) are referenced, and finally
3350 the Type~1 instance \file{cmr10.pfb} of the font is located and
3351 included in the output file (see last line).
3352 \begin{alltt}\small
3353 kdebug:start search(file=cmr10.tfm, must\_exist=1, find\_all=0,
3354 path=.:~/tex/fonts/tfm//:!!/usr/local/texmf/fonts/tfm//:
3355 /var/tex/fonts/tfm//).
3356 kdebug:search(cmr10.tfm) => /usr/local/texmf/fonts/tfm/public/cm/cmr10.tfm
3357 kdebug:start search(file=texps.pro, must\_exist=0, find\_all=0,
3358 ...
3359 <texps.pro>
3360 kdebug:start search(file=cmr10.pfb, must\_exist=0, find\_all=0,
3361 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
3362 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
3363 kdebug:search(cmr10.pfb) => /usr/local/texmf/fonts/type1/public/cm/cmr10.pfb
3364 <cmr10.pfb>[1]
3365 \end{alltt}
3366
3367 \subsection{Runtime options}
3368
3369 Another useful feature of \Webc{} is its possibility to control a number
3370 of memory parameters (in particular, array sizes) via the runtime file
3371 \file{texmf.cnf} read by \KPS{}. The memory settings can be found in
3372 Part 3 of that file in the \TL{} distribution. The more important
3373 are:
3374
3375 \begin{ttdescription}
3376 \item[\texttt{main\_memory}]
3377 Total words of memory available, for
3378 \TeX{}, \MF{} and \MP. You must make a new format file for each
3379 different setting. For instance, you could generate a ``huge''
3380 version of \TeX{}, and call the format file \texttt{hugetex.fmt}.
3381 Using the standard way of specifying the program name used by \KPS{},
3382 the particular value of the \texttt{main\_memory} variable will then
3383 be read from \file{texmf.cnf}.
3384 etc.).
3385 \item[\texttt{extra\_mem\_bot}]
3386 Extra space for ``large'' \TeX{} data structures:
3387 boxes, glue, breakpoints, etc. Especially useful if you use
3388 \PiCTeX{}.
3389 \item[\texttt{font\_mem\_size}]
3390 Number of words for font information available for \TeX. This
3391 is more or less the total size of all TFM files read.
3392 \item[\texttt{hash\_extra}]
3393 Additional space for the hash table of control sequence names.
3394 Approximately 10,000 control sequences can be stored in the main
3395 hash table; if you have a large book with numerous cross-references,
3396 this might not be enough. The default value of
3397 \texttt{hash\_extra} is \texttt{50000}.
3398 \end{ttdescription}
3399
3400 \noindent Of course, this facility is no substitute for truly dynamic
3401 arrays and memory allocation, but since these are extremely difficult to
3402 implement in the present \TeX{} source, these runtime parameters provide
3403 a practical compromise allowing some flexibility.
3404
3405
3406 \section{Building on a new Unix platform}
3407
3408 If you have a platform for which executables are not included, you will
3409 need to compile \TeX{} and friends. This is not as hard as it
3410 sounds. What you need is all in the directory \texttt{source} in the
3411 distribution.
3412
3413 \subsection{Prerequisites}
3414
3415 You will need at least 100 megabytes of disk space to compile all of
3416 \TeX{} and its support programs. You'll also need an \acro{ANSI} C
3417 compiler, a \cmdname{make} utility, a lexical scanner, and a parser
3418 generator. We recommend the \acro{GNU} version of these programs
3419 (\cmdname{gcc}, \acro{GNU} \cmdname{make}, \cmdname{m4}, \cmdname{flex},
3420 \cmdname{bison}). You may be able to work with other C compilers and
3421 \cmdname{make} programs, but you will need a good understanding of
3422 building Unix programs to sort out problems.
3423
3424 Also, the command \texttt{uname} must return a sensible value.
3425
3426
3427 \subsection{Configuration}
3428
3429 To begin, perform a normal installation of \TL{} to your disk (see
3430 section~\ref{sec:unix-install-disk} on
3431 \p.\pageref{sec:unix-install-disk}). You may wish to skip installing
3432 all of the prebuilt binaries.
3433
3434 Then, unpack the source from the compressed \texttt{tar} file in the
3435 directory \dirname{source} to your disk and change directory to where
3436 you placed it.
3437
3438 Next, run \cmdname{configure} with a command line like this:
3439 \begin{alltt}
3440 > \Ucom{sh configure -prefix=/usr/local/TeX}
3441 \end{alltt}
3442
3443 The \optname{-prefix} directory is the one where you installed the
3444 support tree; the directory layout will be as follows (where \$TEXDIR
3445 stands for the directory you chose):
3446
3447 \noindent
3448 \begin{tabular}{>{\ttfamily}ll@{}}
3449 \dirname{$TEXDIR/share/texmf} & main tree with fonts,\\
3450 & \qquad macros, etc\\
3451 \dirname{$TEXDIR/man} & Unix manual pages\\
3452 \dirname{$TEXDIR/info} & \acro{GNU} style Info manuals\\
3453 \dirname{$TEXDIR/bin/$PLATFORM} & binaries\\
3454 \end{tabular}
3455 %$
3456
3457 If you want to leave out the \dirname{$PLATFORM} directory level,
3458 i.e., put the binaries directly into \dirname{$TEXDIR/bin}, specify
3459 the \verb|--disable-multiplatform| option to \cmdname{configure}.
3460
3461 Have a look at the output of \verb|./configure --help| for more
3462 options you can use. For example, you can skip building of \OMEGA{} and
3463 \eTeX{}.
3464
3465
3466 \subsection{Running \cmdname{make}}
3467
3468 Make sure the shell variable or option \texttt{noclobber} is not set.
3469 Then, run the main \cmdname{make} like this:
3470 \begin{alltt}
3471 > \Ucom{make world}
3472 \end{alltt}
3473 and relax\ldots
3474
3475 Alternatively, you want to log all the output, as in:
3476 \begin{alltt}
3477 > \Ucom{sh -c "make world >world.log 2>\&1" \&}
3478 \end{alltt}
3479
3480 Before you believe that everything went ok, please check the log file
3481 for errors: \acro{GNU} \cmdname{make} always uses the string \samp{***}
3482 whenever a command fails. Also, check if all the programs were built:
3483
3484 \begin{alltt}
3485 > \Ucom{cd \var{TEXDIR}/bin/\var{archname}}
3486 > \Ucom{ls | wc}
3487 \end{alltt}
3488 The result should be over 200 (you can check the exact number with the
3489 \dirname{bin} directory contents in the distribution).
3490
3491 If you need special privileges for \texttt{make install}, you can
3492 separate the \samp{make world} into two different runs, like this:
3493 \begin{alltt}
3494 > \Ucom{make all}
3495 > \Ucom{su}
3496 > \Ucom{make install strip}
3497 \end{alltt}
3498
3499 After you've installed your new binaries, you should follow the normal
3500 post-installation procedures, given in section~\ref{sec:postinstall}
3501 (\p.\pageref{sec:postinstall}).
3502
3503 Also, if you'd like to make your binaries available to others, please
3504 contact us. We'll be happy to put them on the \TL\ web pages.
3505
3506
3507 \section{Acknowledgements}
3508
3509 \TL{} is a joint effort by virtually all of the \TeX{} user groups.
3510 This edition of \TL{} was overseen by Sebastian Rahtz and Karl Berry.
3511 The other principal contributors are listed below.
3512
3513 \begin{itemize*}
3514
3515 \item The German-speaking \TeX{} Users (\acro{DANTE} e.V.), who provide
3516 the hardware for the \TL{} source repository; and Rainer Sch\"opf and
3517 Reinhard Zierke who look after it. \acro{DANTE} officers Volker Schaa
3518 and Klaus Hoeppner coordinated production with the Lehmann's Bookstore
3519 (\url{http://www.lob.de}).
3520
3521 \item The Perforce corporation (\url{http://www.perforce.com}), for providing
3522 a free copy of their excellent change management system, which we used
3523 to manage the \TL{} sources.
3524
3525 \item Peter Breitenlohner and the \eTeX\ team for the stable foundation
3526 of future \TeX's.
3527
3528 \item Thomas Esser, without whose marvelous \teTeX{} package \TL{}
3529 would certainly not exist, and whose continual help makes it a better
3530 product.
3531
3532 \item Michel Goossens, who co-authored the original documentation.
3533
3534 \item Eitan Gurari, whose \TeX4ht was used to create the \HTML{}
3535 version of this documentation, and who worked tirelessly to improve
3536 it at short notice.
3537
3538 \item Hans Hagen, for major testing and making the \ConTeXt\ format
3539 conform to \TL's needs.
3540
3541 \item \Thanh, Martin Schr\"oder, and the pdf\TeX\ team for continuing
3542 enhancements of \TeX's abilities.
3543
3544 \item Petr Olsak, who coordinated and checked all the Czech and Slovak
3545 material very carefully.
3546
3547 \item Fabrice Popineau, for the Windows side of \TL{} and devising the
3548 new directory layout.
3549
3550 \item Staszek Wawrykiewicz, the principal tester for all of \TL{}, and
3551 coordinator of the Polish contributions.
3552
3553 \item Olaf Weber, for his patient assembly and maintenance of Web2C,
3554 upon which all else depends.
3555
3556 \item Gerben Wierda, for creating and maintaining the \MacOSX\ support,
3557 and much integration and testing.
3558
3559 \item Graham Williams, on whose work the catalogue of packages depends.
3560
3561 \end{itemize*}
3562
3563 Builders of the binaries:
3564 Tigran Aivazian (\pkgname{x86\_64-linux}),
3565 Manfred Lotz (\pkgname{i386-freebsd}),
3566 Maksym Polyakov (\pkgname{sparc-solaris}),
3567 Fabrice Popineau (\pkgname{win32}),
3568 Norbert Preining (\pkgname{alpha-linux}),
3569 Vladimir Volovich (\pkgname{powerpc-aix} and \pkgname{sparc64-linux}),
3570 Staszek Wawrykiewicz (\pkgname{i386-linux}),
3571 Olaf Weber (\pkgname{mips-irix}),
3572 Gerben Wierda (\pkgname{powerpc-darwin}).
3573
3574 Documentation and translation updates:
3575 Karl Berry (English),
3576 Daniel Flipo \& Fabrice Popineau (French),
3577 G\"unter Partosch \& Hartmut Henkel (German),
3578 Petr Sojka \& Jan Busa (Czech\slash Slovak),
3579 Boris Veytsman (Russian),
3580 Staszek Wawrykiewicz (Polish).
3581
3582 Of course the most important acknowledgement must go to Donald Knuth, first
3583 for inventing \TeX, and then for giving it to the world.
3584
3585
3586 \section{Release history}
3587 \label{sec:history}
3588
3589 \subsection{Past}
3590
3591 Discussion began in late 1993 when the Dutch \TeX{} Users Group was
3592 starting work on its 4All\TeX{} \CD{} for \acro{MS-DOS} users, and it
3593 was hoped at that time to issue a single, rational, \CD{} for all
3594 systems. This was too ambitious a target for the time, but it did spawn
3595 not only the very successful 4All\TeX{} \CD{}, but also the \acro{TUG}
3596 Technical Council working group on a \emph{\TeX{} Directory Structure}
3597 (\url{http://tug.org/tds}), which specified how to create consistent and
3598 manageable collections of \TeX{} support files. A complete draft of the
3599 \TDS{} was published in the December 1995 issue of \textsl{TUGboat}, and
3600 it was clear from an early stage that one desirable product would be a
3601 model structure on \CD{}. The distribution you now have is a very direct
3602 result of the working group's deliberations. It was also clear that the
3603 success of the 4All\TeX{} \CD{} showed that Unix users would benefit
3604 from a similarly easy system, and this is the other main strand of
3605 \TL.
3606
3607 We first undertook to make a new Unix-based \TDS{} \CD{} in the autumn
3608 of 1995, and quickly identified Thomas Esser's \teTeX{} as the ideal
3609 setup, as it already had multi-platform support and was built with
3610 portability across file systems in mind. Thomas agreed to help, and work
3611 began seriously at the start of 1996. The first edition was released in
3612 May 1996. At the start of 1997, Karl Berry completed a major new release
3613 of Web2c, which included nearly all the features which Thomas Esser had
3614 added in \teTeX, and we decided to base the 2nd edition of the \CD{} on
3615 the standard \Webc, with the addition of \teTeX's \texttt{texconfig}
3616 script. The 3rd edition of the \CD{} was based on a major revision of
3617 \Webc, 7.2, by Olaf Weber; at the same time, a new revision of \teTeX
3618 was being made, and \TL{} included almost all of its features. The
3619 4th edition followed the same pattern, using a new version of \teTeX,
3620 and a new release of \Webc{} (7.3). The system now included a complete
3621 Windows setup.
3622
3623 For the 5th edition (March 2000) many parts of the \CD{} were revised
3624 and checked, updating hundreds of packages. Package details were stored
3625 in XML files. But the major change for \TeX\ Live 5 was that all
3626 non-free software was removed. Everything in \TL{} is now intended
3627 to be compatible with the Debian Free Software Guidelines
3628 (\url{http://www.debian.org/intro/free}); we have done our best to check
3629 the license conditions of all packages, but we would very much
3630 appreciate hearing of any mistakes.
3631
3632 The 6th edition (July 2001) had much more material updated. The major
3633 change was a new install concept: the user could select a more exact set
3634 of needed collections. Language-related collections were completely
3635 reorganized, so selecting any of them installs not only macros, fonts,
3636 etc., but also prepares an appropriate \texttt{language.dat}.
3637
3638 The 7th edition of 2002 had the notable addition of \MacOSX{} support,
3639 and the usual myriad of updates to all sorts of packages and
3640 programs. An important goal was integration of the source back with
3641 \teTeX, to correct the drift apart in versions~5 and~6.
3642
3643 In 2003, with the continuing flood of updates and additions, we found
3644 that \TL{} had grown so large it could no longer be contained on a
3645 single \CD, so we split it into three different distributions (see
3646 section~\ref{sec:multiple-dist}, \p.\pageref{sec:multiple-dist}). In
3647 addition:
3648
3649 \begin{itemize*}
3650 \item At the request of the \LaTeX{} team, we changed the standard
3651 \cmdname{latex} and \cmdname{pdflatex} commands to now use \eTeX{} (see
3652 \p.\pageref{text:etex}).
3653 \item The new Latin Modern fonts were included (and are recommended).
3654 \item Support for Alpha \acro{OSF} was removed
3655 (\acro{HPUX} support was removed previously), since no one had (or
3656 volunteered) hardware available on which to compile new binaries.
3657 \item Windows setup was substantially changed; for the first time
3658 an integrated environment based on XEmacs was introduced.
3659 \item Important supplementary programs for Windows
3660 (Perl, Ghost\-script, Image\-Magick, Ispell) are now installed
3661 in the \TL{} installation directory.
3662 \item Font map files used by \cmdname{dvips}, \cmdname{dvipdfm}
3663 and \cmdname{pdftex} are now generated by the new program
3664 \cmdname{updmap} and installed into \dirname{texmf/fonts/map}.
3665 \item \TeX{}, \MF{}, and \MP{} now, by default, output most input
3666 characters (32 and above) as themselves in output (e.g.,
3667 \verb|\write|) files,
3668 log files, and the terminal, i.e., \emph{not} translated using the
3669 \verb|^^| notation. In \TL{}~7, this translation was
3670 dependent on the system locale settings; now, locale settings do
3671 not influence the \TeX{} programs' behavior. If for some reason
3672 you need the \verb|^^| output, rename the file
3673 \verb|texmf/web2c/cp8bit.tcx|. (Future releases will have cleaner
3674 ways to control this.)
3675 \item This documentation was substantially revised.
3676 \item Finally, since the edition numbers had grown unwieldy,
3677 the version is now simply identified by the year: \TL{} 2003.
3678 \end{itemize*}
3679
3680 \subsection{Present}
3681 \label{tlcurrent}
3682
3683 2004 saw the usual huge number of updates to packages and programs.
3684 Here are the most notable changes, including one important backward
3685 incompatibility:
3686
3687 \begin{itemize}
3688
3689 \item If you have locally-installed fonts which use their own
3690 \filename{.map} or (much less likely) \filename{.enc} support files, you
3691 may need to move those support files.
3692
3693 \filename{.map} files are now searched for in subdirectories of
3694 \dirname{fonts/map} only (in each \filename{texmf} tree), along the
3695 \envname{TEXFONTMAPS} path. Similarly, \filename{.enc} files are now
3696 searched for in subdirectories of \dirname{fonts/enc} only, along the
3697 \envname{ENCFONTS} path. \cmdname{updmap} will attempt to warn about
3698 problematic files.
3699
3700 For methods of handling this and other information, please see
3701 \url{http://tug.org/texlive/mapenc.html}.
3702
3703 \item The \TK\ has been expanded with the addition of a \MIKTEX-based
3704 installable \CD, for those who prefer that implementation to Web2C.
3705 See section~\ref{sec:struct-tl} (\p.\pageref{sec:struct-tl}).
3706
3707 \item Within \TL, the single large \dirname{texmf} tree of previous
3708 releases has been replaced by three: \dirname{texmf},
3709 \dirname{texmf-dist}, and \dirname{texmf-doc}. See
3710 section~\ref{sec:tld} (\p.\pageref{sec:tld}), and the \filename{README}
3711 files for each.
3712
3713 \item All \TeX-related input files are now collected in
3714 the \dirname{tex} subdirectory of \dirname{texmf*} trees, rather than
3715 having separate sibling directories \dirname{tex}, \dirname{etex},
3716 \dirname{pdftex}, \dirname{pdfetex}, etc. See
3717 \CDref{texmf-doc/doc/english/tds/tds.html\#Extensions}
3718 {\texttt{texmf-doc/doc/english/tds/tds.html\#Extensions}}.
3719
3720 \item Helper scripts (not meant to be invoked by users) are now located
3721 in a new \dirname{scripts} directory of \dirname{texmf*} trees, and
3722 searched for via \verb|kpsewhich -format=texmfscripts|. So if you have
3723 programs which call such scripts, they'll need to be adjusted. See
3724 \CDref{texmf-doc/doc/english/tds/tds.html\#Scripts}
3725 {\texttt{texmf-doc/doc/english/tds/tds.html\#Scripts}}.
3726
3727 \item Almost all formats leave most characters printable as
3728 themselves via the ``translation file'' \filename{cp227.tcx}, instead of
3729 translating them with the \verb|^^| notation. Specifically, characters
3730 at positions 32--256, plus tab, vertical tab, and form feed are
3731 considered printable and not translated. The exceptions are plain \TeX\
3732 (only 32--126 printable), \ConTeXt\ (0--255 printable), and the
3733 \OMEGA-related formats. This default behavior is almost the same as in
3734 \TL\,2003, but it's implemented more cleanly, with more possibilities
3735 for customization. See \CDref{texmf/doc/web2c/web2c.html\#TCX-files}
3736 {\texttt{texmf/doc/web2c/web2c.html\#TCX-files}}.
3737 (By the way, with Unicode input, \TeX\ may output partial character
3738 sequences when showing error contexts, since it is byte-oriented.)
3739
3740 \item \textsf{pdfetex} is now the default engine for all formats
3741 except (plain) \textsf{tex} itself. (Of course it generates \acro{DVI}
3742 when run as \textsf{latex}, etc.) This means, among other things, that
3743 the microtypographic features of \textsf{pdftex} are available in
3744 \LaTeX, \ConTeXt, etc., as well as the \eTeX\ features
3745 (\OnCD{texmf-dist/doc/etex/base/}).
3746
3747 It also means it's \emph{more important than ever} to use the
3748 \pkgname{ifpdf} package (works with both plain and \LaTeX) or equivalent
3749 code, because simply testing whether \cs{pdfoutput} or some other
3750 primitive is defined is not a reliable way to determine if \acro{PDF}
3751 output is being generated. We made this backward compatible as best we
3752 could this year, but next year, \cs{pdfoutput} may be defined even when
3753 \acro{DVI} is being written.
3754
3755 \item pdf\TeX\ (\url{http://pdftex.org}) has many new features:
3756
3757 \begin{itemize*}
3758
3759 \item \cs{pdfmapfile} and \cs{pdfmapline} provide font map support
3760 from within a document.
3761
3762 \item Microtypographic font expansion can be used more easily.\\
3763 \url{http://www.ntg.nl/pipermail/ntg-pdftex/2004-May/000504.html}
3764
3765 \item All parameters previously set through the special configuration
3766 file \filename{pdftex.cfg} must now be set through primitives,
3767 typically in \filename{pdftexconfig.tex}; \filename{pdftex.cfg} is no
3768 longer supported. Any extant \filename{.fmt} files must be redumped
3769 when \filename{pdftexconfig.tex} is changed.
3770
3771 \item See the pdf\TeX\ manual for more: \OnCD{texmf/doc/pdftex/manual}.
3772
3773 \end{itemize*}
3774
3775 \item The \cs{input} primitive in \cmdname{tex} (and \cmdname{mf} and
3776 \cmdname{mpost}) now accepts double quotes containing spaces and other
3777 special characters. Typical examples:
3778 \begin{verbatim}
3779 \input "filename with spaces" % plain
3780 \input{"filename with spaces"} % latex
3781 \end{verbatim}
3782 See the Web2C manual for more: \OnCD{texmf/doc/web2c}.
3783
3784 \item enc\TeX\ support is now included within Web2C and consequently all
3785 \TeX\ programs, via the \optname{-enc} option\Dash \emph{only when
3786 formats are built}. enc\TeX\ supports general re-encoding of input and
3787 output, enabling full support of Unicode (in \acro{UTF}-8). See
3788 \OnCD{texmf-dist/doc/generic/enctex/} and
3789 \url{http://www.olsak.net/enctex.html}.
3790
3791 \item Aleph, a new engine combining \eTeX\ and \OMEGA, is available.
3792 A little information is available in \OnCD{texmf-dist/doc/aleph/base}
3793 and \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=aleph}. The
3794 \LaTeX-based format for Aleph is named \textsf{lamed}.
3795
3796 \item The latest \LaTeX\ release has a new version of the
3797 \acro{LPPL}\Dash now officially a Debian-approved license. Assorted
3798 other updates, see the \filename{ltnews} files in
3799 \OnCD{texmf-dist/doc/latex/base}.
3800
3801 \item \cmdname{dvipng}, a new program for converting \acro{DVI} to
3802 \acro{PNG} image files, is included. See \OnCD{texmf/doc/man/man1/dvipng.1}.
3803
3804 \item We reduced the \pkgname{cbgreek} package to a ``medium'' sized set
3805 of fonts, with the assent and advice of the author (Claudio Beccari).
3806 The excised fonts are the invisible, outline, and transparency ones,
3807 which are relatively rarely used, and we needed the space. The full set
3808 is of course available from \acro{CTAN}
3809 (\url{http://www.ctan.org/tex-archive/fonts/greek/cb}).
3810
3811 \item \cmdname{oxdvi} has been removed; just use \cmdname{xdvi}.
3812
3813 \item The \cmdname{ini} and \cmdname{vir} commands (links) for
3814 \cmdname{tex}, \cmdname{mf}, and \cmdname{mpost} are no longer created,
3815 such as \cmdname{initex}. The \cmdname{ini} functionality has been
3816 available through the command-line option \optname{-ini} for years now.
3817
3818 \item \textsf{i386-openbsd} platform support was removed. Since the
3819 \pkgname{tetex} package in the \acro{BSD} Ports system is available, and
3820 \acro{GNU/}Linux and Free\acro{BSD} binaries were available, it seemed
3821 volunteer time could be better spent elsewhere.
3822
3823 \item On \textsf{sparc-solaris} (at least), you may have to set the
3824 \envname{LD\_LIBRARY\_PATH} environment variable to run the
3825 \pkgname{t1utils} programs. This is because they are compiled with C++,
3826 and there is no standard location for the runtime libraries. (This is
3827 not new in 2004, but wasn't previously documented.) Similarly, on
3828 \textsf{mips-irix}, the \acro{MIPS}pro 7.4 runtimes are required.
3829
3830 \end{itemize}
3831
3832
3833 \subsection{Future}
3834
3835 \emph{\TL{} is not perfect!} (And never will be.) We intend to
3836 continue to release new versions yearly, and would like to provide more
3837 help material, more utilities, more installation programs, and (of
3838 course) an ever-improved and checked tree of macros and fonts. This work
3839 is all done by hard-pressed volunteers in their limited spare time, and
3840 a great deal remains to be done. If you can help, don't hesitate to put
3841 your name forward!
3842
3843 Please send corrections, suggestions, and offers of help to:\hfill\null
3844 \begin{quote}
3845 Sebastian Rahtz \ / \ 7 Stratfield Road \ / \ Oxford OX2 7BG \ / \ UK \\
3846 \email{[email protected]} \\
3847 \url{http://tug.org/texlive}
3848 \end{quote}
3849
3850 \medskip
3851 \noindent \textsl{Happy \TeX ing!}
3852
3853 \end{multicols}
3854 \end{document}