diff options
Diffstat (limited to 'Master')
3 files changed, 4508 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2021.tex b/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2021.tex new file mode 100644 index 00000000000..da99180be28 --- /dev/null +++ b/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2021.tex @@ -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. +% +\documentclass{article} +\let\tldocenglish=1 % for live4ht.cfg +\usepackage{tex-live} +\usepackage[latin1]{inputenc} % translators: use your preferred encodings. +\usepackage[T1]{fontenc} + +\title{% + {\huge \textit{The \TeX\ Live Guide---2021}} +} + +\author{Karl Berry, editor \\[3mm] + \url{https://tug.org/texlive/} + } + +\date{March 2021} + +\begin{document} +\maketitle + +\begin{multicols}{2} +\tableofcontents +%\listoftables +\end{multicols} + +\section{Introduction} +\label{sec:intro} + +\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} +(\p.\pageref{sec:history}). + + +\htmlanchor{platforms} +\subsection{Operating system support} +\label{sec:os-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{}} +\label{sec:basic} + +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: + +\begin{itemize*} + +\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. + +\end{itemize*} + + +\htmlanchor{security} +\subsection{Security considerations} +\label{sec:security} + +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} +\label{sec: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: + +\begin{description} +\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 +\url{https://ctan.org/pkg/catalogue}. + +\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@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@tug.org} through email. But before you post anywhere, +please read this FAQ entry, to maximize your chances of getting a useful +answer: +\url{https://texfaq.org/FAQ-askquestion}. + +\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@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. + +\end{description} + +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} +\label{sec:overview-tl} + +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} +\label{sec:tl-coll-dists} + +The \TK{} \DVD{} comprises the following: + +\begin{description} + +\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: +\url{https://tug.org/mactex/}. + +\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: +\url{https://tug.org/protext/}. + +\item [CTAN] A snapshot of the \CTAN{} repository (\url{https://ctan.org/}). + +\end{description} + +\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} +\label{sec:tld} + +Here is a brief listing and description of the top level directories in a +\TL{} installation. + +\begin{ttdescription} +\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. +\end{ttdescription} + +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: + +\begin{itemize*} +\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} +\end{itemize*} + +\subsection{Overview of the predefined texmf trees} +\label{sec:texmftrees} + +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. + +\begin{ttdescription} +\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}. +\end{ttdescription} + +\noindent +The default layout is: +\begin{description} + \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} +\end{description} + + +\subsection{Extensions to \protect\TeX} +\label{sec:tex-extensions} + +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): + +\begin{description} + +\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 +\OnCD{texmf-dist/doc/etex/base/etex_man.pdf}. + +\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}. + +\end{description} + + +\subsection{Other notable programs in \protect\TL} + +Here are a few other commonly-used programs included in \TL{}: + +\begin{cmddescription} + +\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. + +\end{cmddescription} + + +\htmlanchor{installation} +\section{Installation} +\label{sec:install} + +\subsection{Starting the installer} +\label{sec:inst-start} + +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. + +\begin{description} +\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} +subdirectory. + +\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}. + +\end{description} + +\begin{figure}[tb] +\tlpng{nsis_installer}{.6\linewidth} +\caption{First stage of Windows \code{.exe} installer}\label{fig:nsis} +\end{figure} + +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 +(\url{https://www.gnu.org/software/wget/manual/html_node/Proxies.html}), +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. + +\subsubsection{Unix} + +Below, \texttt{>} denotes the shell prompt; user input is +\Ucom{\texttt{bold}}. +The script \filename{install-tl} is a Perl script. The simplest way +to start it on a Unix-compatible system is as follows: +\begin{alltt} +> \Ucom{perl /path/to/installer/install-tl} +\end{alltt} +(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 +(figure~\ref{fig:text-main}). + +To install in \GUI\ mode (figure~\ref{fig:advanced-lnx}), you'll need to +have Tcl/Tk installed. Given that, you can run: +\begin{alltt} +> \Ucom{perl install-tl -gui} +\end{alltt} + +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: +\begin{alltt} +> \Ucom{perl install-tl -help} +\end{alltt} + +\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 +documentation. + +\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 +section~\ref{sec:cygwin}. + + +\subsubsection{\MacOSX} +\label{sec:macosx} + +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. + + +\subsubsection{Windows}\label{sec:wininst} + +If you are using the unpacked downloaded zip file, or the \DVD\ +installer failed to start automatically, double-click +\filename{install-tl-windows.bat}. + +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: +\begin{alltt} +> \Ucom{install-tl-windows} +\end{alltt} + +Or you can invoke it with an absolute location, such as: +\begin{alltt} +> \Ucom{D:\bs{}texlive\bs{}install-tl-windows} +\end{alltt} +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: +\begin{alltt} +> \Ucom{install-tl-windows -no-gui} +\end{alltt} + +For a complete listing of the various options: +\begin{alltt} +> \Ucom{install-tl-windows -help} +\end{alltt} + +\begin{figure}[tb] +\begin{boxedverbatim} +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 + +Actions: + <I> start installation to hard disk + <P> save installation profile to 'texlive.profile' and exit + <H> help + <Q> quit +\end{boxedverbatim} +\vskip-.5\baselineskip +\caption{Main text installer screen (\GNU/Linux)}\label{fig:text-main} +\end{figure} + +\begin{figure}[tb] +\tlpng{basic-w32}{.6\linewidth} +\caption{Basic installer screen (Windows); the Advanced button will + result in something like figure~\ref{fig:advanced-lnx}}\label{fig:basic-w32} +\end{figure} + +\begin{figure}[tb] +\tlpng{advanced-lnx}{\linewidth} +\caption{Advanced \GUI{} installer screen + (\GNU/Linux)}\label{fig:advanced-lnx} +\end{figure} + + +\htmlanchor{cygwin} +\subsubsection{Cygwin} +\label{sec:cygwin} + +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 +recommended: +\begin{itemize*} +\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] +\end{itemize*} + + +\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} +\label{sec:graphical-inst} + +The default graphical installer starts out simple, with just a +few options; see figure~\ref{fig:basic-w32}. It can be started with +\begin{alltt} +> \Ucom{install-tl -gui} +\end{alltt} +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} +\label{sec:runinstall} + +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)} +\label{sec:binary} + +\begin{figure}[tb] +\begin{boxedverbatim} +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) +\end{boxedverbatim} +\vskip-.5\baselineskip +\caption{Binaries menu}\label{fig:bin-text} +\end{figure} + +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 +system. + +\subsubsection{Selecting what is to be installed} +\label{sec:components} + +\begin{figure}[tbh] +\begin{boxedverbatim} +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 +\end{boxedverbatim} +\vskip-.5\baselineskip +\caption{Scheme menu}\label{fig:scheme-text} +\end{figure} + +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. + +\begin{figure}[tb] +\centering \tlpng{stdcoll}{.7\linewidth} +\caption{Collections menu}\label{fig:collections-gui} +\end{figure} + +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. + +\subsubsection{Directories} +\label{sec:directories} + +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\_PREFIX} or +\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{TEXMFSYSCONFIG}. + +\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), +\dirname{TEXMFVAR}. + + +\subsubsection{Options} +\label{sec:options} + +\begin{figure}[tbh] +\begin{boxedverbatim} +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] +\end{boxedverbatim} +\vskip-.5\baselineskip +\caption{Options menu (Unix)}\label{fig:options-text} +\end{figure} + +Figure~\ref{fig:options-text} shows the text mode options menu. +More info on each: + +\begin{description} +\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}. +\end{description} +Windows-specific options, as displayed in the advanced \GUI{} +interface: +\begin{description} +\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] +\end{description} +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} +\label{sec:cmdline} + +Type +\begin{alltt} +> \Ucom{install-tl -help} +\end{alltt} +for a listing of command-line options. Either |-| or |--| can be used +to introduce option names. These are the most common ones: + +\begin{ttdescription} +\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. + +\htmlanchor{opt-in-place} +\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. +\end{ttdescription} + + +\subsubsection{The \optname{-repository} option} +\label{sec:location} + +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} +\label{sec:postinstall} + +Some post-installation may be required. + +\subsubsection{Environment variables for Unix} +\label{sec:env} + +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 +\envname{PATH}. + +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: + +\begin{sverbatim} +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 +\end{sverbatim} + +For csh or tcsh, the file to edit is typically \filename{$HOME/.cshrc}, and +the lines to add might look like: + +\begin{sverbatim} +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 +\end{sverbatim} + +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} +\label{sec:envglobal} + +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 + +\begin{sverbatim} +MANPATH_MAP /usr/local/texlive/2021/bin/x86_64-linux \ + /usr/local/texlive/2021/texmf-dist/doc/man +\end{sverbatim} + +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} +\label{sec:dvd-install-net-updates} + +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): + +\begin{alltt} +> \Ucom{tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet} +\end{alltt} + +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 +\htmlanchor{sysfontconfig} +\subsubsection{System font configuration for \protect\XeTeX\protect\ and Lua\protect\TeX} +\label{sec:font-conf-sys} + +\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 +methods. + +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 +\filename{TEXMFSYSVAR/fonts/conf/texlive-fontconfig.conf}. + +To set up the \TL{} fonts for system-wide use (assuming you have +suitable privileges), proceed as follows: +\begin{enumerate*} +\item Copy the \filename{texlive-fontconfig.conf} file to +\dirname{/etc/fonts/conf.d/09-texlive.conf}. +\item Run \Ucom{fc-cache -fsv}. +\end{enumerate*} + +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: +\begin{enumerate*} +\item Copy the \filename{texlive-fontconfig.conf} file to + \filename{~/.fonts.conf}, where \filename{~} is your home directory. +\item Run \Ucom{fc-cache -fv}. +\end{enumerate*} + +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} +\label{sec:context-mkiv} + +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: +\begin{sverbatim} +context --generate +\end{sverbatim} +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 +\url{https://wiki.contextgarden.net/Running_Mark_IV}. + + +\subsubsection{Integrating local and personal macros} +\label{sec:local-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: + +\begin{verbatim} + TEXMFHOME = {/my/dir1,/mydir2,/a/third/dir} +\end{verbatim} + +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} +\label{sec:test-install} + +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. + +\begin{enumerate} + +\item Make sure that you can run the \cmdname{tex} program in the first +place: +\begin{alltt} +> \Ucom{tex -{}-version} +TeX 3.14159265 (TeX Live ...) +Copyright ... D.E. Knuth. +... +\end{alltt} +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: +\begin{alltt} +> \Ucom{pdflatex sample2e.tex} +This is pdfTeX 3.14... +... +Output written on sample2e.pdf (3 pages, 142120 bytes). +Transcript written on sample2e.log. +\end{alltt} +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: +\begin{alltt} +> \Ucom{xpdf sample2e.pdf} +\end{alltt} +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: +\begin{alltt} +> \Ucom{latex sample2e.tex} +\end{alltt} + +\item And preview the \dvi{} online: +\begin{alltt} +> \Ucom{xdvi sample2e.dvi} # Unix +> \Ucom{dviout sample2e.dvi} # Windows +\end{alltt} +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: +\begin{alltt} +> \Ucom{dvips sample2e.dvi -o sample2e.ps} +\end{alltt} + +\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: +\begin{alltt} +> \Ucom{dvipdfmx sample2e.dvi -o sample2e.pdf} +\end{alltt} + +\item Other standard test files you may find useful in addition to +\filename{sample2e.tex}: + +\begin{ttdescription} +\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 +story.tex}. +\end{ttdescription} + +\item If you have installed the \filename{xetex} package, you can test +its access to system fonts as follows: +\begin{alltt} +> \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. +\end{alltt} + +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 +section~\ref{sec:font-conf-sys}. + +\end{enumerate} + +\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: +\begin{description} +\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*} +\end{description} +For a much longer list of packages and programs, see +\url{https://tug.org/interest.html}. + + +\section{Specialized installations} + +The previous sections described the basic installation process. Here we +turn to some specialized cases. + +\htmlanchor{tlsharedinstall} +\subsection{Shared-user (or cross-machine) installations} +\label{sec:sharedinstall} + +\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 +\begin{sverbatim} +TEXMFROOT = $SELFAUTOPARENT +... +TEXMFDIST = $TEXMFROOT/texmf-dist +... +TEXMFLOCAL = $SELFAUTOGRANDPARENT/texmf-local +\end{sverbatim} +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 +\url{https://ctan.org/pkg/tlaunch}). + + +\htmlanchor{tlportable} +\subsection{Portable (\USB{}) installations} +\label{sec:portable-tl} + +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: + +\medskip +\tlpng{tray-menu}{4cm} +\smallskip + +\noindent The `More\ldots' entry explains how you can customize this menu. + + +%\htmlanchor{tlisoinstall} +%\subsection{\ISO\ (or \DVD) installations} +%\label{sec:isoinstall} +% +%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: +% +%\begin{itemize} +%\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. +%\end{itemize} +% +%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 +%\url{http://wincdemu.sysprogs.org/}. +% +%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., +%\begin{verbatim} +%sudo ln -s /Volumes/MyTeXLive/bin/universal-darwin /usr/texbin +%\end{verbatim} +% +%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. + + +\htmlanchor{tlmgr} +\section{\cmdname{tlmgr}: Managing your installation} +\label{sec:tlmgr} + +\begin{figure}[tb] +\tlpng{tlshell-macos}{\linewidth} +\caption{\prog{tlshell} \GUI, showing the Actions menu (\MacOSX)} +\label{fig:tlshell} +\end{figure} + +\begin{figure}[tb] +\tlpng{tlcockpit-packages}{.8\linewidth} +\caption{\prog{tlcockpit} \GUI{} for \prog{tlmgr}} +\label{fig:tlcockpit} +\end{figure} + +\begin{figure}[tb] +\tlpng{tlmgr-gui}{\linewidth} +\caption{Legacy \prog{tlmgr} \GUI\ mode: main window, after `Load'} +\label{fig:tlmgr-gui} +\end{figure} + +\TL{} includes a program named \prog{tlmgr} for managing \TL{} after the +initial installation. Its capabilities include: + +\begin{itemize*} +\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}). +\end{itemize*} + +\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} +nowadays. + +\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: +\begin{alltt} +> \Ucom{tlmgr -gui} +\end{alltt} +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: +\begin{alltt} +> \Ucom{tlmgr update -all} +\end{alltt} +If this makes you nervous, first try +\begin{alltt} +> \Ucom{tlmgr update -all -dry-run} +\end{alltt} +or (less verbose): +\begin{alltt} +> \Ucom{tlmgr update -list} +\end{alltt} + +This more complex example adds a collection, for the engine \XeTeX, from +a local directory: + +\begin{alltt} +> \Ucom{tlmgr -repository /local/mirror/tlnet install collection-xetex} +\end{alltt} +It generates the following output (abridged): +\begin{fverbatim} +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. +\end{fverbatim} + +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 +\XeTeX. + +To describe a package (or collection or scheme): +\begin{alltt} +> \Ucom{tlmgr show collection-latexextra} +\end{alltt} +which produces output like this: +\begin{fverbatim} +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 +\end{fverbatim} + +Last and most important, for full documentation see +\url{https://tug.org/texlive/tlmgr.html}, or: +\begin{alltt} +> \Ucom{tlmgr -help} +\end{alltt} + + +\section{Notes on Windows} +\label{sec:windows} + +\subsection{Windows-specific features} +\label{sec:winfeatures} + +Under Windows, the installer does some extra things: +\begin{description} +\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. +\end{description} + +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. + +\begin{description} +\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. + +\end{description} + + +\subsection{User Profile is Home} +\label{sec:winhome} + +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} +\label{sec: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} +\label{sec:winpermissions} + +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} +\label{sec:cygwin-maxmem} + +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 +(\url{https://cygwin.com/cygwin-ug-net/setup-maxmem.html}). + +For Windows, you have to create a file, say \code{moremem.reg}, with +these four lines: + +\begin{sverbatim} +Windows Registry Editor Version 5.00 + +[HKEY_LOCAL_MACHINE\Software\Cygwin] +"heap_chunk_in_mb"=dword:ffffff00 +\end{sverbatim} + +\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 +\url{https://tug.org/web2c}. + +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 +2006. + +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: + +\begin{cmddescription} +\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. +\end{cmddescription} + +\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: +\begin{ttdescription} +\item[-{}-help] print basic usage summary. +\item[-{}-version] print version information, then exit. +\end{ttdescription} + +And most also honor: +\begin{ttdescription} +\item[-{}-verbose] print detailed progress report. +\end{ttdescription} + +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} +\label{sec:kpathsea} + +Let us first describe the generic path searching mechanism of the \KPS{} +library. + +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 +matches). + +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 +place. + +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. + +\ifSingleColumn +\else +\begin{figure*} +\verbatiminput{examples/ex5.tex} +\setlength{\abovecaptionskip}{0pt} + \caption{An illustrative configuration file sample} + \label{fig:config-sample} +\end{figure*} +\fi + +\subsubsection{Path sources} +\label{sec:path-sources} + +A search path can come from many sources. In the order in which +\KPS{} uses them: + +\begin{enumerate} +\item + 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}. +\item + 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. +\end{enumerate} +\noindent You can see each of these values for a given search path by +using the debugging options (see ``Debugging actions'' on +page~\pageref{sec:debugging}). + +\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 +method: +\begin{verbatim} + TEXINPUTS=.:/my/macro/dir: +\end{verbatim} +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|. + +\begin{itemize*} +\item + Comments start with \code{\%}, either at the beginning of a line or + preceded by whitespace, and continue to the end of the line. +\item + Blank lines are ignored. +\item + 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. +\item + 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.) +\item + The \ttvar{variable} name may contain any character other + than whitespace, \samp{=}, or \samp{.}, but sticking to + \samp{A-Za-z\_} is safest. +\item + 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. + +\item + All definitions are read before anything is expanded, so + variables can be referenced before they are defined. +\end{itemize*} +A configuration file fragment illustrating most of these points is +\ifSingleColumn +shown below: + +\verbatiminput{examples/ex5.tex} +\else +shown in figure~\ref{fig:config-sample}. +\fi + +\subsubsection{Path expansion} +\label{sec: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} +\label{sec: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 + +\begin{alltt} +> \Ucom{setenv TEXINPUTS /home/karl:} +\end{alltt} +and a \code{TEXINPUTS} value from \file{texmf.cnf} of + +\begin{alltt} + .:\$TEXMF//tex +\end{alltt} +then the final value used for searching will be: + +\begin{alltt} + /home/karl:.:\$TEXMF//tex +\end{alltt} + +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} +\label{sec: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: +\begin{verbatim} + TEXMF = {$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFDIST} +\end{verbatim} +We then use this to define, for example, the \TeX\ input path: +\begin{verbatim} + TEXINPUTS = .;$TEXMF/tex// +\end{verbatim} +%$ +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} +\label{sec: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} +\label{sec:cnf-special-chars} + +The following list summarizes the special characters and constructs in +\KPS{} configuration files. + +% need a wider space for the item labels here. +\newcommand{\CODE}[1]{\makebox[3em][l]{\code{#1}}} +\begin{ttdescription} +\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. +\end{ttdescription} + +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} +\label{sec:filename-database} + +\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} +\label{sec:ls-R} + +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 +\begin{alltt} +cd \var{/your/texmf/root} && \path|\|ls -1LAR ./ >ls-R +\end{alltt} +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} +\label{sec:invoking-kpsewhich} + +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). + +\begin{alltt} +> \Ucom{kpsewhich \var{option}\dots{} \var{filename}\dots{}} +\end{alltt} +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. + +\begin{ttdescription} +\item[\texttt{-{}-dpi=\var{num}}]\mbox{} + 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. + +\item[\texttt{-{}-format=\var{name}}]\mbox{}\\ + 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. + +\item[\texttt{-{}-mode=\var{string}}]\mbox{}\\ + Set the mode name to \ttvar{string}; this only affects \samp{gf} + and \samp{pk} lookups. No default: any mode will be found. +\item[\texttt{-{}-must-exist}]\mbox{}\\ + 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. +\item[\texttt{-{}-path=\var{string}}]\mbox{}\\ + 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. +\item[\texttt{-{}-progname=\var{name}}]\mbox{}\\ + 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}. +\item[\texttt{-{}-show-path=\var{name}}]\mbox{}\\ + 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. +\item[\texttt{-{}-debug=\var{num}}]\mbox{}\\ + sets the debugging options to \texttt{\var{num}}. +\end{ttdescription} + + +\subsubsection{Examples of use} +\label{sec:examples-of-use} + +Let us now have a look at \KPS{} in action. Here's a straightforward search: + +\begin{alltt} +> \Ucom{kpsewhich article.cls} + /usr/local/texmf-dist/tex/latex/base/article.cls +\end{alltt} +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. +\begin{alltt} +> \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 +\end{alltt} + +By the way, that last is a \BibTeX{} bibliography database for +\textsl{TUGboat} articles. + +\begin{alltt} +> \Ucom{kpsewhich cmr10.pk} +\end{alltt} +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. +\begin{alltt} +> \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 +\fi\end{alltt} +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. +\begin{alltt} +> \Ucom{kpsewhich -dpi=300 wsuipa10.pk} +\end{alltt} +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 +\texttt{config.ps}. +\begin{alltt} +> \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 +\end{alltt} + +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: +\begin{alltt} +> \Ucom{kpsewhich --format="dvips config" config.utm} + /usr/local/texmf-dist/dvips/psnfss/config.utm +\end{alltt} +The contents of that file is +\begin{alltt} + p +utm.map +\end{alltt} +which points to the file \file{utm.map}, which we want to +locate next. +\begin{alltt} +> \Ucom{kpsewhich utm.map} + /usr/local/texmf-dist/fonts/map/dvips/times/utm.map +\end{alltt} +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 +lines): +\begin{alltt} +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 +\end{alltt} +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: +\begin{alltt} +> \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 +\fi\end{alltt} + +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} +\label{sec:debugging} + +Sometimes it is necessary to investigate how a program resolves file +references. To make this practical, \KPS{} offers various levels of +debugging output: + +\begin{ttdescription} +\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. +\end{ttdescription} +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. +\begin{verbatim} + \documentclass{article} + \begin{document} + Hello World! + \end{document} +\end{verbatim} +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}). +\begin{alltt} +> \Ucom{dvips -d4100 hello-world -Pcms -o} +\end{alltt} +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 +Figure~\ref{fig:dvipsdbga}. +\begin{figure*}[tp] +\centering +\input{examples/ex6a.tex} +\caption{Finding configuration files}\label{fig:dvipsdbga} +\end{figure*} + +\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. +\begin{alltt} +> \Ucom{more /usr/local/texmf/dvips/cms/config.cms} + p +ams.map + p +cms.map + p +cmbkm.map + p +amsbkm.map +\end{alltt} +\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: +\begin{alltt} +This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com) +\end{alltt} +\ifSingleColumn +Then it goes on to look for the prolog file \file{texc.pro}: +\begin{alltt}\small +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 +\end{alltt} +\else +Then it goes on to look for the prolog file \file{texc.pro} (see +Figure~\ref{fig:dvipsdbgb}). +\fi + +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): +\begin{alltt}\small +TeX output 1998.02.26:1204' -> hello-world.ps +Defining font () cmr10 at 10.0pt +Font cmr10 <CMR10> is resident. +\end{alltt} +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). +\begin{alltt}\small +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, + ... +<texps.pro> +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 +<cmr10.pfb>[1] +\end{alltt} + +\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 +are: + +\begin{ttdescription} +\item[\texttt{main\_memory}] + 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}. +\item[\texttt{extra\_mem\_bot}] + Extra space for ``large'' \TeX{} data structures: + boxes, glue, breakpoints, etc. Especially useful if you use + \PiCTeX{}. +\item[\texttt{font\_mem\_size}] + Number of words for font information available for \TeX. This + is more or less the total size of all TFM files read. +\item[\texttt{hash\_extra}] + Additional space for the hash table of control sequence names; its + default value is \texttt{600000}. +\end{ttdescription} + +\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. + +\htmlanchor{texmfdotdir} +\subsection{\texttt{\$TEXMFDOTDIR}} +\label{sec:texmfdotdir} + +In various places above, we gave various search paths starting with +\code{.} (to search the current directory first), as in +\begin{alltt}\small +TEXINPUTS=.;$TEXMF/tex// +\end{alltt} + +This is a simplification. The \code{texmf.cnf} file we distribute in +\TL{} uses \filename{$TEXMFDOTDIR} instead of just \samp{.}, as in: +\begin{alltt}\small +TEXINPUTS=$TEXMFDOTDIR;$TEXMF/tex// +\end{alltt} +(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 +\filename{texmf.cnf}. + +\htmlanchor{ack} +\section{Acknowledgements} + +\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. + +\begin{itemize*} + +\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 +\url{https://tug.org/usergroups.html}.) + +\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 +abilities. + +\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 +so. + +\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 +\pkgname{hyperref}. + +\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 +\cmdname{xindy}. + +\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\ +support. + +\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. + +\end{itemize*} + +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 +\url{https://tug.org/texlive/build.html}. + +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} +\label{sec:history} + +\subsection{Past} + +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 +\TL. + +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. + +\subsubsection{2003} + +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 +addition: + +\begin{itemize*} +\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. +\end{itemize*} + + +\subsubsection{2004} + +2004 saw many changes: + +\begin{itemize} + +\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 +\url{https://tug.org/texlive/mapenc.html}. + +\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 +\CDref{texmf-dist/doc/generic/tds/tds.html\#Extensions} +{\texttt{texmf-dist/doc/generic/tds/tds.html\#Extensions}}. + +\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 +\CDref{texmf-dist/doc/generic/tds/tds.html\#Scripts} +{\texttt{texmf-dist/doc/generic/tds/tds.html\#Scripts}}. + +\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} +{\texttt{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 +(\OnCD{texmf-dist/doc/etex/base/}). + +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: +\begin{verbatim} +\input "filename with spaces" % plain +\input{"filename with spaces"} % latex +\end{verbatim} +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 +\url{http://olsak.net/enctex.html}. + +\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 +\OnCD{texmf-dist/doc/latex/base}. + +\item \cmdname{dvipng}, a new program for converting DVI to +PNG image files, is included. See +\url{https://ctan.org/pkg/dvipng}. + +\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. + +\end{itemize} + +\subsubsection{2005} + +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: + +\begin{itemize} + +\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: +\begin{verbatim} +latex --translate-file=empty.tcx yourfile.tex +\end{verbatim} + +\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. + +\end{itemize} + + +\subsubsection{2006--2007} + +In 2006--2007, the major new addition to \TL{} was the \XeTeX{} program, +available as the \texttt{xetex} and \texttt{xelatex} programs; see +\url{https://scripts.sil.org/xetex}. + +MetaPost also received a notable update, with more planned for the +future (\url{https://tug.org/metapost/articles}), likewise pdf\TeX{} +(\url{https://tug.org/applications/pdftex}). + +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 +everyone. + +\subsubsection{2008} + +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\ +documents. + +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 +\cmdname{dvipdfmx}. + +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 +\url{https://tug.org/TUGboat/Articles/tb29-2/tb92knut.pdf}. + +\subsubsection{2009} + +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 +\url{https://ams.org/tex/amsfonts.html}. + +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 +ease-of-use. + +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 +\url{ftp://tug.org/historic/systems/texlive}. + + +\subsubsection{2010} +\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 +(\url{https://ctan.org/pkg/epstopdf-pkg}). + +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 +\AllTeX\ +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. + +\subsubsection{2011} + +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). + +\subsubsection{2012} + +\code{tlmgr} supports updates from multiple network repositories. The +section on multiple repositories in the \code{tlmgr help} output has +more. + +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 +extant. + +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 +exists. + +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. + +\subsubsection{2013} + +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 +\code{texmf-dist}. + +Many small language collections have been merged together, to simplify +installation. + +\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): +\begin{itemize*} +\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 +layout. +\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 +\code{xdvipdfmx}. +\item Support OpenType math cut-ins. +\end{itemize*} + +\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 +enhancements. + +\cmdname{tlmgr}: new \code{pinning} action to ease configuring multiple +repositories; that section in \verb|tlmgr --help| has more, online at +\url{https://tug.org/texlive/doc/tlmgr.html#MULTIPLE-REPOSITORIES}. + +Platforms: \pkgname{armhf-linux}, \pkgname{mips-irix}, +\pkgname{i386-netbsd}, and \pkgname{amd64-netbsd} added or revived; +\pkgname{powerpc-aix} removed. + +\subsubsection{2014} + +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. + +\subsubsection{2015} + +\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 +\prog{up*tex}. + +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. + +% +\subsubsection{2016} + +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, +\OnCD{texmf-dist/doc/luatex/base/luatex.pdf}. + +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 +incremented. + +Other utilities: +\begin{itemize*} +\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 +changes. + +\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. +\end{itemize*} + +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. + +% +\subsubsection{2017} + +Lua\TeX: More callbacks, more typesetting control, more access to +internals; \code{ffi} library for dynamic code loading added on some +platforms. + +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 +winning. + +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 +accepted). + +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. + +% +\subsubsection{2018} + +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 +fixes. + +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}. + +Platforms: +\begin{itemize*} +\item +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. +\end{itemize*} + +% +\subsubsection{2019} + +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 +\cs{expanded}. + +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{creationdate}, +\cs{elapsedtime}, +\cs{filedump}, +\cs{filemoddate}, +\cs{filesize}, +\cs{resettimer}, +\cs{normaldeviate}, +\cs{uniformdeviate}, +\cs{randomseed}; extend \cs{Ucharcat} to produce active +characters. + +\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}). + +Utilities: +\begin{itemize*} +\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. +\end{itemize*} + +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}. + +% +\subsubsection{2020} + +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}, +\url{https://latex-project.org/news}). + +\end{itemize} + +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 +\cs{openin}. + +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 +capabilities +(\url{https://tug.org/TUGboat/tb40-2/tb125rokicki-type3search.pdf}). + +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. +\end{itemize*} + +% +\htmlanchor{news} +\subsection{Present: 2021} +\label{sec:tlcurrent} + +General: \begin{itemize} +\item Donald Knuth's changes for his 2021 tuneup of \TeX\ and Metafont are +incorporated +(\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. + +\end{itemize} + +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. +\end{itemize*} + +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. +\end{itemize*} + +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}. +\end{itemize*} + +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. +\end{itemize*} + +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 +status. +\item Support new feature of virtual font to fallback Japanese font definition. +\end{itemize*} + +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 +\texttt{texmf-var/web2c/tlmgr-commands.log}. +\end{itemize*} + + + +\subsection{Future} + +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: +\begin{quote} +\email{tex-live@tug.org} \\ +\url{https://tug.org/texlive} +\end{quote} + +\medskip +\noindent \textsl{Happy \TeX ing!} + +\end{document} diff --git a/Master/texmf-dist/doc/texlive/texlive-en/archive/live4ht.cfg-2021 b/Master/texmf-dist/doc/texlive/texlive-en/archive/live4ht.cfg-2021 new file mode 100644 index 00000000000..146a9ac0658 --- /dev/null +++ b/Master/texmf-dist/doc/texlive/texlive-en/archive/live4ht.cfg-2021 @@ -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. +\Preamble{} + +% add extra stylesheet +\Configure{@HEAD}{\HCode{% +<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 +\Configure{graphics*} + {png} + {\Needs{""}% + \Picture[pict]{../texlive-common/\csname Gin@base\endcsname.png}% + } +% or LaTeX complains it is missing. +\begin{document} + +\EndPreamble + +% simplify output for HTML. We leave TeX and LaTeX alone, since tex4ht +% actually does the lowered E (and raised A) in CSS. +\def\OMEGA{Omega} +\def\LaTeXe{LaTeX2e} +\def\eTeX{e-\TeX} +\def\acro#1{#1} +\def\MF{Metafont} +\def\BibTeX{BibTeX} +\def\warningbox{} +\def\endwarningbox{} + +\newif\ifhackliterals +\ifx\tldocenglish\undefined \else \hackliteralstrue \fi +\ifx\tldocrussian\undefined \else \hackliteralstrue \fi +\ifx\tldocgerman\undefined \else \hackliteralstrue \fi +% +\ifhackliterals + % 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 +\fi diff --git a/Master/texmf-dist/doc/texlive/texlive-en/archive/tex-live.sty-2021 b/Master/texmf-dist/doc/texlive/texlive-en/archive/tex-live.sty-2021 new file mode 100644 index 00000000000..db26ec78f1c --- /dev/null +++ b/Master/texmf-dist/doc/texlive/texlive-en/archive/tex-live.sty-2021 @@ -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. +% +\NeedsTeXFormat{LaTeX2e}[1995/12/01] +\ProvidesPackage{tex-live}[2019/08/14 TeX Live Guide style] +% +% colortbl and other packages otherwise make the default be letter, it seems. +\RequirePackage[a4paper,hscale=0.75,lines=60,vmarginratio=10:8]{geometry} +% +\RequirePackage{alltt} +\RequirePackage{array} +\RequirePackage{colortbl} +\RequirePackage{comment} +\RequirePackage{float} +\RequirePackage{graphicx} +\RequirePackage{longtable} +\RequirePackage{shortvrb} +\RequirePackage[normalem]{ulem} +\RequirePackage[obeyspaces]{url} +\RequirePackage{xspace} +% +% for a proper \acro command. +\RequirePackage{relsize} +%\DeclareRobustCommand{\acro}[1]{\textscale{.9}{#1}\@} +\def\acro#1{\texorpdfstring{\textscale{.9}{#1}}{#1}\@} +% +%% No lmodern for Russian; LM doesn't have cyrillic. +\ifx\tldocrussion\undefined \RequirePackage{lmodern}\fi +% +\usepackage{textcomp}% including \textbullet +\def\p.{p.\,} + +\RequirePackage{fancyvrb} +\DefineVerbatimEnvironment{verbatim}{Verbatim}{fontsize=\normalsize} +\DefineVerbatimEnvironment{sverbatim}{Verbatim}{fontsize=\small} +\DefineVerbatimEnvironment{fverbatim}{Verbatim}{fontsize=\footnotesize} +\DefineVerbatimEnvironment{boxedverbatim} + {Verbatim}{fontsize=\footnotesize,frame=single} +\DefineVerbatimEnvironment{Verbatim}{Verbatim}{fontsize=\normalsize} +\def\verbatiminput#1{\VerbatimInput[fontsize=\small]{#1}} +\def\boxedverbatiminput#1{\VerbatimInput[frame=single,fontsize=\footnotesize]{#1}} +\def\listinginput#1#2{\VerbatimInput[fontsize=\scriptsize,firstnumber=#1,numbers=left]{#2}} +\MakeShortVerb\| +% +% +% 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 + +% +\pagestyle{headings} +% +% LaTeX parameters. +\renewcommand{\topfraction}{0.85} +\renewcommand{\floatpagefraction}{0.86} +\renewcommand{\textfraction}{0.1} +\renewcommand{\abovecaptionskip}{4pt} +\renewcommand{\belowcaptionskip}{4pt} +\setcounter{tocdepth}{3} +\setcounter{secnumdepth}{3} +\setcounter{topnumber}{5} +\setcounter{totalnumber}{5} +% +% linebreaking, etc. +\hbadness=4000 +\vbadness=4000 +\emergencystretch=.1\hsize +\relpenalty=500 +% +\def\slash{/\penalty\z@\hskip\z@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{\code}[1]{\texttt{#1}} +\newcommand{\file}[1]{\texttt{#1}} +\newcommand{\prog}[1]{\textsf{#1}}% same as \cmdname +\newcommand{\samp}[1]{`\texttt{#1}'\@} +\newcommand{\var}[1]{{\sl #1}}% not \textsl, for roman not typewriter slanted. +\newcommand{\ttvar}[1]{\texttt{\var{#1}}} +% +% underlined command input. +%\def\Ucom#1{% +% \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.) +\def\CDref#1#2{\texttt{#1}} +% +% \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. +\def\OnCD#1{\path{#1}} +% +% \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. +%\def\OnCD#1{\href{../../../../#1}{\path{#1}}} +% +% \href incorrectly appends .pdf to anything without an extension; these +% definitions using \hyper@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@linkurl{#2}{../../../../#1}} +%\def\OnCD#1{\hyper@linkurl{\path{#1}}{../../../../#1}} + +% GUI menu/button/tab sequence: +\def\guiseq#1{\textsf{#1}} +\def\arw{\unskip$\rightarrow$\ignorespaces} +% +% Special names. +\def\dpi{$\,$dpi\xspace} +\def\bs{{\protect\normalfont\ttfamily\char'134}} +\DeclareRobustCommand{\cs}[1]{{\normalfont\ttfamily\char`\\#1}} +\def\Q#1{\par\vskip6pt\leftline{#1}\par} +\def\hyph{-} +% +% many abbreviations. +\def\AllTeX{(\La\kern-.075em)\kern-.075em\TeX} +\def\AFMtoTFM{\cmdname{AFM2TFM}\null} +\def\bv{\emph{Baskerville}} +\let\BV=\bv +\newcommand{\CS}{$\mathcal{C}\kern-.1667em\lower.5ex% + \hbox{$\mathcal{S}$}\kern-.075em $} +\def\Dash{\unskip\nobreak\thinspace---\thinspace\ignorespaces} +\def\dvicopy{\cmdname{dvicopy}} +\def\dvidvi{\cmdname{dvidvi}} +\def\dvips{\cmdname{dvips}} +\def\eTeX{$\varepsilon$-\TeX} +\def\fpTeX{\textrm{fp}\TeX\xspace} +\def\GFtoDVI{\cmdname{GFtoDVI}\null} +\def\GFtoPK{\cmdname{GFtoPK}\null} +\def\GFtype{\cmdname{GFtype}} +\def\GUI{GUI\xspace} +\def\KPS{Kpathsea} +% This code % is hacked from its definition of \cs{LaTeX}; it allows +% slants (for example) to propagate into the raised (small) `A': +\newcommand{\La}% + {L\kern-.36em + {\setbox0\hbox{T}% + \vbox to\ht0{\hbox{$\m@th$% + \csname S@\f@size\endcsname + \fontsize\sf@size\z@ + \math@fontsfalse\selectfont + A}% + \vss}% + }} +\def\OMEGA{$\Omega$} +\def\OzMF{OzMF} +\def\OzMP{OzMP} +\def\OzTeX{O\kern-.03em z\kern-.15em\TeX} +\def\PKtype{\cmdname{PKtype}} +\def\PLtoTF{\cmdname{PLtoTF}\null} +\def\ProTeXt{pro\TeX t} +\def\teTeX{\textrm{te}\TeX\xspace} +\def\TeXLive{\TeX{} Live\xspace} +\def\TFtoPL{\cmdname{TFtoPL}\null} +\def\TK{\TeX\ Collection} +\let\TL=\TeXLive +\def\TypeI{Type~1} +\def\VFtoVP{\cmdname{VFtoVP}\null} +\def\VPtoVF{\cmdname{VPtoVF}\null} +\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} +\def\XEmTeX{\textrm{XEm}\TeX\xspace} +\def\XEmacs{\textrm{XEmacs}\xspace} +\def\XeTeX{Xe\TeX} +\def\Webc{Web2C} +\providecommand*{\CD}{CD\xspace} +\providecommand*{\CTAN}{CTAN\xspace} +\providecommand*{\DVD}{DVD\xspace} +\providecommand*{\GNU}{GNU\xspace} +\providecommand*{\HTML}{HTML\xspace} +\providecommand*{\ISO}{ISO\xspace} +\providecommand*{\MacOSX}{\texorpdfstring{Mac\,OS\,X}{MacOSX}\xspace} +\providecommand*{\PS}{Post\-Script\xspace} +\providecommand*{\TDS}{TDS\xspace} +\providecommand*{\USB}{USB\xspace} +\providecommand*{\dvi}{DVI\xspace} +\providecommand*{\web}{\texttt{WEB}\xspace} + +% Include a png image. +% #1 - name of image file in ../texlive-common/, always .png +% #2 - width for TeX +% +\def\tlpng#1#2{% + \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@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. +% +\newenvironment{ttdescription} + {\begin{list}{label must be supplied}{% + \itemsep=0pt % these lists tend to have short descriptions + \parindent=0pt + \let\makelabel=\ttdescriptionlabel}}% + {\end{list}} +\newcommand*\ttdescriptionlabel[1]{\hspace\labelsep + \normalfont\ttfamily #1\hfil} +% +% Likewise, for commands using sans serif. +\newenvironment{cmddescription} + {\begin{list}{label must be supplied}{% + \itemsep=0pt + \let\makelabel=\cmddescriptionlabel}}% + {\end{list}} +\newcommand*\cmddescriptionlabel[1]{\hspace\labelsep + \normalfont\sffamily #1\hfil} + +% General squeezed itemize/enumerate; no extra space at top or between items. +\newenvironment{itemize*}% + {\begin{itemize}% + \setlength{\itemsep}{0pt}% + \setlength{\parskip}{0pt}% + \setlength{\topsep}{0pt}% + \setlength{\partopsep}{0pt}% + }% + {\end{itemize}} + +\newenvironment{enumerate*}% + {\begin{enumerate}% + \setlength{\itemsep}{0pt}% + \setlength{\parskip}{0pt}}% + {\end{enumerate}} + +\newsavebox{\wbox} +\newenvironment{warningbox} + {\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 +\newsavebox{\mylrbox} +\newenvironment{lrBox} + {\begin{lrbox}{\mylrbox}} + {\end{lrbox}} + + +% emacs-page output setup +% +\ifx \HCode\UnDef + \providecommand{\Status}{0}% running TeX +\else + \providecommand{\Status}{2}% running TeX4ht +\fi +%\typeout{Status is \Status} +% +\newif\ifSingleColumn +% +% By default, we won't be creating hyperlinks. +\def\href#1#2{#2} +\def\hypertarget#1#2{} +\def\email#1{\href{mailto:#1}{\path{#1}}} % \path comes from url +\def\htmlanchor#1{} +% +\definecolor{hypercolor}{rgb}{0.5,0.0,0.5} % purplish external links. +% +% +\ifcase\Status + % \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]{}{} +\fi +% +\ifnum \Status=4 +\else + \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 +\fi +% +% hacking at sections etc., to pay attention to baskerville status +\newcommand{\@condend@multicols}{% + \ifSingleColumn + \else + \def\@tempa{multicols}% + \ifx\@tempa\@currenvir + \end{multicols}% + \fi + \fi +} +\let\Section\section +\renewcommand{\section}{% + \@ifstar + {\Section*}% + {% + \@condend@multicols + \@dblarg\@full@section + }% +} +\def\@full@section[#1]#2{% + \Section[#1]{#2}% + \ifSingleColumn\else\begin{multicols}{2}\fi +} +\let\SubSection\subsection +\renewcommand{\subsection}{% + \@ifstar{\SubSection*}% + {% + \@condend@multicols + \@dblarg\@full@subsection + } +} +\def\@full@subsection[#1]#2{% + \SubSection[#1]{#2}% + \ifSingleColumn\else\begin{multicols}{2}\fi +} + +% Reduce list spacing. +\def\@listI{\leftmargin\leftmargini + \parsep \z@ + \topsep 2\p@ \@plus 1\p@ \@minus 1\p@ + \itemsep \z@ \@plus .1\p@ +} +\let\@listi\@listI +\@listi +\def\@listii{\leftmargin\leftmarginii + \labelwidth\leftmarginii\advance\labelwidth-\labelsep + \topsep 2\p@ \@plus 1\p@ \@minus 1\p@ + \parsep \z@ + \itemsep \z@ \@plus .1\p@ +} +\def\@listiii{\leftmargin\leftmarginiii + \labelwidth\leftmarginiii\advance\labelwidth-\labelsep + \topsep 1\p@ \@plus 1\p@ \@minus 1\p@ + \parsep \z@ + \partopsep \z@ + \itemsep \topsep +} +\def\@listiv{\leftmargin\leftmarginiv + \labelwidth\leftmarginiv\advance\labelwidth-\labelsep +} +\def\@listv{\leftmargin\leftmarginv + \labelwidth\leftmarginv\advance\labelwidth-\labelsep +} +\def\@listvi{\leftmargin\leftmarginvi + \labelwidth\leftmarginvi\advance\labelwidth-\labelsep +} +% +% array package stuff +\def\arraybackslash{\let\\=\@arraycr} +\newcolumntype{P}[1]{>{\raggedright\arraybackslash}p{#1}} +% +% shaded rows (using facilities of colortbl) +% +\definecolor{pale}{gray}{.9} +\newcount\colrow +\gdef\RowColor{pale} +\def\SetRowColor{% + \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@filesw \immediate\write\@auxout + {\string\bibcite{#1}{?}}\fi\ignorespaces} +% +% \unknownTeXlive is a dummy texlive entry for the biblio +\newcommand\unknownTeXlive[2][\relax]{\textbf{\textsc{unknown}}% + \global\@all@unknown\expandafter{\the\@all@unknown{#2}}% +} +\newtoks\@all@unknown +\global\@all@unknown{} +\AtEndDocument{\@message@unknowns} +\def\@message@unknowns{\edef\@tempa{\the\@all@unknown}% + \ifx\@tempa\@empty + \else + \def\@tempa{*** TeX Live package location of }% + \expandafter\@output@unknowns\the\@all@unknown\@empty + \fi +} +\def\@output@unknowns#1{\edef\@tempb{#1}% + \ifx\@tempb\@empty + \typeout{ unknown}% + \else + \message{\@tempa#1,}% + \def\@tempa{}% + \expandafter\@output@unknowns + \fi +} + + +% Silence font warnings about no bold typewriter in LM. +\def\@font@warning#1{}% + +% Silence hyperref warnings about \kern. +\def\HyPsd@Warning#1{}% + +\endinput |