diff options
author | Siep Kroonenberg <siepo@cybercomm.nl> | 2008-07-14 16:09:18 +0000 |
---|---|---|
committer | Siep Kroonenberg <siepo@cybercomm.nl> | 2008-07-14 16:09:18 +0000 |
commit | 12701de60c4b2659d3d0a0ce0245672808927c57 (patch) | |
tree | 602d67a84e4fa09987be55669edfadef5dfdb80e /Master/texmf-doc/source | |
parent | f99a10c1e4bda886c3bf828b87f8aeb1ca914ee2 (diff) |
texlive-en complete. source in 1 piece
git-svn-id: svn://tug.org/texlive/trunk@9547 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-doc/source')
13 files changed, 3000 insertions, 2763 deletions
diff --git a/Master/texmf-doc/source/texlive/texlive-common/w32client/install-w32client b/Master/texmf-doc/source/texlive/texlive-common/w32client/install-w32client new file mode 100755 index 00000000000..043a23a0a1a --- /dev/null +++ b/Master/texmf-doc/source/texlive/texlive-common/w32client/install-w32client @@ -0,0 +1,167 @@ +#!/usr/bin/env perl + +# copy this file and install-w32client.bat to the same directory +# as texmf, texmf-dist etc. + +# sample mini-installer to give Windows systems access to an +# existing TeXLive installation + +# it assumes a standard directory layout, which avoids hard-coded paths. +# if this is not the case, adjustments may be necessary. + +$^W = 1; + +use TeXLive::TLUtils qw(mkdirhier conv_to_win_path); +#use Cwd 'abs_path'; +use TeXLive::TLWinGoo qw(non_admin add_texbindir_to_path setenv_reg + init_unshortbat add_desktop_shortcut add_menu_shortcut + register_extension register_file_type + update_assocs broadcast_env + create_uninstaller); +use strict; + +# the code below assumes that this script is in $texdir, +# the directory above texmf, texmf-dist etc. + +my $texdir=$0; +$texdir=~s!\\!/!g; +$texdir=~s!(.*)/.*$!$1!; + +# private runtime-generated files +$::texlive_release = '2008'; +my $texdirw = $ENV{'USERPROFILE'}.'/.texlive'.$::texlive_release; +$texdirw=~s!\\!/!g; +my $private_var = $texdirw.'/texmf-var'; +my $private_var_bsl = $private_var; +$private_var_bsl =~ s!/!\\!g; + +# make only per-user modifications +non_admin(); + +# general + +add_texbindir_to_path($texdir.'/bin/win32'); +broadcast_env(); + +my $mainmenu = "TeX Live 2008"; +my $texbindir_bsl = $texdir.'/bin/win32'; +$texbindir_bsl =~ s!/!\\!g; + +mkdirhier("$texdirw/tlpkg/installer"); +create_uninstaller($texdir, $texdirw, $private_var, $texdirw.'/texmf-config'); +init_unshortbat($texdirw); + +# if the path can't be fixed globally add command prompt +# with texbindir prepended to path + +if (uc(TeXLive::TLWinGoo::win_which_dir('tex.exe')) ne + uc($texdir.'/bin/win32') or + uc(TeXLive::TLWinGoo::win_which_dir('pdftex.exe')) ne + uc($texdir.'/bin/win32') or + uc(TeXLive::TLWinGoo::win_which_dir('luatex.exe')) ne + uc($texdir.'/bin/win32')) { + add_menu_shortcut( + $mainmenu, + 'TeX Live Prompt', + '', + $ENV{'COMSPEC'}, + "/k \"path $texbindir_bsl;%path%\"", + '', + ); +} + +# texlive manual + +add_menu_shortcut( + $mainmenu, + 'TeX Live Manual (en)', + '', # default pdf icon + $texdir.'/texmf-doc/doc/english/texlive-en/live.pdf', + '', + '', +); + +# texdoctk documentation browser + +if (-e $texdir.'/bin/win32/texdoctk.bat') { + add_menu_shortcut( + $mainmenu, + 'TeXdoc GUI', + '', # icon + $texdir.'/bin/win32/texdoctk.bat', + '', # arguments + 'batgui', # any non-null value to hide command-prompt + ) +} + +# psview + +add_desktop_shortcut( + $texdirw, + 'PS_View', + $texdir.'/tlpkg/tlpsv/psv.exe', # icon, not prog! + $texdir.'/bin/win32/psv.bat', + '', # no args + 'batgui', # any non-null value to hide command-prompt +); +add_menu_shortcut( + $mainmenu, + 'PS_View', + $texdir.'/tlpkg/tlpsv/psv.exe', # icon, not prog! + $texdir.'/bin/win32/psv.bat', + '', # no args + 'batgui', # any non-null value to hide command-prompt +); +# comment out if you prefer gsview +register_extension(".ps", "PostScript"); +register_extension(".eps", "PostScript"); +register_file_type("PostScript", + '"'.$texdir.'/tlpkg/tlpsv/gswxlua.exe" -g '. + '"'.$texdir.'/tlpkg/tlgs/bin/gsdll32.dll" -l '. + '"'.$texdir.'/tlpkg/tlpsv/psv.wx.lua" -p '. + '"'.$texdir.'/tlpkg/tlpsv/psv_view.ps" -sINPUT="%1"'); +update_assocs(); + +# xetex + +if (-e $texdir.'/bin/win32/xetex.exe') { + my $xetexmfcnf = $private_var.'/web2c'; + my $texmfcnf = $xetexmfcnf.';'.$texdir.'/texmf/web2c'; + setenv_reg('TEXMFCNF', $texmfcnf); + broadcast_env(); + mkdirhier($private_var."/fonts"); + system("xcopy", "/e", "/i", "/q", "/y", "\"$texbindir_bsl\\conf\"", + "\"$private_var_bsl\\fonts\\conf\""); + system("xcopy", "/e", "/i", "/q", "/y", "\"$texbindir_bsl\\cache\"", + "\"$private_var_bsl\\fonts\\cache\""); + if (open(FONTSCONF, "<$texdir/bin/win32/conf/fonts.conf")) { + my @lines = <FONTSCONF>; + close(FONTSCONF); + if (open(FONTSCONF, ">$private_var/fonts/conf/fonts.conf")) { + my $winfontdir; + $winfontdir = $ENV{'SystemRoot'}.'/fonts'; + $winfontdir =~ s!\\!/!g; + foreach (@lines) { + $_ =~ s!c:/Program Files/texlive/2008!$texdir!; + $_ =~ s!c:/windows/fonts!$winfontdir!; + print FONTSCONF; + } + close(FONTSCONF); + } else { + warn("Cannot open $private_var/fonts/conf/fonts.conf for writing\n"); + } + } else { + warn ("Cannot open $texdir/bin/win32/conf/fonts.conf\n"); + } + mkdirhier($xetexmfcnf); + if (open(TMF, ">$xetexmfcnf/texmf.cnf")) { + print TMF "FONTCONFIG_PATH=\$TEXMFVAR/fonts/conf\n"; + print TMF "FC_CACHEDIR=\$TEXMFVAR/fonts/cache\n"; + close TMF; + } else { + warn("Cannot open $xetexmfcnf/texmf.cnf for writing\n"); + } + $ENV{'TEXMFCNF'} = $texmfcnf; + $ENV{'PATH'} = $texbindir_bsl.';'.$ENV{'PATH'}; + system("\"$texbindir_bsl\\fc-cache.exe\"", "-v", "-r"); +} diff --git a/Master/texmf-doc/source/texlive/texlive-common/w32client/install-w32client.bat b/Master/texmf-doc/source/texlive/texlive-common/w32client/install-w32client.bat new file mode 100755 index 00000000000..0d22ada6688 --- /dev/null +++ b/Master/texmf-doc/source/texlive/texlive-common/w32client/install-w32client.bat @@ -0,0 +1,28 @@ +@echo off
+
+rem copy this file and install-w32client to the same directory
+rem as texmf, texmf-dist etc.
+
+rem TeX Live Root; ends with backslash
+rem This may also work with UNC names
+
+set texdir=%~dp0
+set tldrive=%~d0
+
+%tldrive%
+cd %texdir%
+
+rem use provided Perl
+
+set PERL5SAVE=%PERL5LIB%
+set PERL5LIB=%texdir%tlpkg\tlperl\lib;%texdir%tlpkg
+"%texdir%tlpkg\tlperl\bin\perl" "%~dpn0" %*
+rem pause Done
+
+rem cleanup in case of start from command-line
+
+set PERL5LIB=%PERL5SAVE%
+set PERL5SAVE=
+set tldrive=
+set texdir=
+pause
\ No newline at end of file diff --git a/Master/texmf-doc/source/texlive/texlive-en/acknowledgements.tex b/Master/texmf-doc/source/texlive/texlive-en/acknowledgements.tex deleted file mode 100644 index 861126f1432..00000000000 --- a/Master/texmf-doc/source/texlive/texlive-en/acknowledgements.tex +++ /dev/null @@ -1,105 +0,0 @@ -\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}). -(For information on the build process, see -\filename{Build/source/README} in the repository.) - -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. - - diff --git a/Master/texmf-doc/source/texlive/texlive-en/installation.tex b/Master/texmf-doc/source/texlive/texlive-en/installation.tex deleted file mode 100644 index f27739a5857..00000000000 --- a/Master/texmf-doc/source/texlive/texlive-en/installation.tex +++ /dev/null @@ -1,770 +0,0 @@ -\section{Installation} -\label{sec:install} - -\subsection{Starting the installer} -\label{sec:inst_start} -First, get the \TL{} \DVD{} or the \TK{} \DVD{} or the net installer, -and locate the installer script: \filename{install-tl} for Unix, -\filename{install-tl.bat} for Windows: - -\begin{description} -\item [\TeX{} Collection \DVD:] go to its \dirname{texlive} - subdirectory. Under Windows, the installer will probably start - automatically when you insert the \DVD. -\item [Net installer:] Download from CTAN, under - \dirname{systems/texlive/tlnet}. You can choose between - \filename{install-tl.zip} which can be used under Unix and Windows - and \filename{install-unx.tar.gz} which is Unix-only (including - \MacOSX). After unpacking, \filename{install-tl} and - \filename{install-tl.bat} will be in the \dirname{install-tl} - subdirectory. -\item [Downloadable \TeX{} Live \ISO{} image:] Download from CTAN, - under \dirname{systems/texlive/Images}. Since even the compressed - image is about 1 GB in size, you should not use this option - without good reason. Under most Unices, including Linux and - \MacOSX, you can mount the image directly. Otherwise, burn the - image to a physical \DVD\ and mount it. The installer scripts - \filename{install-tl} and \filename{install-tl.bat} will be in the - root. Under Windows, the installer will probably start - automatically when you insert the \DVD. -\end{description} - -\subsubsection{Unix/Linux} - -\begin{figure}[tb] -\begin{boxedverbatim} -======================> TeX Live installation procedure <===================== - -=======> Note: Letters/digits in <angle brackets> indicate menu items <======= -=======> for commands or configurable options <======= - - - Detected platform: Intel x86 with GNU/Linux - - <B> binary systems: 1 out of 16 - - <S> Installation scheme (scheme-full) - - Customizing installation scheme: - <C> standard collections - <L> language collections - 83 collections out of 84, disk space required: 1666 MB - - <D> directories: - TEXDIR (the main TeX directory): - !! default location: /usr/local/texlive/2008 - !! is not writable, please select a different one! - TEXMFLOCAL (directory for site-wide local files): - /usr/local/texlive/texmf-local - TEXMFSYSVAR (directory for variable and automatically generated data): - /usr/local/texlive/2008/texmf-var - TEXMFSYSCONFIG (directory for local config): - /usr/local/texlive/2008/texmf-config - TEXMFHOME (directory for user-specific files): - ~/texmf - - <O> options: - [ ] use letter size instead of A4 by default - [X] create all format files - [X] install macro/font doc tree - [X] install macro/font source tree - [ ] create symlinks in standard directories - - <V> Install for running from DVD - -Other actions: - <I> start installation to HD - <H> help - <Q> quit - -Enter command: -\end{boxedverbatim} -\caption{Main text installer screen (Linux)}\label{fig:text_main} -\end{figure} - -\begin{figure}[tb] -\tlpng{install-w32-main}{\linewidth} -\caption{Main \GUI{} installer screen (Windows)}\label{fig:gui_main} -\end{figure} - -\noindent -Below, \texttt{>} denotes the shell prompt; user input is -\Ucom{\texttt{bold}}. -Starting under Unix/Linux from an xterm or other terminal: - -\begin{alltt} -> \Ucom{./install-tl} -\end{alltt} -or -\begin{alltt} -> \Ucom{perl install-tl} -\end{alltt} -if you are in the installer directory, otherwise -\begin{alltt} -> \Ucom{<path_to_installer>/install-tl} -\end{alltt} -For \GUI\ mode, use -\begin{alltt} -> \Ucom{./install-tl -gui} -\end{alltt} -For a complete listing of the various options: -\begin{alltt} -> \Ucom{./install-tl -help} -\end{alltt} - -\textbf{Warning.} Your \code{umask} at the time of installation will -be respected by the \TL{} installer. Therefore, if you want your -installation to be usable by users other than you, make sure your -setting is sufficiently permissive, for instance, \code{umask 002}. -For more information about \code{umask}, consult your system -documentation. - -\subsubsection{Windows} - -As already noted, the \DVD\ installer will probably start -automatically when you put the \DVD\ in the \DVD-drive. If not, or -if you use the net installer, you can double-click \filename{install-tl.bat}. - -You can also start the installer from the command-prompt: -Below, \texttt{>} denotes the prompt; user input is -\Ucom{\texttt{bold}}. - -\begin{alltt} -> \Ucom{install-tl} -\end{alltt} -if you are in the installer directory, otherwise -\begin{alltt} -> \Ucom{D:\bs{}install-tl} -\end{alltt} -for the downloadable \ISO, if \texttt{D:} is the optical drive, or -\begin{alltt} -> \Ucom{D:\bs{}texlive\bs{}install-tl} -\end{alltt} -for the \TK\ \DVD. For text mode, use -\begin{alltt} -> \Ucom{install-tl -no-gui} -\end{alltt} -For a complete listing of the various options: -\begin{alltt} -> \Ucom{install-tl -help} -\end{alltt} - -\subsubsection{The text installer} - -Figure~\ref{fig:text_main} displays the main text mode screen under -Unix/Linux: - -You cannot tab around checkboxes or input fields. You just have to -type something at the prompt and press the Enter key, and then the -entire terminal screen will be rewritten, with adjusted content. - -The text installer interface is this primitive for a reason: it -is designed to run on as many platforms as possible, even with a -very barebones Perl (for Windows, a Perl subset is included). - -\subsubsection{The graphical installer} - -Figure~\ref{fig:gui_main} displays the graphical installer under Windows. - -Most differences in available options are due to -this screenshot being from Windows, and the text screen above being -from Linux. - -\subsection{Running the installer} -\label{sec:runinstall} - -The installer is mostly self-explanatory. Still, a few quick notes -about the various options and submenus: - -\subsubsection{Binary systems menu (Unix/Linux only)} -\label{sec:binary} - -\begin{figure}[tbh] -\begin{boxedverbatim} -Available sets of binaries: -=============================================================================== - - a [ ] alpha-linux: DEC Alpha with GNU/Linux - b [ ] amd64-freebsd: x86_64 with FreeBSD - c [ ] hppa-hpux: HP-UX - d [ ] i386-freebsd: Intel x86 with FreeBSD - e [X] i386-linux: Intel x86 with GNU/Linux - f [ ] i386-openbsd: Intel x86 with OpenBSD - g [ ] i386-solaris: Intel x86 with Sun Solaris - h [ ] mips-irix: SGI IRIX - i [ ] powerpc-aix: PowerPC with AIX - j [ ] powerpc-linux: PowerPC with GNU/Linux - k [ ] sparc-linux: Sparc with GNU/Linux - l [ ] sparc-solaris: Sparc with Solaris - m [ ] universal-darwin: universal binaries for MacOSX/Darwin - o [ ] win32: Windows - p [ ] x86_64-linux: x86_64 with GNU/Linux -\end{boxedverbatim} -\caption{Binaries menu}\label{fig:bin_text} -\end{figure} - -Figure~\ref{fig:bin_text} displays the text mode binaries menu. By -default, only the binaries for your current platform will be -installed. From this menu, you can select installation of binaries -for other architectures as well. This can be useful if you are -sharing a \TeX\ tree across a network of heterogenous machines, or -for a dual-boot system. - -\subsubsection{Selecting what is going to be installed} -\label{sec:components} - -From the scheme menu, see figure~\ref{fig:text_scheme}, you can -choose an overall set of package collections. The default -\optname{full} scheme installs everything available, but you can -also choose the \optname{basic} scheme for a minimal system, or -\optname{medium} or \optname{teTeX} to get something in between. -There are also various specialized and country-specific schemes. - -\begin{figure}[tbh] -\begin{boxedverbatim} -Select a scheme: -=============================================================================== - - a [ ] TeX Live basic scheme - b [ ] TeX Live scheme for ConTeXt - c [X] TeX Live full scheme - d [ ] GUST TeX Live scheme - e [ ] GUTenberg TeX Live scheme - f [ ] TeX Live medium scheme - g [ ] TeX Live minimal scheme - h [ ] TeX Live for Omega users - i [ ] teTeX scheme - j [ ] XML typesetting scheme -\end{boxedverbatim} -\caption{Scheme menu}\label{fig:text_scheme} -\end{figure} - -\begin{figure}[tbh] -\tlpng{stdcoll}{.7\linewidth} -\caption{Collections menu (Linux)}\label{fig:gui_collections} -\end{figure} - -You can refine your selection with the `standard collections' and -`language collections' menus. 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 these -submenus, selection letters are case-sensitive\Dash unless you run -the gui installer, where you can simply click checkboxes; see -figure~\ref{fig:gui_collections}. - -If you want more detail, you need run the \prog{tlmgr} program -afterwards, see section~\ref{sec:tlmgr}. The installer will take -care of appropriate configuration of format generation, hyphenation -patterns and font-related matters. - -\subsubsection{Directories} -\label{sec:directories} - -The default layout is described in section~\ref{sec:texmftrees}, -\p.\pageref{sec:texmftrees}. The default location of -\dirname{TEXDIR} is different for Windows -(|%PROGRAMFILES%\texlive\2008|) and for Unix/Linux -(\dirname{/usr/local/texlive/2008})\footnote{It is possible to - override these defaults beforehand with environment variables; - search the file \filename{install-tl} for - \texttt{TEXLIVE\_INSTALL\_}. However, if you want to automate - installations then a far better option is to use profiles; see - section~\ref{sec:cmdline} under \optname{-profile}.}. - -The main reason for changing the proposed directory structure is -lack of write permissions for the default location. You don't have -to be root or adminstrator to install \TL, but you do need write -access to the target directory. - -A logical alternate choice is a directory under your home directory, -especially if you will be the sole user. Type -`|~|' to indicate this, \emph{e.g.}: `|~/texlive/2008|'. - -We recommend including the year in the name, to enable keeping -different releases of \TL{} side by side. (You may wish to make a -version-independent name such \dirname{/usr/local/texlive-cur} via a -symbolic link, which you can then update after testing the new -release.) - -Changing \dirname{TEXDIR} will also change \dirname{TEXMFLOCAL}, -\dirname{TEXMFSYSVAR} and \dirname{TEXMFSYSCONFIG}. - -\dirname{TEXMFHOME} is the recommended location for personal -macro files or packages. The default value is |~/texmf|. In -contrast to \dirname{TEXDIR}, here a |~| is preserved in the -newly-written configuration files, since it usefully refers to the home -directory of each individual running \TeX. It expands to -\dirname{$HOME} on Unix and \verb|%USERPROFILE%| on Windows. - -\subsubsection{Options} -\label{sec:options} - -\begin{figure}[tbh] -\begin{boxedverbatim} -<P> use letter size instead of A4 by default: [ ] -<F> create all format files: [X] -<D> install font/macro doc tree: [X] -<S> install font/macro source tree: [X] -<L> create symlinks in standard directories: [ ] - binaries to: - manpages to: - info to: -\end{boxedverbatim} -\caption{Options menu (Linux)}\label{fig:text_options} -\end{figure} - -Figure~\ref{fig:text_options} displays the text mode options menu. -Three options require some explanation: -\begin{description} -\item[create all format files:] Although unnecessary format files - take time to generate and disk space to store, it is still - recommended to check this option: if you don't, then format files - will be generated in people's private \dirname{TEXMFVAR} tree, and - won't be updated automatically if binaries or hyphenation patterns - etc. are updated, and they may end up with incompatible format - files. -\item[install font/macro source tree:] These are mostly - \LaTeX{} \filename{.dtx} files, from which both \filename{.sty} files - and documentation are generated. It is ok to uncheck this. -\item[create symlinks in standard directories] (Unix/Linux only): - this option bypasses the need to change environment - variables. Without this option, \TL{} directories have to be added - to \envname{PATH}, \envname{MANPATH} and \envname{INFOPATH}. You will - need write permissions to the target directories. It is not - advisable to overwrite a \TeX\ system that came with your system - with this option. It is 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. -\end{description} - -Now when all these settings are to your liking, you can type `I' to -start the installation process. When it is done, skip to -section~\ref{sec:postinstall} to read what else needs to be done, if -anything. - -\subsubsection{Set up for running from \DVD{} (text mode only)} -\label{sec:fromdvd} - -Typing `V' to select this option. This changes the main menu into something -like figure~\ref{fig:main_fromdvd}. -\begin{figure}[tbh] -\begin{boxedverbatim} -======================> TeX Live installation procedure <===================== - -=======> Note: Letters/digits in <angle brackets> indicate menu items <======= -=======> for commands or configurable options <======= - - <D> directories: - TEXDIRW (Writable root): - !! default location: /usr/local/texlive/2008 - !! is not writable, please select a different one! - TEXMFLOCAL (directory for site-wide local files): - /usr/local/texlive/texmf-local - TEXMFSYSVAR (directory for variable and automatically generated data): - /usr/local/texlive/2008/texmf-var - TEXMFSYSCONFIG (directory for local config): - /usr/local/texlive/2008/texmf-config - TEXMFHOME (directory for user-specific files): - ~/texmf - - <O> options: - [ ] use letter size instead of A4 by default - [X] create all format files - - <V> set up for installing to hard disk - -Other actions: - <I> start installation for running from DVD - <H> help - <Q> quit -\end{boxedverbatim} -\caption{The main menu with \optname{from DVD} - set}\label{fig:main_fromdvd} -\end{figure} - -Note the changes: all options about what to install have -disappeared, and the directories section now talks about -\dirname{TEXDIRW} or writable root. The symlinks option has also -disappeared. - -The installer will still create various directories and -configuration files, but won't copy \dirname{texmf}, -\dirname{texmf-dist} or \dirname{texmf-doc} to harddisk. - -Post-install configuration for Unix/Linux will be slightly more -complicated, see section~\ref{sec:postinstall}, because now the -directory layout deviates from the default. - -Due to time constraints, this option didn't make it into the \GUI{} -installer, but it is available both for Unix/Linux and for -Windows. Windows users have to start the installer from a command -prompt, see section~\ref{sec:cmdline}. - -Section \ref{sec:portable-unix} describes a more strictly portable -way to run \TL, which doesn't make or require changes in the -system's configuration, but doesn't allow any configuration either. - -\subsection{Command-line install options} -\label{sec:cmdline} - -Type -\begin{alltt} -> \Ucom{install-tl -help} -\end{alltt} -for a listing of command-line options. These are the more -interesting ones: - -\begin{ttdescription} -\item[-gui] If possible, use the \GUI{} installer. This requires the - Perl/Tk module (\url{http://tug.org/texlive/distro.html#perltk}); - if Perl/Tk is not available, installation continues in text mode. -\item[-no-gui] Force using the text mode installer, even under - Windows, \emph{e.g.} because you want a `from \DVD' installation, - which is not available in \GUI{} mode. -\item[-lang \textit{2-letter code}] Specify the installer interface - language. Currently supported languages: English (\texttt{en}, - default), German (\texttt{de}), French (\texttt{fr}), Dutch - (\texttt{nl}), Polish (\texttt{pl}) and Slovenian - (\texttt{sl}). The installer tries to determine the right language - itself but if it fails, or if the right language is not available, - then it uses English as a fallback. -\item[-profile \textit{profile}] The installer writes a file - \filename{texlive.profile} to the \dirname{2008/tlpkg}- or - \dirname{tlpkg} subdirectory of your installation. An - example profile: - \begin{fverbatim} -# texlive.profile written on Wed Jul 9 16:13:44 2008 UTC -# it will NOT be overwritten and reflects only the -# installation profile at installation time -selected_scheme scheme-basic -TEXDIR /usr/local/texlive/2008 -TEXDIRW /usr/local/texlive/2008 -TEXDIRW /usr/local/texlive/2008 -TEXMFHOME ~/texmf -TEXMFLOCAL /usr/local/texlive/texmf-local -TEXMFSYSCONFIG /usr/local/texlive/2008/texmf-config -TEXMFSYSVAR /usr/local/texlive/2008/texmf-var -collection-basic 1 -collection-latex 1 -option_doc 0 -option_fmt 0 -option_letter 0 -option_src 0 -option_symlinks 0 - \end{fverbatim} - With a copy of this file, you can install in batchmode on - subsequent systems, reproducing the choices you made for the - original installation. -\item [-location \textit{url/path}] Specify a non-default source for - packages; see below. -\end{ttdescription} - -\subsubsection{The \optname{location} parameter} -\label{sec:location} - -The argument can be an \texttt{ftp:} or \texttt{http:} url, but also -a local \texttt{file:/} url, and even a plain path. If the given -argument is on a local drive (either a path or a \texttt{file:/} -url), the installation type (compressed or live) is automatically -determined: if an \dirname{archive} subdirectory with -\filename{.tar.lzma} files is found then it will be used, even if -uncompressed files are available as well. - -When giving an \texttt{http:} or \texttt{ftp:} location, -trailing `\texttt{/}' characters and/or a trailing `\texttt{/tlpkg}' -component are ignored. For example, you could choose a particular -CTAN mirror with something like: -\url{http://ctan.example.org/tex-archive/texlive/tlnet/2008}, -substituting of course a proper hostname and its particular top-level -CTAN path (the list of CTAN mirrors is maintained at -\url{http://ctan.org/mirrors}). The default is to pick a mirror -automatically, using \url{http://mirror.ctan.org}; one mirror is -used for the entire download. - - -\subsection{Post-install actions} -\label{sec:postinstall} - -Some post-install may be required. - -\subsubsection{Windows} - -For Windows, the installer takes care of everything. - -\subsubsection{If symlinks were created} - -If you elected to create symlinks in standard directories then there -is no need to edit environment variables. - -\subsubsection{Environment variables for Unix/Linux} -\label{sec:env} - -The directory of the binaries for your platform should be added to -the searchpath. Each supported platform has its own subdirectory -under \dirname{TEXDIR/bin}. See figure~\ref{fig:bin_text} for the -list of subdirectories and corresponding platforms. - -You might as well also add the \TeX{} info- and manpage directories -to their respective searchpaths. A couple of examples: - -For Bash or another Bourne-compatible shell and Intel x86 -GNU/Linux and a default directory setup, the file to edit might be -\filename{$HOME/.profile} or \filename{$HOME/.bash_profile}, and the lines -to add might look like - -\begin{sverbatim} -PATH=/usr/local/texlive/2008/bin/i386-linux:$PATH -export PATH -MANPATH=/usr/local/texlive/2008/texmf/doc/man:$MANPATH -export MANPATH -INFOPATH=/usr/local/texlive/2008/texmf/doc/info:$INFOPATH -export INFOPATH -\end{sverbatim} - -For csh or tcsh, the file to edit might be \filename{$HOME/.cshrc} and -the lines to add might look like: - -\begin{sverbatim} -setenv PATH /usr/local/texlive/2008/bin/i386-freebsd:$PATH -setenv MANPATH /usr/local/texlive/2008/texmf/doc/man:$MANPATH -setenv INFOPATH /usr/local/texlive/2008/texmf/doc/info:$INFOPATH -\end{sverbatim} - -\subsubsection{Environment variables: global configuration} -\label{sec:envglobal} - -If you want to make these changes globally, or at least for a -default new user, then you are on your own; there is just too much -variation between systems in how and where these things are -configured. You may also want to check for a file -\filename{/etc/manpath.config} and, if present, add lines such as - -\begin{sverbatim} -MANPATH_MAP /usr/local/texlive/2008/bin/i386-linux \ - /usr/local/texlive/2008/texmf/doc/man -\end{sverbatim} - -Check also for a file \filename{/etc/environment} which may define -the searchpath and some other default environment variables. - -\subsubsection{When running from DVD} - -Normally, a \TL{} program consults a file \filename{texmf.cnf} for -the location of the various trees. It looks for this file in a -series of locations relative to its own location. However, this -scheme breaks down when the program in on the \DVD{}: the \DVD{} is -read-only, but some of the paths to be recorded in -\filename{texmf.cnf} are only known at installation time. The fix is -to define an environment \envname{TEXMFCNF} variable which tells -\TL{} programs in what directory to find this \filename{texmf.cnf}. - -At the end of the installation, the installer should have printed a -message to what value \envname{TEXMFCNF} should be set. In -case you missed it: this value is \dirname{$TEXMFSYSVAR/web2c}. The -default for this is -\dirname{/usr/local/texlive/2008/texmf-var/web2c}. -\begin{sverbatim} -TEXMFCNF=/usr/local/texlive/2008/texmf-var/web2c -export TEXMFCNF -\end{sverbatim} -or, for [t]csh: -\begin{sverbatim} -setenv TEXMFCNF /usr/local/texlive/2008/texmf-var/web2c -\end{sverbatim} - -\subsubsection{\ConTeXt{} Mark IV} - -The `old' \ConTeXt{} should run out of the box. The new `Mark IV' -\ConTeXt{} will require manual setup; see -\url{http://wiki.contextgarden.net/Running_Mark_IV} - -\subsubsection{Integrating local and personal macros} - -This is already mentioned implicitly in -section~\ref{sec:texmftrees}: \dirname{TEXMFLOCAL}, \emph{e.g.} -\dirname{/usr/local/texlive/texmf-local} or -\verb|C:\Program Files\texlive\texmf-local| is intended for local -fonts and macros; \dirname{TEXMFHOME}, usually \dirname{$HOME/texmf} -or \verb|%USERPROFILE%\texmf|, are for -personal fonts and macros. These directories should stick around -from release to release. Their content will be automatically seen by -a new \TL{} release. - -\subsubsection{Integrating third-party fonts} - -This is unfortunately a very complicated and messy topic. Forget -about it unless you really know your way around blindfolded in a -\TeX{} installation. Don't forget to check first what you get for -free: see section~\ref{sec:tl-fonts}. - -An alternative is using Xe\TeX, -see section~\ref{sec:tex-extensions}, which lets you use operating -system fonts without installation in \TeX. - - -\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{sec:env}. - -\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{Network installations} -\label{sec:netinstall} - -\TL{} has been designed to be shared between different users, and -even different systems on a network. With a standard directory -layout, no hard paths are configured: the locations for files needed -by \TL{} programs are defined relative to the places of those -programs. This is true even if \dirname{$TEXMFLOCAL} is on the same -level as the other trees instead of one level higher. You can see -this at work in the configuration file -\filename{$TEXMFMAIN/web2c/texmf.cnf}, which contains lines such as -\begin{sverbatim} -TEXMFMAIN = $SELFAUTOPARENT/texmf -... -TEXMFLOCAL = $SELFAUTOPARENT../texmf-local -\end{sverbatim} -This means that other systems or other users merely need to add the -directory for \TL{} binaries for their platform to their searchpath. - -By the same token, you can also install \TL{} locally and then move -the entire hierarchy afterwards to a network location. - -Of course, Windows users have different expectations. The script -\filename{install-w32client} is a sample script which creates -registry entries and menu shortcuts for using an existing \TL{} -installation. - -You can read more about \TL{} configuration and path searching in -section~\ref{sec:kpathsea}. - -\section{Really portable \protect\TL{} on DVD and USB} -\label{sec:portable-unix} - -The `running from \DVD{}' option described in -section~\ref{sec:fromdvd} is fine for your own system, but if you -are a guest on somebody else's system then you might prefer -something with minimal side-effects. - -In the root of the \TL{} \DVD, or the \dirname{texlive} subdirectory -of the \TK{} \DVD, are a \filename{tl-portable} script (Unix/Linux) -and a \filename{tl-portable.bat} batchfile (Windows) which start up -a secondary shell/command prompt with environment settings suitable -for accessing the \TL{} on the \DVD. - -When it runs for the first time, some files will be generated in a -directory \dirname{~/.tlportable2008}. On subsequent runs, though, it -will start almost instantaneously. - -The rest of the system will be unaware of \TL. If you want your -editor to be aware of this \TL, then you can start it from -a second, parallel such \TL{} session. - -You can also use \filename{tl-portable} to run \TL{} on a -\acro{USB} stick. In this case, copy all the top-level files and -the contents of the \dirname{bin}, \dirname{texmf}, -\dirname{texmf-dist}, and \dirname{tlpkg} directories (at least) to -the stick. This may take quite a while! If you are copying to a -\acro{FAT32}-formatted \acro{USB} stick, make sure to dereference -symbolic links (\code{cp -L}). A \dirname{texmf-local} directory on -the stick will also be found and used. - -Then run \filename{tl-portable} from the root of the stick, as -above. In this case, the script will notice that the stick is -writable and use it for generated files. You could probably burn -the resulting contents of the stick back to \DVD{} if that is more -convenient to (for example) give to others. - - -% diff --git a/Master/texmf-doc/source/texlive/texlive-en/intro.tex b/Master/texmf-doc/source/texlive/texlive-en/intro.tex deleted file mode 100644 index c4d1474b5fd..00000000000 --- a/Master/texmf-doc/source/texlive/texlive-en/intro.tex +++ /dev/null @@ -1,137 +0,0 @@ -\section{Introduction} -\label{sec:intro} - -\subsection{\TeX\ Live and the \TeX\ Collection} - -This document describes the main features of the \TL{} software -distribution\Dash \TeX{} and related programs for \acro{GNU}/Linux -and other Unix flavors, \MacOSX, and Windows systems. - -You may have acquired \TL{} by downloading, or on the \TK{} \DVD, -which \TeX{} usergroups distribute among their members. Section -\ref{sec:tl-coll-dists} briefly describes the contents of this \DVD. -Both \TL{} and the \TK{} are cooperative efforts by the \TeX{} user -groups. This document mainly describes \TL{} itself. - -\TL{} includes executables for \TeX{}, \LaTeXe{}, \ConTeXt, -\MF, \MP, \BibTeX{} and many other programs; an extensive collection -of macros, fonts and documentation; and support for typesetting in -many different scripts from around the world. - -\TL{} packages are regularly updated from -\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{Operating system support} -\label{sec:os_support} - -\TL{} contains binaries for many Linux- and Unix architectures, -including \MacOSX. The included sources should enable installation -on additional Linux- and Unix platforms. - -As to Windows: only Windows 2000 and later are supported. Windows -9\textit{x}, ME and NT have been dropped. Because of this -restriction, Windows requires less special treatment compared to -Linux and Unix. There are no 64-bit executables for Windows, but the -32-bit executables should run on 64-bit systems. - -See section~\ref{sec:tl-coll-dists} for alternate solutions -for Windows and \MacOSX. - -\subsection{Basic usage of \protect\TL{}} -\label{sec:basic} - -You can install \TL{} either from \DVD{} or over the internet. The -net installer itself is very small and downloads everything needed -from the internet. The net installer is an attractive option if you -need only a fraction of the complete \TL. - -The \DVD{} installer lets you install to a local disk, but you can -also run \TL{} directly from the \DVD{} (or from a \DVD{} image, if -your system supports that). - -\noindent This is described in the -installation sections following, but here is a quick start: - -\begin{itemize*} - -\item The installation script is \filename{install-tl}, which has -both a text mode (default for Unix) and a \GUI{} mode (default for -Windows). - -\item One of the installed items is \prog{tlmgr} or \TL\ Manager, - which can also be used in \GUI{} mode and in text mode. You can - use it to install and uninstall packages and do various - configuration tasks. - -\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{}! - - diff --git a/Master/texmf-doc/source/texlive/texlive-en/macosx.tex b/Master/texmf-doc/source/texlive/texlive-en/macosx.tex deleted file mode 100644 index 971416be757..00000000000 --- a/Master/texmf-doc/source/texlive/texlive-en/macosx.tex +++ /dev/null @@ -1,25 +0,0 @@ -\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:install} on -\p.\pageref{sec:install}; \MacOSX-specific notes are included there -where needed. - diff --git a/Master/texmf-doc/source/texlive/texlive-en/maintenance.tex b/Master/texmf-doc/source/texlive/texlive-en/maintenance.tex deleted file mode 100644 index f9218a47d26..00000000000 --- a/Master/texmf-doc/source/texlive/texlive-en/maintenance.tex +++ /dev/null @@ -1,133 +0,0 @@ -\section{Managing your installation} -\label{sec:tlmgr} - -\begin{figure}[tb] -\tlpng{tlmgr-gui}{\linewidth} -\caption{\texttt{tlmgr} in GUI mode. The list of - packages/collections/schemes only shows up after clicking the - `Load' button.}\label{fig:tlmgr-gui} -\end{figure} - -\begin{figure}[tb] -\tlpng{tlmgr-config}{\linewidth} -\caption{\texttt{tlmgr} in GUI mode: Configuration tab}\label{fig:tlmgr-config} -\end{figure} - -The installer installs a program \prog{tlmgr} for managing the -installation\footnote{\texttt{updmap}, \texttt{fmtutil} and - \texttt{texconfig} are still included, but \texttt{tlmgr} is now - the preferred interface. Don't use the other, more low-level tools - unless you know what you are doing.}. Its capabilities include: -\begin{itemize} -\item listing schemes, collections and packages -\item installing, updating, backing up, restoring and uninstalling - individual packages, optionally taking dependencies into account -\item searching the package database -\item listing and adding architectures -\item changing installation options such as paper size, location - (see section~\ref{sec:location}) and format generation -\end{itemize} -\textit{Warning.} \prog{tlmgr} has not been designed for or tested -with installations which run from \DVD. - -\subsection{\texttt{tlmgr GUI mode}} -\prog{tlmgr} can be started in \GUI{} mode with -\begin{alltt} -> \Ucom{tlmgr -gui} -\end{alltt} -or in Windows via the Start menu: Start, Programs, TeX Live 2008, -TeX Live Manager. After clicking `Load' it displays a list of -available and installed packages\Dash the latter prepended with -`(i)'. This assumes of course that the installation source is valid -and reachable. - -Figure~\ref{fig:tlmgr-config} shows the configuration tab. - -\subsection{Sample command-line invocations} -Installing several packages, including a new `engine', from a -non-default location: -\begin{alltt} -> \Ucom{tlmgr -location http://172.16.18.1/tldev install collection-xetex xkeyval} -\end{alltt} -generates the following output: - -\begin{fverbatim} -install: collection-xetex -install: arabxetex -install: euenc -install: bidi -install: fontspec -install: fontwrap -install: ifxetex -install: philokalia -install: polyglossia -install: xecyr -install: xecyr.i386-linux -install: xepersian -install: xetex -install: xetexconfig -install: xetex.i386-linux -running post install action for xetex -install: xetex-def -install: xetex-pstricks -install: xetexfontinfo -install: xltxtra -install: xunicode -install: xkeyval -running mktexlsr -mktexlsr: Updating /usr/local/texlive/2008/texmf/ls-R... -mktexlsr: Updating /usr/local/texlive/2008/texmf-config/ls-R... -mktexlsr: Updating /usr/local/texlive/2008/texmf-dist/ls-R... -mktexlsr: Updating /usr/local/texlive/2008/texmf-doc/ls-R... -mktexlsr: Updating /usr/local/texlive/2008/../texmf-local/ls-R... -mktexlsr: Updating /usr/local/texlive/2008/texmf-var/ls-R... -mktexlsr: Done. -regenerating fmtutil.cnf -running fmtutil-sys --missing -... -Transcript written on xelatex.log. -fmtutil: /usr/local/texlive/2008/texmf-var/web2c/xetex/xelatex.fmt installed. -\end{fverbatim} -As you see, \prog{tlmgr} takes care of any necessary -post-install actions, including updating the filename database and -generating formats. - -\noindent -Installing a language also triggers format generation: -\begin{alltt} -> \Ucom{tlmgr install collection-langdutch} -\end{alltt} -Printing some information about a package: -\begin{alltt} -C:\bs Documents and Settings\bs siepo> \Ucom{tlmgr show collection-wintools} -\end{alltt} -produces -\begin{fverbatim} -Package: collection-wintools -Category: Collection -ShortDesc: Windows support programs -LongDesc: Utilities for Windows, since they are not readily available there: - gzip, chktex, jpeg2ps, unzip, wget, xpdf. -Installed: Yes -\end{fverbatim} -Updating your entire installation: -\begin{alltt} -> \Ucom{tlmgr update -all} -\end{alltt} -If this makes you nervous, first type -\begin{alltt} -> \Ucom{tlmgr update -all -dry-run} -\end{alltt} -or -\begin{alltt} -> \Ucom{tlmgr update -list} -\end{alltt} -For full documentation, type -\begin{alltt} -> \Ucom{tlmgr -help} -\end{alltt} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "live" -%%% End: diff --git a/Master/texmf-doc/source/texlive/texlive-en/overview.tex b/Master/texmf-doc/source/texlive/texlive-en/overview.tex deleted file mode 100644 index 9c99f717c87..00000000000 --- a/Master/texmf-doc/source/texlive/texlive-en/overview.tex +++ /dev/null @@ -1,281 +0,0 @@ - -% don't use \TL so the \uppercase in the headline works. Also so -% tex4ht ends up with the right TeX. Likewise the \protect's. -\section{Overview of \protect\TeX\protect\ Live} -\label{sec:overview-tl} - -This section describes the structure and contents of \TL{} and the -\TK{} of which it is a part. - -\subsection{The \protect\TeX\protect\ Collection: \protect\pkgname{live}, - \protect\pkgname{protext}, - \protect\pkgname{Mac\TeX}} -\label{sec:tl-coll-dists} - -The \TK{} \DVD{} comprises the following: - -\begin{description} - -\item [live] A complete \TeX{} system which can be run live or - installed to disk. It is too large for \acro{CD}. - -\item [CTAN] A snapshot of the \CTAN{} repository - -\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}. - -\item [Mac\TeX] for \MacOSX is independent of but based on \TL{}. - -\item [\texttt{texmf-extra}] A directory with assorted additional packages. - -\end{description} - -\CTAN{}, \pkgname{protext}, Mac\TeX, and \dirname{texmf-extra} do not follow -the same copying conditions as \TL{}, so be careful when redistributing or -modifying. - -\noindent You can tell which type of distribution you're in by -looking for a \filename{release-texlive.txt} 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{texlive}, not at the top -level of the disc. - -%\smallskip -%\begingroup -% \renewcommand{\arraystretch}{1.3} % open up interrow spacing -%\begin{tabular}{>{\ttfamily}lp{.78\hsize}} -\begin{ttdescription} -\item[bin] The \TeX{} system programs, arranged by platform. -% -\item[readme.html] Readme html pages in various languages, with a quick -introduction and useful links -% -\item[source] The source of all programs, including the main \Webc{} - \TeX{} and \MF{} distributions. These are stored in -various compressed archives. -% -\item[support] Various auxiliary packages and programs. These are - \emph{not} installed automatically. This includes - assorted editors and \TeX\ shells. -% -\item[texmf] See \dirname{TEXMFMAIN} below. -% -\item[texmf-dist] See \dirname{TEXMFDIST} below. -% -\item[texmf-doc] Tree for self-contained pure documentation, arranged by - language. -% -\item[tlpkg] Scripts, programs and data for managing the - installation. It also contains private copies of - Perl and Ghostscript for Windows, which are invisible outside \TL, - and a new Windows PostScript viewer PSView. -\end{ttdescription} -%\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 documentation which does -not belong to any particular package or program. The documentation -for the programs (manuals, man pages, Info files) is in -\dirname{texmf/doc}. The documentation for \TeX\ packages and -formats is in \dirname{texmf-dist/doc}. You can use the -\cmdname{texdoc} or \cmdname{texdoctk} programs to find any -documentation wherever it is 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, and the default -layout of a \TL{} system. 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+) and other - support files and their documentation. Does not include - \TeX\ formats and packages. -\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} - -\noindent -The default layout is: -\begin{description} - \item[system-wide root] can span multiple \TL{} releases - \begin{ttdescription} - \item[2007] A previous release - \begin{ttdescription} - \item [] ... - \end{ttdescription} - \item[2008] the current release - \begin{ttdescription} - \item [bin] ~ - \begin{ttdescription} - \item [i386-linux] Linux binaries - \item [...] ... - \item [universal-darwin] \MacOSX binaries - \item [win32] Windows binaries - \end{ttdescription} - \item [TEXMFMAIN] \textit{i.e.} \dirname{texmf} - \item [TEXMFDIST] \textit{i.e.} \dirname{texmf-dist} - \item [TEXMFDOC] \textit{i.e.} \dirname{texmf-doc} - \item [TEXMFSYSVAR] \textit{i.e.} \dirname{texmf-var} - \item [TEXMFSYSCONFIG] \textit{i.e.} \dirname{texmf-config} - \end{ttdescription} - \item [TEXMFLOCAL] \textit{i.e.} \dirname{texmf-local}, can be - retained from release to release - \end{ttdescription} - \item[user's home] \textit{i.e.} \texttt{\$HOME} or - \texttt{\%USERPROFILE\%} - \begin{ttdescription} - \item[.texlive2007] Private generated and configuration data - for a previous release - \begin{ttdescription} - \item [] ... - \end{ttdescription} - \item[.texlive2008] Private generated and configuration data - for the current release - \begin{ttdescription} - \item [TEXMFVAR] \textit{i.e.} \dirname{texmf-var} - \item [TEXMFCONFIG] \textit{i.e.} \dirname{texmf-config} - \end{ttdescription} - \item[TEXMFHOME] \textit{i.e.} \dirname{texmf} Private macros - \textit{etc.} - \end{ttdescription} -\end{description} - -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} - -\TeX{} itself is frozen, apart from rare bug fixes. It is still -present in \TL, and will remain so in the foreseeable future. \TL{} -contains several extended versions of \TeX: - -\begin{description} - -\item [\eTeX] adds a set of new primitives -\label{text:etex} (related to macro expansion, character scanning, -classes of marks, additional debugging features, and more) and the -\TeXXeT{} extensions for bidirectional typesetting. In default mode, -\eTeX{} is 100\% compatible with ordinary \TeX. See -\OnCD{texmf-dist/doc/etex/base/etex_man.pdf}. - -\item [pdf\TeX] builds on the \eTeX\ extensions, adding support for - writing \acro{PDF} output as well as \dvi{}. See - \OnCD{texmf/doc/pdftex/manual/} for the manual, and - \OnCD{texmf/doc/pdftex/manual/samplepdf/samplepdf.tex}. - \emph{This is the default program for all formats except plain - \TeX.} - -\item [Lua\TeX] (see \url{http://www.luatex.org/} and - \OnCD{texmf-dist/doc/luatex/luatexref-t.pdf}) is the designated - successor of pdf\TeX, with which it should be - backward-compatible. It should also supersede Aleph, see - below. The incorporated Lua interpreter (see - \url{http://www.lua.org/}) enables elegant solutions for many - thorny \TeX{} problems. When called as \filename{texlua}, it - functions as a standalone Lua interpreter, and is already used as - such within \TL. - -\item [Xe\TeX] adds support for Unicode input, OpenType- and system - 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 / texmfstart] Con\TeX{}t and \acro{PDF} processor. - -\item [tex4ht] \TeX{} to \acro{HTML} converter. - -\end{cmddescription} - - -\subsection{Fonts in \protect\TL} -\label{sec:tl-fonts} -\TL{} also comes with more and more high-quality scalable fonts -built-in: check \emph{e.g.} the \CTAN{} catalogue. Most fonts listed -there are available as a \TL{} package. Check also -\dirname{texmf-doc/english/free-math-fonts-survey}. diff --git a/Master/texmf-doc/source/texlive/texlive-en/releasehist.tex b/Master/texmf-doc/source/texlive/texlive-en/releasehist.tex deleted file mode 100644 index 5d750bd76b0..00000000000 --- a/Master/texmf-doc/source/texlive/texlive-en/releasehist.tex +++ /dev/null @@ -1,372 +0,0 @@ -\section{Release history} -\label{sec:history} - -\subsection{Past} - -Discussion began in late 1993 when the Dutch \TeX{} Users Group was -starting work on its 4All\TeX{} \CD{} for \acro{MS-DOS} users, and it -was hoped at that time to issue a single, rational, \CD{} for all -systems. This was too ambitious a target for the time, but it did spawn -not only the very successful 4All\TeX{} \CD{}, but also the \acro{TUG} -Technical Council working group on a \emph{\TeX{} Directory Structure} -(\url{http://tug.org/tds}), which specified how to create consistent and -manageable collections of \TeX{} support files. A complete draft of the -\TDS{} was published in the December 1995 issue of \textsl{TUGboat}, and -it was clear from an early stage that one desirable product would be a -model structure on \CD{}. The distribution you now have is a very direct -result of the working group's deliberations. It was also clear that the -success of the 4All\TeX{} \CD{} showed that Unix users would benefit -from a similarly easy system, and this is the other main strand of -\TL. - -We first undertook to make a new Unix-based \TDS{} \CD{} in the autumn -of 1995, and quickly identified Thomas Esser's \teTeX{} as the ideal -setup, as it already had multi-platform support and was built with -portability across file systems in mind. Thomas agreed to help, and work -began seriously at the start of 1996. The first edition was released in -May 1996. At the start of 1997, Karl Berry completed a major new release -of Web2c, which included nearly all the features which Thomas Esser had -added in \teTeX, and we decided to base the 2nd edition of the \CD{} on -the standard \Webc, with the addition of \teTeX's \texttt{texconfig} -script. The 3rd edition of the \CD{} was based on a major revision of -\Webc, 7.2, by Olaf Weber; at the same time, a new revision of \teTeX -was being made, and \TL{} included almost all of its features. The -4th edition followed the same pattern, using a new version of \teTeX, -and a new release of \Webc{} (7.3). The system now included a complete -Windows setup. - -For the 5th edition (March 2000) many parts of the \CD{} were revised -and checked, updating hundreds of packages. Package details were stored -in XML files. But the major change for \TeX\ Live 5 was that all -non-free software was removed. Everything in \TL{} is now intended -to be compatible with the Debian Free Software Guidelines -(\url{http://www.debian.org/intro/free}); we have done our best to check -the license conditions of all packages, but we would very much -appreciate hearing of any mistakes. - -The 6th edition (July 2001) had much more material updated. The major -change was a new install concept: the user could select a more exact set -of needed collections. Language-related collections were completely -reorganized, so selecting any of them installs not only macros, fonts, -etc., but also prepares an appropriate \texttt{language.dat}. - -The 7th edition of 2002 had the notable addition of \MacOSX{} support, -and the usual myriad of updates to all sorts of packages and -programs. An important goal was integration of the source back with -\teTeX, to correct the drift apart in versions~5 and~6. - -\subsubsection{2003} - -In 2003, with the continuing flood of updates and additions, we found -that \TL{} had grown so large it could no longer be contained on a -single \CD, so we split it into three different distributions (see -section~\ref{sec:tl-coll-dists}, \p.\pageref{sec:tl-coll-dists}). In -addition: - -\begin{itemize*} -\item At the request of the \LaTeX{} team, we changed the standard - \cmdname{latex} and \cmdname{pdflatex} commands to now use \eTeX{} (see - \p.\pageref{text:etex}). -\item The new Latin Modern fonts were included (and are recommended). -\item Support for Alpha \acro{OSF} was removed - (\acro{HPUX} support was removed previously), since no one had (or - volunteered) hardware available on which to compile new binaries. -\item Windows setup was substantially changed; for the first time - an integrated environment based on XEmacs was introduced. -\item Important supplementary programs for Windows - (Perl, Ghost\-script, Image\-Magick, Ispell) are now installed - in the \TL{} installation directory. -\item Font map files used by \cmdname{dvips}, \cmdname{dvipdfm} - and \cmdname{pdftex} are now generated by the new program - \cmdname{updmap} and installed into \dirname{texmf/fonts/map}. -\item \TeX{}, \MF{}, and \MP{} now, by default, output most input - characters (32 and above) as themselves in output (e.g., - \verb|\write|) files, - log files, and the terminal, i.e., \emph{not} translated using the - \verb|^^| notation. In \TL{}~7, this translation was - dependent on the system locale settings; now, locale settings do - not influence the \TeX{} programs' behavior. If for some reason - you need the \verb|^^| output, rename the file - \verb|texmf/web2c/cp8bit.tcx|. (Future releases will have cleaner - ways to control this.) -\item This documentation was substantially revised. -\item Finally, since the edition numbers had grown unwieldy, - the version is now simply identified by the year: \TL{} 2003. -\end{itemize*} - - -\subsubsection{2004} - -2004 saw many changes: - -\begin{itemize} - -\item If you have locally-installed fonts which use their own -\filename{.map} or (much less likely) \filename{.enc} support files, you -may need to move those support files. - -\filename{.map} files are now searched for in subdirectories of -\dirname{fonts/map} only (in each \filename{texmf} tree), along the -\envname{TEXFONTMAPS} path. Similarly, \filename{.enc} files are now -searched for in subdirectories of \dirname{fonts/enc} only, along the -\envname{ENCFONTS} path. \cmdname{updmap} will attempt to warn about -problematic files. - -For methods of handling this and other information, please see -\url{http://tug.org/texlive/mapenc.html}. - -\item The \TK\ has been expanded with the addition of a \MIKTEX-based -installable \CD, for those who prefer that implementation to Web2C. -See section~\ref{sec:overview-tl} (\p.\pageref{sec:overview-tl}). - -\item Within \TL, the single large \dirname{texmf} tree of previous -releases has been replaced by three: \dirname{texmf}, -\dirname{texmf-dist}, and \dirname{texmf-doc}. See -section~\ref{sec:tld} (\p.\pageref{sec:tld}), and the \filename{README} -files for each. - -\item All \TeX-related input files are now collected in -the \dirname{tex} subdirectory of \dirname{texmf*} trees, rather than -having separate sibling directories \dirname{tex}, \dirname{etex}, -\dirname{pdftex}, \dirname{pdfetex}, etc. See -\CDref{texmf-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 better-checked tree of macros and fonts. This work is -all done by hard-pressed volunteers in their limited spare time, and a -great deal remains to be done. If you can help, please 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!} - diff --git a/Master/texmf-doc/source/texlive/texlive-en/tex-live.sty b/Master/texmf-doc/source/texlive/texlive-en/tex-live.sty index d5a5bfea37b..22a00a09fb7 100644 --- a/Master/texmf-doc/source/texlive/texlive-en/tex-live.sty +++ b/Master/texmf-doc/source/texlive/texlive-en/tex-live.sty @@ -165,6 +165,7 @@ \def\Thanh{H\`an~Th\^e\llap{\raise 0.5ex\hbox{\'{}}}~Th\`anh} \def\XEmTeX{\textrm{XEm}\TeX\xspace} \def\XEmacs{\textrm{XEmacs}\xspace} +\def\XeTeX{Xe\TeX\xspace} \def\Webc{Web2C} \providecommand*{\CD}{\acro{CD}\xspace} \providecommand*{\CTAN}{\acro{CTAN}\xspace} diff --git a/Master/texmf-doc/source/texlive/texlive-en/texlive-en.tex b/Master/texmf-doc/source/texlive/texlive-en/texlive-en.tex index 53fc5a01838..c3b017fd9cf 100644 --- a/Master/texmf-doc/source/texlive/texlive-en/texlive-en.tex +++ b/Master/texmf-doc/source/texlive/texlive-en/texlive-en.tex @@ -23,16 +23,2810 @@ \begin{multicols}{2} \tableofcontents -\listoftables +%\listoftables \end{multicols} -\input{intro} -\input{overview} -\input{installation} -\input{maintenance} -%\input{macosx} -\input{windows} -\input{web2c} -\input{acknowledgements} -\input{releasehist} +\section{Introduction} +\label{sec:intro} + +\subsection{\TeX\ Live and the \TeX\ Collection} + +This document describes the main features of the \TL{} software +distribution\Dash \TeX{} and related programs for \acro{GNU}/Linux +and other Unix flavors, \MacOSX, and Windows systems. + +You may have acquired \TL{} by downloading, or on the \TK{} \DVD, +which \TeX{} usergroups distribute among their members. Section +\ref{sec:tl-coll-dists} briefly describes the contents of this \DVD. +Both \TL{} and the \TK{} are cooperative efforts by the \TeX{} user +groups. This document mainly describes \TL{} itself. + +\TL{} includes executables for \TeX{}, \LaTeXe{}, \ConTeXt, +\MF, \MP, \BibTeX{} and many other programs; an extensive collection +of macros, fonts and documentation; and support for typesetting in +many different scripts from around the world. + +\TL{} packages are regularly updated from +\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{Operating system support} +\label{sec:os_support} + +\TL{} contains binaries for many Linux- and Unix architectures, +including \MacOSX. The included sources should enable installation +on additional Linux- and Unix platforms. + +As to Windows: only Windows 2000 and later are supported. Windows +9\textit{x}, ME and NT have been dropped. Because of this +restriction, Windows requires less special treatment compared to +Linux and Unix. There are no 64-bit executables for Windows, but the +32-bit executables should run on 64-bit systems. + +See section~\ref{sec:tl-coll-dists} for alternate solutions +for Windows and \MacOSX. + +\subsection{Basic usage of \protect\TL{}} +\label{sec:basic} + +You can install \TL{} either from \DVD{} or over the internet. The +net installer itself is very small and downloads everything needed +from the internet. The net installer is an attractive option if you +need only a fraction of the complete \TL. + +The \DVD{} installer lets you install to a local disk, but you can +also run \TL{} directly from the \DVD{} (or from a \DVD{} image, if +your system supports that). + +\noindent This is described in the +installation sections following, but here is a quick start: + +\begin{itemize*} + +\item The installation script is \filename{install-tl}, which has +both a text mode (default for Unix) and a \GUI{} mode (default for +Windows). + +\item One of the installed items is \prog{tlmgr} or \TL\ Manager, + which can also be used in \GUI{} mode and in text mode. You can + use it to install and uninstall packages and do various + configuration tasks. + +\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/html/index.html}, and is available + on the Internet through \url{http://www.tex.ac.uk/faq}. Please + check here first. + +\item [\TeX{} Catalogue] If you are looking for a specific package, +font, program, etc., the \TeX{} Catalogue is the place to look. It is a +huge collection of all \TeX{}-related items. See +%\OnCD{texmf-doc/doc/english/catalogue}, or +\url{http://dante.ctan.org/tex-archive/help/Catalogue/index.html}. + +\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{Overview of \protect\TeX\protect\ Live} +\label{sec:overview-tl} + +This section describes the structure and contents of \TL{} and the +\TK{} of which it is a part. + +\subsection{The \protect\TeX\protect\ Collection: \protect\pkgname{live}, + \protect\pkgname{protext}, + \protect\pkgname{Mac\TeX}} +\label{sec:tl-coll-dists} + +The \TK{} \DVD{} comprises the following: + +\begin{description} + +\item [live] A complete \TeX{} system which can be run live or + installed to disk. It is too large for \acro{CD}. + +\item [CTAN] A snapshot of the \CTAN{} repository + +\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}. + +\item [Mac\TeX] for \MacOSX is independent of but based on \TL{}, + although slightly modified to make a better fit with \MacOSX. Its + home page is \url{http://www.tug.org/mactex/}. + +\item [\texttt{texmf-extra}] A directory with assorted additional packages. + +\end{description} + +\CTAN{}, \pkgname{protext}, Mac\TeX, and \dirname{texmf-extra} do not follow +the same copying conditions as \TL{}, so be careful when redistributing or +modifying. + +\noindent You can tell which type of distribution you're in by +looking for a \filename{release-texlive.txt} 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{texlive}, not at the top +level of the disc. + +%\smallskip +%\begingroup +% \renewcommand{\arraystretch}{1.3} % open up interrow spacing +%\begin{tabular}{>{\ttfamily}lp{.78\hsize}} +\begin{ttdescription} +\item[bin] The \TeX{} system programs, arranged by platform. +% +\item[readme.html] Readme html pages in various languages, with a quick +introduction and useful links +% +\item[source] The source of all programs, including the main \Webc{} + \TeX{} and \MF{} distributions. These are stored in +various compressed archives. +% +\item[support] Various auxiliary packages and programs. These are + \emph{not} installed automatically. This includes + assorted editors and \TeX\ shells. +% +\item[texmf] See \dirname{TEXMFMAIN} below. +% +\item[texmf-dist] See \dirname{TEXMFDIST} below. +% +\item[texmf-doc] Tree for self-contained pure documentation, arranged by + language. +% +\item[tlpkg] Scripts, programs and data for managing the + installation. It also contains private copies of + Perl and Ghostscript for Windows, which are invisible outside \TL, + and a new Windows PostScript viewer PSView. +\end{ttdescription} +%\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 documentation which does +not belong to any particular package or program. The documentation +for the programs (manuals, man pages, Info files) is in +\dirname{texmf/doc}. The documentation for \TeX\ packages and +formats is in \dirname{texmf-dist/doc}. You can use the +\cmdname{texdoc} or \cmdname{texdoctk} programs to find any +documentation wherever it is 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, and the default +layout of a \TL{} system. 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+) and other + support files and their documentation. Does not include + \TeX\ formats and packages. +\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} + +\noindent +The default layout is: +\begin{description} + \item[system-wide root] can span multiple \TL{} releases + \begin{ttdescription} + \item[2007] A previous release + \begin{ttdescription} + \item [] ... + \end{ttdescription} + \item[2008] the current release + \begin{ttdescription} + \item [bin] ~ + \begin{ttdescription} + \item [i386-linux] Linux binaries + \item [...] ... + \item [universal-darwin] \MacOSX binaries + \item [win32] Windows binaries + \end{ttdescription} + \item [TEXMFMAIN] \textit{i.e.} \dirname{texmf} + \item [TEXMFDIST] \textit{i.e.} \dirname{texmf-dist} + \item [TEXMFDOC] \textit{i.e.} \dirname{texmf-doc} + \item [TEXMFSYSVAR] \textit{i.e.} \dirname{texmf-var} + \item [TEXMFSYSCONFIG] \textit{i.e.} \dirname{texmf-config} + \end{ttdescription} + \item [TEXMFLOCAL] \textit{i.e.} \dirname{texmf-local}, can be + retained from release to release + \end{ttdescription} + \item[user's home] \textit{i.e.} \texttt{\$HOME} or + \texttt{\%USERPROFILE\%} + \begin{ttdescription} + \item[.texlive2007] Private generated and configuration data + for a previous release + \begin{ttdescription} + \item [] ... + \end{ttdescription} + \item[.texlive2008] Private generated and configuration data + for the current release + \begin{ttdescription} + \item [TEXMFVAR] \textit{i.e.} \dirname{texmf-var} + \item [TEXMFCONFIG] \textit{i.e.} \dirname{texmf-config} + \end{ttdescription} + \item[TEXMFHOME] \textit{i.e.} \dirname{texmf} Private macros + \textit{etc.} + \end{ttdescription} +\end{description} + +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} + +\TeX{} itself is frozen, apart from rare bug fixes. It is still +present in \TL, and will remain so in the foreseeable future. \TL{} +contains several extended versions of \TeX: + +\begin{description} + +\item [\eTeX] adds a set of new primitives +\label{text:etex} (related to macro expansion, character scanning, +classes of marks, additional debugging features, and more) and the +\TeXXeT{} extensions for bidirectional typesetting. In default mode, +\eTeX{} is 100\% compatible with ordinary \TeX. See +\OnCD{texmf-dist/doc/etex/base/etex_man.pdf}. + +\item [pdf\TeX] builds on the \eTeX\ extensions, adding support for + writing \acro{PDF} output as well as \dvi{}. See + \OnCD{texmf/doc/pdftex/manual/} for the manual, and + \OnCD{texmf/doc/pdftex/manual/samplepdf/samplepdf.tex}. + \emph{This is the default program for all formats except plain + \TeX.} + +\item [Lua\TeX] (see \url{http://www.luatex.org/} and + \OnCD{texmf-dist/doc/luatex/luatexref-t.pdf}) is the designated + successor of pdf\TeX, with which it should be + backward-compatible. It should also supersede Aleph, see + below. The incorporated Lua interpreter (see + \url{http://www.lua.org/}) enables elegant solutions for many + thorny \TeX{} problems. When called as \filename{texlua}, it + functions as a standalone Lua interpreter, and is already used as + such within \TL. + +\item [\XeTeX] adds support for Unicode input, OpenType- and system + 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 / texmfstart] Con\TeX{}t and \acro{PDF} processor. + +\item [tex4ht] \TeX{} to \acro{HTML} converter. + +\end{cmddescription} + + +\subsection{Fonts in \protect\TL} +\label{sec:tl-fonts} +\TL{} also comes with more and more high-quality scalable fonts +built-in: check \emph{e.g.} the \CTAN{} catalogue. Most fonts listed +there are available as a \TL{} package. Check also +\dirname{texmf-doc/english/free-math-fonts-survey}. + +\section{Installation} +\label{sec:install} + +\subsection{Starting the installer} +\label{sec:inst_start} +First, get the \TL{} \DVD{} or the \TK{} \DVD{} or the net installer, +and locate the installer script: \filename{install-tl} for Unix, +\filename{install-tl.bat} for Windows: + +\begin{description} +\item [\TeX{} Collection \DVD:] go to its \dirname{texlive} + subdirectory. Under Windows, the installer will probably start + automatically when you insert the \DVD. +\item [Net installer:] Download from CTAN, under + \dirname{systems/texlive/tlnet}. You can choose between + \filename{install-tl.zip} which can be used under Unix and Windows + and \filename{install-unx.tar.gz} which is Unix-only (including + \MacOSX). After unpacking, \filename{install-tl} and + \filename{install-tl.bat} will be in the \dirname{install-tl} + subdirectory. +\item [Downloadable \TeX{} Live \ISO{} image:] Download from CTAN, + under \dirname{systems/texlive/Images}. Since even the compressed + image is about 1 GB in size, you should not use this option + without good reason. Under most Unices, including Linux and + \MacOSX, you can mount the image directly. Otherwise, burn the + image to a physical \DVD\ and mount it. The installer scripts + \filename{install-tl} and \filename{install-tl.bat} will be in the + root. Under Windows, the installer will probably start + automatically when you insert the \DVD. +\end{description} + +\subsubsection{Unix/Linux} + +\begin{figure}[tb] +\begin{boxedverbatim} +======================> TeX Live installation procedure <===================== + +=======> Note: Letters/digits in <angle brackets> indicate menu items <======= +=======> for commands or configurable options <======= + + + Detected platform: Intel x86 with GNU/Linux + + <B> binary systems: 1 out of 16 + + <S> Installation scheme (scheme-full) + + Customizing installation scheme: + <C> standard collections + <L> language collections + 83 collections out of 84, disk space required: 1666 MB + + <D> directories: + TEXDIR (the main TeX directory): + !! default location: /usr/local/texlive/2008 + !! is not writable, please select a different one! + TEXMFLOCAL (directory for site-wide local files): + /usr/local/texlive/texmf-local + TEXMFSYSVAR (directory for variable and automatically generated data): + /usr/local/texlive/2008/texmf-var + TEXMFSYSCONFIG (directory for local config): + /usr/local/texlive/2008/texmf-config + TEXMFHOME (directory for user-specific files): + ~/texmf + + <O> options: + [ ] use letter size instead of A4 by default + [X] create all format files + [X] install macro/font doc tree + [X] install macro/font source tree + [ ] create symlinks in standard directories + + <V> Install for running from DVD + +Other actions: + <I> start installation to HD + <H> help + <Q> quit + +Enter command: +\end{boxedverbatim} +\caption{Main text installer screen (Linux)}\label{fig:text_main} +\end{figure} + +\begin{figure}[tb] +\tlpng{install-w32-main}{\linewidth} +\caption{Main \GUI{} installer screen (Windows)}\label{fig:gui_main} +\end{figure} + +\noindent +Below, \texttt{>} denotes the shell prompt; user input is +\Ucom{\texttt{bold}}. +Starting under Unix/Linux from an xterm or other terminal: + +\begin{alltt} +> \Ucom{./install-tl} +\end{alltt} +or +\begin{alltt} +> \Ucom{perl install-tl} +\end{alltt} +if you are in the installer directory, otherwise +\begin{alltt} +> \Ucom{<path_to_installer>/install-tl} +\end{alltt} +For \GUI\ mode, use +\begin{alltt} +> \Ucom{./install-tl -gui} +\end{alltt} +For a complete listing of the various options: +\begin{alltt} +> \Ucom{./install-tl -help} +\end{alltt} + +\textbf{Warning.} Your \code{umask} at the time of installation will +be respected by the \TL{} installer. Therefore, if you want your +installation to be usable by users other than you, make sure your +setting is sufficiently permissive, for instance, \code{umask 002}. +For more information about \code{umask}, consult your system +documentation. + +\subsubsection{Windows} + +As already noted, the \DVD\ installer will probably start +automatically when you put the \DVD\ in the \DVD-drive. If not, or +if you use the net installer, you can double-click \filename{install-tl.bat}. + +You can also start the installer from the command-prompt: +Below, \texttt{>} denotes the prompt; user input is +\Ucom{\texttt{bold}}. + +\begin{alltt} +> \Ucom{install-tl} +\end{alltt} +if you are in the installer directory, otherwise +\begin{alltt} +> \Ucom{D:\bs{}install-tl} +\end{alltt} +for the downloadable \ISO, if \texttt{D:} is the optical drive, or +\begin{alltt} +> \Ucom{D:\bs{}texlive\bs{}install-tl} +\end{alltt} +for the \TK\ \DVD. For text mode, use +\begin{alltt} +> \Ucom{install-tl -no-gui} +\end{alltt} +For a complete listing of the various options: +\begin{alltt} +> \Ucom{install-tl -help} +\end{alltt} + +\subsubsection{The text installer} + +Figure~\ref{fig:text_main} displays the main text mode screen under +Unix/Linux. + +You cannot tab around checkboxes or input fields. You just have to +type something at the prompt and press the Enter key, and then the +entire terminal screen will be rewritten, with adjusted content. + +The text installer interface is this primitive for a reason: it +is designed to run on as many platforms as possible, even with a +very barebones Perl (for Windows, a Perl subset is included). + +\subsubsection{The graphical installer} + +Figure~\ref{fig:gui_main} displays the graphical installer under Windows. + +Most differences in available options are due to +this screenshot being from Windows, and the text screen above being +from Linux. + +\subsection{Running the installer} +\label{sec:runinstall} + +The installer is mostly self-explanatory. Still, a few quick notes +about the various options and submenus: + +\subsubsection{Binary systems menu (Unix/Linux only)} +\label{sec:binary} + +\begin{figure}[tbh] +\begin{boxedverbatim} +Available sets of binaries: +=============================================================================== + + a [ ] alpha-linux: DEC Alpha with GNU/Linux + b [ ] amd64-freebsd: x86_64 with FreeBSD + c [ ] hppa-hpux: HP-UX + d [ ] i386-freebsd: Intel x86 with FreeBSD + e [X] i386-linux: Intel x86 with GNU/Linux + f [ ] i386-openbsd: Intel x86 with OpenBSD + g [ ] i386-solaris: Intel x86 with Sun Solaris + h [ ] mips-irix: SGI IRIX + i [ ] powerpc-aix: PowerPC with AIX + j [ ] powerpc-linux: PowerPC with GNU/Linux + k [ ] sparc-linux: Sparc with GNU/Linux + l [ ] sparc-solaris: Sparc with Solaris + m [ ] universal-darwin: universal binaries for MacOSX/Darwin + o [ ] win32: Windows + p [ ] x86_64-linux: x86_64 with GNU/Linux +\end{boxedverbatim} +\caption{Binaries menu}\label{fig:bin_text} +\end{figure} + +Figure~\ref{fig:bin_text} displays the text mode binaries menu. By +default, only the binaries for your current platform will be +installed. From this menu, you can select installation of binaries +for other architectures as well. This can be useful if you are +sharing a \TeX\ tree across a network of heterogenous machines, or +for a dual-boot system. + +\subsubsection{Selecting what is going to be installed} +\label{sec:components} + +From the scheme menu, see figure~\ref{fig:text_scheme}, you can +choose an overall set of package collections. The default +\optname{full} scheme installs everything available, but you can +also choose the \optname{basic} scheme for a minimal system, or +\optname{medium} or \optname{teTeX} to get something in between. +There are also various specialized and country-specific schemes. + +\begin{figure}[tbh] +\begin{boxedverbatim} +Select a scheme: +=============================================================================== + + a [ ] TeX Live basic scheme + b [ ] TeX Live scheme for ConTeXt + c [X] TeX Live full scheme + d [ ] GUST TeX Live scheme + e [ ] GUTenberg TeX Live scheme + f [ ] TeX Live medium scheme + g [ ] TeX Live minimal scheme + h [ ] TeX Live for Omega users + i [ ] teTeX scheme + j [ ] XML typesetting scheme +\end{boxedverbatim} +\caption{Scheme menu}\label{fig:text_scheme} +\end{figure} + +\begin{figure}[tbh] +\tlpng{stdcoll}{.7\linewidth} +\caption{Collections menu (Linux)}\label{fig:gui_collections} +\end{figure} + +You can refine your selection with the `standard collections' and +`language collections' menus. 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 these +submenus, selection letters are case-sensitive\Dash unless you run +the \GUI{} installer, where you can simply click checkboxes; see +figure~\ref{fig:gui_collections}. + +If you want more detail, you need run the \prog{tlmgr} program +afterwards, see section~\ref{sec:tlmgr}. The installer will take +care of appropriate configuration of format generation, hyphenation +patterns and font-related matters. + +\subsubsection{Directories} +\label{sec:directories} + +The default layout is described in section~\ref{sec:texmftrees}, +\p.\pageref{sec:texmftrees}. The default location of +\dirname{TEXDIR} is different for Windows +(|%PROGRAMFILES%\texlive\2008|) and for Unix/Linux +(\dirname{/usr/local/texlive/2008})\footnote{It is possible to + override these defaults beforehand with environment variables; + search the file \filename{install-tl} for + \texttt{TEXLIVE\_INSTALL\_}. However, if you want to automate + installations then a far better option is to use profiles; see + section~\ref{sec:cmdline} under \optname{-profile}.}. + +The main reason for changing the proposed directory structure is +lack of write permissions for the default location. You don't have +to be root or adminstrator to install \TL, but you do need write +access to the target directory. + +A logical alternate choice is a directory under your home directory, +especially if you will be the sole user. Type +`|~|' to indicate this, \emph{e.g.}: `|~/texlive/2008|'. + +We recommend including the year in the name, to enable keeping +different releases of \TL{} side by side. (You may wish to make a +version-independent name such \dirname{/usr/local/texlive-cur} via a +symbolic link, which you can then update after testing the new +release.) + +Changing \dirname{TEXDIR} will also change \dirname{TEXMFLOCAL}, +\dirname{TEXMFSYSVAR} and \dirname{TEXMFSYSCONFIG}. + +\dirname{TEXMFHOME} is the recommended location for personal +macro files or packages. The default value is |~/texmf|. In +contrast to \dirname{TEXDIR}, here a |~| is preserved in the +newly-written configuration files, since it usefully refers to the home +directory of each individual running \TeX. It expands to +\dirname{$HOME} on Unix and \verb|%USERPROFILE%| on Windows. + +\subsubsection{Options} +\label{sec:options} + +\begin{figure}[tbh] +\begin{boxedverbatim} +<P> use letter size instead of A4 by default: [ ] +<F> create all format files: [X] +<D> install font/macro doc tree: [X] +<S> install font/macro source tree: [X] +<L> create symlinks in standard directories: [ ] + binaries to: + manpages to: + info to: +\end{boxedverbatim} +\caption{Options menu (Linux)}\label{fig:text_options} +\end{figure} + +Figure~\ref{fig:text_options} displays the text mode options menu. +Three options require some explanation: +\begin{description} +\item[create all format files:] Although unnecessary format files + take time to generate and disk space to store, it is still + recommended to check this option: if you don't, then format files + will be generated in people's private \dirname{TEXMFVAR} tree, and + won't be updated automatically if binaries or hyphenation patterns + etc. are updated, and they may end up with incompatible format + files. +\item[install font/macro source tree:] These are mostly + \LaTeX{} \filename{.dtx} files, from which both \filename{.sty} files + and documentation are generated. It is ok to uncheck this. +\item[create symlinks in standard directories] (Unix/Linux only): + this option bypasses the need to change environment + variables. Without this option, \TL{} directories have to be added + to \envname{PATH}, \envname{MANPATH} and \envname{INFOPATH}. You will + need write permissions to the target directories. It is not + advisable to overwrite a \TeX\ system that came with your system + with this option. It is 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. +\end{description} + +Now when all these settings are to your liking, you can type `I' to +start the installation process. When it is done, skip to +section~\ref{sec:postinstall} to read what else needs to be done, if +anything. + +\subsubsection{Set up for running from \DVD{} (text mode only)} +\label{sec:fromdvd} + +Typing `V' to select this option. This changes the main menu into something +like figure~\ref{fig:main_fromdvd}. +\begin{figure}[tbh] +\begin{boxedverbatim} +======================> TeX Live installation procedure <===================== + +=======> Note: Letters/digits in <angle brackets> indicate menu items <======= +=======> for commands or configurable options <======= + + <D> directories: + TEXDIRW (Writable root): + !! default location: /usr/local/texlive/2008 + !! is not writable, please select a different one! + TEXMFLOCAL (directory for site-wide local files): + /usr/local/texlive/texmf-local + TEXMFSYSVAR (directory for variable and automatically generated data): + /usr/local/texlive/2008/texmf-var + TEXMFSYSCONFIG (directory for local config): + /usr/local/texlive/2008/texmf-config + TEXMFHOME (directory for user-specific files): + ~/texmf + + <O> options: + [ ] use letter size instead of A4 by default + [X] create all format files + + <V> set up for installing to hard disk + +Other actions: + <I> start installation for running from DVD + <H> help + <Q> quit +\end{boxedverbatim} +\caption{The main menu with \optname{from DVD} + set}\label{fig:main_fromdvd} +\end{figure} + +Note the changes: all options about what to install have +disappeared, and the directories section now talks about +\dirname{TEXDIRW} or writable root. The symlinks option has also +disappeared. + +The installer will still create various directories and +configuration files, but won't copy \dirname{texmf}, +\dirname{texmf-dist} or \dirname{texmf-doc} to harddisk. + +Post-install configuration for Unix/Linux will be slightly more +complicated, see section~\ref{sec:postinstall}, because now the +directory layout deviates from the default. + +Due to time constraints, this option didn't make it into the \GUI{} +installer, but it is available both for Unix/Linux and for +Windows. Windows users have to start the installer from a command +prompt, see section~\ref{sec:cmdline}. + +Section \ref{sec:portable-unix} describes a more strictly portable +way to run \TL, which doesn't make or require changes in the +system's configuration, but doesn't allow any configuration either. + +\subsection{Command-line install options} +\label{sec:cmdline} + +Type +\begin{alltt} +> \Ucom{install-tl -help} +\end{alltt} +for a listing of command-line options. These are the more +interesting ones: + +\begin{ttdescription} +\item[-gui] If possible, use the \GUI{} installer. This requires the + Perl/Tk module (\url{http://tug.org/texlive/distro.html#perltk}); + if Perl/Tk is not available, installation continues in text mode. +\item[-no-gui] Force using the text mode installer, even under + Windows, \emph{e.g.} because you want a `from \DVD' installation, + which is not available in \GUI{} mode. +\item[-lang \textit{2-letter code}] Specify the installer interface + language. Currently supported languages: English (\texttt{en}, + default), German (\texttt{de}), French (\texttt{fr}), Dutch + (\texttt{nl}), Polish (\texttt{pl}), Slovenian (\texttt{sl}) + and Vietnamese (\texttt{vi}). The installer tries to determine the + right language itself but if it fails, or if the right language is + not available, then it uses English as a fallback. +\item[-profile \textit{profile}] The installer writes a file + \filename{texlive.profile} to the \dirname{2008/tlpkg}- or + \dirname{tlpkg} subdirectory of your installation. An + example profile: + \begin{fverbatim} +# texlive.profile written on Wed Jul 9 16:13:44 2008 UTC +# it will NOT be overwritten and reflects only the +# installation profile at installation time +selected_scheme scheme-basic +TEXDIR /usr/local/texlive/2008 +TEXDIRW /usr/local/texlive/2008 +TEXDIRW /usr/local/texlive/2008 +TEXMFHOME ~/texmf +TEXMFLOCAL /usr/local/texlive/texmf-local +TEXMFSYSCONFIG /usr/local/texlive/2008/texmf-config +TEXMFSYSVAR /usr/local/texlive/2008/texmf-var +collection-basic 1 +collection-latex 1 +option_doc 0 +option_fmt 0 +option_letter 0 +option_src 0 +option_symlinks 0 + \end{fverbatim} + With a copy of this file, you can install in batchmode on + subsequent systems, reproducing the choices you made for the + original installation. +\item [-location \textit{url/path}] Specify a non-default source for + packages; see below. +\end{ttdescription} + +\subsubsection{The \optname{location} parameter} +\label{sec:location} + +The argument can be an \texttt{ftp:} or \texttt{http:} url, but also +a local \texttt{file:/} url, and even a plain path. If the given +argument is on a local drive (either a path or a \texttt{file:/} +url), the installation type (compressed or live) is automatically +determined: if an \dirname{archive} subdirectory with +\filename{.tar.lzma} files is found then it will be used, even if +uncompressed files are available as well. + +When giving an \texttt{http:} or \texttt{ftp:} location, +trailing `\texttt{/}' characters and/or a trailing `\texttt{/tlpkg}' +component are ignored. For example, you could choose a particular +CTAN mirror with something like: +\url{http://ctan.example.org/tex-archive/texlive/tlnet/2008}, +substituting of course a proper hostname and its particular top-level +CTAN path (the list of CTAN mirrors is maintained at +\url{http://ctan.org/mirrors}). The default is to pick a mirror +automatically, using \url{http://mirror.ctan.org}; one mirror is +used for the entire download. + + +\subsection{Post-install actions} +\label{sec:postinstall} + +Some post-install may be required. + +\subsubsection{Windows} + +For Windows, the installer takes care of everything. + +\subsubsection{If symlinks were created} + +If you elected to create symlinks in standard directories then there +is no need to edit environment variables. + +\subsubsection{Environment variables for Unix/Linux} +\label{sec:env} + +The directory of the binaries for your platform should be added to +the searchpath. Each supported platform has its own subdirectory +under \dirname{TEXDIR/bin}. See figure~\ref{fig:bin_text} for the +list of subdirectories and corresponding platforms. + +You might as well also add the \TeX{} info- and manpage directories +to their respective searchpaths. A couple of examples: + +For Bash or another Bourne-compatible shell and Intel x86 +GNU/Linux and a default directory setup, the file to edit might be +\filename{$HOME/.profile} or \filename{$HOME/.bash_profile}, and the lines +to add might look like + +\begin{sverbatim} +PATH=/usr/local/texlive/2008/bin/i386-linux:$PATH +export PATH +MANPATH=/usr/local/texlive/2008/texmf/doc/man:$MANPATH +export MANPATH +INFOPATH=/usr/local/texlive/2008/texmf/doc/info:$INFOPATH +export INFOPATH +\end{sverbatim} + +For csh or tcsh, the file to edit might be \filename{$HOME/.cshrc} and +the lines to add might look like: + +\begin{sverbatim} +setenv PATH /usr/local/texlive/2008/bin/i386-freebsd:$PATH +setenv MANPATH /usr/local/texlive/2008/texmf/doc/man:$MANPATH +setenv INFOPATH /usr/local/texlive/2008/texmf/doc/info:$INFOPATH +\end{sverbatim} + +\subsubsection{Environment variables: global configuration} +\label{sec:envglobal} + +If you want to make these changes globally, or at least for a +default new user, then you are on your own; there is just too much +variation between systems in how and where these things are +configured. + +You may want to check for a file +\filename{/etc/manpath.config} and, if present, add lines such as + +\begin{sverbatim} +MANPATH_MAP /usr/local/texlive/2008/bin/i386-linux \ + /usr/local/texlive/2008/texmf/doc/man +\end{sverbatim} + +Check also for a file \filename{/etc/environment} which may define +the searchpath and some other default environment variables. + +\subsubsection{When running from DVD} + +Normally, a \TL{} program consults a file \filename{texmf.cnf} for +the location of the various trees. It looks for this file in a +series of locations relative to its own location. However, this +scheme breaks down when the program file is on the \DVD{}: the +\DVD{} is read-only. Some of the paths to be recorded in +\filename{texmf.cnf} are only known at installation time, so this +file cannot be on the \DVD{} and must be placed somewhere else. This +makes it necessary to define an environment \envname{TEXMFCNF} +variable which tells \TL{} programs in what directory to find this +\filename{texmf.cnf}. Of course it is still necessary to modify the +\envname{PATH} environment variable, as described before. + +At the end of the installation, the installer should have printed a +message to what value \envname{TEXMFCNF} should be set. In case you +missed it: this value is \dirname{$TEXMFSYSVAR/web2c}. For the +default, \dirname{/usr/local/texlive/2008/texmf-var/web2c}, you need +the lines +\begin{sverbatim} +TEXMFCNF=/usr/local/texlive/2008/texmf-var/web2c +export TEXMFCNF +\end{sverbatim} +or, for [t]csh: +\begin{sverbatim} +setenv TEXMFCNF /usr/local/texlive/2008/texmf-var/web2c +\end{sverbatim} + +\subsubsection{\ConTeXt{} Mark IV} + +The `old' \ConTeXt{} should run out of the box. The new `Mark IV' +\ConTeXt{} will require manual setup; see +\url{http://wiki.contextgarden.net/Running_Mark_IV} + +\subsubsection{Integrating local and personal macros} + +This is already mentioned implicitly in +section~\ref{sec:texmftrees}: \dirname{TEXMFLOCAL}, \emph{e.g.} +\dirname{/usr/local/texlive/texmf-local} or +\verb|C:\Program Files\texlive\texmf-local| is intended for local +fonts and macros; \dirname{TEXMFHOME}, usually \dirname{$HOME/texmf} +or \verb|%USERPROFILE%\texmf|, are for +personal fonts and macros. These directories should stick around +from release to release. Their content will be seen automatically by +a new \TL{} release. + +\subsubsection{Integrating third-party fonts} + +This is unfortunately a very complicated and messy topic. Forget +about it unless you really know your way around blindfolded in a +\TeX{} installation. Don't forget to check first what you get for +free: see section~\ref{sec:tl-fonts}. + +An alternative is using \XeTeX, +see section~\ref{sec:tex-extensions}, which lets you use operating +system fonts without installation in \TeX. + + +\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{sec:env}. + +\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{Network installations} +\label{sec:netinstall} + +\TL{} has been designed to be shared between different users, and +even different systems on a network. With a standard directory +layout, no hard paths are configured: the locations for files needed +by \TL{} programs are defined relative to the places of those +programs. This is true even if \dirname{$TEXMFLOCAL} is on the same +level as the other trees instead of one level higher. You can see +this at work in the configuration file +\filename{$TEXMFMAIN/web2c/texmf.cnf}, which contains lines such as +\begin{sverbatim} +TEXMFMAIN = $SELFAUTOPARENT/texmf +... +TEXMFLOCAL = $SELFAUTOPARENT../texmf-local +\end{sverbatim} +This means that other systems or other users merely need to add the +directory for \TL{} binaries for their platform to their searchpath. + +By the same token, you can also install \TL{} locally and then move +the entire hierarchy afterwards to a network location. + +Of course, Windows users have different +expectations. The directory +\dirname{texmf-doc/source/texlive/texlive-common/w32client} contains +a sample script \filename{install-w32client} +which creates settings and menu shortcuts for using an +existing \TL{} installation on a LAN. It is to be invoked through a +batchfile wrapper \filename{install-w32client.bat} in the same +directory. + +You can read more about \TL{} configuration and path searching in +section~\ref{sec:kpathsea}. + +\section{Really portable \protect\TL{} on DVD and USB} +\label{sec:portable-unix} + +The `running from \DVD{}' option described in +section~\ref{sec:fromdvd} is fine for your own system, but if you +are a guest on somebody else's system then you might prefer +something with minimal side-effects. + +In the root of the \TL{} \DVD, or the \dirname{texlive} subdirectory +of the \TK{} \DVD, are a \filename{tl-portable} script (Unix/Linux) +and a \filename{tl-portable.bat} batchfile (Windows) which start up +a secondary shell/command prompt with environment settings suitable +for accessing the \TL{} on the \DVD. + +When it runs for the first time, some files will be generated in a +directory \dirname{~/.tlportable2008}. On subsequent runs, though, it +will start almost instantaneously. + +The rest of the system will be unaware of \TL. If you want your +editor to be aware of this \TL, then you can start it from +a second, parallel such \TL{} session. + +You can also use \filename{tl-portable} to run \TL{} on a +\acro{USB} stick. In this case, copy all the top-level files and +the contents of the \dirname{bin}, \dirname{texmf}, +\dirname{texmf-dist}, and \dirname{tlpkg} directories (at least) to +the stick. This may take quite a while! If you are copying to a +\acro{FAT32}-formatted \acro{USB} stick, make sure to dereference +symbolic links (\code{cp -L}). A \dirname{texmf-local} directory on +the stick will also be found and used. + +Then run \filename{tl-portable} from the root of the stick, as +above. In this case, the script will notice that the stick is +writable and use it for generated files. You could probably burn +the resulting contents of the stick back to \DVD{} if that is more +convenient to (for example) give to others. + +\section{Managing your installation} +\label{sec:tlmgr} + +\begin{figure}[tb] +\tlpng{tlmgr-gui}{\linewidth} +\caption{\texttt{tlmgr} in GUI mode. The list of + packages/collections/schemes only shows up after clicking the + `Load' button.}\label{fig:tlmgr-gui} +\end{figure} + +\begin{figure}[tb] +\tlpng{tlmgr-config}{\linewidth} +\caption{\texttt{tlmgr} in GUI mode: Configuration tab}\label{fig:tlmgr-config} +\end{figure} + +The installer installs a program \prog{tlmgr} for managing the +installation\footnote{\texttt{updmap}, \texttt{fmtutil} and + \texttt{texconfig} are still included, but \texttt{tlmgr} is now + the preferred interface. Don't use the other, more low-level tools + unless you know what you are doing.}. Its capabilities include: +\begin{itemize} +\item listing schemes, collections and packages +\item installing, updating, backing up, restoring and uninstalling + individual packages, optionally taking dependencies into account +\item searching the package database +\item listing and adding architectures +\item changing installation options such as paper size, location + (see section~\ref{sec:location}) and format generation +\end{itemize} +\textit{Warning.} \prog{tlmgr} has not been designed for or tested +with installations which run from \DVD. + +\subsection{\texttt{tlmgr GUI mode}} +\prog{tlmgr} can be started in \GUI{} mode with +\begin{alltt} +> \Ucom{tlmgr -gui} +\end{alltt} +or in Windows via the Start menu: Start, Programs, TeX Live 2008, +TeX Live Manager. After clicking `Load' it displays a list of +available and installed packages\Dash the latter prepended with +`(i)'. This assumes of course that the installation source is valid +and reachable. + +Figure~\ref{fig:tlmgr-config} shows the configuration tab. + +\subsection{Sample command-line invocations} +Installing several packages, including a new `engine', from a +non-default location: +\begin{alltt} +> \Ucom{tlmgr -location http://172.16.18.1/tldev install collection-xetex xkeyval} +\end{alltt} +generates the following output: + +\begin{fverbatim} +install: collection-xetex +install: arabxetex +install: euenc +install: bidi +install: fontspec +install: fontwrap +install: ifxetex +install: philokalia +install: polyglossia +install: xecyr +install: xecyr.i386-linux +install: xepersian +install: xetex +install: xetexconfig +install: xetex.i386-linux +running post install action for xetex +install: xetex-def +install: xetex-pstricks +install: xetexfontinfo +install: xltxtra +install: xunicode +install: xkeyval +running mktexlsr +mktexlsr: Updating /usr/local/texlive/2008/texmf/ls-R... +mktexlsr: Updating /usr/local/texlive/2008/texmf-config/ls-R... +mktexlsr: Updating /usr/local/texlive/2008/texmf-dist/ls-R... +mktexlsr: Updating /usr/local/texlive/2008/texmf-doc/ls-R... +mktexlsr: Updating /usr/local/texlive/2008/../texmf-local/ls-R... +mktexlsr: Updating /usr/local/texlive/2008/texmf-var/ls-R... +mktexlsr: Done. +regenerating fmtutil.cnf +running fmtutil-sys --missing +... +Transcript written on xelatex.log. +fmtutil: /usr/local/texlive/2008/texmf-var/web2c/xetex/xelatex.fmt installed. +\end{fverbatim} +As you see, \prog{tlmgr} takes care of any necessary +post-install actions, including updating the filename database and +generating formats. + +\noindent +Installing a language also triggers format generation: +\begin{alltt} +> \Ucom{tlmgr install collection-langdutch} +\end{alltt} +Printing some information about a package: +\begin{alltt} +> \Ucom{tlmgr show collection-wintools} +\end{alltt} +produces +\begin{fverbatim} +Package: collection-wintools +Category: Collection +ShortDesc: Windows support programs +LongDesc: Utilities for Windows, since they are not readily available there: + gzip, chktex, jpeg2ps, unzip, wget, xpdf. +Installed: Yes +\end{fverbatim} +Updating your entire installation: +\begin{alltt} +> \Ucom{tlmgr update -all} +\end{alltt} +If this makes you nervous, first type +\begin{alltt} +> \Ucom{tlmgr update -all -dry-run} +\end{alltt} +or +\begin{alltt} +> \Ucom{tlmgr update -list} +\end{alltt} +For full documentation, type +\begin{alltt} +> \Ucom{tlmgr -help} +\end{alltt} + +\section{Notes on Windows} +\label{sec:windows} + +For this edition of \TL, we built a unified installer for Windows +and Unix. This was only possible by dropping support for older +Windows versions. + +\subsection{Windows-specific features} +\label{sec:winfeatures} + +Under Windows, the installer does some extra things: +\begin{description} +\item[Menus and shortcuts.] There is a new \TL{} submenu of the + Start menu which contains entries for some \GUI{} programs + (\prog{tlmgr}, \prog{texdoctk}, the PS\_View PostScript previewer) + and some documentation. PS\_View also gets a shortcut on the + desktop as a drag-and-drop target for PostScript files. +\item[Automatic setting of environment variables.] No manual + configuration steps are required. +\item[Uninstaller.] The installer creates an entry under `Add/Remove + Programs' for \TL. The uninstall tab of\prog{tlmgr} just refers to + this. +\end{description} + +\subsection{Additional included software} + +\begin{figure}[tb] +\tlpng{psview}{.6\linewidth} +\caption{PS\_View: very high magnifications available!}\label{fig:psview} +\end{figure} + +To be complete, a \TL installation needs support packages that are not +commonly found on a Windows machine. \TL{} provides the missing +pieces: +\begin{description} +\item[Perl and Ghostscript.] Because of the importance of Perl and + Ghostscript, \TL{} includes `hidden' copies of these + programs. \TL{} programs that need them know where to find them, + but they don't betray their presence through environment variables + or registry settings. They aren't full-scale distributions, and + shouldn't interfere with a normal installation of Perl or + Ghostscript. +\item[Command-line tools.] A number of Windows ports of common Unix + command-line programs are installed along with the usual \TL{} + binaries. These include gzip, chktex, jpeg2ps, unzip, wget and the + command-line utilities from the xpdf suite. +\item[\texttt{fc-cache}] helps \XeTeX{} to handle fonts more + efficiently. +\item[PS\_View.] Also installed is PS\_View, a new PostScript viewer + with a free license; see figure~\ref{fig:psview}. +\end{description} +\begin{description} +\item[The \texttt{support} directory,] already mentioned in + section~\ref{sec:tld}. This directory contains various programs + which can be useful in connection with \TeX, in particular a + number of \TeX-aware editors and \TeX{} frontends. The software in + this directory isn't covered by the installer. This directory also + contains the \prog{dviout} \dvi{} previewer, see below. +\end{description} + +\subsection{The Dviout previewer} + +This \TL{} release unfortunately doesn't offer a preinstalled \dvi{} +previewer for Windows. However, you can install \prog{dviout} by +Toshio Oshima from the \path{support/dviout/} directory, which +contains also a short \filename{README} describing how to install +and configure \prog{dviout} for \TL. Please read this carefully +before installation. + +At first, when you preview files with \cmdname{dviout}, it will create fonts, +because screen fonts were not installed. After a while, you will have created +most of the fonts you use, and you will rarely see the font-creation window. +More information can be found in the (very good) on-line help. + +\subsection{Urls for additional downloadable software} + +Urls for some other tools you may consider installing: +\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 for Windows is available on \TL in + the \path{support} directory, 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} + + +\subsection{User Profile is Home} +\label{sec:winhome} + +The Windows counterpart of a Unix home directory is the +\verb|%USERPROFILE%| directory, under Windows XP and Windows 2000 usually +\dirname{C:/Documents and Settings/<user name>}, but under Windows +Vista \dirname{C:/Users/<user name>}. So finally \verb|$HOME| means +something to \TL{} even under Windows. + +\subsection{The registry} +\label{sec:registry} + +Windows stores pretty nearly all configuration data in the +registry. The registry contains a set of hierarchically organized +keys. There are several root keys. The most important ones for +installation programs are \path{HKEY_CURRENT_USER} and +\path{HKEY_LOCAL_MACHINE}, \path{HKCU} and \path{HKLM} in short. The +\path{HKCU} part of the registry is in the user's home directory, +see section~\ref{sec:winhome}. \path{HKLM} is normally in a +subdirectory of the Windows directory. + +In some cases, system information could be obtained from environment +variables but for other information, \emph{e.g.} the location of +shortcuts, it was necessary to consult the registry. Setting +environment variables permanently also requires registry access. + +\subsection{Permissions} +\label{sec:winpermissions} + +In later versions of Windows, a distinction is made between regular +users and administrators, where only the latter have free +access to the entire operating system. In practice, though, you +could better describe these classes of users as unprivileged users +and normal users: being an administrator is the rule, not the +exception. Nevertheless, we have made an effort to make \TL{} +installable without administrative privileges. + +If the user is an administrator, shortcuts are +created for all users, and the system environment is +modified. Otherwise, shortcuts and menu entries are created for the +current user, and the user environment is modified. Use the +\optname{non-admin} option to \prog{install-tl} if you prefer +per-user settings even as an administrator. + +Regardless of administrator status, the default root of \TL{} +proposed by the installer is always under \verb|%PROGRAMFILES%|. The +installer always tests whether this root is writable for the current +user. + +\subsection{Path problem} + +A problem may arise if the user is not an administrator and there is +already a \TeX{} on the searchpath. Since the effective path +consists of the system path followed by the user path, the new \TL{} +will never get precedence. As a workaround, in this case the +installer creates shortcuts to the command-prompt in which the new +\TL{} binary directory is prepended to the local searchpath. \TL{} +will be usable when run in a command-line session started from such +a shortcut. + +\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} +\label{sec:kpathsea} + +Let us first describe the generic path searching mechanism of the \KPS{} +library. + +We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list +of \emph{path elements}, which are basically directory names. A +search path can come from (a combination of) many sources. To look up +a file \samp{my-file} along a path \samp{.:/dir}, \KPS{} checks each +element of the path in turn: first \file{./my-file}, then +\file{/dir/my-file}, returning the first match (or possibly all +matches). + +In order to adapt optimally to all operating systems' conventions, on +non-Unix systems \KPS{} can use filename separators different from +colon (\samp{:}) and slash (\samp{/}). + +To check a particular path element \var{p}, \KPS{} first checks if a +prebuilt database (see ``Filename data\-base'' on +page~\pageref{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:install-disk} on +\p.\pageref{sec:install-disk}). You may wish to skip installing +all of the prebuilt binaries. + +Then, unpack the source from the compressed \texttt{tar} file in the +directory \dirname{source} to your disk and change directory to where +you placed it. + +Next, run \cmdname{configure} with a command line like this: +\begin{alltt} +> \Ucom{sh configure -prefix=/usr/local/TeX} +\end{alltt} + +The \optname{-prefix} directory is the one where you installed the +support tree; the directory layout will be as follows (where \$TEXDIR +stands for the directory you chose): + +\noindent +\begin{tabular}{>{\ttfamily}ll@{}} + \dirname{$TEXDIR/share/texmf} & main tree with fonts,\\ + & \qquad macros, etc\\ + \dirname{$TEXDIR/man} & Unix manual pages\\ + \dirname{$TEXDIR/info} & \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 \XeTeX{} 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}). +(For information on the build process, see +\filename{Build/source/README} in the repository.) + +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:tl-coll-dists}, \p.\pageref{sec:tl-coll-dists}). In +addition: + +\begin{itemize*} +\item At the request of the \LaTeX{} team, we changed the standard + \cmdname{latex} and \cmdname{pdflatex} commands to now use \eTeX{} (see + \p.\pageref{text:etex}). +\item The new Latin Modern fonts were included (and are recommended). +\item Support for Alpha \acro{OSF} was removed + (\acro{HPUX} support was removed previously), since no one had (or + volunteered) hardware available on which to compile new binaries. +\item Windows setup was substantially changed; for the first time + an integrated environment based on XEmacs was introduced. +\item Important supplementary programs for Windows + (Perl, Ghost\-script, Image\-Magick, Ispell) are now installed + in the \TL{} installation directory. +\item Font map files used by \cmdname{dvips}, \cmdname{dvipdfm} + and \cmdname{pdftex} are now generated by the new program + \cmdname{updmap} and installed into \dirname{texmf/fonts/map}. +\item \TeX{}, \MF{}, and \MP{} now, by default, output most input + characters (32 and above) as themselves in output (e.g., + \verb|\write|) files, + log files, and the terminal, i.e., \emph{not} translated using the + \verb|^^| notation. In \TL{}~7, this translation was + dependent on the system locale settings; now, locale settings do + not influence the \TeX{} programs' behavior. If for some reason + you need the \verb|^^| output, rename the file + \verb|texmf/web2c/cp8bit.tcx|. (Future releases will have cleaner + ways to control this.) +\item This documentation was substantially revised. +\item Finally, since the edition numbers had grown unwieldy, + the version is now simply identified by the year: \TL{} 2003. +\end{itemize*} + + +\subsubsection{2004} + +2004 saw many changes: + +\begin{itemize} + +\item If you have locally-installed fonts which use their own +\filename{.map} or (much less likely) \filename{.enc} support files, you +may need to move those support files. + +\filename{.map} files are now searched for in subdirectories of +\dirname{fonts/map} only (in each \filename{texmf} tree), along the +\envname{TEXFONTMAPS} path. Similarly, \filename{.enc} files are now +searched for in subdirectories of \dirname{fonts/enc} only, along the +\envname{ENCFONTS} path. \cmdname{updmap} will attempt to warn about +problematic files. + +For methods of handling this and other information, please see +\url{http://tug.org/texlive/mapenc.html}. + +\item The \TK\ has been expanded with the addition of a \MIKTEX-based +installable \CD, for those who prefer that implementation to Web2C. +See section~\ref{sec:overview-tl} (\p.\pageref{sec:overview-tl}). + +\item Within \TL, the single large \dirname{texmf} tree of previous +releases has been replaced by three: \dirname{texmf}, +\dirname{texmf-dist}, and \dirname{texmf-doc}. See +section~\ref{sec:tld} (\p.\pageref{sec:tld}), and the \filename{README} +files for each. + +\item All \TeX-related input files are now collected in +the \dirname{tex} subdirectory of \dirname{texmf*} trees, rather than +having separate sibling directories \dirname{tex}, \dirname{etex}, +\dirname{pdftex}, \dirname{pdfetex}, etc. See +\CDref{texmf-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 \XeTeX{} program, +available as the \texttt{xetex} and \texttt{xelatex} programs; see +\url{http://scripts.sil.org/xetex}. + +MetaPost also received a notable update, with more planned for the +future (\url{http://tug.org/metapost/articles}), likewise pdf\TeX{} +(\url{http://tug.org/applications/pdftex}) + +The \TeX\ \filename{.fmt} (high-speed format) and the similar files for +MetaPost and \MF\ are now stored in subdirectories of \dirname{texmf/web2c}, +instead of in the directory itself (although the directory is still +searched, for the sake of existing \filename{.fmt}'s). The +subdirectories are named for the `engine' in use, such as \filename{tex} +or \filename{pdftex} or \filename{xetex}. This change should be +invisible in normal use. + +The (plain) \texttt{tex} program no longer reads \texttt{\%\&} first +lines to determine what format to run; it is the pure Knuthian \TeX. +(\LaTeX\ and everything else do still read \texttt{\%\&} lines). + +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 better-checked tree of macros and fonts. This work is +all done by hard-pressed volunteers in their limited spare time, and a +great deal remains to be done. If you can help, please 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} diff --git a/Master/texmf-doc/source/texlive/texlive-en/web2c.tex b/Master/texmf-doc/source/texlive/texlive-en/web2c.tex deleted file mode 100644 index b8c9524b37c..00000000000 --- a/Master/texmf-doc/source/texlive/texlive-en/web2c.tex +++ /dev/null @@ -1,832 +0,0 @@ -\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} -\label{sec:kpathsea} - -Let us first describe the generic path searching mechanism of the \KPS{} -library. - -We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list -of \emph{path elements}, which are basically directory names. A -search path can come from (a combination of) many sources. To look up -a file \samp{my-file} along a path \samp{.:/dir}, \KPS{} checks each -element of the path in turn: first \file{./my-file}, then -\file{/dir/my-file}, returning the first match (or possibly all -matches). - -In order to adapt optimally to all operating systems' conventions, on -non-Unix systems \KPS{} can use filename separators different from -colon (\samp{:}) and slash (\samp{/}). - -To check a particular path element \var{p}, \KPS{} first checks if a -prebuilt database (see ``Filename data\-base'' on -page~\pageref{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:install-disk} on -\p.\pageref{sec:install-disk}). You may wish to skip installing -all of the prebuilt binaries. - -Then, unpack the source from the compressed \texttt{tar} file in the -directory \dirname{source} to your disk and change directory to where -you placed it. - -Next, run \cmdname{configure} with a command line like this: -\begin{alltt} -> \Ucom{sh configure -prefix=/usr/local/TeX} -\end{alltt} - -The \optname{-prefix} directory is the one where you installed the -support tree; the directory layout will be as follows (where \$TEXDIR -stands for the directory you chose): - -\noindent -\begin{tabular}{>{\ttfamily}ll@{}} - \dirname{$TEXDIR/share/texmf} & main tree with fonts,\\ - & \qquad macros, etc\\ - \dirname{$TEXDIR/man} & Unix manual pages\\ - \dirname{$TEXDIR/info} & \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} - diff --git a/Master/texmf-doc/source/texlive/texlive-en/windows.tex b/Master/texmf-doc/source/texlive/texlive-en/windows.tex deleted file mode 100644 index 15d1c6762a3..00000000000 --- a/Master/texmf-doc/source/texlive/texlive-en/windows.tex +++ /dev/null @@ -1,98 +0,0 @@ -\section{Notes on Windows} -\label{sec:windows} - -This edition of \TL, we built a unified installer for Windows and -Unix. We limited support to Windows 2000, XP and Vista. These -versions are less quirky than their predecessors, and have user home -directories (\verb|%USERPROFILE%|). - -%\subsection{Different user expectations} -% -%We made some effort to conform to expectations of Windows users: the -%installer defaults to \GUI{} mode; the default install location is -%\dirname{Program Files}, it creates shortcuts to some -%documentation and some \GUI{} utilities; it creates an entry in -%Add/Remove Programs, and there is no need for any manual -%configuration afterwards. -% -%A second issue is that Windows users are often unaware of different -%levels of user permissions. Later Windows versions make some -%rudimentary differentiation between administrators and regular -%users, but non-administrators can \emph{e.g.} still write to many -%locations outside their `home' directory., We tried to deal with this as -%unobtrusively as possible. - -\subsection{Additional included software} - -\begin{figure}[tb] -\tlpng{psview}{.6\linewidth} -\caption{PS\_View: very high magnifications available!}\label{fig:psview} -\end{figure} - -To be complete, a \TL installation needs support packages that are not -commonly found on a Windows machine. \TL{} provides the missing -pieces: -\begin{description} -\item[Perl and Ghostscript] Because of the importance of Perl and - Ghostscript, \TL{} includes `hidden' copies of these - programs. \TL{} programs that need them know where to find them, - but they don't betray their presence through environment variables - or registry settings. They aren't full-scale distributions, and - shouldn't interfere with a normal installation of Perl or - Ghostscript. -\item[Command-line tools] A number of Windows ports of common Unix - command-line programs are installed along with the usual \TL{} - binaries. These include gzip, chktex, jpeg2ps, unzip, wget and the - command-line utilities from the xpdf suite. -\item[PS\_View] Also installed is PS\_View, a new PostScript viewer - with a free license; see figure~\ref{fig:psview}. -\end{description} -\begin{description} -\item[The \texttt{support} directory], already mentioned in - section~\ref{sec:tld}. This directory contains various programs - which can be useful in connection with \TeX, in particular a - number of \TeX-aware editors and \TeX{} frontends. The software in - this directory isn't covered by the installer. -\end{description} - -\subsection{Urls for additional downloadable software} - -Urls for some other tools you may consider installing: -\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} - -%registry -%user vs system -%file associations -%path problem -%non-admin -%network install -%fc-cache - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: t -%%% End: |