Debian Codegraph @

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

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