Debian Codegraph @

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

raw
1 % $Id: live.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{} 2005}}
14 }
15
16 \author{Sebastian Rahtz \& Karl Berry, editors \\[3mm]
17 \url{http://tug.org/texlive/}
18 }
19
20 \date{October 2005}
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 \TeX{} and friends for \acro{GNU}/Linux and other Unix
34 flavors, \MacOSX, and (32-bit) Windows systems. (Warning: it is not
35 especially useful for older Mac or \acro{MS-DOS} systems.)
36
37 \TL{} includes executables for \TeX{}, \LaTeXe{}, \ConTeXt, \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}). Both are cooperative efforts by the \TeX\
43 user 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 the end of the document, section~\ref{sec:history}
50 (\p.\pageref{sec:history}).
51
52
53 \subsection{Basic usage of \protect\TL{}}
54 \label{sec:basic}
55
56 You can use \TL{} in three principal ways:
57
58 \begin{enumerate}
59
60 \item You can run \TL{} directly from the \pkgname{live} \DVD
61 (see section~\ref{sec:multiple-dist}, \p.\pageref{sec:multiple-dist}).
62 This takes almost no disk space, and gives you immediate access to
63 everything in \TL{}. Of course performance will be worse than running
64 on local disk, but you may well find it useful.
65
66 \item You can install all or part of \TL{} to a local disk, from either
67 the \DVD\ or the \pkgname{inst} \acro{CD}. This is the most common use
68 of \TL. You will need (approximately) 100 megabytes for the most
69 minimal system, and upwards of 1.3 gigabytes 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 The installation program for Windows is \texttt{tlpmgui.exe}.
88 It can be used also for adding or removing the packages.
89 See section~\ref{sec:win-install} below 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 collection 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 on asking questions in such a
141 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, the \pkgname{protext}
180 distribution for Windows and the Mac\TeX\ distribution for \MacOSX, entirely
181 independent of \TL{}, as well as assorted other packages in a
182 \texttt{texmf-extra} directory.
183
184 \CTAN{}, \pkgname{protext}, Mac\TeX, and \texttt{texmf-extra} do not follow
185 the same copying conditions as \TL{}, so be careful when redistributing or
186 modifying.
187
188 \item [inst(allable)] A complete system on \CD; in order to make this fit,
189 the packages and programs are compressed. Therefore, it is not possible
190 to run \TeX\ directly from the installable \CD, you have to install it
191 to disk (hence its name). Installation is described in subsequent sections.
192
193 \item [protext] An enhancement of the \MIKTEX\ distribution for Windows,
194 \ProTeXt\ adds a few extra tools to \MIKTEX, and simplifies
195 installation. It is entirely independent of \TL{}, and has its own
196 installation instructions. It can be run live, or installed to disk.
197 The \ProTeXt\ home page is \url{http://tug.org/protext}.
198
199 \ProTeXt\ is provided as both the top level of the \pkgname{live} \DVD\
200 and on its own \CD\ (for those who cannot use the \DVD).
201
202 \end{description}
203
204 \noindent You can tell which type of distribution you're in by looking
205 for a \texttt{00\var{type}.TL} file at the top of the \TL{} directory.
206 This file also contains the \TL{} release date.
207
208 Naturally, each user group chooses what to distribute, at its own
209 discretion. (\acro{TUG} is sending all three discs above to all of its
210 members.)
211
212
213 \subsection{Top level directories}
214 \label{sec:tld}
215
216 Here is a brief listing and description of the top level directories in
217 the \TL{} distribution. On the \pkgname{live} \DVD, the entire \TL{}
218 hierarchy is in a subdirectory \dirname{texlive2005}, not at the top
219 level of the disc.
220
221 \smallskip
222 \begingroup
223 \renewcommand{\arraystretch}{1.3} % open up interrow spacing
224 \begin{tabular}{>{\ttfamily}lp{.78\hsize}}
225 bin & The \TeX{} system programs, arranged by platform. \\
226 source & The source of all programs, including the main \Webc{}
227 \TeX{} and \MF{} distributions. These are stored in a
228 \cmdname{bzip2}-compressed tar archive. \\
229 support & Assorted auxiliary packages and programs. These are
230 \emph{not} installed automatically. This includes
231 assorted editors and \TeX\ shells. \\
232 texmf & Tree for the programs, along with their support files and
233 documentation. Does not include \TeX\ formats and packages.
234 (\texttt{TEXMFMAIN} in the next section.) \\
235 texmf-dist & The main tree of formats and packages.
236 (\texttt{TEXMFDIST} in the next section.) \\
237 texmf-doc & Tree for self-contained pure documentation, arranged by
238 language. \\
239 texmf-var & Tree for files automatically generated and stored.
240 (\texttt{TEXMFSYSVAR} in the next section.) \\
241 xemtex & Tree for supporting programs used only in Windows.
242 These programs generally come pre-installed on Unix systems, or are
243 at least easy to compile. \\
244 \end{tabular}
245 \endgroup
246
247 \smallskip
248
249 In addition to the directories above, the installation scripts and
250 \filename{README} files (in various languages) are at the top level of
251 the distribution.
252
253 The \dirname{texmf-doc} directory contains only documentation, but
254 it does not contain all the documentation. The documentation for the
255 programs (manuals, man pages, Info files) is in \dirname{texmf/doc},
256 since the programs are in \dirname{texmf}. Similarly, the documentation
257 for \TeX\ packages and formats is in \dirname{texmf-dist/doc}. You can
258 use the \cmdname{texdoc} or \cmdname{texdoctk} programs to find any
259 documentation wherever it's located. The comprehensive links in the
260 top-level file \OnCD{doc.html} may also be helpful.
261
262
263 \subsection{Overview of the predefined texmf trees}
264 \label{sec:texmftrees}
265
266 This section lists all predefined variables specifying texmf trees used
267 by the system, and their intended purpose. The command \texttt{texconfig
268 conf} shows you the values of these variables, so that you can easily
269 find out how they map to directory names in your installation.
270
271 \begin{ttdescription}
272 \item [TEXMFMAIN] The tree which holds vital parts of the system
273 such as helper scripts (e.g., \verb+web2c/mktexdir+), pool files and
274 other support files.
275 \item [TEXMFDIST] The tree which holds the main set of macro packages,
276 fonts, etc., as originally distributed.
277 \item [TEXMFLOCAL] The tree which administrators can use for system-wide
278 installation of additional or updated macros, fonts, etc.
279 \item [TEXMFHOME] The tree which users can use for their own individual
280 installations of additional or updated macros, fonts, etc.
281 The expansion of this variable depends on \verb+$HOME+ by default, % $
282 which dynamically adjusts for each user to an individual
283 directory.
284 \item [TEXMFCONFIG] The tree used by te\TeX's utilities
285 \verb+texconfig+, \verb+updmap+, and \verb+fmtutil+ to store modified
286 configuration data. Under \verb+$HOME+ by default. %$
287 \item [TEXMFSYSCONFIG] The tree used by te\TeX's utilities
288 \verb+texconfig-sys+, \verb+updmap-sys+, and \verb+fmtutil-sys+ to
289 store modified configuration data.
290 \item [TEXMFVAR] The tree used by \verb+texconfig+, \verb+updmap+ and
291 \verb+fmtutil+ to store (cached) runtime data such as format files and
292 generated map files. Under \verb+$HOME+ by default. %$
293 \item [TEXMFSYSVAR] The tree used by \verb+texconfig-sys+,
294 \verb+updmap-sys+ and \verb+fmtutil-sys+ to store (cached) runtime
295 data such as format files and generated map files.
296 \end{ttdescription}
297
298 For more discussion of \texttt{texconfig} and related utilities, please
299 see section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig}.
300
301
302 \subsection{Extensions to \protect\TeX}
303 \label{sec:tex-extensions}
304
305 \TL{} contains several extended versions of \TeX:
306
307 \begin{description}
308
309 \item [\eTeX] adds a small but powerful set of new primitives
310 \label{text:etex} (related to macro expansion, character scanning,
311 classes of marks, additional debugging features, and more) and the
312 \TeXXeT{} extensions for bidirectional typesetting. In default mode,
313 \eTeX{} is 100\% compatible with ordinary \TeX. See
314 \OnCD{texmf-dist/doc/etex/base/etex_man.pdf}.
315
316 \item [pdf\TeX] writes Acrobat \acro{PDF} format as well as \dvi{}. The
317 \LaTeX{} \pkgname{hyperref} package has an option `\optname{pdftex}'
318 which turns on all the program features. See
319 \OnCD{texmf/doc/pdftex/manual/} for the manual, and
320 \OnCD{texmf/doc/pdftex/manual/samplepdf/samplepdf.tex}.
321
322 \item [pdfe\TeX] combines the pdf\TeX\ and \eTeX\ extensions. This is
323 the default program for all formats except plain \TeX.
324 See above for documentation.
325
326 \item [\OMEGA\ (Omega)] is based on Unicode (16-bit characters), thus
327 supports working with almost all the world's scripts simultaneously. It
328 also supports so-called `\OMEGA{} Translation Processes' (\acro{OTP}s),
329 for performing complex transformations on arbitrary input. See
330 \OnCD{texmf-dist/doc/omega/base/doc-1.8.tex} (not completely up-to-date).
331
332 \item [Aleph] combines the \OMEGA\ and \eTeX\ extensions.
333 See \OnCD{texmf-dist/doc/aleph/base} for some minimal documentation.
334
335 \end{description}
336
337
338 \subsection{Other notable programs in \protect\TL}
339
340 Here are a few other commonly-used programs included in \TL{}:
341
342 \begin{cmddescription}
343
344 \item [bibtex] bibliography support.
345
346 \item [makeindex] index support.
347
348 \item [dvips] convert \dvi{} to \PS{}.
349
350 \item [xdvi] \dvi{} previewer for the X Window System.
351
352 \item [dvilj] \dvi{} drive for the HP LaserJet family.
353
354 \item [dv2dt, dt2dv] convert \dvi{} to/from plain text.
355
356 \item [dviconcat, dviselect] cut and paste pages
357 from \dvi{} files.
358
359 \item [dvipdfmx] convert \dvi{} to \acro{PDF}, an alternative approach
360 to pdf\TeX\ (mentioned above). See the \pkgname{ps4pdf} and
361 \pkgname{pdftricks} packages for still more alternatives.
362
363 \item [psselect, psnup, \ldots] \PS{}
364 utilities.
365
366 \item [lacheck] \LaTeX{} syntax checker.
367
368 \item [texexec] Con\TeX{}t and \acro{PDF} processor.
369
370 \item [tex4ht] \TeX{} to \acro{HTML} converter.
371
372 \end{cmddescription}
373
374
375 \section{Unix installation}
376 \label{sec:unix-install}
377
378 As introduced in section~\ref{sec:basic} (\p.\pageref{sec:basic}),
379 \TL{} has three principal uses:
380
381 \begin{enumerate}
382 \item Run directly from media.
383 \item Install to disk.
384 \item Integrate a particular package or collection into your existing
385 \TeX{} installation.
386 \end{enumerate}
387
388 \noindent The following sections describes the Unix-specific procedures
389 for each of these.
390
391 \ifSingleColumn \begin{figure}[ht]\noindent \fi
392 \begin{warningbox}
393 \textbf{Warning: } The \TK{} \CD{}s and \DVD{} are in ISO 9660 (High Sierra)
394 format, \emph{with} Rock Ridge (and Joliet, for Windows)
395 extensions. Therefore, in order to take full advantage of the \TK{}
396 under Unix, your system needs to be able to use the Rock Ridge
397 extensions. Please consult the documentation for your \cmdname{mount}
398 command to see how to do this. If you have several different machines
399 on a local network, you may be able to mount the discs on one which
400 does support Rock Ridge, and use this with the others.
401
402 \leavevmode\quad Modern systems should be able to use the discs without
403 problems. If troubles, let us know. The discussion below assumes you
404 have been able to mount the \CD{}s with full Rock Ridge compatibility.
405 \end{warningbox}
406 \ifSingleColumn\end{figure}\fi
407
408
409 %
410 \subsection{Running \protect\TL{} directly from media (Unix)}
411
412 \def\runlive{% text repeated in windows section
413 It is possible to use the \TeX{} system directly from the \pkgname{live}
414 \DVD{}, without installing the distribution to disk. (Thus the name
415 \TeX\ `Live', in fact.) It is \emph{not} possible to run \TeX{}
416 directly from the other \CD{}s (see section~\ref{sec:multiple-dist},
417 \p.\pageref{sec:multiple-dist}).
418 }
419
420 \def\startinst{% repeated in other subsections
421 To start, you mount the \CD{} or \DVD{}, with Rock Ridge extensions
422 enabled. The exact command to do this varies from system to system; the
423 following works under Linux, except the name of the device
424 (\filename{/dev/cdrom}, here) may vary. (All our examples will use
425 \texttt{>} as the shell prompt; user input is
426 \Ucom{\texttt{underlined}}.)
427 \begin{alltt}
428 > \Ucom{mount -t iso9660 /dev/cdrom /mnt/cdrom}
429 \end{alltt}
430
431 \noindent Change the current directory to the mount point:
432 \begin{alltt}
433 > \Ucom{cd /mnt/cdrom}
434 \end{alltt}
435
436 \noindent Under \MacOSX, the directory is typically under
437 \dirname{/Volumes}, and the media will be mounted automatically.
438 }
439
440 \def\installtlsh{
441 Run the installation script \filename{install-tl.sh}:
442 \begin{alltt}
443 > \Ucom{sh install-tl.sh}\\
444 Welcome to TeX Live...
445 \end{alltt}
446
447 \noindent After various greeting messages and a list of the main menu
448 options, the installation will ask you to enter a command. Do this by
449 typing the desired character and hitting return; don't type the angle
450 brackets shown. Either uppercase or lowercase is ok; we'll use
451 lowercase in our examples.
452 }
453
454 \runlive
455 \startinst
456 \installtlsh
457
458 For running live, our first command will be \Ucom{d} and then the
459 subcommand \Ucom{1} to set directories. Even in this case, we must
460 choose a directory on the local disk to place files that the \TeX{}
461 system itself generates, such as fonts and formats, and also to provide
462 a place for updated configuration files, if need be.
463
464 We'll use \dirname{/opt/texlive2005} in this example. It's good to
465 include the year in the name, as these generated files are not
466 compatible from release to release. (If the default value of
467 \dirname{/usr/local/texlive/2005} works for you, then you can skip this
468 step.)
469
470 \begin{alltt}
471 Enter command: \Ucom{d}
472 Current directories setup:
473 <1> TEXDIR: /usr/local/texlive/2005
474 ...
475 Enter command: \Ucom{1}
476 New value for TEXDIR [/usr/local/texlive/TeX]: \Ucom{/opt/texlive2005}
477 ...
478 Enter command: \Ucom{r}
479 \end{alltt}
480
481 \noindent Back at the main menu, our second and last command is
482 \Ucom{r}, to set up for running live off the media without installing
483 to disk:
484 \begin{alltt}
485 Enter command: \Ucom{r}
486 Preparing destination directories...
487 ...
488 Welcome to TeX Live!
489 >
490 \end{alltt}
491
492 \noindent And we are back at the system prompt, as shown.
493
494 Next, it is necessary to alter two environment variables:
495 \envname{PATH}, to an architecture-dependent value (so that we can run
496 the programs), and \envname{TEXMFSYSVAR}, to the value specified above.
497 See table~\ref{tab:archlist} for a list of the architecture names for
498 the different systems.
499
500
501 \def\textruntexconfig{%
502 After the main installation has completed, and environment variables
503 have been set, the last step is to run \cmdname{texconfig} or
504 \cmdname{texconfig-sys} to customize your installation to your needs.
505 This is explained in section~\ref{sec:texconfig},
506 \p.\pageref{sec:texconfig}.
507 }
508 \textruntexconfig
509
510 \begin{table*}[ht]
511 \caption[Supported system architectures.]{Supported system
512 architectures.}
513 \label{tab:archlist}
514 \begin{tabular}{>{\ttfamily}ll}
515 alpha-linux & HP Alpha GNU/Linux \\
516 %alphaev5-osf4.0d & HP Alphaev5 OSF \\
517 %hppa2.0-hpux10.20 & HP9000 HPUX 10.20 \\
518 i386-darwin & Intel x86 \MacOSX \\
519 i386-freebsd & Intel x86 FreeBSD \\
520 i386-linux & Intel x86 GNU/Linux \\
521 %i386-openbsd3.3 & Intel x86 OpenBSD \\
522 %i386-solaris2.8 & Intel x86 Solaris \\
523 mips-irix & SGI IRIX \\
524 powerpc-aix & IBM RS/6000 AIX \\
525 powerpc-darwin & PowerPC \MacOSX \\
526 sparc-linux & Sun Sparc GNU/Linux \\
527 sparc-solaris & Sun Sparc Solaris \\
528 win32 & Windows (32-bit) \\
529 x86\_64-linux & Intel x86 64-bit GNU/Linux \\
530 \hline
531 \end{tabular}
532 \end{table*}
533
534 \label{text:path}
535 The syntax for setting the environment variables, and the initialization
536 file to put them in, depends on the shell you use. If you use a
537 Bourne-compatible shell (\cmdname{sh}, \cmdname{bash}, \cmdname{ksh}, et
538 al.), put the following into your \filename{$HOME/.profile} file:
539 \begin{alltt}
540 PATH=/mnt/cdrom/bin/\var{archname}:$PATH; export PATH
541 TEXMFSYSVAR=/opt/texlive2005/texmf-var; export TEXMFVAR
542 \end{alltt}
543
544 \noindent For C shell-compatible shells (\cmdname{csh}, \cmdname{tcsh}),
545 put the following into your \filename{$HOME/.cshrc} file:
546 \begin{alltt}
547 setenv PATH /mnt/cdrom/bin/\var{archname}:$PATH
548 setenv TEXMFSYSVAR /opt/texlive2005/texmf-var
549 \end{alltt}
550
551 \noindent Then log out, log back in, and test your installation
552 (see section~\ref{sec:test-install}, \p.\pageref{sec:test-install}).
553
554 \def\textifindoubt{%
555 If in doubt, please ask any local system gurus to help you with
556 problems; for example, the way to mount the \TL{} media, which
557 directory or directories to use, and precise details of the changes to
558 your personal initialization files can and do vary from site to site.
559 }
560 \textifindoubt
561
562
563 %
564 \subsection{Installing \protect\TeX\protect\ Live to disk}
565 \label{sec:unix-install-disk}
566
567 It is possible, indeed typical, to install the \TL{} distribution to
568 hard disk. This can be done from either the \pkgname{live} or
569 \pkgname{inst} distributions. (See section~\ref{sec:multiple-dist},
570 \p.\pageref{sec:multiple-dist}, for an explanation of the different
571 distributions.)
572
573 \startinst
574 \installtlsh
575
576 Table~\ref{tab:main-menu-options} briefly lists the options in the main
577 menu. The order in which you select the options makes little
578 difference, except that \Ucom{i} must be last. It's reasonable to go
579 through them in the order presented here.
580
581 % apparently here.sty [H] doesn't support table*.
582 \begin{table}[H]
583 \caption{Main menu options for the installation.}
584 \label{tab:main-menu-options}
585 \begin{tabular}{>{\ttfamily}ll}
586 p & The platform you are running on.\\
587 b & The architectures for which to install binaries.\\
588 s & The base installation scheme to use (minimal, recommended,
589 full, etc.)\\
590 c & Override the base scheme for individual collections.\\
591 l & Override for language collections.\\
592 d & Directories in which to install.\\
593 o & Other options.\\
594 i & Perform the installation.\\
595 \end{tabular}
596 \end{table}
597
598 Here are further details on each option.
599
600 \textbf{\optname{p} -- Current platform.} Since the installation script
601 automatically guesses which platform you're running on, it is usually
602 unnecessary to use this option. It's there in case you need to override
603 the automatic detection.
604
605 \textbf{\optname{b} -- Binary architectures.} By default, only the
606 binaries for your current platform will be installed. From this menu,
607 you can select installation of binaries for other architectures as well
608 (or omit installing the current platform). This can be useful if you are
609 sharing a \TeX\ tree across a network of heterogenous machines. For a
610 list of the supported architectures, see table~\ref{tab:archlist},
611 \p.\pageref{tab:archlist}.
612
613 \textbf{\optname{s} -- Base installation scheme.} From this menu, you
614 can choose an overall set of package collections, called a ``scheme''.
615 The default \optname{full} scheme installs everything available, but you
616 can also choose the \optname{basic} scheme for a minimal system, or
617 \optname{medium} to get something in between. There are also specific
618 sets for Omega and \acro{XML}.
619
620 \textbf{\optname{c} -- Individual collections.} From this menu, you can
621 override the scheme's set of collections to install. Collections are
622 one level more detailed than schemes\Dash collections consist of one or
623 more packages, where packages (the lowest level grouping in \TL) contain
624 the actual \TeX\ macro files, font families, and so on. In this menu,
625 selection letters are case-sensitive.
626
627 \textbf{\optname{l} -- Language collections}. This menu has the same
628 basic purpose as \Ucom{c}, to override the collection set in the chosen
629 scheme. In this case, the collections are specifically for different
630 languages. Selection letters are case-sensitive here too. Here is a
631 list of the language collections in \TL:
632
633 % xx really should generate list from texmf/tpm/collection/tex-lang*
634 % a la install-tl.sh.
635 \begin{tabbing}
636 \hspace{.25\linewidth} \=
637 \hspace{.25\linewidth} \=
638 \hspace{.25\linewidth} \=
639 \hspace{.25\linewidth} \kill
640 (some) African scripts \>
641 Arabic \>
642 Armenian \>
643 Chinese\,Japanese\,Korean \\
644 Croatian \>
645 Cyrillic \>
646 Czech/Slovak \>
647 Danish \\
648 Dutch \>
649 Finnish \>
650 French \>
651 German \\
652 Greek \>
653 Hebrew \>
654 Hungarian \>
655 Indic \\
656 Italian \>
657 Latin \>
658 Manju \>
659 Mongolian \\
660 Norwegian \>
661 Polish \>
662 Portuguese \>
663 Spanish \\
664 Swedish \>
665 Tibetan \>
666 \acro{UK} English \>
667 Vietnamese \\
668 \end{tabbing}
669
670 \noindent Language collections typically include fonts, macros,
671 hyphenation patterns, and other support files. (For instance,
672 \pkgname{frenchle.sty} is installed if you select the \optname{French}
673 collection.) In addition, installing a language collection will alter
674 the \filename{language.dat} configuration file controlling which
675 hyphenation patterns are loaded.
676
677 \textbf{\optname{d} -- Installation directories}. Three directories can
678 be changed here:
679 \label{text:instdir}
680
681 \begin{ttdescription}
682 \item [TEXDIR] The top-level directory under which
683 everything else will be installed. The default value is
684 \dirname{/usr/local/texlive/2005}, and is often changed. We recommend
685 including the year in the name, to keep different releases of \TL{}
686 separate. (You may wish to make a version-independent name such
687 \dirname{/usr/local/texlive} via a symbolic link, which you can then
688 update after testing the new release.)
689
690 Under \MacOSX, the usual frontends look for \TeX{} in
691 \dirname{/usr/local/teTeX}, so you may wish to install \TL{} there.
692
693 \item [TEXMFLOCAL] This tree is where the \TeX{} system (not as part of
694 the initial installation, but rather as time goes by) puts
695 non-version-specific files, primarily fonts. The default value is
696 \dirname{/usr/local/texlive/texmf-local}, independent of the current
697 \TL{} release, because it's also the recommended location to put any
698 local packages or configuration settings.
699
700 \item [TEXMFSYSVAR] This tree is where \cmdname{texconfig-sys} puts
701 files that \emph{are} version-specific. The default value is
702 \dirname{TEXDIR/texmf-var}, and there's generally no reason to change
703 it. There is also \envname{TEXMFSYSCONFIG}, which is where
704 \cmdname{texconfig} looks for modified configuration data. See
705 section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig} for more
706 information.
707
708 \end{ttdescription}
709
710 \textbf{\optname{o} -- Other options.} From this menu, you can select
711 the following general options:
712
713 \begin{ttdescription}
714 \item [a] Specify an alternate directory for generated fonts.
715 The default is to use the \envname{TEXMFVAR} tree, as explained above.
716 Setting this is useful if you plan to mount the main tree read-only, and
717 therefore you need another location (perhaps host-specific) for
718 dynamically created fonts.
719
720 \item [l] Create symbolic links for the binaries, man pages,
721 and\slash or \acro{GNU} Info files in other locations. For example, you may
722 wish to make the man pages available under \dirname{/usr/local/man} and
723 the Info files available under \dirname{/usr/local/info}. (Of course
724 you need appropriate privileges to write in the specified directories.)
725
726 It is not advisable to overwrite a \TeX\ system that came with your
727 system with this option. It's intended primarily for creating the links
728 in standard directories that are known to users, such as
729 \dirname{/usr/local/bin}, which don't already contain any \TeX\ files.
730
731 \item [d] Skip installation of the font/macro documentation tree.
732 This is useful if you need to save space, or if you've previously
733 installed the documentation elsewhere.
734
735 \item [s] Skip installation of the main font/macro source
736 tree. This is useful if you are arranging to share that tree between
737 machines and\slash or architectures in some other way, such as \acro{NFS}.
738
739 \end{ttdescription}
740
741 \textbf{i -- Perform installation.} When you're satisfied with your
742 configuration options, enter \Ucom{i} to actually do the installation
743 from the media to your chosen locations.
744
745 % text is similar to above, but no TEXMFSYSVAR, so we have to write out.
746 After the installation completes, your next step is to include the
747 architecture-specific subdirectory of \dirname{TEXDIR/bin} in your
748 \envname{PATH}, so the newly-installed programs can be found. The
749 architecture names are listed in table~\ref{tab:archlist},
750 \p.\pageref{tab:archlist}, or you can simply list the directory
751 \dirname{TEXDIR/bin}.
752
753 The syntax for doing this, and the initialization file to use, depends
754 on your shell. If you use a Bourne-compatible shell (\cmdname{sh},
755 \cmdname{bash}, \cmdname{ksh}, et al.), put the following into your
756 \filename{$HOME/.profile} file:
757
758 \begin{alltt}
759 PATH=/usr/local/texlive/2005/bin/\var{archname}:$PATH; export PATH
760 \end{alltt}
761
762 \noindent For C shell-compatible shells (\cmdname{csh}, \cmdname{tcsh}),
763 put the following into your \filename{$HOME/.cshrc} file:
764 \begin{alltt}
765 setenv PATH /usr/local/texlive/2005/bin/\var{archname}:$PATH
766 \end{alltt}
767
768 \textruntexconfig
769
770 Here is a minimal annotated example which accepts the default
771 directories and installs binaries for the current system only. Thus,
772 only one command is needed, \Ucom{i} for install. The \texttt{>} is the
773 shell prompt as usual.
774
775 \begin{alltt}
776 > \Ucom{sh install-tl.sh}
777 \Ucom{i} # perform installation
778 > \Ucom{texconfig} ... # see section \ref{sec:texconfig}
779 # New PATH element, with Linux as the example:
780 > \Ucom{PATH=/usr/local/texlive/2005/bin/i386-linux:$PATH; export PATH}
781 \end{alltt}
782
783 \textifindoubt
784
785
786 %
787 \subsection{Installing individual packages to disk}
788
789 You can add individual packages or collections from the current
790 distribution to an existing non-\TL{} setup, or an earlier
791 \TL{} installation.
792
793 \startinst
794
795 Run the installation script \filename{install-pkg.sh} (not
796 \filename{install-tl.sh}, which is intended for complete installations
797 only):
798 \begin{alltt}
799 > \Ucom{sh install-pkg.sh \var{options}}
800 \end{alltt}
801
802 The first set of options controls what gets read:
803
804 \begin{ttdescription}
805 \item [-{}-package=\var{pkgname}] The individual package to work on.
806
807 \item [-{}-collection=\var{colname}] The individual collection to work on.
808
809 \item [-{}-nodoc] Exclude documentation files from the operation.
810
811 \item [-{}-nosrc] Exclude source files from the operation.
812
813 \item [-{}-cddir=\var{dir}] Source directory to read from; defaults
814 to the current directory. If you followed the instructions above, that
815 will be the distribution directory, and won't need to be changed.
816
817 \item [-{}-listdir=\var{dir}] The so-called `lists' directory within
818 \var{cddir} from which to read the package information. The only
819 reason to change the default is if you're making changes to \TL{}
820 yourself.
821
822 \end{ttdescription}
823
824 What actually happens is controlled by the following options. If
825 neither of these are specified, the default action is to install the
826 selected files. The main destination tree is found by expanding
827 \envname{\$TEXMFMAIN} with \cmdname{kpsewhich}. You can override it by
828 setting either the environment variable \envname{TEXMFMAIN} or
829 \envname{TEXMF}.
830
831 \begin{ttdescription}
832 \item [-{}-listonly] List the files that would be installed, but don't
833 actually install anything.
834
835 \item [-{}-archive=\var{tarfile}] Instead of installing the files into
836 the \TeX{} system, make a \cmdname{tar} archive.
837
838 \end{ttdescription}
839
840 Additional options:
841
842 \begin{ttdescription}
843
844 \item [-{}-config] After installation, run \code{texconfig init}.
845
846 \item [-{}-nohash] After installation, don't run \cmdname{mktexlsr} to
847 rebuild the filename database.
848
849 \item [-{}-verbose] Give more information as the script runs.
850
851 \end{ttdescription}
852
853 Here are some usage examples:
854
855 \begin{enumerate}
856
857 \item To see the files in the package \pkgname{fancyhdr} without
858 installing it:
859
860 \begin{alltt}
861 \ifSingleColumn> \Ucom{sh install-pkg.sh --package=fancyhdr --listonly}
862 \else> \Ucom{sh install-pkg.sh --package=fancyhdr \bs}
863 > \Ucom{--listonly}
864 \fi{}
865 texmf/doc/latex/fancyhdr/README
866 texmf/doc/latex/fancyhdr/fancyhdr.pdf
867 ...
868 \end{alltt}
869
870 \item Install the \LaTeX{} package \pkgname{natbib}:
871 \begin{alltt}
872 > \Ucom{sh install-pkg.sh --package=natbib}
873 \end{alltt}
874
875 \item Install the \LaTeX{} package \pkgname{alg} without source files or
876 documentation:
877 \begin{alltt}
878 \ifSingleColumn> \Ucom{sh install-pkg.sh --package=alg --nosrc --nodoc}
879 \else> \Ucom{sh install-pkg.sh -{}-package=alg \bs}
880 > \Ucom{-{}-nosrc -{}-nodoc}
881 \fi\end{alltt}
882
883 \item Install all the packages in the collection of additional
884 plain \TeX\ macros:
885 \begin{alltt}
886 > \Ucom{sh install-pkg.sh --collection=tex-plainextra}
887 \end{alltt}
888
889 \item Write all files in the \pkgname{pstricks} package to a
890 \cmdname{tar} file in \path|/tmp|:
891 \begin{alltt}
892 \ifSingleColumn> \Ucom{sh install-pkg.sh --package=pstricks --archive=/tmp/pstricks.tar}
893 \else
894 > \Ucom{sh install-pkg.sh -{}-package=pstricks \bs}
895 > \Ucom{-{}-archive=/tmp/pstricks.tar}
896 \fi\end{alltt}
897
898 \end{enumerate}
899
900 \textifindoubt
901
902
903 %
904 \section{Post-installation}
905 \label{sec:postinstall}
906
907 After the main installation is done, for any operating system, the
908 remaining steps are to configure the system for your local needs, and
909 perform some basic tests.
910
911 Another sort of post-installation is to acquire packages, fonts, or
912 programs that were not included in \TL{}. The basic idea is to
913 install such additions in the \envname{TEXMFLOCAL} tree (if you
914 installed to disk), or \envname{TEXMFSYSVAR} (if you are running live).
915 See the ``Installation directories'' option on \p.\pageref{text:instdir}.
916
917 Unfortunately, the details can and do vary widely, and so we do not attempt to
918 address them here. Here are some external links to descriptions:
919 \begin{itemize*}
920 \item
921 \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=instpackages}
922 \item
923 \url{http://www.ctan.org/installationadvice}
924 \item
925 \url{http://www.ctan.org/tex-archive/info/beginlatex/html/chapter5.html#pkginst}
926 \item
927 \url{http://www.ctan.org/tex-archive/info/Type1fonts} for
928 installation information for fonts in particular.
929 \end{itemize*}
930
931
932 \subsection{The \protect\cmdname{texconfig} program}
933 \label{sec:texconfig}
934
935 At any time after installation, you can and should use the program
936 \cmdname{texconfig} to configure the system to fit your local needs. It
937 is installed in the architecture-specific subdirectory
938 \texttt{TEXDIR/bin/\var{arch}} along with everything else.
939
940 If you run it without arguments, it will enter full-screen mode and
941 allow you to view and change options interactively.
942
943 You can also run it with various command-line options. Here are some of
944 the most common (\TL{} is configured for the A4 paper size by default):
945
946 \begin{ttdescription}
947
948 \item [texconfig paper letter] Set default paper size for
949 various programs and drivers (\cmdname{pdftex}, \cmdname{dvips},
950 \cmdname{dvipdfm}, \cmdname{xdvi}) to be \acro{US} letter. The other
951 allowable size is \optname{a4}, which is the default.
952
953 \item [texconfig rehash] Update all the \TeX{} ``filename databases'',
954 after adding or removing files.
955
956 \item [texconfig faq] Show the \teTeX{} \acro{FAQ}.
957 (See also the main \TeX{} \acro{FAQ} in \OnCD{texmf-doc/doc/english/FAQ-en}.)
958
959 \item [texconfig help] Output help information for \cmdname{texconfig}.
960
961 \end{ttdescription}
962
963 Of course, \cmdname{texconfig} can only support changing a few of the
964 many options and configuration parameters in a \TeX{} system. The main
965 configuration file for the base \Webc{} programs is named
966 \filename{texmf.cnf}. You can find its location by running
967 \samp{kpsewhich texmf.cnf}; it contains many comments explaining the
968 default settings and useful alternatives.
969
970 As of 2005, \cmdname{texconfig} alters files in a user-specific
971 directory, namely \dirname{$HOME/.texlive2005}. If you install \TeX\
972 just for yourself, that is unlikely to make a difference. But if you
973 install \TeX\ on a multi-user system, you will want to change the
974 configuration for the whole system. In this case, run
975 \cmdname{texconfig-sys} instead of \cmdname{texconfig}.
976
977 Likewise, the \cmdname{updmap} and \cmdname{fmtutil} scripts were
978 changed, to work under \dirname{$HOME/.texlive2005}. To alter system
979 directories, use \cmdname{updmap-sys} and \cmdname{fmtutil-sys}.
980
981 In particular, for multi-user systems, you will probably want to
982 pregenerate the standard formats with \texttt{fmtutil-sys --missing}.
983 Otherwise, each user will end up with their own formats.
984
985 Also, if you have a personally-modified copy of \filename{fmtutil.cnf}
986 or \filename{updmap.cfg}, instead of using the ones generated by
987 installation, they must be installed in the tree referenced by the
988 variable \envname{TEXMFSYSCONFIG}.
989
990 The variables specifying the directories altered by these commands are
991 listed in section~\ref{sec:texmftrees}, \p.\pageref{sec:texmftrees}.
992 You can see the actual directories by running \texttt{texconfig conf},
993 and you can change them by editing \filename{texmf.cnf}.
994
995
996 \subsection{Testing the installation}
997 \label{sec:test-install}
998
999 After installing \TL{} as best you can, you naturally want to test
1000 it out, so you can start creating beautiful documents and\slash or fonts.
1001
1002 This section gives some basic procedures for testing that the new system
1003 is functional. We give Unix commands; under \MacOSX{} and Windows,
1004 you're more likely to run the tests through a graphical interface, but
1005 the principles are the same.
1006
1007 \begin{enumerate}
1008
1009 \item Make sure that you can run the \cmdname{tex} program in the first
1010 place:
1011
1012 \begin{alltt}
1013 > \Ucom{tex -{}-version}
1014 TeX 3.141592 (Web2C 7.5.5)
1015 kpathsea version 3.5.5
1016 ...
1017 \end{alltt}
1018 If this comes back with `command not found' instead of version and
1019 copyright information, most likely you don't have the correct
1020 \dirname{bin} subdirectory in your \envname{PATH}. See
1021 the environment-setting information on \p.\pageref{text:path}.
1022
1023 \item Process a basic \LaTeX{} file:
1024 \begin{alltt}
1025 > \Ucom{latex sample2e.tex}
1026 This is pdfeTeXk, Version 3.141592...
1027 ...
1028 Output written on sample2e.dvi (3 pages, 7496 bytes).
1029 Transcript written on sample2e.log.
1030 \end{alltt}
1031 If this fails to find \filename{sample2e.tex} or other files, perhaps
1032 you have interference from old environment variables or configuration
1033 files. For a deep analysis, you can always ask \TeX{} to report on
1034 exactly what it is searching for, and finding; see ``Debugging actions''
1035 on page~\pageref{Debugging}.
1036
1037 \item Preview the result online:
1038 \begin{alltt}
1039 > \Ucom{xdvi sample2e.dvi}
1040 \end{alltt}
1041 (Under Windows, the analogous command is \cmdname{windvi}.) You should
1042 see a new window with a nice document explaining some of the basics of
1043 \LaTeX{}. (Well worth reading, by the way if you're new to the system.)
1044 You do have to be running under X for \cmdname{xdvi} to work; if you're
1045 not, or your \envname{DISPLAY} environment variable is set incorrectly,
1046 you'll get an error \samp{Can't open display}.
1047
1048 \item Create a \PS{} file for printing or display:
1049 \begin{alltt}
1050 > \Ucom{dvips sample2e.dvi -o sample2e.ps}
1051 \end{alltt}
1052
1053 \item Create a \acro{PDF} file instead of \dvi{}; this processes the
1054 \filename{.tex} file and writes \acro{PDF} directly:
1055 \begin{alltt}
1056 > \Ucom{pdflatex sample2e.tex}
1057 \end{alltt}
1058
1059 \item Preview the \acro{PDF} file:
1060 \begin{alltt}
1061 > \Ucom{gv sample2e.pdf}
1062 \textrm{or:}
1063 > \Ucom{xpdf sample2e.pdf}
1064 \end{alltt}
1065 Unfortunately neither \cmdname{gv} nor \cmdname{xpdf} are currently
1066 included in \TL{}, so you must install them separately. See
1067 \url{http://www.gnu.org/software/gv} and
1068 \url{http://www.foolabs.com/xpdf}, respectively.
1069
1070 \item Other standard test files you may find useful:
1071
1072 \begin{ttdescription}
1073 \item [small2e.tex] A simpler document than \filename{sample2e}, to
1074 reduce the input size if you're having troubles.
1075 \item [testpage.tex] Test if your printer introduces any offsets.
1076 \item [nfssfont.tex] For printing font tables and tests.
1077 \item [testfont.tex] Also for font tables, but using plain \TeX{}.
1078 \item [story.tex] The most canonical (plain) \TeX{} test file of all.
1079 You must type \samp{\bs bye} to the \code{*} prompt after \samp{tex
1080 story.tex}.
1081 \end{ttdescription}
1082 You can process these in the same way as we did with
1083 \filename{sample2e.tex}.
1084
1085 \end{enumerate}
1086
1087 If you are new to \TeX{}, or otherwise need help with actually
1088 constructing \TeX{} or \LaTeX{} documents, please visit
1089 \url{http://tug.org/begin.html} for some introductory resources.
1090
1091
1092 \section{\MacOSX{} installation}
1093 \label{sec:mac-install}
1094
1095 The recommended way to install \TeX\ on \MacOSX\ is from the Mac\TeX\
1096 distribution, new in 2005. This is provided on the \pkgname{live}
1097 \DVD{} in the top-level \dirname{mactex/} directory. It contains its
1098 own (native) installer for a full \TeX\ distribution, based on a
1099 combination of te\TeX\ and \TL, along with many additional applications
1100 and documentation. The project web page is \url{http://tug.org/mactex}.
1101
1102 If you prefer, installation of \TeX{} under \MacOSX{} can also be done
1103 directly from \TL, using the \filename{install*} scripts, as follows.
1104
1105 In order to run the installation scripts under \MacOSX, you need to have
1106 the \cmdname{bash} shell installed. If you are running \MacOSX~10.2
1107 or later, you have \cmdname{bash}, and can proceed. If you're running
1108 an earlier \MacOSX{} version, however, the default shell is
1109 \cmdname{zsh}, which won't work; you'll need to get \cmdname{bash} from
1110 the Internet, or more likely upgrade your system.
1111
1112 Once you have \cmdname{bash}, the Unix installation documentation in the
1113 previous section can be followed. See section~\ref{sec:unix-install} on
1114 \p.\pageref{sec:unix-install}; \MacOSX-specific notes are included there
1115 where needed.
1116
1117 \section{Windows installation}
1118 \label{sec:win-install}
1119
1120 In this release of \TL{}, happily, the distribution once
1121 again has a native Windows installer, named \cmdname{tlpmgui.exe}. (See
1122 section~\ref{sec:multiple-dist}, \p.\pageref{sec:multiple-dist}, for an
1123 explanation of the different distributions.)
1124
1125 \cmdname{tlpmgui} has essentially the same options as the Unix
1126 installer, only done through a GUI interface: selecting schemes,
1127 individual collections, installation directories, and so on.
1128 Section~\ref{sec:unix-install-disk} on
1129 \p.\pageref{sec:unix-install-disk} describes the basic elements. It
1130 also allows some post-installation activities such as adding/removing
1131 packages, updating the filename database and building formats.
1132 Moreover, \cmdname{tlpmgui} can setup the system for running
1133 programs directly from the \DVD.
1134
1135 For those who like to look underneath the hood, \cmdname{tlpmgui} uses
1136 as its ``engine'' a command-line Windows program named \cmdname{tlpm}.
1137
1138 The Windows \TeX{} system included in \TL{} is based on new binaries
1139 borrowed from the \XEmTeX{} project, formerly known as \fpTeX{} (see
1140 \url{http://www.metz.supelec.fr/~popineau/xemtex-1.html}).
1141 It also includes some older (but still working) tools, notably
1142 a \texttt{dvi} previewer, \textsf{Windvi}, which is similar in usage to
1143 the established Unix \textsf{xdvi}. The documentation can be found in
1144 \OnCD{texmf/doc/html/windvi/windvi.html}.
1145
1146 \TL{} can be installed on systems running Windows 98, \acro{ME},
1147 \acro{NT}, \acro{2K} or \acro{XP}. Older versions of Windows (3.1x)
1148 and \acro{MS-DOS} are not supported.
1149
1150 \textbf{Warning:} Win9.x users must ensure they have enough environment
1151 space before undertaking installation. The \cmdname{tlpmgui.exe}
1152 program won't change the environment size for them. A few environment
1153 variables will be created and it is possible you run out of
1154 environment space. Add \texttt{SHELL=<path>COMMAND.COM /E:4096 /P} in the
1155 config.sys file in order to increase your environment size.
1156
1157 \subsection{Installing \protect\TeX\protect\ Live to disk}
1158
1159 After inserting the \TL{} CD into the \acro{CD} drive, autostart should
1160 activate \cmdname{tlpmgui}. If it does not, click \guiseq{Start\arw Run},
1161 then type \verb|<drive letter>:\setup-win32\tplmgui.exe| (or
1162 \verb|<drive letter>:\texlive\setup-win32\tplmgui.exe| if you are
1163 installing from the TeX Collection DVD), where \verb|<drive letter>|
1164 is the drive letter with the TeX Live CD (or TeX Collection DVD), and
1165 then click OK.
1166
1167 The installation window titled \guiseq{TeX Live installation and maintenance
1168 utility} should open. It contains the following sections: \guiseq{Main
1169 customization}, \guiseq{Install}, \guiseq{Select a scheme}, \guiseq{Select
1170 systems}, \guiseq{Directories} and \guiseq{Options}.
1171
1172 In the \guiseq{Directories} section the installation drive (directory) next
1173 to the \guiseq{CD/DVD} button should be displayed (e.g., \texttt{F:/} or \texttt{F:/texlive/} for the DVD), but
1174 if it is not, then click the \guiseq{CD/DVD} button and select the \acro{CD/DVD}
1175 drive, with the \TL{} CD (or TeX Collection DVD).
1176
1177 The directory in which you wish to install the software can be set by
1178 clicking the \guiseq{TLroot} button. This directory will be set as
1179 \path|TLroot| environment variable for later usage. The \path|TEXMFTEMP| and
1180 \path|TEXMFCNF| environment variables as displayed next to the
1181 \guiseq{TEXMFTEMP} and \guiseq{TEXMFCNF} buttons will be adjusted
1182 automatically and set during installation, but they can also be adjusted
1183 manually now to suit special needs.
1184
1185 In the \guiseq{Select a scheme} section the desired \TL{} installation scheme
1186 should be chosen by clicking the radio button labelled with the installation
1187 scheme name (e.g., \guiseq{scheme-gust}). Each scheme is accompanied by an
1188 \guiseq{Info} button which, when clicked, displays a short description of the
1189 relevant scheme.
1190
1191 A scheme is a large set of files targeted at some kind of usage. There are
1192 generic schemes for basic, medium and full installations. The remaining ones
1193 are either targeted at certain LUGs (i.e., what GUST or GUTenberg propose
1194 for their members) or application targeted (e.g., for XML and \TeX{}
1195 cooperation). A preselected scheme can be refined. This is done in the
1196 \guiseq{Main customization} section by choosing additional collections from
1197 \guiseq{Standard collections} or \guiseq{Language collections}. For example,
1198 by clicking the \guiseq{Select} button labelled \guiseq{Standard
1199 collections}, additional collections like Metapost, Omega or documentation
1200 in different languages can be selected.
1201
1202 \textbf{Note:} The \guiseq{Ghostscript}, \guiseq{Perl} and \guiseq{Wintools}
1203 collections are selected by default and should be installed unless they are
1204 already installed and you really know what you are doing. This is because
1205 they are required by many important tools. The \verb|PERL5LIB| and
1206 \verb|GS_LIB| environment variables will be set too.
1207
1208 Next, clicking the \guiseq{Select} button labelled \guiseq{Language
1209 Collections} in the \guiseq{Main customization} section opens the
1210 \guiseq{Language collections} window in which the installation language can
1211 be chosen by ticking the box next to the language.
1212
1213 Next, click the \guiseq{Install} button in the \guiseq{Install} section to
1214 start the installation proper process.
1215
1216 The \TL{} system needs some post-processing steps (format files
1217 generation, ls-R databases generation, environment variables, etc.). All
1218 these operations are done there, some of them can be lengthy. So please wait
1219 until you see a statement about the successfully finished installation.
1220
1221 The shortcut for \cmdname{tlpmgui} will be added to the
1222 \guiseq{Start\arw Programs\arw TeXLive2005} menu.
1223
1224 If it is needed (Win9x/WinME), you will be asked to reboot your computer.
1225
1226 \subsection{Support packages for Windows}
1227 \label{sec:win-xemtex}
1228
1229 To be complete, a \TL installation needs support packages that are not
1230 commonly found on a Windows machine. Many scripts are written using the Perl
1231 language. Some important tools require the Ghostscript \PS{} interpreter to
1232 render or to convert files. A graphic file toolbox is also needed in some
1233 cases. Last but not least, a \TeX-oriented editor makes it easy to type in
1234 your \TeX{} files.
1235
1236 All these tools are quite easy to find for Windows, but in order to try to
1237 make your life even easier, we have put such a set of tools on \TL:
1238 \begin{itemize*}
1239 \item GNU \cmdname{Ghostscript} 7.07
1240 \item a minimal \cmdname{Perl} 5.8, sufficient to run all the \TL{}
1241 Perl scripts.
1242 \item win-tools is a set of small programs (bzip2, gzip, jpeg2ps
1243 and tiff2png)
1244 %\item a subset of \cmdname{ImageMagick} 5.5.6
1245 %\item the \cmdname{ISpell} checker
1246 %\item \cmdname{XEmacs} 21.5.14 with a selection of packages to support
1247 %\TeX{} typesetting.
1248 \end{itemize*}
1249
1250 These packages are borrowed from the \XEmTeX{} distribution
1251 (the successor of fp\TeX).
1252
1253 Perl and Ghostscript are installed by default; you may explicitly
1254 deselect them during installation if you already have them.
1255
1256 If you don't want to install this bundle, then you are on your own to
1257 install the required tools to complete your \TL{} system. Here is a
1258 list of places to get those tools:
1259
1260 \begin{description}
1261 \item[Ghostscript] \url{http://www.cs.wisc.edu/~ghost/}
1262 \item[Perl] \url{http://www.activestate.com/} (but you might need some
1263 supplementary packages from CPAN: \url{http://www.cpan.org/})
1264 \item[ImageMagick] \url{http://www.imagemagick.com}
1265 \item[NetPBM] alternatively, you could use NetPBM instead of ImageMagick to
1266 process or convert your graphic files. NetPBM home page is
1267 \url{http://netpbm.sourceforge.net/}
1268 \item[\TeX-oriented editors] There is a wide choice, and it is a matter of the
1269 user's taste. Here is a selection:
1270 \begin{itemize*}
1271 \item \cmdname{GNU Emacs} is available natively under Windows, see
1272 \url{http://www.gnu.org/software/emacs/windows/ntemacs.html}
1273 \item \cmdname{XEmacs} is available natively under Windows, see
1274 \url{http://www.xemacs.org/}
1275 \item \cmdname{WinShell} is available on \TL in the \path|support|
1276 directory, see \url{http://www.winshell.de}
1277 \item \cmdname{WinEdt} is shareware available from \url{http://www.winedt.com}
1278 \item \cmdname{Vim} is available on \TL{} in the
1279 \path|support\vim| directory and the
1280 reference site is \url{http://www.vim.org}
1281 \item TeXnicCenter is free software, available from
1282 \url{http://www.toolscenter.org} and in the proTeXt distribution.
1283 \item \cmdname{LEd} is available from \url{http://www.ctan.org/support/LEd}
1284 \item \cmdname{SciTE} is available from \url{http://www.scintilla.org/SciTE.html}
1285 \end{itemize*}
1286 \end{description}
1287
1288 You might want to install other tools that are not free\footnote{Not
1289 free, that is, in the sense of freedom to modify and redistribute,
1290 following free software guidelines. This does not mean you can't acquire
1291 them for no money.} and therefore not included on \TL{}, such as
1292 \cmdname{GSView}, the \cmdname{Ghostscript} companion to more
1293 conveniently view PS/PDF files. \cmdname{GSView} is available from
1294 \url{http://www.cs.wisc.edu/~ghost/gsview/} or any \acro{CTAN} site.
1295
1296 \section{Maintenance of the installation in Windows}
1297
1298 If you have TeX Live installed, you can use \cmdname{tlpmgui} again
1299 for modyfying and maintaining your installation.
1300
1301 \subsection{Adding/removing packages}
1302
1303 As the \cmdname{tlpmgui} shortcut is available in the \guiseq{Start\arw
1304 Programs\arw TeXLive2005} menu, start it from here. The maintenance window
1305 titled \guiseq{TeX Live installation and maintenance utility} shows. It
1306 contains several tabs: \guiseq{Add Packages}, \guiseq{Remove packages},
1307 \guiseq{Manage installation}, \guiseq{Remove installation}.
1308
1309 Click the tab labelled \guiseq{Add packages} or \guiseq{Remove packages}
1310 to enter the relevant functionality and then:
1311
1312 \begin{itemize}
1313 \item In the first tab select the proper \CD{} drive (or \DVD with
1314 \texttt{texlive} directory) by pressing the \guiseq{CD/DVD} button.
1315 \item Click the \guiseq{Search} button in the \guiseq{Buttons} section to
1316 display or refresh in the \guiseq{Select packages to\dots} section the
1317 list of packages to install or remove.
1318
1319 When adding packages, the list of installed packages is compared to the list
1320 of packages available from your \CD/\DVD. Only packages not already installed are
1321 displayed. It is up to you to select which packages you want to
1322 install.
1323
1324 When removing individual packages, only a list of installed packages
1325 will be displayed.
1326
1327 Please note that for both \guiseq{Add packages} and \guiseq{Remove packages}
1328 the collections are listed first.
1329
1330 \item Select a package by clicking on the name of the package. Clicking the
1331 \guiseq{Info} button in the \guiseq{Buttons} section displays a short
1332 description of the selected package in the window located in the \guiseq{Info
1333 about the selected item} section. To select several packages at once hold
1334 down one of the Ctrl or Shift keys at your keyboard while holding down the
1335 left mouse button or drag the mouse pointer while holding down the left mouse
1336 button.
1337
1338 \item Click the \guiseq{Install} or \guiseq{Remove} button in the
1339 \guiseq{Buttons} section to perform the appropriate action.
1340 \end{itemize}
1341
1342 \subsection{Configuring and other management tasks}
1343
1344 The functions available in the tab labelled \guiseq{Manage the installation}
1345 are helpful in performing actions needed when you want to add support for a
1346 language which was not selected during the installation, or add/regenerate a
1347 format which was not selected during the installation or was modified after
1348 the installation.
1349
1350 The following actions can be performed:
1351
1352 \begin{itemize}
1353 \item Refresh the \filename{ls-R} database
1354 \item Create formats (All or Missing)
1355 \item Edit \filename{language.dat}
1356 \item Edit \filename{fmtutil.cnf}
1357 \item Edit \filename{updmap.cfg}
1358 \end{itemize}
1359
1360 Note: you can close the Edit\dots{} window with the \guiseq{Cancel} or
1361 \guiseq{Done} button; the latter will start rebuilding the format files
1362 (or the fontmap files if you have edited \filename{updmap.cfg}), followed by a
1363 \filename{ls-R} database files refresh.
1364
1365 For more information about the configuration see section~\ref{sec:persconf},
1366 \p.\pageref{sec:persconf}.
1367
1368 \subsection{Uninstalling \protect\TL{}}
1369
1370 The tab labelled \guiseq{Remove the TeX Live installation} opens a window
1371 which contains functionality not worth describing and we do not know who would
1372 need it and what it is for\dots :-)
1373
1374 Anyway, if you have the \path|texmf-local| directory for your local additions,
1375 the removal procedure will not wipe it out or delete things in it. The \path|setup-win32|
1376 directory containing \cmdname{tlpmgui} and related files will not be deleted. You will have to do some manual cleanup to
1377 actually remove them.
1378
1379 \subsection{Adding your own packages to the installation}
1380
1381 First, whatever changes you make, \textbf{do not forget to rebuild the ls-R
1382 database files}. Otherwise, your new files will not be found. You can do this
1383 either via the \cmdname{tlpmgui} run and selection of the appropriate action
1384 from the \guiseq{Manage the installation} tab, or manually running the
1385 \file{mktexlsr} command.
1386
1387 If you want to add files that are not provided by the \TL{} distribution,
1388 it is recommended to put them in the \path|$TEXMFLOCAL| directory. This
1389 way, you will be safe against upgrades of the \TL{} software.
1390
1391 The directory pointed to by \path|$TEXMFLOCAL| is initially empty. If,
1392 for example, you want to add the support file for the Maple symbolic
1393 computation program, you will have to put the style files in:\\
1394 \path|c:\TeXLive2005\texmf-local\tex\latex\maple\|\\ and the
1395 documentation files in:\\ \path|c:\TeXLive2005\texmf-local\doc\latex\maple\|
1396
1397 \subsection{Running \texttt{tlmp.exe} from the command line}
1398 The \cmdname{tlpm.exe} program which is used as engine by \cmdname{tlpmgui}
1399 has a number of other useful options. You can get the list by running:
1400 \begin{verbatim}
1401 tlpm --help
1402 \end{verbatim}
1403
1404 More information and examples of use can be found in \path|tlpm.readme|.
1405
1406 \subsection{Network installation}
1407
1408 \KPS{} knows about UNC names, so you can use them to get your TEXMF
1409 tree from the network. But there is better than this.
1410 All the support files and configuration files, everything except the files in the
1411 \path|bin/win32| are shareable with a \teTeX{} or Unix \TL{} installation. That means
1412 you can use Samba either to mount from an NT server to a Unix
1413 workstation or the converse. Several strategies are possible:
1414 \begin{itemize}
1415 \item Put everything on the server. Just add each set of files for the OS and
1416 architecture you want to use in the \path|bin| directory. That means
1417 for example \path|bin/win32| and \path|bin/i386-linux|. Next configure
1418 your main variables. You can use UNC names to
1419 point to the right directories under Win32.
1420 \item Install a local copy for the binaries and format files. In this
1421 case, assign \path|$TEXMFMAIN| to the main \path|texmf| tree that
1422 will be accessed remotely. Set \path|$TEXMFVAR| to be a local
1423 directory which will hold local configuration files and on-the-fly
1424 generated files.
1425 \end{itemize}
1426
1427 \subsection{What's different in Windows?}
1428
1429 The Windows version of \Webc{} has some specific features that should be
1430 pointed out.
1431
1432 \begin{description}
1433 \item[\KPS{}] The hash-tables that \KPS{} builds are quite large for
1434 the \TL{}. In order to cut down the starting time of any
1435 \KPS{}-enabled program, these hash-tables have been put in shared
1436 memory. This way, when you chain the execution of several such
1437 programs, like \path|tex| calling \path|mpost| calling \path|tex|,
1438 the overhead when starting each of the subprograms is
1439 reduced. This change is hidden to the user, except if you set the
1440 debug flag of kpathsea to the \path|-1| value: you will then trace
1441 access to the shared memory, which is not what you want (it is
1442 accessed very often!). What is useful in a log trace of the shared
1443 memory access is still to be defined, so the situation might evolve
1444 in the future.
1445 \item[\cmdname{kpsecheck}] This command provides some options that did
1446 not fit well into \cmdname{kpsewhich}. It will allow you to list all
1447 the files that occur multiple times across your texmf trees. This
1448 could be handy, but most of the time you will also get unwanted
1449 output (like dozens of \path|README| files). It is noticeable
1450 that all these files result in clashes inside the \KPS{}-hashing
1451 mechanism; fortunately, \KPS{} never looks for these files. For
1452 this reason, you can combine the \path|-multiple-occurrences| with 2
1453 other options for including or excluding any filename that match
1454 some pattern (you can request for several patterns).
1455
1456 The \cmdname{kpsecheck} command will also report the status of shared
1457 memory: in use or not used. That might be useful to know because if
1458 the status reported is \samp{in use}, that means one or several
1459 processes are working, and the effect of any \cmdname{mktexlsr}
1460 command will be delayed until the next time where no \KPS{} linked
1461 process will be running.
1462
1463 Last, this same command will report about the location it thinks
1464 Ghostscript can be found. Under Win32, for many programs, it is
1465 easier to use the Ghostscript dll, and find it by using the
1466 Ghostscript registry key than to change the \path|PATH|, which has a
1467 limited length anyway.
1468 \item[\Webc{}] The engines have a few more options than in Unix
1469 \Webc{}, and one option with a different behavior:
1470 \begin{itemize}
1471 \item \path|-halt-on-error| stop the compilation at the first error.
1472 \item \path|-job-time| set the job time to the same timestamp as the
1473 file given in argument.
1474 \item \path|-oem| use the DOS codepage for console output.
1475 \item \path|-output-directory| allow to write all the output files in the
1476 specified directory.
1477 \item \path|-time-statistics| print statistics about the job run
1478 time. It is to be noted that Win9x not being a true multitasking
1479 operating system, it has no reliable timer for short periods, so
1480 the value printed is an approximation. Under NT/2K/XP, the result
1481 is quite accurate with user time and system time values allocated
1482 for this run. For Unix
1483 users: the \path|time| command is not usually available to Windows
1484 users.
1485 \end{itemize}
1486 \end{description}
1487
1488 \subsection{Personal configurations}
1489 \label{sec:persconf}
1490
1491 \subsubsection{Dvips}
1492
1493 The configuration file for dvips can be found in\\
1494 \verb+C:\TeXLive2005\texmf-var\dvips\config\config.ps+\\
1495 You may open it with any editor
1496 %(\cmdname{WinShell} will do fine)
1497 and change some parameters:
1498
1499 \begin{description}
1500 \item [fonts] you can change the default printer \MF{} mode or printer
1501 resolution in case \cmdname{dvips} needs to generate PK fonts. By default it
1502 is configured to use Type~1 versions of the CM fonts, so it should
1503 not call \cmdname{mktexpk} too often;
1504 \item[printer] you can tell dvips where you want to print by default. If
1505 the \optname{o} option is not followed by a printer name, then a
1506 \file{.ps} \PS{} file is written. You can give dvips a printer
1507 name such as:
1508 \begin{verbatim}
1509 o lpt1:
1510 % o | lpr -S server -P myprinter
1511 % o \\server\myprinter
1512 \end{verbatim}
1513 \item[paper] Next, you might want
1514 to change the paper size from European (A4) to US letter
1515 by making the US letter the first paper size mentioned in the file.
1516 Scroll to the group of lines beginning with \code{@}. Move
1517 the appropriate lines so that this section begins with the lines:\\
1518 \hspace*{1em} @ letterSize 8.5in 11in\\
1519 \hspace*{1em} @ letter 8.5in 11in\\
1520 \hspace*{1em} @+ \%\%BeginPaperSize: Letter\\
1521 \hspace*{1em} @+ letter\\
1522 \hspace*{1em} @+ \%\%EndPaperSize
1523 \end{description}
1524
1525 The current \TL{} distribution implements the procedure of making
1526 always up-to-date fontmaps files for Dvips and Pdftex. This is done by
1527 the \cmdname{updmap} program during installation, as well as during any
1528 font package addition. If you add new packages by hand, edit the file
1529 \verb+updmap.cfg+ in \path|$TEXMFVAR/web2c|.
1530
1531 \subsubsection{PdfTeX}
1532
1533 If you use the program pdf{}latex to write \acro{PDF} format directly,
1534 and you are using \acro{US} letter-size paper, edit the file
1535 \verb+C:\TeXLive2005\texmf-var\tex\generic\config\pdftexconfig.tex+ and
1536 change \samp{\bs pdfpagewidth} and \samp{\bs pdfpageheight}. These entries
1537 should read:
1538 \begin{alltt}
1539 \bs{}pdfpagewidth=8.5 true in
1540 \bs{}pdfpageheight=11 true in
1541 \end{alltt}
1542 Save the file and exit the editor.
1543
1544 \subsubsection{GSView}
1545 GSView is now distributed under the Aladdin License, and therefore is no
1546 longer included in \TL{}.
1547
1548 If you may want to change the page size to US letter size. If so, open
1549 GSView from the \guiseq{Start} menu, and select \guiseq{Media\arw Letter}.
1550
1551 Also, there are menu settings that are supposed to give you the most
1552 readable screen image. On \guiseq{Media \arw Display Settings}, set both
1553 \optname{Text Alpha} and \optname{Graphics Alpha} to 4~bits.
1554
1555 Note that the installation process has set all \code{.ps} and
1556 \code{.eps} files to automatically open with \cmdname{GSView}.
1557
1558 For printing instructions, see section~\ref{printing} below.
1559
1560 \subsubsection{WinDvi}
1561 \label{sub:windvi}
1562
1563 The \file{tlpmgui.exe} program takes care of associating the files
1564 with the \file{.dvi} extension with \file{Windvi}, but it doesn't make an icon
1565 on the desktop, so please do it yourself.
1566
1567 Open \cmdname{windvi} by clicking an icon or from the command line.
1568
1569 You can set it for US letter-size paper by going to \guiseq{View\arw
1570 Options\arw Papertype} and selecting US (8.5\verb+"+ x 11\verb+"+) (and
1571 then \optname{OK}. Exit \cmdname{windvi}.
1572
1573 You can change other parameters from there as well, such as the ability
1574 to execute system commands specified by the document (disabled by
1575 default for security reasons). Also, the first time you view any .dvi
1576 file, you may find the magnification too large. Zoom out until you get
1577 an appropriate size.
1578
1579 All configuration settings for \cmdname{windvi} are stored in a file
1580 named \path|windvi.cnf| file. You can find it by running this command at
1581 the prompt:
1582 \begin{verbatim}
1583 c:\>kpsewhich --expand-var $HOME/windvi.cnf
1584 \end{verbatim}
1585
1586 Should you have problems with \cmdname{windvi}, please remove the
1587 configuration file and test your problem against a vanilla configuration.
1588
1589 \subsection{Testing}
1590
1591 For generic verification procedures, see section~\ref{sec:test-install}
1592 (\p.\pageref{sec:test-install}). This section describes
1593 Windows-specific tests.
1594
1595 Open the file \verb+sample2e.tex+ in your editor (Xemacs, WinShell),
1596 found in \path|C:\TeXLive2005\texmf-dist\tex\latex\base|. The \LaTeX\ source
1597 should appear on the screen. Process it by clicking on the
1598 \guiseq{Command\arw LaTeX} menu (XEmacs) or \LaTeX\ icon on the toolbar
1599 (WinShell), then view it by clicking on the \guiseq{Command\arw View DVI}
1600 menu (XEmacs) or Preview (Windvi) icon (WinShell).
1601
1602 At first, when you preview files with Windvi, it will create fonts because
1603 screen fonts were not installed. After a while, you will have created most
1604 of the fonts you use, and you will rarely see the font-creation window.
1605
1606 \textbf{Hint for the future:} If a \LaTeX\ run stops because \LaTeX\
1607 cannot find a file, you can press Ctrl-z to quit.
1608
1609
1610 \subsection{Printing}
1611 \label{printing}
1612
1613 It is possible to print from Windvi. In this case, printing will be done
1614 using the Windows unified printer driver. By definition, it is
1615 compatible with all printers. However, there is some drawback: it can
1616 generate some huge spool files, and some (older) versions of Windows
1617 just don't like them. The advantage is that you can use features like
1618 embedding BMP or WMF images. You also need to make sure that the printer
1619 parameters are correctly set (subsection~\ref{sub:windvi}), else you
1620 will get scaled printing (printing at 600\dpi{} on a 300\dpi{} printer
1621 will give you only one quadrant of your page).
1622
1623 Printing is faster and more reliable if you run \cmdname{dvips} to make
1624 a \filename{.ps} file and then print from \cmdname{GSView}. In
1625 \cmdname{GSview}, select \guiseq{File\arw Print\ldots}. A \guiseq{Print}
1626 window will appear.
1627
1628 If you are using a \PS{} printer, \textit{be sure to select
1629 \guiseq{\PS{} Printer}}. This is done in the \guiseq{Print Method} box
1630 at the bottom left of the \guiseq{Print} window. You can then select any
1631 of the printers that you have previously installed. If you fail to
1632 check the box for \optname{\PS{} Printer}, printing will not work.
1633
1634 If you will be using your own non-\PS{} printer, select
1635 \guiseq{Ghostscript device} in the \guiseq{Print Method} box, then click
1636 on the button to the right labelled \guiseq{djet500} and select your
1637 printer type from the list that pops up. (In the older version of
1638 \cmdname{GSView}, make sure \optname{\PS{} Printer} is \textit{not}
1639 selected, then select your printer type from the \guiseq{Device} list.)
1640
1641 \subsection{Tips and tricks for Win32}
1642
1643 \subsubsection{Different flavors of Win32}
1644
1645 What we call Win32 is not an operating system by itself. It is a large
1646 set of functions (around 12,000 in the header files of the Microsoft
1647 \acro{SDK}) that you can use to write programs for different operating
1648 systems of the Windows family.
1649
1650 Windows comes in different flavors:
1651 \begin{itemize}
1652 \item Win95, Win98 and Win\acro{ME}, which \emph{are not true multitasking,
1653 multithreading} environments. They are the latest\Dash and hopefully
1654 last\Dash metamorphosis of \acro{DOS}. This can be more or less proven
1655 by the fact that when booting, the PC will load the \path|command.com|
1656 interpreter, and if you stop the boot process at this point, you can
1657 ask for the current (\acro{DOS}) version and it will answer something
1658 like \samp{MS-DOS 7.0} (at least for the old versions of Win9x).
1659 \item Windows \acro{NT}, which is a new operating system written from
1660 scratch, capable of true multitasking behavior, and including many
1661 high level features.
1662 \item Windows 2000, based on \acro{NT}, with all the bells and
1663 whistles of Win98.
1664 \item Windows \acro{XP}, which comes with Personal and Pro flavors. This is
1665 the last step in merging both lines of products (Win9x based and
1666 \acro{NT} based). \acro{XP} is based on \acro{NT}.
1667 \end{itemize}
1668
1669 Win9x are able to run 32~bits programs and 16~bits programs
1670 concurrently. But the operating system by itself is not entirely
1671 written in 32~bits mode, and does not support memory protection: 16bits
1672 applications can overwrite parts of the operating system memory! Some
1673 parts of the system like the \acro{GDI} (Graphical Device Interface)
1674 manage limited resources like bitmaps, fonts, pens and so on for the set
1675 of all programs that run concurrently. All the bitmaps headers available
1676 at the same time can't amount for more than 64kB. This explains the
1677 performance tool and the fact that you can put your system on his knees
1678 by making intensive use of graphic objects for example.
1679
1680 NT, 2K and XP do not suffer from these limitations, and neither from
1681 other Win9x limitations. They are true multitasking environments, with
1682 protected memory. They are much more responsive than Win9x because
1683 of better memory management, better file system and so on.
1684
1685 \subsubsection{Command line prompt}
1686
1687 You may wonder, ``Why would I need to use a command line prompt when
1688 I have Windows?''
1689
1690 Good question. The problem is of very general nature. Not all operations
1691 can be done easily using only a \acro{GUI}. Command line gives you
1692 programming power\Dash assuming a clever command interpreter.
1693
1694 But the problem here is more fundamental: \TeX{} is \emph{a batch}
1695 tool. Not an interactive one. \TeX{} needs to compute the best
1696 layout for each page, resolve cross-references and so on. This can be
1697 done only by a global processing of the document. It is not (yet) a
1698 task that can be done interactively.
1699
1700 This means that you should use \TeX{} from a command line. In fact the
1701 situation is not so bad. There is an advantage to write command line
1702 tools for complex processing: they are better debugged, because they are
1703 independent of any \acro{GUI} problems, and \acro{GUI} tools can be
1704 designed to interface to the command line tools. This is the case for
1705 \TeX{}, where you will mostly interact with it through a \acro{GUI} text
1706 editor.
1707
1708 However, you may need to use the command line prompt in a number of
1709 situations. One is when you are having difficulties and want to debug
1710 your setup.
1711
1712 \begin{description}
1713 \item[Win9x] You can open a command line prompt by looking either for
1714 the \acro{MS-DOS} icon in the \guiseq{Start\arw Programs} menu,
1715 or by choosing \guiseq{Start\arw Run} menu typing in
1716 \path|command.com| as the progrm name.
1717 \item[NT, 2K, XP] You can open a command line prompt by looking for
1718 \guiseq{Command Prompt} in the \guiseq{Start\arw Accessories} menu.
1719 You can also choose \guiseq{Start\arw Run} and type in
1720 \path|cmd.exe|, which is the name of the brand new command
1721 interpreter for \acro{NT} (thus, it is untrue to call this a
1722 \emph{DOS} box!).
1723 \end{description}
1724
1725 These locations may change across different Windows versions.
1726
1727 \subsubsection{Path separators}
1728
1729 The Win32 API understands both \path|/| and \path|\| characters as PATH
1730 separators. But the command interpreters do not! So whenever a path name
1731 is used programmatically, you can use both separators, and even mix them
1732 up in the same path name. But on the command line, you must type
1733 \path|\| as path separator. The reason is compatibility: the command
1734 processor used \samp{/} to introduce arguments to commands.
1735
1736 All this to say: do not be surprised to read path names written using
1737 the Unix convention; \fpTeX{} is a port of \Webc, and aims to be compatible
1738 across platforms. For this reason, all the configuration files that
1739 need to specify path names use the Unix convention.
1740
1741 \subsubsection{File systems}
1742 \label{sec:clusters}
1743
1744 The worst feature of Win9x with regard to \TeX{} is probably the
1745 so-called FAT file system. \TeX{} uses very many small files, with size
1746 around 1--3kB. The \acro{FAT} file system is old, and predates by
1747 decades the multi-gigabytes hard disks we have today. As a result, it
1748 cannot manage efficiently the tens of thousands of \TeX{} files found in
1749 \TL{}. The \acro{FAT} file system allocates a minimum of 32kB for
1750 \emph{any} file on a huge partition. It means that \TeX{} will use much
1751 more disk space than it actually needs.
1752
1753 The other, more modern, file systems available, \acro{FAT32} and
1754 \acro{NTFS}, do not have this drawback. They manage clusters of 4kB
1755 only. (You can lower the limit to 512 bytes on \acro{NTFS}.)
1756
1757 \subsubsection{How to add some directory to your PATH}
1758
1759 There are pairs of variables and values which behave much like global
1760 variables inside your programs. The set of those variables is called the
1761 environment. Each program is initialized with a copy of the
1762 environment when it is run. It can request and change the
1763 value of any variable. The changes happen in the copy of the
1764 environment, and is not at all propagated to the other running
1765 programs.
1766
1767 Your PATH is a special environment variable used to search for
1768 programs you want to run.
1769 There is a different procedure to change it for Win9x, WinME and NT/2K/XP:
1770
1771 \begin{description}
1772 \item[Windows 95/98] Edit your \path|autoexec.bat|. In this file should be a line
1773 starting with \texttt{PATH=} and followed by a list of directories separated
1774 by \path|;|. Please add the directory with the executables in this line.
1775 After this, this line could look as follows:
1776 \begin{verbatim}
1777 PATH=c:\windows;c:\windows\system;c:\TeXLive2005\bin\win32
1778 \end{verbatim}
1779 \item[Windows ME] You need to run the special program
1780 \path|c:\windows\system\msconfig.exe| to be able to change any
1781 environment variable. From this program, select the `Environment'
1782 tab, and then add or modify the variable you want. You will be asked to reboot the
1783 machine upon any change.
1784 \item[Windows NT/2K/XP]
1785 Click left on \guiseq{Start \arw Settings \arw Control Panel}. Now the
1786 window with the control panel icons opens. Double click on System. The
1787 System Properties window opens. Click on the tab \textsf{Environment}
1788 or look for a button named \guiseq{Environment Variables} among the
1789 dialog boxes. Now you can change the environment variables for your
1790 user account. Note: There are also displayed the environment settings
1791 for the system. Normally, you can't change the system variables
1792 unless you have administrator rights on your machine. If you want to
1793 change the \texttt{PATH} for all users, you will have to contact your
1794 system administrator or be the system administrator yourself\Dash in
1795 the latter case you should know what you are doing.
1796
1797 If there is already a \texttt{PATH} setting for your user account,
1798 left click on \texttt{PATH}. In the field \textsf{Variable} appears
1799 \texttt{PATH} while the field Value shows the current setting of
1800 \texttt{PATH} as a list of directories separated by \path|;|. Add
1801 the directory where the executables are located (e.g.
1802 \path|c:\TeXLive2005\bin\win32|). If there isn't a \texttt{PATH} variable
1803 for your user account, simply click in the field Variable and type
1804 in \texttt{PATH}, click in the field \textsf{Value}
1805 and type in the directory with the executables. Important: Click on
1806 the \textsf{Apply} button before clicking \textsf{Ok}, otherwise the
1807 changes to \texttt{PATH} won't apply to your system. Be careful when
1808 changing the environment settings.
1809 \end{description}
1810
1811 The best way to be sure that a variable has been properly set is to
1812 open a console and type:
1813 \begin{verbatim}
1814 set VARIABLE
1815 \end{verbatim}
1816 which should return the corresponding value.
1817
1818 \subsubsection{\TeX{} engines}
1819
1820 If you have a look at the \Webc{} documentation, you will read that all
1821 the various \TeX{} derived programs use the same base engine. For
1822 example, \path|tex.exe| and \path|latex.exe| are exact copies of the
1823 same program, but each one will use a different format file, based on
1824 its calling name.
1825
1826 Under Unix, this feature is implemented through \emph{symbolic
1827 links}. It saves up a bit of disk space, because some engines are
1828 used with many different format files.
1829
1830 The Win32 API does not know about file links. So to save up almost
1831 the same amount of memory, all the \TeX{} base engines have been put
1832 in DLLs (\emph{Dynamic Linked Library}). This means that you will have
1833 the following layout:
1834 \begin{alltt}
1835 18/09/2005 14:19 3 584 latex.exe
1836 18/09/2005 14:19 3 584 pdfetex.exe
1837 18/09/2005 14:19 524 288 tl90pdfetex.dll
1838 \end{alltt}
1839 and the \path|latex.exe| file is nothing but a rough copy of
1840 \path|pdfetex.exe| using the same core \path|tl90pdfetex.dll|.
1841 The same trick has been used for the \path|mktex*.exe| family of programs
1842 which are linked to the \path|mktex.dll| library.
1843
1844 In fact, a generic tool called \path|irun.exe| is provided to build the
1845 equivalent of Unix hard links for executable files only under Win32.
1846
1847 \subsection{In case of problems}
1848 \label{sec:troubleshooting}
1849
1850 \subsubsection{What to do if \texttt{latex} does not find your files?}
1851
1852 \begin{itemize}
1853
1854 \item \cmdname{kpsewhich} is the tool of choice to debug any
1855 problem. Unfortunately, \cmdname{kpsewhich} outputs debug information
1856 to stderr, and the older Windows consoles do not know how to redirect stderr
1857 to a file. (NT and Windows 2000 consoles know how to do that. But
1858 the trick will work for any console.) For diagnostic purposes you can
1859 temporarily set an environment variable (in a \acro{DOS} box):
1860
1861 \begin{verbatim}
1862 SET KPATHSEA_DEBUG_OUTPUT=err.log
1863 \end{verbatim}
1864 You can also set the debug level:
1865 \begin{verbatim}
1866 SET KPATHSEA_DEBUG=-1
1867 \end{verbatim}
1868
1869 If you want to redirect stderr to stdout, which is not possible
1870 Windows, then do:
1871 \begin{verbatim}
1872 SET KPATHSEA_DEBUG_OUTPUT=con:
1873 \end{verbatim}
1874 This way you can capture both stdout and stderr in the same file.
1875
1876 \item Assuming the installation has been done in \path|c:/TeX|, check
1877 the following values: \\
1878 {\small
1879 \begin{tabular}{ll}
1880 \path|kpsewhich -expand-path $SELFAUTOPARENT| & \path|c:/TeX| \\
1881 \path|kpsewhich -expand-path $TEXMF| & \path|c:/TeX/texmf....| \\
1882 \path|kpsewhich -expand-path $TEXMFCNF| &
1883 \path|.;c:/TeX/texmf-var/web2c;| \\
1884 \path|kpsewhich -expand-var $TEXINPUTS| & \path|.;c:/TeX/texmf/tex//|
1885 \end{tabular}
1886 }
1887 \item If you have other \TeX{}-related values already set in your
1888 environment, please, remove them. They are overriding the ones in
1889 texmf.cnf.
1890 \item Check the values from:\\
1891 {\small
1892 \begin{tabular}{ll}
1893 \texttt{kpsewhich cmr10.tfm} & \path|c:/TeX/texmf/fonts/tfm/public/cm/cmr10.tfm|\\
1894 \texttt{kpsewhich latex.fmt}& \path|c:/TeX/texmf/web2c/latex.fmt|
1895 \end{tabular}
1896 }
1897 \item At this point, if everything is correct, \TeX{} and friends
1898 should work. If it is not the case, you will need to play with
1899 the \path|-debug=n| option from \path|kpsewhich|, and check back all
1900 the values. Try to identify and report the problem.
1901 \end{itemize}
1902
1903 \subsubsection{What to do if your setup still does not work as expected?}
1904
1905 Here are several questions to investigate:
1906
1907 \begin{enumerate}
1908 \item Is \file{tex.exe} in my \path|PATH|?
1909
1910 \item Is the \path|TEXMFCNF| variable correctly set to
1911 \path|c:/TeXLive2005/texmf-var/web2c| (default value)?
1912
1913 \item Are there any errors in the log file generated by the
1914 \file{tlmpgui.exe} program?
1915 \file{tlmpgui.log} can be found in your
1916 \file{TEMP} directory. You can find this by searching for the
1917 string \samp{Error}. Hint: the log file can show some errors after
1918 building all format files. Please do not panic: perhaps some formats
1919 weren't already installed.
1920
1921 \item Are there any relevant bug fixes at \url{http://tug.org/texlive/}?
1922 (Unlikely, but it doesn't hurt to check.)
1923
1924 \end{enumerate}
1925
1926 The \TL{} software consists of hundreds of programs and tens of
1927 thousands of files, all from varying sources. So it is quite difficult to
1928 predict all possible causes for problems. Nevertheless, we will do our
1929 best to help you. (See section~\ref{sec:help}, \p.\pageref{sec:help}.)
1930
1931 % don't use \Webc so the \uppercase in the headline works.
1932 \section{A user's guide to Web2C}
1933
1934 \Webc{} is an integrated collection of \TeX-related programs: \TeX{}
1935 itself, \MF{}, \MP, \BibTeX{}, etc. It is the heart of \TL{}.
1936
1937 A bit of history: The original implementation was by Tomas Rokicki who,
1938 in 1987, developed a first \TeX{}-to-C system based on change files
1939 under Unix, which were primarily the original work of Howard Trickey and
1940 Pavel Curtis. Tim Morgan became the maintainer of the system, and
1941 during this period the name changed to Web-to-C\@. In 1990, Karl Berry
1942 took over the work, assisted by dozens of additional contributors, and
1943 in 1997 he handed the baton to Olaf Weber.
1944
1945 The \Webc{} system runs on Unix, 32-bit Windows systems, \MacOSX{}, and
1946 other operating systems. It uses Knuth's original sources for \TeX{} and
1947 other basic programs written in \web{} and translates them into C source
1948 code. The core \TeX{} programs are:
1949
1950 \begin{cmddescription}
1951 \item[bibtex] Maintaining bibliographies.
1952 \item[dmp] \cmdname{troff} to MPX (\MP{} pictures).
1953 \item[dvicopy] Expands virtual font references in \dvi{} files.
1954 \item[dvitomp] \dvi{} to MPX (MetaPost pictures).
1955 \item[dvitype] \dvi{} to human-readable text.
1956 \item[gftodvi] Generic font proofsheets.
1957 \item[gftopk] Generic to packed fonts.
1958 \item[gftype] GF to human-readable text.
1959 \item[makempx] \MP{} label typesetting.
1960 \item[mf] Creating typeface families.
1961 \item[mft] Prettyprinting \MF{} source.
1962 \item[mpost] Creating technical diagrams.
1963 \item[mpto] MetaPost label extraction.
1964 \item[newer] Compare modification times.
1965 \item[patgen] Creating hyphenation patterns.
1966 \item[pktogf] Packed to generic fonts.
1967 \item[pktype] PK to human-readable text.
1968 \item[pltotf] Plain text property list to TFM.
1969 \item[pooltype] Display \web{} pool files.
1970 \item[tangle] \web{} to Pascal.
1971 \item[tex] Typesetting.
1972 \item[tftopl] TFM to plain text property list.
1973 \item[vftovp] Virtual font to virtual property list.
1974 \item[vptovf] Virtual property list to virtual font.
1975 \item[weave] \web{} to \TeX.
1976 \end{cmddescription}
1977
1978 \noindent The precise functions and syntax of these programs are
1979 described in the documentation of the individual packages and of \Webc{}
1980 itself. However, knowing a few principles governing the whole family of
1981 programs will help you take advantage of your \Webc{} installation.
1982
1983 All programs honor these standard \acro{GNU} options:
1984 \begin{ttdescription}
1985 \item[-{}-help] print basic usage summary.
1986 \item[-{}-verbose] print detailed progress report.
1987 \item[-{}-version] print version information, then exit.
1988 \end{ttdescription}
1989
1990 For locating files the \Webc{} programs use the path searching library
1991 \KPS{}. This library uses a combination of environment variables and a
1992 configuration files to optimize searching the (huge) collection of
1993 \TeX{} files. \Webc{} can look at more than one directory tree
1994 simultaneously, which is useful in maintaining \TeX's standard
1995 distribution and local extensions in two distinct trees. To speed up
1996 file searches the root of each tree has a file \file{ls-R}, containing
1997 an entry showing the name and relative pathname for all files under that
1998 root.
1999
2000 \subsection{Kpathsea path searching}
2001
2002 Let us first describe the generic path searching mechanism of the \KPS{}
2003 library.
2004
2005 We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list
2006 of \emph{path elements}, which are basically directory names. A
2007 search path can come from (a combination of) many sources. To look up
2008 a file \samp{my-file} along a path \samp{.:/dir}, \KPS{} checks each
2009 element of the path in turn: first \file{./my-file}, then
2010 \file{/dir/my-file}, returning the first match (or possibly all
2011 matches).
2012
2013 In order to adapt optimally to all operating systems' conventions, on
2014 non-Unix systems \KPS{} can use filename separators different from
2015 colon (\samp{:}) and slash (\samp{/}).
2016
2017 To check a particular path element \var{p}, \KPS{} first checks if a
2018 prebuilt database (see ``Filename data\-base'' on
2019 page~\pageref{Filename-database}) applies to \var{p}, i.e., if the database
2020 is in a directory that is a prefix of \var{p}. If so, the path
2021 specification is matched against the contents of the database.
2022
2023 If the database does not exist, or does not apply to this path
2024 element, or contains no matches, the filesystem is searched (if this
2025 was not forbidden by a specification starting with \samp{!!}\ and if
2026 the file being searched for must exist). \KPS{} constructs the list
2027 of directories that correspond to this path element, and then checks
2028 in each for the file being sought.
2029
2030 The ``file must exist'' condition comes into play with \samp{.vf} files and
2031 input files read by \TeX's \cs{openin} command. Such files may not
2032 exist (e.g., \file{cmr10.vf}), and so it would be wrong to search the
2033 disk for them. Therefore, if you fail to update \file{ls-R} when you
2034 install a new \samp{.vf} file, it will never be found.
2035 Each path element is checked in turn: first the database, then the
2036 disk. If a match is found, the search stops and the result is
2037 returned.
2038
2039 Although the simplest and most common path element is a directory
2040 name, \KPS{} supports additional features in search paths: layered
2041 default values, environment variable names, config file values, users'
2042 home directories, and recursive subdirectory searching. Thus, we say
2043 that \KPS{} \emph{expands} a path element, meaning it transforms all
2044 the specifications into basic directory name or names. This is
2045 described in the following sections in the same order as it takes
2046 place.
2047
2048 Note that if the filename being searched for is absolute or explicitly
2049 relative, i.e., starts with \samp{/} or \samp{./} or \samp{../},
2050 \KPS{} simply checks if that file exists.
2051
2052 \ifSingleColumn
2053 \else
2054 \begin{figure*}
2055 \verbatiminput{examples/ex5.tex}
2056 \setlength{\abovecaptionskip}{0pt}
2057 \caption{An illustrative configuration file sample}
2058 \label{fig:config-sample}
2059 \end{figure*}
2060 \fi
2061
2062 \subsubsection{Path sources}
2063 \label{Path-sources}
2064
2065 A search path can come from many sources. In the order in which
2066 \KPS{} uses them:
2067
2068 \begin{enumerate}
2069 \item
2070 A user-set environment variable, for instance, \envname{TEXINPUTS}\@.
2071 Environment variables with a period and a program name appended
2072 override; e.g., if \samp{latex} is the name of the program being run,
2073 then \envname{TEXINPUTS.latex} will override \envname{TEXINPUTS}.
2074 \item
2075 A program-specific configuration file, for exam\-ple, a line
2076 \samp{S /a:/b} in \cmdname{dvips}'s \file{config.ps}.
2077 \item A \KPS{} configuration file \file{texmf.cnf}, containing a line like
2078 \samp{TEXINPUTS=/c:/d} (see below).
2079 \item The compile-time default.
2080 \end{enumerate}
2081 \noindent You can see each of these values for a given
2082 search path by using the debugging options (see ``Debugging actions''
2083 on page~\pageref{Debugging}).
2084
2085 \subsubsection{Config files}
2086
2087 \begingroup\tolerance=3500
2088 \KPS{} reads \emph{runtime configuration files} named \file{texmf.cnf}
2089 for search path and other definitions. The search path used to look
2090 for these files is named \envname{TEXMFCNF} (by default such a file lives
2091 in the \file{texmf/web2c} subdirectory). \emph{All}
2092 \file{texmf.cnf} files in the search path will be read and definitions
2093 in earlier files override those in later files. Thus, with a search
2094 path of \verb|.:$TEXMF|, values from \file{./texmf.cnf} override those
2095 from \verb|$TEXMF/texmf.cnf|.
2096 \endgroup
2097
2098 \begin{itemize}
2099 \item
2100 Comments start with \code{\%} and continue to the end of the line.
2101 \item
2102 Blank lines are ignored.
2103 \item
2104 A \bs{} at the end of a line acts as a continuation character,
2105 i.e., the next line is appended. Whitespace at the beginning of
2106 continuation lines is not ignored.
2107 \item
2108 Each remaining line has the form:
2109 \begin{alltt}
2110 \var{variable}[.\var{progname}] [=] \var{value}
2111 \end{alltt}%
2112 where the \samp{=} and surrounding whitespace are optional.
2113 \item
2114 The \ttvar{variable} name may contain any character other
2115 than whitespace, \samp{=}, or \samp{.}, but sticking to
2116 \samp{A-Za-z\_} is safest.
2117 \item
2118 If \samp{.\var{progname}} is present, the definition only
2119 applies if the program that is running is named
2120 \texttt{\var{progname}} or \texttt{\var{progname}.exe}. This allows
2121 different flavors of \TeX{} to have different search paths, for
2122 example.
2123 \item \var{value} may contain any characters except
2124 \code{\%} and \samp{@}. The
2125 \code{\$\var{var}.\var{prog}} feature is not available on the
2126 right-hand side; instead, you must use an additional variable. A
2127 \samp{;}\ in \var{value} is translated to \samp{:}\ if
2128 running under Unix; this is useful to be able to have a single
2129 \file{texmf.cnf} for Unix, \acro{MS-DOS} and Windows systems.
2130 \item
2131 All definitions are read before anything is expanded, so
2132 variables can be referenced before they are defined.
2133 \end{itemize}
2134 A configuration file fragment illustrating most of these points is
2135 \ifSingleColumn
2136 shown below:
2137
2138 \verbatiminput{examples/ex5.tex}
2139 \else
2140 shown in Figure~\ref{fig:config-sample}.
2141 \fi
2142
2143 \subsubsection{Path expansion}
2144 \label{Path-expansion}
2145
2146
2147 \KPS{} recognizes certain special characters and constructions in
2148 search paths, similar to those available in Unix shells. As a
2149 general example, the complex path,
2150 \verb+~$USER/{foo,bar}//baz+, expands to all subdirectories under
2151 directories \file{foo} and \file{bar} in \texttt{\$USER}'s home
2152 directory that contain a directory or file \file{baz}. These
2153 expansions are explained in the sections below.
2154 %$
2155 \subsubsection{Default expansion}
2156 \label{Default-expansion}
2157
2158 \tolerance=2500
2159 If the highest-priority search path (see ``Path sources'' on
2160 page~\pageref{Path-sources}) contains an \emph{extra colon} (i.e.,
2161 leading, trailing, or doubled), \KPS{} inserts at that point the
2162 next-highest-prio\-rity search path that is defined. If that inserted
2163 path has an extra colon, the same happens with the next highest. For
2164 example, given an environment variable setting
2165
2166 \tolerance=1500
2167
2168 \begin{alltt}
2169 > \Ucom{setenv TEXINPUTS /home/karl:}
2170 \end{alltt}
2171 and a \code{TEXINPUTS} value from \file{texmf.cnf} of
2172
2173 \begin{alltt}
2174 .:\$TEXMF//tex
2175 \end{alltt}
2176 then the final value used for searching will be:
2177
2178 \begin{alltt}
2179 /home/karl:.:\$TEXMF//tex
2180 \end{alltt}
2181
2182 Since it would be useless to insert the default value in more than one
2183 place, \KPS{} changes only one extra \samp{:}\ and leaves any others in
2184 place. It checks first for a leading \samp{:}, then a trailing
2185 \samp{:}, then a doubled \samp{:}.
2186
2187 \subsubsection{Brace expansion}
2188
2189 A useful feature is brace expansion, which means that, for instance,
2190 \verb+v{a,b}w+ expands to \verb+vaw:vbw+. Nesting is allowed.
2191 This is used to implement multiple \TeX{} hierarchies, by
2192 assigning a brace list to \code{\$TEXMF}.
2193 For example, in \file{texmf.cnf}, the following definition
2194 (appproximately; there are actually even more trees) is made:
2195 \begin{verbatim}
2196 TEXMF = {$TEXMFHOME,$TEXMFLOCAL,!!$TEXMFVAR,!!$TEXMFMAIN}
2197 \end{verbatim}
2198 Using this you can then write something like
2199 \begin{verbatim}
2200 TEXINPUTS = .;$TEXMF/tex//
2201 \end{verbatim}
2202 %$
2203 which means that, after looking in the current directory, the
2204 \code{\$TEXMFHOME/tex}, \code{\$TEXMFLOCAL/tex}, \code{\$TEXMFVAR/tex}
2205 and \code{\$TEXMFMAIN/tex} trees \emph{only}) will be searched (the
2206 last two use using \file{ls-R} data base files). It is a convenient
2207 way for running two parallel \TeX{} structures, one ``frozen'' (on a
2208 \CD, for instance) and the other being continuously updated with new
2209 versions as they become available. By using the \code{\$TEXMF}
2210 variable in all definitions, one is sure to always search the
2211 up-to-date tree first.
2212
2213 \subsubsection{Subdirectory expansion}
2214 \label{Subdirectory-expansion}
2215
2216 Two or more consecutive slashes in a path element following a directory
2217 \var{d} is replaced by all subdirectories of \var{d}: first those
2218 subdirectories directly under \var{d}, then the subsubdirectories under
2219 those, and so on. At each level, the order in which the directories are
2220 searched is \emph{unspecified}.
2221
2222 If you specify any filename components after the \samp{//}, only
2223 subdirectories with matching components are included. For example,
2224 \samp{/a//b} expands into directories \file{/a/1/b}, \file{/a/2/b},
2225 \file{/a/1/1/b}, and so on, but not \file{/a/b/c} or \file{/a/1}.
2226
2227 Multiple \samp{//} constructs in a path are possible, but
2228 \samp{//} at the beginning of a path is ignored.
2229
2230 \subsubsection{List of special characters and their meaning: a summary}
2231
2232 The following list summarizes the special characters in \KPS{}
2233 configuration files.
2234
2235 % need a wider space for the item labels here.
2236 \newcommand{\CODE}[1]{\makebox[3em][l]{\code{#1}}}
2237 \begin{ttdescription}
2238 \item[\CODE{:}] Separator in path specification; at the beginning or
2239 the end of a path it substitutes the default path expansion.\par
2240 \item[\CODE{;}] Separator on non-Unix systems (acts like \code{:}).
2241 \item[\CODE{\$}] Variable expansion.
2242 \item[\CODE{\string~}] Represents the user's home directory.
2243 \item[\CODE{\char`\{...\char`\}}] Brace expansion.
2244 \item[\CODE{//}] Subdirectory expansion (can occur anywhere in
2245 a path, except at its beginning).
2246 \item[\CODE{\%}] Start of comment.
2247 \item[\CODE{\bs}] Continuation character (allows multi-line entries).
2248 \item[\CODE{!!}] Search \emph{only} database to locate file, \emph{do
2249 not} search the disk.
2250 \end{ttdescription}
2251
2252
2253 \subsection{Filename databases}
2254 \label{Filename-database}
2255
2256 \KPS{} goes to some lengths to minimize disk accesses for searches.
2257 Nevertheless, at installations with enough directories, searching each
2258 possible directory for a given file can take an excessively long time
2259 (this is especially true if many hundreds of font directories have to
2260 be traversed.) Therefore, \KPS{} can use an externally-built plain text
2261 ``database'' file named \file{ls-R} that maps files to directories,
2262 thus avoiding the need to exhaustively search the disk.
2263
2264 A second database file \file{aliases} allows you to give additional
2265 names to the files listed in \file{ls-R}. This can be helpful to
2266 confirm to \acro{DOS} 8.3 filename conventions in source files.
2267
2268 \subsubsection{The filename database}
2269 \label{ls-R}
2270
2271 As explained above, the name of the main filename database must be
2272 \file{ls-R}. You can put one at the root of each \TeX{} hierarchy in
2273 your installation that you wish to be searched (\code{\$TEXMF} by
2274 default); most sites have only one hierarchy. \KPS{} looks for
2275 \file{ls-R} files along the \code{TEXMFDBS} path.
2276
2277 The recommended way to create and maintain \samp{ls-R} is to run the
2278 \code{mktexlsr} script included with the distribution. It is invoked
2279 by the various \samp{mktex}\dots\ scripts. In principle, this script
2280 just runs the command
2281 \begin{alltt}
2282 cd \var{/your/texmf/root} && \path|\|ls -1LAR ./ >ls-R
2283 \end{alltt}
2284 presuming your system's \code{ls} produces the right output format
2285 (\acro{GNU} \code{ls} is all right). To ensure that the database is
2286 always up-to-date, it is easiest to rebuild it regularly via
2287 \code{cron}, so that it is automatically updated when the installed
2288 files change, such as after installing or updating a \LaTeX{} package.
2289
2290 If a file is not found in the database, by default \KPS{} goes ahead
2291 and searches the disk. If a particular path element begins with
2292 \samp{!!}, however, \emph{only} the database will be searched for that
2293 element, never the disk.
2294
2295
2296 \subsubsection{kpsewhich: Standalone path searching}
2297 \label{Invoking-kpsewhich}
2298
2299 The \texttt{kpsewhich} program exercises path searching independent of any
2300 particular application. This can be useful as a sort of \code{find}
2301 program to locate files in \TeX{} hierarchies (this is used heavily in
2302 the distributed \samp{mktex}\dots\ scripts).
2303
2304 \begin{alltt}
2305 > \Ucom{kpsewhich \var{option}\dots{} \var{filename}\dots{}}
2306 \end{alltt}
2307 The options specified in \ttvar{option} start with either \samp{-}
2308 or \samp{-{}-}, and any unambiguous abbreviation is accepted.
2309
2310 \KPS{} looks up each non-option argument on the command line as a
2311 filename, and returns the first file found. There is no option to
2312 return all the files with a particular name (you can run the Unix
2313 \samp{find} utility for that).
2314
2315 The more important options are described next.
2316
2317 \begin{ttdescription}
2318 \item[\texttt{-{}-dpi=\var{num}}]\mbox{}
2319 Set the resolution to \ttvar{num}; this only affects \samp{gf}
2320 and \samp{pk} lookups. \samp{-D} is a synonym, for compatibility
2321 with \cmdname{dvips}. Default is 600.
2322
2323 \item[\texttt{-{}-format=\var{name}}]\mbox{}\\
2324 Set the format for lookup to \ttvar{name}. By default, the
2325 format is guessed from the filename. For formats which do not have
2326 an associated unambiguous suffix, such as \MP{} support files and
2327 \cmdname{dvips} configuration files, you have to specify the name as
2328 known to \KPS{}, such as \texttt{tex} or \texttt{enc files}. Run
2329 \texttt{kpsewhich -{}-help} for a list.
2330
2331 \item[\texttt{-{}-mode=\var{string}}]\mbox{}\\
2332 Set the mode name to \ttvar{string}; this only affects \samp{gf}
2333 and \samp{pk} lookups. No default: any mode will be found.
2334 \item[\texttt{-{}-must-exist}]\mbox{}\\
2335 Do everything possible to find the files, notably including
2336 searching the disk. By default, only the \file{ls-R} database is
2337 checked, in the interest of efficiency.
2338 \item[\texttt{-{}-path=\var{string}}]\mbox{}\\
2339 Search along the path \ttvar{string} (colon-separated as usual),
2340 instead of guessing the search path from the filename. \samp{//} and
2341 all the usual expansions are supported. The options \samp{-{}-path}
2342 and \samp{-{}-format} are mutually exclusive.
2343 \item[\texttt{-{}-progname=\var{name}}]\mbox{}\\
2344 Set the program name to \texttt{\var{name}}.
2345 This can affect the search paths via the \texttt{.\var{progname}}
2346 feature.
2347 The default is \cmdname{kpsewhich}.
2348 \item[\texttt{-{}-show-path=\var{name}}]\mbox{}\\
2349 shows the path used for file lookups of file type \texttt{\var{name}}.
2350 Either a filename extension (\code{.pk}, \code{.vf}, etc.) or a
2351 name can be used, just as with \samp{-{}-format} option.
2352 \item[\texttt{-{}-debug=\var{num}}]\mbox{}\\
2353 sets the debugging options to \texttt{\var{num}}.
2354 \end{ttdescription}
2355
2356
2357 \subsubsection{Examples of use}
2358 \label{SExamplesofuse}
2359
2360 Let us now have a look at \KPS{} in action. Here's a straightforward search:
2361
2362 \begin{alltt}
2363 > \Ucom{kpsewhich article.cls}
2364 /usr/local/texmf-dist/tex/latex/base/article.cls
2365 \end{alltt}
2366 We are looking for the file \file{article.cls}. Since the \samp{.cls}
2367 suffix is unambiguous we do not need to specify that we want to look for a
2368 file of type \optname{tex} (\TeX{} source file directories). We find it in
2369 the subdirectory \file{tex/latex/base} below the \samp{texmf-dist} \TL\
2370 directory. Similarly, all of the following are found without problems
2371 thanks to their unambiguous suffix.
2372 \begin{alltt}
2373 > \Ucom{kpsewhich array.sty}
2374 /usr/local/texmf-dist/tex/latex/tools/array.sty
2375 > \Ucom{kpsewhich latin1.def}
2376 /usr/local/texmf-dist/tex/latex/base/latin1.def
2377 > \Ucom{kpsewhich size10.clo}
2378 /usr/local/texmf-dist/tex/latex/base/size10.clo
2379 > \Ucom{kpsewhich small2e.tex}
2380 /usr/local/texmf-dist/tex/latex/base/small2e.tex
2381 > \Ucom{kpsewhich tugboat.bib}
2382 /usr/local/texmf-dist/bibtex/bib/beebe/tugboat.bib
2383 \end{alltt}
2384
2385 That last is a \BibTeX{} bibliography database for \textsl{TUGBoat} articles.
2386
2387 \begin{alltt}
2388 > \Ucom{kpsewhich cmr10.pk}
2389 \end{alltt}
2390 Font bitmap glyph files of type \file{.pk} are used by display
2391 programs like \cmdname{dvips} and \cmdname{xdvi}. Nothing is returned in
2392 this case since there are no pre-generated Computer Modern \samp{.pk}
2393 files in \TL{}\Dash the Type~1 variants are used by default.
2394 \begin{alltt}
2395 > \Ucom{kpsewhich wsuipa10.pk}
2396 \ifSingleColumn /usr/local/texmf-var/fonts/pk/ljfour/public/wsuipa/wsuipa10.600pk
2397 \else /usr/local/texmf-var/fonts/pk/ljfour/public/
2398 ... wsuipa/wsuipa10.600pk
2399 \fi\end{alltt}
2400
2401 For these fonts (a phonetic alphabet from the University of Washington)
2402 we had to generate \samp{.pk} files, and since the default \MF{} mode on
2403 our installation is \texttt{ljfour} with a base resolution of 600\dpi{}
2404 (dots per inch), this instantiation is returned.
2405 \begin{alltt}
2406 > \Ucom{kpsewhich -dpi=300 wsuipa10.pk}
2407 \end{alltt}
2408 In this case, when specifying that we are interested in a resolution
2409 of 300\dpi{} (\texttt{-dpi=300}) we see that no such font is available on
2410 the system. A program like \cmdname{dvips} or \cmdname{xdvi} would
2411 go off and actually build the required \texttt{.pk} files
2412 using the script \cmdname{mktexpk}.
2413
2414 Next we turn our attention to \cmdname{dvips}'s header and configuration
2415 files. We first look at one of the commonly used files, the general
2416 prolog \file{tex.pro} for \TeX{} support, before turning our attention
2417 to the generic configuration file (\file{config.ps}) and the \PS{} font
2418 map \file{psfonts.map}\Dash as of 2004, map and encoding files have
2419 their own search paths and new location in \dirname{texmf} trees. As
2420 the \samp{.ps} suffix is ambiguous we have to specify explicitly which
2421 type we are considering (\optname{dvips config}) for the file
2422 \texttt{config.ps}.
2423 \begin{alltt}
2424 > \Ucom{kpsewhich tex.pro}
2425 /usr/local/texmf/dvips/base/tex.pro
2426 > \Ucom{kpsewhich --format="dvips config" config.ps}
2427 /usr/local/texmf/dvips/config/config.ps
2428 > \Ucom{kpsewhich psfonts.map}
2429 /usr/local/texmf/fonts/map/dvips/updmap/psfonts.map
2430 \end{alltt}
2431
2432 We now take a closer look at the \acro{URW} Times \PS{} support
2433 files. The prefix for these in the standard font naming scheme is
2434 \samp{utm}. The first file we look at is the configuration file,
2435 which contains the name of the map file:
2436 \begin{alltt}
2437 > \Ucom{kpsewhich --format="dvips config" config.utm}
2438 /usr/local/texmf-dist/dvips/psnfss/config.utm
2439 \end{alltt}
2440 The contents of that file is
2441 \begin{alltt}
2442 p +utm.map
2443 \end{alltt}
2444 which points to the file \file{utm.map}, which we want to
2445 locate next.
2446 \begin{alltt}
2447 > \Ucom{kpsewhich utm.map}
2448 /usr/local/texmf-dist/fonts/map/dvips/times/utm.map
2449 \end{alltt}
2450 This map file defines the file names of the Type~1 \PS{} fonts in
2451 the URW collection. Its contents look like (we only show part of the
2452 lines):
2453 \begin{alltt}
2454 utmb8r NimbusRomNo9L-Medi ... <utmb8a.pfb
2455 utmbi8r NimbusRomNo9L-MediItal... <utmbi8a.pfb
2456 utmr8r NimbusRomNo9L-Regu ... <utmr8a.pfb
2457 utmri8r NimbusRomNo9L-ReguItal... <utmri8a.pfb
2458 utmbo8r NimbusRomNo9L-Medi ... <utmb8a.pfb
2459 utmro8r NimbusRomNo9L-Regu ... <utmr8a.pfb
2460 \end{alltt}
2461 Let us, for instance, take the Times Roman instance
2462 \file{utmr8a.pfb} and find its position in the \file{texmf} directory
2463 tree with a search for Type~1 font files:
2464 \begin{alltt}
2465 > \Ucom{kpsewhich utmr8a.pfb}
2466 \ifSingleColumn /usr/local/texmf-dist/fonts/type1/urw/times/utmr8a.pfb
2467 \else /usr/local/texmf-dist/fonts/type1/
2468 ... urw/utm/utmr8a.pfb
2469 \fi\end{alltt}
2470
2471 It should be evident from these examples how you can easily locate the
2472 whereabouts of a given file. This is especially important if you suspect
2473 that the wrong version of a file is picked up somehow, since
2474 \cmdname{kpsewhich} will show you the first file encountered.
2475
2476 \subsubsection{Debugging actions}
2477 \label{Debugging}
2478
2479 Sometimes it is necessary to investigate how a program resolves file
2480 references. To make this practical, \KPS{} offers various levels of
2481 debugging output:
2482
2483 \begin{ttdescription}
2484 \item[\texttt{\ 1}] \texttt{stat} calls (disk lookups). When running
2485 with an up-to-date \file{ls-R} database this should almost give no
2486 output.
2487 \item[\texttt{\ 2}] References to hash tables (such as \file{ls-R}
2488 databases, map files, configuration files).
2489 \item[\texttt{\ 4}] File open and close operations.
2490 \item[\texttt{\ 8}] General path information for file types
2491 searched by \KPS. This is useful to find out where a particular
2492 path for the file was defined.
2493 \item[\texttt{16}] Directory list for each path element (only relevant
2494 for searches on disk).
2495 \item[\texttt{32}] File searches.
2496 \end{ttdescription}
2497 A value of \texttt{-1} will set all the above options; in practice,
2498 this is usually the most convenient.
2499
2500 Similarly, with the \cmdname{dvips} program, by setting a combination of
2501 debug switches, one can follow in detail where files are being picked up
2502 from. Alternatively, when a file is not found, the debug trace shows in
2503 which directories the program looks for the given file, so that one can
2504 get an indication what the problem~is.
2505
2506 Generally speaking, as most programs call the \KPS{} library
2507 internally, one can select a debug option by using the
2508 \envname{KPATHSEA\_DEBUG} environment variable, and setting it to (a
2509 combination of) values as described in the above list.
2510
2511 (Note for Windows users: it is not easy to redirect
2512 all messages to a file in this system. For diagnostic purposes
2513 you can temporarily \texttt{SET KPATHSEA\_DEBUG\_OUTPUT=err.log}).
2514
2515 Let us consider, as an example, a small \LaTeX{} source file,
2516 \file{hello-world.tex}, which contains the following input.
2517 \begin{verbatim}
2518 \documentclass{article}
2519 \begin{document}
2520 Hello World!
2521 \end{document}
2522 \end{verbatim}
2523 This little file only uses the font \file{cmr10}, so let us look at
2524 how \cmdname{dvips} prepares the \PS{} file (we want to use the Type~1
2525 version of the Computer Modern fonts, hence the option \texttt{-Pcms}).
2526 \begin{alltt}
2527 > \Ucom{dvips -d4100 hello-world -Pcms -o}
2528 \end{alltt}
2529 In this case we have combined \cmdname{dvips}'s debug class 4 (font
2530 paths) with \KPS's path element expansion (see \cmdname{dvips} Reference
2531 Manual, \OnCD{texmf/doc/html/dvips/dvips_toc.html}).
2532 The output (slightly rearranged) appears in
2533 Figure~\ref{fig:dvipsdbga}.
2534 \begin{figure*}[tp]
2535 \centering
2536 \input{examples/ex6a.tex}
2537 \caption{Finding configuration files}\label{fig:dvipsdbga}
2538
2539 \bigskip
2540
2541 \input{examples/ex6b.tex}
2542 \caption{Finding the prolog file}\label{fig:dvipsdbgb}
2543
2544 \bigskip
2545
2546 \input{examples/ex6c.tex}
2547 \caption{Finding the font file}\label{fig:dvipsdbgc}
2548 \end{figure*}
2549
2550 \cmdname{dvips} starts by locating its working files. First,
2551 \file{texmf.cnf} is found, which gives the definitions of the search
2552 paths for the other files, then the file database \file{ls-R} (to
2553 optimize file searching) and the file \file{aliases}, which makes it
2554 possible to declare several names (e.g., a short \acro{DOS}-like 8.3 and
2555 a more natural longer version) for the same file. Then \cmdname{dvips}
2556 goes on to find the generic configuration file \file{config.ps}
2557 before looking for the customization file \file{.dvipsrc} (which, in
2558 this case is \emph{not found}). Finally, \cmdname{dvips} locates the
2559 config file for the Computer Modern \PS{} fonts \file{config.cms}
2560 (this was initiated with the \texttt{-Pcms} option on the \cmdname{dvips}
2561 command). This file contains the list of the map files which
2562 define the relation between the \TeX{}, \PS{} and file system
2563 names of the fonts.
2564 \begin{alltt}
2565 > \Ucom{more /usr/local/texmf/dvips/cms/config.cms}
2566 p +ams.map
2567 p +cms.map
2568 p +cmbkm.map
2569 p +amsbkm.map
2570 \end{alltt}
2571 \cmdname{dvips} thus goes on to find all these files, plus the generic
2572 map file \file{psfonts.map}, which is always loaded (it contains
2573 declarations for commonly used \PS{} fonts; see the last part of
2574 Section \ref{SExamplesofuse} for more details about \PS{} map
2575 file handling).
2576
2577 At this point \cmdname{dvips} identifies itself to the user:
2578 \begin{alltt}
2579 This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com)
2580 \end{alltt}
2581 \ifSingleColumn
2582 Then it goes on to look for the prolog file \file{texc.pro}:
2583 \begin{alltt}\small
2584 kdebug:start search(file=texc.pro, must\_exist=0, find\_all=0,
2585 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
2586 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
2587 kdebug:search(texc.pro) => /usr/local/texmf/dvips/base/texc.pro
2588 \end{alltt}
2589 \else
2590 Then it goes on to look for the prolog file \file{texc.pro} (see
2591 Figure~\ref{fig:dvipsdbgb}).
2592 \fi
2593
2594 After having found the file in question, \cmdname{dvips} outputs
2595 date and time, and informs us that it will generate the
2596 file \file{hello-world.ps}, then that it needs the font file
2597 \file{cmr10}, and that the latter is declared as ``resident'' (no
2598 bitmaps needed):
2599 \begin{alltt}\small
2600 TeX output 1998.02.26:1204' -> hello-world.ps
2601 Defining font () cmr10 at 10.0pt
2602 Font cmr10 <CMR10> is resident.
2603 \end{alltt}
2604 Now the search is on for the file \file{cmr10.tfm}, which is found,
2605 then a few more prolog files (not shown) are referenced, and finally
2606 the Type~1 instance \file{cmr10.pfb} of the font is located and
2607 included in the output file (see last line).
2608 \begin{alltt}\small
2609 kdebug:start search(file=cmr10.tfm, must\_exist=1, find\_all=0,
2610 path=.:~/tex/fonts/tfm//:!!/usr/local/texmf/fonts/tfm//:
2611 /var/tex/fonts/tfm//).
2612 kdebug:search(cmr10.tfm) => /usr/local/texmf/fonts/tfm/public/cm/cmr10.tfm
2613 kdebug:start search(file=texps.pro, must\_exist=0, find\_all=0,
2614 ...
2615 <texps.pro>
2616 kdebug:start search(file=cmr10.pfb, must\_exist=0, find\_all=0,
2617 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
2618 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
2619 kdebug:search(cmr10.pfb) => /usr/local/texmf/fonts/type1/public/cm/cmr10.pfb
2620 <cmr10.pfb>[1]
2621 \end{alltt}
2622
2623 \subsection{Runtime options}
2624
2625 Another useful feature of \Webc{} is its possibility to control a number
2626 of memory parameters (in particular, array sizes) via the runtime file
2627 \file{texmf.cnf} read by \KPS{}. The memory settings can be found in
2628 Part 3 of that file in the \TL{} distribution. The more important
2629 are:
2630
2631 \begin{ttdescription}
2632 \item[\texttt{main\_memory}]
2633 Total words of memory available, for
2634 \TeX{}, \MF{} and \MP. You must make a new format file for each
2635 different setting. For instance, you could generate a ``huge''
2636 version of \TeX{}, and call the format file \texttt{hugetex.fmt}.
2637 Using the standard way of specifying the program name used by \KPS{},
2638 the particular value of the \texttt{main\_memory} variable will then
2639 be read from \file{texmf.cnf}.
2640 etc.).
2641 \item[\texttt{extra\_mem\_bot}]
2642 Extra space for ``large'' \TeX{} data structures:
2643 boxes, glue, breakpoints, etc. Especially useful if you use
2644 \PiCTeX{}.
2645 \item[\texttt{font\_mem\_size}]
2646 Number of words for font information available for \TeX. This
2647 is more or less the total size of all TFM files read.
2648 \item[\texttt{hash\_extra}]
2649 Additional space for the hash table of control sequence names.
2650 Approximately 10,000 control sequences can be stored in the main
2651 hash table; if you have a large book with numerous cross-references,
2652 this might not be enough. The default value of
2653 \texttt{hash\_extra} is \texttt{50000}.
2654 \end{ttdescription}
2655
2656 \noindent Of course, this facility is no substitute for truly dynamic
2657 arrays and memory allocation, but since these are extremely difficult to
2658 implement in the present \TeX{} source, these runtime parameters provide
2659 a practical compromise allowing some flexibility.
2660
2661
2662 \begin{comment}
2663 \section{Building on a new Unix platform}
2664
2665 If you have a platform for which executables are not included, you will
2666 need to compile \TeX{} and friends. This is not as hard as it
2667 sounds. What you need is all in the directory \texttt{source} in the
2668 distribution.
2669
2670 \subsection{Prerequisites}
2671
2672 You will need at least 100 megabytes of disk space to compile all of
2673 \TeX{} and its support programs. You'll also need an \acro{ANSI} C
2674 compiler, a \cmdname{make} utility, a lexical scanner, and a parser
2675 generator. We recommend the \acro{GNU} version of these programs
2676 (\cmdname{gcc}, \acro{GNU} \cmdname{make}, \cmdname{m4}, \cmdname{flex},
2677 \cmdname{bison}). You may be able to work with other C compilers and
2678 \cmdname{make} programs, but you will need a good understanding of
2679 building Unix programs to sort out problems.
2680
2681 Also, the command \texttt{uname} must return a sensible value.
2682
2683
2684 \subsection{Configuration}
2685
2686 To begin, perform a normal installation of \TL{} to your disk (see
2687 section~\ref{sec:unix-install-disk} on
2688 \p.\pageref{sec:unix-install-disk}). You may wish to skip installing
2689 all of the prebuilt binaries.
2690
2691 Then, unpack the source from the compressed \texttt{tar} file in the
2692 directory \dirname{source} to your disk and change directory to where
2693 you placed it.
2694
2695 Next, run \cmdname{configure} with a command line like this:
2696 \begin{alltt}
2697 > \Ucom{sh configure -prefix=/usr/local/TeX}
2698 \end{alltt}
2699
2700 The \optname{-prefix} directory is the one where you installed the
2701 support tree; the directory layout will be as follows (where \$TEXDIR
2702 stands for the directory you chose):
2703
2704 \noindent
2705 \begin{tabular}{>{\ttfamily}ll@{}}
2706 \dirname{$TEXDIR/share/texmf} & main tree with fonts,\\
2707 & \qquad macros, etc\\
2708 \dirname{$TEXDIR/man} & Unix manual pages\\
2709 \dirname{$TEXDIR/info} & \acro{GNU} style Info manuals\\
2710 \dirname{$TEXDIR/bin/$PLATFORM} & binaries\\
2711 \end{tabular}
2712 %$
2713
2714 If you want to leave out the \dirname{$PLATFORM} directory level,
2715 i.e., put the binaries directly into \dirname{$TEXDIR/bin}, specify
2716 the \verb|--disable-multiplatform| option to \cmdname{configure}.
2717
2718 Have a look at the output of \verb|./configure --help| for more
2719 options you can use. For example, you can skip building of \OMEGA{} and
2720 \eTeX{}.
2721
2722
2723 \subsection{Running \cmdname{make}}
2724
2725 Make sure the shell variable or option \texttt{noclobber} is not set.
2726 Then, run the main \cmdname{make} like this:
2727 \begin{alltt}
2728 > \Ucom{make world}
2729 \end{alltt}
2730 and relax\ldots
2731
2732 Alternatively, you want to log all the output, as in:
2733 \begin{alltt}
2734 > \Ucom{sh -c "make world >world.log 2>\&1" \&}
2735 \end{alltt}
2736
2737 Before you believe that everything went ok, please check the log file
2738 for errors: \acro{GNU} \cmdname{make} always uses the string \samp{***}
2739 whenever a command fails. Also, check if all the programs were built:
2740
2741 \begin{alltt}
2742 > \Ucom{cd \var{TEXDIR}/bin/\var{archname}}
2743 > \Ucom{ls | wc}
2744 \end{alltt}
2745 The result should be over 200 (you can check the exact number with the
2746 \dirname{bin} directory contents in the distribution).
2747
2748 If you need special privileges for \texttt{make install}, you can
2749 separate the \samp{make world} into two different runs, like this:
2750 \begin{alltt}
2751 > \Ucom{make all}
2752 > \Ucom{su}
2753 > \Ucom{make install strip}
2754 \end{alltt}
2755
2756 After you've installed your new binaries, you should follow the normal
2757 post-installation procedures, given in section~\ref{sec:postinstall}
2758 (\p.\pageref{sec:postinstall}).
2759
2760 Also, if you'd like to make your binaries available to others, please
2761 contact us. We'll be happy to put them on the \TL\ web pages.
2762 \end{comment}
2763
2764 \section{Acknowledgements}
2765
2766 \TL{} is a joint effort by virtually all of the \TeX{} user groups.
2767 This edition of \TL{} was overseen by Sebastian Rahtz and Karl Berry.
2768 The other principal contributors are listed below.
2769
2770 \begin{itemize*}
2771
2772 \item The German-speaking \TeX{} Users (\acro{DANTE} e.V.), who provide
2773 the hardware for the \TL{} source repository; and Rainer Sch\"opf and
2774 Reinhard Zierke who look after it. \acro{DANTE} officers Volker Schaa
2775 and Klaus H\"oppner coordinate production with the Lehmann's Bookstore
2776 (\url{http://www.lob.de}).
2777
2778 \item The Perforce corporation (\url{http://www.perforce.com}), for providing
2779 a free copy of their excellent change management system, which we use
2780 to manage the \TL{} sources.
2781
2782 \item Peter Breitenlohner and the \eTeX\ team for the stable foundation
2783 of future \TeX's.
2784
2785 \item Thomas Esser, without whose marvelous \teTeX{} package \TL{}
2786 would certainly not exist, and whose continual help makes it a better
2787 product.
2788
2789 \item Michel Goossens, who co-authored the original documentation.
2790
2791 \item Eitan Gurari, whose \TeX4ht was used to create the \HTML{}
2792 version of this documentation, and who worked tirelessly to improve
2793 it at short notice.
2794
2795 \item Hans Hagen, for major testing and making the \ConTeXt\ format
2796 conform to \TL's needs.
2797
2798 \item Pawe{\l} Jackowski, for the Windows installer \cmdname{tlpm},
2799 and Tomasz {\L}uczak, for \cmdname{tlpmgui}.
2800
2801 \item \Thanh, Martin Schr\"oder, and the pdf\TeX\ team for continuing
2802 enhancements of \TeX's abilities.
2803
2804 \item Petr Olsak, who coordinated and checked all the Czech and Slovak
2805 material very carefully.
2806
2807 \item Fabrice Popineau, for the Windows binaries in \TL{}.
2808
2809 \item Staszek Wawrykiewicz, the principal tester for all of \TL{},
2810 and coordinator of the many major Polish contributions: fonts, Windows
2811 installation, and more.
2812
2813 \item Olaf Weber, for his patient assembly and maintenance of Web2C,
2814 upon which all else depends.
2815
2816 \item Gerben Wierda, for creating and maintaining the \MacOSX\ support,
2817 and much integration and testing.
2818
2819 \item Graham Williams, on whose work the catalogue of packages depends.
2820
2821 \end{itemize*}
2822
2823 Builders of the binaries:
2824 Tigran Aivazian (\pkgname{x86\_64-linux}),
2825 Manfred Lotz (\pkgname{i386-freebsd}),
2826 Fabrice Popineau (\pkgname{win32}),
2827 Norbert Preining (\pkgname{alpha-linux}),
2828 Vladimir Volovich (\pkgname{powerpc-aix}, \pkgname{sparc-linux},
2829 \pkgname{sparc-solaris}),
2830 Staszek Wawrykiewicz (\pkgname{i386-linux}),
2831 Olaf Weber (\pkgname{mips-irix}),
2832 Gerben Wierda (\pkgname{i386-darwin}, \pkgname{powerpc-darwin}).
2833
2834 Documentation and translation updates:
2835 Karl Berry (English),
2836 Daniel Flipo \& Fabrice Popineau (French),
2837 G\"unter Partosch \& Hartmut Henkel (German),
2838 Petr Sojka \& Jan Busa (Czech\slash Slovak),
2839 Boris Veytsman (Russian),
2840 Staszek Wawrykiewicz (Polish).
2841
2842 Of course the most important acknowledgement must go to Donald Knuth, first
2843 for inventing \TeX, and then for giving it to the world.
2844
2845
2846 \section{Release history}
2847 \label{sec:history}
2848
2849 \subsection{Past}
2850
2851 Discussion began in late 1993 when the Dutch \TeX{} Users Group was
2852 starting work on its 4All\TeX{} \CD{} for \acro{MS-DOS} users, and it
2853 was hoped at that time to issue a single, rational, \CD{} for all
2854 systems. This was too ambitious a target for the time, but it did spawn
2855 not only the very successful 4All\TeX{} \CD{}, but also the \acro{TUG}
2856 Technical Council working group on a \emph{\TeX{} Directory Structure}
2857 (\url{http://tug.org/tds}), which specified how to create consistent and
2858 manageable collections of \TeX{} support files. A complete draft of the
2859 \TDS{} was published in the December 1995 issue of \textsl{TUGboat}, and
2860 it was clear from an early stage that one desirable product would be a
2861 model structure on \CD{}. The distribution you now have is a very direct
2862 result of the working group's deliberations. It was also clear that the
2863 success of the 4All\TeX{} \CD{} showed that Unix users would benefit
2864 from a similarly easy system, and this is the other main strand of
2865 \TL.
2866
2867 We first undertook to make a new Unix-based \TDS{} \CD{} in the autumn
2868 of 1995, and quickly identified Thomas Esser's \teTeX{} as the ideal
2869 setup, as it already had multi-platform support and was built with
2870 portability across file systems in mind. Thomas agreed to help, and work
2871 began seriously at the start of 1996. The first edition was released in
2872 May 1996. At the start of 1997, Karl Berry completed a major new release
2873 of Web2c, which included nearly all the features which Thomas Esser had
2874 added in \teTeX, and we decided to base the 2nd edition of the \CD{} on
2875 the standard \Webc, with the addition of \teTeX's \texttt{texconfig}
2876 script. The 3rd edition of the \CD{} was based on a major revision of
2877 \Webc, 7.2, by Olaf Weber; at the same time, a new revision of \teTeX
2878 was being made, and \TL{} included almost all of its features. The
2879 4th edition followed the same pattern, using a new version of \teTeX,
2880 and a new release of \Webc{} (7.3). The system now included a complete
2881 Windows setup.
2882
2883 For the 5th edition (March 2000) many parts of the \CD{} were revised
2884 and checked, updating hundreds of packages. Package details were stored
2885 in XML files. But the major change for \TeX\ Live 5 was that all
2886 non-free software was removed. Everything in \TL{} is now intended
2887 to be compatible with the Debian Free Software Guidelines
2888 (\url{http://www.debian.org/intro/free}); we have done our best to check
2889 the license conditions of all packages, but we would very much
2890 appreciate hearing of any mistakes.
2891
2892 The 6th edition (July 2001) had much more material updated. The major
2893 change was a new install concept: the user could select a more exact set
2894 of needed collections. Language-related collections were completely
2895 reorganized, so selecting any of them installs not only macros, fonts,
2896 etc., but also prepares an appropriate \texttt{language.dat}.
2897
2898 The 7th edition of 2002 had the notable addition of \MacOSX{} support,
2899 and the usual myriad of updates to all sorts of packages and
2900 programs. An important goal was integration of the source back with
2901 \teTeX, to correct the drift apart in versions~5 and~6.
2902
2903 \subsubsection{2003}
2904
2905 In 2003, with the continuing flood of updates and additions, we found
2906 that \TL{} had grown so large it could no longer be contained on a
2907 single \CD, so we split it into three different distributions (see
2908 section~\ref{sec:multiple-dist}, \p.\pageref{sec:multiple-dist}). In
2909 addition:
2910
2911 \begin{itemize*}
2912 \item At the request of the \LaTeX{} team, we changed the standard
2913 \cmdname{latex} and \cmdname{pdflatex} commands to now use \eTeX{} (see
2914 \p.\pageref{text:etex}).
2915 \item The new Latin Modern fonts were included (and are recommended).
2916 \item Support for Alpha \acro{OSF} was removed
2917 (\acro{HPUX} support was removed previously), since no one had (or
2918 volunteered) hardware available on which to compile new binaries.
2919 \item Windows setup was substantially changed; for the first time
2920 an integrated environment based on XEmacs was introduced.
2921 \item Important supplementary programs for Windows
2922 (Perl, Ghost\-script, Image\-Magick, Ispell) are now installed
2923 in the \TL{} installation directory.
2924 \item Font map files used by \cmdname{dvips}, \cmdname{dvipdfm}
2925 and \cmdname{pdftex} are now generated by the new program
2926 \cmdname{updmap} and installed into \dirname{texmf/fonts/map}.
2927 \item \TeX{}, \MF{}, and \MP{} now, by default, output most input
2928 characters (32 and above) as themselves in output (e.g.,
2929 \verb|\write|) files,
2930 log files, and the terminal, i.e., \emph{not} translated using the
2931 \verb|^^| notation. In \TL{}~7, this translation was
2932 dependent on the system locale settings; now, locale settings do
2933 not influence the \TeX{} programs' behavior. If for some reason
2934 you need the \verb|^^| output, rename the file
2935 \verb|texmf/web2c/cp8bit.tcx|. (Future releases will have cleaner
2936 ways to control this.)
2937 \item This documentation was substantially revised.
2938 \item Finally, since the edition numbers had grown unwieldy,
2939 the version is now simply identified by the year: \TL{} 2003.
2940 \end{itemize*}
2941
2942
2943 \subsubsection{2004}
2944
2945 2004 saw many changes:
2946
2947 \begin{itemize}
2948
2949 \item If you have locally-installed fonts which use their own
2950 \filename{.map} or (much less likely) \filename{.enc} support files, you
2951 may need to move those support files.
2952
2953 \filename{.map} files are now searched for in subdirectories of
2954 \dirname{fonts/map} only (in each \filename{texmf} tree), along the
2955 \envname{TEXFONTMAPS} path. Similarly, \filename{.enc} files are now
2956 searched for in subdirectories of \dirname{fonts/enc} only, along the
2957 \envname{ENCFONTS} path. \cmdname{updmap} will attempt to warn about
2958 problematic files.
2959
2960 For methods of handling this and other information, please see
2961 \url{http://tug.org/texlive/mapenc.html}.
2962
2963 \item The \TK\ has been expanded with the addition of a \MIKTEX-based
2964 installable \CD, for those who prefer that implementation to Web2C.
2965 See section~\ref{sec:struct-tl} (\p.\pageref{sec:struct-tl}).
2966
2967 \item Within \TL, the single large \dirname{texmf} tree of previous
2968 releases has been replaced by three: \dirname{texmf},
2969 \dirname{texmf-dist}, and \dirname{texmf-doc}. See
2970 section~\ref{sec:tld} (\p.\pageref{sec:tld}), and the \filename{README}
2971 files for each.
2972
2973 \item All \TeX-related input files are now collected in
2974 the \dirname{tex} subdirectory of \dirname{texmf*} trees, rather than
2975 having separate sibling directories \dirname{tex}, \dirname{etex},
2976 \dirname{pdftex}, \dirname{pdfetex}, etc. See
2977 \CDref{texmf-doc/doc/english/tds/tds.html\#Extensions}
2978 {\texttt{texmf-doc/doc/english/tds/tds.html\#Extensions}}.
2979
2980 \item Helper scripts (not meant to be invoked by users) are now located
2981 in a new \dirname{scripts} directory of \dirname{texmf*} trees, and
2982 searched for via \verb|kpsewhich -format=texmfscripts|. So if you have
2983 programs which call such scripts, they'll need to be adjusted. See
2984 \CDref{texmf-doc/doc/english/tds/tds.html\#Scripts}
2985 {\texttt{texmf-doc/doc/english/tds/tds.html\#Scripts}}.
2986
2987 \item Almost all formats leave most characters printable as
2988 themselves via the ``translation file'' \filename{cp227.tcx}, instead of
2989 translating them with the \verb|^^| notation. Specifically, characters
2990 at positions 32--256, plus tab, vertical tab, and form feed are
2991 considered printable and not translated. The exceptions are plain \TeX\
2992 (only 32--126 printable), \ConTeXt\ (0--255 printable), and the
2993 \OMEGA-related formats. This default behavior is almost the same as in
2994 \TL\,2003, but it's implemented more cleanly, with more possibilities
2995 for customization. See \CDref{texmf/doc/web2c/web2c.html\#TCX-files}
2996 {\texttt{texmf/doc/web2c/web2c.html\#TCX-files}}.
2997 (By the way, with Unicode input, \TeX\ may output partial character
2998 sequences when showing error contexts, since it is byte-oriented.)
2999
3000 \item \textsf{pdfetex} is now the default engine for all formats
3001 except (plain) \textsf{tex} itself. (Of course it generates \acro{DVI}
3002 when run as \textsf{latex}, etc.) This means, among other things, that
3003 the microtypographic features of \textsf{pdftex} are available in
3004 \LaTeX, \ConTeXt, etc., as well as the \eTeX\ features
3005 (\OnCD{texmf-dist/doc/etex/base/}).
3006
3007 It also means it's \emph{more important than ever} to use the
3008 \pkgname{ifpdf} package (works with both plain and \LaTeX) or equivalent
3009 code, because simply testing whether \cs{pdfoutput} or some other
3010 primitive is defined is not a reliable way to determine if \acro{PDF}
3011 output is being generated. We made this backward compatible as best we
3012 could this year, but next year, \cs{pdfoutput} may be defined even when
3013 \acro{DVI} is being written.
3014
3015 \item pdf\TeX\ (\url{http://pdftex.org}) has many new features:
3016
3017 \begin{itemize*}
3018
3019 \item \cs{pdfmapfile} and \cs{pdfmapline} provide font map support
3020 from within a document.
3021
3022 \item Microtypographic font expansion can be used more easily.\\
3023 \url{http://www.ntg.nl/pipermail/ntg-pdftex/2004-May/000504.html}
3024
3025 \item All parameters previously set through the special configuration
3026 file \filename{pdftex.cfg} must now be set through primitives,
3027 typically in \filename{pdftexconfig.tex}; \filename{pdftex.cfg} is no
3028 longer supported. Any extant \filename{.fmt} files must be redumped
3029 when \filename{pdftexconfig.tex} is changed.
3030
3031 \item See the pdf\TeX\ manual for more: \OnCD{texmf/doc/pdftex/manual}.
3032
3033 \end{itemize*}
3034
3035 \item The \cs{input} primitive in \cmdname{tex} (and \cmdname{mf} and
3036 \cmdname{mpost}) now accepts double quotes containing spaces and other
3037 special characters. Typical examples:
3038 \begin{verbatim}
3039 \input "filename with spaces" % plain
3040 \input{"filename with spaces"} % latex
3041 \end{verbatim}
3042 See the Web2C manual for more: \OnCD{texmf/doc/web2c}.
3043
3044 \item enc\TeX\ support is now included within Web2C and consequently all
3045 \TeX\ programs, via the \optname{-enc} option\Dash \emph{only when
3046 formats are built}. enc\TeX\ supports general re-encoding of input and
3047 output, enabling full support of Unicode (in \acro{UTF}-8). See
3048 \OnCD{texmf-dist/doc/generic/enctex/} and
3049 \url{http://www.olsak.net/enctex.html}.
3050
3051 \item Aleph, a new engine combining \eTeX\ and \OMEGA, is available.
3052 A little information is available in \OnCD{texmf-dist/doc/aleph/base}
3053 and \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=aleph}. The
3054 \LaTeX-based format for Aleph is named \textsf{lamed}.
3055
3056 \item The latest \LaTeX\ release has a new version of the
3057 \acro{LPPL}\Dash now officially a Debian-approved license. Assorted
3058 other updates, see the \filename{ltnews} files in
3059 \OnCD{texmf-dist/doc/latex/base}.
3060
3061 \item \cmdname{dvipng}, a new program for converting \acro{DVI} to
3062 \acro{PNG} image files, is included. See \OnCD{texmf/doc/man/man1/dvipng.1}.
3063
3064 \item We reduced the \pkgname{cbgreek} package to a ``medium'' sized set
3065 of fonts, with the assent and advice of the author (Claudio Beccari).
3066 The excised fonts are the invisible, outline, and transparency ones,
3067 which are relatively rarely used, and we needed the space. The full set
3068 is of course available from \acro{CTAN}
3069 (\url{http://www.ctan.org/tex-archive/fonts/greek/cb}).
3070
3071 \item \cmdname{oxdvi} has been removed; just use \cmdname{xdvi}.
3072
3073 \item The \cmdname{ini} and \cmdname{vir} commands (links) for
3074 \cmdname{tex}, \cmdname{mf}, and \cmdname{mpost} are no longer created,
3075 such as \cmdname{initex}. The \cmdname{ini} functionality has been
3076 available through the command-line option \optname{-ini} for years now.
3077
3078 \item \textsf{i386-openbsd} platform support was removed. Since the
3079 \pkgname{tetex} package in the \acro{BSD} Ports system is available, and
3080 \acro{GNU/}Linux and Free\acro{BSD} binaries were available, it seemed
3081 volunteer time could be better spent elsewhere.
3082
3083 \item On \textsf{sparc-solaris} (at least), you may have to set the
3084 \envname{LD\_LIBRARY\_PATH} environment variable to run the
3085 \pkgname{t1utils} programs. This is because they are compiled with C++,
3086 and there is no standard location for the runtime libraries. (This is
3087 not new in 2004, but wasn't previously documented.) Similarly, on
3088 \textsf{mips-irix}, the \acro{MIPS}pro 7.4 runtimes are required.
3089
3090 \end{itemize}
3091
3092 \subsection{Present}
3093 \label{tlcurrent}
3094
3095 2005 saw the usual huge number of updates to packages and programs.
3096 The infrastructure stayed relatively stable from 2004, but inevitably
3097 there were some changes there as well:
3098
3099 \begin{itemize}
3100
3101 \item New scripts \cmdname{texconfig-sys}, \cmdname{updmap-sys}, and
3102 \cmdname{fmtutil-sys} were introduced, which modify the
3103 configuration in the system trees. The \cmdname{texconfig},
3104 \cmdname{updmap}, and \cmdname{fmtutil} scripts now modify
3105 user-specific files, under \dirname{$HOME/.texlive2005}.
3106 See section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig}.
3107
3108 \item Corresponding new variables \envname{TEXMFCONFIG} and
3109 \envname{TEXMFSYSCONFIG} to specify the trees where configuration
3110 files (user or system, respectively) are found. Thus, you may
3111 need to move personal versions of \filename{fmtutil.cnf} and
3112 \filename{updmap.cfg} to these places; another option is to
3113 redefine \envname{TEXMFCONFIG} or \envname{TEXMFSYSCONFIG} in
3114 \filename{texmf.cnf}. In any case the real location of these files
3115 and the values of \envname{TEXMFCONFIG} and \envname{TEXMFSYSCONFIG}
3116 must agree.
3117 See section~\ref{sec:texmftrees}, \p.\pageref{sec:texmftrees}.
3118
3119 \item Last year, we kept \verb|\pdfoutput| and other primitives undefined
3120 for DVI output, even though the \cmdname{pdfetex} program was
3121 being used. This year, as promised, we undid that compatibility
3122 measure. So if your document uses \verb|\ifx\pdfoutput\undefined|
3123 to test if PDF is being output, it will need to be changed. You
3124 can use the package \pkgname{ifpdf.sty} (which works under both
3125 plain \TeX\ and \LaTeX) to do this, or steal its logic.
3126
3127 \item Last year, we changed most formats to output (8-bit) characters as
3128 themselves (see previous section). The new TCX file
3129 \filename{empty.tcx} now provides an easier way to get the
3130 original \verb|^^| notation if you so desire, as in:
3131 \begin{verbatim}
3132 latex --translate-file=empty.tcx yourfile.tex
3133 \end{verbatim}
3134
3135 \item The new program \cmdname{dvipdfmx} is included for translation of
3136 DVI to PDF; this is an actively maintained update of
3137 \cmdname{dvipdfm} (which is also still available for now, though
3138 no longer recommended).
3139
3140 \item The new programs \cmdname{pdfopen} and \cmdname{pdfclose} are included
3141 to allow reloading of pdf files in the Adobe Acrobat Reader without
3142 restarting the program. (Other pdf readers, notably \cmdname{xpdf},
3143 \cmdname{gv}, and \cmdname{gsview}, have never suffered from this
3144 problem.)
3145
3146 \item For consistency, the variables \envname{HOMETEXMF} and
3147 \envname{VARTEXMF} have been renamed to \envname{TEXMFHOME} and
3148 \envname{TEXMFSYSVAR}, respectively. There is also
3149 \envname{TEXMFVAR}, which is by default user-specific. See the
3150 first point above.
3151
3152 \end{itemize}
3153
3154 \subsection{Future}
3155
3156 \emph{\TL{} is not perfect!} (And never will be.) We intend to
3157 continue to release new versions yearly, and would like to provide more
3158 help material, more utilities, more installation programs, and (of
3159 course) an ever-improved and checked tree of macros and fonts. This work
3160 is all done by hard-pressed volunteers in their limited spare time, and
3161 a great deal remains to be done. If you can help, don't hesitate to put
3162 your name forward!
3163
3164 Please send corrections, suggestions, and offers of help to:\hfill\null
3165 \begin{quote}
3166 Sebastian Rahtz \ / \ 7 Stratfield Road \ / \ Oxford OX2 7BG \ / \ UK \\
3167 \email{[email protected]} \\
3168 \url{http://tug.org/texlive}
3169 \end{quote}
3170
3171 \medskip
3172 \noindent \textsl{Happy \TeX ing!}
3173
3174 \end{document}