Debian Codegraph @

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

raw
1 % $Id: texlive-en.tex 15931 2009-11-03 00:48:56Z 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 \usepackage[latin1]{inputenc} % translators: use your preferred encodings.
10 \usepackage[T1]{fontenc}
11
12 \begin{document}
13
14 \title{%
15 {\huge \textit{The \TeX\ Live Guide}\\\smallskip}%
16 {\LARGE \textsf{\TL{} 2009}}%
17 }
18
19 \author{Karl Berry, editor \\[3mm]
20 \url{http://tug.org/texlive/}
21 }
22
23 \date{November 2009}
24
25 \maketitle
26
27 \begin{multicols}{2}
28 \tableofcontents
29 %\listoftables
30 \end{multicols}
31
32 \section{Introduction}
33 \label{sec:intro}
34
35 \subsection{\TeX\ Live and the \TeX\ Collection}
36
37 This document describes the main features of the \TL{} software
38 distribution\Dash \TeX{} and related programs for \GNU/Linux
39 and other Unix flavors, \MacOSX, and Windows systems.
40
41 You may have acquired \TL{} by downloading, or on the \TK{} \DVD, which
42 \TeX{} user groups distribute among their members, or in other ways.
43 Section \ref{sec:tl-coll-dists} briefly describes the contents of the
44 \DVD. Both \TL{} and the \TK{} are cooperative efforts by the \TeX{}
45 user groups. This document mainly describes \TL{} itself.
46
47 \TL{} includes executables for \TeX{}, \LaTeXe{}, \ConTeXt,
48 \MF, \MP, \BibTeX{} and many other programs; an extensive collection
49 of macros, fonts and documentation; and support for typesetting in
50 many different scripts from around the world.
51
52 For a brief summary of the major changes in this edition of \TL{},
53 see the end of the document, section~\ref{sec:history}
54 (\p.\pageref{sec:history}).
55
56 \subsection{Operating system support}
57 \label{sec:os-support}
58
59 \TL{} contains binaries for many Unix-based architectures, including
60 \GNU/Linux and \MacOSX. There are also Cygwin binaries. The
61 included sources can be compiled on platforms for which we do not
62 have binaries.
63
64 As to Windows: only Windows 2000 and later are
65 supported. Windows~9\textit{x}, \acro{ME} and \acro{NT} have been
66 dropped. Because of this change, Windows requires much less special
67 treatment compared to the Unix systems. There are no special 64-bit
68 executables for Windows, but the 32-bit executables should run on 64-bit
69 systems.
70
71 See section~\ref{sec:tl-coll-dists} for alternate solutions
72 for Windows and \MacOSX.
73
74 \subsection{Basic installation of \protect\TL{}}
75 \label{sec:basic}
76
77 You can install \TL{} either from \DVD{} or over the Internet. The net
78 installer itself is small, and downloads everything requested from the
79 Internet.
80
81 The \DVD{} installer lets you install to a local disk, but you can also
82 run \TL{} directly from the \DVD{} (or from a \DVD{} image, if your
83 system supports that). Installation is described in later sections, but
84 here is a quick start:
85
86 \begin{itemize*}
87
88 \item The installation script is named \filename{install-tl}. It can
89 operate in a ``wizard mode'' given the option \code{-gui=wizard}
90 (default for Windows), a text mode given \code{-gui=text} (default for
91 everything else), and an expert \GUI{} mode given \code{-gui=perltk}.
92
93 \item One of the installed items is the `\TL\ Manager' program,
94 named \prog{tlmgr}. Like the installer, it can be used in both \GUI{}
95 mode and in text mode. You can use it to install and uninstall
96 packages and do various configuration tasks.
97
98 \end{itemize*}
99
100
101 \htmlanchor{security}
102 \subsection{Security considerations}
103 \label{sec:security}
104
105 To the best of our knowledge, the core \TeX\ programs themselves are
106 (and always have been) extremely robust. However, the contributed
107 programs in \TeX\ Live may not reach the same level, despite everyone's
108 best efforts. As always, you should be careful when running programs on
109 untrusted input; for maximum safety, use a new subdirectory.
110
111 This need for care is especially urgent on Windows, since in general
112 Windows finds programs in the current directory before anything else,
113 regardless of the search path. This opens up a wide variety of possible
114 attacks. We have closed many holes, but undoubtedly some remain,
115 especially with third-party programs. Thus, we recommend checking for
116 suspicious files in the current directory, especially executables
117 (binaries or scripts). Ordinarily they should not be present, and
118 definitely should not normally be created by merely processing a document.
119
120 Finally, \TeX\ (and its companion programs) are able to write files when
121 processing documents, a feature that can also be abused in a wide
122 variety of ways. Again, processing unknown documents in a new
123 subdirectory is the safest bet.
124
125
126 \subsection{Getting help}
127 \label{sec:help}
128
129 The \TeX{} community is active and friendly, and most serious questions
130 end up getting answered. However, the support is informal, done by
131 volunteers and casual readers, so it's especially important that you do
132 your homework before asking. (If you prefer guaranteed commercial
133 support, you can forgo \TL{} completely and purchase a vendor's system;
134 \url{http://tug.org/interest.html#vendors} has a list.)
135
136 Here is a list of resources, approximately in the order we recommend
137 using them:
138
139 \begin{description}
140 \item [Getting Started] If you are new to \TeX, the web page
141 \url{http://tug.org/begin.html} gives a brief introduction to the system.
142
143 \item [\TeX{} \acro{FAQ}] The \TeX{} \acro{FAQ} is a huge compendium
144 of answers to all sorts of questions, from the most basic to the
145 most arcane. It is included on \TL{} in
146 \OnCD{texmf-dist/doc/generic/FAQ-en/html/index.html}, and is available
147 on the Internet through \url{http://www.tex.ac.uk/faq}. Please
148 check here first.
149
150 \item [\TeX{} Catalogue] If you are looking for a specific package,
151 font, program, etc., the \TeX{} Catalogue is the place to look. It is a
152 huge collection of all \TeX{}-related items. See
153 \url{http://www.ctan.org/help/Catalogue/}.
154
155 \item [\TeX{} Web Resources] The web page
156 \url{http://tug.org/interest.html} has many \TeX{}-related links, in
157 particular for numerous books, manuals, and articles on all aspects of
158 the system.
159
160 \item [support archives] The two principal support forums are the
161 Usenet newsgroup \url{news:comp.text.tex} and the mailing list
162 \email{[email protected]}. Their archives have years of past
163 questions and answers for your searching pleasure, via
164 \url{http://groups.google.com/group/comp.text.tex/topics} and
165 \url{http://tug.org/mail-archives/texhax}, respectively. And a general web
166 search, for example on \url{http://google.com}, never hurts.
167
168 \item [asking questions] If you cannot find an answer, you can post to
169 \dirname{comp.text.tex} through Google or your newsreader, or to
170 \email{[email protected]} through email. But before you post,
171 \emph{please} read this \acro{FAQ} entry, to maximize
172 your chances of getting a useful answer:
173 \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=askquestion}.
174
175 \item [\TL{} support] If you want to report a bug or have
176 suggestions or comments on the \TL{} distribution, installation, or
177 documentation, the mailing list is \email{[email protected]}. However,
178 if your question is about how to use a particular program included in
179 \TL{}, please write to that program's maintainer or
180 mailing list. Often running a program with the \code{-{}-help} option
181 will provide a bug reporting address.
182
183 \end{description}
184
185 The other side of the coin is helping others who have questions. Both
186 \dirname{comp.text.tex} and \code{texhax} are open to anyone, so feel
187 free to join, start reading, and help out where you can.
188
189
190 % don't use \TL so the \uppercase in the headline works. Also so
191 % tex4ht ends up with the right TeX. Likewise the \protect's.
192 \section{Overview of \protect\TeX\protect\ Live}
193 \label{sec:overview-tl}
194
195 This section describes the contents of \TL{} and the \TK{} of which it
196 is a part.
197
198 \subsection{The \protect\TeX\protect\ Collection: \TL, pro\TeX{}t, Mac\TeX}
199 \label{sec:tl-coll-dists}
200
201 The \TK{} \DVD{} comprises the following:
202
203 \begin{description}
204
205 \item [\TL] A complete \TeX{} system which can be run live or
206 installed to disk. Its home page is \url{http://tug.org/texlive/}.
207
208 \item [Mac\TeX] for \MacOSX, this adds a native \MacOSX\ installer and other
209 Mac applications to \TL{}. Its home page is
210 \url{http://tug.org/mactex/}.
211
212 \item [pro\TeX{}t] An enhancement of the \MIKTEX\ distribution for Windows,
213 \ProTeXt\ adds a few extra tools to \MIKTEX, and simplifies
214 installation. It is entirely independent of \TL{}, and has its own
215 installation instructions. The \ProTeXt\ home page is
216 \url{http://tug.org/protext}.
217
218 \item [CTAN] A snapshot of the \CTAN{} repository (\url{http://www.ctan.org}).
219
220 \item [\texttt{texmf-extra}] A directory with assorted additional packages.
221
222 \end{description}
223
224 \CTAN{}, \pkgname{protext}, and \dirname{texmf-extra} do not
225 necessarily follow the same copying conditions as \TL{}, so be careful
226 when redistributing or modifying.
227
228
229 \subsection{Top level \TL{} directories}
230 \label{sec:tld}
231
232 Here is a brief listing and description of the top level directories in the
233 \TL{} distribution. On the \TK{} \DVD, the entire \TL{} hierarchy is in
234 a subdirectory \dirname{texlive}, not at the top level of the disc.
235
236 \begin{ttdescription}
237 \item[bin] The \TeX{} system programs, arranged by platform.
238 %
239 \item[readme-*.dir] Quick overview and useful links for \TL{},
240 in various languages, in both \HTML{} and plain text.
241 %
242 \item[source] The source to all included programs, including the main \Webc{}
243 \TeX{} and \MF{} distributions.
244 %
245 \item[texmf] See \dirname{TEXMFMAIN} below.
246 %
247 \item[texmf-dist] See \dirname{TEXMFDIST} below.
248 %
249 \item[tlpkg] Scripts, programs and data for managing the
250 installation, and some special support for Windows.
251 \end{ttdescription}
252
253 In addition to the directories above, the installation scripts and
254 \filename{README} files (in various languages) are at the top level of
255 the distribution.
256
257 For documentation, the comprehensive links in the top-level file
258 \OnCD{doc.html} may be helpful. The documentation for the programs
259 (manuals, man pages, Info files) is in \dirname{texmf/doc}. The
260 documentation for \TeX\ packages and formats is in
261 \dirname{texmf-dist/doc}. You can use the \cmdname{texdoc} program to
262 find any documentation wherever it is located.
263
264 This \TL\ documentation itself is in \dirname{texmf/doc/texlive},
265 available in several languages:
266
267 \begin{itemize*}
268 \item{Simplified Chinese:} \OnCD{texmf/doc/texlive/texlive-zh-cn}
269 \item{Czech/Slovak:} \OnCD{texmf/doc/texlive/texlive-cz}
270 \item{English:} \OnCD{texmf/doc/texlive/texlive-en}
271 \item{French:} \OnCD{texmf/doc/texlive/texlive-fr}
272 \item{German:} \OnCD{texmf/doc/texlive/texlive-de}
273 \item{Polish:} \OnCD{texmf/doc/texlive/texlive-pl}
274 \item{Russian:} \OnCD{texmf/doc/texlive/texlive-ru}
275 \end{itemize*}
276
277 \subsection{Overview of the predefined texmf trees}
278 \label{sec:texmftrees}
279
280 This section lists the predefined variables specifying the texmf trees
281 used by the system, and their intended purpose, and the default layout
282 of \TL{}. The command \texttt{tlmgr~conf} shows the values of these
283 variables, so that you can easily find out how they map to particular
284 directories in your installation.
285
286 \begin{ttdescription}
287 \item [TEXMFMAIN] The tree which holds vital parts of the
288 system such as configuration files, helper scripts, and program
289 documentation.
290 \item [TEXMFDIST] The tree which holds the main set of macro packages,
291 fonts, etc.
292 \item [TEXMFLOCAL] The tree which administrators can use for system-wide
293 installation of additional or updated macros, fonts, etc.
294 \item [TEXMFHOME] The tree which users can use for their own individual
295 installations of additional or updated macros, fonts, etc.
296 The expansion of this variable dynamically adjusts for each user to
297 their own individual directory.
298 \item [TEXMFCONFIG] The tree used by the utilities
299 \verb+texconfig+, \verb+updmap+, and \verb+fmtutil+ to store modified
300 configuration data. Under \envname{TEXMFHOME} by default.
301 \item [TEXMFSYSCONFIG] The tree used by the utilities
302 \verb+texconfig-sys+, \verb+updmap-sys+, and \verb+fmtutil-sys+ to
303 store modified configuration data.
304 \item [TEXMFVAR] The tree used by \verb+texconfig+, \verb+updmap+ and
305 \verb+fmtutil+ to store (cached) runtime data such as format files and
306 generated map files. Under \envname{TEXMFHOME} by default.
307 \item [TEXMFSYSVAR] The tree used by \verb+texconfig-sys+,
308 \verb+updmap-sys+ and \verb+fmtutil-sys+, and also by \verb+tlmgr+, to
309 store (cached) runtime data such as format files and generated map files.
310 \end{ttdescription}
311
312 \noindent
313 The default layout is:
314 \begin{description}
315 \item[system-wide root] can span multiple \TL{} releases:
316 \begin{ttdescription}
317 \item[2008] A previous release.
318 \item[2009] The current release.
319 \begin{ttdescription}
320 \item [bin] ~
321 \begin{ttdescription}
322 \item [i386-linux] \GNU/Linux binaries
323 \item [...]
324 \item [universal-darwin] \MacOSX binaries
325 \item [win32] Windows binaries
326 \end{ttdescription}
327 \item [texmf\ \ \ \ \ \ \ ] This is \envname{TEXMFMAIN}.
328 \item [texmf-dist\ \ ] \envname{TEXMFDIST}
329 \item [texmf-var \ \ ] \envname{TEXMFSYSVAR}
330 \item [texmf-config] \envname{TEXMFSYSCONFIG}
331 \end{ttdescription}
332 \item [texmf-local] \envname{TEXMFLOCAL}, intended to be
333 retained from release to release.
334 \end{ttdescription}
335 \item[user's home] (\texttt{\$HOME} or
336 \texttt{\%USERPROFILE\%})
337 \begin{ttdescription}
338 \item[.texlive2008] Privately generated and configuration data
339 for a previous release.
340 \item[.texlive2009] Privately generated and configuration data
341 for the current release.
342 \begin{ttdescription}
343 \item [texmf-var\ \ \ ] \envname{TEXMFVAR}
344 \item [texmf-config] \envname{TEXMFCONFIG}
345 \end{ttdescription}
346 \item[texmf] \envname{TEXMFHOME} Personal macros, etc.
347 \end{ttdescription}
348 \end{description}
349
350
351 \subsection{Extensions to \protect\TeX}
352 \label{sec:tex-extensions}
353
354 Knuth's original \TeX{} itself is frozen, apart from rare bug fixes. It
355 is still present in \TL\ as the program \prog{tex}, and will remain so
356 for the foreseeable future. \TL{} contains several extended versions of
357 \TeX:
358
359 \begin{description}
360
361 \item [\eTeX] adds a set of new primitives
362 \label{text:etex} (related to macro expansion, character scanning,
363 classes of marks, additional debugging features, and more) and the
364 \TeXXeT{} extensions for bidirectional typesetting. In default mode,
365 \eTeX{} is 100\% compatible with ordinary \TeX. See
366 \OnCD{texmf-dist/doc/etex/base/etex_man.pdf}.
367
368 \item [pdf\TeX] builds on the \eTeX\ extensions, adding support for
369 writing \acro{PDF} output as well as \dvi{}, and many non-output-related
370 extensions. This is the program invoked for most formats, e.g.,
371 \prog{etex}, \prog{latex}, \prog{pdflatex}. Its web site is
372 \url{http://www.pdftex.org/}. See
373 \OnCD{texmf-dist/doc/pdftex/manual/pdftex-a.pdf} for the manual, and
374 \OnCD{texmf-dist/doc/pdftex/manual/samplepdf/samplepdf.tex} for example
375 usage of some of its features.
376
377 \item [Lua\TeX] is the designated successor of pdf\TeX,
378 and is mostly (but not entirely) backward-compatible. It is also
379 intended to be a functional superset of Aleph (see below), though
380 technical compatibility is not intended. The incorporated Lua
381 interpreter (\url{http://www.lua.org/}) enables elegant solutions for
382 many thorny \TeX{} problems. When called as \filename{texlua}, it
383 functions as a standalone Lua interpreter, and is already used as such
384 within \TL. Its web site is \url{http://www.luatex.org/}, and the
385 reference manual is \OnCD{texmf-dist/doc/luatex/luatexref-t.pdf}.
386
387 \item [\XeTeX] adds support for Unicode input and OpenType- and system
388 fonts, implemented using standard third-party libraries. See
389 \url{http://tug.org/xetex}.
390
391 \item [\OMEGA\ (Omega)] is based on Unicode (16-bit characters), thus
392 supports working with almost all the world's scripts simultaneously. It
393 also supports so-called `\OMEGA{} Translation Processes' (\acro{OTP}s),
394 for performing complex transformations on arbitrary input. Omega is no
395 longer included in \TL{} as a separate program; only Aleph is provided:
396
397 \item [Aleph] combines the \OMEGA\ and \eTeX\ extensions.
398 See \OnCD{texmf-dist/doc/aleph/base} for some minimal documentation.
399
400 \end{description}
401
402
403 \subsection{Other notable programs in \protect\TL}
404
405 Here are a few other commonly-used programs included in \TL{}:
406
407 \begin{cmddescription}
408
409 \item [bibtex] bibliography support.
410
411 \item [makeindex, xindy] index support.
412
413 \item [dvips] convert \dvi{} to \PS{}.
414
415 \item [xdvi] \dvi{} previewer for the X Window System.
416
417 \item [dvilj] \dvi{} drive for the HP LaserJet family.
418
419 \item [dviconcat, dviselect] cut and paste pages
420 from \dvi{} files.
421
422 \item [dvipdfmx] convert \dvi{} to \acro{PDF}, an alternative approach
423 to pdf\TeX\ (mentioned above). See the \pkgname{ps4pdf} and
424 \pkgname{pdftricks} packages for still more alternatives.
425
426 \item [psselect, psnup, \ldots] \PS{} utilities.
427
428 \item [texexec, texmfstart] Con\TeX{}t and \acro{PDF} processor.
429
430 \item [tex4ht] \TeX{} to \acro{HTML} (and \acro{XML} and more) converter.
431
432 \end{cmddescription}
433
434
435 \subsection{Fonts in \protect\TL}
436 \label{sec:tl-fonts}
437
438 \TL{} comes with many high-quality scalable fonts. See
439 \url{http://tug.org/fonts} and
440 \OnCD{texmf-dist/doc/fonts/free-math-font-survey}.
441
442
443 \section{Installation}
444 \label{sec:install}
445
446 \subsection{Starting the installer}
447 \label{sec:inst-start}
448
449 To begin, get the \TK{} \DVD{} or download the \TL{} net installer,
450 and locate the installer script: \filename{install-tl} for Unix,
451 \filename{install-tl.bat} for Windows.
452
453 \begin{description}
454 \item [Net installer:] Download from \CTAN, under
455 \dirname{systems/texlive/tlnet}; the url
456 \url{http://mirror.ctan.org/systems/texlive/tlnet} will automatically
457 redirect to a nearby, up-to-date, mirror. You can retrieve either
458 \filename{install-tl.zip} which can be used under Unix and Windows, or
459 the considerably smaller \filename{install-unx.tar.gz} for Unix
460 only. After unpacking, \filename{install-tl} and
461 \filename{install-tl.bat} will be in the \dirname{install-tl}
462 subdirectory.
463
464 \item [\TeX{} Collection \DVD:] go to its \dirname{texlive}
465 subdirectory. Under Windows, the installer normally starts automatically
466 when you insert the \DVD. You can get the \DVD\ by becoming a member of
467 a \TeX\ user group (highly recommended,
468 \url{http://tug.org/usergroups.html}), or purchasing it separately
469 (\url{http://tug.org/store}), or burning your own from the \ISO\
470 image.
471
472 \end{description}
473
474 See \url{http://tug.org/texlive/acquire.html} for more information and
475 other methods of getting the software.
476
477 The following sections explain installer start-up in more detail.
478
479 \subsubsection{Unix}
480
481 \noindent
482 Below, \texttt{>} denotes the shell prompt; user input is
483 \Ucom{\texttt{bold}}.
484 The script \filename{install-tl} is a Perl script. The simplest way
485 to start it on a Unix-compatible system is as follows:
486 \begin{alltt}
487 > \Ucom{cd /path/to/installer}
488 > \Ucom{perl install-tl}
489 \end{alltt}
490 (Or you can invoke \Ucom{perl /path/to/installer/install-tl}, or
491 \Ucom{./install-tl} if it stayed executable, etc.; we won't repeat all
492 these variations.) You may have to enlarge your terminal window so
493 that it shows the full text installer screen (Figure~\ref{fig:text-main}).
494
495 To install in expert \GUI\ mode (figure~\ref{fig:gui-main}; you'll
496 need the \dirname{Perl/TK} module), use:
497 \begin{alltt}
498 > \Ucom{perl install-tl -gui}
499 \end{alltt}
500
501 For a complete listing of the various options:
502 \begin{alltt}
503 > \Ucom{perl install-tl -help}
504 \end{alltt}
505
506 \textbf{Warning about Unix permissions:} Your \code{umask} at the time
507 of installation will be respected by the \TL{} installer. Therefore, if
508 you want your installation to be usable by users other than you, make
509 sure your setting is sufficiently permissive, for instance, \code{umask
510 002}. For more information about \code{umask}, consult your system
511 documentation.
512
513 \textbf{Special considerations for Cygwin:} Unlike other
514 Unix-compatible systems, Cygwin does not by default include all of the
515 prerequisite programs needed by the \TL{} installer. See
516 Section~\ref{sec:cygwin} for details.
517
518
519 \subsubsection{MacOSX}
520
521 As mentioned in section~\ref{sec:tl-coll-dists}, a separate distribution
522 is prepared for \MacOSX, named Mac\TeX\ (\url{http://tug.org/mactex}).
523 We recommend using the native Mac\TeX\ installer instead of the \TL\
524 installer on \MacOSX, because the native installer makes a few
525 Mac-specific adjustments, in particular to allow easily switching
526 between the various \TeX\ distributions for \MacOSX\ (Mac\TeX, gw\TeX,
527 Fink, MacPorts, \ldots).
528
529 Mac\TeX\ is firmly based on \TL, and the main \TeX\ trees are precisely
530 the same. It does add a few extra folders with Mac-specific
531 documentation and applications.
532
533
534 \subsubsection{Windows}
535
536 If you are using the net installer, or the \DVD\ installer failed to
537 start automatically, double-click \filename{install-tl.bat}.
538 For more customization options, e.g. selection of specific package
539 collections, run \filename{install-tl-advanced.bat} instead.
540
541 You can also start the installer from the command-prompt. Below,
542 \texttt{>} denotes the prompt; user input is \Ucom{\texttt{bold}}. If
543 you are in the installer directory, run just:
544 \begin{alltt}
545 > \Ucom{install-tl}
546 \end{alltt}
547
548 Or you can invoke it with an absolute location, such as:
549 \begin{alltt}
550 > \Ucom{D:\bs{}texlive\bs{}install-tl}
551 \end{alltt}
552 for the \TK\ \DVD, supposing that \dirname{D:} is the optical
553 drive. Figure~\ref{fig:wizard} displays the wizard installer, which
554 is the default for Windows.
555
556 To install in text mode, use:
557 \begin{alltt}
558 > \Ucom{install-tl -no-gui}
559 \end{alltt}
560
561 For a complete listing of the various options:
562 \begin{alltt}
563 > \Ucom{install-tl -help}
564 \end{alltt}
565
566 \begin{figure}[tb]
567 \begin{boxedverbatim}
568 Installing TeX Live 2009 from: ...
569 Platform: i386-linux => 'Intel x86 with GNU/Linux'
570 Distribution: live (uncompressed)
571 ...
572 Detected platform: Intel x86 with GNU/Linux
573
574 <B> binary systems: 1 out of 14
575
576 <S> Installation scheme (scheme-full)
577 83 collections out of 84, disk space required: 1882 MB
578
579 Customizing installation scheme:
580 <C> standard collections
581 <L> language collections
582
583 <D> directories:
584 TEXDIR (the main TeX directory):
585 /usr/local/texlive/2009
586 TEXMFLOCAL (directory for site-wide local files):
587 /usr/local/texlive/texmf-local
588 TEXMFSYSVAR (directory for variable and automatically generated data):
589 /usr/local/texlive/2009/texmf-var
590 TEXMFSYSCONFIG (directory for local config):
591 /usr/local/texlive/2009/texmf-config
592 TEXMFHOME (directory for user-specific files):
593 ~/texmf
594
595 <O> options:
596 [ ] use letter size instead of A4 by default
597 [X] create all format files
598 [X] install macro/font doc tree
599 [X] install macro/font source tree
600 [ ] create symlinks to standard directories
601
602 <V> set up for running from DVD
603
604 Other actions:
605 <I> start installation to hard disk
606 <H> help
607 <Q> quit
608 \end{boxedverbatim}
609 \caption{Main text installer screen (\GNU/Linux)}\label{fig:text-main}
610 \end{figure}
611
612 \begin{figure}[tb]
613 \tlpng{install-lnx-main}{\linewidth}
614 \caption{Expert \GUI{} installer screen (\GNU/Linux)}\label{fig:gui-main}
615 \end{figure}
616
617 \begin{figure}[tb]
618 \tlpng{wizard-w32}{\linewidth}
619 \caption{Wizard installer screen (Windows)}\label{fig:wizard}
620 \end{figure}
621
622
623 \htmlanchor{cygwin}
624 \subsubsection{Cygwin}
625 \label{sec:cygwin}
626
627 The \TL{} installer supports only Cygwin 1.7.
628 % Add a note about Angelo's workaround for 1.5 if he gets it ready for
629 % public use.
630 Before beginning the installation, use Cygwin's \filename{setup.exe} program to
631 install the \filename{perl} and \filename{wget} packages if you have
632 not already done so. The following additional packages are
633 recommended:
634 \begin{itemize*}
635 \item \filename{fontconfig} [needed by \XeTeX]
636 \item \filename{ghostscript} [needed by various utilities]
637 \item \filename{libXaw7} [needed by xdvi]
638 \item \filename{ncurses} [provides the 'clear' command used by the installer]
639 \end{itemize*}
640
641 \subsubsection{The text installer}
642
643 Figure~\ref{fig:text-main} displays the main text mode screen under
644 Unix. The text installer is the default on Unix.
645
646 This is only a command-line installer; there is no cursor support at
647 all. For instance, you cannot tab around checkboxes or input fields.
648 You just type something (case-sensitive) at the prompt and press the
649 Enter key, and then the entire terminal screen will be rewritten, with
650 adjusted content.
651
652 The text installer interface is this primitive for a reason: it
653 is designed to run on as many platforms as possible, even with a
654 very barebones Perl.
655
656 \subsubsection{The expert graphical installer}
657
658 Figure~\ref{fig:gui-main} displays the expert graphical installer under
659 \GNU/Linux. Other than using buttons and menus, this installer does
660 not differ much from the text one (Figure~\ref{fig:text-main}).
661
662 This mode can be invoked explicitly with
663 \begin{alltt}
664 > \Ucom{install-tl -gui=perltk}
665 \end{alltt}
666
667
668 \subsubsection{The simple wizard installer}
669
670 Under Windows, the default is to run the simplest installation method we
671 could devise, which we named the ``wizard'' installer. It installs
672 everything and asks almost no questions. If you want to customize your
673 setup, you should run one of the other installers.
674
675 This mode can be invoked explicitly with
676 \begin{alltt}
677 > \Ucom{install-tl -gui=wizard}
678 \end{alltt}
679
680
681 \subsection{Running the installer}
682 \label{sec:runinstall}
683
684 The installer is intended to be mostly self-explanatory, but following are a
685 few notes about the various options and submenus.
686
687 \subsubsection{Binary systems menu (Unix only)}
688 \label{sec:binary}
689
690 \begin{figure}[tbh]
691 \begin{boxedverbatim}
692 Available sets of binaries:
693 ===============================================================================
694
695 a [ ] alpha-linux DEC Alpha with GNU/Linux
696 b [ ] i386-cygwin Intel x86 with Cygwin
697 c [X] i386-linux Intel x86 with GNU/Linux
698 d [ ] i386-netbsd Intel x86 with NetBSD
699 e [ ] i386-solaris Intel x86 with Sun Solaris
700 f [ ] mips-irix SGI IRIX
701 g [ ] powerpc-aix PowerPC with AIX
702 h [ ] powerpc-linux PowerPC with GNU/Linux
703 i [ ] sparc-linux Sparc with GNU/Linux
704 j [ ] sparc-solaris Sparc with Solaris
705 k [ ] universal-darwin universal binaries for MacOSX/Darwin
706 l [ ] win32 Windows
707 m [ ] x86_64-linux x86_64 with GNU/Linux
708 \end{boxedverbatim}
709 \caption{Binaries menu}\label{fig:bin-text}
710 \end{figure}
711
712 Figure~\ref{fig:bin-text} displays the text mode binaries menu. By
713 default, only the binaries for your current platform will be installed.
714 From this menu, you can select installation of binaries for other
715 architectures as well. This can be useful if you are sharing a \TeX\
716 tree across a network of heterogenous machines, or for a dual-boot
717 system.
718
719 \subsubsection{Selecting what is going to be installed}
720 \label{sec:components}
721
722 \begin{figure}[tbh]
723 \begin{boxedverbatim}
724 Select a scheme:
725 ===============================================================================
726 a [ ] basic scheme (plain and LaTeX)
727 b [ ] ConTeXt scheme
728 c [X] full scheme (everything)
729 d [ ] GUST TeX Live scheme
730 e [ ] GUTenberg TeX Live scheme
731 f [ ] medium scheme (plain, latex, recommended packages, some languages)
732 g [ ] minimal scheme (plain only)
733 h [ ] Omega scheme
734 i [ ] teTeX scheme (more than medium, but nowhere near full)
735 j [ ] XML scheme
736 k [ ] custom selection of collections
737 \end{boxedverbatim}
738 \caption{Scheme menu}\label{fig:scheme-text}
739 \end{figure}
740
741 Figure~\ref{fig:scheme-text} displays the \TL\ scheme menu; from here,
742 you choose a ``scheme'', which is an overall set of package collections.
743 The default \optname{full} scheme installs everything available, but you
744 can also choose the \optname{basic} scheme for a small system,
745 \optname{minimal} for testing purposes, and \optname{medium} or
746 \optname{teTeX} to get something in between. There are also various
747 specialized and country-specific schemes.
748
749 \begin{figure}[tbh]
750 \tlpng{stdcoll}{.7\linewidth}
751 \caption{Collections menu}\label{fig:collections-gui}
752 \end{figure}
753
754 You can refine your scheme selection with the `standard collections' and
755 `language collections' menus (figure~\ref{fig:collections-gui}, shown in
756 \GUI\ mode for a change).
757
758 Collections are one level more detailed than schemes\Dash in essence, a
759 scheme consists of several collections, a collection consists of one or
760 more packages, and a package (the lowest level grouping in \TL) contains
761 the actual \TeX\ macro files, font files, and so on.
762
763 If you want more control than the collection menus provide, you can use
764 the \prog{tlmgr} program after installation (see
765 section~\ref{sec:tlmgr}); using that, you can control the installation
766 at the package level.
767
768 \subsubsection{Directories}
769 \label{sec:directories}
770
771 The default layout is described in section~\ref{sec:texmftrees},
772 \p.\pageref{sec:texmftrees}. The default location of
773 \dirname{TEXDIR} is different between Windows
774 (|%SystemDrive%\texlive\2009|) and Unix
775 (\dirname{/usr/local/texlive/2009}).
776
777 The main reason to change this default is if you lack write permission
778 for the default location. You don't have to be root or administrator to
779 install \TL, but you do need write access to the target directory.
780
781 A reasonable alternative choice is a directory under your home directory,
782 especially if you will be the sole user. Use
783 `|~|' to indicate this, as in `|~/texlive/2009|'.
784
785 We recommend including the year in the name, to enable keeping different
786 releases of \TL{} side by side. (You may wish to make a
787 version-independent name such as \dirname{/usr/local/texlive-cur} via a
788 symbolic link, which you can then update after testing the new release.)
789
790 Changing \dirname{TEXDIR} in the installer will also change
791 \dirname{TEXMFLOCAL}, \dirname{TEXMFSYSVAR} and
792 \dirname{TEXMFSYSCONFIG}.
793
794 \dirname{TEXMFHOME} is the recommended location for personal
795 macro files or packages. The default value is |~/texmf|. In
796 contrast to \dirname{TEXDIR}, here a |~| is preserved in the
797 newly-written configuration files, since it usefully refers to the home
798 directory of any individual running \TeX. It expands to
799 \dirname{$HOME} on Unix and \verb|%USERPROFILE%| on Windows.
800
801 \subsubsection{Options}
802 \label{sec:options}
803
804 \begin{figure}[tbh]
805 \begin{boxedverbatim}
806 <P> use letter size instead of A4 by default: [ ]
807 <F> create format files: [X]
808 <D> install font/macro doc tree: [X]
809 <S> install font/macro source tree: [X]
810 <L> create symlinks in standard directories: [ ]
811 binaries to:
812 manpages to:
813 info to:
814 \end{boxedverbatim}
815 \caption{Options menu (Unix)}\label{fig:options-text}
816 \end{figure}
817
818 Figure~\ref{fig:options-text} shows the text mode options menu.
819 More info:
820
821 \begin{description}
822 \item[use letter size instead of A4 by default:] The default paper
823 size selection. Of course, individual documents can and should
824 specify a specific paper size, if desired.
825
826 \item[create format files:] Although unnecessary format files
827 take time to generate and disk space to store, it is still recommended
828 to leave this option checked: if you don't, then format files will be
829 generated in people's private \dirname{TEXMFVAR} tree as they are
830 needed. In that location, they will not be updated automatically if
831 (say) binaries or hyphenation patterns are updated in the
832 installation, and thus could end up with incompatible format files.
833
834 \begin{comment}
835 \item[execution of restricted list of programs:] As of \TL\ 2009,
836 execution of a few external programs is allowed by default. The list
837 of allowed programs is given in the \filename{texmf.cnf}; it is very
838 small, but still very useful. See the 2009 news
839 (section~\ref{sec:2009news}) for more details.
840 \end{comment}
841
842 \item[install font/macro \ldots\ tree:] These options allow you to omit
843 downloading/installing the documentation and source files present in
844 most packages. Not recommended.
845
846 \item[create symlinks in standard directories] (Unix only):
847 This option bypasses the need to change environment variables. Without
848 this option, \TL{} directories usually have to be added to
849 \envname{PATH}, \envname{MANPATH} and \envname{INFOPATH}. You will
850 need write permissions to the target directories. It is strongly
851 advised \emph{not} to overwrite a \TeX\ system that came with your
852 system with this option. It is intended primarily for accessing the
853 \TeX\ system through directories that are already known to users, such
854 as \dirname{/usr/local/bin}, which don't already contain any \TeX\
855 files.
856 \end{description}
857
858 When all the settings are to your liking, you can type `I' to start the
859 installation process. When it is done, skip to
860 section~\ref{sec:postinstall} to read what else needs to be done, if
861 anything.
862
863 \htmlanchor{runfromdvd}
864 \subsubsection{Set up for running from DVD{} (text mode only)}
865 \label{sec:fromdvd}
866
867 Type `|V|' to select this option. This changes the main menu into something
868 as in figure~\ref{fig:main-fromdvd}.
869
870 \begin{figure}[tbh]
871 \begin{boxedverbatim}
872 ======================> TeX Live installation procedure <=====================
873 ...
874 <D> directories:
875 TEXDIRW (Writable root):
876 !! default location: /usr/local/texlive/2009
877 !! is not writable, please select a different one!
878 TEXMFLOCAL (directory for site-wide local files):
879 /usr/local/texlive/texmf-local
880 TEXMFSYSVAR (directory for variable and automatically generated data):
881 /usr/local/texlive/2009/texmf-var
882 TEXMFSYSCONFIG (directory for local config):
883 /usr/local/texlive/2009/texmf-config
884 TEXMFHOME (directory for user-specific files):
885 ~/texmf
886
887 <O> options:
888 [ ] use letter size instead of A4 by default
889 [X] create all format files
890
891 <V> set up for installing to hard disk
892
893 Other actions:
894 <I> start installation for running from DVD
895 <H> help
896 <Q> quit
897 \end{boxedverbatim}
898 \caption{The main menu with `\optname{from DVD}' set}\label{fig:main-fromdvd}
899 \end{figure}
900
901 Note the changes: all options about what to install have
902 disappeared, and the directories section now talks about
903 \dirname{TEXDIRW} or writable root. The symlinks option has also
904 disappeared.
905
906 The installer will still create various directories and configuration
907 files, but won't copy \dirname{texmf} or \dirname{texmf-dist} to hard
908 disk.
909
910 Post-install configuration for Unix will be slightly more complicated,
911 because now the directory layout deviates from the default; see
912 section~\ref{sec:postinstall}.
913
914 This option is not in the \GUI{} installer, but it is available both
915 for Unix and for Windows. Windows users have to start the installer
916 from a command prompt, see section~\ref{sec:cmdline}.
917
918 Section \ref{sec:portable-tl} describes a more strictly portable
919 way to run \TL, which doesn't make or require any changes in the
920 system's configuration, but doesn't allow any configuration either.
921
922 \subsection{Command-line install-tl options}
923 \label{sec:cmdline}
924
925 Type
926 \begin{alltt}
927 > \Ucom{install-tl -help}
928 \end{alltt}
929 for a listing of command-line options. Either |-| or |--| can be used
930 to introduce option names. These are the most common ones:
931
932 \begin{ttdescription}
933 \item[-gui] If possible, use the \GUI{} installer. This requires the
934 Perl/Tk module (\url{http://tug.org/texlive/distro.html#perltk});
935 if Perl/Tk is not available, installation continues in text mode.
936
937 \item[-no-gui] Force using the text mode installer, even under
938 Windows; you'll need this if you want a `from \DVD' installation,
939 since that is not available in \GUI{} mode.
940
941 \item[-lang {\sl LL}] Specify the installer interface
942 language as its standard two-letter code \textsl{LL}. Currently
943 supported languages: English (\texttt{en}, default), German
944 (\texttt{de}), French (\texttt{fr}), Dutch (\texttt{nl}), Polish
945 (\texttt{pl}), Slovenian (\texttt{sl}) and Vietnamese
946 (\texttt{vi}). The installer tries to determine the right language
947 itself but if it fails, or if the right language is not available,
948 then it uses English as a fallback.
949
950 \item[-profile {\sl file}] The installer always writes a file
951 \filename{texlive.profile} to the \dirname{tlpkg} subdirectory of your
952 installation. This option tells the installer to re-use such a
953 profile file, so you can install in batch mode on subsequent systems,
954 reproducing the choices you made in a prior installation.
955
956 \item [-repository {\sl url-or-directory}] Specify package
957 repository from which to install; see following.
958 \end{ttdescription}
959
960 \subsubsection{The \optname{-repository} option}
961 \label{sec:location}
962
963 The default package repository is a \CTAN{} mirror chosen automatically
964 via \url{http://mirror.ctan.org}.
965
966 If you want to override that, the location value can be a url starting
967 with \texttt{ftp:}, \texttt{http:}, or \texttt{file:/}, or a plain
968 directory path. (When giving an \texttt{http:}\ or \texttt{ftp:}\
969 location, trailing `\texttt{/}' characters and/or a trailing
970 `\texttt{/tlpkg}' component are ignored.)
971
972 For example, you could choose a particular \CTAN\ mirror with something
973 like: \url{http://ctan.example.org/tex-archive/systems/texlive/tlnet/},
974 substituting a real hostname and its particular top-level
975 \CTAN\ path for |ctan.example.org|. The list of \CTAN\ mirrors is
976 maintained at \url{http://ctan.org/mirrors}.
977
978 If the given argument is local (either a path or a \texttt{file:/} url),
979 compressed files in an \dirname{archive} subdirectory of the repository
980 path are used (even if uncompressed files are available as well).
981
982
983 \subsection{Post-install actions}
984 \label{sec:postinstall}
985
986 Some post-install may be required.
987
988 \subsubsection{Windows}
989
990 But on Windows, the installer takes care of everything.
991
992 \subsubsection{If symlinks were created}
993
994 If you elected to create symlinks in standard directories (mentioned in
995 section~\ref{sec:options}), then there is no need to edit environment
996 variables.
997
998 \subsubsection{Environment variables for Unix}
999 \label{sec:env}
1000
1001 The directory of the binaries for your platform must be added to
1002 the search path. Each supported platform has its own subdirectory
1003 under \dirname{TEXDIR/bin}. See figure~\ref{fig:bin-text} for the
1004 list of subdirectories and corresponding platforms.
1005
1006 You can also add the documentation man and Info directories to their
1007 respective search paths, if you want the system tools to find them.
1008 The man pages might be found automatically after the addition to
1009 \envname{PATH}.
1010
1011 For Bourne-compatible shells such as \prog{bash}, and using Intel x86
1012 GNU/Linux and a default directory setup as an example, the file to edit
1013 might be \filename{$HOME/.profile} (or another file sourced by
1014 \filename{.profile}, and the lines to add would look like this:
1015
1016 \begin{sverbatim}
1017 PATH=/usr/local/texlive/2009/bin/i386-linux:$PATH; export PATH
1018 MANPATH=/usr/local/texlive/2009/texmf/doc/man:$MANPATH; export MANPATH
1019 INFOPATH=/usr/local/texlive/2009/texmf/doc/info:$INFOPATH; export INFOPATH
1020 \end{sverbatim}
1021
1022 For csh or tcsh, the file to edit is typically \filename{$HOME/.cshrc}, and
1023 the lines to add might look like:
1024
1025 \begin{sverbatim}
1026 setenv PATH /usr/local/texlive/2009/bin/i386-linux:$PATH
1027 setenv MANPATH /usr/local/texlive/2009/texmf/doc/man:$MANPATH
1028 setenv INFOPATH /usr/local/texlive/2009/texmf/doc/info:$INFOPATH
1029 \end{sverbatim}
1030
1031 If you already have settings somewhere in your ``dot'' files, naturally
1032 the \TL\ directories should simply be merged in as appropriate.
1033
1034 \subsubsection{Environment variables: global configuration}
1035 \label{sec:envglobal}
1036
1037 If you want to make these changes globally, or for a user newly added to
1038 the system, then you are on your own; there is just too much variation
1039 between systems in how and where these things are configured.
1040
1041 Our two hints are: 1)~you may want to check for a file
1042 \filename{/etc/manpath.config} and, if present, add lines such as
1043
1044 \begin{sverbatim}
1045 MANPATH_MAP /usr/local/texlive/2009/bin/i386-linux \
1046 /usr/local/texlive/2009/texmf/doc/man
1047 \end{sverbatim}
1048
1049 And 2)~check for a file \filename{/etc/environment} which may define the
1050 search path and other default environment variables.
1051
1052 We also create a symbolic link named \code{man} in each (Unix) binary
1053 directory. Some \code{man} programs, such as the standard \MacOSX\
1054 \code{man}, will automatically find that, obviating the need for any man
1055 page setup.
1056
1057
1058 \subsubsection{Font configuration for \XeTeX}
1059 \label{sec:font-conf-xetex}
1060
1061 If you have installed the \filename{xetex} package on a Unix-compatible
1062 system, you need to configure your system if you want \XeTeX\ to be able
1063 to find the fonts shipped with \TL. To facilitate this, when the
1064 \pkgname{xetex} package is installed (either at initial installation or
1065 later), the necessary configuration file is created in
1066 \filename{TEXMFSYSVAR/fonts/conf/texlive-fontconfig.conf}.
1067
1068 To set up the \TL{} fonts for system-wide use (assuming you have
1069 suitable privileges), proceed as follows:
1070 \begin{enumerate*}
1071 \item Copy the \filename{texlive-fontconfig.conf} file to
1072 \dirname{/etc/fonts/conf.d/09-texlive.conf}.
1073 \item Run \Ucom{fc-cache -fsv}.
1074 \end{enumerate*}
1075
1076 If you do not have sufficient privileges to carry out the steps above,
1077 you can instead do the following to make the \TL{} fonts available
1078 to you as an individual \XeTeX{} user:
1079 \begin{enumerate*}
1080 \item Copy the \filename{texlive-fontconfig.conf} file to
1081 \filename{~/.fonts.conf}, where \filename{~} is your home directory.
1082 \item Run \Ucom{fc-cache -fv}.
1083 \end{enumerate*}
1084
1085
1086 \subsubsection{When running from DVD}
1087
1088 Normally, a \TL{} program consults a file \filename{texmf.cnf} for the
1089 location of the various trees. It looks for this file in a series of
1090 locations relative to its own location. However, this scheme breaks down
1091 when a program is run from \DVD{}: the \DVD{} is read-only. Some of the
1092 paths to be recorded in \filename{texmf.cnf} are only known at
1093 installation time, so this file cannot be on the \DVD{} and must be
1094 placed somewhere else. This makes it necessary to define an environment
1095 \envname{TEXMFCNF} variable which tells \TL{} programs in what directory
1096 to find this \filename{texmf.cnf}. It is also still necessary to modify
1097 the \envname{PATH} environment variable, as described before.
1098
1099 At the end of the installation, the installer should have printed a
1100 message giving the value to which \envname{TEXMFCNF} should be set. In
1101 case you missed it: this value is \dirname{$TEXMFSYSVAR/web2c}. For the
1102 default, \dirname{/usr/local/texlive/2009/texmf-var/web2c}, you need the
1103 lines
1104 \begin{sverbatim}
1105 TEXMFCNF=/usr/local/texlive/2009/texmf-var/web2c; export TEXMFCNF
1106 \end{sverbatim}
1107 or, for [t]csh:
1108 \begin{sverbatim}
1109 setenv TEXMFCNF /usr/local/texlive/2009/texmf-var/web2c
1110 \end{sverbatim}
1111
1112 This option is most useful when you want to run \TL{} on your own
1113 system, but don't have enough disk space to install it. If you want a
1114 truly `portable' \TL{} that is self-contained, e.g., for a USB stick,
1115 see section~\ref{sec:portable-tl}.
1116
1117 \subsubsection{\ConTeXt{} Mark IV}
1118
1119 The `old' \ConTeXt{} should run out of the box. The new `Mark IV'
1120 \ConTeXt{} will require manual setup; see
1121 \url{http://wiki.contextgarden.net/Running_Mark_IV}.
1122
1123
1124 \subsubsection{Integrating local and personal macros}
1125 \label{sec:local-personal-macros}
1126
1127 This is already mentioned implicitly in section~\ref{sec:texmftrees}:
1128 \dirname{TEXMFLOCAL} (by default,
1129 \dirname{/usr/local/texlive/texmf-local} or
1130 \verb|%SystemDrive%\texlive\texmf-local|)
1131 is intended for system-wide local fonts and macros; and
1132 \dirname{TEXMFHOME} (by default, \dirname{$HOME/texmf} or
1133 \verb|%USERPROFILE%\texmf|), is for personal fonts and macros. These
1134 directories are intended to stick around from release to release, and
1135 have their content seen automatically by a new \TL{} release.
1136 Therefore, it is best to refrain from changing the definition of
1137 \dirname{TEXMFLOCAL} to be too far away from the main \TL{} directory,
1138 or you will need to manually change future releases.
1139
1140 For both trees, files should be placed in their proper subdirectories;
1141 see \url{http://tug.org/tds} or consult
1142 \filename{texmf/web2c/texmf.cnf}. For instance, a \LaTeX{} class file or
1143 package should be placed in \dirname{TEXMFLOCAL/tex/latex} or
1144 \dirname{TEXMFHOME/tex/latex}, or a subdirectory thereof.
1145
1146 \dirname{TEXMFLOCAL} requires an up-to-date filename database, or files
1147 will not be found. You can update it with the command
1148 \cmdname{mktexlsr} or use the `Reinit file database' button on the
1149 configuration tab of \prog{tlmgr} in \GUI\ mode.
1150
1151 \subsubsection{Integrating third-party fonts}
1152
1153 This is unfortunately a messy topic. Forget about it unless you want to
1154 delve into many details of the \TeX{} installation. Don't forget to
1155 check first what you get for free: see section~\ref{sec:tl-fonts}.
1156
1157 A possible alternative is to use \XeTeX (see
1158 section~\ref{sec:tex-extensions}), which lets you use operating system
1159 fonts without any installation in \TeX.
1160
1161 If you do need to do this, see
1162 \url{http://tug.org/fonts/fontinstall.html} for our best effort at
1163 describing the procedure.
1164
1165 \subsection{Testing the installation}
1166 \label{sec:test-install}
1167
1168 After installing \TL{} as best you can, you naturally want to test
1169 it out, so you can start creating beautiful documents and\slash or fonts.
1170
1171 This section gives some basic procedures for testing that the new system
1172 is functional. We give Unix commands here; under \MacOSX{} and Windows,
1173 you're more likely to run the tests through a graphical interface, but
1174 the principles are the same.
1175
1176 \begin{enumerate}
1177
1178 \item Make sure that you can run the \cmdname{tex} program in the first
1179 place:
1180 \begin{alltt}
1181 > \Ucom{tex -{}-version}
1182 TeX 3.1415926 (TeX Live 2009)
1183 kpathsea version 5.0.0
1184 Copyright 2009 D.E. Knuth.
1185 ...
1186 \end{alltt}
1187 If this comes back with `command not found' instead of version and
1188 copyright information, or with an older version, most likely you don't
1189 have the correct \dirname{bin} subdirectory in your \envname{PATH}. See
1190 the environment-setting information on \p.\pageref{sec:env}.
1191
1192 \item Process a basic \LaTeX{} file:
1193 \begin{alltt}
1194 > \Ucom{latex sample2e.tex}
1195 This is pdfTeX, Version 3.1415926-1.40.10 (TeX Live 2009)
1196 ...
1197 Output written on sample2e.dvi (3 pages, 7484 bytes).
1198 Transcript written on sample2e.log.
1199 \end{alltt}
1200 If this fails to find \filename{sample2e.tex} or other files, most
1201 likely you have interference from old environment variables or
1202 configuration files; we recommend unsetting all \TeX-related environment
1203 variables for a start. (For a deep analysis, you can ask \TeX{} to
1204 report on exactly what it is searching for, and finding; see ``Debugging
1205 actions'' on page~\pageref{sec:debugging}.)
1206
1207 \item Preview the result online:
1208 \begin{alltt}
1209 > \Ucom{xdvi sample2e.dvi} # Unix
1210 > \Ucom{dviout sample2e.dvi} # Windows
1211 \end{alltt}
1212 You should see a new window with a nice document explaining some of the
1213 basics of \LaTeX{}. (Well worth reading, by the way, if you're new to
1214 \TeX.) You do have to be running under X for \cmdname{xdvi} to work; if
1215 you're not, or your \envname{DISPLAY} environment variable is set
1216 incorrectly, you'll get an error \samp{Can't open display}.
1217
1218 \item Create a \PS{} file for printing or display:
1219 \begin{alltt}
1220 > \Ucom{dvips sample2e.dvi -o sample2e.ps}
1221 \end{alltt}
1222
1223 \item Create a \acro{PDF} file instead of \dvi{}; this processes the
1224 \filename{.tex} file and writes \acro{PDF} directly:
1225 \begin{alltt}
1226 > \Ucom{pdflatex sample2e.tex}
1227 \end{alltt}
1228
1229 \item Preview the \acro{PDF} file:
1230 \begin{alltt}
1231 > \Ucom{gv sample2e.pdf}
1232 \textrm{or:}
1233 > \Ucom{xpdf sample2e.pdf}
1234 \end{alltt}
1235 Neither \cmdname{gv} nor \cmdname{xpdf} are included in \TL{}, so you
1236 must install them separately. See \url{http://www.gnu.org/software/gv}
1237 and \url{http://www.foolabs.com/xpdf}, respectively. There are plenty
1238 of other \acro{PDF} viewers, too. For Windows, we recommend trying
1239 Sumatra PDF (\url{http://blog.kowalczyk.info/software/sumatrapdf}).
1240
1241 \item Standard test files you may find useful in addition to
1242 \filename{sample2e.tex}:
1243
1244 \begin{ttdescription}
1245 \item [small2e.tex] A simpler document than \filename{sample2e}, to
1246 reduce the input size if you're having troubles.
1247 \item [testpage.tex] Test if your printer introduces any offsets.
1248 \item [nfssfont.tex] For printing font tables and tests.
1249 \item [testfont.tex] Also for font tables, but using plain \TeX{}.
1250 \item [story.tex] The most canonical (plain) \TeX{} test file of all.
1251 You must type \samp{\bs bye} to the \code{*} prompt after \samp{tex
1252 story.tex}.
1253 \end{ttdescription}
1254
1255 \item If you have installed the \filename{xetex} package, you can test
1256 its access to system fonts as follows:
1257 \begin{alltt}
1258 > \Ucom{xetex opentype-info.tex}
1259 This is XeTeX, Version 3.1415926\dots
1260 ...
1261 Output written on opentype-info.pdf (1 page).
1262 Transcript written on opentype-info.log.
1263 \end{alltt}
1264 If you get an error message saying ``Invalid fontname `Latin Modern
1265 Roman/ICU'\dots'', then you need to configure your system so that
1266 \XeTeX{} can find the fonts shipped with \TL. See
1267 Section~\ref{sec:font-conf-xetex}.
1268
1269 \end{enumerate}
1270
1271 \subsection{Links for additional downloadable software}
1272
1273 If you are new to \TeX{}, or otherwise need help with actually writing
1274 \TeX{} or \LaTeX{} documents, please visit
1275 \url{http://tug.org/begin.html} for some introductory resources.
1276
1277 Links for some other tools you may consider installing:
1278 \begin{description}
1279 \item[Ghostscript] \url{http://www.cs.wisc.edu/~ghost/}
1280 \item[Perl] \url{http://www.perl.org/} with
1281 supplementary packages from \acro{CPAN}, \url{http://www.cpan.org/}
1282 \item[ImageMagick] \url{http://www.imagemagick.com}, for graphics
1283 processing and conversion
1284 \item[NetPBM] \url{http://netpbm.sourceforge.net/}, also for graphics.
1285
1286 \item[\TeX-oriented editors] There is a wide choice, and it is a matter of the
1287 user's taste. Here is a selection (a few here are for Windows only).
1288 \begin{itemize*}
1289 \item \cmdname{GNU Emacs} is available natively under Windows, see
1290 \url{http://www.gnu.org/software/emacs/windows/ntemacs.html}.
1291 \item \cmdname{Emacs} with Auc\TeX\ for Windows is available in
1292 the directory \path{tlpkg/support} on the \TL \DVD; its home
1293 page is \url{http://www.gnu.org/software/auctex}.
1294 \item \cmdname{LEd} is available from \url{http://www.ctan.org/support/LEd}.
1295 \item \cmdname{SciTE} is available from
1296 \url{http://www.scintilla.org/SciTE.html}.
1297 \item \cmdname{Texmaker} is free software, available from
1298 \url{http://www.xm1math.net/texmaker/}.
1299 \item \cmdname{TeXnicCenter} is free software, available from
1300 \url{http://www.texniccenter.org} and in the pro\TeX{}t distribution.
1301 \item \cmdname{TeXworks} is free software, available from
1302 \url{http://tug.org/texworks} and installed for Windows and
1303 \MacOSX\ as part of \TL.
1304 \item \cmdname{Vim} is free software, available from
1305 \url{http://www.vim.org}.
1306 \item \cmdname{WinShell} is available from \url{http://www.winshell.de}.
1307 \item \cmdname{WinEdt} is shareware available though
1308 \url{http://tug.org/winedt} or \url{http://www.winedt.com}.
1309 \end{itemize*}
1310 \end{description}
1311 For a much longer list of packages and programs, see
1312 \url{http://tug.org/interest.html}.
1313
1314
1315 \section{Network installations}
1316 \label{sec:netinstall}
1317
1318 \TL{} has been designed to be shared between different users, and even
1319 different systems on a network. With a standard directory layout, no
1320 hard paths are configured: the locations for files needed by \TL{}
1321 programs are found relative to the programs. You can see this in the
1322 principal configuration file \filename{$TEXMFMAIN/web2c/texmf.cnf},
1323 which contains lines such as
1324 \begin{sverbatim}
1325 TEXMFMAIN = $SELFAUTOPARENT/texmf
1326 ...
1327 TEXMFLOCAL = $SELFAUTOPARENT/../texmf-local
1328 \end{sverbatim}
1329 This means that adding the directory for \TL{} executables for their
1330 platform to their search path is sufficient to get a working setup.
1331
1332 By the same token, you can also install \TL{} locally and then move
1333 the entire hierarchy afterwards to a network location.
1334
1335 For Windows, a sample network installation script named
1336 \filename{w32client} can be downloaded through
1337 \url{http://tug.org/texlive/w32client.html}. It creates settings and
1338 menu shortcuts for using an existing \TL{} installation on a \acro{LAN}.
1339 It also registers an uninstaller \filename{w32unclient}, available
1340 in the same zip file. See the web page for more information.
1341
1342
1343 \section{Maximally portable \protect\TL{} on DVD and USB}
1344 \label{sec:portable-tl}
1345
1346 The `running from \DVD{}' option described in
1347 section~\ref{sec:fromdvd} is fine for your own system, but if you
1348 are a guest on somebody else's system then you would probably like
1349 something with minimal side effects.
1350
1351 In the root of the \TL{} \DVD, or the \dirname{texlive} subdirectory of
1352 the \TK{} \DVD, are a \filename{tl-portable} script (Unix) and a
1353 \filename{tl-portable.bat} batch file (Windows) which start up a
1354 secondary shell\slash command prompt with environment settings
1355 for directly accessing the \TL{} on the \DVD.
1356
1357 When it runs for the first time, some files will be generated in a
1358 directory \dirname{~/.tlportable2009}, which will take a little time.
1359 On subsequent runs, though, it will start almost instantaneously.
1360
1361 The rest of the system will be unaware of \TL. If you want your editor
1362 to be aware of this \TL, then you can start it from a second, parallel,
1363 such \filename{tl-portable} session.
1364
1365 You can also use \filename{tl-portable} to run \TL{} on a
1366 \acro{USB} stick. In this case, copy all the top-level files and
1367 the contents of the \dirname{bin}, \dirname{texmf},
1368 \dirname{texmf-dist}, and \dirname{tlpkg} directories (at least) to
1369 the stick. This may take quite a while! If you are copying to a
1370 \acro{FAT}32-formatted \acro{USB} stick, make sure to dereference
1371 symbolic links (\code{cp -L}). A \dirname{texmf-local} directory on
1372 the stick will also be found and used.
1373
1374 Then run \filename{tl-portable} from the root of the stick, as above.
1375 In this case, the script will notice that the stick is writable and use
1376 it for generated files. You could burn the resulting contents of the
1377 stick back to \DVD{} if that is more convenient to (for example) give to
1378 others.
1379
1380
1381 \section{\cmdname{tlmgr}: Managing your installation}
1382 \label{sec:tlmgr}
1383
1384 \begin{figure}[tb]
1385 \tlpng{tlmgr-gui}{\linewidth}
1386 \caption{\prog{tlmgr} in \GUI\ mode. The list of
1387 packages/collections/schemes only shows up after clicking the
1388 `Load' button.}\label{fig:tlmgr-gui}
1389 \end{figure}
1390
1391 \begin{figure}[tb]
1392 \tlpng{tlmgr-config}{.8\linewidth}
1393 \caption{\texttt{tlmgr} in GUI mode: Configuration tab}\label{fig:tlmgr-config}
1394 \end{figure}
1395
1396 \TL{} includes a program named \prog{tlmgr} for managing \TL{} after the
1397 initial installation. The programs \prog{updmap}, \prog{fmtutil} and
1398 \prog{texconfig} are still included and will be retained in the future,
1399 but \prog{tlmgr} is now the preferred interface. Its capabilities
1400 include:
1401
1402 \begin{itemize*}
1403 \item installing, updating, backing up, restoring, and uninstalling
1404 individual packages, optionally taking dependencies into account;
1405 \item searching for and listing packages, etc.;
1406 \item listing, adding, and removing architectures;
1407 \item changing installation options such as paper size and source
1408 location (see section~\ref{sec:location}).
1409 \end{itemize*}
1410 \textit{Warning:} \prog{tlmgr} has not been designed for or tested
1411 with installations which run from \DVD.
1412
1413 \subsection{\cmdname{tlmgr} GUI mode}
1414 \prog{tlmgr} can be started in \GUI{} mode with
1415 \begin{alltt}
1416 > \Ucom{tlmgr -gui}
1417 \end{alltt}
1418 or in Windows via the Start menu: \texttt{Start}, \texttt{Programs},
1419 \texttt{TeX Live 2009}, \texttt{TeX Live Manager}. After clicking `Load'
1420 it displays a list of available and installed packages\Dash the latter
1421 prepended with `(i)'. This assumes of course that the installation
1422 source is valid and reachable.
1423
1424 Figure~\ref{fig:tlmgr-config} shows the configuration tab.
1425
1426 \subsection{Sample \cmdname{tlmgr} command-line invocations}
1427
1428 After the initial installation, you can update your system to the latest
1429 versions available with:
1430 \begin{alltt}
1431 > \Ucom{tlmgr update -all}
1432 \end{alltt}
1433 If this makes you nervous, first try
1434 \begin{alltt}
1435 > \Ucom{tlmgr update -all -dry-run}
1436 \end{alltt}
1437 or (less verbose):
1438 \begin{alltt}
1439 > \Ucom{tlmgr update -list}
1440 \end{alltt}
1441
1442 This more complex example adds a collection, for the engine Xe\TeX, from
1443 a local directory:
1444
1445 \begin{alltt}
1446 > \Ucom{tlmgr -repository /local/mirror/tlnet install collection-xetex}
1447 \end{alltt}
1448 It generates the following output (abridged):
1449 \begin{fverbatim}
1450 install: collection-xetex
1451 install: arabxetex
1452 ...
1453 install: xetex
1454 install: xetexconfig
1455 install: xetex.i386-linux
1456 running post install action for xetex
1457 install: xetex-def
1458 ...
1459 running mktexlsr
1460 mktexlsr: Updating /usr/local/texlive/2009/texmf/ls-R...
1461 ...
1462 running fmtutil-sys --missing
1463 ...
1464 Transcript written on xelatex.log.
1465 fmtutil: /usr/local/texlive/2009/texmf-var/web2c/xetex/xelatex.fmt installed.
1466 \end{fverbatim}
1467
1468 As you can see, \prog{tlmgr} installs dependencies, and takes care of any
1469 necessary post-install actions, including updating the filename database
1470 and (re)generating formats. In the above, we generated new formats for
1471 \XeTeX.
1472
1473 To describe a package (or collection or scheme):
1474 \begin{alltt}
1475 > \Ucom{tlmgr show collection-latexextra}
1476 \end{alltt}
1477 which produces
1478 \begin{fverbatim}
1479 package: collection-latexextra
1480 category: Collection
1481 shortdesc: LaTeX supplementary packages
1482 longdesc: A large collection of add-on packages for LaTeX.
1483 installed: Yes
1484 revision: 14675
1485 \end{fverbatim}
1486
1487 Last and most important, for full documentation see
1488 \url{http://tug.org/texlive/tlmgr.html}, or:
1489 \begin{alltt}
1490 > \Ucom{tlmgr -help}
1491 \end{alltt}
1492
1493
1494 \section{Notes on Windows}
1495 \label{sec:windows}
1496
1497 \TL\ has a single installer which runs on both Windows and Unix. This
1498 was only possible by dropping support for older Windows versions, so
1499 \TL\ can now be installed only on Windows 2000 and later.
1500
1501
1502 \subsection{Windows-specific features}
1503 \label{sec:winfeatures}
1504
1505 Under Windows, the installer does some extra things:
1506 \begin{description}
1507 \item[Menus and shortcuts.] A new `\TL{}' submenu of the
1508 Start menu is installed, which contains entries for some \GUI{}
1509 programs (\prog{tlmgr}, \prog{texdoctk}, the PS\_View (\prog{psv})
1510 PostScript previewer) and some documentation. PS\_View also gets a
1511 shortcut on the desktop as a drag-and-drop target for PostScript
1512 files.
1513 \item[Automatic setting of environment variables.] No manual
1514 configuration steps are required.
1515 \item[Uninstaller.] The installer creates an entry under `Add/Remove
1516 Programs' for \TL. The uninstall tab of \prog{tlmgr} refers to
1517 this.
1518 \end{description}
1519
1520 \subsection{Additional software included on Windows}
1521
1522 To be complete, a \TL installation needs support packages that are not
1523 commonly found on a Windows machine. \TL{} provides the missing
1524 pieces:
1525 \begin{description}
1526 \item[Perl and Ghostscript.] Because of the importance of Perl and
1527 Ghostscript, \TL{} includes `hidden' copies of these
1528 programs. \TL{} programs that need them know where to find them,
1529 but they don't betray their presence through environment variables
1530 or registry settings. They aren't full-scale installations, and
1531 shouldn't interfere with any system installations of Perl or
1532 Ghostscript.
1533
1534 \item[PS\_View.] Also installed is PS\_View, a \PS{} and \acro{PDF}
1535 viewer; see figure~\ref{fig:psview}.
1536
1537 \begin{figure}[tb]
1538 \tlpng{psview}{.6\linewidth}
1539 \caption{PS\_View: very high magnifications available!}\label{fig:psview}
1540 \end{figure}
1541
1542 \item[dviout.] Also installed is \prog{dviout}, a \acro{DVI} viewer.
1543 At first, when you preview files with \cmdname{dviout}, it will create
1544 fonts, because screen fonts were not installed. After a while, you
1545 will have created most of the fonts you use, and you will rarely see
1546 the font-creation window. More information can be found in the
1547 (highly recommended) on-line help.
1548
1549 \item[TeXworks.] \TeX{}works is a \TeX-oriented editor with
1550 an integrated \acro{PDF} viewer. It comes already preconfigured for \TL.
1551
1552 \item[Command-line tools.] A number of Windows ports of common Unix
1553 command-line programs are installed along with the usual \TL{}
1554 binaries. These include \cmdname{gzip}, \cmdname{unzip} and the
1555 command-line utilities from the \cmdname{xpdf} suite. The
1556 \cmdname{xpdf} viewer itself is not available for
1557 Windows. Instead, you can download the Sumatra \acro{PDF} viewer,
1558 which is based on xpdf, from
1559 \url{http://blog.kowalczyk.info/software/sumatrapdf}.
1560
1561 \item[fc-list, fc-cache et al.] The tools from the fontconfig library allow
1562 \XeTeX{} to handle system fonts on Windows. You can use
1563 \prog{fc-list} to determine the font names to pass to Xe\TeX's
1564 extended \cs{font} command. If necessary, run \prog{fc-cache}
1565 first to update font information.
1566
1567 \end{description}
1568
1569
1570 \subsection{User Profile is Home}
1571 \label{sec:winhome}
1572
1573 The Windows counterpart of a Unix home directory is the
1574 \verb|%USERPROFILE%| directory. Under Windows \acro{XP} and Windows 2000, this
1575 is usually \verb|C:\Documents and Settings\<username>|, and under
1576 Windows Vista \verb|C:\Users\<username>|. In the
1577 \filename{texmf.cnf} file, and \KPS{} in general, \verb|~| will expand
1578 appropriately on both Windows and Unix.
1579
1580
1581 \subsection{The Windows registry}
1582 \label{sec:registry}
1583
1584 Windows stores nearly all configuration data in its registry. The
1585 registry contains a set of hierarchically organized keys, with several
1586 root keys. The most important ones for installation programs are
1587 \path{HKEY_CURRENT_USER} and \path{HKEY_LOCAL_MACHINE}, \path{HKCU} and
1588 \path{HKLM} in short. The \path{HKCU} part of the registry is in the
1589 user's home directory (see section~\ref{sec:winhome}). \path{HKLM} is
1590 normally in a subdirectory of the Windows directory.
1591
1592 In some cases, system information could be obtained from environment
1593 variables but for other information, for example the location of
1594 shortcuts, it is necessary to consult the registry. Setting environment
1595 variables permanently also requires registry access.
1596
1597
1598 \subsection{Windows permissions}
1599 \label{sec:winpermissions}
1600
1601 In later versions of Windows, a distinction is made between regular
1602 users and administrators, where only the latter have free access to the
1603 entire operating system. In practice, though, you could better describe
1604 these classes of users as unprivileged users and normal users: being an
1605 administrator is the rule, not the exception. Nevertheless, we have made
1606 an effort to make \TL{} installable without administrative privileges.
1607
1608 If the user is an administrator, there is an option to install for all
1609 users. If this option is chosen, shortcuts are created for all users,
1610 and the system environment is modified. Otherwise, shortcuts and menu
1611 entries are created for the current user, and the user environment is
1612 modified.
1613
1614 Regardless of administrator status, the default root of \TL{} proposed
1615 by the installer is always under \verb|%SystemDrive%|. The installer
1616 always tests whether the root is writable for the current user.
1617
1618 A problem may arise if the user is not an administrator and \TeX{}
1619 already exists in the search path. Since the effective path
1620 consists of the system path followed by the user path, the new \TL{}
1621 would never get precedence. As a safeguard, the installer creates a
1622 shortcut to the command-prompt in which the new \TL{} binary
1623 directory is prepended to the local search path. The new \TL{} will
1624 be always usable from within such a command-prompt. The shortcut for
1625 \TeX{}works, if installed, also prepends \TL{} to the search path, so it
1626 should also be immune to this path problem.
1627
1628 For Vista there is another twist: even if you are logged in as
1629 administrator, you need to explicitly ask for administrator
1630 privileges. In fact, there is not much point in logging in as
1631 administrator. Instead, right-clicking on the program or shortcut
1632 that you want to run usually gives you a choice `Run as
1633 administrator'.
1634
1635 \section{A user's guide to Web2C}
1636
1637 \Webc{} is an integrated collection of \TeX-related programs: \TeX{}
1638 itself, \MF{}, \MP, \BibTeX{}, etc. It is the heart of \TL{}. The home
1639 page for \Webc{}, with the current manual and more, is
1640 \url{http://tug.org/web2c}.
1641
1642 A bit of history: The original implementation was by Tomas Rokicki who,
1643 in 1987, developed a first \TeX{}-to-C system based on change files
1644 under Unix, which were primarily the original work of Howard Trickey and
1645 Pavel Curtis. Tim Morgan became the maintainer of the system, and
1646 during this period the name changed to Web-to-C\@. In 1990, Karl Berry
1647 took over the work, assisted by dozens of additional contributors, and
1648 in 1997 he handed the baton to Olaf Weber, who returned it to Karl in
1649 2006.
1650
1651 The \Webc{} system runs on Unix, 32-bit Windows systems, \MacOSX{}, and
1652 other operating systems. It uses Knuth's original sources for \TeX{} and
1653 other basic programs written in the \web{} literate programming system
1654 and translates them into C source code. The core \TeX{} programs
1655 handled in this way are:
1656
1657 \begin{cmddescription}
1658 \item[bibtex] Maintaining bibliographies.
1659 \item[dvicopy] Expands virtual font references in \dvi{} files.
1660 \item[dvitomp] \dvi{} to MPX (MetaPost pictures).
1661 \item[dvitype] \dvi{} to human-readable text.
1662 \item[gftodvi] Generic font proofsheets.
1663 \item[gftopk] Generic to packed fonts.
1664 \item[gftype] GF to human-readable text.
1665 \item[mf] Creating typeface families.
1666 \item[mft] Prettyprinting \MF{} source.
1667 \item[mpost] Creating technical diagrams.
1668 \item[patgen] Creating hyphenation patterns.
1669 \item[pktogf] Packed to generic fonts.
1670 \item[pktype] PK to human-readable text.
1671 \item[pltotf] Plain text property list to TFM.
1672 \item[pooltype] Display \web{} pool files.
1673 \item[tangle] \web{} to Pascal.
1674 \item[tex] Typesetting.
1675 \item[tftopl] TFM to plain text property list.
1676 \item[vftovp] Virtual font to virtual property list.
1677 \item[vptovf] Virtual property list to virtual font.
1678 \item[weave] \web{} to \TeX.
1679 \end{cmddescription}
1680
1681 \noindent The precise functions and syntax of these programs are
1682 described in the documentation of the individual packages and of \Webc{}
1683 itself. However, knowing a few principles governing the whole family of
1684 programs will help you take advantage of your \Webc{} installation.
1685
1686 All programs honor these standard \GNU options:
1687 \begin{ttdescription}
1688 \item[-{}-help] print basic usage summary.
1689 \item[-{}-verbose] print detailed progress report.
1690 \item[-{}-version] print version information, then exit.
1691 \end{ttdescription}
1692
1693 For locating files the \Webc{} programs use the path searching library
1694 \KPS{} (\url{http://tug.org/kpathsea}). This library uses a combination
1695 of environment variables and a configuration files to optimize searching
1696 the (huge) collection of \TeX{} files. \Webc{} can look at many
1697 directory trees simultaneously, which is useful in maintaining \TeX's
1698 standard distribution and local and personal extensions in distinct
1699 trees. To speed up file searches, the root of each tree has a file
1700 \file{ls-R}, containing an entry showing the name and relative pathname
1701 for all files under that root.
1702
1703
1704 \subsection{Kpathsea path searching}
1705 \label{sec:kpathsea}
1706
1707 Let us first describe the generic path searching mechanism of the \KPS{}
1708 library.
1709
1710 We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list
1711 of \emph{path elements}, which are basically directory names. A
1712 search path can come from (a combination of) many sources. To look up
1713 a file \samp{my-file} along a path \samp{.:/dir}, \KPS{} checks each
1714 element of the path in turn: first \file{./my-file}, then
1715 \file{/dir/my-file}, returning the first match (or possibly all
1716 matches).
1717
1718 In order to adapt optimally to all operating systems' conventions, on
1719 non-Unix systems \KPS{} can use filename separators different from
1720 colon (\samp{:}) and slash (\samp{/}).
1721
1722 To check a particular path element \var{p}, \KPS{} first checks if a
1723 prebuilt database (see ``Filename data\-base'' on
1724 page~\pageref{sec:filename-database}) applies to \var{p}, i.e., if the
1725 database is in a directory that is a prefix of \var{p}. If so, the path
1726 specification is matched against the contents of the database.
1727
1728 If the database does not exist, or does not apply to this path
1729 element, or contains no matches, the filesystem is searched (if this
1730 was not forbidden by a specification starting with \samp{!!}\ and if
1731 the file being searched for must exist). \KPS{} constructs the list
1732 of directories that correspond to this path element, and then checks
1733 in each for the file being sought.
1734
1735 The ``file must exist'' condition comes into play with \samp{.vf} files and
1736 input files read by \TeX's \cs{openin} command. Such files may not
1737 exist (e.g., \file{cmr10.vf}), and so it would be wrong to search the
1738 disk for them. Therefore, if you fail to update \file{ls-R} when you
1739 install a new \samp{.vf} file, it will never be found.
1740 Each path element is checked in turn: first the database, then the
1741 disk. If a match is found, the search stops and the result is
1742 returned.
1743
1744 Although the simplest and most common path element is a directory
1745 name, \KPS{} supports additional features in search paths: layered
1746 default values, environment variable names, config file values, users'
1747 home directories, and recursive subdirectory searching. Thus, we say
1748 that \KPS{} \emph{expands} a path element, meaning it transforms all
1749 the specifications into basic directory name or names. This is
1750 described in the following sections in the same order as it takes
1751 place.
1752
1753 Note that if the filename being searched for is absolute or explicitly
1754 relative, i.e., starts with \samp{/} or \samp{./} or \samp{../},
1755 \KPS{} simply checks if that file exists.
1756
1757 \ifSingleColumn
1758 \else
1759 \begin{figure*}
1760 \verbatiminput{examples/ex5.tex}
1761 \setlength{\abovecaptionskip}{0pt}
1762 \caption{An illustrative configuration file sample}
1763 \label{fig:config-sample}
1764 \end{figure*}
1765 \fi
1766
1767 \subsubsection{Path sources}
1768 \label{sec:path-sources}
1769
1770 A search path can come from many sources. In the order in which
1771 \KPS{} uses them:
1772
1773 \begin{enumerate}
1774 \item
1775 A user-set environment variable, for instance, \envname{TEXINPUTS}\@.
1776 Environment variables with a period and a program name appended
1777 override; e.g., if \samp{latex} is the name of the program being run,
1778 then \envname{TEXINPUTS.latex} will override \envname{TEXINPUTS}.
1779 \item
1780 A program-specific configuration file, for exam\-ple, a line
1781 \samp{S /a:/b} in \cmdname{dvips}'s \file{config.ps}.
1782 \item A \KPS{} configuration file \file{texmf.cnf}, containing a line like
1783 \samp{TEXINPUTS=/c:/d} (see below).
1784 \item The compile-time default.
1785 \end{enumerate}
1786 \noindent You can see each of these values for a given search path by
1787 using the debugging options (see ``Debugging actions'' on
1788 page~\pageref{sec:debugging}).
1789
1790 \subsubsection{Config files}
1791
1792 \begingroup\tolerance=3500
1793 \KPS{} reads \emph{runtime configuration files} named \file{texmf.cnf}
1794 for search path and other definitions. The search path used to look
1795 for these files is named \envname{TEXMFCNF} (by default such a file lives
1796 in the \file{texmf/web2c} subdirectory). \emph{All}
1797 \file{texmf.cnf} files in the search path will be read and definitions
1798 in earlier files override those in later files. Thus, with a search
1799 path of \verb|.:$TEXMF|, values from \file{./texmf.cnf} override those
1800 from \verb|$TEXMF/texmf.cnf|.
1801 \endgroup
1802
1803 \begin{itemize}
1804 \item
1805 Comments start with \code{\%} and continue to the end of the line.
1806 \item
1807 Blank lines are ignored.
1808 \item
1809 A \bs{} at the end of a line acts as a continuation character,
1810 i.e., the next line is appended. Whitespace at the beginning of
1811 continuation lines is not ignored.
1812 \item
1813 Each remaining line has the form:
1814 \begin{alltt}
1815 \var{variable}[.\var{progname}] [=] \var{value}
1816 \end{alltt}%
1817 where the \samp{=} and surrounding whitespace are optional.
1818 \item
1819 The \ttvar{variable} name may contain any character other
1820 than whitespace, \samp{=}, or \samp{.}, but sticking to
1821 \samp{A-Za-z\_} is safest.
1822 \item
1823 If \samp{.\var{progname}} is present, the definition only
1824 applies if the program that is running is named
1825 \texttt{\var{progname}} or \texttt{\var{progname}.exe}. This allows
1826 different flavors of \TeX{} to have different search paths, for
1827 example.
1828 \item \var{value} may contain any characters except
1829 \code{\%} and \samp{@}. The
1830 \code{\$\var{var}.\var{prog}} feature is not available on the
1831 right-hand side; instead, you must use an additional variable. A
1832 \samp{;}\ in \var{value} is translated to \samp{:}\ if
1833 running under Unix; this is useful to be able to have a single
1834 \file{texmf.cnf} for Unix, \acro{MS-DOS} and Windows systems.
1835 \item
1836 All definitions are read before anything is expanded, so
1837 variables can be referenced before they are defined.
1838 \end{itemize}
1839 A configuration file fragment illustrating most of these points is
1840 \ifSingleColumn
1841 shown below:
1842
1843 \verbatiminput{examples/ex5.tex}
1844 \else
1845 shown in Figure~\ref{fig:config-sample}.
1846 \fi
1847
1848 \subsubsection{Path expansion}
1849 \label{sec:path-expansion}
1850
1851
1852 \KPS{} recognizes certain special characters and constructions in
1853 search paths, similar to those available in Unix shells. As a
1854 general example, the complex path,
1855 \verb+~$USER/{foo,bar}//baz+, expands to all subdirectories under
1856 directories \file{foo} and \file{bar} in \texttt{\$USER}'s home
1857 directory that contain a directory or file \file{baz}. These
1858 expansions are explained in the sections below.
1859 %$
1860 \subsubsection{Default expansion}
1861 \label{sec:default-expansion}
1862
1863 \tolerance=2500
1864 If the highest-priority search path (see ``Path sources'' on
1865 page~\pageref{sec:path-sources}) contains an \emph{extra colon} (i.e.,
1866 leading, trailing, or doubled), \KPS{} inserts at that point the
1867 next-highest-prio\-rity search path that is defined. If that inserted
1868 path has an extra colon, the same happens with the next highest. For
1869 example, given an environment variable setting
1870
1871 \tolerance=1500
1872
1873 \begin{alltt}
1874 > \Ucom{setenv TEXINPUTS /home/karl:}
1875 \end{alltt}
1876 and a \code{TEXINPUTS} value from \file{texmf.cnf} of
1877
1878 \begin{alltt}
1879 .:\$TEXMF//tex
1880 \end{alltt}
1881 then the final value used for searching will be:
1882
1883 \begin{alltt}
1884 /home/karl:.:\$TEXMF//tex
1885 \end{alltt}
1886
1887 Since it would be useless to insert the default value in more than one
1888 place, \KPS{} changes only one extra \samp{:}\ and leaves any others in
1889 place. It checks first for a leading \samp{:}, then a trailing
1890 \samp{:}, then a doubled \samp{:}.
1891
1892 \subsubsection{Brace expansion}
1893
1894 A useful feature is brace expansion, which means that, for instance,
1895 \verb+v{a,b}w+ expands to \verb+vaw:vbw+. Nesting is allowed.
1896 This is used to implement multiple \TeX{} hierarchies, by
1897 assigning a brace list to \code{\$TEXMF}.
1898 For example, in \file{texmf.cnf}, the following definition
1899 (approximately; there are actually even more trees) is made:
1900 \begin{verbatim}
1901 TEXMF = {$TEXMFHOME,$TEXMFLOCAL,!!$TEXMFVAR,!!$TEXMFMAIN}
1902 \end{verbatim}
1903 Using this you can then write something like
1904 \begin{verbatim}
1905 TEXINPUTS = .;$TEXMF/tex//
1906 \end{verbatim}
1907 %$
1908 which means that, after looking in the current directory, the
1909 \code{\$TEXMFHOME/tex}, \code{\$TEXMFLOCAL/tex}, \code{\$TEXMFVAR/tex}
1910 and \code{\$TEXMFMAIN/tex} trees \emph{only}) will be searched (the
1911 last two use using \file{ls-R} data base files). It is a convenient
1912 way for running two parallel \TeX{} structures, one ``frozen'' (on a
1913 \CD, for instance) and the other being continuously updated with new
1914 versions as they become available. By using the \code{\$TEXMF}
1915 variable in all definitions, one is sure to always search the
1916 up-to-date tree first.
1917
1918 \subsubsection{Subdirectory expansion}
1919 \label{sec:subdirectory-expansion}
1920
1921 Two or more consecutive slashes in a path element following a directory
1922 \var{d} is replaced by all subdirectories of \var{d}: first those
1923 subdirectories directly under \var{d}, then the subsubdirectories under
1924 those, and so on. At each level, the order in which the directories are
1925 searched is \emph{unspecified}.
1926
1927 If you specify any filename components after the \samp{//}, only
1928 subdirectories with matching components are included. For example,
1929 \samp{/a//b} expands into directories \file{/a/1/b}, \file{/a/2/b},
1930 \file{/a/1/1/b}, and so on, but not \file{/a/b/c} or \file{/a/1}.
1931
1932 Multiple \samp{//} constructs in a path are possible, but
1933 \samp{//} at the beginning of a path is ignored.
1934
1935 \subsubsection{List of special characters and their meaning: a summary}
1936
1937 The following list summarizes the special characters in \KPS{}
1938 configuration files.
1939
1940 % need a wider space for the item labels here.
1941 \newcommand{\CODE}[1]{\makebox[3em][l]{\code{#1}}}
1942 \begin{ttdescription}
1943 \item[\CODE{:}] Separator in path specification; at the beginning or
1944 the end of a path it substitutes the default path expansion.\par
1945 \item[\CODE{;}] Separator on non-Unix systems (acts like \code{:}).
1946 \item[\CODE{\$}] Variable expansion.
1947 \item[\CODE{\string~}] Represents the user's home directory.
1948 \item[\CODE{\char`\{...\char`\}}] Brace expansion.
1949 \item[\CODE{//}] Subdirectory expansion (can occur anywhere in
1950 a path, except at its beginning).
1951 \item[\CODE{\%}] Start of comment.
1952 \item[\CODE{\bs}] Continuation character (allows multi-line entries).
1953 \item[\CODE{!!}] Search \emph{only} database to locate file, \emph{do
1954 not} search the disk.
1955 \end{ttdescription}
1956
1957
1958 \subsection{Filename databases}
1959 \label{sec:filename-database}
1960
1961 \KPS{} goes to some lengths to minimize disk accesses for searches.
1962 Nevertheless, at installations with enough directories, searching each
1963 possible directory for a given file can take an excessively long time
1964 (this is especially true if many hundreds of font directories have to
1965 be traversed.) Therefore, \KPS{} can use an externally-built plain text
1966 ``database'' file named \file{ls-R} that maps files to directories,
1967 thus avoiding the need to exhaustively search the disk.
1968
1969 A second database file \file{aliases} allows you to give additional
1970 names to the files listed in \file{ls-R}. This can be helpful to
1971 confirm to \acro{DOS} 8.3 filename conventions in source files.
1972
1973 \subsubsection{The filename database}
1974 \label{sec:ls-R}
1975
1976 As explained above, the name of the main filename database must be
1977 \file{ls-R}. You can put one at the root of each \TeX{} hierarchy in
1978 your installation that you wish to be searched (\code{\$TEXMF} by
1979 default). \KPS{} looks for
1980 \file{ls-R} files along the \code{TEXMFDBS} path.
1981
1982 The recommended way to create and maintain \samp{ls-R} is to run the
1983 \code{mktexlsr} script included with the distribution. It is invoked
1984 by the various \samp{mktex}\dots\ scripts. In principle, this script
1985 just runs the command
1986 \begin{alltt}
1987 cd \var{/your/texmf/root} && \path|\|ls -1LAR ./ >ls-R
1988 \end{alltt}
1989 presuming your system's \code{ls} produces the right output format
1990 (\GNU \code{ls} is all right). To ensure that the database is
1991 always up-to-date, it is easiest to rebuild it regularly via
1992 \code{cron}, so that it is automatically updated when the installed
1993 files change, such as after installing or updating a \LaTeX{} package.
1994
1995 If a file is not found in the database, by default \KPS{} goes ahead
1996 and searches the disk. If a particular path element begins with
1997 \samp{!!}, however, \emph{only} the database will be searched for that
1998 element, never the disk.
1999
2000
2001 \subsubsection{kpsewhich: Standalone path searching}
2002 \label{sec:invoking-kpsewhich}
2003
2004 The \texttt{kpsewhich} program exercises path searching independent of any
2005 particular application. This can be useful as a sort of \code{find}
2006 program to locate files in \TeX{} hierarchies (this is used heavily in
2007 the distributed \samp{mktex}\dots\ scripts).
2008
2009 \begin{alltt}
2010 > \Ucom{kpsewhich \var{option}\dots{} \var{filename}\dots{}}
2011 \end{alltt}
2012 The options specified in \ttvar{option} start with either \samp{-}
2013 or \samp{-{}-}, and any unambiguous abbreviation is accepted.
2014
2015 \KPS{} looks up each non-option argument on the command line as a
2016 filename, and returns the first file found. There is no option to
2017 return all the files with a particular name (you can run the Unix
2018 \samp{find} utility for that).
2019
2020 The most common options are described next.
2021
2022 \begin{ttdescription}
2023 \item[\texttt{-{}-dpi=\var{num}}]\mbox{}
2024 Set the resolution to \ttvar{num}; this only affects \samp{gf}
2025 and \samp{pk} lookups. \samp{-D} is a synonym, for compatibility
2026 with \cmdname{dvips}. Default is 600.
2027
2028 \item[\texttt{-{}-format=\var{name}}]\mbox{}\\
2029 Set the format for lookup to \ttvar{name}. By default, the
2030 format is guessed from the filename. For formats which do not have
2031 an associated unambiguous suffix, such as \MP{} support files and
2032 \cmdname{dvips} configuration files, you have to specify the name as
2033 known to \KPS{}, such as \texttt{tex} or \texttt{enc files}. Run
2034 \texttt{kpsewhich -{}-help} for a list.
2035
2036 \item[\texttt{-{}-mode=\var{string}}]\mbox{}\\
2037 Set the mode name to \ttvar{string}; this only affects \samp{gf}
2038 and \samp{pk} lookups. No default: any mode will be found.
2039 \item[\texttt{-{}-must-exist}]\mbox{}\\
2040 Do everything possible to find the files, notably including
2041 searching the disk. By default, only the \file{ls-R} database is
2042 checked, in the interest of efficiency.
2043 \item[\texttt{-{}-path=\var{string}}]\mbox{}\\
2044 Search along the path \ttvar{string} (colon-separated as usual),
2045 instead of guessing the search path from the filename. \samp{//} and
2046 all the usual expansions are supported. The options \samp{-{}-path}
2047 and \samp{-{}-format} are mutually exclusive.
2048 \item[\texttt{-{}-progname=\var{name}}]\mbox{}\\
2049 Set the program name to \texttt{\var{name}}.
2050 This can affect the search paths via the \texttt{.\var{progname}}
2051 feature.
2052 The default is \cmdname{kpsewhich}.
2053 \item[\texttt{-{}-show-path=\var{name}}]\mbox{}\\
2054 shows the path used for file lookups of file type \texttt{\var{name}}.
2055 Either a filename extension (\code{.pk}, \code{.vf}, etc.) or a
2056 name can be used, just as with \samp{-{}-format} option.
2057 \item[\texttt{-{}-debug=\var{num}}]\mbox{}\\
2058 sets the debugging options to \texttt{\var{num}}.
2059 \end{ttdescription}
2060
2061
2062 \subsubsection{Examples of use}
2063 \label{sec:examples-of-use}
2064
2065 Let us now have a look at \KPS{} in action. Here's a straightforward search:
2066
2067 \begin{alltt}
2068 > \Ucom{kpsewhich article.cls}
2069 /usr/local/texmf-dist/tex/latex/base/article.cls
2070 \end{alltt}
2071 We are looking for the file \file{article.cls}. Since the \samp{.cls}
2072 suffix is unambiguous we do not need to specify that we want to look for a
2073 file of type \optname{tex} (\TeX{} source file directories). We find it in
2074 the subdirectory \file{tex/latex/base} below the \samp{texmf-dist} \TL\
2075 directory. Similarly, all of the following are found without problems
2076 thanks to their unambiguous suffix.
2077 \begin{alltt}
2078 > \Ucom{kpsewhich array.sty}
2079 /usr/local/texmf-dist/tex/latex/tools/array.sty
2080 > \Ucom{kpsewhich latin1.def}
2081 /usr/local/texmf-dist/tex/latex/base/latin1.def
2082 > \Ucom{kpsewhich size10.clo}
2083 /usr/local/texmf-dist/tex/latex/base/size10.clo
2084 > \Ucom{kpsewhich small2e.tex}
2085 /usr/local/texmf-dist/tex/latex/base/small2e.tex
2086 > \Ucom{kpsewhich tugboat.bib}
2087 /usr/local/texmf-dist/bibtex/bib/beebe/tugboat.bib
2088 \end{alltt}
2089
2090 By the way, that last is a \BibTeX{} bibliography database for
2091 \textsl{TUGboat} articles.
2092
2093 \begin{alltt}
2094 > \Ucom{kpsewhich cmr10.pk}
2095 \end{alltt}
2096 Font bitmap glyph files of type \file{.pk} are used by display
2097 programs like \cmdname{dvips} and \cmdname{xdvi}. Nothing is returned in
2098 this case since there are no pre-generated Computer Modern \samp{.pk}
2099 files in \TL{}\Dash the Type~1 variants are used by default.
2100 \begin{alltt}
2101 > \Ucom{kpsewhich wsuipa10.pk}
2102 \ifSingleColumn /usr/local/texmf-var/fonts/pk/ljfour/public/wsuipa/wsuipa10.600pk
2103 \else /usr/local/texmf-var/fonts/pk/ljfour/public/
2104 ... wsuipa/wsuipa10.600pk
2105 \fi\end{alltt}
2106 For these fonts (a phonetic alphabet from the University of Washington)
2107 we had to generate \samp{.pk} files, and since the default \MF{} mode on
2108 our installation is \texttt{ljfour} with a base resolution of 600\dpi{}
2109 (dots per inch), this instantiation is returned.
2110 \begin{alltt}
2111 > \Ucom{kpsewhich -dpi=300 wsuipa10.pk}
2112 \end{alltt}
2113 In this case, when specifying that we are interested in a resolution
2114 of 300\dpi{} (\texttt{-dpi=300}) we see that no such font is available on
2115 the system. A program like \cmdname{dvips} or \cmdname{xdvi} would
2116 go off and actually build the required \texttt{.pk} files
2117 using the script \cmdname{mktexpk}.
2118
2119 Next we turn our attention to \cmdname{dvips}'s header and configuration
2120 files. We first look at one of the commonly used files, the general
2121 prologue \file{tex.pro} for \TeX{} support, before turning our attention
2122 to the generic configuration file (\file{config.ps}) and the \PS{} font
2123 map \file{psfonts.map}\Dash as of 2004, map and encoding files have
2124 their own search paths and new location in \dirname{texmf} trees. As
2125 the \samp{.ps} suffix is ambiguous we have to specify explicitly which
2126 type we are considering (\optname{dvips config}) for the file
2127 \texttt{config.ps}.
2128 \begin{alltt}
2129 > \Ucom{kpsewhich tex.pro}
2130 /usr/local/texmf/dvips/base/tex.pro
2131 > \Ucom{kpsewhich --format="dvips config" config.ps}
2132 /usr/local/texmf/dvips/config/config.ps
2133 > \Ucom{kpsewhich psfonts.map}
2134 /usr/local/texmf/fonts/map/dvips/updmap/psfonts.map
2135 \end{alltt}
2136
2137 We now take a closer look at the \acro{URW} Times \PS{} support
2138 files. The prefix for these in the standard font naming scheme is
2139 \samp{utm}. The first file we look at is the configuration file,
2140 which contains the name of the map file:
2141 \begin{alltt}
2142 > \Ucom{kpsewhich --format="dvips config" config.utm}
2143 /usr/local/texmf-dist/dvips/psnfss/config.utm
2144 \end{alltt}
2145 The contents of that file is
2146 \begin{alltt}
2147 p +utm.map
2148 \end{alltt}
2149 which points to the file \file{utm.map}, which we want to
2150 locate next.
2151 \begin{alltt}
2152 > \Ucom{kpsewhich utm.map}
2153 /usr/local/texmf-dist/fonts/map/dvips/times/utm.map
2154 \end{alltt}
2155 This map file defines the file names of the Type~1 \PS{} fonts in
2156 the URW collection. Its contents look like (we only show part of the
2157 lines):
2158 \begin{alltt}
2159 utmb8r NimbusRomNo9L-Medi ... <utmb8a.pfb
2160 utmbi8r NimbusRomNo9L-MediItal... <utmbi8a.pfb
2161 utmr8r NimbusRomNo9L-Regu ... <utmr8a.pfb
2162 utmri8r NimbusRomNo9L-ReguItal... <utmri8a.pfb
2163 utmbo8r NimbusRomNo9L-Medi ... <utmb8a.pfb
2164 utmro8r NimbusRomNo9L-Regu ... <utmr8a.pfb
2165 \end{alltt}
2166 Let us, for instance, take the Times Roman instance
2167 \file{utmr8a.pfb} and find its position in the \file{texmf} directory
2168 tree with a search for Type~1 font files:
2169 \begin{alltt}
2170 > \Ucom{kpsewhich utmr8a.pfb}
2171 \ifSingleColumn /usr/local/texmf-dist/fonts/type1/urw/times/utmr8a.pfb
2172 \else /usr/local/texmf-dist/fonts/type1/
2173 ... urw/utm/utmr8a.pfb
2174 \fi\end{alltt}
2175
2176 It should be evident from these examples how you can easily locate the
2177 whereabouts of a given file. This is especially important if you suspect
2178 that the wrong version of a file is picked up somehow, since
2179 \cmdname{kpsewhich} will show you the first file encountered.
2180
2181 \subsubsection{Debugging actions}
2182 \label{sec:debugging}
2183
2184 Sometimes it is necessary to investigate how a program resolves file
2185 references. To make this practical, \KPS{} offers various levels of
2186 debugging output:
2187
2188 \begin{ttdescription}
2189 \item[\texttt{\ 1}] \texttt{stat} calls (disk lookups). When running
2190 with an up-to-date \file{ls-R} database this should almost give no
2191 output.
2192 \item[\texttt{\ 2}] References to hash tables (such as \file{ls-R}
2193 databases, map files, configuration files).
2194 \item[\texttt{\ 4}] File open and close operations.
2195 \item[\texttt{\ 8}] General path information for file types
2196 searched by \KPS. This is useful to find out where a particular
2197 path for the file was defined.
2198 \item[\texttt{16}] Directory list for each path element (only relevant
2199 for searches on disk).
2200 \item[\texttt{32}] File searches.
2201 \item[\texttt{64}] Variable values.
2202 \end{ttdescription}
2203 A value of \texttt{-1} will set all the above options; in practice,
2204 this is usually the most convenient.
2205
2206 Similarly, with the \cmdname{dvips} program, by setting a combination of
2207 debug switches, one can follow in detail where files are being picked up
2208 from. Alternatively, when a file is not found, the debug trace shows in
2209 which directories the program looks for the given file, so that one can
2210 get an indication what the problem~is.
2211
2212 Generally speaking, as most programs call the \KPS{} library
2213 internally, one can select a debug option by using the
2214 \envname{KPATHSEA\_DEBUG} environment variable, and setting it to (a
2215 combination of) values as described in the above list.
2216
2217 (Note for Windows users: it is not easy to redirect
2218 all messages to a file in this system. For diagnostic purposes
2219 you can temporarily \texttt{SET KPATHSEA\_DEBUG\_OUTPUT=err.log}).
2220
2221 Let us consider, as an example, a small \LaTeX{} source file,
2222 \file{hello-world.tex}, which contains the following input.
2223 \begin{verbatim}
2224 \documentclass{article}
2225 \begin{document}
2226 Hello World!
2227 \end{document}
2228 \end{verbatim}
2229 This little file only uses the font \file{cmr10}, so let us look at
2230 how \cmdname{dvips} prepares the \PS{} file (we want to use the Type~1
2231 version of the Computer Modern fonts, hence the option \texttt{-Pcms}).
2232 \begin{alltt}
2233 > \Ucom{dvips -d4100 hello-world -Pcms -o}
2234 \end{alltt}
2235 In this case we have combined \cmdname{dvips}'s debug class 4 (font
2236 paths) with \KPS's path element expansion (see \cmdname{dvips} Reference
2237 Manual, \OnCD{texmf/doc/dvips/dvips.pdf}).
2238 The output (slightly rearranged) appears in
2239 Figure~\ref{fig:dvipsdbga}.
2240 \begin{figure*}[tp]
2241 \centering
2242 \input{examples/ex6a.tex}
2243 \caption{Finding configuration files}\label{fig:dvipsdbga}
2244
2245 \bigskip
2246
2247 \input{examples/ex6b.tex}
2248 \caption{Finding the prolog file}\label{fig:dvipsdbgb}
2249
2250 \bigskip
2251
2252 \input{examples/ex6c.tex}
2253 \caption{Finding the font file}\label{fig:dvipsdbgc}
2254 \end{figure*}
2255
2256 \cmdname{dvips} starts by locating its working files. First,
2257 \file{texmf.cnf} is found, which gives the definitions of the search
2258 paths for the other files, then the file database \file{ls-R} (to
2259 optimize file searching) and the file \file{aliases}, which makes it
2260 possible to declare several names (e.g., a short \acro{DOS}-like 8.3 and
2261 a more natural longer version) for the same file. Then \cmdname{dvips}
2262 goes on to find the generic configuration file \file{config.ps}
2263 before looking for the customization file \file{.dvipsrc} (which, in
2264 this case is \emph{not found}). Finally, \cmdname{dvips} locates the
2265 config file for the Computer Modern \PS{} fonts \file{config.cms}
2266 (this was initiated with the \texttt{-Pcms} option on the \cmdname{dvips}
2267 command). This file contains the list of the map files which
2268 define the relation between the \TeX{}, \PS{} and file system
2269 names of the fonts.
2270 \begin{alltt}
2271 > \Ucom{more /usr/local/texmf/dvips/cms/config.cms}
2272 p +ams.map
2273 p +cms.map
2274 p +cmbkm.map
2275 p +amsbkm.map
2276 \end{alltt}
2277 \cmdname{dvips} thus goes on to find all these files, plus the generic
2278 map file \file{psfonts.map}, which is always loaded (it contains
2279 declarations for commonly used \PS{} fonts; see the last part of
2280 Section \ref{sec:examples-of-use} for more details about \PS{} map
2281 file handling).
2282
2283 At this point \cmdname{dvips} identifies itself to the user:
2284 \begin{alltt}
2285 This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com)
2286 \end{alltt}
2287 \ifSingleColumn
2288 Then it goes on to look for the prolog file \file{texc.pro}:
2289 \begin{alltt}\small
2290 kdebug:start search(file=texc.pro, must\_exist=0, find\_all=0,
2291 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
2292 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
2293 kdebug:search(texc.pro) => /usr/local/texmf/dvips/base/texc.pro
2294 \end{alltt}
2295 \else
2296 Then it goes on to look for the prolog file \file{texc.pro} (see
2297 Figure~\ref{fig:dvipsdbgb}).
2298 \fi
2299
2300 After having found the file in question, \cmdname{dvips} outputs
2301 the date and time, and informs us that it will generate the
2302 file \file{hello-world.ps}, then that it needs the font file
2303 \file{cmr10}, and that the latter is declared as ``resident'' (no
2304 bitmaps needed):
2305 \begin{alltt}\small
2306 TeX output 1998.02.26:1204' -> hello-world.ps
2307 Defining font () cmr10 at 10.0pt
2308 Font cmr10 <CMR10> is resident.
2309 \end{alltt}
2310 Now the search is on for the file \file{cmr10.tfm}, which is found,
2311 then a few more prolog files (not shown) are referenced, and finally
2312 the Type~1 instance \file{cmr10.pfb} of the font is located and
2313 included in the output file (see last line).
2314 \begin{alltt}\small
2315 kdebug:start search(file=cmr10.tfm, must\_exist=1, find\_all=0,
2316 path=.:~/tex/fonts/tfm//:!!/usr/local/texmf/fonts/tfm//:
2317 /var/tex/fonts/tfm//).
2318 kdebug:search(cmr10.tfm) => /usr/local/texmf/fonts/tfm/public/cm/cmr10.tfm
2319 kdebug:start search(file=texps.pro, must\_exist=0, find\_all=0,
2320 ...
2321 <texps.pro>
2322 kdebug:start search(file=cmr10.pfb, must\_exist=0, find\_all=0,
2323 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
2324 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
2325 kdebug:search(cmr10.pfb) => /usr/local/texmf/fonts/type1/public/cm/cmr10.pfb
2326 <cmr10.pfb>[1]
2327 \end{alltt}
2328
2329 \subsection{Runtime options}
2330
2331 Another useful feature of \Webc{} is its possibility to control a number
2332 of memory parameters (in particular, array sizes) via the runtime file
2333 \file{texmf.cnf} read by \KPS{}. The memory settings can be found in
2334 Part 3 of that file in the \TL{} distribution. The more important
2335 are:
2336
2337 \begin{ttdescription}
2338 \item[\texttt{main\_memory}]
2339 Total words of memory available, for
2340 \TeX{}, \MF{} and \MP. You must make a new format file for each
2341 different setting. For instance, you could generate a ``huge''
2342 version of \TeX{}, and call the format file \texttt{hugetex.fmt}.
2343 Using the standard way of specifying the program name used by \KPS{},
2344 the particular value of the \texttt{main\_memory} variable will then
2345 be read from \file{texmf.cnf}.
2346 \item[\texttt{extra\_mem\_bot}]
2347 Extra space for ``large'' \TeX{} data structures:
2348 boxes, glue, breakpoints, etc. Especially useful if you use
2349 \PiCTeX{}.
2350 \item[\texttt{font\_mem\_size}]
2351 Number of words for font information available for \TeX. This
2352 is more or less the total size of all \acro{TFM} files read.
2353 \item[\texttt{hash\_extra}]
2354 Additional space for the hash table of control sequence names.
2355 Only $\approx$10,000 control sequences can be stored in the main
2356 hash table; if you have a large book with numerous cross-references,
2357 this might not be enough. The default value of
2358 \texttt{hash\_extra} is \texttt{50000}.
2359 \end{ttdescription}
2360
2361 \noindent Of course, this facility is no substitute for truly dynamic
2362 arrays and memory allocation, but since these are extremely difficult to
2363 implement in the present \TeX{} source, these runtime parameters provide
2364 a practical compromise allowing some flexibility.
2365
2366
2367 \begin{comment}
2368 \section{Building on a new Unix platform}
2369
2370 If you have a platform for which executables are not included, you will
2371 need to compile \TeX{} and friends. This is not as hard as it
2372 sounds. What you need is all in the directory \texttt{source} in the
2373 distribution.
2374
2375 \subsection{Prerequisites}
2376
2377 You will need at least 100 megabytes of disk space to compile all of
2378 \TeX{} and its support programs. You'll also need an \acro{ANSI} C
2379 compiler, a \cmdname{make} utility, a lexical scanner, and a parser
2380 generator. We recommend the \GNU version of these programs
2381 (\cmdname{gcc}, \GNU \cmdname{make}, \cmdname{m4}, \cmdname{flex},
2382 \cmdname{bison}). You may be able to work with other C compilers and
2383 \cmdname{make} programs, but you will need a good understanding of
2384 building Unix programs to sort out problems.
2385
2386 Also, the command \texttt{uname} must return a sensible value.
2387
2388
2389 \subsection{Configuration}
2390
2391 To begin, perform a normal installation of \TL{} to your disk (see
2392 section~\ref{sec:install-disk} on
2393 \p.\pageref{sec:install-disk}). You may wish to skip installing
2394 all of the prebuilt binaries.
2395
2396 Then, unpack the source from the compressed \texttt{tar} file in the
2397 directory \dirname{source} to your disk and change directory to where
2398 you placed it.
2399
2400 Next, run \cmdname{configure} with a command line like this:
2401 \begin{alltt}
2402 > \Ucom{sh configure -prefix=/usr/local/TeX}
2403 \end{alltt}
2404
2405 The \optname{-prefix} directory is the one where you installed the
2406 support tree; the directory layout will be as follows (where \$TEXDIR
2407 stands for the directory you chose):
2408
2409 \noindent
2410 \begin{tabular}{>{\ttfamily}ll@{}}
2411 \dirname{$TEXDIR/share/texmf} & main tree with fonts,\\
2412 & \qquad macros, etc\\
2413 \dirname{$TEXDIR/man} & Unix manual pages\\
2414 \dirname{$TEXDIR/info} & \GNU style Info manuals\\
2415 \dirname{$TEXDIR/bin/$PLATFORM} & binaries\\
2416 \end{tabular}
2417 %$
2418
2419 If you want to leave out the \dirname{$PLATFORM} directory level,
2420 i.e., put the binaries directly into \dirname{$TEXDIR/bin}, specify
2421 the \verb|--disable-multiplatform| option to \cmdname{configure}.
2422
2423 Have a look at the output of \verb|./configure --help| for more
2424 options you can use. For example, you can skip building of \OMEGA{} and
2425 \eTeX{}.
2426
2427
2428 \subsection{Running \cmdname{make}}
2429
2430 Make sure the shell variable or option \texttt{noclobber} is not set.
2431 Then, run the main \cmdname{make} like this:
2432 \begin{alltt}
2433 > \Ucom{make world}
2434 \end{alltt}
2435 and relax\ldots
2436
2437 Alternatively, you want to log all the output, as in:
2438 \begin{alltt}
2439 > \Ucom{sh -c "make world >world.log 2>\&1" \&}
2440 \end{alltt}
2441
2442 Before you believe that everything went ok, please check the log file
2443 for errors: \GNU \cmdname{make} always uses the string \samp{***}
2444 whenever a command fails. Also, check if all the programs were built:
2445
2446 \begin{alltt}
2447 > \Ucom{cd \var{TEXDIR}/bin/\var{archname}}
2448 > \Ucom{ls | wc}
2449 \end{alltt}
2450 The result should be over 200 (you can check the exact number with the
2451 \dirname{bin} directory contents in the distribution).
2452
2453 If you need special privileges for \texttt{make install}, you can
2454 separate the \samp{make world} into two different runs, like this:
2455 \begin{alltt}
2456 > \Ucom{make all}
2457 > \Ucom{su}
2458 > \Ucom{make install strip}
2459 \end{alltt}
2460
2461 After you've installed your new binaries, you should follow the normal
2462 post-installation procedures, given in section~\ref{sec:postinstall}
2463 (\p.\pageref{sec:postinstall}).
2464
2465 Also, if you'd like to make your binaries available to others, please
2466 contact us. We'll be happy to put them on the \TL\ web pages.
2467 \end{comment}
2468
2469 \htmlanchor{ack}
2470 \section{Acknowledgements}
2471
2472 \TL{} is a joint effort by virtually all of the \TeX{} user groups.
2473 This edition of \TL{} was overseen by Karl Berry. The other principal
2474 contributors, past and present, are listed below.
2475
2476 \begin{itemize*}
2477
2478 \item The English, German, Dutch, and Polish \TeX{} user groups
2479 (\acro{TUG}, \acro{DANTE} e.V., \acro{NTG}, and \acro{GUST},
2480 respectively), which provide the necessary technical and administrative
2481 infrastructure. Please join the \TeX\ user group near you! (See
2482 \url{http://tug.org/usergroups.html}.)
2483
2484 \item The \acro{CTAN} team, notably Robin Fairbairns, Jim Hef{}feron,
2485 and Rainer Sch\"opf, which distributes the \TL{} images and provides the
2486 common infrastructure for package updates, upon which \TL{} depends.
2487
2488 \item Nelson Beebe, for making many platforms available to \TL\
2489 developers, and his own comprehensive testing.
2490
2491 \item John Bowman, for making many changes to his advanced graphics
2492 program Asymptote to make it work in \TL.
2493
2494 \item Peter Breitenlohner and the \eTeX\ team for the stable foundation
2495 of future \TeX's, and Peter specifically for stellar help with \GNU\
2496 autotools usage throughout \TL.
2497
2498 \item Jin-Hwan Cho and all of the DVIPDFM$x$ team, for their
2499 excellent driver and responsiveness to configuration issues.
2500
2501 \item Thomas Esser, without whose marvelous \teTeX{} package \TL{}
2502 would have never existed.
2503
2504 \item Michel Goossens, who co-authored the original documentation.
2505
2506 \item Eitan Gurari, whose \TeX4ht was used to create the \HTML{}
2507 version of this documentation, and who worked tirelessly to improve
2508 it at short notice. Eitan prematurely passed away in June 2009, and we
2509 dedicate this documentation to his memory.
2510
2511 \item Hans Hagen, for much testing and making his \ConTeXt\ format
2512 (\url{http://pragma-ade.com}) work within \TL's framework.
2513
2514 \item \Thanh, Martin Schr\"oder, and the pdf\TeX\ team
2515 (\url{http://pdftex.org}) for continuing enhancements of \TeX's
2516 abilities.
2517
2518 \item Hartmut Henkel, for significant development contributions to
2519 pdf\TeX\, Lua\TeX, and more.
2520
2521 \item Taco Hoekwater, for major renewed development efforts on MetaPost and
2522 (Lua)\TeX\ (\url{http://luatex.org}) itself, incorporating
2523 \ConTeXt\ into \TL, giving Kpathsea multi-threaded functionality, and
2524 much more.
2525
2526 \item Pawe{\l} Jackowski, for the Windows installer \cmdname{tlpm},
2527 and Tomasz {\L}uczak, for \cmdname{tlpmgui}, used in past releases.
2528
2529 \item Akira Kakuto, for providing the Windows
2530 binaries from his \acro{W32TEX} distribution for Japanese \TeX\
2531 (\url{http://w32tex.org}), and many other development contributions.
2532
2533 \item Jonathan Kew, for developing the remarkable \XeTeX{} engine and
2534 taking the time and trouble to integrate it in \TL{}, as well as the
2535 initial version of the Mac\TeX\ installer, and also for our recommended
2536 front-end \TeX{}works.
2537
2538 \item Dick Koch, for maintaining Mac\TeX\ (\url{http://tug.org/mactex})
2539 in very close tandem with \TL{}, and for his great good cheer in doing
2540 so.
2541
2542 \item Reinhard Kotucha, for major contributions to the \TL{} 2008
2543 infrastructure and installer, as well as Windows research efforts, the
2544 \texttt{getnonfreefonts} script, and more.
2545
2546 \item Siep Kroonenberg, also for major contributions to the \TL{} 2008
2547 infrastructure and installer, especially on Windows, and for the bulk of
2548 work updating this manual describing those features.
2549
2550 \item Heiko Oberdiek, for the \pkgname{epstopdf} package and many
2551 others, compressing the huge \pkgname{pst-geo} data files so we could
2552 include them, and most of all, for his remarkable work on
2553 \pkgname{hyperref}.
2554
2555 \item Petr Ol\v{s}ak, who coordinated and checked all the Czech and Slovak
2556 material very carefully.
2557
2558 \item Toshio Oshima, for his \cmdname{dviout} previewer for Windows.
2559
2560 \item Manuel P\'egouri\'e-Gonnard, for helping with package updates,
2561 documentation improvements, and \cmdname{texdoc} development.
2562
2563 \item Fabrice Popineau, for the original Windows support in \TL{} and
2564 work on the French documentation.
2565
2566 \item Norbert Preining, the principal architect of the \TL{} 2008
2567 infrastructure and installer, and also for coordinating the Debian
2568 version of \TL{} (together with Frank K\"uster), making many suggestions
2569 along the way.
2570
2571 \item Sebastian Rahtz, for originally creating \TL{} and maintaining it
2572 for many years.
2573
2574 \item Phil Taylor, for setting up the BitTorrent downloads.
2575
2576 \item Tomasz Trzeciak, for wide-ranging help with Windows.
2577
2578 \item Vladimir Volovich, for substantial help with porting and other
2579 maintenance issues, and especially for making it feasible to include
2580 \cmdname{xindy}.
2581
2582 \item Staszek Wawrykiewicz, the principal tester for all of \TL{},
2583 and coordinator of the many major Polish contributions: fonts, Windows
2584 installation, and more.
2585
2586 \item Olaf Weber, for his patient maintenance of \Webc.
2587
2588 \item Gerben Wierda, for creating and maintaining the original \MacOSX\
2589 support, and much integration and testing.
2590
2591 \item Graham Williams, on whose work the \TeX\ Catalogue of packages depends.
2592
2593 \end{itemize*}
2594
2595 Builders of the binaries:
2596 Peter Breitenlohner (\pkgname{x86\_64-linux}),
2597 %Tim Arnold (\pkgname{hppa-hpux}),
2598 %Randy Au (\pkgname{amd64-freebsd}),
2599 %Edd Barrett (\pkgname{i386-openbsd}),
2600 Karl Berry (\pkgname{i386-linux}, \pkgname{sparc-linux}),
2601 Ken Brown (\pkgname{i386-cygwin}),
2602 Akira Kakuto (\pkgname{win32}),
2603 Dick Koch (\pkgname{universal-darwin}),
2604 %Manfred Lotz (\pkgname{i386-freebsd}),
2605 Norbert Preining (\pkgname{alpha-linux}),
2606 %Arthur Reutenauer (\pkgname{sparc-linux}),
2607 Jukka Salmi (\pkgname{i386-netbsd}),
2608 Thomas Schmitz (\pkgname{powerpc-linux}),
2609 Apostolos Syropoulos (\pkgname{i386-solaris}),
2610 Vladimir Volovich (\pkgname{powerpc-aix}, \pkgname{sparc-solaris}),
2611 Olaf Weber (\pkgname{mips-irix}).
2612 For information on the \TL{} build process, see
2613 \url{http://tug.org/texlive/build.html}.
2614
2615 Current documentation translators:
2616 Jjgod Jiang, Jinsong Zhao, Yue Wang, \& Helin Gai (Chinese),
2617 Klaus H\"oppner (German),
2618 Manuel P\'egouri\'e-Gonnard (French),
2619 Petr Sojka \& Jan Busa (Czech\slash Slovak),
2620 Boris Veytsman (Russian),
2621 Staszek Wawrykiewicz (Polish). The \TL{} documentation web page
2622 is \url{http://tug.org/texlive/doc.html}.
2623
2624 Of course the most important acknowledgement must go to Donald Knuth,
2625 first for inventing \TeX, and then for giving it to the world.
2626
2627
2628
2629 \section{Release history}
2630 \label{sec:history}
2631
2632 \subsection{Past}
2633
2634 Discussion began in late 1993 when the Dutch \TeX{} Users Group was
2635 starting work on its 4All\TeX{} \CD{} for \acro{MS-DOS} users, and it
2636 was hoped at that time to issue a single, rational, \CD{} for all
2637 systems. This was too ambitious a target for the time, but it did spawn
2638 not only the very successful 4All\TeX{} \CD{}, but also the \acro{TUG}
2639 Technical Council working group on a \emph{\TeX{} Directory Structure}
2640 (\url{http://tug.org/tds}), which specified how to create consistent and
2641 manageable collections of \TeX{} support files. A complete draft of the
2642 \TDS{} was published in the December 1995 issue of \textsl{TUGboat}, and
2643 it was clear from an early stage that one desirable product would be a
2644 model structure on \CD{}. The distribution you now have is a very direct
2645 result of the working group's deliberations. It was also clear that the
2646 success of the 4All\TeX{} \CD{} showed that Unix users would benefit
2647 from a similarly easy system, and this is the other main strand of
2648 \TL.
2649
2650 We first undertook to make a new Unix-based \TDS{} \CD{} in the autumn
2651 of 1995, and quickly identified Thomas Esser's \teTeX{} as the ideal
2652 setup, as it already had multi-platform support and was built with
2653 portability across file systems in mind. Thomas agreed to help, and work
2654 began seriously at the start of 1996. The first edition was released in
2655 May 1996. At the start of 1997, Karl Berry completed a major new release
2656 of Web2c, which included nearly all the features which Thomas Esser had
2657 added in \teTeX, and we decided to base the 2nd edition of the \CD{} on
2658 the standard \Webc, with the addition of \teTeX's \texttt{texconfig}
2659 script. The 3rd edition of the \CD{} was based on a major revision of
2660 \Webc, 7.2, by Olaf Weber; at the same time, a new revision of \teTeX
2661 was being made, and \TL{} included almost all of its features. The
2662 4th edition followed the same pattern, using a new version of \teTeX,
2663 and a new release of \Webc{} (7.3). The system now included a complete
2664 Windows setup.
2665
2666 For the 5th edition (March 2000) many parts of the \CD{} were revised
2667 and checked, updating hundreds of packages. Package details were stored
2668 in XML files. But the major change for \TeX\ Live 5 was that all
2669 non-free software was removed. Everything in \TL{} is now intended
2670 to be compatible with the Debian Free Software Guidelines
2671 (\url{http://www.debian.org/intro/free}); we have done our best to check
2672 the license conditions of all packages, but we would very much
2673 appreciate hearing of any mistakes.
2674
2675 The 6th edition (July 2001) had much more material updated. The major
2676 change was a new install concept: the user could select a more exact set
2677 of needed collections. Language-related collections were completely
2678 reorganized, so selecting any of them installs not only macros, fonts,
2679 etc., but also prepares an appropriate \texttt{language.dat}.
2680
2681 The 7th edition of 2002 had the notable addition of \MacOSX{} support,
2682 and the usual myriad of updates to all sorts of packages and
2683 programs. An important goal was integration of the source back with
2684 \teTeX, to correct the drift apart in versions~5 and~6.
2685
2686 \subsubsection{2003}
2687
2688 In 2003, with the continuing flood of updates and additions, we found
2689 that \TL{} had grown so large it could no longer be contained on a
2690 single \CD, so we split it into three different distributions (see
2691 section~\ref{sec:tl-coll-dists}, \p.\pageref{sec:tl-coll-dists}). In
2692 addition:
2693
2694 \begin{itemize*}
2695 \item At the request of the \LaTeX{} team, we changed the standard
2696 \cmdname{latex} and \cmdname{pdflatex} commands to now use \eTeX{} (see
2697 \p.\pageref{text:etex}).
2698 \item The new Latin Modern fonts were included (and are recommended).
2699 \item Support for Alpha \acro{OSF} was removed
2700 (\acro{HPUX} support was removed previously), since no one had (or
2701 volunteered) hardware available on which to compile new binaries.
2702 \item Windows setup was substantially changed; for the first time
2703 an integrated environment based on XEmacs was introduced.
2704 \item Important supplementary programs for Windows
2705 (Perl, Ghost\-script, Image\-Magick, Ispell) are now installed
2706 in the \TL{} installation directory.
2707 \item Font map files used by \cmdname{dvips}, \cmdname{dvipdfm}
2708 and \cmdname{pdftex} are now generated by the new program
2709 \cmdname{updmap} and installed into \dirname{texmf/fonts/map}.
2710 \item \TeX{}, \MF{}, and \MP{} now, by default, output most input
2711 characters (32 and above) as themselves in output (e.g.,
2712 \verb|\write|) files,
2713 log files, and the terminal, i.e., \emph{not} translated using the
2714 \verb|^^| notation. In \TL{}~7, this translation was
2715 dependent on the system locale settings; now, locale settings do
2716 not influence the \TeX{} programs' behavior. If for some reason
2717 you need the \verb|^^| output, rename the file
2718 \verb|texmf/web2c/cp8bit.tcx|. (Future releases will have cleaner
2719 ways to control this.)
2720 \item This documentation was substantially revised.
2721 \item Finally, since the edition numbers had grown unwieldy,
2722 the version is now simply identified by the year: \TL{} 2003.
2723 \end{itemize*}
2724
2725
2726 \subsubsection{2004}
2727
2728 2004 saw many changes:
2729
2730 \begin{itemize}
2731
2732 \item If you have locally-installed fonts which use their own
2733 \filename{.map} or (much less likely) \filename{.enc} support files, you
2734 may need to move those support files.
2735
2736 \filename{.map} files are now searched for in subdirectories of
2737 \dirname{fonts/map} only (in each \filename{texmf} tree), along the
2738 \envname{TEXFONTMAPS} path. Similarly, \filename{.enc} files are now
2739 searched for in subdirectories of \dirname{fonts/enc} only, along the
2740 \envname{ENCFONTS} path. \cmdname{updmap} will attempt to warn about
2741 problematic files.
2742
2743 For methods of handling this and other information, please see
2744 \url{http://tug.org/texlive/mapenc.html}.
2745
2746 \item The \TK\ has been expanded with the addition of a \MIKTEX-based
2747 installable \CD, for those who prefer that implementation to Web2C.
2748 See section~\ref{sec:overview-tl} (\p.\pageref{sec:overview-tl}).
2749
2750 \item Within \TL, the single large \dirname{texmf} tree of previous
2751 releases has been replaced by three: \dirname{texmf},
2752 \dirname{texmf-dist}, and \dirname{texmf-doc}. See
2753 section~\ref{sec:tld} (\p.\pageref{sec:tld}), and the \filename{README}
2754 files for each.
2755
2756 \item All \TeX-related input files are now collected in
2757 the \dirname{tex} subdirectory of \dirname{texmf*} trees, rather than
2758 having separate sibling directories \dirname{tex}, \dirname{etex},
2759 \dirname{pdftex}, \dirname{pdfetex}, etc. See
2760 \CDref{texmf-dist/doc/generic/tds/tds.html\#Extensions}
2761 {\texttt{texmf-dist/doc/generic/tds/tds.html\#Extensions}}.
2762
2763 \item Helper scripts (not meant to be invoked by users) are now located
2764 in a new \dirname{scripts} subdirectory of \dirname{texmf*} trees, and
2765 can be searched for via \verb|kpsewhich -format=texmfscripts|. So if you have
2766 programs which call such scripts, they'll need to be adjusted. See
2767 \CDref{texmf-dist/doc/generic/tds/tds.html\#Scripts}
2768 {\texttt{texmf-dist/doc/generic/tds/tds.html\#Scripts}}.
2769
2770 \item Almost all formats leave most characters printable as
2771 themselves via the ``translation file'' \filename{cp227.tcx}, instead of
2772 translating them with the \verb|^^| notation. Specifically, characters
2773 at positions 32--256, plus tab, vertical tab, and form feed are
2774 considered printable and not translated. The exceptions are plain \TeX\
2775 (only 32--126 printable), \ConTeXt\ (0--255 printable), and the
2776 \OMEGA-related formats. This default behavior is almost the same as in
2777 \TL\,2003, but it's implemented more cleanly, with more possibilities
2778 for customization. See \CDref{texmf/doc/web2c/web2c.html\#TCX-files}
2779 {\texttt{texmf/doc/web2c/web2c.html\#TCX-files}}.
2780 (By the way, with Unicode input, \TeX\ may output partial character
2781 sequences when showing error contexts, since it is byte-oriented.)
2782
2783 \item \textsf{pdfetex} is now the default engine for all formats
2784 except (plain) \textsf{tex} itself. (Of course it generates \acro{DVI}
2785 when run as \textsf{latex}, etc.) This means, among other things, that
2786 the microtypographic features of \textsf{pdftex} are available in
2787 \LaTeX, \ConTeXt, etc., as well as the \eTeX\ features
2788 (\OnCD{texmf-dist/doc/etex/base/}).
2789
2790 It also means it's \emph{more important than ever} to use the
2791 \pkgname{ifpdf} package (works with both plain and \LaTeX) or equivalent
2792 code, because simply testing whether \cs{pdfoutput} or some other
2793 primitive is defined is not a reliable way to determine if \acro{PDF}
2794 output is being generated. We made this backward compatible as best we
2795 could this year, but next year, \cs{pdfoutput} may be defined even when
2796 \acro{DVI} is being written.
2797
2798 \item pdf\TeX\ (\url{http://pdftex.org}) has many new features:
2799
2800 \begin{itemize*}
2801
2802 \item \cs{pdfmapfile} and \cs{pdfmapline} provide font map support
2803 from within a document.
2804
2805 \item Microtypographic font expansion can be used more easily.\\
2806 \url{http://www.ntg.nl/pipermail/ntg-pdftex/2004-May/000504.html}
2807
2808 \item All parameters previously set through the special configuration
2809 file \filename{pdftex.cfg} must now be set through primitives,
2810 typically in \filename{pdftexconfig.tex}; \filename{pdftex.cfg} is no
2811 longer supported. Any extant \filename{.fmt} files must be redumped
2812 when \filename{pdftexconfig.tex} is changed.
2813
2814 \item See the pdf\TeX\ manual for more: \OnCD{texmf-dist/doc/pdftex/manual/pdftex-a.pdf}.
2815
2816 \end{itemize*}
2817
2818 \item The \cs{input} primitive in \cmdname{tex} (and \cmdname{mf} and
2819 \cmdname{mpost}) now accepts double quotes containing spaces and other
2820 special characters. Typical examples:
2821 \begin{verbatim}
2822 \input "filename with spaces" % plain
2823 \input{"filename with spaces"} % latex
2824 \end{verbatim}
2825 See the Web2C manual for more: \OnCD{texmf/doc/web2c}.
2826
2827 \item enc\TeX\ support is now included within Web2C and consequently all
2828 \TeX\ programs, via the \optname{-enc} option\Dash \emph{only when
2829 formats are built}. enc\TeX\ supports general re-encoding of input and
2830 output, enabling full support of Unicode (in \acro{UTF}-8). See
2831 \OnCD{texmf-dist/doc/generic/enctex/} and
2832 \url{http://www.olsak.net/enctex.html}.
2833
2834 \item Aleph, a new engine combining \eTeX\ and \OMEGA, is available.
2835 A little information is available in \OnCD{texmf-dist/doc/aleph/base}
2836 and \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=aleph}. The
2837 \LaTeX-based format for Aleph is named \textsf{lamed}.
2838
2839 \item The latest \LaTeX\ release has a new version of the
2840 \acro{LPPL}\Dash now officially a Debian-approved license. Assorted
2841 other updates, see the \filename{ltnews} files in
2842 \OnCD{texmf-dist/doc/latex/base}.
2843
2844 \item \cmdname{dvipng}, a new program for converting \acro{DVI} to
2845 \acro{PNG} image files, is included. See \OnCD{texmf/doc/man/man1/dvipng.1}.
2846
2847 \item We reduced the \pkgname{cbgreek} package to a ``medium'' sized set
2848 of fonts, with the assent and advice of the author (Claudio Beccari).
2849 The excised fonts are the invisible, outline, and transparency ones,
2850 which are relatively rarely used, and we needed the space. The full set
2851 is of course available from \acro{CTAN}
2852 (\url{http://www.ctan.org/tex-archive/fonts/greek/cb}).
2853
2854 \item \cmdname{oxdvi} has been removed; just use \cmdname{xdvi}.
2855
2856 \item The \cmdname{ini} and \cmdname{vir} commands (links) for
2857 \cmdname{tex}, \cmdname{mf}, and \cmdname{mpost} are no longer created,
2858 such as \cmdname{initex}. The \cmdname{ini} functionality has been
2859 available through the command-line option \optname{-ini} for years now.
2860
2861 \item \textsf{i386-openbsd} platform support was removed. Since the
2862 \pkgname{tetex} package in the \acro{BSD} Ports system is available, and
2863 \acro{GNU/}Linux and Free\acro{BSD} binaries were available, it seemed
2864 volunteer time could be better spent elsewhere.
2865
2866 \item On \textsf{sparc-solaris} (at least), you may have to set the
2867 \envname{LD\_LIBRARY\_PATH} environment variable to run the
2868 \pkgname{t1utils} programs. This is because they are compiled with C++,
2869 and there is no standard location for the runtime libraries. (This is
2870 not new in 2004, but wasn't previously documented.) Similarly, on
2871 \textsf{mips-irix}, the \acro{MIPS}pro 7.4 runtimes are required.
2872
2873 \end{itemize}
2874
2875 \subsubsection{2005}
2876
2877 2005 saw the usual huge number of updates to packages and programs.
2878 The infrastructure stayed relatively stable from 2004, but inevitably
2879 there were some changes there as well:
2880
2881 \begin{itemize}
2882
2883 \item New scripts \cmdname{texconfig-sys}, \cmdname{updmap-sys}, and
2884 \cmdname{fmtutil-sys} were introduced, which modify the
2885 configuration in the system trees. The \cmdname{texconfig},
2886 \cmdname{updmap}, and \cmdname{fmtutil} scripts now modify
2887 user-specific files, under \dirname{$HOME/.texlive2005}.
2888
2889 \item Corresponding new variables \envname{TEXMFCONFIG} and
2890 \envname{TEXMFSYSCONFIG} to specify the trees where configuration
2891 files (user or system, respectively) are found. Thus, you may
2892 need to move personal versions of \filename{fmtutil.cnf} and
2893 \filename{updmap.cfg} to these places; another option is to
2894 redefine \envname{TEXMFCONFIG} or \envname{TEXMFSYSCONFIG} in
2895 \filename{texmf.cnf}. In any case the real location of these files
2896 and the values of \envname{TEXMFCONFIG} and \envname{TEXMFSYSCONFIG}
2897 must agree.
2898 See section~\ref{sec:texmftrees}, \p.\pageref{sec:texmftrees}.
2899
2900 \item Last year, we kept \verb|\pdfoutput| and other primitives undefined
2901 for \dvi\ output, even though the \cmdname{pdfetex} program was
2902 being used. This year, as promised, we undid that compatibility
2903 measure. So if your document uses \verb|\ifx\pdfoutput\undefined|
2904 to test if PDF is being output, it will need to be changed. You
2905 can use the package \pkgname{ifpdf.sty} (which works under both
2906 plain \TeX\ and \LaTeX) to do this, or steal its logic.
2907
2908 \item Last year, we changed most formats to output (8-bit) characters as
2909 themselves (see previous section). The new TCX file
2910 \filename{empty.tcx} now provides an easier way to get the
2911 original \verb|^^| notation if you so desire, as in:
2912 \begin{verbatim}
2913 latex --translate-file=empty.tcx yourfile.tex
2914 \end{verbatim}
2915
2916 \item The new program \cmdname{dvipdfmx} is included for translation of
2917 DVI to PDF; this is an actively maintained update of
2918 \cmdname{dvipdfm} (which is also still available for now, though
2919 no longer recommended).
2920
2921 \item The new programs \cmdname{pdfopen} and \cmdname{pdfclose} are included
2922 to allow reloading of pdf files in the Adobe Acrobat Reader without
2923 restarting the program. (Other pdf readers, notably \cmdname{xpdf},
2924 \cmdname{gv}, and \cmdname{gsview}, have never suffered from this
2925 problem.)
2926
2927 \item For consistency, the variables \envname{HOMETEXMF} and
2928 \envname{VARTEXMF} have been renamed to \envname{TEXMFHOME} and
2929 \envname{TEXMFSYSVAR}, respectively. There is also
2930 \envname{TEXMFVAR}, which is by default user-specific. See the
2931 first point above.
2932
2933 \end{itemize}
2934
2935
2936 \subsubsection{2006--2007}
2937
2938 In 2006--2007, the major new addition to \TL{} was the \XeTeX{} program,
2939 available as the \texttt{xetex} and \texttt{xelatex} programs; see
2940 \url{http://scripts.sil.org/xetex}.
2941
2942 MetaPost also received a notable update, with more planned for the
2943 future (\url{http://tug.org/metapost/articles}), likewise pdf\TeX{}
2944 (\url{http://tug.org/applications/pdftex}).
2945
2946 The \TeX\ \filename{.fmt} (high-speed format) and the similar files for
2947 MetaPost and \MF\ are now stored in subdirectories of \dirname{texmf/web2c},
2948 instead of in the directory itself (although the directory is still
2949 searched, for the sake of existing \filename{.fmt}'s). The
2950 subdirectories are named for the `engine' in use, such as \filename{tex}
2951 or \filename{pdftex} or \filename{xetex}. This change should be
2952 invisible in normal use.
2953
2954 The (plain) \texttt{tex} program no longer reads \texttt{\%\&} first
2955 lines to determine what format to run; it is the pure Knuthian \TeX.
2956 (\LaTeX\ and everything else do still read \texttt{\%\&} lines).
2957
2958 Of course the year also saw (the usual) hundreds of other updates to
2959 packages and programs. As usual, please check \acro{CTAN}
2960 (\url{http://www.ctan.org}) for updates.
2961
2962 Internally, the source tree is now stored in Subversion, with a standard
2963 web interface for viewing the tree, as linked from our home page.
2964 Although not visible in the final distribution, we expect this will
2965 provide a stable development foundation for future years.
2966
2967 Finally, in May 2006 Thomas Esser announced that he would no longer be
2968 updating te\TeX{} (\url{http://tug.org/tetex}). As a result, there was
2969 been a surge of interest in \TL{}, especially among \GNU/Linux
2970 distributors. (There is a new \texttt{tetex} installation scheme in
2971 \TL{}, which provides an approximate equivalent.) We hope this will
2972 eventually translate to improvements in the \TeX\ environment for
2973 everyone.
2974
2975 \subsubsection{2008}
2976
2977 In 2008, the entire \TL{} infrastructure was redesigned and
2978 reimplemented. Complete information about an installation is now stored
2979 in a plain text file \filename{tlpkg/texlive.tlpdb}.
2980
2981 Among other things, this finally makes possible upgrading a \TL{}
2982 installation over the Internet after the initial installation, a feature
2983 MiK\TeX\ has provided for many years. We expect to regularly update new
2984 packages as they are released to \CTAN.
2985
2986 The major new engine Lua\TeX\ (\url{http://luatex.org}) is included;
2987 besides a new level of flexibility in typesetting, this provides an
2988 excellent scripting language for use both inside and outside of \TeX\
2989 documents.
2990
2991 Support among Windows and the Unix-based platforms is now much more
2992 uniform. In particular, most Perl and Lua scripts are now available on
2993 Windows, using the Perl internally distributed with \TL.
2994
2995 The new \cmdname{tlmgr} script (section~\ref{sec:tlmgr}) is the
2996 general interface for managing \TL{} after the initial installation.
2997 It handles package updates and consequent regeneration of formats, map
2998 files, and language files, optionally including local additions.
2999
3000 With the advent of \cmdname{tlmgr}, the \cmdname{texconfig} actions to
3001 edit the format and hyphenation configuration files are now disabled.
3002
3003 The \cmdname{xindy} indexing program
3004 (\url{http://xindy.sourceforge.net/}) is now included on most platforms.
3005
3006 The \cmdname{kpsewhich} tool can now report all matches for a given file
3007 (option \optname{--all}) and limit matches to a given subdirectory
3008 (option \optname{--subdir}).
3009
3010 The \cmdname{dvipdfmx} program now includes functionality to extract
3011 bounding box information, via the command name \cmdname{extractbb}; this
3012 was one of the last features provided by \cmdname{dvipdfm} not in
3013 \cmdname{dvipdfmx}.
3014
3015 The font aliases \filename{Times-Roman}, \filename{Helvetica}, and so on
3016 have been removed. Different packages expected them to behave
3017 differently (in particular, to have different encodings), and there was
3018 no good way to resolve this.
3019
3020 The \pkgname{platex} format has been removed, to resolve a name conflict
3021 with a completely different Japanese \pkgname{platex}; the
3022 \pkgname{polski} package is now the main Polish support.
3023
3024 Internally, the \web\ string pool files are now compiled into the
3025 binaries, to ease upgrades.
3026
3027 Finally, the changes made by Donald Knuth in his `\TeX\ tuneup of 2008'
3028 are included in this release. See
3029 \url{http://tug.org/TUGboat/Articles/tb29-2/tb92knut.pdf}.
3030
3031
3032 %
3033 \htmlanchor{news}
3034 \subsection{Present}
3035 \label{sec:tlcurrent}
3036 \label{sec:2009news} % keep with 2009
3037
3038 \begin{comment} % last-minute disablement
3039 In 2009, the most visible change is that pdf\AllTeX\ now
3040 \emph{automatically} converts a requested Encapsulated PostScript (EPS)
3041 file to PDF, via the \pkgname{epstopdf} package, when and if the \LaTeX\
3042 \code{graphics.cfg} configuration file is loaded, and PDF is being
3043 output. The default options are intended to eliminate any chance of
3044 hand-created PDF files being overwritten, but you can also prevent
3045 \code{epstopdf} from being loaded at all by putting
3046 |\newcommand{\DoNotLoadEpstopdf}{}| (or |\def...|) before the
3047 \cs{documentclass} declaration. For details, see the epstopdf package
3048 documentation (\url{http://ctan.org/pkg/epstopdf-pkg}).
3049
3050 A related important change is that execution of a few external commands,
3051 via the \cs{write18} feature, is now enabled by default\Dash for
3052 example, \code{epstopdf}, \code{makeindex}, and \code{bibtex}. The
3053 exact list of commands is defined in the \code{texmf.cnf} file.
3054 Environments which must disallow all such external commands can deselect
3055 this option in the installer (see section~\ref{sec:options}), or
3056 override the value in \code{texmf.cnf} after installation.
3057 \end{comment}
3058
3059 In 2009, the default output format for Lua\AllTeX\ is now PDF, to take
3060 advantage of Lua\TeX's OpenType support, et al. New executables named
3061 \code{dviluatex} and \code{dvilualatex} run Lua\TeX\ with DVI output.
3062 The Lua\TeX\ home page is \url{http://luatex.org}.
3063
3064 The original Omega engine and Lambda format have been excised, after
3065 discussions with the Omega authors. The updated Aleph and Lamed remain,
3066 as do the Omega utilities.
3067
3068 A new release of the AMS \TypeI\ fonts is included, including Computer
3069 Modern: a few shape changes made over the years by Knuth in the Metafont
3070 sources have been integrated, and the hinting has been updated. The
3071 Euler fonts have been thoroughly reshaped by Hermann Zapf (see
3072 \url{http://tug.org/TUGboat/Articles/tb29-2/tb92hagen-euler.pdf}). In
3073 all cases, the metrics remain unchanged. The AMS fonts home page is
3074 \url{http://www.ams.org/tex/amsfonts.html}.
3075
3076 The new GUI front end \TeX{}works is included for Windows, and also in
3077 Mac\TeX. For other platforms, and more information, see the \TeX{}works
3078 home page, \url{http://tug.org/texworks}. It is a cross-platform front
3079 end inspired by the \MacOSX\ TeXShop editor, aiming at ease-of-use.
3080
3081 The graphics program Asymptote is included for several platforms. This
3082 implements a text-based graphics description language vaguely akin to
3083 MetaPost, but with advanced 3D support and other features. Its home
3084 page is \url{http://asymptote.sourceforge.net}.
3085
3086 The separate \code{dvipdfm} program has been replaced by
3087 \code{dvipdfmx}, which operates in a special compatibility mode under
3088 that name. \code{dvipdfmx} includes \acro{CJK} support and has
3089 accumulated many other fixes over the years since the last
3090 \code{dvipdfm} release. The DVIPDFMx home page is
3091 \url{http://project.ktug.or.kr/dvipdfmx}.
3092
3093 Executables for the \pkgname{cygwin} and \pkgname{i386-netbsd} platforms
3094 are now included, while the other BSD distributions have been dropped;
3095 we were advised that OpenBSD and FreeBSD users get \TeX\ through their
3096 package systems, plus there were difficulties in making binaries that
3097 have a chance of working on more than one version.
3098
3099 A miscellany of smaller changes: we now use \pkgname{xz} compression,
3100 the stable replacement for \pkgname{lzma}
3101 (\url{http://tukaani.org/xz/}); a literal |$| is allowed in filenames
3102 when it does not introduce a known variable name; the Kpathsea library
3103 is now multi-threaded (made use of in MetaPost); the entire \TL{} build
3104 is now based on Automake.
3105
3106 Final note on the past: all releases of \TL{}, along with ancillary
3107 material such as \CD\ labels, are available at
3108 \url{ftp://tug.org/historic/systems/texlive}.
3109
3110
3111 \subsection{Future}
3112
3113 \emph{\TL{} is not perfect!} (And never will be.) We intend to
3114 continue to release new versions, and would like to provide more help
3115 material, more utilities, more installation programs, and (of course) an
3116 ever-improved and better-checked tree of macros and fonts. This work is
3117 all done by hard-pressed volunteers in their limited spare time, and a
3118 great deal remains to be done. Please see
3119 \url{http://tug.org/texlive/contribute.html}.
3120
3121 Please send corrections, suggestions, and offers of help to:
3122 \begin{quote}
3123 \email{[email protected]} \\
3124 \url{http://tug.org/texlive}
3125 \end{quote}
3126
3127 \medskip
3128 \noindent \textsl{Happy \TeX ing!}
3129
3130 \end{document}