Debian Codegraph @

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

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