diff options
Diffstat (limited to 'Master/texmf/doc/texlive/texlive-en/archive/live-2007.tex')
-rw-r--r-- | Master/texmf/doc/texlive/texlive-en/archive/live-2007.tex | 3264 |
1 files changed, 0 insertions, 3264 deletions
diff --git a/Master/texmf/doc/texlive/texlive-en/archive/live-2007.tex b/Master/texmf/doc/texlive/texlive-en/archive/live-2007.tex deleted file mode 100644 index 8232db8becf..00000000000 --- a/Master/texmf/doc/texlive/texlive-en/archive/live-2007.tex +++ /dev/null @@ -1,3264 +0,0 @@ -% $Id: live.tex 3938 2007-02-06 01:49:45Z 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} -\begin{document} - -\title{% - {\huge \textit{The \protect\TL{} Guide}\\\strut} - {\LARGE \textsf{\TL{} 2007}} -} - -\author{Karl Berry, editor \\[3mm] - \url{http://tug.org/texlive/} - } - -\date{January 2007} - -\maketitle - -\begin{multicols}{2} -\tableofcontents -\listoftables -\end{multicols} - -\section{Introduction} -\label{sec:intro} - -This document describes the main features of the \TL{} software -distribution\Dash \TeX{} and friends for \acro{GNU}/Linux and other Unix -flavors, \MacOSX, and (32-bit) Windows systems. (Warning: it is not -especially useful for older Mac or \acro{MS-DOS} systems.) - -\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. It is part of the even larger \TK{} -(briefly described below in section~\ref{sec:struct-tl}, -\p.\pageref{sec:struct-tl}). Both are cooperative efforts by the \TeX\ -user groups. - -For newer versions of the packages included here, please check -\acro{CTAN}: \url{http://www.ctan.org}. - -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{Basic usage of \protect\TL{}} -\label{sec:basic} - -You can use \TL{} in three principal ways: - -\begin{enumerate} - -\item You can run \TL{} directly from the \pkgname{live} \DVD -(see section~\ref{sec:multiple-dist}, \p.\pageref{sec:multiple-dist}). -This takes almost no disk space, and gives you immediate access to -everything in \TL{}. Of course performance will be worse than running -on local disk, but you may well find it useful. - -\item You can install all or part of \TL{} to a local disk, from either -the \DVD\ or the \pkgname{inst} \acro{CD}. This is the most common use -of \TL. You will need (approximately) 100 megabytes for the most -minimal system, and upwards of 1.3 gigabytes for a full system. - -\item You can integrate a particular package or collection into your -existing \TeX{} system, either a \TL{} system you installed -earlier, or a different system. - -\end{enumerate} - -\noindent All of these are described in detail in the \acro{OS}-specific -installation sections following, but here is a quick start: - -\begin{itemize*} - -\item The main installation script for Unix and \MacOSX{} is -\texttt{install-tl.sh}. -GNU/Linux users can also try a new GUI installation program: -run \texttt{setuptl/tlpmgui}. More information -can be found in section \ref{sec:win-install} on -p.~\pageref{sec:win-install}. - -\item The single package installation script is \texttt{install-pkg.sh}. -(After installation on Linux with \texttt{tlpmgui}, you can also try -running \texttt{tlpmgui} again to add or remove individual packages or -collections.) - -\item The installation program for Windows is \texttt{tlpmgui.exe}. -It can be used also for adding or removing the packages. -See section~\ref{sec:win-install} below for more information. - -\end{itemize*} - - -\subsection{Getting help} -\label{sec:help} - -The \TeX{} community is both active and friendly, and virtually all -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 forego \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-doc/doc/english/FAQ-en}, and is -available on the Internet through \url{http://www.tex.ac.uk/faq}. -Please check here first. - -\item [\TeX{} Catalogue] If you are looking for a specific package, -font, program, etc., the \TeX{} Catalogue is the place to look. It is a -huge collection of all \TeX{}-related items. See -\OnCD{texmf-doc/doc/english/catalogue}, or -\url{http://www.ctan.org/tex-archive/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/groups?group=comp.text.tex} 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 on asking questions in such a -way that you're most likely to get an 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{}, you are better off writing to that program's maintainer or -mailing list. - -\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. Welcome to -\TeX{}! - - -% 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{Structure of \protect\TeX\protect\ Live} -\label{sec:struct-tl} - -This section describes the structure and contents of \TL{} and the -\TK{} of which it is a part. - -\subsection{Multiple distributions: \protect\pkgname{live}, - \protect\pkgname{inst}, - \protect\pkgname{protext}} -\label{sec:multiple-dist} - -Space limitations of \acro{CD-ROM} format have forced us to divide -\TK{} into several distributions, as follows. - -\begin{description} - -\item [live] A complete system on \acro{DVD}; it is too large -for \acro{CD}. It can be run live or installed to disk. It also -includes a snapshot of the \CTAN{} repository, the \pkgname{protext} -distribution for Windows and the Mac\TeX\ distribution for \MacOSX, entirely -independent of \TL{}, as well as assorted other packages in a -\texttt{texmf-extra} directory. - -\CTAN{}, \pkgname{protext}, Mac\TeX, and \texttt{texmf-extra} do not follow -the same copying conditions as \TL{}, so be careful when redistributing or -modifying. - -\item [inst(allable)] A complete system on \CD; in order to make this fit, -the packages and programs are compressed. Therefore, it is not possible -to run \TeX\ directly from the installable \CD, you have to install it -to disk (hence its name). Installation is described in subsequent sections. - -\item [protext] 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. It can be run live, or installed to disk. -The \ProTeXt\ home page is \url{http://tug.org/protext}. - -\ProTeXt\ is provided as both the top level of the \pkgname{live} \DVD\ -and on its own \CD\ (for those who cannot use the \DVD). - -\end{description} - -\noindent You can tell which type of distribution you're in by looking -for a \texttt{00\var{type}.TL} file at the top of the \TL{} directory. -This file also contains the \TL{} release date. - -Naturally, each user group chooses what to distribute to its own members. - - -\subsection{Top level directories} -\label{sec:tld} - -Here is a brief listing and description of the top level directories in -the \TL{} distribution. On the \pkgname{live} \DVD, the entire \TL{} -hierarchy is in a subdirectory \dirname{texliveYYYY}, not at the top -level of the disc. - -\smallskip -\begingroup - \renewcommand{\arraystretch}{1.3} % open up interrow spacing -\begin{tabular}{>{\ttfamily}lp{.78\hsize}} -bin & The \TeX{} system programs, arranged by platform. \\ -source & The source of all programs, including the main \Webc{} - \TeX{} and \MF{} distributions. These are stored in a - \cmdname{bzip2}-compressed tar archive. \\ -setuptl & Installation programs for Linux and Windows. \\ -support & Assorted auxiliary packages and programs. These are - \emph{not} installed automatically. This includes - assorted editors and \TeX\ shells. \\ -texmf & Tree for the programs, along with their support files and - documentation. Does not include \TeX\ formats and packages. - (\texttt{TEXMFMAIN} in the next section.) \\ -texmf-dist & The main tree of formats and packages. - (\texttt{TEXMFDIST} in the next section.) \\ -texmf-doc & Tree for self-contained pure documentation, arranged by - language. \\ -texmf-var & Tree for files automatically generated and stored. - (\texttt{TEXMFSYSVAR} in the next section.) \\ -\end{tabular} -\endgroup - -\smallskip - -In addition to the directories above, the installation scripts and -\filename{README} files (in various languages) are at the top level of -the distribution. - -The \dirname{texmf-doc} directory contains only documentation, but -it does not contain all the documentation. The documentation for the -programs (manuals, man pages, Info files) is in \dirname{texmf/doc}, -since the programs are in \dirname{texmf}. Similarly, the documentation -for \TeX\ packages and formats is in \dirname{texmf-dist/doc}. You can -use the \cmdname{texdoc} or \cmdname{texdoctk} programs to find any -documentation wherever it's located. The comprehensive links in the -top-level file \OnCD{doc.html} may also be helpful. - - -\subsection{Overview of the predefined texmf trees} -\label{sec:texmftrees} - -This section lists all predefined variables specifying texmf trees used -by the system, and their intended purpose. The command \texttt{texconfig -conf} shows you the values of these variables, so that you can easily -find out how they map to directory names in your installation. - -\begin{ttdescription} -\item [TEXMFMAIN] The tree which holds vital parts of the system - such as helper scripts (e.g., \verb+web2c/mktexdir+), pool files and - other support files. -\item [TEXMFDIST] The tree which holds the main set of macro packages, - fonts, etc., as originally distributed. -\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 depends on \verb+$HOME+ by default, % $ - which dynamically adjusts for each user to an individual - directory. -\item [TEXMFCONFIG] The tree used by te\TeX's utilities - \verb+texconfig+, \verb+updmap+, and \verb+fmtutil+ to store modified - configuration data. Under \verb+$HOME+ by default. %$ -\item [TEXMFSYSCONFIG] The tree used by te\TeX's 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 \verb+$HOME+ by default. %$ -\item [TEXMFSYSVAR] The tree used by \verb+texconfig-sys+, - \verb+updmap-sys+ and \verb+fmtutil-sys+ to store (cached) runtime - data such as format files and generated map files. -\end{ttdescription} - -For more discussion of \texttt{texconfig} and related utilities, please -see section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig}. - - -\subsection{Extensions to \protect\TeX} -\label{sec:tex-extensions} - -\TL{} contains several extended versions of \TeX: - -\begin{description} - -\item [\eTeX] adds a small but powerful 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{}. See -\OnCD{texmf/doc/pdftex/manual/} for the manual, and -\OnCD{texmf/doc/pdftex/manual/samplepdf/samplepdf.tex}. This is the -default program for all formats except plain \TeX. - -\item [Xe\TeX] adds support for Unicode input and OpenType fonts, using -third-party libraries. See \url{http://scripts.sil.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. See -\OnCD{texmf-dist/doc/omega/base/doc-1.8.tex} (not completely up-to-date). - -\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] 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 [dv2dt, dt2dv] convert \dvi{} to/from plain text. - -\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 [lacheck] \LaTeX{} syntax checker. - -\item [texexec] Con\TeX{}t and \acro{PDF} processor. - -\item [tex4ht] \TeX{} to \acro{HTML} converter. - -\end{cmddescription} - - -\section{Unix installation} -\label{sec:unix-install} - -As introduced in section~\ref{sec:basic} (\p.\pageref{sec:basic}), -\TL{} has three principal uses: - -\begin{enumerate} -\item Run directly from media. -\item Install to disk. -\item Integrate a particular package or collection into your existing -\TeX{} installation. -\end{enumerate} - -\noindent The following sections describes the Unix-specific procedures -for each of these. - -\ifSingleColumn \begin{figure}[ht]\noindent \fi -\begin{warningbox} -\textbf{Warning: } The \TK{} \CD{}s and \DVD{} are in ISO 9660 (High Sierra) -format, \emph{with} Rock Ridge (and Joliet, for Windows) -extensions. Therefore, in order to take full advantage of the \TK{} -under Unix, your system needs to be able to use the Rock Ridge -extensions. Please consult the documentation for your \cmdname{mount} -command to see how to do this. If you have several different machines -on a local network, you may be able to mount the discs on one which -does support Rock Ridge, and use this with the others. - -\leavevmode\quad Modern systems should be able to use the discs without -problems. If troubles, let us know. The discussion below assumes you -have been able to mount the \CD{}s with full Rock Ridge compatibility. -\end{warningbox} -\ifSingleColumn\end{figure}\fi - - -% -\subsection{Running \protect\TL{} directly from media (Unix)} - -\def\runlive{% text repeated in windows section -It is possible to use the \TeX{} system directly from the \pkgname{live} -\DVD{}, without installing the distribution to disk. (Thus the name -\TeX\ `Live', in fact.) It is \emph{not} possible to run \TeX{} -directly from the other \CD{}s (see section~\ref{sec:multiple-dist}, -\p.\pageref{sec:multiple-dist}). -} - -\def\startinst{% repeated in other subsections -To start, you mount the \CD{} or \DVD{}, with Rock Ridge extensions -enabled. The exact command to do this varies from system to system; the -following works under Linux, except the name of the device -(\filename{/dev/cdrom}, here) may vary. (All our examples will use -\texttt{>} as the shell prompt; user input is -\Ucom{\texttt{underlined}}.) -\begin{alltt} -> \Ucom{mount -t iso9660 /dev/cdrom /mnt/cdrom} -\end{alltt} - -\noindent Change the current directory to the mount point: -\begin{alltt} -> \Ucom{cd /mnt/cdrom} -\end{alltt} - -\noindent Under \MacOSX, the directory is typically under -\dirname{/Volumes}, and the media will be mounted automatically. -} - -\def\installtlsh{ -Run the installation script \filename{install-tl.sh}: -\begin{alltt} -> \Ucom{sh install-tl.sh}\\ -Welcome to TeX Live... -\end{alltt} - -\noindent After various greeting messages and a list of the main menu -options, the installation will ask you to enter a command. Do this by -typing the desired character and hitting return; don't type the angle -brackets shown. Either uppercase or lowercase is ok; we'll use -lowercase in our examples. -} - -\runlive -\startinst -\installtlsh - -For running live, our first command will be \Ucom{d} and then the -subcommand \Ucom{1} to set directories. Even in this case, we must -choose a directory on the local disk to place files that the \TeX{} -system itself generates, such as fonts and formats, and also to provide -a place for updated configuration files, if need be. - -We'll use \dirname{/opt/texlive2007} in this example. It's good to -include the year in the name, as these generated files are not -in general compatible from release to release. (If the default value of -\dirname{/usr/local/texlive/2007} works for you, then you can skip this -step.) - -\begin{alltt} -Enter command: \Ucom{d} -Current directories setup: -<1> TEXDIR: /usr/local/texlive/2007 -... -Enter command: \Ucom{1} -New value for TEXDIR [/usr/local/texlive/TeX]: \Ucom{/opt/texlive2007} -... -Enter command: \Ucom{r} -\end{alltt} - -\noindent Back at the main menu, our second and last command is -\Ucom{r}, to set up for running live off the media without installing -to disk: -\begin{alltt} -Enter command: \Ucom{r} -Preparing destination directories... -... -Welcome to TeX Live! -> -\end{alltt} - -\noindent And we are back at the system prompt, as shown. - -Next, it is necessary to alter two environment variables: -\envname{PATH}, to an architecture-dependent value (so that we can run -the programs), and \envname{TEXMFSYSVAR}, to the value specified above. -See table~\ref{tab:archlist} for a list of the architecture names for -the different systems. - - -\def\textruntexconfig{% -After the main installation has completed, and environment variables -have been set, the last step is to run \cmdname{texconfig} or -\cmdname{texconfig-sys} to customize your installation to your needs. -This is explained in section~\ref{sec:texconfig}, -\p.\pageref{sec:texconfig}. -} -\textruntexconfig - -\begin{table*}[ht] -\caption[Supported system architectures.]{Supported system -architectures.} -\label{tab:archlist} -\begin{tabular}{>{\ttfamily}ll} -alpha-linux & HP Alpha GNU/Linux \\ -hppa-hpux & HPPA HP-UX \\ -i386-darwin & x86 \MacOSX \\ -i386-freebsd & x86 FreeBSD \\ -i386-linux & x86 GNU/Linux \\ -i386-openbsd & x86 OpenBSD \\ -i386-solaris & x86 Solaris \\ -mips-irix & SGI IRIX \\ -powerpc-aix & IBM RS/6000 AIX \\ -powerpc-darwin & PowerPC \MacOSX \\ -powerpc-linux & PowerPC GNU/Linux \\ -sparc-linux & Sun Sparc GNU/Linux \\ -sparc-solaris & Sun Sparc Solaris \\ -win32 & Windows (32-bit) \\ -x86\_64-linux & x86 64-bit GNU/Linux \\ -\hline -\end{tabular} -\end{table*} - -\label{text:path} -The syntax for setting the environment variables, and the initialization -file to put them in, depends on the shell you use. If you use a -Bourne-compatible shell (\cmdname{sh}, \cmdname{bash}, \cmdname{ksh}, et -al.), put the following into your \filename{$HOME/.profile} file: -\begin{alltt} -PATH=/mnt/cdrom/bin/\var{archname}:$PATH; export PATH -TEXMFSYSVAR=/opt/texlive2007/texmf-var; export TEXMFSYSVAR -\end{alltt} - -\noindent For C shell-compatible shells (\cmdname{csh}, \cmdname{tcsh}), -put the following into your \filename{$HOME/.cshrc} file: -\begin{alltt} -setenv PATH /mnt/cdrom/bin/\var{archname}:$PATH -setenv TEXMFSYSVAR /opt/texlive2007/texmf-var -\end{alltt} - -\noindent Then log out, log back in, and test your installation -(see section~\ref{sec:test-install}, \p.\pageref{sec:test-install}). - -\def\textifindoubt{% -If in doubt, please ask any local system gurus to help you with -problems; for example, the way to mount the \TL{} media, which -directory or directories to use, and precise details of the changes to -your personal initialization files can and do vary from site to site. -} -\textifindoubt - - -% -\subsection{Installing \protect\TeX\protect\ Live to disk} -\label{sec:unix-install-disk} - -It is possible, indeed typical, to install the \TL{} distribution to -hard disk. This can be done from either the \pkgname{live} or -\pkgname{inst} distributions. (See section~\ref{sec:multiple-dist}, -\p.\pageref{sec:multiple-dist}, for an explanation of the different -distributions.) - -\startinst -\installtlsh - -Table~\ref{tab:main-menu-options} briefly lists the options in the main -menu. The order in which you select the options makes little -difference, except that \Ucom{i} must be last. It's reasonable to go -through them in the order presented here. - -% apparently here.sty [H] doesn't support table*. -\begin{table}[H] -\caption{Main menu options for the installation.} -\label{tab:main-menu-options} -\begin{tabular}{>{\ttfamily}ll} -p & The platform you are running on.\\ -b & The architectures for which to install binaries.\\ -s & The base installation scheme to use (minimal, recommended, - full, etc.)\\ -c & Override the base scheme for individual collections.\\ -l & Override for language collections.\\ -d & Directories in which to install.\\ -o & Other options.\\ -i & Perform the installation.\\ -\end{tabular} -\end{table} - -Here are further details on each option. - -\textbf{\optname{p} -- Current platform.} Since the installation script -automatically guesses which platform you're running on, it is usually -unnecessary to use this option. It's there in case you need to override -the automatic detection. - -\textbf{\optname{b} -- Binary architectures.} 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 -(or omit installing the current platform). This can be useful if you are -sharing a \TeX\ tree across a network of heterogenous machines. For a -list of the supported architectures, see table~\ref{tab:archlist}, -\p.\pageref{tab:archlist}. - -\textbf{\optname{s} -- Base installation scheme.} From this menu, you -can choose an overall set of package collections, called a ``scheme''. -The default \optname{full} scheme installs everything available, but you -can also choose the \optname{basic} scheme for a minimal system, or -\optname{medium} to get something in between. There are also specific -sets for Omega and \acro{XML}. - -\textbf{\optname{c} -- Individual collections.} From this menu, you can -override the scheme's set of collections to install. Collections are -one level more detailed than schemes\Dash collections consist of one or -more packages, where packages (the lowest level grouping in \TL) contain -the actual \TeX\ macro files, font families, and so on. In this menu, -selection letters are case-sensitive. - -\textbf{\optname{l} -- Language collections}. This menu has the same -basic purpose as \Ucom{c}, to override the collection set in the chosen -scheme. In this case, the collections are specifically for different -languages. Selection letters are case-sensitive here too. Here is a -list of the language collections in \TL: - -% xx really should generate list from texmf/tpm/collection/tex-lang* -% a la install-tl.sh. -\begin{tabbing} -\hspace{.25\linewidth} \= -\hspace{.25\linewidth} \= -\hspace{.25\linewidth} \= -\hspace{.25\linewidth} \kill -(some) African scripts \> -Arabic \> -Armenian \> -Chinese\,Japanese\,Korean \\ -Croatian \> -Cyrillic \> -Czech/Slovak \> -Danish \\ -Dutch \> -Finnish \> -French \> -German \\ -Greek \> -Hebrew \> -Hungarian \> -Indic \\ -Italian \> -Latin \> -Manju \> -Mongolian \\ -Norwegian \> -Polish \> -Portuguese \> -Spanish \\ -Swedish \> -Tibetan \> -\acro{UK} English \> -Vietnamese \\ -\end{tabbing} - -\noindent Language collections typically include fonts, macros, -hyphenation patterns, and other support files. (For instance, -\pkgname{frenchle.sty} is installed if you select the \optname{French} -collection.) In addition, installing a language collection will alter -the \filename{language.dat} configuration file controlling which -hyphenation patterns are loaded. - -\textbf{\optname{d} -- Installation directories}. Three directories can -be changed here: -\label{text:instdir} - -\begin{ttdescription} -\item [TEXDIR] The top-level directory under which -everything else will be installed. The default value is -\dirname{/usr/local/texlive/2007}, and is often changed. We recommend -including the year in the name, to keep different releases of \TL{} -separate. (You may wish to make a version-independent name such -\dirname{/usr/local/texlive} via a symbolic link, which you can then -update after testing the new release.) - -Under \MacOSX, the usual frontends look for \TeX{} in -\dirname{/usr/local/teTeX}, so you may wish to install \TL{} there. - -\item [TEXMFLOCAL] This tree is where the \TeX{} system (not as part of -the initial installation, but rather as time goes by) puts -non-version-specific files, primarily fonts. The default value is -\dirname{/usr/local/texlive/texmf-local}, independent of the current -\TL{} release, because it's also the recommended location to put any -local packages or configuration settings. - -\item [TEXMFSYSVAR] This tree is where \cmdname{texconfig-sys} puts -files that \emph{are} version-specific. The default value is -\dirname{TEXDIR/texmf-var}, and there's generally no reason to change -it. There is also \envname{TEXMFSYSCONFIG}, which is where -\cmdname{texconfig} looks for modified configuration data. See -section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig} for more -information. - -\end{ttdescription} - -\textbf{\optname{o} -- Other options.} From this menu, you can select -the following general options: - -\begin{ttdescription} -\item [a] Specify an alternate directory for generated fonts. -The default is to use the \envname{TEXMFVAR} tree, as explained above. -Setting this is useful if you plan to mount the main tree read-only, and -therefore you need another location (perhaps host-specific) for -dynamically created fonts. - -\item [l] Create symbolic links for the binaries, man pages, -and\slash or \acro{GNU} Info files in other locations. For example, you may -wish to make the man pages available under \dirname{/usr/local/man} and -the Info files available under \dirname{/usr/local/info}. (Of course -you need appropriate privileges to write in the specified directories.) - -It is not advisable to overwrite a \TeX\ system that came with your -system with this option. It's intended primarily for creating the links -in standard directories that are known to users, such as -\dirname{/usr/local/bin}, which don't already contain any \TeX\ files. - -\item [d] Skip installation of the font/macro documentation tree. -This is useful if you need to save space, or if you've previously -installed the documentation elsewhere. - -\item [s] Skip installation of the main font/macro source -tree. This is useful if you are arranging to share that tree between -machines and\slash or architectures in some other way, such as \acro{NFS}. - -\end{ttdescription} - -\textbf{i -- Perform installation.} When you're satisfied with your -configuration options, enter \Ucom{i} to actually do the installation -from the media to your chosen locations. - -% text is similar to above, but no TEXMFSYSVAR, so we have to write out. -After the installation completes, your next step is to include the -architecture-specific subdirectory of \dirname{TEXDIR/bin} in your -\envname{PATH}, so the newly-installed programs can be found. The -architecture names are listed in table~\ref{tab:archlist}, -\p.\pageref{tab:archlist}, or you can simply list the directory -\dirname{TEXDIR/bin}. - -The syntax for doing this, and the initialization file to use, depends -on your shell. If you use a Bourne-compatible shell (\cmdname{sh}, -\cmdname{bash}, \cmdname{ksh}, et al.), put the following into your -\filename{$HOME/.profile} file: - -\begin{alltt} -PATH=/usr/local/texlive/2007/bin/\var{archname}:$PATH; export PATH -\end{alltt} - -\noindent For C shell-compatible shells (\cmdname{csh}, \cmdname{tcsh}), -put the following into your \filename{$HOME/.cshrc} file: -\begin{alltt} -setenv PATH /usr/local/texlive/2007/bin/\var{archname}:$PATH -\end{alltt} - -\textruntexconfig - -Here is a minimal annotated example which accepts the default -directories and installs binaries for the current system only. Thus, -only one command is needed, \Ucom{i} for install. The \texttt{>} is the -shell prompt as usual. - -\begin{alltt} -> \Ucom{sh install-tl.sh} -\Ucom{i} # perform installation -> \Ucom{texconfig} ... # see section \ref{sec:texconfig} -# New PATH element, with Linux as the example: -> \Ucom{PATH=/usr/local/texlive/2007/bin/i386-linux:$PATH; export PATH} -\end{alltt} - -If your Unix system supports the \cmdname{manpath} command (type \code{man -manpath} to learn more), you can make the \TL\ manual pages available -system-wide via the normal \cmdname{man} command by editing the file -\filename{/etc/manpath.config}; you might need root permissions for this. -With the following entry in \filename{/etc/manpath.config} the \TL\ -manual pages will be found at their original places within the \TL\ tree -(adapt the binary path for your system architecture): - -\begin{verbatim} -MANPATH_MAP /usr/local/texlive/2007/bin/i386-linux \ - /usr/local/texlive/2007/texmf/doc/man -\end{verbatim} - -\textifindoubt - - -\subsubsection{Non-interactive installation} -\label{sec:noninteractive-install} - -It is possible to override the default directories with environment -variables, and then install non-interactively. Example: -\begin{alltt} -> \Ucom{TEXLIVE_INSTALL_PREFIX=/opt/texlive} -> \Ucom{export TEXLIVE_INSTALL_PREFIX} -> \Ucom{echo i | sh install-tl.sh} -\end{alltt} - -The \envname{TEXLIVE\_INSTALL\_PREFIX} variable overrides the default -location of \dirname{/usr/local/texlive}, leaving all else -unchanged---so with the above invocation, the main installation will go -to \dirname{/opt/texlive/2007}. - -In the usual Unix way, the final \Ucom{echo i} can be replaced by any -sequence of input commands via a here document, so any sequence of -commands can be scripted. - -Here are all the possible overrides: - -\begin{ttdescription} -\item [TEXLIVE\_INSTALL\_PREFIX] - Override \dirname{/usr/local/texlive}. -\item [TEXLIVE\_INSTALL\_TEXDIR] - Override \dirname{\$TEXLIVE_INSTALL_PREFIX}/2007. -\item [TEXLIVE\_INSTALL\_TEXMFLOCAL] - Override \dirname{\$TEXLIVE_INSTALL_PREFIX/texmf-var}. -\item [TEXLIVE\_INSTALL\_TEXMFSYSVAR] - Override \dirname{\$TEXLIVE_INSTALL_TEXDIR/texmf-var}. -\item [TEXLIVE\_INSTALL\_TEXMFHOME] - Override \dirname{\$HOME/texmf}. -\end{ttdescription} - -It would be better to support a standard \acro{GNU}-style -\filename{configure} with options, instead of these environment -variables. Volunteers are welcome! - - -% -\subsection{Installing individual packages to disk} - -You can add individual packages or collections from the current -distribution to an existing non-\TL{} setup, or an earlier -\TL{} installation. - -\startinst - -Run the installation script \filename{install-pkg.sh} (not -\filename{install-tl.sh}, which is intended for complete installations -only): -\begin{alltt} -> \Ucom{sh install-pkg.sh \var{options}} -\end{alltt} - -The first set of options controls what gets read: - -\begin{ttdescription} -\item [-{}-package=\var{pkgname}] The individual package to work on. - -\item [-{}-collection=\var{colname}] The individual collection to work on. - -\item [-{}-nodoc] Exclude documentation files from the operation. - -\item [-{}-nosrc] Exclude source files from the operation. - -\item [-{}-cddir=\var{dir}] Source directory to read from; defaults -to the current directory. If you followed the instructions above, that -will be the distribution directory, and won't need to be changed. - -\item [-{}-listdir=\var{dir}] The so-called `lists' directory within -\var{cddir} from which to read the package information. The only -reason to change the default is if you're making changes to \TL{} -yourself. - -\end{ttdescription} - -What actually happens is controlled by the following options. If -neither of these are specified, the default action is to install the -selected files. The main destination tree is found by expanding -\envname{\$TEXMFMAIN} with \cmdname{kpsewhich}. You can override it by -setting either the environment variable \envname{TEXMFMAIN} or -\envname{TEXMF}. - -\begin{ttdescription} -\item [-{}-listonly] List the files that would be installed, but don't -actually install anything. - -\item [-{}-archive=\var{tarfile}] Instead of installing the files into -the \TeX{} system, make a \cmdname{tar} archive. - -\end{ttdescription} - -Additional options: - -\begin{ttdescription} - -\item [-{}-config] After installation, run \code{texconfig init}. - -\item [-{}-nohash] After installation, don't run \cmdname{mktexlsr} to -rebuild the filename database. - -\item [-{}-verbose] Give more information as the script runs. - -\end{ttdescription} - -Here are some usage examples: - -\begin{enumerate} - -\item To see the files in the package \pkgname{fancyhdr} without -installing it: - -\begin{alltt} -\ifSingleColumn> \Ucom{sh install-pkg.sh --package=fancyhdr --listonly} -\else> \Ucom{sh install-pkg.sh --package=fancyhdr \bs} -> \Ucom{--listonly} -\fi{} -texmf/doc/latex/fancyhdr/README -texmf/doc/latex/fancyhdr/fancyhdr.pdf -... -\end{alltt} - -\item Install the \LaTeX{} package \pkgname{natbib}: -\begin{alltt} -> \Ucom{sh install-pkg.sh --package=natbib} -\end{alltt} - -\item Install the \LaTeX{} package \pkgname{alg} without source files or -documentation: -\begin{alltt} -\ifSingleColumn> \Ucom{sh install-pkg.sh --package=alg --nosrc --nodoc} -\else> \Ucom{sh install-pkg.sh -{}-package=alg \bs} -> \Ucom{-{}-nosrc -{}-nodoc} -\fi\end{alltt} - -\item Install all the packages in the collection of additional -plain \TeX\ macros: -\begin{alltt} -> \Ucom{sh install-pkg.sh --collection=tex-plainextra} -\end{alltt} - -\item Write all files in the \pkgname{pstricks} package to a -\cmdname{tar} file in \path|/tmp|: -\begin{alltt} -\ifSingleColumn> \Ucom{sh install-pkg.sh --package=pstricks --archive=/tmp/pstricks.tar} -\else -> \Ucom{sh install-pkg.sh -{}-package=pstricks \bs} -> \Ucom{-{}-archive=/tmp/pstricks.tar} -\fi\end{alltt} - -\end{enumerate} - -\textifindoubt - - -% -\section{Post-installation} -\label{sec:postinstall} - -After the main installation is done, for any operating system, the -remaining steps are to configure the system for your local needs, and -perform some basic tests. - -Another sort of post-installation is to acquire packages, fonts, or -programs that were not included in \TL{}. The basic idea is to -install such additions in the \envname{TEXMFLOCAL} tree (if you -installed to disk), or \envname{TEXMFSYSVAR} (if you are running live). -See the ``Installation directories'' option on \p.\pageref{text:instdir}. - -Unfortunately, the details can and do vary widely, and so we do not attempt to -address them here. Here are some external links to descriptions: -\begin{itemize*} -\item -\url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=instpackages} -\item -\url{http://www.ctan.org/installationadvice} -\item -\url{http://www.ctan.org/tex-archive/info/beginlatex/html/chapter5.html#pkginst} -\item -\url{http://www.ctan.org/tex-archive/info/Type1fonts} for -installation information for fonts in particular. -\end{itemize*} - - -\subsection{The \protect\cmdname{texconfig} program} -\label{sec:texconfig} - -At any time after installation, you can and should use the program -\cmdname{texconfig} to configure the system to fit your local needs. It -is installed in the architecture-specific subdirectory -\texttt{TEXDIR/bin/\var{arch}} along with everything else. - -If you run it without arguments, it will enter full-screen mode and -allow you to view and change options interactively. - -You can also run it with various command-line options. Here are some of -the most common (\TL{} is configured for the A4 paper size by default): - -\begin{ttdescription} - -\item [texconfig paper letter] Set default paper size for -various programs and drivers (\cmdname{pdftex}, \cmdname{dvips}, -\cmdname{dvipdfm}, \cmdname{xdvi}) to be \acro{US} letter. The other -allowable size is \optname{a4}, which is the default. - -\item [texconfig rehash] Update all the \TeX{} ``filename databases'', -after adding or removing files. - -\item [texconfig faq] Show the \teTeX{} \acro{FAQ}. -(See also the main \TeX{} \acro{FAQ} in \OnCD{texmf-doc/doc/english/FAQ-en}.) - -\item [texconfig help] Output help information for \cmdname{texconfig}. - -\end{ttdescription} - -Of course, \cmdname{texconfig} can only support changing a few of the -many options and configuration parameters in a \TeX{} system. The main -configuration file for the base \Webc{} programs is named -\filename{texmf.cnf}. You can find its location by running -\samp{kpsewhich texmf.cnf}; it contains many comments explaining the -default settings and useful alternatives. - -\cmdname{texconfig} alters files in a user-specific directory, as in -\dirname{$HOME/.texlive2007}. If you install \TeX\ just for yourself, -that is unlikely to make a difference. But if you install \TeX\ on a -multi-user system, you will want to change the configuration for the -whole system. In this case, run \cmdname{texconfig-sys} instead of -\cmdname{texconfig}. - -Likewise, the \cmdname{updmap} and \cmdname{fmtutil} scripts were -changed, to work under \dirname{$HOME/.texliveYYYY}. To alter system -directories, use \cmdname{updmap-sys} and \cmdname{fmtutil-sys}. - -In particular, for multi-user systems, you will probably want to -pregenerate the standard formats with \texttt{fmtutil-sys --missing}. -Otherwise, each user will end up with their own formats. - -Also, if you have a personally-modified copy of \filename{fmtutil.cnf} -or \filename{updmap.cfg}, instead of using the ones generated by -installation, they must be installed in the tree referenced by the -variable \envname{TEXMFSYSCONFIG}. - -The variables specifying the directories altered by these commands are -listed in section~\ref{sec:texmftrees}, \p.\pageref{sec:texmftrees}. -You can see the actual directories by running \texttt{texconfig conf}, -and you can change them by editing \filename{texmf.cnf}. - - -\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; 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.141592 (Web2C 7.5.5) -kpathsea version 3.5.5 -... -\end{alltt} -If this comes back with `command not found' instead of version and -copyright information, most likely you don't have the correct -\dirname{bin} subdirectory in your \envname{PATH}. See -the environment-setting information on \p.\pageref{text:path}. - -\item Process a basic \LaTeX{} file: -\begin{alltt} -> \Ucom{latex sample2e.tex} -This is pdfeTeXk, Version 3.141592... -... -Output written on sample2e.dvi (3 pages, 7496 bytes). -Transcript written on sample2e.log. -\end{alltt} -If this fails to find \filename{sample2e.tex} or other files, perhaps -you have interference from old environment variables or configuration -files. For a deep analysis, you can always ask \TeX{} to report on -exactly what it is searching for, and finding; see ``Debugging actions'' -on page~\pageref{Debugging}. - -\item Preview the result online: -\begin{alltt} -> \Ucom{xdvi sample2e.dvi} -\end{alltt} -(Under Windows, the analogous command is \cmdname{dviout}.) 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 the system.) -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} -Unfortunately neither \cmdname{gv} nor \cmdname{xpdf} are currently -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. - -\item Other standard test files you may find useful: - -\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} -You can process these in the same way as we did with -\filename{sample2e.tex}. - -\end{enumerate} - -If you are new to \TeX{}, or otherwise need help with actually -constructing \TeX{} or \LaTeX{} documents, please visit -\url{http://tug.org/begin.html} for some introductory resources. - - -\section{\MacOSX{} installation} -\label{sec:mac-install} - -The recommended way to install \TeX\ on \MacOSX\ is from the Mac\TeX\ -distribution, new in 2005. This is provided on the \pkgname{live} -\DVD{} in the top-level \dirname{mactex/} directory. It contains its -own (native) installer for a full \TeX\ distribution, based on a -combination of te\TeX\ and \TL, along with many additional applications -and documentation. The project web page is \url{http://tug.org/mactex}. - -If you prefer, installation of \TeX{} under \MacOSX{} can also be done -directly from \TL, using the \filename{install*} scripts, as follows. - -In order to run the installation scripts under \MacOSX, you need to have -the \cmdname{bash} shell installed. If you are running \MacOSX~10.2 -or later, you have \cmdname{bash}, and can proceed. If you're running -an earlier \MacOSX{} version, however, the default shell is -\cmdname{zsh}, which won't work; you'll need to get \cmdname{bash} from -the Internet, or more likely upgrade your system. - -Once you have \cmdname{bash}, the Unix installation documentation in the -previous section can be followed. See section~\ref{sec:unix-install} on -\p.\pageref{sec:unix-install}; \MacOSX-specific notes are included there -where needed. - -\section{Windows installation} -\label{sec:win-install} - -In this release of \TL{}, happily, the distribution once -again has a native Windows installer, named \cmdname{tlpmgui.exe}. (See -section~\ref{sec:multiple-dist}, \p.\pageref{sec:multiple-dist}, for an -explanation of the different distributions.) - -\cmdname{tlpmgui} has essentially the same options as the Unix -installer, only done through a GUI interface: selecting schemes, -individual collections, installation directories, and so on. -Section~\ref{sec:unix-install-disk} on -\p.\pageref{sec:unix-install-disk} describes the basic elements. It -also allows some post-installation activities such as adding/removing -packages, updating the filename database and building formats. -Moreover, \cmdname{tlpmgui} can setup the system for running -programs directly from the \DVD. - -For those who like to look underneath the hood, \cmdname{tlpmgui} uses -as its ``engine'' a command-line Windows program named \cmdname{tlpm}. - -The Windows \TeX{} system included in \TL{} is based on new binaries -borrowed from the \acro{W32TEX} distribution, kindly provided by Akira Kakuto. -It also includes some older (but still working) tools made by Fabrice -Popineau, and also a new \texttt{dvi} previewer, \textsf{dviout} by -Toshio Oshima. - -\TL{} can be installed on systems running Windows 98, \acro{ME}, -\acro{NT}, \acro{2K} or \acro{XP}. Older versions of Windows (3.1x) -and \acro{MS-DOS} are not supported. - -\textbf{Warning:} Win9.x users must ensure they have enough environment - space before undertaking installation. The \cmdname{tlpmgui.exe} - program won't change the environment size for them. A few environment - variables will be created and it is possible you run out of - environment space. Add \texttt{SHELL=<path>COMMAND.COM /E:4096 /P} in the - config.sys file in order to increase your environment size. - -\subsection{Installing \protect\TeX\protect\ Live to disk} - -After inserting the \TL{} \acro{CD} into the \acro{CD} drive, autostart should -activate \cmdname{tlpmgui}. If it does not, click \guiseq{Start\arw Run}, -then type \verb|<drive letter>:\setuptl\tplmgui.exe| (or -\verb|<drive letter>:\texlive\setuptl\tplmgui.exe| if you are -installing from the \TeX\ Collection \acro{DVD}), where \verb|<drive letter>| -is the drive letter with the \TeX\ Live \acro{CD} (or TeX Collection -\acro{DVD}), and then click \acro{OK}. - -The installation window titled \guiseq{TeX Live installation and maintenance -utility} should open. It contains the following sections: \guiseq{Main -customization}, \guiseq{Install}, \guiseq{Select a scheme}, \guiseq{Select -systems}, \guiseq{Directories} and \guiseq{Options}. - -By default, \cmdname{tlpmgui} tries to detect if \TeX{} is already -installed and depending on the result starts either in fresh -installation or maintenance mode. If you have \TeX{} already installed -but want to install the new version nevertheless, you can use -\texttt{tlpmgui~--install-mode} to force installation mode; but you -should know what you are doing, as the new \TL{} installation will -override the environment variables and other settings of the existing -installation; reverting to your old installation is not automatically -supported. - -Diagnostic information is collected by \cmdname{tlpmgui} in a log file -which is deleted at the end of the run, along with any other temporary -files. Invoking with \texttt{--debug} displays the names and contents -of all \cmdname{tlpmgui} temporary files in a separate window. - -In the \guiseq{Directories} section the installation drive (directory) -next to the \guiseq{CD/DVD} button should be displayed (e.g., -\texttt{F:/} or \texttt{F:/texlive/} for the \acro{DVD}), but if it is not, -then click the \guiseq{CD/DVD} button and select the \acro{CD/DVD} -drive, with the \TL{} \acro{CD} (or \TeX\ Collection \acro{DVD}). - -The directory in which you wish to install the software can be set by -clicking the \guiseq{TLroot} button. This directory will be set as -\path|TLroot| environment variable for later usage. - -In the \guiseq{Select a scheme} section the desired \TL{} installation scheme -should be chosen by clicking the radio button labelled with the installation -scheme name (e.g., \guiseq{scheme-gust}). Each scheme is accompanied by an -\guiseq{Info} button which, when clicked, displays a short description of the -relevant scheme. - -A scheme is a large set of files targeted at some kind of usage. There are -generic schemes for basic, medium and full installations. The remaining ones -are either targeted at certain LUGs (i.e., what GUST or GUTenberg propose -for their members) or application targeted (e.g., for XML and \TeX{} -cooperation). A preselected scheme can be refined. This is done in the -\guiseq{Main customization} section by choosing additional collections from -\guiseq{Standard collections} or \guiseq{Language collections}. For example, -by clicking the \guiseq{Select} button labelled \guiseq{Standard -collections}, additional collections like Metapost, Omega or documentation -in different languages can be selected. - -\guiseq{Wintools} collection is selected by default as it contains many small -programs, usually absent in Windows, which can be handy, like graphics -converters: \cmdname{sam2p}, \cmdname{jpeg2ps}, \cmdname{tiff2png}; -(de)compression programs: \cmdname{bzip2}, \cmdname{gzip}, \cmdname{unzip}, -and \cmdname{wget} which is needed for \cmdname{getnonfreefonts} (new) -utility. - -Next, clicking the \guiseq{Select} button labelled \guiseq{Language -Collections} in the \guiseq{Main customization} section opens the -\guiseq{Language collections} window in which the installation language can -be chosen by ticking the box next to the language. - -Next, click the \guiseq{Install} button in the \guiseq{Install} section to -start the installation proper process. - -\textbf{Note:} The \guiseq{Perl} and \guiseq{Ghostscript} are installed only -on demand. They should be installed unless they are already installed and you -really know what you are doing. Both programs are required by many important -tools. The \verb|PERL5LIB| and \verb|GS_LIB| environment variables will be -set too, as well the path to Ghostscript binaries will be added to the -\verb|PATH| variable. - -The \TL{} system needs some post-processing steps (format files -generation, ls-R databases generation, environment variables, etc.). All -these operations are done there, some of them can be lengthy. So please wait -until you see a statement about the successfully finished installation. - -The shortcut for \cmdname{tlpmgui} (and also \cmdname{dviout}, if installed) -will be added to the menu \guiseq{Start\arw Programs\arw TeXLive2007}. - -If it is needed (Win9x/WinME), you will be asked to reboot your computer. - -\subsection{Support packages for Windows} -\label{sec:win-xemtex} - -To be complete, a \TL installation needs support packages that are not -commonly found on a Windows machine. Many scripts are written using the Perl -language. Some important tools require the Ghostscript \PS{} interpreter to -render or to convert files. A graphic file toolbox is also needed in some -cases. Last but not least, a \TeX-oriented editor makes it easy to type in -your \TeX{} files. - -All these tools are quite easy to find for Windows, but in order to try to -make your life even easier, we have put such a set of tools on \TL: -\begin{itemize*} -\item GNU \cmdname{Ghostscript} 8.54 -\item a minimal \cmdname{Perl} 5.8, sufficient to run all the \TL{} - Perl scripts. -\item win-tools is a set of small programs (bzip2, gzip, jpeg2ps - and tiff2png) -%\item a subset of \cmdname{ImageMagick} 5.5.6 -%\item the \cmdname{ISpell} checker -%\item \cmdname{XEmacs} 21.5.14 with a selection of packages to support -%\TeX{} typesetting. -\end{itemize*} - -Perl and Ghostscript are installed upon request; you may explicitly -deselect them during installation if you already have them. - -If you don't want to install this bundle, then you are on your own to -install the required tools to complete your \TL{} system. Here is a -list of places to get those tools: - -\begin{description} -\item[Ghostscript] \url{http://www.cs.wisc.edu/~ghost/} -\item[Perl] \url{http://www.activestate.com/} (but you might need some - supplementary packages from CPAN: \url{http://www.cpan.org/}) -\item[ImageMagick] \url{http://www.imagemagick.com} -\item[NetPBM] alternatively, you could use NetPBM instead of ImageMagick to - process or convert your graphic files. NetPBM home page is - \url{http://netpbm.sourceforge.net/} -\item[\TeX-oriented editors] There is a wide choice, and it is a matter of the - user's taste. Here is a selection: - \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 AucTeX is available natively under Windows, see - \url{ftp://alpha.gnu.org/gnu/auctex} - \item \cmdname{WinShell} is available on \TL in the \path|support| - directory, see \url{http://www.winshell.de} - \item \cmdname{WinEdt} is shareware available from \url{http://www.winedt.com} - \item \cmdname{Vim} is available from \url{http://www.vim.org} - \item TeXnicCenter is free software, available from - \url{http://www.toolscenter.org} and in the proTeXt distribution. - \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} - \end{itemize*} -\end{description} - -You might want to install other tools that are not free\footnote{Not -free, that is, in the sense of freedom to modify and redistribute, -following free software guidelines. This does not mean you can't acquire -them for no money.} and therefore not included on \TL{}, such as -\cmdname{GSView}, the \cmdname{Ghostscript} companion to more -conveniently view PS/PDF files. \cmdname{GSView} is available from -\url{http://www.cs.wisc.edu/~ghost/gsview/} or any \acro{CTAN} site. - -\section{Maintenance of the installation in Windows} - -If you have \TeX\ Live installed, you can use \cmdname{tlpmgui} again -for modifying and maintaining your installation. - -\subsection{Adding/removing packages} - -As the \cmdname{tlpmgui} shortcut is available in the \guiseq{Start\arw -Programs\arw TeXLive2007} menu, start it from here. The maintenance window -titled \guiseq{TeX Live installation and maintenance utility} shows. It -contains several tabs: \guiseq{Add Packages}, \guiseq{Remove packages}, -\guiseq{Manage installation}, \guiseq{Remove installation}. - -Click the tab labelled \guiseq{Add packages} or \guiseq{Remove packages} -to enter the relevant functionality and then: - -\begin{itemize} -\item In the first tab select the proper \CD{} drive (or \DVD with - \texttt{texlive} directory) by pressing the \guiseq{CD/DVD} button. -\item Click the \guiseq{Search} button in the \guiseq{Buttons} section to -display or refresh in the \guiseq{Select packages to\dots} section the -list of packages to install or remove. - -When adding packages, the list of installed packages is compared to the list -of packages available from your \CD/\DVD. Only packages not already installed are -displayed. It is up to you to select which packages you want to -install. - -When removing individual packages, only a list of installed packages -will be displayed. - -Please note that for both \guiseq{Add packages} and \guiseq{Remove packages} -the collections are listed first. - -\item Select a package by clicking on the name of the package. Clicking the -\guiseq{Info} button in the \guiseq{Buttons} section displays a short -description of the selected package in the window located in the \guiseq{Info -about the selected item} section. To select several packages at once hold -down one of the Ctrl or Shift keys at your keyboard while holding down the -left mouse button or drag the mouse pointer while holding down the left mouse -button. - -\item Click the \guiseq{Install} or \guiseq{Remove} button in the -\guiseq{Buttons} section to perform the appropriate action. -\end{itemize} - -\subsection{Configuring and other management tasks} - -The functions available in the tab labelled \guiseq{Manage the installation} -are helpful in performing actions needed when you want to add support for a -language which was not selected during the installation, or add/regenerate a -format which was not selected during the installation or was modified after -the installation. - -The following actions can be performed: - -\begin{itemize} -\item Refresh the \filename{ls-R} database -\item Create formats (All or Missing) -\item Edit \filename{language.dat} -\item Edit \filename{fmtutil.cnf} -\item Edit \filename{updmap.cfg} -\end{itemize} - -Note: you can close the Edit\dots{} window with the \guiseq{Cancel} or -\guiseq{Done} button; the latter will start rebuilding the format files -(or the fontmap files if you have edited \filename{updmap.cfg}), followed by a -\filename{ls-R} database files refresh. - -For more information about the configuration see section~\ref{sec:persconf}, -\p.\pageref{sec:persconf}. - -\subsection{Uninstalling \protect\TL{}} - -The tab labelled \guiseq{Remove the TeX Live installation} opens a window -which contains functionality not worth describing and we do not know who would -need it and what it is for\dots :-) - -Anyway, if you have the \path|texmf-local| directory for your local additions, -the removal procedure will not wipe it out or delete things in it. However, -it will be done only if you select it explicitly. The \path|setuptl| -directory containing \cmdname{tlpmgui} and related files will not be deleted. -You will have to do some manual cleanup to actually remove them. - -\subsection{Adding your own packages to the installation} - -First, whatever changes you make, \textbf{do not forget to rebuild the ls-R -database files}. Otherwise, your new files will not be found. You can do this -either via the \cmdname{tlpmgui} run and selection of the appropriate action -from the \guiseq{Manage the installation} tab, or manually running the -\file{mktexlsr} command. - -If you want to add files that are not provided by the \TL{} distribution, -it is recommended to put them in the \path|$TEXMFLOCAL| directory. This -way, you will be safe against upgrades of the \TL{} software. - -The directory pointed to by \path|$TEXMFLOCAL| is initially empty. If, -for example, you want to add the support file for the Maple symbolic -computation program, you will have to put the style files in:\\ -\path|c:\TeXLive2007\texmf-local\tex\latex\maple\|\\ and the -documentation files in:\\ \path|c:\TeXLive2007\texmf-local\doc\latex\maple\| - -\subsection{Running \texttt{tlmp.exe} from the command line} -The \cmdname{tlpm.exe} program which is used as engine by \cmdname{tlpmgui} -has a number of other useful options. You can get the list by running: -\begin{verbatim} -tlpm --help -\end{verbatim} - -More information and examples of use can be found in \path|tlpm.readme|. - -\subsection{Network installation} - -\KPS{} knows about UNC names, so you can use them to get your TEXMF -tree from the network. But there is better than this. -All the support files and configuration files, everything except the files in the -\path|bin/win32| are shareable with a \teTeX{} or Unix \TL{} installation. That means -you can use Samba either to mount from an NT server to a Unix -workstation or the converse. Several strategies are possible: -\begin{itemize} -\item Put everything on the server. Just add each set of files for the OS and -architecture you want to use in the \path|bin| directory. That means -for example \path|bin/win32| and \path|bin/i386-linux|. Next configure -your main variables. You can use UNC names to -point to the right directories under Win32. -\item Install a local copy for the binaries and format files. In this - case, assign \path|$TEXMFMAIN| to the main \path|texmf| tree that - will be accessed remotely. Set \path|$TEXMFVAR| to be a local - directory which will hold local configuration files and on-the-fly - generated files. -\end{itemize} - -\subsection{What's different in Windows?} - -The Windows version of \Webc{} has some specific features that should be -pointed out. - -\begin{description} -\item[\cmdname{kpsecheck}] This command provides some options that did - not fit well into \cmdname{kpsewhich}. It will allow you to list all - the files that occur multiple times across your texmf trees. This - could be handy, but most of the time you will also get unwanted - output (like dozens of \path|README| files). It is noticeable - that all these files result in clashes inside the \KPS{}-hashing - mechanism; fortunately, \KPS{} never looks for these files. For - this reason, you can combine the \path|-multiple-occurrences| with 2 - other options for including or excluding any filename that match - some pattern (you can request for several patterns). - - The \cmdname{kpsecheck} command will also report the status of shared - memory: in use or not used. That might be useful to know because if - the status reported is \samp{in use}, that means one or several - processes are working, and the effect of any \cmdname{mktexlsr} - command will be delayed until the next time where no \KPS{} linked - process will be running. - - Last, this same command will report about the location it thinks - Ghostscript can be found. Under Win32, for many programs, it is - easier to use the Ghostscript dll, and find it by using the - Ghostscript registry key than to change the \path|PATH|, which has a - limited length anyway. -\item[\Webc{}] The engines have one more option than in Unix \Webc: - \begin{itemize} - \item \path|-proctimes| print statistics about the job run - time. It is to be noted that Win9x not being a true multitasking - operating system, it has no reliable timer for short periods, so - the value printed is an approximation. Under NT/2K/XP, the result - is quite accurate with user time and system time values allocated - for this run. For Unix - users: the \path|time| command is not usually available to Windows - users. - \end{itemize} -\end{description} - -\subsection{Personal configurations} -\label{sec:persconf} - -\subsubsection{Dvips} - -The configuration file for dvips can be found in\\ -\verb+C:\TeXLive2007\texmf-var\dvips\config\config.ps+\\ -You may open it with any editor - %(\cmdname{WinShell} will do fine) - and change some parameters: - -\begin{description} -\item [fonts] you can change the default printer \MF{} mode or printer - resolution in case \cmdname{dvips} needs to generate PK fonts. By default it - is configured to use Type~1 versions of the CM fonts, so it should - not call \cmdname{mktexpk} too often; -\item[printer] you can tell dvips where you want to print by default. If - the \optname{o} option is not followed by a printer name, then a - \file{.ps} \PS{} file is written. You can give dvips a printer - name such as: -\begin{verbatim} -o lpt1: -% o | lpr -S server -P myprinter -% o \\server\myprinter -\end{verbatim} -\item[paper] Next, you might want - to change the paper size from European (A4) to US letter - by making the US letter the first paper size mentioned in the file. - Scroll to the group of lines beginning with \code{@}. Move - the appropriate lines so that this section begins with the lines:\\ -\hspace*{1em} @ letterSize 8.5in 11in\\ -\hspace*{1em} @ letter 8.5in 11in\\ -\hspace*{1em} @+ \%\%BeginPaperSize: Letter\\ -\hspace*{1em} @+ letter\\ -\hspace*{1em} @+ \%\%EndPaperSize -\end{description} - -The current \TL{} distribution implements the procedure of making always -up-to-date fontmaps files for Dvips and Pdftex. This is done by the -\cmdname{updmap} program during installation. -If you add new font packages using the installation program or by hand, -edit the file \verb+updmap.cfg+ in \path|$TEXMFVAR/web2c|. - -\subsubsection{PdfTeX} - -If you use the program pdf{}latex to write \acro{PDF} format directly, -and you are using \acro{US} letter-size paper, edit the file -\verb+C:\TeXLive2007\texmf-var\tex\generic\config\pdftexconfig.tex+ and -change \samp{\bs pdfpagewidth} and \samp{\bs pdfpageheight}. These entries -should read: -\begin{alltt} -\bs{}pdfpagewidth=8.5 true in -\bs{}pdfpageheight=11 true in -\end{alltt} -Save the file and exit the editor. - -\subsubsection{Xe\TeX} -Xe\TeX{} for Windows is linked statically with fontconfig 2.4.2. -A configuration file for fontconfig is \verb+fonts.conf+. For details, -see the file \verb+fonts.conf+ itself which is in a directory shown by -the command \texttt{kpsewhich --var-value=FONTCONFIG\_PATH}. - -\subsubsection{GSView} -GSView is now distributed under the Aladdin License, and therefore is no -longer included in \TL{}. - -You may want to change the page size to US letter size. If so, open -GSView from the \guiseq{Start} menu, and select \guiseq{Media\arw Letter}. - -Also, there are menu settings that are supposed to give you the most -readable screen image. On \guiseq{Media \arw Display Settings}, set both -\optname{Text Alpha} and \optname{Graphics Alpha} to 4~bits. - -Note that the installation process has set all \code{.ps} and -\code{.eps} files to automatically open with \cmdname{GSView}. - -For printing instructions, see section~\ref{printing} below. - - -\subsection{Testing} - -For generic verification procedures, see section~\ref{sec:test-install} -(\p.\pageref{sec:test-install}). This section describes -Windows-specific tests. - -Open the file \verb+sample2e.tex+ in your editor (Xemacs, WinShell), -found in \path|C:\TeXLive2007\texmf-dist\tex\latex\base|. The \LaTeX\ source -should appear on the screen. Process it by clicking on the -\guiseq{Command\arw LaTeX} menu (XEmacs) or \LaTeX\ icon on the toolbar -(WinShell), then view it by clicking on the \guiseq{Command\arw View DVI} -menu (XEmacs) or Preview (dviout) icon (WinShell). - -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. - -\textbf{Hint for the future:} If a \LaTeX\ run stops because \LaTeX\ -cannot find a file, you can press Ctrl-z to quit. - - -\subsection{Printing} -\label{printing} - -It is possible to print from \cmdname{dviout}. In this case, printing -will be done using the Windows unified printer driver. By definition, it is -compatible with all printers. However, there is some drawback: it can -generate some huge spool files, and some (older) versions of Windows -just don't like them. The advantage is that you can use features like -embedding BMP or WMF images. You also need to make sure that the printer -parameters are correctly set, else you -will get scaled printing (printing at 600\dpi{} on a 300\dpi{} printer -will give you only one quadrant of your page). - -Printing is faster and more reliable if you run \cmdname{dvips} to make -a \filename{.ps} file and then print from \cmdname{GSView}. In -\cmdname{GSview}, select \guiseq{File\arw Print\ldots}. A \guiseq{Print} -window will appear. - -If you are using a \PS{} printer, \textit{be sure to select -\guiseq{\PS{} Printer}}. This is done in the \guiseq{Print Method} box -at the bottom left of the \guiseq{Print} window. You can then select any -of the printers that you have previously installed. If you fail to -check the box for \optname{\PS{} Printer}, printing will not work. - -If you will be using your own non-\PS{} printer, select -\guiseq{Ghostscript device} in the \guiseq{Print Method} box, then click -on the button to the right labelled \guiseq{djet500} and select your -printer type from the list that pops up. (In the older version of -\cmdname{GSView}, make sure \optname{\PS{} Printer} is \textit{not} -selected, then select your printer type from the \guiseq{Device} list.) - -\subsection{Tips and tricks for Win32} - -\subsubsection{Different flavors of Win32} - -What we call Win32 is not an operating system by itself. It is a large -set of functions (around 12,000 in the header files of the Microsoft -\acro{SDK}) that you can use to write programs for different operating -systems of the Windows family. - -Windows comes in different flavors: -\begin{itemize} -\item Win95, Win98 and Win\acro{ME}, which \emph{are not true multitasking, - multithreading} environments, but rather updated incarnations of - \acro{DOS}. This can be more or less proven by the fact that when - booting, the PC will load the \path|command.com| interpreter, and if - you stop the boot process at this point, you can ask for the current - (\acro{DOS}) version and it will answer something like \samp{MS-DOS - 7.0} (at least for the old versions of Win9x). -\item Windows \acro{NT}, which is a new operating system written from - scratch, capable of true multitasking behavior, and including many - high level features. -\item Windows 2000, based on \acro{NT}, with all the bells and - whistles of Win98. -\item Windows \acro{XP}, which comes with Personal and Pro flavors. This is - the last step in merging both lines of products (Win9x based and - \acro{NT} based). \acro{XP} is based on \acro{NT}. -\end{itemize} - -Win9x are able to run 32~bits programs and 16~bits programs -concurrently. But the operating system by itself is not entirely -written in 32~bits mode, and does not support memory protection: 16bits -applications can overwrite parts of the operating system memory! Some -parts of the system like the \acro{GDI} (Graphical Device Interface) -manage limited resources like bitmaps, fonts, pens and so on for the set -of all programs that run concurrently. All the bitmaps headers available -at the same time can't amount for more than 64kB. This explains the -performance tool and the fact that you can put your system on his knees -by making intensive use of graphic objects for example. - -NT, 2K and XP do not suffer from these limitations, and neither from -other Win9x limitations. They are true multitasking environments, with -protected memory. They are much more responsive than Win9x because -of better memory management, better file system and so on. - -\subsubsection{Command line prompt} - -You may wonder, ``Why would I need to use a command line prompt when -I have Windows?'' - -Good question! The problem is of very general nature. Not all operations -can be done easily using only a \acro{GUI}. Command line gives you -programming power\Dash assuming a clever command interpreter. - -But the problem here is more fundamental: \TeX{} is \emph{a batch} -tool. Not an interactive one. \TeX{} needs to compute the best -layout for each page, resolve cross-references and so on. This can be -done only by a global processing of the document. It is not (yet) a -task that can be done interactively. - -This means that you should use \TeX{} from a command line. In fact the -situation is not so bad. There is an advantage to write command line -tools for complex processing: they are better debugged, because they are -independent of any \acro{GUI} problems, and \acro{GUI} tools can be -designed to interface to the command line tools. This is the case for -\TeX{}, where you will mostly interact with it through a \acro{GUI} text -editor. - -However, you may need to use the command line prompt in a number of -situations. One is when you are having difficulties and want to debug -your setup. - -\begin{description} - \item[Win9x] You can open a command line prompt by looking either for - the \acro{MS-DOS} icon in the \guiseq{Start\arw Programs} menu, - or by choosing \guiseq{Start\arw Run} menu typing in - \path|command.com| as the program name. - \item[NT, 2K, XP] You can open a command line prompt by looking for - \guiseq{Command Prompt} in the \guiseq{Start\arw Accessories} menu. - You can also choose \guiseq{Start\arw Run} and type in - \path|cmd.exe|, which is the name of the brand new command - interpreter for \acro{NT} (thus, it is untrue to call this a - \emph{DOS} box!). -\end{description} - -These locations may change across different Windows versions. - -\subsubsection{Path separators} - -The Win32 API understands both \path|/| and \path|\| characters as PATH -separators. But the command interpreters do not! So whenever a path name -is used programmatically, you can use both separators, and even mix them -up in the same path name. But on the command line, you must type -\path|\| as path separator. The reason is compatibility: the command -processor used \samp{/} to introduce arguments to commands. - -All this to say: do not be surprised to read path names written using -the Unix convention; Windows-\TL{} is a port of \Webc, and aims to be -compatible across platforms. For this reason, all the configuration files -that need to specify path names use the Unix convention. - -\subsubsection{File systems} -\label{sec:clusters} - -The worst feature of Win9x with regard to \TeX{} is probably the -so-called FAT file system. \TeX{} uses very many small files, with size -around 1--3kB. The \acro{FAT} file system is old, and predates by -decades the multi-gigabytes hard disks we have today. As a result, it -cannot manage efficiently the tens of thousands of \TeX{} files found in -\TL{}. The \acro{FAT} file system allocates a minimum of 32kB for -\emph{any} file on a huge partition. It means that \TeX{} will use much -more disk space than it actually needs. - -The other, more modern, file systems available, \acro{FAT32} and -\acro{NTFS}, do not have this drawback. They manage clusters of 4kB -only. (You can lower the limit to 512 bytes on \acro{NTFS}.) - -\subsubsection{How to add some directory to your PATH} - -There are pairs of variables and values which behave much like global -variables inside your programs. The set of those variables is called the -environment. Each program is initialized with a copy of the -environment when it is run. It can request and change the -value of any variable. The changes happen in the copy of the -environment, and is not at all propagated to the other running -programs. - -Your PATH is a special environment variable used to search for -programs you want to run. -There is a different procedure to change it for Win9x, WinME and NT/2K/XP: - -\begin{description} -\item[Windows 95/98] Edit your \path|autoexec.bat|. In this file should be a line - starting with \texttt{PATH=} and followed by a list of directories separated - by \path|;|. Please add the directory with the executables in this line. - After this, this line could look as follows: -\begin{verbatim} -PATH=c:\windows;c:\windows\system;c:\TeXLive2007\bin\win32 -\end{verbatim} -\item[Windows ME] You need to run the special program - \path|c:\windows\system\msconfig.exe| to be able to change any - environment variable. From this program, select the `Environment' - tab, and then add or modify the variable you want. You will be asked to reboot the - machine upon any change. -\item[Windows NT/2K/XP] - Click left on \guiseq{Start \arw Settings \arw Control Panel}. Now the - window with the control panel icons opens. Double click on System. The - System Properties window opens. Click on the tab \textsf{Environment} - or look for a button named \guiseq{Environment Variables} among the - dialog boxes. Now you can change the environment variables for your - user account. Note: There are also displayed the environment settings - for the system. Normally, you can't change the system variables - unless you have administrator rights on your machine. If you want to - change the \texttt{PATH} for all users, you will have to contact your - system administrator or be the system administrator yourself\Dash in - the latter case you should know what you are doing. - - If there is already a \texttt{PATH} setting for your user account, - left click on \texttt{PATH}. In the field \textsf{Variable} appears - \texttt{PATH} while the field Value shows the current setting of - \texttt{PATH} as a list of directories separated by \path|;|. Add - the directory where the executables are located (e.g. - \path|c:\TeXLive2007\bin\win32|). If there isn't a \texttt{PATH} variable - for your user account, simply click in the field Variable and type - in \texttt{PATH}, click in the field \textsf{Value} - and type in the directory with the executables. Important: Click on - the \textsf{Apply} button before clicking \textsf{Ok}, otherwise the - changes to \texttt{PATH} won't apply to your system. Be careful when - changing the environment settings. -\end{description} - -The best way to be sure that a variable has been properly set is to -open a console and type: -\begin{verbatim} -set VARIABLE -\end{verbatim} -which should return the corresponding value. - -\subsubsection{\TeX{} engines} - -If you have a look at the \Webc{} documentation, you will read that all -the various \TeX{} derived programs use the same base engine. For -example, \path|tex.exe| and \path|latex.exe| are exact copies of the -same program, but each one will use a different format file, based on -its calling name. - -Under Unix, this feature is implemented through \emph{symbolic -links}. It saves up a bit of disk space, because some engines are -used with many different format files. - -The Win32 API does not know about file links. So to save up almost -the same amount of memory, all the \TeX{} base engines have been put -in DLLs (\emph{Dynamic Linked Library}). This means that you will have -the following layout: -\begin{alltt} -2006-11-23 07:06 2 560 latex.exe -2007-01-06 23:54 1 073 664 pdftex.dll -2006-01-28 08:05 2 560 pdftex.exe -\end{alltt} -and the \path|latex.exe| file is nothing but a rough copy of -\path|pdftex.exe| using the same core \path|pdftex.dll|. -The same trick has been used for the \path|mktex*.exe| family of programs -which are linked to the \path|mktex.dll| library. - -In fact, a generic tool called \path|irun.exe| is provided to build the -equivalent of Unix hard links for executable files only under Win32. - -\subsection{In case of problems} -\label{sec:troubleshooting} - -\subsubsection{What to do if \texttt{latex} does not find your files?} - -\begin{itemize} - -\item \cmdname{kpsewhich} is the tool of choice to debug any -problem. However, \cmdname{kpsewhich} outputs debug information to -stderr, and the older Windows consoles do not know how to redirect -stderr to a file. (Windows NT and later do support redirections, but -the trick below will work for any console.) For diagnostic purposes you -can temporarily set an environment variable (in a \acro{DOS}/\acro{cmd} box): - -\begin{verbatim} -SET KPATHSEA_DEBUG_OUTPUT=err.log -\end{verbatim} -You can also set the debug level: -\begin{verbatim} -SET KPATHSEA_DEBUG=-1 -\end{verbatim} - -Similarly, to redirect stderr to stdout: -\begin{verbatim} -SET KPATHSEA_DEBUG_OUTPUT=con: -\end{verbatim} -This way you can capture both stdout and stderr in the same file. -\item Assuming the installation has been done in \path|c:/TeX|, check - the following values: \\ - {\small - \begin{tabular}{ll} - \path|kpsewhich -expand-path $SELFAUTOPARENT| & \path|c:/TeX| \\ - \path|kpsewhich -expand-path $TEXMF| & \path|c:/TeX/texmf....| \\ - \path|kpsewhich -expand-path $TEXMFCNF| & - \path|.;c:/TeX/texmf-var/web2c;| \\ - \path|kpsewhich -expand-var $TEXINPUTS| & \path|.;c:/TeX/texmf/tex//| - \end{tabular} -} -\item If you have other \TeX{}-related values already set in your - environment, please, remove them. They are overriding the ones in - texmf.cnf. -\item Check the values from:\\ -{\small - \begin{tabular}{ll} - \texttt{kpsewhich cmr10.tfm} & \path|c:/TeX/texmf-dist/fonts/tfm/public/cm/cmr10.tfm|\\ - \texttt{kpsewhich latex.fmt}& \path|c:/TeX/texmf-var/web2c/latex.fmt| - \end{tabular} -} -\item At this point, if everything is correct, \TeX{} and friends - should work. If it is not the case, you will need to play with - the \path|-debug=n| option from \path|kpsewhich|, and check back all - the values. Try to identify and report the problem. -\end{itemize} - -\subsubsection{What to do if your setup still does not work as expected?} - -Here are several questions to investigate: - -\begin{enumerate} -\item Is \file{tex.exe} in my \path|PATH|? - -\item Is the \path|TEXMFCNF| variable correctly set to -\path|c:/TeXLive2007/texmf-var/web2c| (default value)? - -\item Are there any errors in the log file generated by the -\file{tlmpgui.exe} program? -\file{tlmpgui.log} can be found in your -\file{TEMP} directory. You can find this by searching for the -string \samp{Error}. Hint: the log file can show some errors after -building all format files. Please do not panic: perhaps some formats -weren't already installed. - -\item Are there any relevant bug fixes at \url{http://tug.org/texlive/}? -(Unlikely, but it doesn't hurt to check.) - -\end{enumerate} - -The \TL{} software consists of hundreds of programs and tens of -thousands of files, all from varying sources. So it is quite difficult to -predict all possible causes for problems. Nevertheless, we will do our -best to help you. (See section~\ref{sec:help}, \p.\pageref{sec:help}.) - -% don't use \Webc so the \uppercase in the headline works. -\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{}. - -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. - -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 \web{} and translates them into C source -code. The core \TeX{} programs are: - -\begin{cmddescription} -\item[bibtex] Maintaining bibliographies. -\item[dmp] \cmdname{troff} to MPX (\MP{} pictures). -\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[makempx] \MP{} label typesetting. -\item[mf] Creating typeface families. -\item[mft] Prettyprinting \MF{} source. -\item[mpost] Creating technical diagrams. -\item[mpto] MetaPost label extraction. -\item[newer] Compare modification times. -\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 \acro{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{}. 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 more than one directory tree -simultaneously, which is useful in maintaining \TeX's standard -distribution and local extensions in two distinct trees. To speed up -file searches the root of each tree has a file \file{ls-R}, containing -an entry showing the name and relative pathname for all files under that -root. - -\subsection{Kpathsea path searching} - -Let us first describe the generic path searching mechanism of the \KPS{} -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{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{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{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{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{Default-expansion} - -\tolerance=2500 -If the highest-priority search path (see ``Path sources'' on -page~\pageref{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 -(appproximately; 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{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{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{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); most sites have only one hierarchy. \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 -(\acro{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{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 more important 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{SExamplesofuse} - -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} - -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 -prolog \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{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. -\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/html/dvips/dvips_toc.html}). -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{SExamplesofuse} 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 -date and time, and informs us that it will generate the -file \file{hello-world.ps}, then that it needs the font file -\file{cmr10}, and that the latter is declared as ``resident'' (no -bitmaps needed): -\begin{alltt}\small -TeX output 1998.02.26:1204' -> hello-world.ps -Defining font () cmr10 at 10.0pt -Font cmr10 <CMR10> is resident. -\end{alltt} -Now the search is on for the file \file{cmr10.tfm}, which is found, -then a few more prolog files (not shown) are referenced, and finally -the Type~1 instance \file{cmr10.pfb} of the font is located and -included in the output file (see last line). -\begin{alltt}\small -kdebug:start search(file=cmr10.tfm, must\_exist=1, find\_all=0, - path=.:~/tex/fonts/tfm//:!!/usr/local/texmf/fonts/tfm//: - /var/tex/fonts/tfm//). -kdebug:search(cmr10.tfm) => /usr/local/texmf/fonts/tfm/public/cm/cmr10.tfm -kdebug:start search(file=texps.pro, must\_exist=0, find\_all=0, - ... -<texps.pro> -kdebug:start search(file=cmr10.pfb, must\_exist=0, find\_all=0, - path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//: - ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//). -kdebug:search(cmr10.pfb) => /usr/local/texmf/fonts/type1/public/cm/cmr10.pfb -<cmr10.pfb>[1] -\end{alltt} - -\subsection{Runtime options} - -Another useful feature of \Webc{} is its possibility to control a number -of memory parameters (in particular, array sizes) via the runtime file -\file{texmf.cnf} read by \KPS{}. The memory settings can be found in -Part 3 of that file in the \TL{} distribution. The more important -are: - -\begin{ttdescription} -\item[\texttt{main\_memory}] - Total words of memory available, for - \TeX{}, \MF{} and \MP. You must make a new format file for each - different setting. For instance, you could generate a ``huge'' - version of \TeX{}, and call the format file \texttt{hugetex.fmt}. - Using the standard way of specifying the program name used by \KPS{}, - the particular value of the \texttt{main\_memory} variable will then - be read from \file{texmf.cnf}. -\item[\texttt{extra\_mem\_bot}] - Extra space for ``large'' \TeX{} data structures: - boxes, glue, breakpoints, etc. Especially useful if you use - \PiCTeX{}. -\item[\texttt{font\_mem\_size}] - Number of words for font information available for \TeX. This - is more or less the total size of all TFM files read. -\item[\texttt{hash\_extra}] - Additional space for the hash table of control sequence names. - Approximately 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 \acro{GNU} version of these programs -(\cmdname{gcc}, \acro{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:unix-install-disk} on -\p.\pageref{sec:unix-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} & \acro{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: \acro{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} - -\section{Acknowledgements} - -\TL{} is a joint effort by virtually all of the \TeX{} user groups. -This edition of \TL{} was overseen by Sebastian Rahtz and Karl Berry. -The other principal contributors 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 together provide the necessary technical -and administrative infrastructure. Please join your local user group! - -\item The \acro{CTAN} team, which distributes the \TL{} images and -provides the common infrastructure for package updates, upon which \TL{} -depends. - -\item Peter Breitenlohner and the \eTeX\ team for the stable foundation -of future \TeX's. - -\item Thomas Esser, without whose marvelous \teTeX{} package \TL{} -would certainly not exist, and whose continual help makes it a better -product. - -\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. - -\item Hans Hagen, for major testing and making the \ConTeXt\ format -conform to \TL's needs. - -\item \Thanh, Martin Schr\"oder, and the pdf\TeX\ team for continuing -enhancements of \TeX's abilities. - -\item Taco Hoekwater, for renewed development efforts on MetaPost and -\TeX\ itself. - -\item Pawe{\l} Jackowski, for the Windows installer \cmdname{tlpm}, -and Tomasz {\L}uczak, for \cmdname{tlpmgui}. - -\item Akira Kakuto, for great assistance in incorporating the Windows -binaries from his \acro{W32TEX} distribution -(\url{http://www.fsci.fuk.kindai.ac.jp/kakuto/win32-ptex/}). - -\item Jonathan Kew and his employer \acro{SIL}, for the major new -development of Xe\TeX{} and taking the time and trouble to integrate it -in \TL{}. - -\item Reinhard Kotucha, for helping with the massive task of updating -packages in \TL{}, as well as Windows research efforts, the -\texttt{getnonfreefonts} script, and more. - -\item Petr Ol\v{s}ak, who coordinated and checked all the Czech and Slovak -material very carefully. - -\item Toshio Oshima, for his \cmdname{dviout} previewer for Windows. - -\item Fabrice Popineau, for the original Windows support in \TL{}. - -\item Norbert Preining, for helping with the \TL{} infrastructure and -package updates, and coordinating the Debian version of \TL{} (together -with Frank K\"uster), making many suggestions for improvement along the -way. - -\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 assembly and maintenance of Web2C, -upon which all else depends. - -\item Gerben Wierda, for creating and maintaining the \MacOSX\ support, -and much integration and testing. - -\item Graham Williams, on whose work the catalogue of packages depends. - -\end{itemize*} - -Builders of the binaries: -Tigran Aivazian and Hartmut Henkel (\pkgname{x86\_64-linux}), -Akira Kakuto and Fabrice Popineau (\pkgname{win32}), -Manfred Lotz (\pkgname{i386-freebsd}), -Norbert Preining (\pkgname{alpha-linux}), -Vladimir Volovich (\pkgname{powerpc-aix}, \pkgname{sparc-linux}, - \pkgname{sparc-solaris}), -Karl Berry (\pkgname{i386-linux}), -Olaf Weber (\pkgname{mips-irix}), -Gerben Wierda (\pkgname{i386-darwin}, \pkgname{powerpc-darwin}). - -Documentation and translation updates: -Karl Berry (English), -Daniel Flipo \& Fabrice Popineau (French), -G\"unter Partosch \& Hartmut Henkel (German), -Petr Sojka \& Jan Busa (Czech\slash Slovak), -Boris Veytsman (Russian), -Staszek Wawrykiewicz (Polish). - -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:multiple-dist}, \p.\pageref{sec:multiple-dist}). 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:struct-tl} (\p.\pageref{sec:struct-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-doc/doc/english/tds/tds.html\#Extensions} -{\texttt{texmf-doc/doc/english/tds/tds.html\#Extensions}}. - -\item Helper scripts (not meant to be invoked by users) are now located -in a new \dirname{scripts} directory of \dirname{texmf*} trees, and -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-doc/doc/english/tds/tds.html\#Scripts} -{\texttt{texmf-doc/doc/english/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/doc/pdftex/manual}. - - \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}. - See section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig}. - -\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} - - -\subsection{Present} -\label{tlcurrent} - -In 2006--2007, the major new addition to \TL{} was the Xe\TeX{} 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). - -The installation scripts now accept various environment variables to -allow for non-interactive installation; see -section~\ref{sec:noninteractive-install}. - -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 \acro{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. - - -\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 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. If you can help, don't hesitate to put -your name forward! - -Please send corrections, suggestions, and offers of help to:\hfill\null -\begin{quote} -\email{tex-live@tug.org} \\ -\url{http://tug.org/texlive} -\end{quote} - -\medskip -\noindent \textsl{Happy \TeX ing!} - -\end{document} |