Debian Codegraph @

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

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