Debian Codegraph @

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

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