Debian Codegraph @

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

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