diff options
Diffstat (limited to 'Master/texmf-dist/doc/texlive/texlive-en/archive/live-2014.tex')
-rw-r--r-- | Master/texmf-dist/doc/texlive/texlive-en/archive/live-2014.tex | 3495 |
1 files changed, 3495 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2014.tex b/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2014.tex new file mode 100644 index 00000000000..634836dda5c --- /dev/null +++ b/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2014.tex @@ -0,0 +1,3495 @@ +% $Id: texlive-en.tex 36087 2015-01-18 23:22:31Z 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} + +\begin{document} + +\title{% + {\huge \textit{The \TeX\ Live Guide---2014}} +} + +\author{Karl Berry, editor \\[3mm] + \url{http://tug.org/texlive/} + } + +\date{May 2014} + +\maketitle + +\begin{multicols}{2} +\tableofcontents +%\listoftables +\end{multicols} + +\section{Introduction} +\label{sec:intro} + +\subsection{\TeX\ Live and the \TeX\ 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 \acro{XP} and later are supported. Windows~2000 +will probably still mostly work. There are no special 64-bit +executables for Windows, but the 32-bit executables should run on 64-bit +systems. + +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{http://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 The installation script is named \filename{install-tl}. It can + operate in a ``wizard mode'' given the option \code{-gui=wizard} + (default for Windows), a text mode given \code{-gui=text} (default for + everything else), and an expert \GUI{} mode given \code{-gui=perltk}. + +\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; for maximum safety, use a new subdirectory. + +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. + + +\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 readers, 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{http://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{http://tug.org/begin.html} gives a brief introduction to the system. + +\item [\TeX{} \acro{FAQ}] The \TeX{} \acro{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{http://www.tex.ac.uk/faq}. Please + check here first. + +\item [\TeX{} Catalogue] If you are looking for a specific package, +font, program, etc., the \TeX{} Catalogue is the place to look. It is a +huge collection of all \TeX{}-related items. See +\url{http://mirror.ctan.org/help/Catalogue/}. + +\item [\TeX{} Web Resources] The web page +\url{http://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 include the +Usenet newsgroup \url{news:comp.text.tex}, the mailing list +\email{texhax@tug.org}, and \url{http://tex.stackexchange.com}, a +collaboratively edited question and answer site. Their archives have +years of past questions and answers for your searching pleasure, via +\url{http://groups.google.com/group/comp.text.tex/topics} and +\url{http://tug.org/mail-archives/texhax}, respectively. And a general +web search, for example on \url{http://google.com}, never hurts. + +\item [asking questions] If you cannot find an answer, you can post to +\dirname{comp.text.tex} through Google or your newsreader, or to +\email{texhax@tug.org} through email. But before you post, +\emph{please} read this \acro{FAQ} entry, to maximize +your chances of getting a useful answer: +\url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=askquestion}. +Also worth mentioning are the \LaTeX{} Community site at +\url{http://www.latex-community.org/} and its forum +\url{http://www.latex-community.org/forum/}, and +\TeX\ StackExchange at \url{http://tex.stackexchange.com/}. + +\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. Both +\dirname{comp.text.tex} and \code{texhax} 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: \TL, pro\TeX{}t, Mac\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{http://tug.org/texlive/}. + +\item [Mac\TeX] for \MacOSX, this adds a native \MacOSX\ installer and other +Mac applications to \TL{}. Home page: +\url{http://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{http://tug.org/protext/}. + +\item [CTAN] A snapshot of the \CTAN{} repository (\url{http://www.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 \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} + +In addition to the directories above, the installation scripts and +\filename{README} files (in various languages) are at the top level of +the distribution. + +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{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{http://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. + +\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 [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 [TEXMFCONFIG] The (personal) tree used by the utilities + \verb+texconfig+, \verb+updmap+, and \verb+fmtutil+ to store modified + configuration data. +\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 [TEXMFVAR] The (personal) tree used by \verb+texconfig+, + \verb+updmap+ and \verb+fmtutil+ to store (cached) runtime data such + as format files and generated map files. +\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 [TEXMFCACHE] The tree(s) used by \ConTeXt\ Mk\acro{IV} 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: + \begin{ttdescription} + \item[2013] A previous release. + \item[2014] The current release. + \begin{ttdescription} + \item [bin] ~ + \begin{ttdescription} + \item [i386-linux] \GNU/Linux binaries + \item [...] + \item [universal-darwin] \MacOSX\ binaries + \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[.texlive2013] Privately generated and configuration data + for a previous release. + \item[.texlive2014] 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 \acro{PDF} output as well as \dvi{}, and many non-output-related +extensions. This is the program invoked for most 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/manual/samplepdf/samplepdf.tex} for example +usage of some of its features. + +\item [Lua\TeX] is the designated successor of pdf\TeX, +and is mostly (but not entirely) backward-compatible. It is also +intended to be a functional superset of Aleph (see below), though +technical compatibility is not intended. The incorporated Lua +interpreter (\url{http://www.lua.org/}) enables elegant solutions for +many thorny \TeX{} problems. When called as \filename{texlua}, it +functions as a standalone Lua interpreter, and is already used as such +within \TL. Its web site is \url{http://www.luatex.org/}, and the +reference manual is \OnCD{texmf-dist/doc/luatex/base/luatexref-t.pdf}. + +\item [\XeTeX] adds support for Unicode input and OpenType- and system +fonts, implemented using standard third-party libraries. See +\url{http://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' (\acro{OTP}s), +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, bibtex8] bibliography support. + +\item [makeindex, xindy] index support. + +\item [dvips] convert \dvi{} to \PS{}. + +\item [xdvi] \dvi{} previewer for the X Window System. + +\item [dvilj] \dvi{} drive for the HP LaserJet family. + +\item [dviconcat, dviselect] cut and paste pages +from \dvi{} files. + +\item [dvipdfmx] convert \dvi{} to \acro{PDF}, an alternative approach +to pdf\TeX\ (mentioned above). + +\item [psselect, psnup, \ldots] \PS{} utilities. + +\item [pdfjam, pdfjoin, \ldots] \acro{PDF} utilities. + +\item [context, mtxrun] Con\TeX{}t and \acro{PDF} processor. + +\item [htlatex, \ldots] \cmdname{tex4ht}: \AllTeX{} to \acro{HTML} (and +\acro{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{http://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} will automatically +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 three choices: ``Simple install'' +starts up the wizard installer, ``Custom install'' the expert GUI +installer, as described in section~\ref{sec:wininst}. A third option is +just unpacking. + +\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{http://tug.org/usergroups.html}), or purchasing it separately +(\url{http://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 .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. + +\noindent +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 expert \GUI\ mode (figure~\ref{fig:gui-main}), you'll +need the \dirname{Perl::TK} module compiled with \acro{XFT} support, +which is generally the case with \GNU/Linux, but often not so with other +systems. Given that, you can run: +\begin{alltt} +> \Ucom{perl install-tl -gui} +\end{alltt} + +For a complete listing of the various options: +\begin{alltt} +> \Ucom{perl install-tl -help} +\end{alltt} + +\textbf{Warning 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{http://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}. If you want more customization +options, e.g., selection of specific package collections, run +\filename{install-tl-advanced.bat} instead. + +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:wizard-w32} displays the wizard 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 2014 from: ... +Platform: i386-linux => 'Intel x86 with GNU/Linux' +Distribution: inst (compressed) +... + Detected platform: Intel x86 with GNU/Linux + + <B> binary platforms: 1 out of 21 + + <S> set installation scheme (scheme-full) + + <C> customizing installation collections + 47 collections out of 48, disk space required: 3641 MB + + <D> directories: + TEXDIR (the main TeX directory): + /usr/local/texlive/2014 + ... + + <O> options: + [ ] use letter size instead of A4 by default + ... + + <V> set up for portable installation + +Actions: + <I> start installation to hard disk + <H> help + <Q> quit +\end{boxedverbatim} +\caption{Main text installer screen (\GNU/Linux)}\label{fig:text-main} +\end{figure} + +\begin{figure}[tb] +\tlpng{install-lnx-main}{\linewidth} +\caption{Expert \GUI{} installer screen (\GNU/Linux)}\label{fig:gui-main} +\end{figure} + +\begin{figure}[tb] +\tlpng{wizard-w32}{\linewidth} +\caption{Wizard installer screen (Windows)}\label{fig:wizard-w32} +\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 for a reason: it +is designed to run on as many platforms as possible, even with a +very barebones Perl. + +\subsubsection{The expert graphical installer} + +Figure~\ref{fig:gui-main} displays the expert graphical installer under +\GNU/Linux. Other than using buttons and menus, this does +not differ much from the text installer. + +This mode can be invoked explicitly with +\begin{alltt} +> \Ucom{install-tl -gui=perltk} +\end{alltt} + + +\subsubsection{The simple wizard installer} + +Under Windows, the default is to run the simplest installation method we +could devise, called the ``wizard'' installer +(figure~\ref{fig:wizard-w32}). It installs everything and asks almost +no questions. If you want to customize your setup, you should run one +of the other installers. + +On other platforms, this mode can be invoked explicitly with +\begin{alltt} +> \Ucom{install-tl -gui=wizard} +\end{alltt} + + +\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 [ ] alpha-linux DEC Alpha with GNU/Linux + b [ ] amd64-freebsd x86_64 with FreeBSD + c [ ] amd64-kfreebsd x86_64 with GNU/kFreeBSD + d [ ] amd64-netbsd x86_64 with NetBSD + e [ ] armel-linux ARM with GNU/Linux + f [ ] armhf-linux ARMhf with GNU/Linux + g [ ] i386-cygwin Intel x86 with Cygwin + h [ ] i386-freebsd Intel x86 with FreeBSD + i [ ] i386-kfreebsd Intel x86 with GNU/kFreeBSD + j [ ] i386-linux Intel x86 with GNU/Linux + k [ ] i386-netbsd Intel x86 with NetBSD + l [ ] i386-solaris Intel x86 with Solaris + m [ ] mipsel-linux mipsel with Linux + o [ ] powerpc-linux PowerPC with GNU/Linux + p [ ] sparc-solaris Sparc with Solaris + s [ ] universal-darwin universal binaries for MacOSX/Darwin + t [ ] win32 Windows + u [ ] x86_64-cygwin x86_64 with Cygwin + v [ ] x86_64-darwin x86_64 with MacOSX/Darwin + w [ ] x86_64-linux x86_64 with GNU/Linux + x [ ] x86_64-solaris x86_64 with Solaris +\end{boxedverbatim} +\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 [ ] teTeX scheme (more than medium, but nowhere near full) + i [ ] XML scheme + j [ ] custom selection of collections +\end{boxedverbatim} +\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 a +small system, \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/2014} on Unix and +|%SystemDrive%\texlive\2014| 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:gui-main}. 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{http://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/2014|'. + +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|. 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\ Mk\acro{IV} (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 setup: +=============================================================================== + <P> use letter size instead of A4 by default: [ ] + <E> execution of restricted list of programs: [X] + <F> create 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 installation, get package updates from CTAN: [X] +\end{boxedverbatim} +\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 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 + (say) binaries or hyphenation patterns are updated in the + installation, and thus you could end up with incompatible format files. + +\item[install font/macro \ldots\ tree:] Omit downloading/installing the + documentation and source files included in most packages. 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. It is strongly + advised \emph{not} to overwrite a \TeX\ system that came with your + system with this option. It is intended primarily 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. + +\item[after installation \ldots\ \CTAN:] 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} + +When all the settings are to your liking, you can type `I' 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] If possible, use the \GUI{} installer. This requires the + Perl/Tk module (\url{http://tug.org/texlive/distro.html#perltk}) + compiled with \acro{XFT} support; if Perl/Tk is not available, + installation continues in text mode. + +\item[-no-gui] Force using the text mode installer, even under + Windows. + +\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{http://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:}, or \texttt{file:/}, or a plain +directory path. (When giving an \texttt{http:}\ 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{http://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/2014/bin/i386-linux:$PATH; export PATH +MANPATH=/usr/local/texlive/2014/texmf-dist/doc/man:$MANPATH; export MANPATH +INFOPATH=/usr/local/texlive/2014/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/2014/bin/i386-linux:$PATH +setenv MANPATH /usr/local/texlive/2014/texmf-dist/doc/man:$MANPATH +setenv INFOPATH /usr/local/texlive/2014/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/2014/bin/i386-linux \ + /usr/local/texlive/2014/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{http://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 \XeTeX\ and Lua\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 made available to \XeTeX\ +automatically. But if you have installed the \filename{xetex} package +on a Unix-compatible system, you need to configure your system to be +able to find the fonts shipped with \TL\ via system name lookup, and not +just filename lookup. + +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{\ConTeXt{} Mark IV} +\label{sec:context-mkiv} + +Both the `old' \ConTeXt{} (Mark \acro{II}) and the `new' \ConTeXt{} +(Mark \acro{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{} Mk\acro{IV} 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 Mk\acro{IV} 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+TEXMSYSVAR;TEXMFVAR+. + +\ConTeXt\ Mk\acro{IV} 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{http://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{http://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. 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 don't already know +that what you want isn't there. + +A possible alternative is to use \XeTeX\ or Lua\TeX\ (see +section~\ref{sec:tex-extensions}), which let you use operating system +fonts without any installation in \TeX. + +If you do need to do this, see +\url{http://tug.org/fonts/fontinstall.html} for our best effort at +describing the procedure. + + +\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{http://tug.org/texworks}) +on Windows, and Mac\TeX\ installs TeXShop +(\url{http://pages.uoregon.edu/koch/texshop}. On other Unix systems, +it's left up to you to choose an editor. Of course there are many other +choices available, some of which are listed in the next section; see +also \url{http://tug.org/interest.html#editors}. In principle, any +plain text editor will work. + +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: +\begin{alltt} +> \Ucom{latex sample2e.tex} +This is pdfTeX 3.14... +... +Output written on sample2e.dvi (3 pages, 7484 bytes). +Transcript written on sample2e.log. +\end{alltt} +If this fails to find \filename{sample2e.tex} or other files, most +likely you 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 result online: +\begin{alltt} +> \Ucom{xdvi sample2e.dvi} # Unix +> \Ucom{dviout sample2e.dvi} # Windows +\end{alltt} +You should see a new window with a nice document explaining some of the +basics of \LaTeX{}. (Well worth reading, by the way, if you're new to +\TeX.) 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 Create a \PS{} file for printing or display: +\begin{alltt} +> \Ucom{dvips sample2e.dvi -o sample2e.ps} +\end{alltt} + +\item Create a \acro{PDF} file instead of \dvi{}; this processes the +\filename{.tex} file and writes \acro{PDF} directly: +\begin{alltt} +> \Ucom{pdflatex sample2e.tex} +\end{alltt} + +\item Preview the \acro{PDF} file: +\begin{alltt} +> \Ucom{gv sample2e.pdf} +\textrm{or:} +> \Ucom{xpdf sample2e.pdf} +\end{alltt} +Neither \cmdname{gv} nor \cmdname{xpdf} are included in \TL{}, so you +must install them separately. See \url{http://www.gnu.org/software/gv} +and \url{http://www.foolabs.com/xpdf}, respectively. There are plenty +of other \acro{PDF} viewers, too. For Windows, we recommend trying +Sumatra PDF (\url{http://blog.kowalczyk.info/software/sumatrapdf}). + +\item 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{http://tug.org/begin.html} for some introductory resources. + +Links for some other tools you may consider installing: +\begin{description} +\item[Ghostscript] \url{http://www.cs.wisc.edu/~ghost/} +\item[Perl] \url{http://www.perl.org/} with + supplementary packages from \acro{CPAN}, \url{http://www.cpan.org/} +\item[ImageMagick] \url{http://www.imagemagick.com}, 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 available natively under Windows, see + \url{http://www.gnu.org/software/emacs/windows/ntemacs.html}. + \item \cmdname{Emacs with Auc\TeX} for Windows is available from \CTAN. + The AuC\TeX\ home page is \url{http://www.gnu.org/software/auctex}. + \item \cmdname{LEd} is available from + \url{http://mirror.ctan.org/support/LEd}. + \item \cmdname{SciTE} is available from + \url{http://www.scintilla.org/SciTE.html}. + \item \cmdname{Texmaker} is free software, available from + \url{http://www.xm1math.net/texmaker}. + \item \cmdname{TeXstudio} started out as a fork of \cmdname{Texmaker} with + additional features; \url{http://texstudio.sourceforge.net}. + \item \cmdname{TeXnicCenter} is free software, available from + \url{http://www.texniccenter.org} and in the pro\TeX{}t distribution. + \item \cmdname{TeXworks} is free software, available from + \url{http://tug.org/texworks} and installed for Windows and + \MacOSX\ as part of \TL. + \item \cmdname{Vim} is free software, available from + \url{http://www.vim.org}. + \item \cmdname{WinEdt} is shareware available though + \url{http://tug.org/winedt} or \url{http://www.winedt.com}. + \item \cmdname{WinShell} is available from \url{http://www.winshell.de}. + \end{itemize*} +\end{description} +For a much longer list of packages and programs, see +\url{http://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 sharable between different users on one +system, and/or 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 = $SELFAUTOPARENT/../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, a sample network installation script named +\filename{w32client} can be downloaded through +\url{http://tug.org/texlive/w32client.html}. It creates settings and +menu shortcuts for using an existing \TL{} installation on a \acro{LAN}. +It also registers an uninstaller \filename{w32unclient}, available +in the same zip file. See the web page for more information. + + +\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. + +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 to choose +between 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 (\acro{FAT32}, \acro{NTFS}, + \acro{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 \acro{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 \acro{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{tlmgr-gui}{\linewidth} +\caption{\prog{tlmgr} in \GUI\ mode: main window, after `Load'.} +\label{fig:tlmgr-gui} +\end{figure} + +\begin{figure}[tb] +\hbox to \hsize{% + \vtop{\hsize=.59\linewidth + \null % make figures align at the top + \tlpng{tlmgr-general-options}{\hsize} + \caption{\texttt{tlmgr} in \GUI\ mode: General options} + \label{fig:tlmgr-general-options} + } + \hfil + \vtop{\hsize=.39\linewidth + \null + \tlpng{tlmgr-paper-options}{\hsize} + \caption{\texttt{tlmgr} in \GUI\ mode: Paper size options} + \label{fig:tlmgr-paper-options} + } +} +\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{\cmdname{tlmgr} GUI mode} +\prog{tlmgr} can be started in \GUI{} mode (figure~\ref{fig:tlmgr-gui}) with +\begin{alltt} +> \Ucom{tlmgr -gui} +\end{alltt} +or in Windows via the Start menu: \texttt{Start}, \texttt{Programs}, +\texttt{TeX Live ...}, \texttt{TeX Live Manager}. After clicking `Load' +it displays a list of available and installed packages. This assumes of +course that the installation source is valid and reachable. + +Figures~\ref{fig:tlmgr-general-options} and~\ref{fig:tlmgr-paper-options} +show the general and paper size option screens. + +\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/2014/texmf-dist/ls-R... +... +running fmtutil-sys --missing +... +Transcript written on xelatex.log. +fmtutil: /usr/local/texlive/2014/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: 32768 +\end{fverbatim} + +Last and most important, for full documentation see +\url{http://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}, the PS\_View (\prog{psv}) + PostScript previewer) and some documentation. +\item[File associations.] If enabled, \prog{TeXworks}, \prog{Dviout} + and \prog{PS\_view} 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. +\end{description} + +\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: +\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[PS\_View.] Also installed is PS\_View, a \PS{} and \acro{PDF} + viewer; see figure~\ref{fig:psview}. + +\begin{figure}[tb] +\tlpng{psview}{.6\linewidth} +\caption{PS\_View: very high magnifications available!}\label{fig:psview} +\end{figure} + +\item[dviout.] Also installed is \prog{dviout}, a \acro{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 \acro{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{unzip} and the + utilities from the \cmdname{xpdf} suite (\cmdname{pdfinfo}, + \cmdname{pdffonts}, \ldots). The \cmdname{xpdf} viewer itself is not + available for Windows. Instead, you can download the Sumatra + \acro{PDF} viewer, which is based on \cmdname{xpdf}, from + \url{http://blog.kowalczyk.info/software/sumatrapdf}, among other options. + +\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 \acro{XP}, this +is usually \verb|C:\Documents and Settings\<username>|, and 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 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 environment is +modified. Otherwise, shortcuts and menu entries are created for the +current user, and the user environment 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 path +consists of the system path followed by the user path, the new \TL{} +would never get precedence. As a safeguard, 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. + +For Windows Vista and later, 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{http://www.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{http://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[-{}-verbose] print detailed progress report. +\item[-{}-version] print version information, then exit. +\end{ttdescription} + +For locating files the \Webc{} programs use the path searching library +\KPS{} (\url{http://tug.org/kpathsea}). This library uses a combination +of environment variables and a 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. + +If the database does not exist, or does not apply to this path +element, or contains no matches, the filesystem is searched (if this +was not forbidden by a specification starting with \samp{!!}\ and if +the file being searched for must exist). \KPS{} constructs the list +of directories that correspond to this path element, and then checks +in each for the file being sought. + +The ``file must exist'' condition comes into play with \samp{.vf} files and +input files read by \TeX's \cs{openin} command. Such files may not +exist (e.g., \file{cmr10.vf}), and so it would be wrong to search the +disk for them. Therefore, if you fail to update \file{ls-R} when you +install a new \samp{.vf} file, it will never be found. +Each path element is checked in turn: first the database, then the +disk. If a match is found, the search stops and the result is +returned. + +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 used to look +for these files is named \envname{TEXMFCNF}, but we do not recommend +setting this (or any) environment variable. + +Instead, normal installation results in a file +\file{.../2014/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{.../2014/texmf-dist/web2c/texmf.cnf}. +You should not edit this latter file, as your changes will be lost when +the distributed version is updated. + +\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{\%} 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: +\begin{alltt} + \var{variable}[.\var{progname}] [=] \var{value} +\end{alltt}% + where the \samp{=} and surrounding whitespace are optional. +\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 \var{value} may contain any characters except + \code{\%} and \samp{@}. The + \code{\$\var{var}.\var{prog}} feature is not available on the + right-hand side; instead, you must use an additional variable. A + \samp{;}\ in \var{value} is translated to \samp{:}\ if + running under Unix; this is useful to be able to have a single + \file{texmf.cnf} for Unix, \acro{MS-DOS} and Windows systems. +\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 complex 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}. +For example, in \file{texmf.cnf}, a definition like this +(simplified for this example) is made: +\begin{verbatim} + TEXMF = {$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFDIST} +\end{verbatim} +We can 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 \emph{only}) will be searched (the +last two using \file{ls-R} data base files). It is a convenient +way for running two parallel \TeX{} structures, one ``frozen'' (on a +\CD, for instance) and the other being continuously updated with new +versions as they become available. By using the \code{\$TEXMF} +variable in all definitions, one is sure to always search the +up-to-date tree first. + +\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{List of special characters and their meaning: a summary} + +The following list summarizes the special characters 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 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{//}] Subdirectory expansion (can occur anywhere in + a path, except at its beginning). +\item[\CODE{\%}] Start of comment. +\item[\CODE{\bs}] Continuation character (allows multi-line entries). +\item[\CODE{!!}] Search \emph{only} database to locate file, \emph{do + not} search the disk. +\end{ttdescription} + + +\subsection{Filename databases} +\label{sec:filename-database} + +\KPS{} goes to some lengths to minimize disk accesses for searches. +Nevertheless, at installations with enough directories, searching each +possible directory for a given file can take an excessively long time +(this is especially true if many hundreds of font directories have to +be traversed.) 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}. This can be helpful to +confirm to \acro{DOS} 8.3 filename conventions in source files. + +\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} 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 \acro{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} + +\bigskip + +\input{examples/ex6b.tex} +\caption{Finding the prolog file}\label{fig:dvipsdbgb} + +\bigskip + +\input{examples/ex6c.tex} +\caption{Finding the font file}\label{fig:dvipsdbgc} +\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 \acro{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 \acro{TFM} files read. +\item[\texttt{hash\_extra}] + Additional space for the hash table of control sequence names. + Only $\approx$10,000 control sequences can be stored in the main + hash table; if you have a large book with numerous cross-references, + this might not be enough. The default value of + \texttt{hash\_extra} is \texttt{50000}. +\end{ttdescription} + +\noindent Of course, 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. + + +\begin{comment} +\section{Building on a new Unix platform} + +If you have a platform for which executables are not included, you will +need to compile \TeX{} and friends. This is not as hard as it +sounds. What you need is all in the directory \texttt{source} in the +distribution. + +\subsection{Prerequisites} + +You will need at least 100 megabytes of disk space to compile all of +\TeX{} and its support programs. You'll also need an \acro{ANSI} C +compiler, a \cmdname{make} utility, a lexical scanner, and a parser +generator. We recommend the \GNU version of these programs +(\cmdname{gcc}, \GNU \cmdname{make}, \cmdname{m4}, \cmdname{flex}, +\cmdname{bison}). You may be able to work with other C compilers and +\cmdname{make} programs, but you will need a good understanding of +building Unix programs to sort out problems. + +Also, the command \texttt{uname} must return a sensible value. + + +\subsection{Configuration} + +To begin, perform a normal installation of \TL{} to your disk (see +section~\ref{sec:install-disk} on +\p.\pageref{sec:install-disk}). You may wish to skip installing +all of the prebuilt binaries. + +Then, unpack the source from the compressed \texttt{tar} file in the +directory \dirname{source} to your disk and change directory to where +you placed it. + +Next, run \cmdname{configure} with a command line like this: +\begin{alltt} +> \Ucom{sh configure -prefix=/usr/local/TeX} +\end{alltt} + +The \optname{-prefix} directory is the one where you installed the +support tree; the directory layout will be as follows (where \$TEXDIR +stands for the directory you chose): + +\noindent +\begin{tabular}{>{\ttfamily}ll@{}} + \dirname{$TEXDIR/share/texmf} & main tree with fonts,\\ + & \qquad macros, etc\\ + \dirname{$TEXDIR/man} & Unix manual pages\\ + \dirname{$TEXDIR/info} & \GNU style Info manuals\\ + \dirname{$TEXDIR/bin/$PLATFORM} & binaries\\ +\end{tabular} +%$ + +If you want to leave out the \dirname{$PLATFORM} directory level, +i.e., put the binaries directly into \dirname{$TEXDIR/bin}, specify +the \verb|--disable-multiplatform| option to \cmdname{configure}. + +Have a look at the output of \verb|./configure --help| for more +options you can use. For example, you can skip building of \OMEGA{} and +\eTeX{}. + + +\subsection{Running \cmdname{make}} + +Make sure the shell variable or option \texttt{noclobber} is not set. +Then, run the main \cmdname{make} like this: +\begin{alltt} +> \Ucom{make world} +\end{alltt} +and relax\ldots + +Alternatively, you want to log all the output, as in: +\begin{alltt} +> \Ucom{sh -c "make world >world.log 2>\&1" \&} +\end{alltt} + +Before you believe that everything went ok, please check the log file +for errors: \GNU \cmdname{make} always uses the string \samp{***} +whenever a command fails. Also, check if all the programs were built: + +\begin{alltt} +> \Ucom{cd \var{TEXDIR}/bin/\var{archname}} +> \Ucom{ls | wc} +\end{alltt} +The result should be over 200 (you can check the exact number with the +\dirname{bin} directory contents in the distribution). + +If you need special privileges for \texttt{make install}, you can +separate the \samp{make world} into two different runs, like this: +\begin{alltt} +> \Ucom{make all} +> \Ucom{su} +> \Ucom{make install strip} +\end{alltt} + +After you've installed your new binaries, you should follow the normal +post-installation procedures, given in section~\ref{sec:postinstall} +(\p.\pageref{sec:postinstall}). + +Also, if you'd like to make your binaries available to others, please +contact us. We'll be happy to put them on the \TL\ web pages. +\end{comment} + +\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 +(\acro{TUG}, \acro{DANTE} e.V., \acro{NTG}, and \acro{GUST}, +respectively), which provide the necessary technical and administrative +infrastructure. Please join the \TeX\ user group near you! (See +\url{http://tug.org/usergroups.html}.) + +\item The \acro{CTAN} team, notably Robin Fairbairns and Rainer +Sch\"opf, 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. + +\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 stellar help with \GNU\ +autotools usage throughout \TL. + +\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\ format +(\url{http://pragma-ade.com}) work within \TL's framework. + +\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 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 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 \acro{W32TEX} distribution 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 Dick Koch, for maintaining Mac\TeX\ (\url{http://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 Mojca Miklavec, for much help with \ConTeXt. + +\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 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 \TL{} 2008 +infrastructure and installer, and also for coordinating the Debian +version of \TL{} (together with Frank K\"uster), making many suggestions +along the way. + +\item Sebastian Rahtz, for originally creating \TL{} and maintaining it +for many years. + +\item Phil Taylor, for setting up the BitTorrent downloads. + +\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, the principal tester for all of \TL{}, +and coordinator of the many major Polish contributions: fonts, Windows +installation, and more. + +\item Olaf Weber, for his patient maintenance of \Webc. + +\item Gerben Wierda, for creating and maintaining the original \MacOSX\ +support. + +\item Graham Williams, the originator of the \TeX\ Catalogue. + +\end{itemize*} + +Builders of the binaries: +Ettore Aldrovandi (\pkgname{i386-solaris}, \pkgname{x86\_64-solaris}), +Marc Baudoin (\pkgname{amd64-netbsd}, \pkgname{i386-netbsd}), +Karl Berry (\pkgname{i386-linux}), +Alan Braslau (\pkgname{amd64-kfreebsd}, \pkgname{i386-kfreebsd}), +Peter Breitenlohner (\pkgname{x86\_64-linux}), +Ken Brown (\pkgname{i386-cygwin}, \pkgname{x86\_64-cygwin}), +Simon Dales (\pkgname{armhf-linux}), +%Christian Mensing (\pkgname{mips-irix}), +Akira Kakuto (\pkgname{win32}), +Dick Koch (\pkgname{universal-darwin}, \pkgname{x86\_64-darwin}), +Nikola Le\v{c}i\'c (\pkgname{amd64-freebsd}, \pkgname{i386-freebsd}), +Mojca Miklavec (\pkgname{mipsel-linux}), \pkgname{sparc-solaris}), +Norbert Preining (\pkgname{alpha-linux}), +Thomas Schmitz (\pkgname{powerpc-linux}), +Boris Veytsman (\pkgname{armel-linux}). +For information on the \TL{} build process, see +\url{http://tug.org/texlive/build.html}. + +Translators of this manual: +Boris Veytsman (Russian), +Jjgod Jiang, Jinsong Zhao, Yue Wang, \& Helin Gai (Chinese), +Uwe Ziegenhagen (German), +Manuel P\'egouri\'e-Gonnard (French), +Marco Pallante (Italian), +Nikola Le\v{c}i\'c (Serbian), +Petr Sojka \& Jan Busa (Czech\slash Slovak), +Staszek Wawrykiewicz (Polish). The \TL{} documentation web page +is \url{http://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 \acro{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 \acro{TUG} +Technical Council working group on a \emph{\TeX{} Directory Structure} +(\url{http://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. + +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{http://www.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 \acro{OSF} was removed + (\acro{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{http://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 \acro{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 \acro{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 +\acro{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 \acro{UTF}-8). See +\OnCD{texmf-dist/doc/generic/enctex/} and +\url{http://www.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{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=aleph}. The +\LaTeX-based format for Aleph is named \textsf{lamed}. + +\item The latest \LaTeX\ release has a new version of the +\acro{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 \acro{DVI} to +\acro{PNG} image files, is included. See +\url{http://www.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 \acro{CTAN} +(\url{http://mirror.ctan.org/tex-archive/fonts/greek/cbfonts}). + +\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 \acro{BSD} Ports system is available, and +\acro{GNU/}Linux and Free\acro{BSD} 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 \acro{MIPS}pro 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{http://scripts.sil.org/xetex}. + +MetaPost also received a notable update, with more planned for the +future (\url{http://tug.org/metapost/articles}), likewise pdf\TeX{} +(\url{http://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 \acro{CTAN} +(\url{http://mirror.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{http://tug.org/tetex}). As a result, there was +been 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{http://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{http://tug.org/TUGboat/Articles/tb29-2/tb92hagen-euler.pdf}). In +all cases, the metrics remain unchanged. The AMS fonts home page is +\url{http://www.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{http://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{http://asymptote.sourceforge.net}. + +The separate \code{dvipdfm} program has been replaced by +\code{dvipdfmx}, which operates in a special compatibility mode under +that name. \code{dvipdfmx} includes \acro{CJK} support and has +accumulated many other fixes over the years since the last +\code{dvipdfm} release. The DVIPDFMx home page is +\url{http://project.ktug.or.kr/dvipdfmx}. + +Executables for the \pkgname{cygwin} and \pkgname{i386-netbsd} platforms +are now included, while we were advised that Open\acro{BSD} 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{http://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{http://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 +are 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 packages 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 +(\url{http://baruch.ev-en.org/proj/chktex}) for checking \AllTeX\ +documents; the \prog{dvisvgm} (\url{http://dvisvgm.sourceforge.net}) +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{http://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 2gb. + +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 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{http://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. + + +\htmlanchor{news} +\subsection{Present---2014} +\label{sec:tlcurrent} + +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 \acro{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} (\url{http://foundry.supelec.fr/projects/luajittex}) +and its siblings \code{texluajit} and \code{texluajitc}. This uses a +just-in-time Lua compiler (detailed \textsl{TUGboat} article at +\url{http://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 +\acro{SVG} and \acro{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. + +Support for some additional platforms is available as custom binaries +(\url{http://tug.org/texlive/custom-bin.html}). In addition, some +platforms are omitted from the \DVD\ (simply to save space), but can be +installed normally over the net. + + +\subsection{Future} + +\emph{\TL{} is not perfect!} (And never will be.) We intend to +continue to release new versions, and would like to provide more help +material, more utilities, more installation programs, and (of course) an +ever-improved and better-checked tree of macros and fonts. This work is +all done by volunteers in their spare time, and so there is always more +to do. Please see \url{http://tug.org/texlive/contribute.html}. + +Please send corrections, suggestions, and offers of help to: +\begin{quote} +\email{tex-live@tug.org} \\ +\url{http://tug.org/texlive} +\end{quote} + +\medskip +\noindent \textsl{Happy \TeX ing!} + +\end{document} |