Debian Codegraph @

texmf-dist/doc/pdftex/tests/38-interword-space-at-font-switch/texlive-en.tex

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