Debian Codegraph @

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

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