Debian Codegraph @

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

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