Debian Codegraph @

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

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