summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2009.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/texlive/texlive-en/archive/live-2009.tex')
-rw-r--r--Master/texmf-dist/doc/texlive/texlive-en/archive/live-2009.tex3130
1 files changed, 3130 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2009.tex b/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2009.tex
new file mode 100644
index 00000000000..022bae432e3
--- /dev/null
+++ b/Master/texmf-dist/doc/texlive/texlive-en/archive/live-2009.tex
@@ -0,0 +1,3130 @@
+% $Id: texlive-en.tex 15931 2009-11-03 00:48:56Z 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}\\\smallskip}%
+ {\LARGE \textsf{\TL{} 2009}}%
+}
+
+\author{Karl Berry, editor \\[3mm]
+ \url{http://tug.org/texlive/}
+ }
+
+\date{November 2009}
+
+\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}).
+
+\subsection{Operating system support}
+\label{sec:os-support}
+
+\TL{} contains binaries for many Unix-based architectures, including
+\GNU/Linux and \MacOSX. There are also Cygwin binaries. The
+included sources can be compiled on platforms for which we do not
+have binaries.
+
+As to Windows: only Windows 2000 and later are
+supported. Windows~9\textit{x}, \acro{ME} and \acro{NT} have been
+dropped. Because of this change, Windows requires much less special
+treatment compared to the Unix systems. 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. The net
+installer itself is small, and downloads everything requested from the
+Internet.
+
+The \DVD{} installer lets you install to a local disk, but you can also
+run \TL{} directly from the \DVD{} (or from a \DVD{} image, if your
+system supports that). Installation is described in later sections, 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/html/index.html}, 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://www.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] The two principal support forums are the
+Usenet newsgroup \url{news:comp.text.tex} and the mailing list
+\email{texhax@tug.org}. Their archives have years of past
+questions and answers for your searching pleasure, via
+\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}.
+
+\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 which can be run live or
+ installed to disk. Its home page is \url{http://tug.org/texlive/}.
+
+\item [Mac\TeX] for \MacOSX, this adds a native \MacOSX\ installer and other
+Mac applications to \TL{}. Its home page is
+\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. The \ProTeXt\ home page is
+\url{http://tug.org/protext}.
+
+\item [CTAN] A snapshot of the \CTAN{} repository (\url{http://www.ctan.org}).
+
+\item [\texttt{texmf-extra}] A directory with assorted additional packages.
+
+\end{description}
+
+\CTAN{}, \pkgname{protext}, and \dirname{texmf-extra} do not
+necessarily 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 the
+\TL{} distribution. On the \TK{} \DVD, the entire \TL{} hierarchy is in
+a subdirectory \dirname{texlive}, not at the top level of the disc.
+
+\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{}
+ \TeX{} and \MF{} distributions.
+%
+\item[texmf] See \dirname{TEXMFMAIN} below.
+%
+\item[texmf-dist] See \dirname{TEXMFDIST} below.
+%
+\item[tlpkg] Scripts, programs and data for managing the
+ installation, and some 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 the programs
+(manuals, man pages, Info files) is in \dirname{texmf/doc}. The
+documentation for \TeX\ packages and formats is in
+\dirname{texmf-dist/doc}. You can use the \cmdname{texdoc} program to
+find any documentation wherever it is located.
+
+This \TL\ documentation itself is in \dirname{texmf/doc/texlive},
+available in several languages:
+
+\begin{itemize*}
+\item{Simplified Chinese:} \OnCD{texmf/doc/texlive/texlive-zh-cn}
+\item{Czech/Slovak:} \OnCD{texmf/doc/texlive/texlive-cz}
+\item{English:} \OnCD{texmf/doc/texlive/texlive-en}
+\item{French:} \OnCD{texmf/doc/texlive/texlive-fr}
+\item{German:} \OnCD{texmf/doc/texlive/texlive-de}
+\item{Polish:} \OnCD{texmf/doc/texlive/texlive-pl}
+\item{Russian:} \OnCD{texmf/doc/texlive/texlive-ru}
+\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.
+
+\begin{ttdescription}
+\item [TEXMFMAIN] The tree which holds vital parts of the
+ system such as configuration files, helper scripts, and program
+ documentation.
+\item [TEXMFDIST] The tree which holds the main set of macro packages,
+ fonts, etc.
+\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 tree used by the utilities
+ \verb+texconfig+, \verb+updmap+, and \verb+fmtutil+ to store modified
+ configuration data. Under \envname{TEXMFHOME} by default.
+\item [TEXMFSYSCONFIG] The tree used by the utilities
+ \verb+texconfig-sys+, \verb+updmap-sys+, and \verb+fmtutil-sys+ to
+ store modified configuration data.
+\item [TEXMFVAR] The tree used by \verb+texconfig+, \verb+updmap+ and
+ \verb+fmtutil+ to store (cached) runtime data such as format files and
+ generated map files. Under \envname{TEXMFHOME} by default.
+\item [TEXMFSYSVAR] The 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.
+\end{ttdescription}
+
+\noindent
+The default layout is:
+\begin{description}
+ \item[system-wide root] can span multiple \TL{} releases:
+ \begin{ttdescription}
+ \item[2008] A previous release.
+ \item[2009] 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\ \ \ \ \ \ \ ] This is \envname{TEXMFMAIN}.
+ \item [texmf-dist\ \ ] \envname{TEXMFDIST}
+ \item [texmf-var \ \ ] \envname{TEXMFSYSVAR}
+ \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] (\texttt{\$HOME} or
+ \texttt{\%USERPROFILE\%})
+ \begin{ttdescription}
+ \item[.texlive2008] Privately generated and configuration data
+ for a previous release.
+ \item[.texlive2009] Privately generated and configuration data
+ for the current release.
+ \begin{ttdescription}
+ \item [texmf-var\ \ \ ] \envname{TEXMFVAR}
+ \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 still present in \TL\ as the program \prog{tex}, and will remain so
+for the foreseeable future. \TL{} contains several extended versions of
+\TeX:
+
+\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/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} for some minimal documentation.
+
+\end{description}
+
+
+\subsection{Other notable programs in \protect\TL}
+
+Here are a few other commonly-used programs included in \TL{}:
+
+\begin{cmddescription}
+
+\item [bibtex] 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). See the \pkgname{ps4pdf} and
+\pkgname{pdftricks} packages for still more alternatives.
+
+\item [psselect, psnup, \ldots] \PS{} utilities.
+
+\item [texexec, texmfstart] Con\TeX{}t and \acro{PDF} processor.
+
+\item [tex4ht] \TeX{} to \acro{HTML} (and \acro{XML} and more) converter.
+
+\end{cmddescription}
+
+
+\subsection{Fonts in \protect\TL}
+\label{sec:tl-fonts}
+
+\TL{} comes with many high-quality scalable fonts. See
+\url{http://tug.org/fonts} and
+\OnCD{texmf-dist/doc/fonts/free-math-font-survey}.
+
+
+\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,
+and locate the installer script: \filename{install-tl} for Unix,
+\filename{install-tl.bat} for Windows.
+
+\begin{description}
+\item [Net installer:] 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.bat} will be in the \dirname{install-tl}
+subdirectory.
+
+\item [\TeX{} Collection \DVD:] go to its \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.
+
+\end{description}
+
+See \url{http://tug.org/texlive/acquire.html} for more information and
+other methods of getting the software.
+
+The following sections explain installer start-up in more detail.
+
+\subsubsection{Unix}
+
+\noindent
+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{cd /path/to/installer}
+> \Ucom{perl install-tl}
+\end{alltt}
+(Or you can invoke \Ucom{perl /path/to/installer/install-tl}, or
+\Ucom{./install-tl} if it stayed executable, etc.; we won't repeat all
+these 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), use:
+\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} for details.
+
+
+\subsubsection{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, gw\TeX,
+Fink, MacPorts, \ldots).
+
+Mac\TeX\ is firmly based on \TL, and the main \TeX\ trees are precisely
+the same. It does add a few extra folders with Mac-specific
+documentation and applications.
+
+
+\subsubsection{Windows}
+
+If you are using the net installer, or the \DVD\ installer failed to
+start automatically, double-click \filename{install-tl.bat}.
+For 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}
+\end{alltt}
+
+Or you can invoke it with an absolute location, such as:
+\begin{alltt}
+> \Ucom{D:\bs{}texlive\bs{}install-tl}
+\end{alltt}
+for the \TK\ \DVD, supposing that \dirname{D:} is the optical
+drive. Figure~\ref{fig:wizard} displays the wizard installer, which
+is the default for Windows.
+
+To install in text mode, use:
+\begin{alltt}
+> \Ucom{install-tl -no-gui}
+\end{alltt}
+
+For a complete listing of the various options:
+\begin{alltt}
+> \Ucom{install-tl -help}
+\end{alltt}
+
+\begin{figure}[tb]
+\begin{boxedverbatim}
+Installing TeX Live 2009 from: ...
+Platform: i386-linux => 'Intel x86 with GNU/Linux'
+Distribution: live (uncompressed)
+...
+ Detected platform: Intel x86 with GNU/Linux
+
+ <B> binary systems: 1 out of 14
+
+ <S> Installation scheme (scheme-full)
+ 83 collections out of 84, disk space required: 1882 MB
+
+ Customizing installation scheme:
+ <C> standard collections
+ <L> language collections
+
+ <D> directories:
+ TEXDIR (the main TeX directory):
+ /usr/local/texlive/2009
+ TEXMFLOCAL (directory for site-wide local files):
+ /usr/local/texlive/texmf-local
+ TEXMFSYSVAR (directory for variable and automatically generated data):
+ /usr/local/texlive/2009/texmf-var
+ TEXMFSYSCONFIG (directory for local config):
+ /usr/local/texlive/2009/texmf-config
+ TEXMFHOME (directory for user-specific files):
+ ~/texmf
+
+ <O> options:
+ [ ] use letter size instead of A4 by default
+ [X] create all format files
+ [X] install macro/font doc tree
+ [X] install macro/font source tree
+ [ ] create symlinks to standard directories
+
+ <V> set up for running from DVD
+
+Other 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}
+\end{figure}
+
+
+\htmlanchor{cygwin}
+\subsubsection{Cygwin}
+\label{sec:cygwin}
+
+The \TL{} installer supports only Cygwin 1.7.
+% Add a note about Angelo's workaround for 1.5 if he gets it ready for
+% public use.
+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]
+\item \filename{ghostscript} [needed by various utilities]
+\item \filename{libXaw7} [needed by xdvi]
+\item \filename{ncurses} [provides the '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 installer does
+not differ much from the text one (Figure~\ref{fig:text-main}).
+
+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, which we named the ``wizard'' installer. It installs
+everything and asks almost no questions. If you want to customize your
+setup, you should run one of the other installers.
+
+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}[tbh]
+\begin{boxedverbatim}
+Available sets of binaries:
+===============================================================================
+
+ a [ ] alpha-linux DEC Alpha with GNU/Linux
+ b [ ] i386-cygwin Intel x86 with Cygwin
+ c [X] i386-linux Intel x86 with GNU/Linux
+ d [ ] i386-netbsd Intel x86 with NetBSD
+ e [ ] i386-solaris Intel x86 with Sun Solaris
+ f [ ] mips-irix SGI IRIX
+ g [ ] powerpc-aix PowerPC with AIX
+ h [ ] powerpc-linux PowerPC with GNU/Linux
+ i [ ] sparc-linux Sparc with GNU/Linux
+ j [ ] sparc-solaris Sparc with Solaris
+ k [ ] universal-darwin universal binaries for MacOSX/Darwin
+ l [ ] win32 Windows
+ m [ ] x86_64-linux x86_64 with GNU/Linux
+\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
+architectures as well. This can be useful if you are sharing a \TeX\
+tree across a network of heterogenous machines, or for a dual-boot
+system.
+
+\subsubsection{Selecting what is going to be installed}
+\label{sec:components}
+
+\begin{figure}[tbh]
+\begin{boxedverbatim}
+Select a scheme:
+===============================================================================
+ a [ ] basic scheme (plain and LaTeX)
+ b [ ] ConTeXt scheme
+ c [X] full scheme (everything)
+ d [ ] GUST TeX Live scheme
+ e [ ] GUTenberg TeX Live scheme
+ f [ ] medium scheme (plain, latex, recommended packages, some languages)
+ g [ ] minimal scheme (plain only)
+ h [ ] Omega scheme
+ i [ ] teTeX scheme (more than medium, but nowhere near full)
+ j [ ] XML scheme
+ k [ ] 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, 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}[tbh]
+\tlpng{stdcoll}{.7\linewidth}
+\caption{Collections menu}\label{fig:collections-gui}
+\end{figure}
+
+You can refine your scheme selection with the `standard collections' and
+`language collections' menus (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 \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 location of
+\dirname{TEXDIR} is different between Windows
+(|%SystemDrive%\texlive\2009|) and Unix
+(\dirname{/usr/local/texlive/2009}).
+
+The main reason to change this default is if you lack 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.
+
+A reasonable alternative choice is a directory under your home directory,
+especially if you will be the sole user. Use
+`|~|' to indicate this, as in `|~/texlive/2009|'.
+
+We recommend including the year in the name, to enable keeping different
+releases of \TL{} side by side. (You may wish to make a
+version-independent name such as \dirname{/usr/local/texlive-cur} via a
+symbolic link, which you can then update 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 any individual running \TeX. It expands to
+\dirname{$HOME} on Unix and \verb|%USERPROFILE%| on Windows.
+
+\subsubsection{Options}
+\label{sec:options}
+
+\begin{figure}[tbh]
+\begin{boxedverbatim}
+ <P> use letter size instead of A4 by default: [ ]
+ <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:
+\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:
+
+\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[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 could end up with incompatible format files.
+
+\begin{comment}
+\item[execution of restricted list of programs:] As of \TL\ 2009,
+ execution of a few external programs is allowed by default. The list
+ of allowed programs is given in the \filename{texmf.cnf}; it is very
+ small, but still very useful. See the 2009 news
+ (section~\ref{sec:2009news}) for more details.
+\end{comment}
+
+\item[install font/macro \ldots\ tree:] These options allow you to omit
+ downloading/installing the documentation and source files present in
+ most packages. Not recommended.
+
+\item[create symlinks in standard directories] (Unix only):
+ This option 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.
+\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.
+
+\htmlanchor{runfromdvd}
+\subsubsection{Set up for running from DVD{} (text mode only)}
+\label{sec:fromdvd}
+
+Type `|V|' to select this option. This changes the main menu into something
+as in figure~\ref{fig:main-fromdvd}.
+
+\begin{figure}[tbh]
+\begin{boxedverbatim}
+======================> TeX Live installation procedure <=====================
+...
+ <D> directories:
+ TEXDIRW (Writable root):
+ !! default location: /usr/local/texlive/2009
+ !! is not writable, please select a different one!
+ TEXMFLOCAL (directory for site-wide local files):
+ /usr/local/texlive/texmf-local
+ TEXMFSYSVAR (directory for variable and automatically generated data):
+ /usr/local/texlive/2009/texmf-var
+ TEXMFSYSCONFIG (directory for local config):
+ /usr/local/texlive/2009/texmf-config
+ TEXMFHOME (directory for user-specific files):
+ ~/texmf
+
+ <O> options:
+ [ ] use letter size instead of A4 by default
+ [X] create all format files
+
+ <V> set up for installing to hard disk
+
+Other actions:
+ <I> start installation for running from DVD
+ <H> help
+ <Q> quit
+\end{boxedverbatim}
+\caption{The main menu with `\optname{from DVD}' set}\label{fig:main-fromdvd}
+\end{figure}
+
+Note the changes: all options about what to install have
+disappeared, and the directories section now talks about
+\dirname{TEXDIRW} or writable root. The symlinks option has also
+disappeared.
+
+The installer will still create various directories and configuration
+files, but won't copy \dirname{texmf} or \dirname{texmf-dist} to hard
+disk.
+
+Post-install configuration for Unix will be slightly more complicated,
+because now the directory layout deviates from the default; see
+section~\ref{sec:postinstall}.
+
+This option is not in the \GUI{} installer, but it is available both
+for Unix and for Windows. Windows users have to start the installer
+from a command prompt, see section~\ref{sec:cmdline}.
+
+Section \ref{sec:portable-tl} describes a more strictly portable
+way to run \TL, which doesn't make or require any changes in the
+system's configuration, but doesn't allow any configuration either.
+
+\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});
+ if Perl/Tk is not available, installation continues in text mode.
+
+\item[-no-gui] Force using the text mode installer, even under
+ Windows; you'll need this if you want a `from \DVD' installation,
+ since that is not available in \GUI{} mode.
+
+\item[-lang {\sl LL}] Specify the installer interface
+ language as its standard two-letter code \textsl{LL}. Currently
+ supported languages: English (\texttt{en}, default), German
+ (\texttt{de}), French (\texttt{fr}), Dutch (\texttt{nl}), Polish
+ (\texttt{pl}), Slovenian (\texttt{sl}) and Vietnamese
+ (\texttt{vi}). The installer tries to determine the right language
+ itself but if it fails, or if the right language is not available,
+ then it uses English as a fallback.
+
+\item[-profile {\sl file}] The installer always writes a file
+ \filename{texlive.profile} to the \dirname{tlpkg} subdirectory of your
+ installation. This option tells the installer to re-use such a
+ profile file, so you can install in batch mode on subsequent systems,
+ reproducing the choices you made in a prior installation.
+
+\item [-repository {\sl url-or-directory}] Specify package
+ repository from which to install; see following.
+\end{ttdescription}
+
+\subsubsection{The \optname{-repository} option}
+\label{sec:location}
+
+The default 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|. 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-install may be required.
+
+\subsubsection{Windows}
+
+But on Windows, the installer takes care of everything.
+
+\subsubsection{If symlinks were created}
+
+If you elected to create symlinks in standard directories (mentioned in
+section~\ref{sec:options}), then there is no need to edit environment
+variables.
+
+\subsubsection{Environment variables for Unix}
+\label{sec:env}
+
+The directory of the binaries for your platform must be added to
+the search path. 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.
+
+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/2009/bin/i386-linux:$PATH; export PATH
+MANPATH=/usr/local/texlive/2009/texmf/doc/man:$MANPATH; export MANPATH
+INFOPATH=/usr/local/texlive/2009/texmf/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/2009/bin/i386-linux:$PATH
+setenv MANPATH /usr/local/texlive/2009/texmf/doc/man:$MANPATH
+setenv INFOPATH /usr/local/texlive/2009/texmf/doc/info:$INFOPATH
+\end{sverbatim}
+
+If you already have settings somewhere in your ``dot'' files, naturally
+the \TL\ directories should simply 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/2009/bin/i386-linux \
+ /usr/local/texlive/2009/texmf/doc/man
+\end{sverbatim}
+
+And 2)~check for a file \filename{/etc/environment} which may define the
+search path and other default environment variables.
+
+We also create a symbolic link named \code{man} in each (Unix) binary
+directory. Some \code{man} programs, such as the standard \MacOSX\
+\code{man}, will automatically find that, obviating the need for any man
+page setup.
+
+
+\subsubsection{Font configuration for \XeTeX}
+\label{sec:font-conf-xetex}
+
+If you have installed the \filename{xetex} package on a Unix-compatible
+system, you need to configure your system if you want \XeTeX\ to be able
+to find the fonts shipped with \TL. 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,
+you can instead do the following to make the \TL{} fonts available
+to you as an individual \XeTeX{} user:
+\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*}
+
+
+\subsubsection{When running from DVD}
+
+Normally, a \TL{} program consults a file \filename{texmf.cnf} for the
+location of the various trees. It looks for this file in a series of
+locations relative to its own location. However, this scheme breaks down
+when a program is run from \DVD{}: the \DVD{} is read-only. Some of the
+paths to be recorded in \filename{texmf.cnf} are only known at
+installation time, so this file cannot be on the \DVD{} and must be
+placed somewhere else. This makes it necessary to define an environment
+\envname{TEXMFCNF} variable which tells \TL{} programs in what directory
+to find this \filename{texmf.cnf}. It is also still necessary to modify
+the \envname{PATH} environment variable, as described before.
+
+At the end of the installation, the installer should have printed a
+message giving the value to which \envname{TEXMFCNF} should be set. In
+case you missed it: this value is \dirname{$TEXMFSYSVAR/web2c}. For the
+default, \dirname{/usr/local/texlive/2009/texmf-var/web2c}, you need the
+lines
+\begin{sverbatim}
+TEXMFCNF=/usr/local/texlive/2009/texmf-var/web2c; export TEXMFCNF
+\end{sverbatim}
+or, for [t]csh:
+\begin{sverbatim}
+setenv TEXMFCNF /usr/local/texlive/2009/texmf-var/web2c
+\end{sverbatim}
+
+This option is most useful when you want to run \TL{} on your own
+system, but don't have enough disk space to install it. If you want a
+truly `portable' \TL{} that is self-contained, e.g., for a USB stick,
+see section~\ref{sec:portable-tl}.
+
+\subsubsection{\ConTeXt{} Mark IV}
+
+The `old' \ConTeXt{} should run out of the box. The new `Mark IV'
+\ConTeXt{} will require manual setup; 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|)
+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 subdirectories;
+see \url{http://tug.org/tds} or consult
+\filename{texmf/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 \prog{tlmgr} in \GUI\ mode.
+
+\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. Don't forget to
+check first what you get for free: see section~\ref{sec:tl-fonts}.
+
+A possible alternative is to use \XeTeX (see
+section~\ref{sec:tex-extensions}), which lets 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{} as best you can, you naturally want to test
+it out, so you can start creating beautiful documents and\slash or fonts.
+
+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.1415926 (TeX Live 2009)
+kpathsea version 5.0.0
+Copyright 2009 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, Version 3.1415926-1.40.10 (TeX Live 2009)
+...
+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.1415926\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
+\XeTeX{} can find the fonts shipped with \TL. See
+Section~\ref{sec:font-conf-xetex}.
+
+\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 (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 in
+ the directory \path{tlpkg/support} on the \TL \DVD; its home
+ page is \url{http://www.gnu.org/software/auctex}.
+ \item \cmdname{LEd} is available from \url{http://www.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{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{WinShell} is available from \url{http://www.winshell.de}.
+ \item \cmdname{WinEdt} is shareware available though
+ \url{http://tug.org/winedt} or \url{http://www.winedt.com}.
+ \end{itemize*}
+\end{description}
+For a much longer list of packages and programs, see
+\url{http://tug.org/interest.html}.
+
+
+\section{Network installations}
+\label{sec:netinstall}
+
+\TL{} has been designed to be shared between different users, and even
+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{$TEXMFMAIN/web2c/texmf.cnf},
+which contains lines such as
+\begin{sverbatim}
+TEXMFMAIN = $SELFAUTOPARENT/texmf
+...
+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.
+
+
+\section{Maximally portable \protect\TL{} on DVD and USB}
+\label{sec:portable-tl}
+
+The `running from \DVD{}' option described in
+section~\ref{sec:fromdvd} is fine for your own system, but if you
+are a guest on somebody else's system then you would probably like
+something with minimal side effects.
+
+In the root of the \TL{} \DVD, or the \dirname{texlive} subdirectory of
+the \TK{} \DVD, are a \filename{tl-portable} script (Unix) and a
+\filename{tl-portable.bat} batch file (Windows) which start up a
+secondary shell\slash command prompt with environment settings
+for directly accessing the \TL{} on the \DVD.
+
+When it runs for the first time, some files will be generated in a
+directory \dirname{~/.tlportable2009}, which will take a little time.
+On subsequent runs, though, it will start almost instantaneously.
+
+The rest of the system will be unaware of \TL. If you want your editor
+to be aware of this \TL, then you can start it from a second, parallel,
+such \filename{tl-portable} session.
+
+You can also use \filename{tl-portable} to run \TL{} on a
+\acro{USB} stick. In this case, copy all the top-level files and
+the contents of the \dirname{bin}, \dirname{texmf},
+\dirname{texmf-dist}, and \dirname{tlpkg} directories (at least) to
+the stick. This may take quite a while! If you are copying to a
+\acro{FAT}32-formatted \acro{USB} stick, make sure to dereference
+symbolic links (\code{cp -L}). A \dirname{texmf-local} directory on
+the stick will also be found and used.
+
+Then run \filename{tl-portable} from the root of the stick, as above.
+In this case, the script will notice that the stick is writable and use
+it for generated files. You could burn the resulting contents of the
+stick back to \DVD{} if that is more convenient to (for example) give to
+others.
+
+
+\section{\cmdname{tlmgr}: Managing your installation}
+\label{sec:tlmgr}
+
+\begin{figure}[tb]
+\tlpng{tlmgr-gui}{\linewidth}
+\caption{\prog{tlmgr} in \GUI\ mode. The list of
+ packages/collections/schemes only shows up after clicking the
+ `Load' button.}\label{fig:tlmgr-gui}
+\end{figure}
+
+\begin{figure}[tb]
+\tlpng{tlmgr-config}{.8\linewidth}
+\caption{\texttt{tlmgr} in GUI mode: Configuration tab}\label{fig:tlmgr-config}
+\end{figure}
+
+\TL{} includes a program named \prog{tlmgr} for managing \TL{} after the
+initial installation. The programs \prog{updmap}, \prog{fmtutil} and
+\prog{texconfig} are still included and will be retained in the future,
+but \prog{tlmgr} is now the preferred interface. 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, etc.;
+\item listing, adding, and removing architectures;
+\item changing installation options such as paper size and source
+ location (see section~\ref{sec:location}).
+\end{itemize*}
+\textit{Warning:} \prog{tlmgr} has not been designed for or tested
+with installations which run from \DVD.
+
+\subsection{\cmdname{tlmgr} GUI mode}
+\prog{tlmgr} can be started in \GUI{} mode with
+\begin{alltt}
+> \Ucom{tlmgr -gui}
+\end{alltt}
+or in Windows via the Start menu: \texttt{Start}, \texttt{Programs},
+\texttt{TeX Live 2009}, \texttt{TeX Live Manager}. After clicking `Load'
+it displays a list of available and installed packages\Dash the latter
+prepended with `(i)'. This assumes of course that the installation
+source is valid and reachable.
+
+Figure~\ref{fig:tlmgr-config} shows the configuration tab.
+
+\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 Xe\TeX, 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/2009/texmf/ls-R...
+...
+running fmtutil-sys --missing
+...
+Transcript written on xelatex.log.
+fmtutil: /usr/local/texlive/2009/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
+\begin{fverbatim}
+package: collection-latexextra
+category: Collection
+shortdesc: LaTeX supplementary packages
+longdesc: A large collection of add-on packages for LaTeX.
+installed: Yes
+revision: 14675
+\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}
+
+\TL\ has a single installer which runs on both Windows and Unix. This
+was only possible by dropping support for older Windows versions, so
+\TL\ can now be installed only on Windows 2000 and later.
+
+
+\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. PS\_View also gets a
+ shortcut on the desktop as a drag-and-drop target for PostScript
+ files.
+\item[Automatic setting of environment variables.] No manual
+ configuration steps are required.
+\item[Uninstaller.] The installer creates an entry under `Add/Remove
+ Programs' for \TL. The uninstall tab of \prog{tlmgr} 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[TeXworks.] \TeX{}works is a \TeX-oriented editor with
+ an integrated \acro{PDF} viewer. It comes already preconfigured for \TL.
+
+\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
+ command-line utilities from the \cmdname{xpdf} suite. The
+ \cmdname{xpdf} viewer itself is not available for
+ Windows. Instead, you can download the Sumatra \acro{PDF} viewer,
+ which is based on xpdf, from
+ \url{http://blog.kowalczyk.info/software/sumatrapdf}.
+
+\item[fc-list, fc-cache et al.] 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 Xe\TeX'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} and Windows 2000, this
+is usually \verb|C:\Documents and Settings\<username>|, and under
+Windows Vista \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. In practice, though, you could better describe
+these classes of users as unprivileged users and normal users: being an
+administrator is the rule, not the exception. Nevertheless, we have made
+an effort to make \TL{} installable without administrative privileges.
+
+If the user is an administrator, 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 Vista there is another twist: 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'.
+
+\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}
+
+\begingroup\tolerance=3500
+\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} (by default such a file lives
+in the \file{texmf/web2c} subdirectory). \emph{All}
+\file{texmf.cnf} files in the search path will be read and definitions
+in earlier files override those in later files. Thus, with a search
+path of \verb|.:$TEXMF|, values from \file{./texmf.cnf} override those
+from \verb|$TEXMF/texmf.cnf|.
+\endgroup
+
+\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}
+
+\tolerance=2500
+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
+
+\tolerance=1500
+
+\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}
+
+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}, the following definition
+(approximately; there are actually even more trees) is made:
+\begin{verbatim}
+ TEXMF = {$TEXMFHOME,$TEXMFLOCAL,!!$TEXMFVAR,!!$TEXMFMAIN}
+\end{verbatim}
+Using this you can then write something like
+\begin{verbatim}
+ TEXINPUTS = .;$TEXMF/tex//
+\end{verbatim}
+%$
+which means that, after looking in the current directory, the
+\code{\$TEXMFHOME/tex}, \code{\$TEXMFLOCAL/tex}, \code{\$TEXMFVAR/tex}
+and \code{\$TEXMFMAIN/tex} trees \emph{only}) will be searched (the
+last two use 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 \cmdname{dvips} Reference
+Manual, \OnCD{texmf/doc/dvips/dvips.pdf}).
+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, Jim Hef{}feron,
+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 was used to create the \HTML{}
+version of this documentation, and who worked tirelessly to improve
+it at short notice. 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 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, and much integration and testing.
+
+\item Graham Williams, on whose work the \TeX\ Catalogue of packages depends.
+
+\end{itemize*}
+
+Builders of the binaries:
+Peter Breitenlohner (\pkgname{x86\_64-linux}),
+%Tim Arnold (\pkgname{hppa-hpux}),
+%Randy Au (\pkgname{amd64-freebsd}),
+%Edd Barrett (\pkgname{i386-openbsd}),
+Karl Berry (\pkgname{i386-linux}, \pkgname{sparc-linux}),
+Ken Brown (\pkgname{i386-cygwin}),
+Akira Kakuto (\pkgname{win32}),
+Dick Koch (\pkgname{universal-darwin}),
+%Manfred Lotz (\pkgname{i386-freebsd}),
+Norbert Preining (\pkgname{alpha-linux}),
+%Arthur Reutenauer (\pkgname{sparc-linux}),
+Jukka Salmi (\pkgname{i386-netbsd}),
+Thomas Schmitz (\pkgname{powerpc-linux}),
+Apostolos Syropoulos (\pkgname{i386-solaris}),
+Vladimir Volovich (\pkgname{powerpc-aix}, \pkgname{sparc-solaris}),
+Olaf Weber (\pkgname{mips-irix}).
+For information on the \TL{} build process, see
+\url{http://tug.org/texlive/build.html}.
+
+Current documentation translators:
+Jjgod Jiang, Jinsong Zhao, Yue Wang, \& Helin Gai (Chinese),
+Klaus H\"oppner (German),
+Manuel P\'egouri\'e-Gonnard (French),
+Petr Sojka \& Jan Busa (Czech\slash Slovak),
+Boris Veytsman (Russian),
+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/doc/web2c/web2c.html\#TCX-files}
+{\texttt{texmf/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/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 \OnCD{texmf/doc/man/man1/dvipng.1}.
+
+\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://www.ctan.org/tex-archive/fonts/greek/cb}).
+
+\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://www.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}.
+
+
+%
+\htmlanchor{news}
+\subsection{Present}
+\label{sec:tlcurrent}
+\label{sec:2009news} % keep with 2009
+
+\begin{comment} % last-minute disablement
+In 2009, the most visible change is that 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. For details, see the epstopdf package
+documentation (\url{http://ctan.org/pkg/epstopdf-pkg}).
+
+A related important change is that execution of a few external commands,
+via the \cs{write18} feature, is now enabled by default\Dash for
+example, \code{epstopdf}, \code{makeindex}, and \code{bibtex}. The
+exact list of commands is defined in the \code{texmf.cnf} file.
+Environments which must disallow all such external commands can deselect
+this option in the installer (see section~\ref{sec:options}), or
+override the value in \code{texmf.cnf} after installation.
+\end{comment}
+
+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 the other BSD distributions have been dropped;
+we were advised that OpenBSD and FreeBSD 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}.
+
+
+\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 hard-pressed volunteers in their limited spare time, and a
+great deal remains to be done. 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}