Debian Codegraph @

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

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