Debian Codegraph @

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

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