Debian Codegraph @

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

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