texlive[61735] Master/texmf-dist/doc/texlive/texlive-en/archive:

commits+karl at tug.org commits+karl at tug.org
Tue Jan 25 18:29:20 CET 2022

Revision: 61735
Author:   karl
Date:     2022-01-25 18:29:20 +0100 (Tue, 25 Jan 2022)
Log Message:
archive 2021 TL Guide files

Added Paths:

Added: trunk/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2021.tex
--- trunk/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2021.tex	                        (rev 0)
+++ trunk/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2021.tex	2022-01-25 17:29:20 UTC (rev 61735)
@@ -0,0 +1,3965 @@
+% $Id: texlive-en.tex 58572 2021-03-21 01:34:09Z karl $
+% TeX Live documentation.  Originally written by Sebastian Rahtz and
+% Michel Goossens, now maintained by Karl Berry and others.
+% Public domain.
+\let\tldocenglish=1  % for live4ht.cfg
+\usepackage[latin1]{inputenc} % translators: use your preferred encodings.
+  {\huge \textit{The \TeX\ Live Guide---2021}}
+\author{Karl Berry, editor \\[3mm]
+        \url{https://tug.org/texlive/}
+       }
+\date{March 2021}
+\subsection{\protect\TeX\protect\ Live and the \protect\TeX\protect\ Collection}
+This document describes the main features of the \TL{} software
+distribution\Dash \TeX{} and related programs for \GNU/Linux
+and other Unix flavors, \MacOSX, and Windows systems.
+You may have acquired \TL{} by downloading, or on the \TK{} \DVD, which
+\TeX{} user groups distribute among their members, or in other ways.
+Section \ref{sec:tl-coll-dists} briefly describes the contents of the
+\DVD.  Both \TL{} and the \TK{} are cooperative efforts by the \TeX{}
+user groups. This document mainly describes \TL{} itself.
+\TL{} includes executables for \TeX{}, \LaTeXe{}, \ConTeXt,
+\MF, \MP, \BibTeX{} and many other programs; an extensive collection
+of macros, fonts and documentation; and support for typesetting in
+many different scripts from around the world.
+For a brief summary of the major changes in this edition of \TL{},
+see the end of the document, section~\ref{sec:history}
+\subsection{Operating system support}
+\TL{} contains binaries for many Unix-based platforms, including
+\GNU/Linux, \MacOSX, and Cygwin.  The included sources can be compiled
+on platforms for which we do not provide binaries.
+As to Windows: Windows~7 and later are supported. Windows Vista
+may still mostly work, but \TL{} will no longer even install on Windows
+XP or earlier.  \TL{} includes no
+64-bit executables for Windows, but the 32-bit executables should
+run on 64-bit systems. But see
+\url{https://tug.org/texlive/windows.html} for options to add
+64-bit binaries.
+See section~\ref{sec:tl-coll-dists} for alternate solutions
+for Windows and \MacOSX.
+\subsection{Basic installation of \protect\TL{}}
+You can install \TL{} either from \DVD{} or over the Internet
+(\url{https://tug.org/texlive/acquire.html}). The net installer itself is
+small, and downloads everything requested from the Internet.
+The \DVD{} installer lets you install to a local disk.  You cannot run
+\TL{} directly from the \TK{} \DVD{} (or its \code{.iso} image), but you
+can prepare a runnable installation on, e.g., a \USB{} stick (see
+section~\ref{sec:portable-tl}).  Installation is described in later
+sections (\p.\pageref{sec:install}), but here is a quick start:
+\item For Unix, the installation script is \filename{install-tl}; on
+  Windows, one should instead invoke \filename{install-tl-windows}.
+  The installer will operate in a graphical mode given the option
+  \code{-gui} (default for Windows and \MacOSX), or a text mode given
+  the option \code{-gui=text} (default for everything else).
+\item One of the installed items is the `\TL\ Manager' program,
+  named \prog{tlmgr}.  Like the installer, it can be used in both \GUI{}
+  mode and in text mode. You can use it to install and uninstall
+  packages and do various configuration tasks.
+\subsection{Security considerations}
+To the best of our knowledge, the core \TeX\ programs themselves are
+(and always have been) extremely robust.  However, the contributed
+programs in \TeX\ Live may not reach the same level, despite everyone's
+best efforts.  As always, you should be careful when running programs on
+untrusted input; to improve safety, use a new subdirectory or chroot.
+This need for care is especially urgent on Windows, since in general
+Windows finds programs in the current directory before anything else,
+regardless of the search path.  This opens up a wide variety of possible
+attacks.  We have closed many holes, but undoubtedly some remain,
+especially with third-party programs.  Thus, we recommend checking for
+suspicious files in the current directory, especially executables
+(binaries or scripts).  Ordinarily they should not be present, and
+definitely should not normally be created by merely processing a document.
+Finally, \TeX\ (and its companion programs) are able to write files when
+processing documents, a feature that can also be abused in a wide
+variety of ways.  Again, processing unknown documents in a new
+subdirectory is the safest bet.
+Another aspect of security is ensuring that downloaded material has not
+been changed from what was created. The \prog{tlmgr} program
+(section~\ref{sec:tlmgr}) will automatically perform cryptographic
+verification on downloads if the \prog{gpg} (GNU Privacy Guard) program
+is available. It is not distributed as part of \TL, but see
+\url{https://texlive.info/tlgpg/} for information about \prog{gpg} if
+need be.
+\subsection{Getting help}
+The \TeX{} community is active and friendly, and most serious questions
+end up getting answered.  However, the support is informal, done by
+volunteers and casual users, so it's especially important that you do
+your homework before asking.  (If you prefer guaranteed commercial
+support, you can forgo \TL{} completely and purchase a vendor's system;
+\url{https://tug.org/interest.html#vendors} has a list.)
+Here is a list of resources, approximately in the order we recommend
+using them:
+\item [Getting started] If you are new to \TeX, the web page
+\url{https://tug.org/begin.html} gives a brief introduction to the system.
+\item [\TeX{} FAQ] The \TeX{} FAQ is a huge compendium
+  of answers to all sorts of questions, from the most basic to the
+  most arcane.  It is included on \TL{} in
+  \OnCD{texmf-dist/doc/generic/FAQ-en/}, and is available
+  on the Internet through \url{https://texfaq.org}.  Please
+  check here first.
+\item [\TeX{} Catalogue] If you are looking for a particular package,
+font, program, etc., the \TeX{} Catalogue is the place to look.  It is a
+huge collection of all \TeX{}-related items.  See
+\item [\TeX{} Web Resources] The web page
+\url{https://tug.org/interest.html} has many \TeX{}-related links, in
+particular for numerous books, manuals, and articles on all aspects of
+the system.
+\item [support archives] Principal support forums for \TeX\ include
+the \LaTeX{} community site at \url{https://latex.org}, the
+q\&a site \url{https://tex.stackexchange.com}, the Usenet newsgroup
+\url{news:comp.text.tex}, and the mailing list \email{texhax at tug.org}.
+Their archives have years of past questions and answers for your
+searching pleasure, via, for the latter two,
+\url{http://groups.google.com/group/comp.text.tex/topics} and
+\url{https://tug.org/mail-archives/texhax}.  And a general web search
+never hurts.
+\item [asking questions] If you cannot find an answer, you can post to 
+\url{http://latex-community.org/} and
+\url{https://tex.stackexchange.com/} through their web interfaces, to
+\dirname{comp.text.tex} through Google or your newsreader, or to
+\email{texhax at tug.org} through email.  But before you post anywhere,
+please read this FAQ entry, to maximize your chances of getting a useful
+\item [\TL{} support] If you want to report a bug or have
+suggestions or comments on the \TL{} distribution, installation, or
+documentation, the mailing list is \email{tex-live at tug.org}.  However,
+if your question is about how to use a particular program included in
+\TL{}, please write to that program's maintainer or
+mailing list.  Often running a program with the \code{-{}-help} option
+will provide a bug reporting address.
+The other side of the coin is helping others who have questions.  All
+the above resources are open to anyone, so feel free to join, start
+reading, and help out where you can.
+% don't use \TL so the \uppercase in the headline works.  Also so
+% tex4ht ends up with the right TeX.  Likewise the \protect's.
+\section{Overview of \protect\TeX\protect\ Live}
+This section describes the contents of \TL{} and the \TK{} of which it
+is a part.
+\subsection{The \protect\TeX\protect\ Collection: \protect\TL,
+           pro\protect\TeX{}t, Mac\protect\TeX}
+The \TK{} \DVD{} comprises the following:
+\item [\TL] A complete \TeX{} system to be installed to disk.  Home
+page: \url{https://tug.org/texlive/}.
+\item [Mac\TeX] for \MacOSX\ (currently named macOS by Apple, but we
+continue to use the older name in this document), this adds a native
+\MacOSX\ installer and other Mac applications to \TL{}. Home page:
+\item [pro\TeX{}t] An enhancement of the \MIKTEX\ distribution for Windows,
+\ProTeXt\ adds a few extra tools to \MIKTEX, and simplifies
+installation.  It is entirely independent of \TL{}, and has its own
+installation instructions.  Home page:
+\item [CTAN] A snapshot of the \CTAN{} repository (\url{https://ctan.org/}).
+\CTAN{} and \pkgname{protext} do not follow the same copying conditions
+as \TL{}, so be careful when redistributing or modifying.
+\subsection{Top level \protect\TL{} directories}
+Here is a brief listing and description of the top level directories in a
+\TL{} installation.  
+\item[bin] The \TeX{} system programs, arranged by platform.
+\item[readme-*.dir] Quick overview and useful links for \TL{},
+in various languages, in both \HTML{} and plain text.
+\item[source] The source to all included programs, including the main
+  \Webc{}-based \TeX{} distributions.
+\item[texmf-dist] The principal tree; see \dirname{TEXMFDIST} below.
+\item[tlpkg] Scripts, programs and data for managing the
+  installation, and special support for Windows.
+For documentation, the comprehensive links in the top-level file
+\OnCD{doc.html} may be helpful.  The documentation for nearly everything
+(packages, formats, fonts, program manuals, man pages, Info files) is in
+\dirname{texmf-dist/doc}.  You can use the \cmdname{texdoc} program to
+find documentation wherever it is located.
+This \TL\ documentation itself is in \dirname{texmf-dist/doc/texlive},
+available in several languages:
+\item{Czech/Slovak:} \OnCD{texmf-dist/doc/texlive/texlive-cz}
+\item{German:} \OnCD{texmf-dist/doc/texlive/texlive-de}
+\item{English:} \OnCD{texmf-dist/doc/texlive/texlive-en}
+\item{French:} \OnCD{texmf-dist/doc/texlive/texlive-fr}
+\item{Italian:} \OnCD{texmf-dist/doc/texlive/texlive-it}
+\item{Japanese:} \OnCD{texmf-dist/doc/texlive/texlive-ja}
+\item{Polish:} \OnCD{texmf-dist/doc/texlive/texlive-pl}
+\item{Russian:} \OnCD{texmf-dist/doc/texlive/texlive-ru}
+\item{Serbian:} \OnCD{texmf-dist/doc/texlive/texlive-sr}
+\item{Simplified Chinese:} \OnCD{texmf-dist/doc/texlive/texlive-zh-cn}
+\subsection{Overview of the predefined texmf trees}
+This section lists the predefined variables specifying the texmf trees
+used by the system, and their intended purpose, and the default layout
+of \TL{}. The command \texttt{tlmgr~conf} shows the values of these
+variables, so that you can easily find out how they map to particular
+directories in your installation.
+All of the trees, including the personal ones, should follow the \TeX\
+Directory Structure (\TDS, \url{https://tug.org/tds}), with all its
+myriad subdirectories, or files may not be found.  Section
+\ref{sec:local-personal-macros} (\p.\pageref{sec:local-personal-macros})
+describes this in more detail.  The order here is the reverse order in
+which the trees are searched, that is, later trees in the list override
+earlier ones.
+\item [TEXMFDIST] The tree which holds nearly all of the files in the original
+  distribution---configuration files, scripts, packages, fonts, etc.
+  (The main exception are the per-platform executables, which are stored
+  in a sibling directory \code{bin/}.)
+\item [TEXMFSYSVAR] The (site-wide) tree used by \verb+texconfig-sys+,
+  \verb+updmap-sys+ and \verb+fmtutil-sys+, and also by \verb+tlmgr+, to
+  store (cached) runtime data such as format files and generated map files.
+\item [TEXMFSYSCONFIG] The (site-wide) tree used by the utilities
+  \verb+texconfig-sys+, \verb+updmap-sys+, and \verb+fmtutil-sys+ to
+  store modified configuration data.
+\item [TEXMFLOCAL] The tree which administrators can use for system-wide
+  installation of additional or updated macros, fonts, etc.
+\item [TEXMFHOME] The tree which users can use for their own individual
+  installations of additional or updated macros, fonts, etc.
+  The expansion of this variable dynamically adjusts for each user to
+  their own individual directory.
+\item [TEXMFVAR] The (personal) tree used by \verb+texconfig+,
+  \verb+updmap-user+ and \verb+fmtutil-user+ to store (cached) runtime data such
+  as format files and generated map files.
+\item [TEXMFCONFIG] The (personal) tree used by the utilities
+  \verb+texconfig+, \verb+updmap-sys+, and \verb+fmtutil-sys+ to store modified
+  configuration data.
+\item [TEXMFCACHE] The tree(s) used by \ConTeXt\ MkIV and Lua\LaTeX\
+  to store (cached) runtime data; defaults to \code{TEXMFSYSVAR},
+  or (if that's not writable), \code{TEXMFVAR}.
+The default layout is:
+  \item[system-wide root] can span multiple \TL{} releases
+  (\texttt{/usr/local/texlive} by default on Unix):
+  \begin{ttdescription}
+    \item[2020] A previous release.
+    \item[2021] The current release.
+    \begin{ttdescription}
+      \item [bin] ~
+      \begin{ttdescription}
+        \item [i386-linux] \GNU/Linux binaries (32-bit)
+        \item [...]
+        \item [universal-darwin] \MacOSX\ binaries
+        \item [x86\_64-linux] \GNU/Linux binaries (64-bit)
+        \item [win32] Windows binaries
+      \end{ttdescription}
+      \item [texmf-dist\ \ ]      \envname{TEXMFDIST} and \envname{TEXMFMAIN}
+      \item [texmf-var \ \ ]      \envname{TEXMFSYSVAR}, \envname{TEXMFCACHE}
+      \item [texmf-config]        \envname{TEXMFSYSCONFIG}
+    \end{ttdescription}
+    \item [texmf-local] \envname{TEXMFLOCAL}, intended to be
+      retained from release to release.
+  \end{ttdescription}
+  \item[user's home directory] (\texttt{\$HOME} or
+      \texttt{\%USERPROFILE\%})
+    \begin{ttdescription}
+      \item[.texlive2020] Privately generated and configuration data
+        for a previous release.
+      \item[.texlive2021] Privately generated and configuration data
+        for the current release.
+      \begin{ttdescription}
+        \item [texmf-var\ \ \ ] \envname{TEXMFVAR}, \envname{TEXMFCACHE}
+        \item [texmf-config]    \envname{TEXMFCONFIG}
+      \end{ttdescription}
+    \item[texmf] \envname{TEXMFHOME} Personal macros, etc.
+  \end{ttdescription}
+\subsection{Extensions to \protect\TeX}
+Knuth's original \TeX{} itself is frozen, apart from rare bug fixes. It
+is present in \TL\ as the program \prog{tex}, and will remain so
+for the foreseeable future.  \TL{} also contains several extended versions of
+\TeX\ (also known as \TeX\ engines):
+\item [\eTeX] adds a set of new primitives
+\label{text:etex} (related to macro expansion, character scanning,
+classes of marks, additional debugging features, and more) and the
+\TeXXeT{} extensions for bidirectional typesetting.  In default mode,
+\eTeX{} is 100\% compatible with ordinary \TeX. See
+\item [pdf\TeX] builds on the \eTeX\ extensions, adding support for
+writing PDF output as well as \dvi{}, and many non-output-related
+extensions.  This is the program invoked for many common formats, e.g.,
+\prog{etex}, \prog{latex}, \prog{pdflatex}.  Its web site is
+\url{http://www.pdftex.org/}.  See
+\OnCD{texmf-dist/doc/pdftex/manual/pdftex-a.pdf} for the manual, and
+\OnCD{texmf-dist/doc/pdftex/samplepdftex/samplepdf.tex} for example
+usage of some of its features.
+\item [Lua\TeX] adds support for Unicode input and OpenType\slash
+TrueType- and system fonts. It also incorporates a Lua interpreter
+(\url{https://lua.org/}), enabling solutions for many thorny \TeX{}
+problems. When called as \filename{texlua}, it functions as a standalone
+Lua interpreter. Its web site is \url{http://www.luatex.org/}, and the
+reference manual is \OnCD{texmf-dist/doc/luatex/base/luatex.pdf}.
+\item [(e)(u)p\TeX] have native support for Japanese typesetting
+requirements; p\TeX\ is the basic engine, while the e- variants add
+\eTeX\ functionality and u- add Unicode support.
+\item [\XeTeX] adds support for Unicode input and OpenType\slash
+TrueType- and system fonts, implemented using standard third-party
+libraries. See \url{https://tug.org/xetex}.
+\item [\OMEGA\ (Omega)] is based on Unicode (16-bit characters), thus
+supports working with almost all the world's scripts simultaneously. It
+also supports so-called `\OMEGA{} Translation Processes' (OTPs),
+for performing complex transformations on arbitrary input.  Omega is no
+longer included in \TL{} as a separate program; only Aleph is provided:
+\item [Aleph] combines the \OMEGA\ and \eTeX\ extensions.
+See \OnCD{texmf-dist/doc/aleph/base}.
+\subsection{Other notable programs in \protect\TL}
+Here are a few other commonly-used programs included in \TL{}:
+\item [bibtex, biber] bibliography support.
+\item [makeindex, xindy] index support.
+\item [dvips] convert \dvi{} to \PS{}.
+\item [xdvi] \dvi{} previewer for the X Window System.
+\item [dviconcat, dviselect] cut and paste pages
+from \dvi{} files.
+\item [dvipdfmx] convert \dvi{} to PDF, an alternative approach
+to pdf\TeX\ (mentioned above).
+\item [psselect, psnup, \ldots] \PS{} utilities.
+\item [pdfjam, pdfjoin, \ldots] PDF utilities.
+\item [context, mtxrun] Con\TeX{}t and PDF processor.
+\item [htlatex, \ldots] \cmdname{tex4ht}: \AllTeX{} to HTML (and
+XML and more) converter.
+\subsection{Starting the installer}
+To begin, get the \TK{} \DVD{} or download the \TL{} net installer.  See
+\url{https://tug.org/texlive/acquire.html} for more information and other
+methods of getting the software.
+\item [Net installer, .zip or .tar.gz:] Download from \CTAN, under
+\dirname{systems/texlive/tlnet}; the url
+\url{http://mirror.ctan.org/systems/texlive/tlnet} should redirect to a
+nearby, up-to-date, mirror.  You can retrieve either
+\filename{install-tl.zip} which can be used under Unix and Windows, or
+the considerably smaller \filename{install-unx.tar.gz} for Unix
+only. After unpacking, \filename{install-tl} and
+\filename{install-tl-windows.bat} will be in the \dirname{install-tl}
+\item[Net installer, Windows .exe:] Download from \CTAN{} as above,
+and double-click. This starts up a first-stage installer and unpacker;
+see figure~\ref{fig:nsis}. It gives two choices: ``Install''
+and``Unpack only''.
+\item [\TeX{} Collection \DVD:] go to the \DVD's \dirname{texlive}
+subdirectory. Under Windows, the installer normally starts automatically
+when you insert the \DVD.  You can get the \DVD\ by becoming a member of
+a \TeX\ user group (highly recommended,
+\url{https://tug.org/usergroups.html}), or purchasing it separately
+(\url{https://tug.org/store}), or burning your own from the \ISO\ image.
+You can also mount the \ISO\ directly on most systems.  After installing
+from \DVD\ or \ISO, if you want to get continuing updates from the
+Internet, please see \ref{sec:dvd-install-net-updates}.
+\caption{First stage of Windows \code{.exe} installer}\label{fig:nsis}
+The same installer program is run, whatever the source.  The most
+visible difference between the two is that with the net installer, what
+you end up with is the packages that are currently available.  This is
+in contrast to the \DVD\ and \ISO\ images, which are not updated between
+the major public releases.
+If you need to download through proxies, use a \filename{~/.wgetrc} file
+or environment variables with the proxy settings for Wget
+or the equivalent for whatever download program you are using. This does
+not matter if you are installing from the \DVD\ or \ISO\ image.
+The following sections explain installer start-up in more detail.
+Below, \texttt{>} denotes the shell prompt; user input is
+The script \filename{install-tl} is a Perl script.  The simplest way
+to start it on a Unix-compatible system is as follows:
+> \Ucom{perl /path/to/installer/install-tl}
+(Or you can invoke \Ucom{/path/to/installer/install-tl} if it stayed
+executable, or \texttt{cd} to the directory first, etc.; we won't repeat
+all the variations.)  You may have to enlarge your terminal window so
+that it shows the full text installer screen
+To install in \GUI\ mode (figure~\ref{fig:advanced-lnx}), you'll need to
+have Tcl/Tk installed.  Given that, you can run:
+> \Ucom{perl install-tl -gui}
+The old \code{wizard} and \code{perltk}/\code{expert} options are
+still available, but now do the same thing as \code{-gui}. For
+a complete listing of the various options:
+> \Ucom{perl install-tl -help}
+\textbf{About Unix permissions:} Your \code{umask} at the time
+of installation will be respected by the \TL{} installer.  Therefore, if
+you want your installation to be usable by users other than you, make
+sure your setting is sufficiently permissive, for instance, \code{umask
+002}.  For more information about \code{umask}, consult your system
+\textbf{Special considerations for Cygwin:} Unlike other
+Unix-compatible systems, Cygwin does not by default include all of the
+prerequisite programs needed by the \TL{} installer.  See
+As mentioned in section~\ref{sec:tl-coll-dists}, a separate distribution
+is prepared for \MacOSX, named Mac\TeX\ (\url{https://tug.org/mactex}).
+We recommend using the native Mac\TeX\ installer instead of the \TL\
+installer on \MacOSX, because the native installer makes a few
+Mac-specific adjustments, in particular to allow easily switching
+between the various \TeX\ distributions for \MacOSX\ (Mac\TeX, Fink,
+MacPorts, \ldots) using the so-called \TeX{}Dist data structure.
+Mac\TeX\ is firmly based on \TL, and the main \TeX\ trees and binaries
+are precisely the same.  It adds a few extra folders with Mac-specific
+documentation and applications.
+If you are using the unpacked downloaded zip file, or the \DVD\
+installer failed to start automatically, double-click
+You can also start the installer from the command-prompt.  Below,
+\texttt{>} denotes the prompt; user input is \Ucom{\texttt{bold}}.  If
+you are in the installer directory, run just:
+> \Ucom{install-tl-windows}
+Or you can invoke it with an absolute location, such as:
+> \Ucom{D:\bs{}texlive\bs{}install-tl-windows}
+for the \TK\ \DVD, supposing that \dirname{D:} is the optical
+drive. Figure~\ref{fig:basic-w32} displays the initial basic screen
+of the \GUI\ installer, which is the default for Windows.
+To install in text mode, use:
+> \Ucom{install-tl-windows -no-gui}
+For a complete listing of the various options:
+> \Ucom{install-tl-windows -help}
+Installing TeX Live 2021 from: ...
+Platform: x86_64-linux => 'GNU/Linux on x86_64'
+Distribution: inst (compressed)
+Directory for temporary files: /tmp
+ Detected platform: GNU/Linux on Intel x86_64
+ <B> binary platforms: 1 out of 16
+ <S> set installation scheme: scheme-full
+ <C> customizing installation collections
+     40 collections out of 41, disk space required: 7172 MB
+ <D> directories:
+   TEXDIR (the main TeX directory):
+     /usr/local/texlive/2021
+   ...
+ <O> options:
+   [ ] use letter size instead of A4 by default
+   ...
+ <V> set up for portable installation
+ <I> start installation to hard disk
+ <P> save installation profile to 'texlive.profile' and exit
+ <H> help
+ <Q> quit
+\caption{Main text installer screen (\GNU/Linux)}\label{fig:text-main}
+\caption{Basic installer screen (Windows); the Advanced button will
+  result in something like figure~\ref{fig:advanced-lnx}}\label{fig:basic-w32}
+\caption{Advanced \GUI{} installer screen
+  (\GNU/Linux)}\label{fig:advanced-lnx}
+Before beginning the installation, use Cygwin's \filename{setup.exe} program to
+install the \filename{perl} and \filename{wget} packages if you have
+not already done so.  The following additional packages are
+\item \filename{fontconfig} [needed by \XeTeX\ and Lua\TeX]
+\item \filename{ghostscript} [needed by various utilities]
+\item \filename{libXaw7} [needed by \code{xdvi}]
+\item \filename{ncurses} [provides the \code{clear} command used by the installer]
+\subsubsection{The text installer}
+Figure~\ref{fig:text-main} displays the main text mode screen under
+Unix.  The text installer is the default on Unix.
+This is only a command-line installer; there is no cursor support at
+all.  For instance, you cannot tab around checkboxes or input fields.
+You just type something (case-sensitive) at the prompt and press the
+Enter key, and then the entire terminal screen will be rewritten, with
+adjusted content.
+The text installer interface is this primitive in order to make it run
+on as many platforms as possible, even with a minimal Perl.
+\subsubsection{The graphical installer}
+The default graphical installer starts out simple, with just a
+few options; see figure~\ref{fig:basic-w32}. It can be started with
+> \Ucom{install-tl -gui}
+The Advanced button gives access to most of the options of the text
+installer; see figure~\ref{fig:advanced-lnx}.
+The \texttt{perltk}/\texttt{expert} and \texttt{wizard} \GUI{}
+options now invoke the regular graphical installer.
+\subsection{Running the installer}
+The installer is intended to be mostly self-explanatory, but following are a
+few notes about the various options and submenus.
+\subsubsection{Binary systems menu (Unix only)}
+Available platforms:
+   a [ ] Cygwin on Intel x86 (i386-cygwin)
+   b [ ] Cygwin on x86_64 (x86_64-cygwin)
+   c [ ] MacOSX current (10.14-) on ARM/x86_64 (universal-darwin)
+   d [ ] MacOSX legacy (10.6-) on x86_64 (x86_64-darwinlegacy)
+   e [ ] FreeBSD on x86_64 (amd64-freebsd)
+   f [ ] FreeBSD on Intel x86 (i386-freebsd)
+   g [ ] GNU/Linux on ARM64 (aarch64-linux)
+   h [ ] GNU/Linux on ARMv6/RPi (armhf-linux)
+   i [ ] GNU/Linux on Intel x86 (i386-linux)
+   j [X] GNU/Linux on x86_64 (x86_64-linux)
+   k [ ] GNU/Linux on x86_64 with musl (x86_64-linuxmusl)
+   l [ ] NetBSD on x86_64 (amd64-netbsd)
+   m [ ] NetBSD on Intel x86 (i386-netbsd)
+   o [ ] Solaris on Intel x86 (i386-solaris)
+   p [ ] Solaris on x86_64 (x86_64-solaris)
+   s [ ] Windows (win32)
+\caption{Binaries menu}\label{fig:bin-text}
+Figure~\ref{fig:bin-text} displays the text mode binaries menu.  By
+default, only the binaries for your current platform will be installed.
+From this menu, you can select installation of binaries for other
+platforms as well.  This can be useful if you are sharing a \TeX\
+tree across a network of heterogeneous machines, or for a dual-boot
+\subsubsection{Selecting what is to be installed}
+Select scheme:
+ a [X] full scheme (everything)
+ b [ ] medium scheme (small + more packages and languages)
+ c [ ] small scheme (basic + xetex, metapost, a few languages)
+ d [ ] basic scheme (plain and latex)
+ e [ ] minimal scheme (plain only)
+ f [ ] ConTeXt scheme
+ g [ ] GUST TeX Live scheme
+ h [ ] infrastructure-only scheme (no TeX at all)
+ i [ ] teTeX scheme (more than medium, but nowhere near full)
+ j [ ] custom selection of collections
+\caption{Scheme menu}\label{fig:scheme-text}
+Figure~\ref{fig:scheme-text} displays the \TL\ scheme menu; from here,
+you choose a ``scheme'', which is an overall set of package collections.
+The default \optname{full} scheme installs everything available. This is
+recommended, but you can also choose the \optname{basic} scheme for
+just plain and \LaTeX, \optname{small} for a few more programs
+(equivalent to the so-called Basic\TeX\ installation of Mac\TeX),
+\optname{minimal} for testing purposes, and \optname{medium} or
+\optname{teTeX} to get something in between. There are also various
+specialized and country-specific schemes.
+\centering \tlpng{stdcoll}{.7\linewidth}
+\caption{Collections menu}\label{fig:collections-gui}
+You can refine your scheme selection with the `collections' menu
+(figure~\ref{fig:collections-gui}, shown in \GUI\ mode for a change).
+Collections are one level more detailed than schemes\Dash in essence, a
+scheme consists of several collections, a collection consists of one or
+more packages, and a package (the lowest level grouping in \TL) contains
+the actual \TeX\ macro files, font files, and so on.
+If you want more control than the collection menus provide, you can use
+the \TeX\ Live Manager (\prog{tlmgr}) program after installation (see
+section~\ref{sec:tlmgr}); using that, you can control the installation
+at the package level.
+The default layout is described in section~\ref{sec:texmftrees},
+\p.\pageref{sec:texmftrees}.  The default installation directory is
+\dirname{/usr/local/texlive/2021} on Unix and
+|%SystemDrive%\texlive\2021| on Windows.  This arrangement enables
+having many parallel \TL\ installations, such as one for each release
+(typically by year, as here), and you can switch between them merely by
+altering your search path.
+That installation directory can be overridden by setting the so-called
+\dirname{TEXDIR} in the installer.  The \GUI\ screen for this and other
+options is shown in figure~\ref{fig:advanced-lnx}.  The most common reasons
+to change it are either lacking enough disk space in that partition (the
+full \TL\ needs several gigabytes), or lacking write permission for the
+default location (you don't have to be root or administrator to install
+\TL, but you do need write access to the target directory).
+The installation directories can also be changed by setting a variety of
+environment variables before running the installer (most likely,
+\envname{TEXLIVE\_INSTALL\_TEXDIR}); see the documentation from
+|install-tl --help| (available online at
+\url{https://tug.org/texlive/doc/install-tl.html}) for the full list and
+more details.
+A reasonable alternative destination is a directory under your home,
+especially if you will be the sole user. Use `|~|' to indicate this, as
+in `|~/texlive/2021|'.
+We recommend including the year in the name, to enable keeping different
+releases of \TL{} side by side.  (You may wish to also maintain a
+version-independent name, such as \dirname{/usr/local/texlive-cur}, via a
+symbolic link, which you can then repoint after testing the new release.)
+Changing \dirname{TEXDIR} in the installer will also change
+\dirname{TEXMFLOCAL}, \dirname{TEXMFSYSVAR} and
+\dirname{TEXMFHOME} is the recommended location for personal macro files
+or packages.  The default value is |~/texmf| (|~/Library/texmf| on
+Macs).  In contrast to \dirname{TEXDIR}, here a |~| is preserved in the
+newly-written configuration files, since it usefully refers to the home
+directory of the user running \TeX.  It expands to \dirname{$HOME} on
+Unix and \verb|%USERPROFILE%| on Windows.  Special redundant note:
+\envname{TEXMFHOME}, like all trees, must be organized according to the
+\TDS, or files may not be found.
+\dirname{TEXMFVAR} is the location for storing most cached runtime data
+specific to each user.  \dirname{TEXMFCACHE} is the variable name used
+for that purpose by Lua\LaTeX\ and \ConTeXt\ MkIV (see
+section~\ref{sec:context-mkiv}, \p.\pageref{sec:context-mkiv}); its
+default value is \dirname{TEXMFSYSVAR}, or (if that's not writable),
+Options customization:
+ <P> use letter size instead of A4 by default: [ ]
+ <E> execution of restricted list of programs: [X]
+ <F> create all format files:                  [X]
+ <D> install font/macro doc tree:              [X]
+ <S> install font/macro source tree:           [X]
+ <L> create symlinks in standard directories:  [ ]
+            binaries to:
+            manpages to:
+                info to:
+ <Y> after install, set CTAN as source for package updates: [X]
+\caption{Options menu (Unix)}\label{fig:options-text}
+Figure~\ref{fig:options-text} shows the text mode options menu.
+More info on each:
+\item[use letter size instead of A4 by default:] The default paper
+  size selection.  Of course, individual documents can and should
+  specify a specific paper size, if desired.
+\item[execution of restricted list of programs:] As of \TL\ 2010,
+  execution of a few external programs is allowed by default.  The (very
+  short) list of allowed programs is given in the \filename{texmf.cnf}.
+  See the 2010 news (section~\ref{sec:2010news}) for more details.
+\item[create all format files:] Although unnecessary format files
+  take time to generate and disk space to store, it is still recommended
+  to leave this option checked: if you don't, then format files will be
+  generated in people's private \dirname{TEXMFVAR} tree as they are
+  needed.  In that location, they will not be updated automatically if
+  (for example) core packages or hyphenation patterns are updated in the
+  installation, and thus you could end up with incompatible format files.
+\item[install font/macro \ldots\ tree:] Download/install the
+  documentation and source files included in most packages.  Unchecking
+  is not recommended.
+\item[create symlinks in standard directories:]
+  This option (Unix only) bypasses the need to change environment
+  variables. Without this option, \TL{} directories usually have to be
+  added to \envname{PATH}, \envname{MANPATH} and \envname{INFOPATH}. You
+  will need write permissions to the target directories.  This option is
+  intended for accessing the \TeX\ system through directories that are
+  already known to users, such as \dirname{/usr/local/bin}, which don't
+  already contain any \TeX\ files.  Do not overwrite existing files on
+  your system with this option, e.g., by specifying system directories.
+  The safest and recommended approach is to leave the option unchecked.
+\item[after install, set CTAN as source for package updates:]
+  When installing from \DVD, this
+  option is enabled by default, since usually one wants to take any
+  subsequent package updates from the \CTAN\ area that is updated
+  throughout the year.  The only likely reason to disable it is if you
+  install only a subset from the \DVD\ and plan to augment the
+  installation later.  In any case, the package repository for the
+  installer, and for updates after installation, can be set
+  independently as needed; see section~\ref{sec:location} and
+  section~\ref{sec:dvd-install-net-updates}.
+Windows-specific options, as displayed in the advanced \GUI{}
+\item[adjust searchpath] This ensures that all
+  programs will see the \TL{} binary directory on their search path.
+\item[add menu shortcuts] If set, there will be a \TL{} submenu of
+  the Start menu. There is a third option `Launcher entry' besides
+  `TeX Live menu' and `No shortcuts'. This option is described in
+  section \ref{sec:sharedinstall}.
+\item[File associations] The options are `Only new' (create
+  file associations, but do not overwrite existing ones), `All' and
+  `None'.
+\item[install \TeX{}works front end]
+When all the settings are to your liking, you can type `I' in the
+text interface, or press the `Install' button in the
+\GUI, to start the installation process. When it is done,
+skip to section~\ref{sec:postinstall} to read what else needs to be
+done, if anything.
+\subsection{Command-line install-tl options}
+> \Ucom{install-tl -help}
+for a listing of command-line options.  Either |-| or |--| can be used
+to introduce option names.  These are the most common ones:
+\item[-gui] Use the \GUI{} installer if possible. This requires
+  Tcl/Tk version 8.5 or higher. This is the case on \MacOSX\ and is
+  distributed with \TL{} on Windows. The legacy options
+  \texttt{-gui=perltk} and \texttt{-gui=wizard} are still available
+  but invoke the same \GUI{} interface; if Tcl/Tk is not available,
+  installation continues in text mode.
+\item[-no-gui] Force using the text mode installer.
+\item[-lang {\sl LL}] Specify the installer interface
+  language as a standard (usually two-letter) code.  The installer tries
+  to automatically determine the right language but if it fails, or if
+  the right language is not available, then it uses English as a
+  fallback.  Run \verb|install-tl --help| to get the list of available
+  languages.
+\item[-portable] Install for portable use on, e.g., a \USB{} stick.
+  Also selectable from within the text installer with the \code{V}
+  command, and from the \GUI{} installer.  See
+  section~\ref{sec:portable-tl}.
+\item[-profile {\sl file}] Load the installation profile \var{file} and
+  do the installation with no user interaction.  The installer always
+  writes a file \filename{texlive.profile} to the \dirname{tlpkg}
+  subdirectory of your installation.  That file can be given as the
+  argument to redo the exact same installation on a different system,
+  for example.  Alternatively, you can use a custom profile, most easily
+  created by starting from a generated one and changing values, or an
+  empty file, which will take all the defaults.
+\item [-repository {\sl url-or-directory}] Specify package
+  repository from which to install; see following.
+\item[-in-place] (Documented only for completeness: Do not use this
+  unless you know what you are doing.) If you already have an rsync, svn,
+  or other copy of \TL{} (see
+  \url{https://tug.org/texlive/acquire-mirror.html}) then this option
+  will use what you've got, as-is, and do only the necessary
+  post-install.  Be warned that the file \filename{tlpkg/texlive.tlpdb}
+  may be overwritten; saving it is your responsibility.  Also, package
+  removal has to be done manually. This option cannot be toggled via the
+  installer interface.
+\subsubsection{The \optname{-repository} option}
+The default network package repository is a \CTAN{} mirror chosen
+automatically via \url{http://mirror.ctan.org}.
+If you want to override that, the location value can be a url
+starting with \texttt{ftp:}, \texttt{http:}, \texttt{https:},
+\texttt{file:/}, or a plain directory path.  (When giving an
+\texttt{http:}, \texttt{https:} or \texttt{ftp:}\ location, trailing
+`\texttt{/}' characters and/or a trailing `\texttt{/tlpkg}'
+component are ignored.)
+For example, you could choose a particular \CTAN\ mirror with something
+like: \url{http://ctan.example.org/tex-archive/systems/texlive/tlnet/},
+substituting a real hostname and its particular top-level \CTAN\ path
+for |ctan.example.org/tex-archive|.  The list of \CTAN\ mirrors is
+maintained at \url{https://ctan.org/mirrors}.
+If the given argument is local (either a path or a \texttt{file:/} url),
+compressed files in an \dirname{archive} subdirectory of the repository
+path are used (even if uncompressed files are available as well).
+\subsection{Post-install actions}
+Some post-installation may be required.
+\subsubsection{Environment variables for Unix}
+If you elected to create symlinks in standard directories (described in
+section~\ref{sec:options}), then there is no need to edit environment
+variables.  Otherwise, on Unix systems, the directory of the binaries
+for your platform must be added to the search path.  (On Windows, the
+installer takes care of this.)
+Each supported platform has its own subdirectory under
+\dirname{TEXDIR/bin}. See figure~\ref{fig:bin-text} for the list of
+subdirectories and corresponding platforms.
+Optionally, you can also add the documentation man and Info directories
+to their respective search paths, if you want the system tools to find
+them.  The man pages might be found automatically after the addition to
+For Bourne-compatible shells such as \prog{bash}, and using Intel x86
+GNU/Linux and a default directory setup as an example, the file to edit
+might be \filename{$HOME/.profile} (or another file sourced by
+\filename{.profile}), and the lines to add would look like this:
+PATH=/usr/local/texlive/2021/bin/x86_64-linux:$PATH; export PATH
+MANPATH=/usr/local/texlive/2021/texmf-dist/doc/man:$MANPATH; export MANPATH
+INFOPATH=/usr/local/texlive/2021/texmf-dist/doc/info:$INFOPATH; export INFOPATH
+For csh or tcsh, the file to edit is typically \filename{$HOME/.cshrc}, and
+the lines to add might look like:
+setenv PATH /usr/local/texlive/2021/bin/x86_64-linux:$PATH
+setenv MANPATH /usr/local/texlive/2021/texmf-dist/doc/man:$MANPATH
+setenv INFOPATH /usr/local/texlive/2021/texmf-dist/doc/info:$INFOPATH
+If you already have settings somewhere in your ``dot'' files, naturally
+the \TL\ directories should be merged in as appropriate.
+\subsubsection{Environment variables: Global configuration}
+If you want to make these changes globally, or for a user newly added to
+the system, then you are on your own; there is just too much variation
+between systems in how and where these things are configured.
+Our two hints are: 1)~you may want to check for a file
+\filename{/etc/manpath.config} and, if present, add lines such as
+MANPATH_MAP /usr/local/texlive/2021/bin/x86_64-linux \
+            /usr/local/texlive/2021/texmf-dist/doc/man
+And 2)~check for a file \filename{/etc/environment} which may define the
+search path and other default environment variables.
+In each (Unix) binary directory, we also create a symbolic link named
+\code{man} to the directory \dirname{texmf-dist/doc/man}.  Some \code{man}
+programs, such as the standard \MacOSX\ \code{man}, will automatically
+find that, obviating the need for any man page setup.
+\subsubsection{Internet updates after \DVD\ installation}
+If you installed \TL\ from \DVD\ and then wish to get updates from the
+Internet, you need to run this command---\emph{after} you've updated
+your search path (as described in the previous section):
+> \Ucom{tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet}
+This tells \cmdname{tlmgr} to use a nearby \CTAN\ mirror for future updates.
+This is done by default when installing from \DVD, via the option
+described in section~\ref{sec:options}.
+If there are problems with the automatic mirror selection, you can
+specify a particular \CTAN\ mirror from the list at
+\url{https://ctan.org/mirrors}.  Use the exact path to the
+\dirname{tlnet} subdir on that mirror, as shown above.
+\htmlanchor{xetexfontconfig}  % keep historical anchor working
+\subsubsection{System font configuration for \protect\XeTeX\protect\ and Lua\protect\TeX}
+\XeTeX\ and Lua\TeX\ can use any font installed on the system, not just
+those in the \TeX\ trees.  They do these via related but not identical
+On Windows, fonts shipped with \TL\ are automatically made available to
+\XeTeX\ by font name.  On \MacOSX, supporting font name lookups requires
+additional steps; please see the Mac\TeX\ web pages
+(\url{https://tug.org/mactex}).  For other Unix systems, the procedure to
+be able to find the fonts shipped with \TL\ via font name follows.
+To facilitate this, when the \pkgname{xetex} package is installed
+(either at initial installation or later), the necessary configuration
+file is created in
+To set up the \TL{} fonts for system-wide use (assuming you have
+suitable privileges), proceed as follows:
+\item Copy the \filename{texlive-fontconfig.conf} file to
+\item Run \Ucom{fc-cache -fsv}.
+If you do not have sufficient privileges to carry out the steps above,
+or if you want to make the \TL{} fonts available to only one user,
+you can do the following:
+\item Copy the \filename{texlive-fontconfig.conf} file to
+      \filename{~/.fonts.conf}, where \filename{~} is your home directory.
+\item Run \Ucom{fc-cache -fv}.
+You can run \code{fc-list} to see the names of the system fonts.  The
+incantation \code{fc-list : family style file spacing} (all arguments
+are literal strings) shows some generally interesting information.
+\subsubsection{\protect\ConTeXt{} Mark IV}
+Both the `old' \ConTeXt{} (Mark II) and the `new' \ConTeXt{}
+(Mark IV) should run out of the box after \TL{} installation,
+and should need no special attention as long as you stick to
+using \verb+tlmgr+ for updates.
+However, because \ConTeXt{} MkIV does not use the kpathsea
+library, some setup will be required whenever you install new 
+files manually (without using \verb+tlmgr+). After each such 
+installation, each MkIV user must run:
+context --generate
+to refresh the \ConTeXt{} disk cache data.
+The resulting files are stored under \code{TEXMFCACHE},
+whose default value in \TL\ is \verb+TEXMFSYSVAR;TEXMFVAR+. 
+\ConTeXt\ MkIV will read from
+all paths mentioned in \verb+TEXMFCACHE+, and write to the first
+path that is writable. While reading, the last found match will 
+take precedence in the case of duplicated cache data.
+For more information, see
+\subsubsection{Integrating local and personal macros}
+This is already mentioned implicitly in section~\ref{sec:texmftrees}:
+\dirname{TEXMFLOCAL} (by default,
+\dirname{/usr/local/texlive/texmf-local} or
+\verb|%SystemDrive%\texlive\texmf-local| on Windows)
+is intended for system-wide local fonts and macros; and
+\dirname{TEXMFHOME} (by default, \dirname{$HOME/texmf} or
+\verb|%USERPROFILE%\texmf|), is for personal fonts and macros.  These
+directories are intended to stick around from release to release, and
+have their content seen automatically by a new \TL{} release.
+Therefore, it is best to refrain from changing the definition of
+\dirname{TEXMFLOCAL} to be too far away from the main \TL{} directory,
+or you will need to manually change future releases.
+For both trees, files should be placed in their proper \TeX\ Directory
+Structure (\TDS) subdirectories; see \url{https://tug.org/tds} or consult
+\filename{texmf-dist/web2c/texmf.cnf}. For instance, a \LaTeX{} class file or
+package should be placed in \dirname{TEXMFLOCAL/tex/latex} or
+\dirname{TEXMFHOME/tex/latex}, or a subdirectory thereof.
+\dirname{TEXMFLOCAL} requires an up-to-date filename database, or files
+will not be found.  You can update it with the command
+\cmdname{mktexlsr} or use the `Reinit file database' button on the
+configuration tab of the \TeX\ Live Manager \GUI.
+By default, each of these variables is defined to be a single directory,
+as shown.  This is not a hard-and-fast requirement.  If you need to
+easily switch back and forth between different versions of large
+packages, for example, you can maintain multiple trees for your own
+purposes.  This is done by setting \dirname{TEXMFHOME} to the
+list of directories, within braces, separated by commas:
+  TEXMFHOME = {/my/dir1,/mydir2,/a/third/dir}
+Section~\ref{sec:brace-expansion} describes brace expansion further.
+\subsubsection{Integrating third-party fonts}
+This is unfortunately a messy topic for \TeX\ and pdf\TeX. Forget about
+it unless you want to delve into many details of the \TeX{}
+installation. Many fonts are included in \TL\ already, so take a look if
+you like; the web pages under \url{https://tug.org/FontCatalogue}
+display nearly all of the text fonts included in the main \TeX\
+distributions, categorized in various ways.
+If you do want to install your own fonts, see
+\url{https://tug.org/fonts/fontinstall.html} for our best effort at
+describing the procedure.
+Also consider using \XeTeX\ or Lua\TeX\ (see
+section~\ref{sec:tex-extensions}), which let you use operating
+system fonts without any installation in \TeX. (But beware that using
+system fonts makes your documents instantly unusable by anyone in a
+different environment.)
+\subsection{Testing the installation}
+After installing \TL{}, you naturally want to test it out, so you can
+start creating beautiful documents and\slash or fonts.
+One thing you may immediately be looking for is a front-end with which
+to edit files.  \TL{} installs \TeX{}works
+(\url{https://tug.org/texworks}) on Windows (only), and Mac\TeX\ installs
+TeXShop (\url{https://pages.uoregon.edu/koch/texshop}).  On other Unix
+systems, it's left up to you to choose an editor.  There are many
+choices available, some of which are listed in the next section; see
+also \url{https://tug.org/interest.html#editors}.  Any plain text editor
+will work; something \TeX-specific is not required.
+The rest of this section gives some basic procedures for testing that
+the new system is functional.  We give Unix commands here; under
+\MacOSX{} and Windows, you're more likely to run the tests through a
+graphical interface, but the principles are the same.
+\item Make sure that you can run the \cmdname{tex} program in the first
+> \Ucom{tex -{}-version}
+TeX 3.14159265 (TeX Live ...)
+Copyright ... D.E. Knuth.
+If this comes back with `command not found' instead of version and
+copyright information, or with an older version, most likely you don't
+have the correct \dirname{bin} subdirectory in your \envname{PATH}.  See
+the environment-setting information on \p.\pageref{sec:env}.
+\item Process a basic \LaTeX{} file, generating PDF:
+> \Ucom{pdflatex sample2e.tex}
+This is pdfTeX 3.14...
+Output written on sample2e.pdf (3 pages, 142120 bytes).
+Transcript written on sample2e.log.
+If this fails to find \filename{sample2e.tex} or other files,
+you may have interference from old environment variables or
+configuration files; we recommend unsetting all \TeX-related environment
+variables for a start.  (For a deep analysis, you can ask \TeX{} to
+report on exactly what it is searching for, and finding; see ``Debugging
+actions'' on page~\pageref{sec:debugging}.)
+\item Preview the PDF file, for example:
+> \Ucom{xpdf sample2e.pdf}
+You should see a new window with a nice document explaining some of the
+basics of \LaTeX{}.  (It's well worth reading, by the way, if you're new
+to \TeX.)  
+Of course there are many other PDF viewers; on Unix systems,
+\cmdname{evince} and \cmdname{okular} are commonly used. For Windows, we
+recommend trying Sumatra PDF
+(\url{https://www.sumatrapdfreader.org/free-pdf-reader.html}). No PDF
+viewers are included in \TL{}, so you must install whatever you want to
+use separately.
+\item Of course you can still generate \TeX's original \dvi{} format:
+> \Ucom{latex sample2e.tex}
+\item And preview the \dvi{} online:
+> \Ucom{xdvi sample2e.dvi}    # Unix
+> \Ucom{dviout sample2e.dvi}  # Windows
+You do have to be running under X for \cmdname{xdvi} to work; if
+you're not, or your \envname{DISPLAY} environment variable is set
+incorrectly, you'll get an error \samp{Can't open display}.
+\item To create a \PS{} file from the \dvi:
+> \Ucom{dvips sample2e.dvi -o sample2e.ps}
+\item Or to create PDF from the \dvi{}, an alternate path to using
+pdf\TeX\ (or Xe\TeX\ or Lua\TeX) which can be useful sometimes:
+> \Ucom{dvipdfmx sample2e.dvi -o sample2e.pdf}
+\item Other standard test files you may find useful in addition to
+\item [small2e.tex] A simpler document than \filename{sample2e}, to
+reduce the input size if you're having troubles.
+\item [testpage.tex] Test if your printer introduces any offsets.
+\item [nfssfont.tex] For printing font tables and tests.
+\item [testfont.tex] Also for font tables, but using plain \TeX{}.
+\item [story.tex] The most canonical (plain) \TeX{} test file of all.
+You must type \samp{\bs bye} to the \code{*} prompt after \samp{tex
+\item If you have installed the \filename{xetex} package, you can test
+its access to system fonts as follows:
+> \Ucom{xetex opentype-info.tex}
+This is XeTeX, Version 3.14\dots
+Output written on opentype-info.pdf (1 page).
+Transcript written on opentype-info.log.
+If you get an error message saying ``Invalid fontname `Latin Modern
+Roman/ICU'\dots'', then you need to configure your system so that the
+fonts shipped with \TL\ can be found.  See
+\subsection{Links for additional downloadable software}
+If you are new to \TeX{}, or otherwise need help with actually writing
+\TeX{} or \LaTeX{} documents, please visit
+\url{https://tug.org/begin.html} for some introductory resources.
+Links for some other tools you may consider installing:
+\item[Ghostscript] \url{https://ghostscript.com/}
+\item[Perl] \url{https://perl.org/} with
+      supplementary packages from CPAN, \url{https://cpan.org/}
+\item[ImageMagick] \url{https://imagemagick.org}, for graphics
+      processing and conversion
+\item[NetPBM] \url{http://netpbm.sourceforge.net}, also for graphics.
+\item[\TeX-oriented editors] There is a wide choice, and it is a matter of the
+      user's taste. Here is a selection in alphabetical order (a few
+      here are for Windows only).
+  \begin{itemize*}
+  \item \cmdname{GNU Emacs} is also available natively under Windows, see
+        \url{https://www.gnu.org/software/emacs/emacs.html}.
+  \item \cmdname{Emacs with Auc\TeX} for Windows is available from \CTAN.
+        The AuC\TeX\ home page is \url{https://www.gnu.org/software/auctex}.
+  \item \cmdname{SciTE} is available from
+        \url{https://www.scintilla.org/SciTE.html}.
+  \item \cmdname{Texmaker} is free software, available from
+        \url{https://www.xm1math.net/texmaker}.
+  \item \cmdname{TeXstudio} started as a fork of
+    \cmdname{Texmaker} and given additional features; available from
+    \url{https://texstudio.org/} and in the pro\TeX{}t distribution.
+  \item \cmdname{TeXnicCenter} is free software, available from
+        \url{https://www.texniccenter.org}.
+  \item \cmdname{TeXworks} is free software, available from
+        \url{https://tug.org/texworks} and installed as part of \TL\ for
+        Windows (only).
+  \item \cmdname{Vim} is free software, available from
+        \url{https://www.vim.org}.
+  \item \cmdname{WinEdt} is shareware available though
+        \url{https://tug.org/winedt} or \url{https://www.winedt.com}.
+  \item \cmdname{WinShell} is available from \url{https://www.winshell.de}.
+  \end{itemize*}
+For a much longer list of packages and programs, see
+\section{Specialized installations}
+The previous sections described the basic installation process.  Here we
+turn to some specialized cases.
+\subsection{Shared-user (or cross-machine) installations}
+\TL{} has been designed to be shared between different systems on a
+network. With a standard directory layout, no hard paths are
+configured: the locations for files needed by \TL{} programs are
+found relative to the programs.  You can see this in the principal
+configuration file
+\filename{$TEXMFDIST/web2c/texmf.cnf}, which contains lines such as
+This means that adding the directory for \TL{} executables for their
+platform to their search path is sufficient to get a working setup.
+By the same token, you can also install \TL{} locally and then move
+the entire hierarchy afterwards to a network location.
+For Windows, \TL{} includes a launcher \filename{tlaunch}. Its main
+window contains menu entries and buttons for various \TeX-related
+programs and documentation, customizable via an \code{ini} file.  On
+first use, it replicates the usual Windows-specific post-install,
+\emph{i.e.}, search path modification and file associations, but only
+for the current user. Therefore, workstations with access to \TL{} on
+the local network only need a menu shortcut for the launcher.  See the
+\code{tlaunch} manual (\code{texdoc tlaunch}, or
+\subsection{Portable (\USB{}) installations}
+The \code{-portable} installer option (or \code{V} command in the text
+installer or corresponding \GUI{} option) creates a completely
+self-contained \TL{} installation under a common root and forgoes system
+integration. You can create such an installation directly on a \USB{}
+stick, or copy it to a \USB{} stick afterwards.
+Technically, the portable installation is made self-contained by setting
+the default values of \envname{TEXMFHOME}, \envname{TEXMFVAR}, and
+\envname{TEXMFCONFIG} to be the same as \envname{TEXMFLOCAL},
+\envname{TEXMFSYSVAR}, and \envname{TEXMFSYSCONFIG} respectively; thus,
+per-user configuration and caches will not be created.
+To run \TeX\ using this portable installation, you need to add the
+appropriate binary directory to the search path during your terminal
+session, as usual.
+On Windows, you can double-click \filename{tl-tray-menu} at the root
+of the installation and create a temporary `tray menu' offering a
+choice of a few common tasks, as shown in this screenshot:
+\noindent The `More\ldots' entry explains how you can customize this menu.
+%\subsection{\ISO\ (or \DVD) installations}
+%If you don't need to update or otherwise modify your installation often,
+%and\slash or have several systems on which to use \TL{}, it may be
+%convenient to create an \ISO\ of your \TL{} installation, because:
+%\item Copying an \ISO\ between different computers is much
+%  faster than copying a normal installation.
+%\item If you are dual-booting between different operating systems
+%  and want them to share a \TL{} installation, an \ISO
+%  installation is not tied to the idiosyncrasies and limitations of
+%  other mutually supported filesystems (FAT32, NTFS,
+%  HFS+).
+%\item Virtual machines can simply mount such an \ISO.
+%Of course you can also burn an \ISO\ to \DVD, if that is useful for you.
+%Desktop \GNU/Linux/Unix systems, including \MacOSX, are able to
+%mount an \ISO. Windows 8 is the first(!) Windows version which can
+%do this. Apart from that, nothing changes compared to a normal hard
+%disk installation, see section \ref{sec:env}.
+%When preparing such an \ISO\ installation, it is best to omit the
+%subdirectory for the release year, and have
+%\filename{texmf-local} at the same level as the other trees
+%(\filename{texmf-dist}, \filename{texmf-var}, etc.).  You can do this with
+%the normal directory options in the installer.
+%For a physical (rather than virtual) Windows system, you can burn
+%the \ISO\ to DVD. However, it may be worth your while to
+%investigate free \ISO-mounting options such as WinCDEmu at
+%For Windows system integration, you can include the \filename{w32client}
+%scripts described in section~\ref{sec:sharedinstall} and at
+%\url{http://tug.org/texlive/w32client.html}, which work just as well for
+%an \ISO\ as for a network installation.
+%On \MacOSX, TeXShop will be able to use the DVD
+%installation if a symlink \filename{/usr/texbin} points to the
+%appropriate binary directory, e.g.,
+%sudo ln -s /Volumes/MyTeXLive/bin/universal-darwin /usr/texbin
+%Historical note: \TL{} 2010 was the first \TL{} edition which was no
+%longer distributed `live'.  However, it always required some acrobatics
+%to run from \DVD\ or \ISO; in particular, there was no way around
+%setting at least one extra environment variable.  If you create your
+%\ISO\ from an existing installation then there is no need for this.
+\section{\cmdname{tlmgr}: Managing your installation}
+\caption{\prog{tlshell} \GUI, showing the Actions menu (\MacOSX)}
+\caption{\prog{tlcockpit} \GUI{} for \prog{tlmgr}}
+\caption{Legacy \prog{tlmgr} \GUI\ mode: main window, after `Load'}
+\TL{} includes a program named \prog{tlmgr} for managing \TL{} after the
+initial installation.  Its capabilities include:
+\item installing, updating, backing up, restoring, and uninstalling
+  individual packages, optionally taking dependencies into account;
+\item searching for and listing packages and their descriptions;
+\item listing, adding, and removing platforms;
+\item changing installation options such as paper size and source
+  location (see section~\ref{sec:location}).
+\prog{tlmgr}'s functionality completely subsumes the \prog{texconfig}
+program.  We still distribute and maintain \prog{texconfig} for the sake
+of anyone used to its interface, but we recommend using \prog{tlmgr}
+\subsection{\GUI{} interfaces for \cmdname{tlmgr}}
+\TL{} contains several \GUI{} front-ends for \prog{tlmgr}. Two notable
+ones: (1)~Figure~\ref{fig:tlshell} shows \cmdname{tlshell}, which is
+written in Tcl/Tk and runs out of the box under Windows and \MacOSX;
+(2)~Figure~\ref{fig:tlcockpit} shows \prog{tlcockpit}, which requires
+Java version~8 or higher and JavaFX. Both are separate packages.
+\prog{tlmgr} also has a native \GUI{} mode (shown in
+figure~\ref{fig:tlmgr-gui}), which is started with:
+> \Ucom{tlmgr -gui}
+However, this \GUI\ extension requires Perl/Tk, which module is no
+longer included in \TL's Perl distribution for Windows.
+\subsection{Sample \cmdname{tlmgr} command-line invocations}
+After the initial installation, you can update your system to the latest
+versions available with:
+> \Ucom{tlmgr update -all}
+If this makes you nervous, first try
+> \Ucom{tlmgr update -all -dry-run}
+or (less verbose):
+> \Ucom{tlmgr update -list}
+This more complex example adds a collection, for the engine \XeTeX, from
+a local directory:
+> \Ucom{tlmgr -repository /local/mirror/tlnet install collection-xetex}
+It generates the following output (abridged):
+install: collection-xetex
+install: arabxetex
+install: xetex
+install: xetexconfig
+install: xetex.i386-linux
+running post install action for xetex
+install: xetex-def
+running mktexlsr
+mktexlsr: Updating /usr/local/texlive/2021/texmf-dist/ls-R...
+running fmtutil-sys --missing
+Transcript written on xelatex.log.
+fmtutil: /usr/local/texlive/2021/texmf-var/web2c/xetex/xelatex.fmt installed.
+As you can see, \prog{tlmgr} installs dependencies, and takes care of any
+necessary post-install actions, including updating the filename database
+and (re)generating formats.  In the above, we generated new formats for
+To describe a package (or collection or scheme):
+> \Ucom{tlmgr show collection-latexextra}
+which produces output like this:
+package:    collection-latexextra
+category:   Collection
+shortdesc:  LaTeX supplementary packages
+longdesc:   A very large collection of add-on packages for LaTeX.
+installed:  Yes
+revision:   46963
+sizes:      657941k
+Last and most important, for full documentation see
+\url{https://tug.org/texlive/tlmgr.html}, or:
+> \Ucom{tlmgr -help}
+\section{Notes on Windows}
+\subsection{Windows-specific features}
+Under Windows, the installer does some extra things:
+\item[Menus and shortcuts.] A new `\TL{}' submenu of the
+  Start menu is installed, which contains entries for some \GUI{}
+  programs (\prog{tlmgr}, \prog{texdoctk} and some documentation.
+\item[File associations.] If enabled, \prog{TeXworks} and \prog{Dviout}
+  become either the default program for
+  their respective filetypes, or get an entry in the `Open with'
+  right-click menus of those filetypes.
+\item[Bitmap to eps converter.] Various bitmapped formats get an
+  entry \cmdname{bitmap2eps} in their `Open with' right-click
+  menu. Bitmap2eps is a simple script which lets \cmdname{sam2p} or
+  \cmdname{bmeps} do the real work.
+\item[Automatic path adjustment.] No manual configuration steps are required.
+\item[Uninstaller.] The installer creates an entry under `Add/Remove
+  Programs' for \TL. The uninstall tab of the \TeX\ Live Manager \GUI\
+  refers to this. For a single-user install, the installer also
+  creates an uninstall entry under the Start menu.
+\item[Write-protect.] For an admin install, the \TL\ directories are
+  write-protected, at least if \TL\ is installed on a normal
+  NTFS-formatted non-removable disk.
+Also, have a look at \filename{tlaunch}, described in
+section~\ref{sec:sharedinstall}, for a different approach.
+\subsection{Additional software included on Windows}
+To be complete, a \TL{} installation needs support packages that are not
+commonly found on a Windows machine. \TL{} provides the missing pieces.
+These programs are all installed as part of \TL{} only on Windows.
+\item[Perl and Ghostscript.] Because of the importance of Perl and
+  Ghostscript, \TL{} includes `hidden' copies of these
+  programs. \TL{} programs that need them know where to find them,
+  but they don't betray their presence through environment variables
+  or registry settings. They aren't full-scale installations, and
+  shouldn't interfere with any system installations of Perl or
+  Ghostscript.
+\item[dviout.] Also installed is \prog{dviout}, a DVI viewer.
+  At first, when you preview files with \cmdname{dviout}, it will create
+  fonts, because screen fonts were not installed. After a while, you
+  will have created most of the fonts you use, and you will rarely see
+  the font-creation window.  More information can be found in the
+  (highly recommended) on-line help.
+\item[\TeX{}works.]  \TeX{}works is a \TeX-oriented editor with
+  an integrated PDF viewer.
+\item[Command-line tools.] A number of Windows ports of common Unix
+  command-line programs are installed along with the usual \TL{}
+  binaries. These include \cmdname{gzip}, \cmdname{zip},
+  \cmdname{unzip}, and the utilities from the \cmdname{poppler} suite
+  (\cmdname{pdfinfo}, \cmdname{pdffonts}, \ldots); no standalone PDF
+  viewer for Windows is included.  One option for that is the Sumatra
+  PDF viewer, available from \url{https://sumatrapdfreader.org/}.
+\item[fc-list, fc-cache, \ldots] The tools from the fontconfig library allow
+  \XeTeX{} to handle system fonts on Windows.  You can use
+  \prog{fc-list} to determine the font names to pass to \XeTeX's
+  extended \cs{font} command. If necessary, run \prog{fc-cache}
+  first to update font information.
+\subsection{User Profile is Home}
+The Windows counterpart of a Unix home directory is the
+\verb|%USERPROFILE%| directory.  Under Windows Vista and later it is
+\verb|C:\Users\<username>|.  In the
+\filename{texmf.cnf} file, and \KPS{} in general, \verb|~| will
+expand appropriately on both Windows and Unix.
+\subsection{The Windows registry}
+Windows stores nearly all configuration data in its registry.  The
+registry contains a set of hierarchically organized keys, with several
+root keys. The most important ones for installation programs are
+\path{HKEY_CURRENT_USER} and \path{HKEY_LOCAL_MACHINE}, \path{HKCU} and
+\path{HKLM} in short. The \path{HKCU} part of the registry is in the
+user's home directory (see section~\ref{sec:winhome}).  \path{HKLM} is
+normally in a subdirectory of the Windows directory.
+In some cases, system information could be obtained from environment
+variables but for other information, for example the location of
+shortcuts, it is necessary to consult the registry.  Setting environment
+variables permanently also requires registry access.
+\subsection{Windows permissions}
+In later versions of Windows, a distinction is made between regular
+users and administrators, where only the latter have free access to almost the
+entire operating system. We have made an effort to make \TL{}
+installable without administrative privileges.
+If the installer is started with administrative permissions, there is an
+option to install for all users.  If this option is chosen, shortcuts
+are created for all users, and the system search path is
+modified. Otherwise, shortcuts and menu entries are created for the
+current user, and the user search path is modified.
+Regardless of administrator status, the default root of \TL{} proposed
+by the installer is always under \verb|%SystemDrive%|. The installer
+always tests whether the root is writable for the current user.
+A problem may arise if the user is not an administrator and \TeX{}
+already exists in the search path.  Since the effective search path
+consists of the system search path followed by the user search path, the
+new \TL{} would never get precedence.  As a fallback, the installer
+creates a shortcut to the command-prompt in which the new \TL{} binary
+directory is prepended to the local search path.  The new \TL{} will be
+always usable from within such a command-prompt. The shortcut for
+\TeX{}works, if installed, also prepends \TL{} to the search path, so it
+should also be immune to this path problem.
+You should be aware that even if you are logged in as administrator, you
+need to explicitly ask for administrator privileges. In fact, there is
+not much point in logging in as administrator. Instead, right-clicking
+on the program or shortcut that you want to run usually gives you a
+choice `Run as administrator'.
+\subsection{Increasing maximum memory on Windows and Cygwin}
+Windows and Cygwin (see section~\ref{sec:cygwin} for Cygwin installation
+specifics) users may find that they run out of memory when running some
+of the programs shipped with \TL.  For example, \prog{asy} might run out
+of memory if you try to allocate an array of 25,000,000 reals, and
+Lua\TeX\ might run out of memory if you try to process a document with a
+lot of big fonts.
+For Cygwin, you can increase the amount of available memory by following
+the instructions in the Cygwin User's Guide
+For Windows, you have to create a file, say \code{moremem.reg}, with
+these four lines:
+Windows Registry Editor Version 5.00
+\noindent and then execute the command \code{regedit /s moremem.reg} as
+administrator.  (If you want to change memory only for the current user
+instead of system-wide, use \code{HKEY\_CURRENT\_USER}.)
+\section{A user's guide to Web2C}
+\Webc{} is an integrated collection of \TeX-related programs: \TeX{}
+itself, \MF{}, \MP, \BibTeX{}, etc.  It is the heart of \TL{}.  The home
+page for \Webc{}, with the current manual and more, is
+A bit of history: The original implementation was by Tomas Rokicki who,
+in 1987, developed a first \TeX{}-to-C system based on change files
+under Unix, which were primarily the original work of Howard Trickey and
+Pavel Curtis.  Tim Morgan became the maintainer of the system, and
+during this period the name changed to Web-to-C\@.  In 1990, Karl Berry
+took over the work, assisted by dozens of additional contributors, and
+in 1997 he handed the baton to Olaf Weber, who returned it to Karl in
+The \Webc{} system runs on Unix, 32-bit Windows systems, \MacOSX{}, and
+other operating systems. It uses Knuth's original sources for \TeX{} and
+other basic programs written in the \web{} literate programming system
+and translates them into C source code.  The core \TeX{} programs
+handled in this way are:
+\item[bibtex]    Maintaining bibliographies.
+\item[dvicopy]   Expands virtual font references in \dvi{} files.
+\item[dvitomp]   \dvi{} to MPX (MetaPost pictures).
+\item[dvitype]   \dvi{} to human-readable text.
+\item[gftodvi]   Generic font proofsheets.
+\item[gftopk]    Generic to packed fonts.
+\item[gftype]    GF to human-readable text.
+\item[mf]        Creating typeface families.
+\item[mft]       Prettyprinting \MF{} source.
+\item[mpost]     Creating technical diagrams.
+\item[patgen]    Creating hyphenation patterns.
+\item[pktogf]    Packed to generic fonts.
+\item[pktype]    PK to human-readable text.
+\item[pltotf]    Plain text property list to TFM.
+\item[pooltype]  Display \web{} pool files.
+\item[tangle]    \web{} to Pascal.
+\item[tex]       Typesetting.
+\item[tftopl]    TFM to plain text property list.
+\item[vftovp]    Virtual font to virtual property list.
+\item[vptovf]    Virtual property list to virtual font.
+\item[weave]     \web{} to \TeX.
+\noindent The precise functions and syntax of these programs are
+described in the documentation of the individual packages and of \Webc{}
+itself.  However, knowing a few principles governing the whole family of
+programs will help you take advantage of your \Webc{} installation.
+All programs honor these standard \GNU options:
+\item[-{}-help] print basic usage summary.
+\item[-{}-version] print version information, then exit.
+And most also honor:
+\item[-{}-verbose] print detailed progress report.
+For locating files the \Webc{} programs use the path searching library
+\KPS{} (\url{https://tug.org/kpathsea}).  This library uses a combination
+of environment variables and configuration files to optimize searching
+the (huge) collection of \TeX{} files.  \Webc{} can look at many
+directory trees simultaneously, which is useful in maintaining \TeX's
+standard distribution and local and personal extensions in distinct
+trees.  To speed up file searches, the root of each tree has a file
+\file{ls-R}, containing an entry showing the name and relative pathname
+for all files under that root.
+\subsection{Kpathsea path searching}
+Let us first describe the generic path searching mechanism of the \KPS{}
+We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list
+of \emph{path elements}, which are basically directory names.  A
+search path can come from (a combination of) many sources.  To look up
+a file \samp{my-file} along a path \samp{.:/dir}, \KPS{} checks each
+element of the path in turn: first \file{./my-file}, then
+\file{/dir/my-file}, returning the first match (or possibly all
+In order to adapt optimally to all operating systems' conventions, on
+non-Unix systems \KPS{} can use filename separators different from
+colon (\samp{:}) and slash (\samp{/}).
+To check a particular path element \var{p}, \KPS{} first checks if a
+prebuilt database (see ``Filename data\-base'' on
+page~\pageref{sec:filename-database}) applies to \var{p}, i.e., if the
+database is in a directory that is a prefix of \var{p}.  If so, the path
+specification is matched against the contents of the database.
+Although the simplest and most common path element is a directory
+name, \KPS{} supports additional features in search paths: layered
+default values, environment variable names, config file values, users'
+home directories, and recursive subdirectory searching.  Thus, we say
+that \KPS{} \emph{expands} a path element, meaning it transforms all
+the specifications into basic directory name or names.  This is
+described in the following sections in the same order as it takes
+Note that if the filename being searched for is absolute or explicitly
+relative, i.e., starts with \samp{/} or \samp{./} or \samp{../},
+\KPS{} simply checks if that file exists.
+  \caption{An illustrative configuration file sample}
+  \label{fig:config-sample}
+\subsubsection{Path sources}
+A search path can come from many sources.  In the order in which
+\KPS{} uses them:
+  A user-set environment variable, for instance, \envname{TEXINPUTS}\@.
+  Environment variables with a period and a program name appended
+  override; e.g., if \samp{latex} is the name of the program being run,
+  then \envname{TEXINPUTS.latex} will override \envname{TEXINPUTS}.
+  A program-specific configuration file, for exam\-ple, a line
+  \samp{S /a:/b} in \cmdname{dvips}'s \file{config.ps}.
+\item   A \KPS{} configuration file \file{texmf.cnf}, containing a line like
+  \samp{TEXINPUTS=/c:/d} (see below).
+\item The compile-time default.
+\noindent You can see each of these values for a given search path by
+using the debugging options (see ``Debugging actions'' on
+\subsubsection{Config files}
+\KPS{} reads \emph{runtime configuration files} named \file{texmf.cnf}
+for search path and other definitions.  The search path
+\envname{TEXMFCNF} is used to look for these files, but we do not
+recommend setting this (or any) environment variable to override the
+system directories.
+Instead, normal installation results in a file
+\file{.../2021/texmf.cnf}.  If you must make changes to the defaults
+(not normally necessary), this is the place to put them.  The main
+configuration file is in \file{.../2021/texmf-dist/web2c/texmf.cnf}.
+You should not edit this latter file, as your changes will be lost when
+the distributed version is updated.
+As an aside, if you merely wish to add a personal directory to a
+particular search path, setting an environment variable is a reasonable
+  TEXINPUTS=.:/my/macro/dir:
+To keep the setting maintainable and portable over the years, use a
+trailing \samp{:} (\samp{;} on Windows) to insert the system paths,
+instead of trying to write them all out explicitly (see
+section~\ref{sec:default-expansion}). Another option is to use the
+\envname{TEXMFHOME} tree (see section~\ref{sec:directories}).
+\emph{All} \file{texmf.cnf} files in the search path will be read and
+definitions in earlier files override those in later files.  For
+example, with a search path of \verb|.:$TEXMF|, values from
+\file{./texmf.cnf} override those from \verb|$TEXMF/texmf.cnf|.
+  Comments start with \code{\%}, either at the beginning of a line or
+  preceded by whitespace, and continue to the end of the line.
+  Blank lines are ignored.
+  A \bs{} at the end of a line acts as a continuation character,
+  i.e., the next line is appended.  Whitespace at the beginning of
+  continuation lines is not ignored.
+  Each remaining line has the form:\\
+  \hspace*{2em}\texttt{\var{variable} \textrm{[}.\var{progname}\textrm{]}
+  \textrm{[}=\textrm{]} \var{value}}\\[1pt]
+  where the \samp{=} and surrounding whitespace are optional.
+  (But if \var{value} begins with \samp{.}, it is simplest to use the
+  \samp{=} to avoid the period being interpreted as the program name
+  qualifier.)
+  The \ttvar{variable} name may contain any character other
+  than whitespace, \samp{=}, or \samp{.}, but sticking to
+  \samp{A-Za-z\_} is safest.
+  If \samp{.\var{progname}} is present, the definition only
+  applies if the program that is running is named
+  \texttt{\var{progname}} or \texttt{\var{progname}.exe}.  This allows
+  different flavors of \TeX{} to have different search paths, for
+  example.
+\item Considered as strings, \var{value} may contain any character.
+  However, in practice most \file{texmf.cnf} values are related to path
+  expansion, and since various special characters are used in expansion
+  (see section~\ref{sec:cnf-special-chars}), such as braces and commas,
+  they cannot be used in directory names.
+  A \samp{;} in \var{value} is translated to \samp{:} if running under
+  Unix, in order to have a single \file{texmf.cnf} that can support both
+  Unix and Windows systems. This translation happens with any value, not
+  just search paths, but fortunately in practice \samp{;} is not needed
+  in other values.
+  The \code{\$\var{var}.\var{prog}} feature is not available on the
+  right-hand side; instead, you must use an additional variable.
+  All definitions are read before anything is expanded, so
+  variables can be referenced before they are defined.
+A configuration file fragment illustrating most of these points is
+shown below:
+shown in figure~\ref{fig:config-sample}.
+\subsubsection{Path expansion}
+\KPS{} recognizes certain special characters and constructions in
+search paths, similar to those available in Unix shells.  As a
+general example, the path
+\verb+~$USER/{foo,bar}//baz+, expands to all subdirectories under
+directories \file{foo} and \file{bar} in \texttt{\$USER}'s home
+directory that contain a directory or file \file{baz}.  These
+expansions are explained in the sections below.
+\subsubsection{Default expansion}
+If the highest-priority search path (see ``Path sources'' on
+page~\pageref{sec:path-sources}) contains an \emph{extra colon} (i.e.,
+leading, trailing, or doubled), \KPS{} inserts at that point the
+next-highest-prio\-rity search path that is defined.  If that inserted
+path has an extra colon, the same happens with the next highest.  For
+example, given an environment variable setting
+> \Ucom{setenv TEXINPUTS /home/karl:}
+and a \code{TEXINPUTS} value from \file{texmf.cnf} of
+  .:\$TEXMF//tex
+then the final value used for searching will be:
+  /home/karl:.:\$TEXMF//tex
+Since it would be useless to insert the default value in more than one
+place, \KPS{} changes only one extra \samp{:}\ and leaves any others in
+place.  It checks first for a leading \samp{:}, then a trailing
+\samp{:}, then a doubled \samp{:}.
+\subsubsection{Brace expansion}
+A useful feature is brace expansion, which means that, for instance,
+\verb+v{a,b}w+ expands to \verb+vaw:vbw+. Nesting is allowed.
+This is used to implement multiple \TeX{} hierarchies, by
+assigning a brace list to \code{\$TEXMF}.
+In the distributed \file{texmf.cnf}, a definition like this
+(simplified for this example) is made:
+We then use this to define, for example, the \TeX\ input path:
+  TEXINPUTS = .;$TEXMF/tex//
+which means that, after looking in the current directory, the
+\code{\$TEXMFVAR/tex}, \code{\$TEXMFHOME/tex}, \code{\$TEXMFLOCAL/tex}
+and \code{\$TEXMFDIST/tex} trees will be searched (the
+last two using \file{ls-R} data base files).
+\subsubsection{Subdirectory expansion}
+Two or more consecutive slashes in a path element following a directory
+\var{d} is replaced by all subdirectories of \var{d\/}: first those
+subdirectories directly under \var{d}, then the subsubdirectories under
+those, and so on.  At each level, the order in which the directories are
+searched is \emph{unspecified}.
+If you specify any filename components after the \samp{//}, only
+subdirectories with matching components are included.  For example,
+\samp{/a//b} expands into directories \file{/a/1/b}, \file{/a/2/b},
+\file{/a/1/1/b}, and so on, but not \file{/a/b/c} or \file{/a/1}.
+Multiple \samp{//} constructs in a path are possible, but
+\samp{//} at the beginning of a path is ignored.
+\subsubsection{Summary of special characters in \file{texmf.cnf} files}
+The following list summarizes the special characters and constructs in
+\KPS{} configuration files.
+% need a wider space for the item labels here.
+\item[\CODE{:}] Separator in path specification; at the beginning or
+  the end of a path, or doubled in the middle, it substitutes the
+  default path expansion.\par
+\item[\CODE{;}] Separator on non-Unix systems (acts like \code{:}).
+\item[\CODE{\$}] Variable expansion.
+\item[\CODE{\string~}] Represents the user's home directory.
+\item[\CODE{\char`\{...\char`\}}] Brace expansion.
+\item[\CODE{,}] Separates items in brace expansion.
+\item[\CODE{//}] Subdirectory expansion (can occur anywhere in
+    a path, except at its beginning).
+\item[\CODE{\%}] Start of comment.
+\item[\CODE{\bs}] At the end of a line, continuation character to allow
+    multi-line entries.
+\item[\CODE{!!}] Search \emph{only} database to locate file, \emph{do
+    not} search the disk.
+Exactly when a character will be considered special or act as itself
+depends on the context in which it is used. The rules are inherent in
+the multiple levels of interpretation of the configuration (parsing,
+expansion, search, \ldots)\ and so cannot be concisely stated,
+unfortunately. There is no general escape mechanism; in particular,
+\samp{\bs} is not an ``escape character'' in \file{texmf.cnf} files.
+When it comes choosing directory names for installation, it is safest to
+avoid them all.
+\subsection{Filename databases}
+\KPS{} goes to some lengths to minimize disk accesses for searches.
+Nevertheless, in the standard \TL, or at any installation with enough
+directories, searching every possible directory for a given file will
+take an excessively long time. Therefore, \KPS{} can use an
+externally-built plain text ``database'' file named \file{ls-R} that
+maps files to directories, thus avoiding the need to exhaustively search
+the disk.
+A second database file \file{aliases} allows you to give additional
+names to the files listed in \file{ls-R}.
+\subsubsection{The filename database}
+As explained above, the name of the main filename database must be
+\file{ls-R}.  You can put one at the root of each \TeX{} hierarchy in
+your installation that you wish to be searched (\code{\$TEXMF} by
+default).  \KPS{} looks for
+\file{ls-R} files along the \code{TEXMFDBS} path.
+The recommended way to create and maintain \samp{ls-R} is to run the
+\code{mktexlsr} script included with the distribution. It is invoked
+by the various \samp{mktex}\dots\ scripts.  In principle, this script
+just runs the command
+cd \var{/your/texmf/root} && \path|\|ls -1LAR ./ >ls-R
+presuming your system's \code{ls} produces the right output format
+(\GNU \code{ls} is all right).  To ensure that the database is
+always up-to-date, it is easiest to rebuild it regularly via
+\code{cron}, so that it is automatically updated when the installed
+files change, such as after installing or updating a \LaTeX{} package.
+If a file is not found in the database, by default \KPS{} goes ahead
+and searches the disk. If a particular path element begins with
+\samp{!!}, however, \emph{only} the database will be searched for that
+element, never the disk.
+\subsubsection{kpsewhich: Standalone path searching}
+The \texttt{kpsewhich} program exercises path searching independent of any
+particular application.  This can be useful as a sort of \code{find}
+program to locate files in \TeX{} hierarchies (this is used heavily in
+the distributed \samp{mktex}\dots\ scripts).
+> \Ucom{kpsewhich \var{option}\dots{} \var{filename}\dots{}}
+The options specified in \ttvar{option} start with either \samp{-}
+or \samp{-{}-}, and any unambiguous abbreviation is accepted.
+\KPS{} looks up each non-option argument on the command line as a
+filename, and returns the first file found. There is no option to
+return all the files with a particular name (you can run the Unix
+\samp{find} utility for that).
+The most common options are described next.
+  Set the resolution to \ttvar{num}; this only affects \samp{gf}
+  and \samp{pk} lookups.  \samp{-D} is a synonym, for compatibility
+  with \cmdname{dvips}.  Default is 600.
+  Set the format for lookup to \ttvar{name}.  By default, the
+  format is guessed from the filename. For formats which do not have
+  an associated unambiguous suffix, such as \MP{} support files and
+  \cmdname{dvips} configuration files, you have to specify the name as
+  known to \KPS{}, such as \texttt{tex} or \texttt{enc files}.  Run
+  \texttt{kpsewhich -{}-help-formats} for a list.
+  Set the mode name to \ttvar{string}; this only affects \samp{gf}
+  and \samp{pk} lookups.  No default: any mode will be found.
+  Do everything possible to find the files, notably including
+  searching the disk.  By default, only the \file{ls-R} database is
+  checked, in the interest of efficiency.
+  Search along the path \ttvar{string} (colon-separated as usual),
+  instead of guessing the search path from the filename.  \samp{//} and
+  all the usual expansions are supported.  The options \samp{-{}-path}
+  and \samp{-{}-format} are mutually exclusive.
+  Set the program name to \texttt{\var{name}}.
+  This can affect the search paths via the \texttt{.\var{progname}}
+  feature.
+  The default is \cmdname{kpsewhich}.
+  shows the path used for file lookups of file type \texttt{\var{name}}.
+  Either a filename extension (\code{.pk}, \code{.vf}, etc.) or a
+  name can be used, just as with \samp{-{}-format} option.
+  sets the debugging options to \texttt{\var{num}}.
+\subsubsection{Examples of use}
+Let us now have a look at \KPS{} in action.  Here's a straightforward search:
+> \Ucom{kpsewhich article.cls}
+   /usr/local/texmf-dist/tex/latex/base/article.cls
+We are looking for the file \file{article.cls}. Since the \samp{.cls}
+suffix is unambiguous we do not need to specify that we want to look for a
+file of type \optname{tex} (\TeX{} source file directories). We find it in
+the subdirectory \file{tex/latex/base} below the \samp{texmf-dist} \TL\
+directory.  Similarly, all of the following are found without problems
+thanks to their unambiguous suffix.
+> \Ucom{kpsewhich array.sty}
+   /usr/local/texmf-dist/tex/latex/tools/array.sty
+> \Ucom{kpsewhich latin1.def}
+   /usr/local/texmf-dist/tex/latex/base/latin1.def
+> \Ucom{kpsewhich size10.clo}
+   /usr/local/texmf-dist/tex/latex/base/size10.clo
+> \Ucom{kpsewhich small2e.tex}
+   /usr/local/texmf-dist/tex/latex/base/small2e.tex
+> \Ucom{kpsewhich tugboat.bib}
+   /usr/local/texmf-dist/bibtex/bib/beebe/tugboat.bib
+By the way, that last is a \BibTeX{} bibliography database for
+\textsl{TUGboat} articles.
+> \Ucom{kpsewhich cmr10.pk}
+Font bitmap glyph files of type \file{.pk} are used by display
+programs like \cmdname{dvips} and \cmdname{xdvi}.  Nothing is returned in
+this case since there are no pre-generated Computer Modern \samp{.pk}
+files in \TL{}\Dash the Type~1 variants are used by default.
+> \Ucom{kpsewhich wsuipa10.pk}
+\ifSingleColumn   /usr/local/texmf-var/fonts/pk/ljfour/public/wsuipa/wsuipa10.600pk
+\else /usr/local/texmf-var/fonts/pk/ljfour/public/
+...                         wsuipa/wsuipa10.600pk
+For these fonts (a phonetic alphabet from the University of Washington)
+we had to generate \samp{.pk} files, and since the default \MF{} mode on
+our installation is \texttt{ljfour} with a base resolution of 600\dpi{}
+(dots per inch), this instantiation is returned.
+> \Ucom{kpsewhich -dpi=300 wsuipa10.pk}
+In this case, when specifying that we are interested in a resolution
+of 300\dpi{} (\texttt{-dpi=300}) we see that no such font is available on
+the system. A program like \cmdname{dvips} or \cmdname{xdvi} would
+go off and actually build the required \texttt{.pk} files
+using the script \cmdname{mktexpk}.
+Next we turn our attention to \cmdname{dvips}'s header and configuration
+files.  We first look at one of the commonly used files, the general
+prologue \file{tex.pro} for \TeX{} support, before turning our attention
+to the generic configuration file (\file{config.ps}) and the \PS{} font
+map \file{psfonts.map}\Dash as of 2004, map and encoding files have
+their own search paths and new location in \dirname{texmf} trees.  As
+the \samp{.ps} suffix is ambiguous we have to specify explicitly which
+type we are considering (\optname{dvips config}) for the file
+> \Ucom{kpsewhich tex.pro}
+   /usr/local/texmf/dvips/base/tex.pro
+> \Ucom{kpsewhich --format="dvips config" config.ps}
+   /usr/local/texmf/dvips/config/config.ps
+> \Ucom{kpsewhich psfonts.map}
+   /usr/local/texmf/fonts/map/dvips/updmap/psfonts.map
+We now take a closer look at the URW Times \PS{} support
+files.  The prefix for these in the standard font naming scheme is
+\samp{utm}.  The first file we look at is the configuration file,
+which contains the name of the map file:
+> \Ucom{kpsewhich --format="dvips config" config.utm}
+   /usr/local/texmf-dist/dvips/psnfss/config.utm
+The contents of that file is
+  p +utm.map
+which points to the file \file{utm.map}, which we want to
+locate next.
+> \Ucom{kpsewhich utm.map}
+   /usr/local/texmf-dist/fonts/map/dvips/times/utm.map
+This map file defines the file names of the Type~1 \PS{} fonts in
+the URW collection.  Its contents look like (we only show part of the
+utmb8r  NimbusRomNo9L-Medi    ... <utmb8a.pfb
+utmbi8r NimbusRomNo9L-MediItal... <utmbi8a.pfb
+utmr8r  NimbusRomNo9L-Regu    ... <utmr8a.pfb
+utmri8r NimbusRomNo9L-ReguItal... <utmri8a.pfb
+utmbo8r NimbusRomNo9L-Medi    ... <utmb8a.pfb
+utmro8r NimbusRomNo9L-Regu    ... <utmr8a.pfb
+Let us, for instance, take the Times Roman instance
+\file{utmr8a.pfb} and find its position in the \file{texmf} directory
+tree with a search for Type~1 font files:
+> \Ucom{kpsewhich utmr8a.pfb}
+\ifSingleColumn   /usr/local/texmf-dist/fonts/type1/urw/times/utmr8a.pfb
+\else   /usr/local/texmf-dist/fonts/type1/
+... urw/utm/utmr8a.pfb
+It should be evident from these examples how you can easily locate the
+whereabouts of a given file. This is especially important if you suspect
+that the wrong version of a file is picked up somehow, since
+\cmdname{kpsewhich} will show you the first file encountered.
+\subsubsection{Debugging actions}
+Sometimes it is necessary to investigate how a program resolves file
+references. To make this practical, \KPS{} offers various levels of
+debugging output:
+\item[\texttt{\ 1}] \texttt{stat} calls (disk lookups). When running
+  with an up-to-date \file{ls-R} database this should almost give no
+  output.
+\item[\texttt{\ 2}] References to hash tables (such as \file{ls-R}
+  databases, map files, configuration files).
+\item[\texttt{\ 4}] File open and close operations.
+\item[\texttt{\ 8}] General path information for file types
+  searched by \KPS. This is useful to find out where a particular
+  path for the file was defined.
+\item[\texttt{16}] Directory list for each path element (only relevant
+  for searches on disk).
+\item[\texttt{32}] File searches.
+\item[\texttt{64}] Variable values.
+A value of \texttt{-1} will set all the above options; in practice,
+this is usually the most convenient.
+Similarly, with the \cmdname{dvips} program, by setting a combination of
+debug switches, one can follow in detail where files are being picked up
+from.  Alternatively, when a file is not found, the debug trace shows in
+which directories the program looks for the given file, so that one can
+get an indication what the problem~is.
+Generally speaking, as most programs call the \KPS{} library
+internally, one can select a debug option by using the
+\envname{KPATHSEA\_DEBUG} environment variable, and setting it to (a
+combination of) values as described in the above list.
+(Note for Windows users: it is not easy to redirect
+all messages to a file in this system. For diagnostic purposes
+you can temporarily \texttt{SET KPATHSEA\_DEBUG\_OUTPUT=err.log}).
+Let us consider, as an example, a small \LaTeX{} source file,
+\file{hello-world.tex}, which contains the following input.
+  \documentclass{article}
+  \begin{document}
+  Hello World!
+  \end{document}
+This little file only uses the font \file{cmr10}, so let us look at
+how \cmdname{dvips} prepares the \PS{} file (we want to use the Type~1
+version of the Computer Modern fonts, hence the option \texttt{-Pcms}).
+> \Ucom{dvips -d4100 hello-world -Pcms -o}
+In this case we have combined \cmdname{dvips}'s debug class 4 (font
+paths) with \KPS's path element expansion (see the \cmdname{dvips}
+reference manual).
+The output (slightly rearranged) appears in
+\caption{Finding configuration files}\label{fig:dvipsdbga}
+\cmdname{dvips} starts by locating its working files. First,
+\file{texmf.cnf} is found, which gives the definitions of the search
+paths for the other files, then the file database \file{ls-R} (to
+optimize file searching) and the file \file{aliases}, which makes it
+possible to declare several names (e.g., a short DOS-like 8.3 and
+a more natural longer version) for the same file.  Then \cmdname{dvips}
+goes on to find the generic configuration file \file{config.ps}
+before looking for the customization file \file{.dvipsrc} (which, in
+this case is \emph{not found}).  Finally, \cmdname{dvips} locates the
+config file for the Computer Modern \PS{} fonts \file{config.cms}
+(this was initiated with the \texttt{-Pcms} option on the \cmdname{dvips}
+command).  This file contains the list of the map files which
+define the relation between the \TeX{}, \PS{} and file system
+names of the fonts.
+> \Ucom{more /usr/local/texmf/dvips/cms/config.cms}
+   p +ams.map
+   p +cms.map
+   p +cmbkm.map
+   p +amsbkm.map
+\cmdname{dvips} thus goes on to find all these files, plus the generic
+map file \file{psfonts.map}, which is always loaded (it contains
+declarations for commonly used \PS{} fonts; see the last part of
+section~\ref{sec:examples-of-use} for more details about \PS{} map
+file handling).
+At this point \cmdname{dvips} identifies itself to the user:
+This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com)
+Then it goes on to look for the prolog file \file{texc.pro}:
+kdebug:start search(file=texc.pro, must\_exist=0, find\_all=0,
+  path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
+       ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
+kdebug:search(texc.pro) => /usr/local/texmf/dvips/base/texc.pro
+Then it goes on to look for the prolog file \file{texc.pro} (see
+After having found the file in question, \cmdname{dvips} outputs
+the date and time, and informs us that it will generate the
+file \file{hello-world.ps}, then that it needs the font file
+\file{cmr10}, and that the latter is declared as ``resident'' (no
+bitmaps needed):
+TeX output 1998.02.26:1204' -> hello-world.ps
+Defining font () cmr10 at 10.0pt
+Font cmr10 <CMR10> is resident.
+Now the search is on for the file \file{cmr10.tfm}, which is found,
+then a few more prolog files (not shown) are referenced, and finally
+the Type~1 instance \file{cmr10.pfb} of the font is located and
+included in the output file (see last line).
+kdebug:start search(file=cmr10.tfm, must\_exist=1, find\_all=0,
+  path=.:~/tex/fonts/tfm//:!!/usr/local/texmf/fonts/tfm//:
+       /var/tex/fonts/tfm//).
+kdebug:search(cmr10.tfm) => /usr/local/texmf/fonts/tfm/public/cm/cmr10.tfm
+kdebug:start search(file=texps.pro, must\_exist=0, find\_all=0,
+   ...
+kdebug:start search(file=cmr10.pfb, must\_exist=0, find\_all=0,
+  path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
+       ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
+kdebug:search(cmr10.pfb) => /usr/local/texmf/fonts/type1/public/cm/cmr10.pfb
+\subsection{Runtime options}
+Another useful feature of \Webc{} is its possibility to control a number
+of memory parameters (in particular, array sizes) via the runtime file
+\file{texmf.cnf} read by \KPS{}.  The memory settings can be found in
+Part~3 of that file in the \TL{} distribution. The more important
+  Total words of memory available, for
+  \TeX{}, \MF{} and \MP.  You must make a new format file for each
+  different setting. For instance, you could generate a ``huge''
+  version of \TeX{}, and call the format file \texttt{hugetex.fmt}.
+  Using the standard way of specifying the program name used by \KPS{},
+  the particular value of the \texttt{main\_memory} variable will then
+  be read from \file{texmf.cnf}.
+  Extra space for ``large'' \TeX{} data structures:
+  boxes, glue, breakpoints, etc.  Especially useful if you use
+  \PiCTeX{}.
+  Number of words for font information available for \TeX. This
+  is more or less the total size of all TFM files read.
+  Additional space for the hash table of control sequence names; its
+  default value is \texttt{600000}.
+\noindent This facility is no substitute for truly dynamic
+arrays and memory allocation, but since these are extremely difficult to
+implement in the present \TeX{} source, these runtime parameters provide
+a practical compromise allowing some flexibility.
+In various places above, we gave various search paths starting with
+\code{.} (to search the current directory first), as in
+This is a simplification. The \code{texmf.cnf} file we distribute in
+\TL{} uses \filename{$TEXMFDOTDIR} instead of just \samp{.}, as in:
+(In the distributed file, the second path element is also slightly more
+complicated than \filename{$TEXMF/tex//}. But that's minor; here we want
+to discuss the \filename{$TEXMFDOTDIR} feature.)
+The reason to use the variable \filename{$TEXMFDOTDIR} in the path
+definitions instead of simply \samp{.} is purely so that it can be
+overridden. For example, a complex document may have many source files
+arranged in many subdirectories. To handle that, you can set
+\filename{TEXMFDOTDIR} to \filename{.//} (for example, in the environment when
+you build the document) and they will all get searched. (Warning: don't
+use \filename{.//} by default; it's usually highly undesirable, and
+potentially insecure, to search through all subdirectories for an
+arbitrary document.)
+As another example, you may wish not to search the current directory at
+all, e.g., if you have arranged for all the files to be found via
+explicit paths. You can set \filename{$TEXMFDOTDIR} to, say,
+\filename{/nonesuch} or any nonexistent directory for this.
+The default value of \filename{$TEXMFDOTDIR} is just \samp{.}, as set in our
+\TL{} is a joint effort by virtually all of the \TeX{} user groups.
+This edition of \TL{} was overseen by Karl Berry.  The other principal
+contributors, past and present, are listed below.
+\item The English, German, Dutch, and Polish \TeX{} user groups
+(TUG, DANTE e.V., NTG, and GUST,
+respectively), which provide the necessary technical and administrative
+infrastructure.  Please join the \TeX\ user group near you!  (See
+\item The CTAN team (\url{https://ctan.org}), which distributes
+the \TL{} images and provides the common infrastructure for package
+updates, upon which \TL{} depends.
+\item Nelson Beebe, for making many platforms available to \TL\
+developers, and his own comprehensive testing and unparalleled
+bibliographic efforts.
+\item John Bowman, for making many changes to his advanced graphics
+program Asymptote to make it work in \TL.
+\item Peter Breitenlohner and the \eTeX\ team for the stable foundation
+of future \TeX's, and Peter specifically for years of stellar help with
+\GNU\ autotools and keeping sources up to date.  Peter passed away in
+October 2015, and we dedicate the continuing work to his memory.
+\item Jin-Hwan Cho and all of the DVIPDFM$x$ team, for their
+excellent driver and responsiveness to configuration issues.
+\item Thomas Esser, without whose marvelous \teTeX{} package \TL{}
+would have never existed.
+\item Michel Goossens, who co-authored the original documentation.
+\item Eitan Gurari, whose \TeX4ht is used to create the \HTML{}
+version of this documentation, and who worked tirelessly to improve it
+at short notice, every year.  Eitan prematurely passed away in June
+2009, and we dedicate this documentation to his memory.
+\item Hans Hagen, for much testing and making his \ConTeXt\ package
+(\url{https://pragma-ade.com}) work within \TL's framework, and
+continually driving \TeX\ development.
+\item \Thanh, Martin Schr\"oder, and the pdf\TeX\ team
+(\url{http://pdftex.org}), for continuing enhancements of \TeX's
+\item Hartmut Henkel, for significant development contributions to
+pdf\TeX\, Lua\TeX, and more.
+\item Shunshaku Hirata, for much original and continuing work on DVIPDFM$x$.
+\item Taco Hoekwater, for major renewed development efforts on MetaPost and
+(Lua)\TeX\ (\url{http://luatex.org}) itself, incorporating
+\ConTeXt\ into \TL, giving Kpathsea multi-threaded functionality, and
+much more.
+\item Khaled Hosny, for substantial work on \XeTeX, DVIPDFM$x$, and
+efforts with Arabic and other fonts.
+\item Pawe{\l} Jackowski, for the Windows installer \cmdname{tlpm},
+and Tomasz {\L}uczak, for \cmdname{tlpmgui}, used in past releases.
+\item Akira Kakuto, for providing the Windows
+binaries from his W32TEX and W64TEX distributions for Japanese \TeX\
+(\url{http://w32tex.org}), and many other development contributions.
+\item Jonathan Kew, for developing the remarkable \XeTeX{} engine and
+taking the time and trouble to integrate it in \TL{}, as well as the
+initial version of the Mac\TeX\ installer, and also for our recommended
+front-end \TeX{}works.
+\item Hironori Kitagawa, for maintenance of (e)p\TeX\ and related support.
+\item Dick Koch, for maintaining Mac\TeX\ (\url{https://tug.org/mactex})
+in very close tandem with \TL{}, and for his great good cheer in doing
+\item Reinhard Kotucha, for major contributions to the \TL{} 2008
+infrastructure and installer, as well as Windows research efforts, the
+\texttt{getnonfreefonts} script, and more.
+\item Siep Kroonenberg, also for major contributions to the \TL{} 2008
+infrastructure and installer, especially on Windows, and for the bulk of
+work updating this manual describing those features.
+\item Clerk Ma, for engine bug fixes and extensions.
+\item Mojca Miklavec, for much help with \ConTeXt, building many binary
+sets, and plenty more.
+\item Heiko Oberdiek, for the \pkgname{epstopdf} package and many
+others, compressing the huge \pkgname{pst-geo} data files so we could
+include them, and most of all, for his remarkable work on
+\item Phelype Oleinik, for the group-delimited \cs{input} across engines
+in 2020, and more.
+\item Petr Ol\v{s}ak, who coordinated and checked all the Czech and Slovak
+material very carefully.
+\item Toshio Oshima, for his \cmdname{dviout} previewer for Windows.
+\item Manuel P\'egouri\'e-Gonnard, for helping with package updates,
+documentation improvements, and \cmdname{texdoc} development.
+\item Fabrice Popineau, for the original Windows support in \TL{} and
+work on the French documentation.
+\item Norbert Preining, the principal architect of the current \TL{}
+infrastructure and installer, and also for coordinating the Debian
+version of \TL{} (together with Frank K\"uster), and doing so much work
+along the way.
+\item Sebastian Rahtz, for originally creating \TL{} and maintaining it
+for many years.  Sebastian passed away in March 2016, and we dedicate
+the continuing work to his memory.
+\item Luigi Scarso, for continuing development of MetaPost, Lua\TeX, and
+much more.
+\item Andreas Scherer, for \texttt{cwebbin}, the CWEB implementation
+used in \TL{}, and continuing maintenance of the original CWEB.
+\item Takuji Tanaka, for maintenance of (e)(u)p\TeX\ and related support.
+\item Tomasz Trzeciak, for wide-ranging help with Windows.
+\item Vladimir Volovich, for substantial help with porting and other
+maintenance issues, and especially for making it feasible to include
+\item Staszek Wawrykiewicz, a principal tester for all of \TL{},
+and coordinator of the many major Polish contributions: fonts, Windows
+installation, and more.  Staszek passed away in February 2018, and we
+dedicate the continuing work to his memory.
+\item Olaf Weber, for his patient maintenance of \Webc\ in past years.
+\item Gerben Wierda, for creating and maintaining the original \MacOSX\
+\item Graham Williams, the originator of the \TeX\ Catalogue.
+\item Joseph Wright, for much work on making the same primitive
+functionality available across engines.
+\item Hironobu Yamashita, for much work on p\TeX\ and related support.
+Builders of the binaries:
+Marc Baudoin (\pkgname{amd64-netbsd}, \pkgname{i386-netbsd}),
+Ken Brown (\pkgname{i386-cygwin}, \pkgname{x86\_64-cygwin}),
+Simon Dales (\pkgname{armhf-linux}),
+Johannes Hielscher (\pkgname{aarch64-linux}),
+Akira Kakuto (\pkgname{win32}),
+Dick Koch (\pkgname{universal-darwin}),
+Mojca Miklavec (\pkgname{amd64-freebsd},
+                \pkgname{i386-freebsd},
+                \pkgname{x86\_64-darwinlegacy},
+                \pkgname{i386-solaris}, \pkgname{x86\_64-solaris},
+                \pkgname{sparc-solaris}),
+Norbert Preining (\pkgname{i386-linux},
+                  \pkgname{x86\_64-linux},
+                  \pkgname{x86\_64-linuxmusl}).
+For information on the \TL{} build process, see
+Translators of this manual:
+Takuto Asakura (Japanese),
+Denis Bitouz\'e \& Patrick Bideault (French),
+Carlos Enriquez Figueras (Spanish),
+Jjgod Jiang, Jinsong Zhao, Yue Wang, \& Helin Gai (Chinese),
+Nikola Le\v{c}i\'c (Serbian),
+Marco Pallante \& Carla Maggi (Italian),
+Petr Sojka \& Jan Busa (Czech\slash Slovak),
+Boris Veytsman (Russian),
+Zofia Walczak (Polish),
+Uwe Ziegenhagen (German).  The \TL{} documentation web page
+is \url{https://tug.org/texlive/doc.html}.
+Of course the most important acknowledgement must go to Donald Knuth,
+first for inventing \TeX, and then for giving it to the world.
+\section{Release history}
+Discussion began in late 1993 when the Dutch \TeX{} Users Group was
+starting work on its 4All\TeX{} \CD{} for MS-DOS users, and it
+was hoped at that time to issue a single, rational, \CD{} for all
+systems. This was too ambitious a target for the time, but it did spawn
+not only the very successful 4All\TeX{} \CD{}, but also the TUG
+Technical Council working group on a \emph{\TeX{} Directory Structure}
+(\url{https://tug.org/tds}), which specified how to create consistent and
+manageable collections of \TeX{} support files. A complete draft of the
+\TDS{} was published in the December 1995 issue of \textsl{TUGboat}, and
+it was clear from an early stage that one desirable product would be a
+model structure on \CD{}. The distribution you now have is a very direct
+result of the working group's deliberations. It was also clear that the
+success of the 4All\TeX{} \CD{} showed that Unix users would benefit
+from a similarly easy system, and this is the other main strand of
+We first undertook to make a new Unix-based \TDS{} \CD{} in the autumn
+of 1995, and quickly identified Thomas Esser's \teTeX{} as the ideal
+setup, as it already had multi-platform support and was built with
+portability across file systems in mind. Thomas agreed to help, and work
+began seriously at the start of 1996. The first edition was released in
+May 1996. At the start of 1997, Karl Berry completed a major new release
+of Web2c, which included nearly all the features which Thomas Esser had
+added in \teTeX, and we decided to base the 2nd edition of the \CD{} on
+the standard \Webc, with the addition of \teTeX's \texttt{texconfig}
+script. The 3rd edition of the \CD{} was based on a major revision of
+\Webc, 7.2, by Olaf Weber; at the same time, a new revision of \teTeX
+was being made, and \TL{} included almost all of its features. The
+4th edition followed the same pattern, using a new version of \teTeX,
+and a new release of \Webc{} (7.3).  The system now included a complete
+Windows setup, thanks to Fabrice Popineau.
+For the 5th edition (March 2000) many parts of the \CD{} were revised
+and checked, updating hundreds of packages. Package details were stored
+in XML files. But the major change for \TeX\ Live 5 was that all
+non-free software was removed. Everything in \TL{} is now intended
+to be compatible with the Debian Free Software Guidelines
+(\url{https://debian.org/intro/free}); we have done our best to check
+the license conditions of all packages, but we would very much
+appreciate hearing of any mistakes.
+The 6th edition (July 2001) had much more material updated. The major
+change was a new install concept: the user could select a more exact set
+of needed collections. Language-related collections were completely
+reorganized, so selecting any of them installs not only macros, fonts,
+etc., but also prepares an appropriate \texttt{language.dat}.
+The 7th edition of 2002 had the notable addition of \MacOSX{} support,
+and the usual myriad of updates to all sorts of packages and
+programs. An important goal was integration of the source back with
+\teTeX, to correct the drift apart in versions~5 and~6.
+In 2003, with the continuing flood of updates and additions, we found
+that \TL{} had grown so large it could no longer be contained on a
+single \CD, so we split it into three different distributions (see
+section~\ref{sec:tl-coll-dists}, \p.\pageref{sec:tl-coll-dists}).  In
+\item At the request of the \LaTeX{} team, we changed the standard
+      \cmdname{latex} and \cmdname{pdflatex} commands to now use \eTeX{} (see
+      \p.\pageref{text:etex}).
+\item The new Latin Modern fonts were included (and are recommended).
+\item Support for Alpha OSF was removed
+      (HPUX support was removed previously), since no one had (or
+      volunteered) hardware available on which to compile new binaries.
+\item Windows setup was substantially changed; for the first time
+      an integrated environment based on XEmacs was introduced.
+\item Important supplementary programs for Windows
+      (Perl, Ghost\-script, Image\-Magick, Ispell) are now installed
+      in the \TL{} installation directory.
+\item Font map files used by \cmdname{dvips}, \cmdname{dvipdfm}
+      and \cmdname{pdftex} are now generated by the new program
+      \cmdname{updmap} and installed into \dirname{texmf/fonts/map}.
+\item \TeX{}, \MF{}, and \MP{} now, by default, output most input
+      characters (32 and above) as themselves in output (e.g.,
+      \verb|\write|) files,
+      log files, and the terminal, i.e., \emph{not} translated using the
+      \verb|^^| notation.  In \TL{}~7, this translation was
+      dependent on the system locale settings; now, locale settings do
+      not influence the \TeX{} programs' behavior.  If for some reason
+      you need the \verb|^^| output, rename the file
+      \verb|texmf/web2c/cp8bit.tcx|.  (Future releases will have cleaner
+      ways to control this.)
+\item This documentation was substantially revised.
+\item Finally, since the edition numbers had grown unwieldy,
+      the version is now simply identified by the year: \TL{} 2003.
+2004 saw many changes:
+\item If you have locally-installed fonts which use their own
+\filename{.map} or (much less likely) \filename{.enc} support files, you
+may need to move those support files.
+\filename{.map} files are now searched for in subdirectories of
+\dirname{fonts/map} only (in each \filename{texmf} tree), along the
+\envname{TEXFONTMAPS} path.  Similarly, \filename{.enc} files are now
+searched for in subdirectories of \dirname{fonts/enc} only, along the
+\envname{ENCFONTS} path.  \cmdname{updmap} will attempt to warn about
+problematic files.
+For methods of handling this and other information, please see
+\item The \TK\ has been expanded with the addition of a \MIKTEX-based
+installable \CD, for those who prefer that implementation to Web2C.
+See section~\ref{sec:overview-tl} (\p.\pageref{sec:overview-tl}).
+\item Within \TL, the single large \dirname{texmf} tree of previous
+releases has been replaced by three: \dirname{texmf},
+\dirname{texmf-dist}, and \dirname{texmf-doc}.  See
+section~\ref{sec:tld} (\p.\pageref{sec:tld}), and the \filename{README}
+files for each.
+\item All \TeX-related input files are now collected in
+the \dirname{tex} subdirectory of \dirname{texmf*} trees, rather than
+having separate sibling directories \dirname{tex}, \dirname{etex},
+\dirname{pdftex}, \dirname{pdfetex}, etc.  See
+\item Helper scripts (not meant to be invoked by users) are now located
+in a new \dirname{scripts} subdirectory of \dirname{texmf*} trees, and
+can be searched for via \verb|kpsewhich -format=texmfscripts|.  So if you have
+programs which call such scripts, they'll need to be adjusted.  See
+\item Almost all formats leave most characters printable as
+themselves via the ``translation file'' \filename{cp227.tcx}, instead of
+translating them with the \verb|^^| notation.  Specifically, characters
+at positions 32--256, plus tab, vertical tab, and form feed are
+considered printable and not translated.  The exceptions are plain \TeX\
+(only 32--126 printable), \ConTeXt\ (0--255 printable), and the
+\OMEGA-related formats.  This default behavior is almost the same as in
+\TL\,2003, but it's implemented more cleanly, with more possibilities
+for customization.  See \CDref{texmf-dist/doc/web2c/web2c.html\#TCX-files}
+(By the way, with Unicode input, \TeX\ may output partial character
+sequences when showing error contexts, since it is byte-oriented.)
+\item \textsf{pdfetex} is now the default engine for all formats
+except (plain) \textsf{tex} itself.  (Of course it generates DVI
+when run as \textsf{latex}, etc.)  This means, among other things, that
+the microtypographic features of \textsf{pdftex} are available in
+\LaTeX, \ConTeXt, etc., as well as the \eTeX\ features
+It also means it's \emph{more important than ever} to use the
+\pkgname{ifpdf} package (works with both plain and \LaTeX) or equivalent
+code, because simply testing whether \cs{pdfoutput} or some other
+primitive is defined is not a reliable way to determine if PDF
+output is being generated.  We made this backward compatible as best we
+could this year, but next year, \cs{pdfoutput} may be defined even when
+DVI is being written.
+\item pdf\TeX\ (\url{http://pdftex.org}) has many new features:
+  \begin{itemize*}
+  \item \cs{pdfmapfile} and \cs{pdfmapline} provide font map support
+  from within a document.
+  \item Microtypographic font expansion can be used more easily.\\
+  \url{http://www.ntg.nl/pipermail/ntg-pdftex/2004-May/000504.html}
+  \item All parameters previously set through the special configuration
+  file \filename{pdftex.cfg} must now be set through primitives,
+  typically in \filename{pdftexconfig.tex}; \filename{pdftex.cfg} is no
+  longer supported.  Any extant \filename{.fmt} files must be redumped
+  when \filename{pdftexconfig.tex} is changed.
+  \item See the pdf\TeX\ manual for more: \OnCD{texmf-dist/doc/pdftex/manual/pdftex-a.pdf}.
+  \end{itemize*}
+\item The \cs{input} primitive in \cmdname{tex} (and \cmdname{mf} and
+\cmdname{mpost}) now accepts double quotes containing spaces and other
+special characters.  Typical examples:
+\input "filename with spaces"   % plain
+\input{"filename with spaces"}  % latex
+See the Web2C manual for more: \OnCD{texmf-dist/doc/web2c}.
+\item enc\TeX\ support is now included within Web2C and consequently all
+\TeX\ programs, via the \optname{-enc} option\Dash \emph{only when
+formats are built}.  enc\TeX\ supports general re-encoding of input and
+output, enabling full support of Unicode (in UTF-8).  See
+\OnCD{texmf-dist/doc/generic/enctex/} and
+\item Aleph, a new engine combining \eTeX\ and \OMEGA, is available.
+A little information is available in \OnCD{texmf-dist/doc/aleph/base}
+and \url{https://texfaq.org/FAQ-enginedev}.  The
+\LaTeX-based format for Aleph is named \textsf{lamed}.
+\item The latest \LaTeX\ release has a new version of the
+LPPL\Dash now officially a Debian-approved license.  Assorted
+other updates, see the \filename{ltnews} files in
+\item \cmdname{dvipng}, a new program for converting DVI to
+PNG image files, is included.  See
+\item We reduced the \pkgname{cbgreek} package to a ``medium'' sized set
+of fonts, with the assent and advice of the author (Claudio Beccari).
+The excised fonts are the invisible, outline, and transparency ones,
+which are relatively rarely used, and we needed the space.  The full set
+is of course available from CTAN (\url{https://ctan.org/pkg/cbgreek-complete}).
+\item \cmdname{oxdvi} has been removed; just use \cmdname{xdvi}.
+\item The \cmdname{ini} and \cmdname{vir} commands (links) for
+\cmdname{tex}, \cmdname{mf}, and \cmdname{mpost} are no longer created,
+such as \cmdname{initex}.  The \cmdname{ini} functionality has been
+available through the command-line option \optname{-ini} for years now.
+\item \textsf{i386-openbsd} platform support was removed.  Since the
+\pkgname{tetex} package in the BSD Ports system is available, and
+GNU/Linux and FreeBSD binaries were available, it seemed
+volunteer time could be better spent elsewhere.
+\item On \textsf{sparc-solaris} (at least), you may have to set the
+\envname{LD\_LIBRARY\_PATH} environment variable to run the
+\pkgname{t1utils} programs.  This is because they are compiled with C++,
+and there is no standard location for the runtime libraries.  (This is
+not new in 2004, but wasn't previously documented.)  Similarly, on
+\textsf{mips-irix}, the MIPSpro 7.4 runtimes are required.
+2005 saw the usual huge number of updates to packages and programs.
+The infrastructure stayed relatively stable from 2004, but inevitably
+there were some changes there as well:
+\item New scripts \cmdname{texconfig-sys}, \cmdname{updmap-sys}, and
+      \cmdname{fmtutil-sys} were introduced, which modify the
+      configuration in the system trees.  The \cmdname{texconfig},
+      \cmdname{updmap}, and \cmdname{fmtutil} scripts now modify
+      user-specific files, under \dirname{$HOME/.texlive2005}.
+\item Corresponding new variables \envname{TEXMFCONFIG} and
+      \envname{TEXMFSYSCONFIG} to specify the trees where configuration
+      files (user or system, respectively) are found.  Thus, you may
+      need to move personal versions of \filename{fmtutil.cnf} and
+      \filename{updmap.cfg} to these places; another option is to
+      redefine \envname{TEXMFCONFIG} or \envname{TEXMFSYSCONFIG} in
+      \filename{texmf.cnf}. In any case the real location of these files
+      and the values of \envname{TEXMFCONFIG} and \envname{TEXMFSYSCONFIG}
+      must agree.
+      See section~\ref{sec:texmftrees}, \p.\pageref{sec:texmftrees}.
+\item Last year, we kept \verb|\pdfoutput| and other primitives undefined
+      for \dvi\ output, even though the \cmdname{pdfetex} program was
+      being used.  This year, as promised, we undid that compatibility
+      measure.  So if your document uses \verb|\ifx\pdfoutput\undefined|
+      to test if PDF is being output, it will need to be changed.  You
+      can use the package \pkgname{ifpdf.sty} (which works under both
+      plain \TeX\ and \LaTeX) to do this, or steal its logic.
+\item Last year, we changed most formats to output (8-bit) characters as
+      themselves (see previous section).  The new TCX file
+      \filename{empty.tcx} now provides an easier way to get the
+      original \verb|^^| notation if you so desire, as in:
+latex --translate-file=empty.tcx yourfile.tex
+\item The new program \cmdname{dvipdfmx} is included for translation of
+      DVI to PDF; this is an actively maintained update of
+      \cmdname{dvipdfm} (which is also still available for now, though
+      no longer recommended).
+\item The new programs \cmdname{pdfopen} and \cmdname{pdfclose} are included
+      to allow reloading of PDF files in the Adobe Acrobat Reader without
+      restarting the program.  (Other PDF readers, notably \cmdname{xpdf},
+      \cmdname{gv}, and \cmdname{gsview}, have never suffered from this
+      problem.)
+\item For consistency, the variables \envname{HOMETEXMF} and
+      \envname{VARTEXMF} have been renamed to \envname{TEXMFHOME} and
+      \envname{TEXMFSYSVAR}, respectively.  There is also
+      \envname{TEXMFVAR}, which is by default user-specific.  See the
+      first point above.
+In 2006--2007, the major new addition to \TL{} was the \XeTeX{} program,
+available as the \texttt{xetex} and \texttt{xelatex} programs; see
+MetaPost also received a notable update, with more planned for the
+future (\url{https://tug.org/metapost/articles}), likewise pdf\TeX{}
+The \TeX\ \filename{.fmt} (high-speed format) and the similar files for
+MetaPost and \MF\ are now stored in subdirectories of \dirname{texmf/web2c},
+instead of in the directory itself (although the directory is still
+searched, for the sake of existing \filename{.fmt}'s).  The
+subdirectories are named for the `engine' in use, such as \filename{tex}
+or \filename{pdftex} or \filename{xetex}.  This change should be
+invisible in normal use.
+The (plain) \texttt{tex} program no longer reads \texttt{\%\&} first
+lines to determine what format to run; it is the pure Knuthian \TeX.
+(\LaTeX\ and everything else do still read \texttt{\%\&} lines).
+Of course the year also saw (the usual) hundreds of other updates to
+packages and programs.  As usual, please check CTAN
+(\url{https://ctan.org}) for updates.
+Internally, the source tree is now stored in Subversion, with a standard
+web interface for viewing the tree, as linked from our home page.
+Although not visible in the final distribution, we expect this will
+provide a stable development foundation for future years.
+Finally, in May 2006 Thomas Esser announced that he would no longer be
+updating te\TeX{} (\url{https://tug.org/tetex}).  As a result, there was
+a surge of interest in \TL{}, especially among \GNU/Linux
+distributors.  (There is a new \texttt{tetex} installation scheme in
+\TL{}, which provides an approximate equivalent.)  We hope this will
+eventually translate to improvements in the \TeX\ environment for
+In 2008, the entire \TL{} infrastructure was redesigned and
+reimplemented.  Complete information about an installation is now stored
+in a plain text file \filename{tlpkg/texlive.tlpdb}.
+Among other things, this finally makes possible upgrading a \TL{}
+installation over the Internet after the initial installation, a feature
+MiK\TeX\ has provided for many years.  We expect to regularly update new
+packages as they are released to \CTAN.
+The major new engine Lua\TeX\ (\url{http://luatex.org}) is included;
+besides a new level of flexibility in typesetting, this provides an
+excellent scripting language for use both inside and outside of \TeX\
+Support among Windows and the Unix-based platforms is now much more
+uniform.  In particular, most Perl and Lua scripts are now available on
+Windows, using the Perl internally distributed with \TL.
+The new \cmdname{tlmgr} script (section~\ref{sec:tlmgr}) is the
+general interface for managing \TL{} after the initial installation.
+It handles package updates and consequent regeneration of formats, map
+files, and language files, optionally including local additions.
+With the advent of \cmdname{tlmgr}, the \cmdname{texconfig} actions to
+edit the format and hyphenation configuration files are now disabled.
+The \cmdname{xindy} indexing program
+(\url{http://xindy.sourceforge.net/}) is now included on most platforms.
+The \cmdname{kpsewhich} tool can now report all matches for a given file
+(option \optname{--all}) and limit matches to a given subdirectory
+(option \optname{--subdir}).
+The \cmdname{dvipdfmx} program now includes functionality to extract
+bounding box information, via the command name \cmdname{extractbb}; this
+was one of the last features provided by \cmdname{dvipdfm} not in
+The font aliases \filename{Times-Roman}, \filename{Helvetica}, and so on
+have been removed.  Different packages expected them to behave
+differently (in particular, to have different encodings), and there was
+no good way to resolve this.
+The \pkgname{platex} format has been removed, to resolve a name conflict
+with a completely different Japanese \pkgname{platex}; the
+\pkgname{polski} package is now the main Polish support.
+Internally, the \web\ string pool files are now compiled into the
+binaries, to ease upgrades.
+Finally, the changes made by Donald Knuth in his `\TeX\ tuneup of 2008'
+are included in this release.  See
+In 2009, the default output format for Lua\AllTeX\ is now PDF, to take
+advantage of Lua\TeX's OpenType support, et al.  New executables named
+\code{dviluatex} and \code{dvilualatex} run Lua\TeX\ with DVI output.
+The Lua\TeX\ home page is \url{http://luatex.org}.
+The original Omega engine and Lambda format have been excised, after
+discussions with the Omega authors.  The updated Aleph and Lamed remain,
+as do the Omega utilities.
+A new release of the AMS \TypeI\ fonts is included, including Computer
+Modern: a few shape changes made over the years by Knuth in the Metafont
+sources have been integrated, and the hinting has been updated.  The
+Euler fonts have been thoroughly reshaped by Hermann Zapf (see
+\url{https://tug.org/TUGboat/Articles/tb29-2/tb92hagen-euler.pdf}).  In
+all cases, the metrics remain unchanged.  The AMS fonts home page is
+The new \GUI{} front end \TeX{}works is included for Windows, and also in
+Mac\TeX.  For other platforms, and more information, see the \TeX{}works
+home page, \url{https://tug.org/texworks}.  It is a cross-platform
+front-end inspired by the \MacOSX\ TeXShop editor, aiming at
+The graphics program Asymptote is included for several platforms.  This
+implements a text-based graphics description language vaguely akin to
+MetaPost, but with advanced 3D support and other features.  Its home
+page is \url{https://asymptote.sourceforge.io}.
+The separate \code{dvipdfm} program has been replaced by
+\code{dvipdfmx}, which operates in a special compatibility mode under
+that name.  \code{dvipdfmx} includes CJK support and has
+accumulated many other fixes over the years since the last
+\code{dvipdfm} release.
+Executables for the \pkgname{cygwin} and \pkgname{i386-netbsd} platforms
+are now included, while we were advised that OpenBSD users get
+\TeX\ through their package systems, plus there were difficulties in
+making binaries that have a chance of working on more than one version.
+A miscellany of smaller changes: we now use \pkgname{xz} compression,
+the stable replacement for \pkgname{lzma}
+(\url{https://tukaani.org/xz/}); a literal |$| is allowed in filenames
+when it does not introduce a known variable name; the Kpathsea library
+is now multi-threaded (made use of in MetaPost); the entire \TL{} build
+is now based on Automake.
+Final note on the past: all releases of \TL{}, along with ancillary
+material such as \CD\ labels, are available at
+\label{sec:2010news} % keep with 2010
+In 2010, the default version for PDF output is now 1.5, enabling more
+compression.  This applies to all the \TeX\ engines when used to produce
+PDF and to \code{dvipdfmx}.  Loading the \pkgname{pdf14} \LaTeX\ package
+changes back to PDF~1.4, or set |\pdfminorversion=4|.
+pdf\AllTeX\ now \emph{automatically} converts a requested Encapsulated
+PostScript (EPS) file to PDF, via the \pkgname{epstopdf} package, when
+and if the \LaTeX\ \code{graphics.cfg} configuration file is loaded, and
+PDF is being output.  The default options are intended to eliminate any
+chance of hand-created PDF files being overwritten, but you can also
+prevent \code{epstopdf} from being loaded at all by putting
+|\newcommand{\DoNotLoadEpstopdf}{}| (or |\def...|) before the
+\cs{documentclass} declaration.  It is also not loaded if the
+\pkgname{pst-pdf} package is used.  For more details, see the
+\pkgname{epstopdf} package documentation
+A related change is that execution of a very few external commands from
+\TeX, via the \cs{write18} feature, is now enabled by default.  These
+commands are \code{repstopdf}, \code{makeindex}, \code{kpsewhich},
+\code{bibtex}, and \code{bibtex8}; the list is defined in
+\code{texmf.cnf}.  Environments which must disallow all such external
+commands can deselect this option in the installer (see
+section~\ref{sec:options}), or override the value after installation by
+running |tlmgr conf texmf shell_escape 0|.
+Yet another related change is that \BibTeX\ and Makeindex now refuse to
+write their output files to an arbitrary directory (like \TeX\ itself),
+by default.  This is so they can now be enabled for use by the
+restricted \cs{write18}.  To change this, the \envname{TEXMFOUTPUT}
+environment variable can be set, or the |openout_any| setting changed.
+\XeTeX\ now supports margin kerning along the same lines as pdf\TeX.
+(Font expansion is not presently supported.)
+By default, \prog{tlmgr} now saves one backup of each package updated
+(\code{tlmgr option autobackup 1}), so broken package updates can be
+easily reverted with \code{tlmgr restore}.  If you do post-install
+updates, and don't have the disk space for the backups, run \code{tlmgr
+option autobackup 0}.
+New programs included: the p\TeX\ engine and related utilities for
+typesetting Japanese; the \BibTeX{}U program for Unicode-enabled
+\BibTeX; the \prog{chktex} utility
+(originally from \url{http://baruch.ev-en.org/proj/chktex}) for checking
+documents; the \prog{dvisvgm} (\url{https://dvisvgm.de})
+DVI-to-SVG translator.
+Executables for these new platforms are now included: \code{amd64-freebsd},
+\code{amd64-kfreebsd}, \code{i386-freebsd}, \code{i386-kfreebsd},
+\code{x86\_64-darwin}, \code{x86\_64-solaris}.
+A change in \TL{} 2009 that we failed to note: numerous \TeX4ht-related
+executables (\url{https://tug.org/tex4ht}) were removed from the binary
+directories.  The generic \code{mk4ht} program can be used to run any of
+the various \code{tex4ht} combinations.
+Finally, the \TL{} release on the \TK\ \DVD\ can no longer be run live
+(oddly enough).  A single \DVD\ no longer has enough room.  One
+beneficial side effect is that installation from the physical \DVD\ is
+much faster.
+The \MacOSX\ binaries (\code{universal-darwin} and
+\code{x86\_64-darwin}) now work only on Leopard or later; Panther and
+Tiger are no longer supported.
+The \code{biber} program for bibliography processing is included on
+common platforms.  Its development is closely coupled with the
+\code{biblatex} package, which completely reimplements the
+bibliographical facilities provided by LaTeX.
+The MetaPost (\code{mpost}) program no longer creates or uses
+\code{.mem} files.  The needed files, such as \code{plain.mp}, are
+simply read on every run.  This is related to supporting MetaPost as a
+library, which is another significant though not user-visible change.
+The \code{updmap} implementation in Perl, previously used only on
+Windows, has been revamped and is now used on all platforms.  There
+shouldn't be any user-visible changes as a result, except that it runs
+much faster.
+The \cmdname{initex} and \cmdname{inimf} programs were restored (but no
+other \cmdname{ini*} variants).
+\code{tlmgr} supports updates from multiple network repositories.  The
+section on multiple repositories in the \code{tlmgr help} output has
+The parameter \cs{XeTeXdashbreakstate} is set to~1 by default, for both
+\code{xetex} and \code{xelatex}.  This allows line breaks after
+em-dashes and en-dashes, which has always been the behavior of plain
+\TeX, \LaTeX, Lua\TeX, etc.  Existing \XeTeX\ documents which must
+retain perfect line-break compatibility will need to set
+\cs{XeTeXdashbreakstate} to~0 explicitly.
+The output files generated by \code{pdftex} and \code{dvips}, among
+others, can now exceed 2 gigabytes.
+The 35 standard PostScript fonts are included in the output of
+\code{dvips} by default, since so many different versions of them are
+In the restricted \cs{write18} execution mode, set by default,
+\code{mpost} is now an allowed program.
+A \code{texmf.cnf} file is also found in \filename{../texmf-local},
+e.g., \filename{/usr/local/texlive/texmf-local/web2c/texmf.cnf}, if it
+The \code{updmap} script reads a per-tree \code{updmap.cfg} instead of
+one global config.  This change should be invisible, unless you edited
+your updmap.cfg's directly.  The \verb|updmap --help| output has more.
+Platforms: \pkgname{armel-linux} and \pkgname{mipsel-linux} added;
+\pkgname{sparc-linux} and \pkgname{i386-netbsd} are no longer in the
+main distribution.
+Distribution layout: the top-level \code{texmf/} directory has been
+merged into \code{texmf-dist/}, for simplicity.  Both the
+\code{TEXMFMAIN} and \code{TEXMFDIST} Kpathsea variables now point to
+Many small language collections have been merged together, to simplify
+\MP: native support for PNG output and floating-point (IEEE double) has
+been added.
+Lua\TeX: updated to Lua 5.2, and includes a new library
+(\code{pdfscanner}) to process external PDF page content, among much
+else (see its web pages).
+\XeTeX\ (also see its web pages for more):
+\item The HarfBuzz library is now used for font layout instead of
+ICU.  (ICU is still used to support input encodings, bidirectionality,
+and the optional Unicode line breaking.)
+\item Graphite2 and HarfBuzz are used instead of SilGraphite for Graphite
+\item On Macs, Core Text is used instead of the (deprecated) ATSUI.
+\item Prefer TrueType/OpenType fonts to Type1 when the names are the same.
+\item Fix occasional mismatch in font finding between \XeTeX\ and
+\item Support OpenType math cut-ins.
+\cmdname{xdvi}: now uses FreeType instead of \code{t1lib} for rendering.
+\pkgname{microtype.sty}: some support for \XeTeX\ (protrusion) and
+Lua\TeX\ (protrusion, font expansion, tracking), among other
+\cmdname{tlmgr}: new \code{pinning} action to ease configuring multiple
+repositories; that section in \verb|tlmgr --help| has more, online at
+Platforms: \pkgname{armhf-linux}, \pkgname{mips-irix},
+\pkgname{i386-netbsd}, and \pkgname{amd64-netbsd} added or revived;
+\pkgname{powerpc-aix} removed.
+2014 saw another \TeX\ tune-up from Knuth; this affected all engines,
+but the only visible change likely is the restoration of the
+\code{preloaded format} string on the banner line.  Per Knuth, this now
+reflects the format that \emph{would} be loaded by default, rather than
+an undumped format that is actually preloaded in the binary; it may be
+overridden in various ways.
+pdf\TeX: new warning-suppression parameter
+\cs{pdfsuppresswarningpagegroup}; new primitives for fake interword
+spaces to help with PDF text reflowing: \cs{pdfinterwordspaceon},
+\cs{pdfinterwordspaceoff}, \cs{pdffakespace}.
+Lua\TeX: Notable changes and fixes were made to font loading and
+hyphenation. The biggest addition is a new engine variant,
+\code{luajittex} and its siblings \code{texluajit} and
+\code{texluajitc}. This uses a just-in-time Lua compiler (detailed
+\textsl{TUGboat} article at
+\url{https://tug.org/TUGboat/tb34-1/tb106scarso.pdf}). \code{luajittex}
+is still in development, is not available on all platforms, and is
+considerably less stable than \code{luatex}. Neither we nor its
+developers recommend using it except for the specific purpose of
+experimenting with jit on Lua code.
+\XeTeX: The same image formats are now supported on all platforms
+(including Mac); avoid Unicode compatibility decomposition fallback (but
+not other variants); prefer OpenType to Graphite fonts, for
+compatibility with previous \XeTeX\ versions.
+\MP: A new numbersystem \code{decimal} is supported, along with a
+companion internal \code{numberprecision}; a new definition of
+\code{drawdot} in \filename{plain.mp}, per Knuth; bug fixes in
+SVG and PNG output, among others.
+The \cmdname{pstopdf} Con\TeX{}t utility will be removed as a standalone
+command at some point after the release, due to conflicts with OS
+utilities of the same name.  It can still (and now) be invoked as
+\code{mtxrun --script pstopdf}.
+\cmdname{psutils} has been substantially revised by a new maintainer.
+As a result, several seldom-used utilities (\code{fix*}, \code{getafm},
+\code{psmerge}, \code{showchar}) are now only in the \dirname{scripts/}
+directory rather than being user-level executables (this can be reversed
+if it turns out to be problematic).  A new script, \code{psjoin}, has
+been added.
+The Mac\TeX\ redistribution of \TeX\ Live (section~\ref{sec:macosx}) no
+longer includes the optional Mac-only packages for the Latin Modern and
+\TeX\ Gyre fonts, since it is easy enough for individual users to make
+them available to the system.  The \cmdname{convert} program from
+ImageMagick has also been excised, since \TeX4ht (specifically
+\code{tex4ht.env}) now uses Ghostscript directly.
+The \pkgname{langcjk} collection for Chinese, Japanese, and Korean
+support has been split into individual language collections for the sake
+of more moderate sizes.
+Platforms: \pkgname{x86\_64-cygwin} added, \pkgname{mips-irix} removed;
+Microsoft no longer supports Windows XP, so our programs may
+start failing there at any time.
+\LaTeXe\ now incorporates, by default, changes previously included only
+by explicitly loading the \pkgname{fixltx2e} package, which is now a
+no-op.  A new \pkgname{latexrelease} package and other mechanisms allow
+for controlling what is done.  The included \LaTeX\ News \#22 and
+``\LaTeX\ changes'' documents have details.  Incidentally, the
+\pkgname{babel} and \pkgname{psnfss} packages, while core parts of
+\LaTeX, are maintained separately and are not affected by these changes
+(and should still work).
+Internally, \LaTeXe\ now includes Unicode-related engine configuration
+(what characters are letters, naming of primitives, etc.) which was
+previously part of \TeX\ Live.  This change is intended to be invisible
+to users; a few low-level internal control sequences have been renamed
+or removed, but the behavior should be just the same.
+pdf\TeX: Support JPEG Exif as well as JFIF; do not
+emit a warning if \cs{pdfinclusionerrorlevel} is negative; sync
+with \prog{xpdf}~3.04.
+Lua\TeX: New library \pkgname{newtokenlib} for scanning tokens; bug
+fixes in the \code{normal} random number generator and other places.
+\XeTeX: Image handling fixes; \prog{xdvipdfmx} binary looked for first
+as a sibling to \prog{xetex}; internal \code{XDV} opcodes changed.
+MetaPost: New numbersystem \code{binary}; new Japanese-enabled
+\prog{upmpost} and \prog{updvitomp} programs, analogous to
+Mac\TeX:\ Updates to the included Ghostscript package for CJK
+support.  The \TeX\ Distribution Preference Pane now works in Yosemite
+(\MacOSX~10.10).  Resource-fork font suitcases (generally without an
+extension) are no longer supported by \XeTeX; data-fork suitcases
+(\code{.dfont}) remain supported.
+Infrastructure: The \prog{fmtutil} script has been reimplemented to read
+\filename{fmtutil.cnf} on a per-tree basis, analogous to \prog{updmap}.
+Web2C \prog{mktex*} scripts (including \prog{mktexlsr}, \prog{mktextfm},
+\prog{mktexpk}) now prefer programs in their own directory, instead of
+always using the existing \envname{PATH}.
+Platforms: \pkgname{*-kfreebsd} removed, since \TeX\ Live is now easily
+available through the system platform mechanisms.
+Support for some additional platforms is available as custom binaries
+(\url{https://tug.org/texlive/custom-bin.html}).  In addition, some
+platforms are now omitted from the \DVD\ (simply to save space), but can
+be installed normally over the net.

+Lua\TeX: Sweeping changes to primitives, both renames and removals,
+along with some node structure rearrangements.  The changes are
+summarized in an article by Hans Hagen, ``Lua\TeX\ 0.90 backend changes
+for PDF and more''
+(\url{https://tug.org/TUGboat/tb37-1/tb115hagen-pdf.pdf}); for all the
+details, see the Lua\TeX\ manual,
+Metafont: New highly experimental sibling programs MFlua and MFluajit,
+integrating Lua with \MF, for trial testing purposes.
+MetaPost: Bug fixes and internal preparations for MetaPost 2.0.
+\code{SOURCE\_DATE\_EPOCH} support in all engines except Lua\TeX\ (which
+will come in the next release) and original \code{tex} (intentionally
+omitted): if the environment variable \code{SOURCE\_DATE\_EPOCH} is set,
+its value is used for timestamps in the PDF output.  If
+\code{SOURCE\_DATE\_EPOCH\_TEX\_PRIMITIVES} is also set, the
+\code{SOURCE\_DATE\_EPOCH} value is used to initialize the \TeX\
+primitives \cs{year}, \cs{month}, \cs{day}, \cs{time}.  The pdf\TeX\
+manual has examples and details.
+pdf\TeX: new primitives \cs{pdfinfoomitdate}, \cs{pdftrailerid},
+\cs{pdfsuppressptexinfo}, to control values appearing in the output
+which normally change with each run.  These features are for PDF output
+only, not DVI.
+Xe\TeX: New primitives \cs{XeTeXhyphenatablelength},
+\cs{XeTeXgenerateactualtext},\\ \cs{XeTeXinterwordspaceshaping},
+\cs{mdfivesum}; character class limit increased to 4096; DVI id byte
+Other utilities:
+\item \code{gregorio} is a new program, part of the \code{gregoriotex}
+package for typesetting Gregorian chant scores; it is included in
+\code{shell\_escape\_commands} by default.
+\item \code{upmendex} is an index creation program, mostly compatible
+with \code{makeindex}, with support for Unicode sorting, among other
+\item \code{afm2tfm} now makes only accent-based height adjustments
+upward; a new option \code{-a} omits all adjustments.
+\item \code{ps2pk} can handle extended PK/GF fonts.
+Mac\TeX:\ The \TeX\ Distribution Preference Pane is gone; its
+functionality is now in \TeX\ Live Utility; bundled GUI applications
+upgraded; new script \code{cjk-gs-integrate} to be run by users who wish
+to incorporate various CJK fonts into Ghostscript.
+Infrastructure: System-level \code{tlmgr} configuration file supported;
+verify package checksums; if GPG is available, verify signature of
+network updates.  These checks happen with both the installer and
+\code{tlmgr}.  If GPG is not available, updates proceed as usual.
+Platforms: \code{alpha-linux} and \code{mipsel-linux} removed.

+Lua\TeX: More callbacks, more typesetting control, more access to
+internals; \code{ffi} library for dynamic code loading added on some
+pdf\TeX: Environment variable |SOURCE_DATE_EPOCH_TEX_PRIMITIVES| from
+last year renamed to |FORCE_SOURCE_DATE|, with no changes in
+functionality; if the \cs{pdfpageattr} token list contains the string
+\code{/MediaBox}, omit output of the default \code{/MediaBox}.
+Xe\TeX: Unicode/OpenType math now based on HarfBuzz's MATH table support;
+some bug fixes.
+Dvips: Make the last papersize special win, for consistency with
+\code{dvipdfmx} and package expectations; the \code{-L0} option (\code{L0}
+config setting) restores the previous behavior of the first special
+ep\TeX, eup\TeX: New primitives \cs{pdfuniformdeviate},
+\cs{pdfnormaldeviate}, \cs{pdfrandomseed}, \cs{pdfsetrandomseed},
+\cs{pdfelapsedtime}, \cs{pdfresettimer}, from pdf\TeX.
+Mac\TeX:\ As of this year, only \MacOSX\ releases for which Apple still
+releases security patches will be supported in Mac\TeX, under the
+platform name |x86_64-darwin|; currently this means Yosemite,
+El~Capitan, and Sierra (10.10 and newer). Binaries for older \MacOSX\
+versions are not included in Mac\TeX, but are still available in \TeX\
+Live (|x86_64-darwinlegacy|, \code{i386-darwin}, \code{powerpc-darwin}).
+Infrastructure: The \envname{TEXMFLOCAL} tree is now searched before
+\envname{TEXMFSYSCONFIG} and \envname{TEXMFSYSVAR} (by default); the
+hope is that this will better match expectations of local files
+overriding system files.  Also, \code{tlmgr} has a new mode \code{shell}
+for interactive and scripted use, and a new action \code{conf auxtrees}
+to easily add and remove extra trees.
+\code{updmap} and \code{fmtutil}: These scripts now give a warning when
+invoked without explicitly specifying either so-called system mode
+(\code{updmap-sys}, \code{fmtutil-sys}, or option \code{-sys}), or user
+mode (\code{updmap-user}, \code{fmtutil-user}, or option \code{-user}).
+The hope is that this will reduce the perennial problem of invoking user
+mode by accident and thus losing future system updates.  See
+\url{https://tug.org/texlive/scripts-sys-user.html} for details.
+\code{install-tl}: Personal paths such as \envname{TEXMFHOME} are now
+set to Mac\TeX\ values (|~/Library/...|)\ by default on Macs.  New
+option \code{-init-from-profile} to start an installation with the
+values from a given profile; new command \code{P} to explicitly save a
+profile; new profile variable names (but previous ones are still
+Sync\TeX: the name of the temporary file now looks like
+\code{foo.synctex(busy)}, instead of \code{foo.synctex.gz(busy)}
+(no~\code{.gz}). Front-ends and build systems that want to remove temp
+files may need adjusting.
+Other utilities: \code{texosquery-jre8} is a new cross-platform program
+for retrieving locale and other OS information from a \TeX\ document; it
+is included in |shell_escape_commands| by default for restricted
+shell execution. (Older JRE versions are supported by texosquery, but
+cannot be enabled in restricted mode, as they are no longer supported by
+Oracle, even for security issues.)
+Platforms: See Mac\TeX\ entry above; no other changes.

+Kpathsea: Case-insensitive filename matching now done by default in
+non-system directories; set \code{texmf.cnf} or environment variable
+\code{texmf\_casefold\_search} to~\code{0} to disable.
+Full details in the Kpathsea manual (\url{https://tug.org/kpathsea}).
+ep\TeX, eup\TeX: New primitive \cs{epTeXversion}.
+Lua\TeX: Preparation for moving to Lua 5.3 in 2019: a binary
+\code{luatex53} is available on most platforms, but must be renamed to
+\code{luatex} to be effective. Or use the \ConTeXt\ Garden
+(\url{https://wiki.contextgarden.net}) files; more information there.
+MetaPost: Fixes for wrong path directions, TFM and PNG output.
+pdf\TeX: Allow encoding vectors for bitmap fonts; current directory not
+hashed into PDF ID; bug fixes for \cs{pdfprimitive} and related.
+Xe\TeX: Support \code{/Rotate} in PDF image inclusion; exit nonzero if
+the output driver fails; various obscure UTF-8 and other primitive
+Mac\TeX:\ See version support changes below. In addition, the files
+installed in \code{/Applications/TeX/} by Mac\TeX\ have been reorganized for
+greater clarity; now this location contains four GUI programs (BibDesk,
+LaTeXiT, \TeX\ Live Utility, and TeXShop) at the top level and folders
+with additional utilities and documentation.
+\code{tlmgr}: new front-ends \code{tlshell} (Tcl/Tk) and
+\code{tlcockpit} (Java); JSON output; \code{uninstall} now a synonym
+for \code{remove}; new action/option \code{print-platform-info}.
+Removed: \code{armel-linux}, \code{powerpc-linux}.
+\item \code{x86\_64-darwin} supports 10.10--10.13
+(Yosemite, El~Capitan, Sierra, and High~Sierra).
+\item \code{x86\_64-darwinlegacy} supports 10.6--10.10 (though
+\code{x86\_64-darwin} is preferred for 10.10).  All support for 10.5
+(Leopard) is gone, that is, both the \code{powerpc-darwin} and
+\code{i386-darwin platforms} have been removed.
+\item Windows: XP is no longer supported.

+Kpathsea: More consistent brace expansion and path splitting; new
+variable \code{TEXMFDOTDIR} instead of hard-coded \code{.}\ in paths
+allows for easily searching additional or sub-directories (see comments
+in \code{texmf.cnf}).
+ep\TeX, eup\TeX: New primitives \cs{readpapersizespecial} and
+Lua\TeX: Lua 5.3 now used, with concomitant arithmetic and interface changes.
+The homegrown library pplib is used to read pdf files, thus
+eliminating the dependency on poppler (and the need for C++);
+Lua interface changed accordingly.
+MetaPost: \code{r-mpost} command name recognized as an
+alias for invocation with the \code{--restricted} option, and added to
+the list of restricted commands available by default.
+Minimum precision now 2 for decimal and binary mode.
+Binary mode no longer available in MPlib but still available in
+standalone MetaPost.
+pdf\TeX: New primitive \cs{expanded}; if new primitive parameter
+\cs{pdfomitcharset} is set to 1, the \code{/CharSet} string
+omitted from the PDF output, since it cannot feasibly be guaranteed
+correct, as required by PDF/A-2 and PDF/A-3.
+Xe\TeX: New primitives \cs{expanded},
+\cs{randomseed}; extend \cs{Ucharcat} to produce active
+\code{tlmgr}: Support \code{curl} as a download program;
+   use \code{lz4} and gzip before \code{xz} for local backups, if available;
+   prefer system-provided binaries over binaries provided with \TL\ for
+   compressor and download programs, unless the environment variable
+   \code{TEXLIVE\_PREFER\_OWN} is set.
+\code{install-tl}: New option \code{-gui} (with no argument) is the
+default on Windows and Macs, and invokes a new Tcl/TK GUI (see
+sections~\ref{sec:basic} and~\ref{sec:graphical-inst}).
+\item \code{cwebbin} (\url{https://ctan.org/pkg/cwebbin}) is now the CWEB
+implementation in \TeX\ Live, with support for more language dialects,
+and including the \code{ctwill} program to make mini-indexes.
+\item \code{chkdvifont}: report font information from \dvi{} files, also
+from tfm/ofm, vf, gf, pk.
+\item \code{dvispc}: make a DVI file page-independent with respect to specials.
+Mac\TeX:\ \code{x86\_64-darwin} now supports 10.12 and higher (Sierra,
+High Sierra, Mojave); \code{x86\_64-darwinlegacy} still supports 10.6
+and newer. The spell checker Excalibur is no longer included, since it
+requires 32-bit support.
+Platforms: removed \code{sparc-solaris}.

+General: \begin{itemize}
+\item The \cs{input} primitive in all \TeX\ engines, including
+\texttt{tex}, now also accepts a group-delimited filename argument, as a
+system-dependent extension. The usage with a standard
+space/token-delimited filename is completely unchanged. The
+group-delimited argument was previously implemented in Lua\TeX; now it
+is available in all engines. ASCII double quote characters (\texttt{"})
+are removed from the filename, but it is otherwise left unchanged after
+tokenization. This does not currently affect \LaTeX's \cs{input} command,
+as that is a macro redefinition of the standard \cs{input} primitive.
+\item New option \texttt{--cnf-line} for \texttt{kpsewhich}, \texttt{tex},
+\texttt{mf}, and all other engines, to support arbitrary configuration
+settings on the command line.
+\item The addition of various primitives to various engines in this and
+previous years is intended to result in a common set of functionality
+available across all engines (\textsl{\LaTeX\ News \#31},
+ep\TeX, eup\TeX: New primitives \cs{Uchar}, \cs{Ucharcat},
+\cs{current(x)spacingmode}, \cs{ifincsname}; revise \cs{fontchar??} and
+\cs{iffontchar}. For eup\TeX\ only: \cs{currentcjktoken}.
+Lua\TeX: Integration with HarfBuzz library, available as new engines
+\texttt{luahbtex} (used for \texttt{lualatex}) and \texttt{luajithbtex}.
+New primitives: \cs{eTeXgluestretchorder}, \cs{eTeXglueshrinkorder}.
+pdf\TeX: New primitive \cs{pdfmajorversion}; this merely changes the
+version number in the PDF output; it has no effect on any PDF content.
+\cs{pdfximage} and similar now search for image files in the same way as
+p\TeX: New primitives \cs{ifjfont}, \cs{iftfont}. Also in ep\TeX,
+up\TeX, eup\TeX.
+Xe\TeX: Fixes for \cs{Umathchardef}, \cs{XeTeXinterchartoks}, \cs{pdfsavepos}.
+Dvips: Output encodings for bitmap fonts, for better copy/paste
+Mac\TeX:\ Mac\TeX\ and \texttt{x86\_64-darwin} now require 10.13 or
+higher (High~Sierra, Mojave, and Catalina);
+\texttt{x86\_64-darwinlegacy} supports 10.6 and newer. Mac\TeX\ is
+notarized and command line programs have hardened runtimes, as now
+required by Apple for install packages. BibDesk and \TeX\ Live Utility
+are not in Mac\TeX\ because they are not notarized, but a
+\filename{README} file lists urls where they can be obtained.
+\code{tlmgr} and infrastructure: \begin{itemize*}
+\item Automatically retry (once) packages that fail to download.
+\item New option \texttt{tlmgr check texmfdbs}, to 
+to check consistency of \texttt{ls-R} files and \texttt{!!}
+specifications for each tree.
+\item Use versioned filenames for the package containers, as in
+\texttt{tlnet/archive/\textsl{pkgname}.rNNN.tar.xz}; should be
+invisible to users, but a notable change in distribution.
+\item \texttt{catalogue-date} information no longer propagated from the
+\TeX~Catalogue, since it was often unrelated to package updates.

+\subsection{Present: 2021}
+General: \begin{itemize}
+\item Donald Knuth's changes for his 2021 tuneup of \TeX\ and Metafont are
+(\url{https://tug.org/TUGboat/tb42-1/tb130knuth-tuneup21.pdf}). They are
+also available on CTAN as the \code{knuth-dist} and \code{knuth-local}
+packages. As expected, the fixes are for obscure cases and do not affect
+any behavior in practice.
+\item Except in original \TeX: if \cs{tracinglostchars} is set to 3 or
+more, missing characters will result in an error, not just a message in
+the log file, and the missing character code will be shown in hex.
+\item Except in original \TeX: a new integer parameter
+\cs{tracingstacklevels}, if positive, and \cs{tracingmacros}
+is also positive, causes a prefix indicating the macro expansion depth
+to be output on each relevant log line (e.g., |~..| at depth 2).
+Also, macro logging is truncated at a depth $\ge$ the parameter value.
+Aleph: The Aleph-based \LaTeX\ format, named \code{lamed}, has been
+removed. The \code{aleph} binary itself is still included and supported.
+Lua\TeX: \begin{itemize*}
+\item Lua 5.3.6.
+\item Callback for nesting level used in \cs{tracingmacros}, as
+generalized variant of the new \cs{tracingstacklevels}.
+\item Mark math glyphs as protected to prevent processing as text.
+\item Removed width/ic compensation for traditional math code path.
+MetaPost: \begin{itemize*}
+\item |SOURCE_DATE_EPOCH| environment variable support for reproducible output.
+\item Avoid wrong final \texttt{\%} in \texttt{mpto}.
+\item Document \texttt{-T} option, other fixes to manual.
+\item Value of \texttt{epsilon} changed in binary and decimal modes, so
+|mp_solve_rising_cubic| works as expected.
+pdf\TeX{}: \begin{itemize*}
+\item New primitives \cs{pdfrunninglinkoff} and
+\cs{pdfrunninglinkon}; e.g., for disabling generation of links in
+headers and footers.
+\item Warn instead of aborting when ``\cs{pdfendlink} ended up in
+different nesting level than \cs{pdfstartlink}''.
+\item Dump \cs{pdfglyphtounicode} assignments in \texttt{fmt} file.
+\item Source: \texttt{poppler} support removed, as it was too hard to
+keep in sync with upstream. In native TL, pdf\TeX\ has always used
+\texttt{libs/xpdf}, which is cut-down and adapted code from \texttt{xpdf}.
+Xe\TeX{}: Fixes for math kerning.
+Dvipdfmx: \begin{itemize*}
+\item Ghostscript is now invoked safely by default; to override
+    (assuming all input files are trusted), use
+    \verb|-i dvipdfmx-unsafe.cfg|. To use PSTricks with \XeTeX, this is
+    required, as in:
+    \verb|xetex -output-driver="xdvipdfmx -i dvipdfmx-unsafe.cfg -q -E" ...|
+\item If an image file is not found, exit with bad status.
+\item Extended special syntax for color support.
+\item Specials for manipulating |ExtGState|.
+\item Compatibility specials \code{pdfcolorstack} and \code{pdffontattr}.
+\item Experimental support for \code{dviluatex}'s extended |fnt_def|.
+\item Support new feature of virtual font to fallback Japanese font definition.
+Dvips: \begin{itemize*}
+\item Default PostScript document title is now the basename of the input
+file, and can be overridden with the new option \texttt{-title}.
+\item If an \texttt{.eps} or other image file is not found, exit with bad
+\item Support new feature of virtual font to fallback Japanese font definition.
+Mac\TeX{}: Mac\TeX{} and its new binary folder \texttt{universal-darwin} now
+require macOS 10.14 or higher (Mojave, Catalina, and Big~Sur); the
+|x86_64-darwin| binary folder is no longer present. The
+|x86_64-darwinlegacy| binary folder, available only with the Unix
+\texttt{install-tl}, supports 10.6 and newer.
+This is an important year for the Macintosh because Apple introduced
+ARM machines in November and will sell and support both ARM and Intel
+machines for many years. All programs in \texttt{universal-darwin} have
+executable code for both ARM and Intel. Both binaries are compiled from
+the same source code.
+The additional programs Ghostscript, LaTeXiT, \TeX{} Live Utility, and
+TeXShop are all universal and are signed with a hardened runtime, so all
+are included in Mac\TeX{} this year.
+\code{tlmgr} and infrastructure: \begin{itemize*}
+\item keep only one backup of the main repository's \texttt{texlive.tlpdb}.
+\item even more portability across systems and Perl versions.
+\item \texttt{tlmgr info} reports new \texttt{lcat-*} and \texttt{rcat-*}
+fields for local vs. remote Catalogue data.
+\item full logging of subcommands moved to new log file

+We intend to continue to release new versions of \TL, and would like to
+provide more documentation, more programs, an ever-improved and
+better-checked tree of macros and fonts, and anything else \TeX. This
+work is all done by volunteers in their spare time, and there is always
+more to do. Please see \url{https://tug.org/texlive/contribute.html}.
+Please send corrections, suggestions, and offers of help to:
+\email{tex-live at tug.org} \\
+\noindent \textsl{Happy \TeX ing!}

Property changes on: trunk/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2021.tex
Added: svn:eol-style
## -0,0 +1 ##
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/texlive/texlive-en/archive/live4ht.cfg-2021
--- trunk/Master/texmf-dist/doc/texlive/texlive-en/archive/live4ht.cfg-2021	                        (rev 0)
+++ trunk/Master/texmf-dist/doc/texlive/texlive-en/archive/live4ht.cfg-2021	2022-01-25 17:29:20 UTC (rev 61735)
@@ -0,0 +1,51 @@
+% $Id: live4ht.cfg 54322 2020-03-15 18:10:11Z karl $
+% tex4ht configuration file for the TeX Live documentation.
+% Accumulated over many years.  Public domain.
+% We specify tex4ht options on the htlatex command line; see ./Makefile.
+% \Preamble still needs to be invoked, though.
+% add extra stylesheet
+<link rel="stylesheet" type="text/css" href="\jobname.css" >\Hnewline
+<link rel="stylesheet" type="text/css" href="tex-live.css" >\Hnewline
+% use png graphics as-is
+         {png}
+         {\Needs{""}%
+          \Picture[pict]{../texlive-common/\csname Gin at base\endcsname.png}%
+         }
+% or LaTeX complains it is missing.
+% simplify output for HTML.  We leave TeX and LaTeX alone, since tex4ht
+% actually does the lowered E (and raised A) in CSS.
+\ifx\tldocenglish\undefined \else \hackliteralstrue \fi
+\ifx\tldocrussian\undefined \else \hackliteralstrue \fi
+\ifx\tldocgerman\undefined \else \hackliteralstrue \fi
+  % these definitions cause "missing } inserted" at \end{tabularx} in
+  % French and Czech.  don't know why.
+  %
+  % don't make these into links, as happens with \path.  We only have a few
+  % special characters that actually occur.
+  \def\dirname{\texttt\bgroup\catcode`\$=12 \catcode`\_=12 \catcode`\~=12
+    \finishliteral}
+  \def\finishliteral#1{#1\egroup}
+  \let\filename=\dirname

Added: trunk/Master/texmf-dist/doc/texlive/texlive-en/archive/tex-live.sty-2021
--- trunk/Master/texmf-dist/doc/texlive/texlive-en/archive/tex-live.sty-2021	                        (rev 0)
+++ trunk/Master/texmf-dist/doc/texlive/texlive-en/archive/tex-live.sty-2021	2022-01-25 17:29:20 UTC (rev 61735)
@@ -0,0 +1,492 @@
+% $Id: tex-live.sty 57999 2021-02-28 16:55:30Z karl $
+% TeX Live documentation style.  Written by many people over many years.
+% Public domain.
+\ProvidesPackage{tex-live}[2019/08/14 TeX Live Guide style]
+% colortbl and other packages otherwise make the default be letter, it seems.
+% for a proper \acro command.
+%% No lmodern for Russian; LM doesn't have cyrillic.
+\ifx\tldocrussion\undefined \RequirePackage{lmodern}\fi
+\usepackage{textcomp}% including \textbullet
+ {Verbatim}{fontsize=\footnotesize,frame=single}
+% Done with packages.
+% emacs-page page layout.
+%ltr \advance\textwidth by 1.1in
+%ltr \advance\oddsidemargin by -.55in
+%ltr \advance\evensidemargin by -.55in
+%ltr %
+%ltr \advance\textheight by 1in
+%ltr \advance\topmargin by -.5in
+%ltr \advance\footskip by -.5in
+%ltr %
+\message{dimens: textwidth=\the\textwidth\space
+         oddsidemargin=\the\oddsidemargin\space
+         evensidemargin=\the\evensidemargin\space
+         textheight=\the\textheight\space
+         topmargin=\the\topmargin\space
+         footskip=\the\footskip}
+% with settings above, and without a4 (hence letter):
+% textwidth=424.49744pt  oddsidemargin=22.25128pt evensidemargin=22.25128pt
+% textheight=622.26999pt topmargin=-20.135pt      footskip=-6.135pt
+% with default a4paper geometry settings (not enough height):
+% textwidth=418.25368pt oddsidemargin=17.3571pt evensidemargin=17.3571pt 
+% textheight=591.5302pt topmargin=-7.86334pt    footskip=30.0pt
+% with geometry settings [a4paper,hscale=0.75,lines=60,vmarginratio=10:8]:
+% textwidth=448.1309pt oddsidemargin=2.41849pt  evensidemargin=2.41849pt
+% textheight=718.0pt   topmargin=-38.68848pt    footskip=30.0pt
+% LaTeX parameters.
+% linebreaking, etc.
+\def\slash{/\penalty\z@\hskip\z at skip }
+% various sorts of names
+\newcommand*{\pkgname}[1]{\textsf{#1}}% package name
+\newcommand*{\optname}[1]{\texttt{#1}}% (package,class) option name
+\newcommand*{\cmdname}[1]{\textsf{#1}}% command name
+\newcommand*{\colname}[1]{\emph{#1}}%   collection name
+\newcommand*{\dirname}[1]{\path{#1}}%   directory name
+\def\filename#1{\path{#1}}%  file name
+\newcommand*{\envname}[1]{\texttt{#1}}% environment variable name
+\newcommand{\prog}[1]{\textsf{#1}}% same as \cmdname
+\newcommand{\var}[1]{{\sl #1}}% not \textsl, for roman not typewriter slanted.
+% underlined command input.
+%   \uline{\rule[-.2\baselineskip]{0pt}{.9\baselineskip}\ttfamily #1}}
+% bold command input
+\def\Ucom#1{{\bfseries\ttfamily #1}}
+% \CDref is for url's with a #, where we need to write the target url and
+% displayed url separately in the input, due to catcode madness.
+% (We could simplify/remove this next time, I think.)
+% \OnCD no longer has any use at all, since we don't have unpacked files
+% on the DVD and it has never worked when reading the PDF online.
+% \OnCD is currently for any other reference to a file or directory in
+% the distribution.  PDF readers only open .pdf files, though, so we
+% should change this to only use \href for those.  Or more likely use
+% different macros in the source.
+% \href incorrectly appends .pdf to anything without an extension; these
+% definitions using \hyper at linkurl do not, but they fail for .pdf
+% references -- which are the only ones that work anyway.  So this is
+% useless, in practice.
+%\def\CDref#1#2{\hyper at linkurl{#2}{../../../../#1}}
+%\def\OnCD#1{\hyper at linkurl{\path{#1}}{../../../../#1}}
+% GUI menu/button/tab sequence:
+% Special names.
+% many abbreviations.
+                 \hbox{$\mathcal{S}$}\kern-.075em $}
+% This code % is hacked from its definition of \cs{LaTeX}; it allows
+% slants (for example) to propagate into the raised (small) `A':
+   {L\kern-.36em
+        {\setbox0\hbox{T}%
+         \vbox to\ht0{\hbox{$\m at th$%
+                            \csname S@\f at size\endcsname
+                            \fontsize\sf at size\z@
+                            \math at fontsfalse\selectfont
+                            A}%
+                      \vss}%
+        }}
+\def\OzTeX{O\kern-.03em z\kern-.15em\TeX}
+\def\ProTeXt{pro\TeX t}
+\def\TeXLive{\TeX{} Live\xspace}
+\def\TK{\TeX\ Collection}
+\def\Thanh{H\`an~Th\ifx  % get Unicode char in tex4ht's HTML output
+     \HCode\UnDef\^e\llap{\raise 0.5ex\hbox{\'{}}}\else
+     \HCode{\string&\#x1EBF;}\fi~Th\`anh}
+% Include a png image.
+% #1 - name of image file in ../texlive-common/, always .png
+% #2 - width for TeX
+  \ifnum \Status=2 % html, want relative path in output
+    \includegraphics{../texlive-common/#1.png}%
+    % We intentionally are not specifying the size, so that the natural
+    % size of the graphic is used in the HTML output. Thus we do not
+    % get a graphics.sty warning about "cannot determine size of graphic
+    % (no BoundingBox)" on every image. Unfortunately there is no good
+    % way to eliminate that except by eliminating all LaTeX errors
+    % (\@latex at error), which does not seem like a good idea.
+  \else % not html, handled by TEXINPUTS in Makefile
+    \par
+    \centerline{\includegraphics[width=#2]{#1.png}}%
+  \fi
+% description-like environment that uses tt instead of bf, and doesn't
+% go to the left margin.  Without the \hfil, get an underfull box.
+% Don't know why \descriptionlabel doesn't.
+  {\begin{list}{label must be supplied}{%
+     \itemsep=0pt  % these lists tend to have short descriptions
+     \parindent=0pt
+     \let\makelabel=\ttdescriptionlabel}}%
+  {\end{list}}
+                                   \normalfont\ttfamily #1\hfil}
+% Likewise, for commands using sans serif.
+  {\begin{list}{label must be supplied}{%
+     \itemsep=0pt
+     \let\makelabel=\cmddescriptionlabel}}%
+  {\end{list}}
+                                    \normalfont\sffamily #1\hfil}
+% General squeezed itemize/enumerate; no extra space at top or between items.
+  {\begin{itemize}%
+    \setlength{\itemsep}{0pt}%
+    \setlength{\parskip}{0pt}%
+    \setlength{\topsep}{0pt}%
+    \setlength{\partopsep}{0pt}%
+  }%
+  {\end{itemize}}
+  {\begin{enumerate}%
+    \setlength{\itemsep}{0pt}%
+    \setlength{\parskip}{0pt}}%
+  {\end{enumerate}}
+ {\begin{lrbox}{\wbox}
+ \begin{minipage}{.95\textwidth}}
+ {\end{minipage}\end{lrbox}\fbox{\usebox{\wbox}}}
+% lrbox is used as a representation marking. I changed it to
+% lrBox in tne source file, to get closer to logical marking
+ {\begin{lrbox}{\mylrbox}}
+ {\end{lrbox}}
+% emacs-page output setup
+\ifx \HCode\UnDef
+  \providecommand{\Status}{0}% running TeX
+  \providecommand{\Status}{2}% running TeX4ht
+%\typeout{Status is \Status}
+% By default, we won't be creating hyperlinks.
+\def\email#1{\href{mailto:#1}{\path{#1}}}  % \path comes from url
+\definecolor{hypercolor}{rgb}{0.5,0.0,0.5} % purplish external links.
+  % \Status = 0
+  \typeout{TeX Live documentation in DVI format}
+  \SingleColumntrue
+  \newenvironment{multicols}[1]{}{}
+ \or
+  % \Status = 1
+  \typeout{TeX Live documentation in PDF format}
+  \RequirePackage[breaklinks,
+                  colorlinks,linkcolor=hypercolor,citecolor=hypercolor,
+                    urlcolor=hypercolor,filecolor=hypercolor,
+                  bookmarksopen,
+                  %pdfstartview={FitBH -320000}, % fails with acrobat7
+                  hyperindex]
+        {hyperref}
+  \SingleColumntrue
+  \newenvironment{multicols}[1]{}{}
+ \or
+  % \Status = 2
+  \typeout{TeX Live documentation in HTML format}
+  \SingleColumntrue
+  \newenvironment{multicols}[1]{}{}
+  % Our config file, live4ht.cfg, is read from the htlatex call
+  % in the Makefile.
+  \RequirePackage[tex4ht]{hyperref}  \hyperlinkfileprefix{}
+  % definitions need simplifying for TeX4ht to make relative paths work.
+  \def\CDref#1#2{\href{../../../../#1}{#2}}
+  \def\OnCD#1{\href{../../../../#1}{#1}}
+  \def\htmlanchor#1{\HCode{<a id="#1"></a>}}
+ \or
+  % \Status = 3
+  \typeout{TeX Live documentation as a Baskerville issue}
+  \@ifundefined{Fonts}%
+    {\RequirePackage{ae}}%
+    {\RequirePackage[T1]{\Fonts}}
+  \RequirePackage{bvoutln}% outline of baskerville
+  \SingleColumnfalse
+  \RequirePackage{multicol}
+ \or
+  % \Status = 4
+  \typeout{TeX Live documentation as a TUB article}
+  \@ifundefined{Fonts}%
+    {\RequirePackage{ae}}%
+    {\RequirePackage[T1]{\Fonts}}
+  \SingleColumnfalse
+  \newenvironment{multicols}[1]{}{}
+\ifnum \Status=4
+  \RequirePackage{texnames}
+  \providecommand\TeXXeT{\TeX-{}-%
+    \kern-.1emX\kern-.125em\lower.5ex\hbox{E}\kern-.1667emT\@}
+  \def\MP{MetaPost}
+  \let\mf\MF
+  \newcommand\ConTeXt{C\kern-.0333emon\-\kern-.0667em\TeX\kern-.0333emt}
+  \newcommand\MIKTEX{MiK\kern-.025em \TeX}% per www.miktex.org
+  % from pictex.tex:
+  \ifx\PiC\undefined \def\PiC{P\kern-.12em\lower.5ex\hbox{I}\kern-.075emC} \fi
+  \ifx\PiCTeX\undefined \def\PiCTeX{\PiC\kern-.11em\TeX} \fi
+% hacking at sections etc., to pay attention to baskerville status
+\newcommand{\@condend at multicols}{%
+  \ifSingleColumn
+  \else
+    \def\@tempa{multicols}%
+    \ifx\@tempa\@currenvir
+      \end{multicols}%
+    \fi
+  \fi
+  \@ifstar
+    {\Section*}%
+    {%
+      \@condend at multicols
+      \@dblarg\@full at section
+    }%
+\def\@full at section[#1]#2{%
+  \Section[#1]{#2}%
+  \ifSingleColumn\else\begin{multicols}{2}\fi
+  \@ifstar{\SubSection*}%
+  {%
+    \@condend at multicols
+    \@dblarg\@full at subsection
+  }
+\def\@full at subsection[#1]#2{%
+  \SubSection[#1]{#2}%
+  \ifSingleColumn\else\begin{multicols}{2}\fi
+% Reduce list spacing.
+ \parsep \z@
+ \topsep 2\p@ \@plus 1\p@ \@minus 1\p@
+ \itemsep \z@ \@plus .1\p@
+ \labelwidth\leftmarginii\advance\labelwidth-\labelsep
+ \topsep 2\p@ \@plus 1\p@ \@minus 1\p@
+ \parsep \z@
+ \itemsep \z@ \@plus .1\p@
+ \labelwidth\leftmarginiii\advance\labelwidth-\labelsep
+ \topsep 1\p@ \@plus 1\p@ \@minus 1\p@
+ \parsep \z@
+ \partopsep \z@
+ \itemsep \topsep
+ \labelwidth\leftmarginiv\advance\labelwidth-\labelsep
+ \labelwidth\leftmarginv\advance\labelwidth-\labelsep
+ \labelwidth\leftmarginvi\advance\labelwidth-\labelsep
+% array package stuff
+% shaded rows (using facilities of colortbl)
+ \rowcolor{\RowColor}%
+ \global\advance\colrow by1\relax
+ \ifodd\colrow
+   \gdef\RowColor{pale}%
+ \else
+   \gdef\RowColor{white}%
+ \fi
+% redefine to hack up a reference even though we don't need it...
+\renewcommand\@bibitem[1]{\if at filesw \immediate\write\@auxout
+  {\string\bibcite{#1}{?}}\fi\ignorespaces}
+% \unknownTeXlive is a dummy texlive entry for the biblio
+  \global\@all at unknown\expandafter{\the\@all at unknown{#2}}%
+\newtoks\@all at unknown
+\global\@all at unknown{}
+\AtEndDocument{\@message at unknowns}
+\def\@message at unknowns{\edef\@tempa{\the\@all at unknown}%
+  \ifx\@tempa\@empty
+  \else
+    \def\@tempa{*** TeX Live package location of }%
+    \expandafter\@output at unknowns\the\@all at unknown\@empty
+  \fi
+\def\@output at unknowns#1{\edef\@tempb{#1}%
+  \ifx\@tempb\@empty
+    \typeout{ unknown}%
+  \else
+    \message{\@tempa#1,}%
+    \def\@tempa{}%
+    \expandafter\@output at unknowns
+  \fi
+% Silence font warnings about no bold typewriter in LM.
+\def\@font at warning#1{}%
+% Silence hyperref warnings about \kern.
+\def\HyPsd at Warning#1{}%

More information about the tex-live-commits mailing list.