Debian Codegraph @

texmf-dist/doc/texlive/texlive-en/archive/live-2003.tex

raw
1 % $Id: live-2003.tex 1513 2006-02-13 00:22:35Z karl $
2 % change history (started May 13th 2002)
3 % 2003/09/06: fixes from Staszek
4 % 2003/09/05: touched by Karl
5 % 2003/09/04: fixes from Staszek and Fabrice
6 % 2003/09/01: fixes from Volker
7 % 2003/08/24: win32 updates, by Fabrice
8 % 2003/08/12: fixes from Christer Gustafsson <[email protected]>.
9 % 2003/07/07: substantial revisions by karl.
10 % 2002/05/25: remove mention of sizes, and bsr-interpolated; add Gutenberg
11 % 2002/05/18: win32 updates, by Fabrice
12 % 2002/05/14: corrected example files, other small errors noted by Volker
13 % 2002/05/13: added tex-langafrican to list of collections
14 %
15 \documentclass{article}
16 \usepackage{tex-live}
17 %
18 %
19 \begin{document}
20
21 \title{{\huge\textsf{\TK{} 2003}}\\[3mm]
22 The \protect\TeXLive{} Guide}
23 \date{September 2003}
24
25 \author{Sebastian Rahtz, editor \\[3mm]
26 \email{[email protected]}\\
27 \url{http://tug.org/texlive/}\\[10mm]
28 \ifnum \Status=2
29 \includegraphics[bb=0 0 824 741]{../pictures/front.jpg} \\[5mm]
30 \else
31 \includegraphics[width=.5\linewidth]{../pictures/front} \\[5mm]
32 \fi
33 \small \textit{Documentation contacts:}\\[3mm]
34 \small \begin{tabular}{lcr}
35 Czech/Slovak & Petr Sojka & \email{[email protected]} \\
36 & Janka Chleb\'\i kov\'a & \email{chlebikj (at) dcs.fmph.uniba.sk} \\
37 English & Karl Berry & \email{[email protected]} \\
38 French & Fabrice Popineau & \email{[email protected]} \\
39 German & Volker RW Schaa & \email{[email protected]} \\
40 Polish & Staszek Wawrykiewicz & \email{[email protected]} \\
41 Russian & Boris Veytsman & \email{[email protected]} \\
42 \end{tabular}
43 }
44
45 % comes out too close to the toc, and we know it's page one anyway.
46 \thispagestyle{empty}
47
48 \maketitle
49 \newpage
50
51 \begin{multicols}{2}
52 \tableofcontents
53 \listoftables
54 \end{multicols}
55
56 \section{Introduction}
57 \label{sec:intro}
58
59 This document describes the main features of the \TeXLive{} software
60 distribution\Dash a \TeX{} and \LaTeX{} distribution for Linux and other
61 Unix flavors, \MacOSX, and (32-bit) Windows systems. (Warning: it is
62 not especially useful for older Mac or \acro{MS-DOS} systems.) It
63 includes precompiled binaries for \TeX{}, \LaTeXe{}, \MF, \MP,
64 \BibTeX{} and many other programs; an extensive collection of
65 macros, fonts and documentation; and support for typesetting in many
66 different scripts from around the~world.
67
68 For the 2003 release, the last update of packages and programs was made
69 on September 3, 2003. For newer versions, please consult \acro{CTAN},
70 \url{http://www.ctan.org}.
71
72 For a brief summary of the major changes in this edition of \TeXLive{},
73 see section~\ref{sec:history} on p.~\pageref{sec:history}.
74
75
76 \subsection{Basic usage of \protect\TeXLive{}}
77 \label{sec:basic}
78
79 You can use \TeXLive{} in three principal ways:
80
81 \begin{enumerate}
82
83 \item You can run \TeXLive{} directly from the distribution media
84 (except for the \pkgname{inst} distribution; see
85 section~\ref{sec:multiple-dist} on p.~\pageref{sec:multiple-dist}).
86 This takes almost no disk space, as you might expect, and gives you
87 immediate access to everything in \TeXLive{}. Of course performance
88 will be worse than running on local disk, but you may well find it
89 acceptable.
90
91 \item You can install all or part of \TeXLive{} to a local disk. This
92 is the most common use of \TeXLive. You will need a minimum of 120
93 megabytes, 360 megabytes for a recommended system, and 800 megabytes for
94 a full system.
95
96 \item You can integrate a particular package or collection into your
97 existing \TeX{} system, either a \TeXLive{} system you installed earlier
98 or a different system.
99
100 \end{enumerate}
101
102 \noindent All of these are described in detail in the \acro{OS}-specific
103 installation sections.
104
105
106 \subsection{Getting help}
107 \label{sec:help}
108
109 The \TeX{} community is both active and friendly, and virtually all
110 serious questions end up getting answered. However, the support is
111 informal, done by volunteers and casual readers, so it's especially
112 important that you do your homework before asking. (If you prefer
113 commercial-style support, you can forego \TeXLive{} completely and
114 purchase a vendor's system; see
115 \url{http://tug.org/interest.html#vendors} for a list.)
116
117 Here is a list of resources, approximately in the order we recommend
118 using them:
119
120 \begin{description}
121 \item [\TeX{} \acro{FAQ}] The \TeX{} \acro{FAQ} is a huge compendium of
122 answers to all sorts of questions, from the most basic to the most
123 arcane. It is included on \TeXLive{} in \OnCD{FAQ/english}, and is
124 available on the Internet through \url{http://faq.tug.org}. Please
125 check here first.
126
127 \item [\TeX{} Catalogue] If you are specifically looking for a package,
128 font, program, etc., the \TeX{} Catalogue is the place to look. It is a
129 huge list of all \TeX{}-related items. See
130 \OnCD{texmf/doc/html/catalogue}, or
131 \url{http://www.ctan.org/tex-archive/help/Catalogue/catalogue.html}.
132
133 \item [\TeX{} Web Resources] This web page has many \TeX{}-related
134 links, in particular for numerous books, manuals, and articles on all
135 aspects of the system: \url{http://tug.org/interest.html}.
136
137 \item [support archives] The two principal forums for support are the
138 Usenet newsgroup \url{news:comp.text.tex} and the mailing list
139 \email{[email protected]}. So, their archives have thousands of past
140 questions and answers for your searching pleasure. See
141 \url{http://groups.google.com/groups?group=comp.text.tex} and
142 \url{http://tug.org/mail-archives/texhax}, respectively. A query on a
143 general web search engine, such as \url{http://google.com}, never hurts.
144
145 \item [posting questions] If you cannot find an answer, you can post to
146 \dirname{comp.text.tex} through Google or your newsreader, or through
147 email to \email{[email protected]}. But before you post, \emph{please}
148 read this \acro{FAQ} entry for advice on asking questions in such a way
149 that you're most likely to get an answer:
150 \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=askquestion}.
151
152 \item [\TeXLive{} support] If you want to report a bug or have
153 suggestions or comments on the \TeXLive{} distribution, installation, or
154 documentation, the mailing list is \email{[email protected]}. However,
155 if your question is about how to use a particular program included in
156 \TeXLive{}, you are better off writing to that program's maintainer or
157 mailing list.
158
159 \end{description}
160
161 The other side of the coin is helping others who have questions. Both
162 \dirname{comp.text.tex} and \code{texhax} are open to anyone, so feel
163 free to join, start reading, and help out where you can. Welcome to
164 \TeX{}!
165
166
167 \section{Structure of \protect\TeXLive}
168 \label{sec:struct-tl}
169
170 The main two installation scripts for Unix and \MacOSX{} are
171 \texttt{install-tl.sh} and \texttt{install-pkg.sh}. We discuss them
172 in section \ref{sec:unix-install} on p.~\pageref{sec:unix-install}.
173 Here, we describe the structure and contents of \TeXLive{}.
174
175
176 \subsection{Multiple distributions: \protect\pkgname{live},
177 \protect\pkgname{inst}, \protect\pkgname{demo}}
178 \label{sec:multiple-dist}
179
180 As of 2003, space limitations of \acro{CD-ROM} format have forced us to
181 divide \TeXLive{} into three distributions, as follows.
182
183 \begin{description}
184
185 \item [live] a complete, runnable system on \acro{DVD}; it is too large
186 for \acro{CD-ROM}. (The \DVD{} also includes a snapshot of the \CTAN{}
187 repository, completely independent of \TeXLive{}.)
188
189 \item [inst(allable)] a complete system on \CD; in order to make it fit,
190 we had to compress everything we could. Therefore, it is not possible
191 to run \TeX\ directly from the installable \CD, you have to install it to
192 disk (hence its name). Installation is described in subsequent sections.
193
194 \item [demo] a live system runnable directly from \CD; in order to make
195 this fit, we omitted the very large collection of \acro{CJK} (Chinese,
196 Japanese, Korean) language support, support for typesetting music, some
197 less-commonly used fonts, and included executables only for Linux,
198 \MacOSX, and Windows systems.
199
200 \end{description}
201
202 \noindent You can tell which type of distribution you're in by looking
203 for a \texttt{00\var{type}.TL} file in this top-level directory.
204
205
206 \subsection{Top level directories}
207
208 Here is a brief listing and description of the top level directories in
209 the \TeXLive{} distribution.
210
211 \smallskip
212 \begin{tabular}{>{\ttfamily}lp{.8\hsize}}
213 bin & The \TeX{} system programs, arranged by platform. \\
214 Books & Examples from some of the books about \TeX\ (see
215 \filename{Books/README}). \\
216 FAQ & Current versions of major FAQ collections. \\
217 info & A few manuals in \acro{GNU} Info format, where available. \\
218 \MacOSX & Supporting software for \MacOSX (see
219 section~\ref{sec:mac-install} on p.~\pageref{sec:mac-install}). \\
220 man & Unix man pages. \\
221 source & The source of all programs, including the main \Webc{}
222 \TeX{} and \MF{} distributions. These are stored in a
223 \cmdname{bzip2}-compressed tar archive. \\
224 support & assorted auxiliary packages and programs. These are
225 \emph{not} installed by default. This includes
226 \cmdname{Ghostscript}, \cmdname{netpbm}, and assorted editors and
227 \TeX\ shells. \\
228 texmf & root of installed packages, fonts, config files, etc. \\
229 usergrps & Material about a few of the \TeX\ user groups. (Visit
230 \url{http://tug.org/usergroups.html} for a current list.) \\
231 xemtex & The \cmdname{XEmacs} editor and other support programs for
232 Windows (see section~\ref{sec:win-xemtex} on p.~\pageref{sec:win-xemtex}).
233 These programs generally come pre-installed on Unix systems, or are
234 at least easy to compile. \\
235 \end{tabular}
236
237
238 \subsection{Extensions to \TeX}
239 \label{sec:tex-extensions}
240
241 \TeXLive{} contains three extended versions of \TeX:
242
243 \begin{description}
244
245 \item [\eTeX] adds a small but powerful set of new primitives
246 \label{text:etex}
247 (related to macro expansion, character scanning, classes of marks,
248 additional debugging features, and more) and the \TeXXeT{} extensions
249 for bidirectional typesetting. In default mode, \eTeX{} is 100\%
250 compatible with ordinary \TeX. See
251 \OnCD{texmf/doc/etex/base/etex_man.pdf}. \eTeX{} is now the default for
252 \LaTeX{} and pdf\LaTeX{}.
253
254 \item [pdf\TeX] writes Acrobat PDF format as well as \dvi{}. The
255 \LaTeX{} \pkgname{hyperref} package has an option `\optname{pdftex}'
256 which turns on all the program features. See
257 \OnCD{texmf/doc/pdftex/pdftex-l.pdf} and
258 \OnCD{texmf/doc/pdftex/base/example.tex}.
259
260 \item [\OMEGA\ (Omega)] based on Unicode (16-bit characters), thus
261 supports working with almost all the world's scripts simultaneously. It
262 also supports so-called `\OMEGA{} Translation Processes' (\acro{OTP}s),
263 for performing complex transformations on arbitrary input. See
264 \OnCD{texmf/doc/omega/base/doc-1.8.tex} (not completely up-to-date).
265
266 \end{description}
267
268
269 \subsection{Other notable programs in \protect\TeXLive}
270
271 Here are a few other commonly-used programs included in \TeXLive{}:
272
273 \begin{cmddescription}
274
275 \item [bibtex] bibliography support.
276
277 \item [makeindex] index support.
278
279 \item [dvips] convert \dvi{} to \PS{}.
280
281 \item [xdvi] \dvi{} previewer for the X Window System.
282
283 \item [dvilj] HP LaserJet driver.
284
285 \item [dv2dt, dt2dv] convert \dvi{} to/from plain text.
286
287 \item [dviconcat, dviselect] cut and paste pages
288 from \dvi{} files.
289
290 \item [dvipdfm] convert \dvi{} to PDF, an alternative approach
291 to pdf\TeX\ (mentioned above). See the \pkgname{ps4pdf} and
292 \pkgname{pdftricks} packages for still more alternatives.
293
294 \item [psselect, psnup, \ldots] \PS{}
295 utilities.
296
297 \item [lacheck] \LaTeX{} syntax checker.
298
299 \item [texexec] Con\TeX{}t and PDF processor.
300
301 \item [tex4ht] \TeX{} to HTML converter.
302
303 \end{cmddescription}
304
305
306 \section{Unix installation}
307 \label{sec:unix-install}
308
309 As introduced in section~\ref{sec:basic} on p.~\pageref{sec:basic},
310 \TeXLive{} has three principal uses:
311
312 \begin{enumerate}
313 \item Run directly from media.
314 \item Install to disk.
315 \item Integrate a particular package or collection into your existing
316 \TeX{} installation.
317 \end{enumerate}
318
319 \noindent The following sections describes the Unix-specific procedures
320 for each of these.
321
322 \ifSingleColumn \begin{figure}[ht]\noindent \fi
323 \begin{warningbox}
324 \textbf{Warning: } The \TK{} \CD{}s and \DVD{} are in ISO 9660 (High Sierra)
325 format, \emph{with} Rock Ridge (and Joliet, for Windows)
326 extensions. Therefore, in order to take full advantage of the \TK{}
327 under Unix, your system needs to be able to use the Rock Ridge
328 extensions. Please consult the documentation for your \cmdname{mount}
329 command to see how to do this. If you have several different machines
330 on a local network, you may be able to mount the \CD{}s on one which
331 does support Rock Ridge, and use this with the others.
332
333 \leavevmode\quad Linux, Free\acro{BSD}, Sun, \acro{SGI} and
334 Alpha systems should be able to use the \CD{}s without problems. We
335 would appreciate receiving detailed advice from users on other systems
336 who succeed, for future versions of this documentation.
337
338 \leavevmode\quad
339 The discussion below assumes you have been able to mount
340 the \CD{}s with full Rock Ridge compatibility.
341 \end{warningbox}
342 \ifSingleColumn\end{figure}\fi
343
344
345 %
346 \subsection{Running \protect\TeXLive{} directly from media (Unix)}
347
348 \def\runlive{% text repeated in windows section
349 It is possible to use the \TeX{} system directly from the \pkgname{demo}
350 \CD{} or the \pkgname{live} \DVD{}, without installing the distribution
351 to disk. (Thus the name `\TeXLive', in fact.) It is \emph{not}
352 possible to run \TeX{} directly from the \pkgname{inst} \CD (see
353 section~\ref{sec:multiple-dist} on p.~\pageref{sec:multiple-dist}).
354 }
355
356 Only Linux, \MacOSX, and Windows binaries are included on the demo \CD;
357 if you want to run live on other Unix systems, you'll need to use the
358 \DVD.
359
360 \def\startinst{% repeated in other subsections
361 To start, we must mount the \CD{} or \DVD{}, with Rock Ridge extensions
362 enabled. The exact command to do this varies from system to system; the
363 following works under Linux, except the name of the device
364 (\filename{/dev/cdrom}, here) may vary. (All our examples will use
365 \texttt{>} as the shell prompt; user input is \underline{underlined}.)
366 \begin{alltt}
367 > \Ucom{mount -t iso9660 /dev/cdrom /mnt/cdrom}
368 \end{alltt}
369
370 \noindent Change the current directory to the mount point:
371 \begin{alltt}
372 > \Ucom{cd /mnt/cdrom}
373 \end{alltt}
374
375 \noindent Under \MacOSX, the directory is typically under
376 \dirname{/Volumes}, and the media will be mounted automatically.
377 }
378
379 \startinst
380
381 Run the installation script \filename{install-tl.sh}:
382 \begin{alltt}
383 > \Ucom{sh install-tl.sh}
384 Welcome to TeX Live...
385 \end{alltt}
386
387 \def\firstinstcommand{%
388 \noindent After various greeting messages and a list of the main menu
389 options, the installation will ask you to enter a command. Do this by
390 typing the desired character and hitting return; don't type the angle
391 brackets. Either uppercase or lowercase is ok; we'll use lowercase in
392 our examples.
393 }
394 \firstinstcommand
395
396 For running live, our first command will be \Ucom{d} and then the
397 subcommand \Ucom{1} to set directories. Even in this case, we must
398 choose a directory on the local disk to place files that the \TeX{}
399 system itself generates, such as fonts and formats, and also to provide
400 a place for updated configuration files, if need be. We'll use
401 \dirname{/usr/local/texmf-local} in this example. (If the default value
402 of \dirname{/usr/TeX} works for you, then you can skip this step.)
403 \begin{alltt}
404 Enter command: \Ucom{d}
405 Current directories setup:
406 <1> TEXDIR: /usr/TeX
407 ...
408 Enter command: \Ucom{1}
409 New value for TEXDIR [/usr/TeX]: \Ucom{/usr/local/texmf-local}
410 ...
411 Enter command: \Ucom{r}
412 \end{alltt}
413
414 \noindent Back at the main menu, our second and last command is
415 \Ucom{r}, to set up for running live off the media without installing
416 to disk:
417 \begin{alltt}
418 Enter command: \Ucom{r}
419 Preparing destination directories...
420 ...
421 Welcome to the TeX Live system!
422 >
423 \end{alltt}
424
425 \noindent And we are back at the system prompt, as shown.
426
427 Next, it is necessary to alter two environment variables:
428 \envname{PATH}, to an architecture-dependent value (so that we can run
429 the programs), and \envname{VARTEXMF}, to the value specified above. See
430 table~\ref{tab:archlist} for a list of the architecture names for the
431 different systems, and whether they are available on the \pkgname{demo}
432 \CD. All systems are available in the \pkgname{inst} and \pkgname{live}
433 distributions. (In addition to the version-specific names listed here,
434 there are generic names without the version numbers. For instance,
435 \dirname{sparc-solaris} links to \dirname{sparc-solaris2.7}. The
436 generic names can be used to protect against the version numbers
437 changing in the future, if you wish.)
438
439 \def\runtexconfig{%
440 After the main installation has completed, and environment variables
441 have been set, the next step is to run \cmdname{texconfig} to customize
442 your installation for your needs. This is explained in
443 section~\ref{sec:texconfig}, p.~\pageref{sec:texconfig}.
444 }
445 \runtexconfig
446
447 \begin{table*}[ht]
448 \caption{Supported system architectures.}
449 \label{tab:archlist}
450 \begin{tabular}{>{\ttfamily}lll}
451 alpha-linux & HP Alpha Linux & \\
452 alphaev5-osf4.0d & HP Alphaev5 OSF & \\
453 %hppa2.0-hpux10.20 & HP9000 HPUX 10.20 & \\
454 i386-freebsd4.8 & Intel x86 FreeBSD & \\
455 i386-linux & Intel x86 GNU/Linux & demo \CD\\
456 i386-openbsd3.3 & Intel x86 OpenBSD & \\
457 i386-solaris2.8 & Intel x86 Solaris & \\
458 mips-irix6.5 & SGI IRIX & \\
459 powerpc-aix4.3.3.0 & IBM RS/6000 AIX & \\
460 powerpc-darwin6.3 & \MacOSX & demo \CD\\
461 sparc-solaris2.7 & Sun Sparc Solaris & \\
462 sparc64-linux & Sun Sparc Linux & \\
463 win32 & Windows (32-bit) & demo \CD\\
464 \hline
465 \end{tabular}
466 \end{table*}
467
468 \label{text:path}
469 The syntax for setting the environment variables, and the initialization
470 file to put them in, depends on the shell you use. If you use a
471 Bourne-compatible shell (\cmdname{sh}, \cmdname{bash}, \cmdname{ksh}, et
472 al.), put the following into your \filename{$HOME/.profile} file:
473 \begin{alltt}
474 PATH=/mnt/cdrom/bin/\Ucom{\emph{archname}}:$PATH; export PATH
475 VARTEXMF=/usr/local/texmf-local/texmf-var; export VARTEXMF
476 \end{alltt}
477
478 \noindent For C shell-compatible shells (csh, tcsh), put the following
479 into your \filename{$HOME/.cshrc} file:
480 \begin{alltt}
481 setenv PATH /mnt/cdrom/bin/\Ucom{\emph{archname}}:$PATH
482 setenv VARTEXMF /usr/local/texmf-local/texmf-var
483 \end{alltt}
484
485 \def\donewithinst{%
486 \noindent Then log out, log back in, and test your installation
487 (see section~\ref{sec:test-install} on p.~\pageref{sec:test-install}).
488 }
489 \donewithinst
490
491 \def\ifindoubt{%
492 If in doubt, please ask any local system gurus to help you with
493 problems; for example, the way to mount the \TeXLive{} media, which
494 directory or directories to use, and precise details of the changes to
495 your personal initialization files can and do vary from site to site.
496 }
497 \ifindoubt
498
499
500 %
501 \subsection{Installing \protect\TeXLive{} to disk}
502 \label{sec:unix-install-disk}
503
504 It is possible, indeed typical, to install the \TeX{} system from the
505 \TeXLive{} to disk. This can be done either from the \pkgname{live}
506 \DVD, or the \pkgname{inst} \CD. It can also be done from the
507 \pkgname{demo} \CD, if you don't need the omitted packages or systems.
508 (See section~\ref{sec:multiple-dist} on p.~\pageref{sec:multiple-dist}
509 for an explanation of the different distributions.)
510
511 \startinst
512
513 Run the installation script \filename{install-tl.sh}:
514 \begin{alltt}
515 > \Ucom{sh install-tl.sh}
516 Welcome to TeX Live...
517 \end{alltt}
518
519 \firstinstcommand
520
521 Here is an introductory list of the options in the main menu. The order
522 in which you select the options makes little difference, except that
523 \Ucom{i} must be last. It's reasonable to go through them in the
524 order presented~here.
525
526 % apparently here.sty [H] doesn't support table*.
527 \begin{table}[H]
528 \caption{Main menu options for the installation.}
529 \label{tab:main-menu-options}
530 \begin{tabular}{>{\ttfamily}ll}
531 p & The system you are running on.\\
532 b & The architectures to install binaries for.\\
533 s & The base installation scheme to use (minimal, recommended,
534 full, etc.)\\
535 c & Override the installation scheme for individual collections.\\
536 l & Override for language collections.\\
537 d & Directories in which to install.\\
538 o & General options.\\
539 i & Perform the installation.\\
540 \end{tabular}
541 \end{table}
542
543 Here are further details on each option.
544
545 \textbf{\optname{p} -- Current platform.} Since the installation script
546 automatically guesses which platform you're running on, this is
547 generally unnecessary to override. It's there in case the automatic
548 detection fails.
549
550 \textbf{\optname{b} -- Binary architectures.} By default, only the
551 binaries for your current platform will be installed. From this menu,
552 you can select installation of binaries for other architectures as well
553 (or not install the current platforms). This is often useful if you
554 are sharing a \TeX\ tree across a network of heterogenous machines. For
555 a list of the supported architectures, see table~\ref{tab:archlist},
556 p.~\pageref{tab:archlist}.
557
558 \textbf{\optname{s} -- Base installation scheme.} From this menu, you
559 can choose an overall common set of packages. The default is a
560 recommended set for typical needs, but you can also choose a basic set
561 to conserve disk space, or a full set to get absolutely everything. The
562 \pkgname{Live} scheme is used for creating the \TeXLive{}
563 \pkgname{demo} distribution itself, and isn't generally useful to select
564 for a particular site. There are also specific sets for Omega and
565 \acro{XML} users.
566
567 \textbf{\optname{c} -- Individual collections.} From this menu, you can
568 override the basic scheme's choice of which collections to install.
569 Each collection\Dash TeX macro files, Metafont font families, and so
570 on\Dash consists of several packages. In this menu, selection letters
571 are case-sensitive.
572
573 \textbf{\optname{l} -- Language collections}. This menu has the same
574 basic functionality as \Ucom{c}, to override collection choices. In
575 this case, the collections are specifically for different languages.
576 Selection letters are case-sensitive here. Here is a list of the
577 language collections in \TeXLive:
578
579 % xx really should generate list from texmf/tpm/collection/tex-lang*
580 % a la install-tl.sh.
581 \begin{tabbing}
582 \hspace{.25\linewidth} \=
583 \hspace{.25\linewidth} \=
584 \hspace{.25\linewidth} \=
585 \hspace{.25\linewidth} \kill
586 (some) African scripts \>
587 Armenian \>
588 Chinese,Japanese,Korean \>
589 Croatian \\
590 Cyrillic \>
591 Czech/Slovak \>
592 Danish \>
593 Dutch \\
594 Finnish \>
595 French \>
596 German \>
597 Greek \\
598 Hungarian \>
599 Indic \>
600 Italian \>
601 Latin \\
602 Manju \>
603 Mongolian \>
604 Norwegian \>
605 Polish \\
606 Portuguese \>
607 Spanish \>
608 Swedish \>
609 Tibetan \\
610 \acro{UK} English \>
611 Vietnamese \\
612 \end{tabbing}
613
614 \noindent Language collections typically includes fonts, macros,
615 hyphenation patterns, and other support files. (For instance,
616 \pkgname{frenchle.sty} is installed if you select the \optname{French}
617 collection.) In addition, installing a language collection will alter
618 the \filename{language.dat} configuration file controlling which
619 hyphenations are loaded.
620
621 \textbf{\optname{d} -- Installation directories}. Three directories can
622 be changed here:
623 \label{text:instdir}
624
625 \begin{ttdescription}
626 \item [TEXDIR] By default, the top-level directory under which
627 everything else will be installed. The default value is
628 \dirname{/usr/TeX}, and is often changed. For example, changing to a
629 value such as \dirname{/usr/local/texlive2003} would make it possible to
630 keep different releases of \TeXLive{} separate. You may then wish to
631 make \dirname{/usr/local/texlive} a symbolic link, after testing the new
632 release.
633
634 Under \MacOSX, the usual frontends look for \TeX{} in
635 \dirname{/usr/local/teTeX}, so you may wish to install \TeXLive{} there.
636
637 \item [TEXMFLOCAL] This tree is where the \TeX{} system scripts install
638 non-version-specific files, primarily fonts. The default value is
639 \dirname{TEXDIR/texmf-local}. It's also the recommended location to put
640 any local packages or configuration settings. Therefore, it's desirable
641 to change it to a location independent of the current \TeXLive{}
642 release; for example, \dirname{/usr/local/texmf-local}.
643
644 \item [VARTEXMF] This tree is where the scripts install files that
645 \emph{are} version-specific, primarily format files and the
646 configuration files which are modified by \cmdname{texconfig} (see
647 section~\ref{sec:texconfig}, p.~\pageref{sec:texconfig}). The default
648 value is \dirname{TEXDIR/texmf-var}, and there's generally no reason to
649 change it.
650
651 \end{ttdescription}
652
653 \textbf{\optname{o} - General options.} From this menu, you can select
654 three general options affecting the installation:
655
656 \begin{ttdescription}
657 \item [a] Specify an alternate directory for generated fonts.
658 The default is to use the \envname{VARTEXMF} tree, as explained above.
659 Setting this is useful if you plan to mount the main tree read-only, and
660 therefore another location (perhaps machine-specific) must be used for
661 dynamically created fonts.
662
663 \item [l] Create symbolic links for the binaries, man pages,
664 and/or \acro{GNU} Info files in other locations. For example, you may
665 wish to make the man pages available under \dirname{/usr/local/man} and
666 the Info files available under \dirname{/usr/local/info}. (Of course
667 you need appropriate privileges to write in the specified directories.)
668
669 \item [d] Skip installation of the font/macro documentation tree.
670 This is useful to save space, or if you've previously installed the
671 documentation elsewhere.
672
673 \item [s] Skip installation of the main font/macro source
674 tree. This is useful if you are arranging to share that tree between
675 machines and/or architectures in some other way, such as \acro{NFS} or
676 \cmdname{automount}.
677
678 \end{ttdescription}
679
680 \textbf{i - Perform installation.} When you're satisfied with your
681 configuration options, enter \Ucom{i} to actually do the installation
682 from the media to your chosen locations.
683
684 The last step is to include the architecture-specific subdirectory of
685 \dirname{TEXDIR/bin} in your
686 \envname{PATH}, so the newly-installed programs can be found. The
687 architecture names are listed in table~\ref{tab:archlist},
688 p.~\pageref{tab:archlist}, or you can simply list the directory
689 \dirname{TEXDIR/bin}.
690
691 The syntax for doing this, and the initialization file to put it in,
692 depends on the shell you use. If you use a Bourne-compatible shell
693 (\cmdname{sh}, \cmdname{bash}, \cmdname{ksh}, et al.), put the following
694 into your \filename{$HOME/.profile} file:
695 \begin{alltt}
696 PATH=/\Ucom{\emph{TEXDIR}}/bin/\Ucom{\emph{archname}}:$PATH; export PATH
697 \end{alltt}
698
699 \noindent For C shell-compatible shells (\cmdname{csh}, \cmdname{tcsh}),
700 put the following into your \filename{$HOME/.cshrc} file:
701 \begin{alltt}
702 setenv PATH /\Ucom{\emph{TEXDIR}}/bin/\Ucom{\emph{archname}}:$PATH
703 \end{alltt}
704
705 \runtexconfig
706
707 Here is a brief annotated example which selects a full installation,
708 with binaries for the current system only, with directory changes as
709 recommended above. The prompts and \acro{RETURN} keys are omitted for
710 brevity.
711
712 \begin{alltt}
713 > \Ucom{sh install-tl.sh}
714 \Ucom{s} \Ucom{b} \Ucom{r} # scheme, full, return to main
715 \Ucom{d} # change directories
716 \Ucom{1} \Ucom{/usr/local/texlive2003} # top-level dir
717 \Ucom{2} \Ucom{/usr/local/texmf-local} # TEXMFLOCAL outside TEXDIR
718 \Ucom{r} # return to main
719 \Ucom{i} # perform installation
720 > \Ucom{texconfig} ...
721 # New PATH, assuming Linux:
722 > \Ucom{PATH=/usr/local/texlive2003/bin/i386-linux:$PATH; export PATH}
723 \end{alltt}
724
725 \ifindoubt
726
727
728 %
729 \subsection{Installing individual packages to disk}
730
731 You can add individual packages or collections from the current
732 distribution to an existing non-\TeXLive{} setup, or an earlier
733 \TeXLive{} installation. You can do this from the \pkgname{demo} \CD{}
734 or the \pkgname{live} \DVD{}, but \emph{not} from the \pkgname{inst}
735 \CD. (See section~\ref{sec:multiple-dist} on
736 p.~\pageref{sec:multiple-dist}.)
737
738 \startinst
739
740 Run the installation script \filename{install-pkg.sh} (not
741 \filename{install-tl.sh}, which is intended for complete installations
742 only):
743 \begin{alltt}
744 > \Ucom{sh install-pkg.sh \emph{options}}
745 \end{alltt}
746
747 This first set of options controls what gets read:
748
749 \begin{ttdescription}
750 \item [-{}-package=\emph{pkgname}] The individual package to work on.
751
752 \item [-{}-collection=\emph{colname}] The individual collection to work on.
753
754 \item [-{}-nodoc] Exclude documentation files from the operation.
755
756 \item [-{}-nosrc] Exclude source files from the operation.
757
758 \item [-{}-cddir=\emph{dir}] Source directory to read from; defaults
759 to the current directory. If you followed the instructions above, that
760 will be the distribution directory, and won't need to be changed.
761
762 \item [-{}-listdir=\emph{dir}] The so-called `lists' directory within
763 \emph{cddir} from which to read the package information. The default is
764 \texttt{\emph{cddir}/texmf/tpm/lists}; the only reason to change it is
765 if you're making changes to \TeXLive{} yourself.
766
767 \end{ttdescription}
768
769 What actually happens is controlled by the following options. If
770 neither of these are specified, the default action is to install the
771 selected files. The main destination tree is found by expanding
772 \envname{\$TEXMFMAIN} with \cmdname{kpsewhich}. You can override it by
773 setting either the environment variable \envname{TEXMFMAIN} or
774 \envname{TEXMF}.
775
776 \begin{ttdescription}
777 \item [-{}-listonly] List the files that would be installed, but don't
778 actually install anything.
779
780 \item [-{}-archive=\emph{tarfile}] Instead of installing the files into
781 the \TeX{} system, make a \cmdname{tar} archive.
782
783 \end{ttdescription}
784
785 Additional options:
786
787 \begin{ttdescription}
788
789 \item [-{}-config] After installation, run \code{texconfig init}.
790
791 \item [-{}-nohash] After installation, don't run \cmdname{mktexlsr} to
792 rebuild the filename database.
793
794 \item [-{}-verbose] Give more information as the script runs.
795
796 \end{ttdescription}
797
798 Here are some usage examples:
799
800 \begin{enumerate}
801
802 \item To see the files in the package \pkgname{fancyhdr} without
803 installing it:
804
805 \begin{alltt}
806 \ifSingleColumn> \Ucom{sh install-pkg.sh --package=fancyhdr --listonly}
807 \else> \Ucom{sh install-pkg.sh --package=fancyhdr \bs}
808 > \Ucom{--listonly}
809 \fi{}
810 texmf/doc/latex/fancyhdr/README
811 texmf/doc/latex/fancyhdr/fancyhdr.dvi
812 texmf/doc/latex/fancyhdr/fancyhdr.pdf
813 ...
814 \end{alltt}
815
816 \item Install the \LaTeX{} package \pkgname{natbib}:
817 \begin{alltt}
818 > \Ucom{sh install-pkg.sh --package=natbib}
819 \end{alltt}
820
821 \item Install the \LaTeX{} package \pkgname{alg} without source files or
822 documentation:
823 \begin{alltt}
824 \ifSingleColumn> \Ucom{sh install-pkg.sh --package=alg --nosrc --nodoc}
825 \else> \Ucom{sh install-pkg.sh -{}-package=alg \bs}
826 > \Ucom{-{}-nosrc -{}-nodoc}
827 \fi\end{alltt}
828
829 \item Install all the packages in the collection of additional
830 plain \TeX\ macros:
831 \begin{alltt}
832 > \Ucom{sh install-pkg.sh --collection=tex-plainextra}
833 \end{alltt}
834
835 \item Write all files in the \pkgname{pstricks} package to a
836 \cmdname{tar} file in \path|/tmp|:
837 \begin{alltt}
838 \ifSingleColumn> \Ucom{sh install-pkg.sh --package=pstricks --archive=/tmp/pstricks.tar}
839 \else
840 > \Ucom{sh install-pkg.sh -{}-package=pstricks \bs}
841 > \Ucom{-{}-archive=/tmp/pstricks.tar}
842 \fi\end{alltt}
843
844 \end{enumerate}
845
846 \ifindoubt
847
848
849 %
850 \section{Post-installation}
851 \label{sec:postinstall}
852
853 After the main installation is done, for any operating system, the
854 remaining steps are to configure the system for your local needs, and
855 perform some basic tests.
856
857 Another sort of post-installation is to acquire packages, fonts, or
858 programs that were not included in \TeXLive{}. The basic idea is to
859 install such additions in the \envname{TEXMFLOCAL} tree (if you
860 installed to disk), or \envname{VARTEXMF} (if you are running live).
861 See ``Installation directories'' on p.~\pageref{text:instdir}.
862
863 Unfortunately, the details can vary widely, and so we do not attempt to
864 address them here. Please see
865 \url{http://www.ctan.org/tex-archive/info/beginlatex/html/chapter5.html#pkginst}
866 for a good description, and
867 \url{http://www.ctan.org/tex-archive/info/Type1fonts} for font creation
868 and installation information in particular.
869
870
871 \subsection{The \protect\cmdname{texconfig} program}
872 \label{sec:texconfig}
873
874 At any time after installation, you can and should use the program
875 \cmdname{texconfig} to configure the system to fit your local needs. It
876 is installed in the architecture-specific subdirectory
877 \texttt{TEXDIR/bin/\emph{arch}} along with everything else.
878
879 If you run it without arguments, it will enter full-screen mode and
880 allow you to view and change options interactively.
881
882 You can also run it with various command-line options. Here are some of
883 the most commonly used:
884
885 \begin{ttdescription}
886
887 \item [texconfig dvips paper letter] Set default paper size for
888 \cmdname{dvips} to be letter-size.
889
890 \item [texconfig xdvi us] Likewise, for \cmdname{xdvi}.
891
892 \item [texconfig rehash] Update all the \TeX{} system filename databases.
893
894 \item [texconfig faq] Show the \teTeX{} \acro{FAQ}.
895 (See also the main \TeX{} \acro{FAQ} in the \dirname{FAQ} subdirectory
896 of \TeXLive.)
897
898 \item [texconfig help] Output help information.
899
900 \end{ttdescription}
901
902 Of course, \cmdname{texconfig} only supports changing a few of the many
903 options and configuration parameters in a \TeX{} system. The main
904 configuration file for the base \Webc{} programs is named
905 \filename{texmf.cnf}. You can find its location by running
906 \samp{kpsewhich texmf.cnf}; it contains many comments explaining the
907 default settings and useful alternatives.
908
909
910 \subsection{Testing the installation}
911 \label{sec:test-install}
912
913 After installing \TeXLive{} as best you can, you naturally want to test
914 it out, so you can start creating beautiful documents and/or fonts.
915
916 This section gives some basic procedures for testing that the new system
917 is functional. We described the Unix commands; under \MacOSX{} and
918 Windows, you're more likely to run the tests through a graphical
919 interface, but the principles are the same.
920
921 \begin{enumerate}
922
923 \item Make sure that you can run the \cmdname{tex} program in the first
924 place:
925
926 \begin{alltt}
927 > \Ucom{tex -{}-version}
928 TeX (Web2c 7.5.2) 3.141592
929 kpathsea version 3.5.2
930 Copyright (C) 1997-2003 D.E. Knuth.
931 ...
932 \end{alltt}
933 If this comes back with `command not found' instead of version and
934 copyright information, most likely you don't have the correct
935 \dirname{bin} subdirectory in your \envname{PATH}. See
936 the environment-setting information on p.~\pageref{text:path}.
937
938 \item Process a basic \LaTeX{} file:
939 \begin{alltt}
940 > \Ucom{latex sample2e.tex}
941 >TeX (Web2c 7.5.2) 3.141592
942 ...
943 Output written on sample2e.dvi (3 pages, 7256 bytes).
944 Transcript written on sample2e.log.
945 \end{alltt}
946 If this fails to find \filename{sample2e.tex} or other files, perhaps
947 you have interference from old environment variables or configuration
948 files. For a deep analysis, you can always ask \TeX{} to report on
949 exactly what it is searching for, and finding; see ``Debugging actions''
950 on page~\pageref{Debugging}.
951
952 \item Preview the result online:
953 \begin{alltt}
954 > \Ucom{xdvi sample2e.dvi}
955 \end{alltt}
956 Under Windows, the analogous command is \cmdname{windvi}. You should
957 see a new window with a nice document explaining some of the basics of
958 \LaTeX{}. (Well worth reading, if you're new to the system.) You do
959 have to be running under X for \cmdname{xdvi} to work; if you're not, or
960 your \envname{DISPLAY} environment variable is set incorrectly, you'll
961 get an error \samp{Can't open display}.
962
963 \item Create a \PS{} file for printing or display:
964 \begin{alltt}
965 > \Ucom{dvips sample2e.dvi -o sample2e.ps}
966 \end{alltt}
967
968 \item Create a \acro{PDF} file instead of \dvi{}; this processes the
969 \filename{.tex} file and writes \acro{PDF} directly:
970 \begin{alltt}
971 > \Ucom{pdflatex sample2e.tex}
972 \end{alltt}
973
974 \item Preview the \acro{PDF} file:
975 \begin{alltt}
976 > \Ucom{gv sample2e.pdf}
977 \textrm{or:}
978 > \Ucom{xpdf sample2e.pdf}
979 \end{alltt}
980 Unfortunately neither \cmdname{gv} nor \cmdname{xpdf} are currently
981 included in \TeXLive{}, so you must install them separately. See
982 \url{http://wwwthep.physik.uni-mainz.de/~plass/gv} and
983 \url{http://www.foolabs.com/xpdf}, respectively.
984
985 \item Other standard test files you may find useful:
986
987 \begin{ttdescription}
988 \item [docstrip.tex] Produce \TeX{} source or documentation from a
989 \samp{.dtx} file.
990 \item [small2e.tex] A simpler document than \filename{sample2e}, to
991 reduce the input size if you're having troubles.
992 \item [testpage.tex] Test if your printer introduces any offsets.
993 \item [nfssfont.tex] For printing font tables and tests.
994 \item [testfont.tex] Also for font tables, but using plain \TeX{}.
995 \item [story.tex] The most canonical (plain) \TeX{} test file of all.
996 You must type \samp{\bs bye} to the \code{*} prompt after \samp{tex
997 story.tex}.
998 \end{ttdescription}
999 You can process these in the same way as we did with
1000 \filename{sample2e.tex}.
1001
1002 \end{enumerate}
1003
1004 If you are new to \TeX{}, or otherwise need help with actually
1005 constructing \TeX{} or \LaTeX{} documents, please visit
1006 \url{http://tug.org/begin.html}. We especially recommend the
1007 \textsl{Formatting Information} manual by Peter Flynn, available at
1008 \url{http://www.ctan.org/tex-archive/documentation/beginlatex}.
1009
1010
1011 \section{\MacOSX{} installation}
1012 \label{sec:mac-install}
1013
1014 \TeXLive{} supports \MacOSX, but no prior Macintosh versions. (If you
1015 are running an older Mac version, you can view the files by installing
1016 the Joliet system extension available from
1017 \url{http://www.tempel.org/joliet}; however, the \TeXLive{} binaries
1018 will not run.)
1019
1020 Installation of \TeX{} under \MacOSX{} can be done in two ways:
1021
1022 \begin{enumerate}
1023 \item With the \filename{install*} scripts, as with Unix.
1024 \item With the \cmdname{i-Installer} included in
1025 \filename{MacOSX/II2.dmg}.
1026 \end{enumerate}
1027
1028 \noindent Each of these is described in a following section.
1029
1030 In addition, typical use of \TeX{} under \MacOSX\ goes through a
1031 \emph{frontend}. This is also described below.
1032
1033
1034 \subsection{\protect\cmdname{i-Installer}: Internet installation}
1035 \label{sec:i-Installer}
1036
1037 The \cmdname{i-Installer} is included in the \TeXLive{} distribution as
1038 an alternative to normal installation. It does not use the contents of
1039 the \TeXLive{} distribution at all; instead, the system (approximately
1040 70 megabytes) is downloaded over the Internet.
1041
1042 One advantage of \cmdname{i-Installer} is that it makes updates
1043 relatively painless. If you are interested, please see the
1044 \cmdname{i-Installer} \TeX{} home page at \url{http://www.rna.nl/tex.html}.
1045
1046 To use it, mount \filename{./MacOSX/II2.dmg}. Read the documentation,
1047 launch it, and install at least \emph{TeX Foundation} and \emph{TeX
1048 Programs}. The first will finish without configuration, as soon as the
1049 second is installed you will be presented with a graphical interface to
1050 setting up your \TeX{} system.
1051
1052 The \cmdname{i-Installer} distribution uses the \teTeX{} \dirname{texmf}
1053 tree with some additions. Due to differences between \TeXLive{} and
1054 \teTeX{} you cannot update a \TeXLive{} installation with an
1055 \cmdname{i-Installer} \emph{TeX Programs} i-Package.
1056
1057
1058 \subsection{\protect\cmdname{install*.sh}: \protect\TeXLive{} installation}
1059
1060 In order to run the installation scripts under \MacOSX, you need to have
1061 the \cmdname{bash} shell installed. If you are running \MacOSX~10.2
1062 or later, you have \cmdname{bash}, and can proceed. If you're running
1063 an earlier \MacOSX{} version, however, the default shell is
1064 \cmdname{zsh}, which won't work; please see the
1065 subsection~\ref{sec:mac-bash} (p.~\pageref{sec:mac-bash}) below for
1066 instructions on installing bash \cmdname{bash}.
1067
1068 Once you have \cmdname{bash}, the Unix installation documentation in the
1069 previous section can be followed. See section~\ref{sec:unix-install} on
1070 p.~\pageref{sec:unix-install}; \MacOSX-specific notes are included where
1071 needed.
1072
1073
1074 \subsection{\MacOSX{} frontends}
1075
1076 Using \TeX{} on a Macintosh typically goes through a front end program,
1077 comprising an execution shell, editor, previewer, and other facilities.
1078 Here are the principal frontends:
1079
1080 \begin{cmddescription}
1081 \item [TeXShop] Included in \TeXLive{} as
1082 \filename{./MacOSX/texshop.dmg}. See
1083 \url{http://www.uoregon.edu/~koch/texshop/texshop.html}.
1084
1085 \item [ITeXMac] Included in \TeXLive{} as
1086 \filename{./MacOSX/iTeXMac-*.dmg}. See
1087 \url{http://itexmac.sourceforge.net}.
1088
1089 \item [Mac-emacs] A port of Emacs to \MacOSX{}, integrating
1090 \pkgname{AucTeX}. See \url{http://www.cs.man.ac.uk/~franconi/mac-emacs}.
1091
1092 \end{cmddescription}
1093
1094 The frontends use \dirname{/usr/local/teTeX} as the default location;
1095 therefore, you must either install \TeXLive{} there, or change the
1096 configuration of the frontend.
1097
1098
1099 \subsection{\cmdname{bash} installation for older \MacOSX{} versions}
1100 \label{sec:mac-bash}
1101
1102 \MacOSX{} versions 10.1 and earlier do not include \cmdname{bash} by
1103 default, and the default shell does not run the \TeXLive{} installation
1104 scripts properly. This section explains how to install \cmdname{bash}.
1105
1106 First, check if bash is already installed. `Launch Terminal'
1107 (\filename{/Applications/utilities/Terminal}) and type \code{rehash;
1108 which bash}. If the answer is a filename (for example,
1109 \code{/bin/bash}), then \cmdname{bash} is already installed, and you're done
1110 here; go back to the main installation instructions.
1111 If the answer is \code{bash: command not found}, proceed here.
1112
1113 There are two ways to install \cmdname{bash} if you need it\Dash via the
1114 \acro{GUI} or via command line.
1115
1116 To install via \acro{GUI}, double-click the \filename{MacOSX/bash.dmg}
1117 file in \TeXLive{}. The disk image (volume) will be mounted. Then
1118 start the \cmdname{i-Installer} application on that volume. You will be
1119 asked to authenticate; if you have never seen that before, you might not
1120 have enough privileges to install. Just enter your own user name and
1121 password. Hit install. Bash will be installed on your system.
1122
1123 To install via command line:
1124 \begin{enumerate}
1125 \item ensure you have admin privileges: log in as the
1126 \code{admin} user, the System Administrator, a user with Admin
1127 privileges, using \cmdname{sudo}, etc.
1128
1129 \item copy \filename{MacOSX/bash.tar.gz} from the \TeXLive{}
1130 distribution to your home directory.
1131
1132 \item Launch Terminal, and run:
1133 \begin{alltt}
1134 (cd /usr/local/; sudo tar xvzf ~/bash.tar.gz)
1135 \end{alltt}
1136 You'll be asked for your password, and then \cmdname{bash} will be
1137 installed.
1138
1139 \item Quit Terminal.
1140
1141 \end{enumerate}
1142
1143 After using either installation method, be sure to recheck that
1144 \cmdname{bash} is installed with \code{rehash; which bash} in a new
1145 Terminal window.
1146
1147
1148 \section{Windows installation}
1149 \label{sec:win-install}
1150
1151 \TeXLive{} can be installed on systems running Windows 9x, \acro{ME},
1152 \acro{NT}, \acro{2K} or \acro{XP}. Older versions of Windows (3.1x)
1153 and \acro{MS-DOS} are not supported.
1154
1155 It is necessary to have your Windows set up so that it uses the
1156 Microsoft Joliet extensions for reading \CD{}s; simply look at the \CD{}
1157 in Explorer and see whether it shows long, mixed-case, file names. If it
1158 does not, you must install the Joliet extensions.
1159
1160 The Windows \TeX{} system included in \TeXLive{} is no more and no less
1161 than the \fpTeX{} distribution. It includes a \texttt{dvi} previewer,
1162 \textsf{Windvi}, which is similar in usage to the established Unix
1163 \textsf{xdvi}. The documentation can be found in
1164 \OnCD{texmf/doc/html/windvi/windvi.html}.
1165
1166 \subsection{The \texttt{TeXLive.exe} program}
1167
1168 \begin{figure*}
1169 \begin{center}
1170 \ifnum \Status=1
1171 \includegraphics[width=.7\textwidth]{../pictures/Welcome-to-TeXLive}
1172 \else
1173 \ifnum \Status=2
1174 \includegraphics[bb=0 0 551 534]{../pictures/Welcome-to-TeXLive.jpg}
1175 \else
1176 \includegraphics[width=.7\textwidth]{../pictures/Welcome-to-TeXLive}
1177 \fi
1178 \fi
1179 \end{center}
1180 \caption{``Welcome to \TeXLive'' window}\label{graph:welcome}
1181 \end{figure*}
1182
1183 If your computer is configured to let the \CD{} autostart, then a dialog
1184 box with a menu bar will popup on the screen, and you will have several
1185 choices from there:
1186
1187 \begin{itemize}
1188 \item Install \TeX{} on your hard disk
1189 \item Do maintenance on your \TeX{} system.
1190 \item Remove the \TeX{} system.
1191 \item Use \TeX{} off the \TeXLive{} \CD{} or \DVD{}.
1192 \item Browse documentation: \TeXLive{} documentation, TUG web
1193 pages, \fpTeX web pages.
1194 \item Run the \cmdname{TeXdocTK} application to find specific documentation.
1195 \end{itemize}
1196
1197 If your \CD{} does not autostart, you can explicitly run the program
1198 by double clicking on \path|bin/win32/TeXLive.exe| on the \CD{} from
1199 the explorer window.
1200
1201 \subsection{Running \protect\TeXLive{} directly from media (Windows)}
1202
1203 \runlive
1204
1205 To run live under Windows, from the menu, chose \verb|Explore CD-Rom|, then
1206 \verb|Run TeX off CD-Rom|. This will launch the \cmdname{XEmacs} editor.
1207
1208 %% To run live under Windows, do the following:
1209
1210 %% \begin{enumerate}
1211 %% \item from the menu, chose \verb|Explore CD-Rom|, then
1212 %% \verb|Run TeX off CD-Rom|, that will launch the \cmdname{XEmacs} editor.
1213
1214 %% This program needs to be a \TeX{} oriented editor. It must be able
1215 %% to run the \TeX{} compiler, previewer and any other needed tool. If
1216 %% you don't have one already installed on your system, you can install
1217 %% one from the \CD{}, details section~{\ref{sec:texlive-install}}.
1218
1219 %% \emph{There is no way we can guess if the program you will
1220 %% select is actually a text editor, so be careful}.
1221 %% Here is a list of frequently used \TeX{} editors:
1222 %% \begin{center}
1223 %% \begin{tabular}[H]{ll}
1224 %% GNU Emacs & \path|c:\Program Files\NTEmacs\bin\runemacs.exe| \\
1225 %% XEmacs & \path|c:\Program Files\XEmacs\XEmacs-21.2\i586-pc-win32\xemacs.exe| \\
1226 %% WinShell & \path|c:\Program Files\WinShell\WinShell.exe| \\
1227 %% WinEdt & \path|c:\Program Files\WinEdt Team\WinEdt\WinEdt.exe|\\
1228 %% TeXnicCenter & \path|c:\Program Files\TeXnicCenter\TEXCNTR.exe|
1229 %% \end{tabular}
1230 %% \end{center}
1231 %% The program
1232 %% selected will be memorized as the editor to use for future runs.
1233
1234 %% \item from the menu, chose \verb|Explore CD-Rom|, then
1235 %% \verb|Run TeX off CD-Rom|. The environment will be modified, a small
1236 %% temporary directory created and some configuration files copied
1237 %% there. Then, the selected editor selected will be launched, and you
1238 %% will be able to type in some text, let \TeX{} typeset it and the
1239 %% view it or print it.
1240
1241 %% If Ghostscript is not detected on your machine, you will be warned
1242 %% that rendering your DVI files might fail. You can install it from
1243 %% the \path|Install|, \path|Support| menu item. See
1244 %% section~\ref{sec:texlive-install} for details.
1245
1246 %% \item you can select a different text editor any time you want.
1247
1248 %% \item if you chose \verb|Cleanup CD-Rom setup|, everything \TeX{}
1249 %% needed will be removed, comprised the selection of your text
1250 %% editor, but not the extra packages you may have downloaded and
1251 %% installed. If you installed \cmdname{WinShell} or \cmdname{NTEmacs},
1252 %% they won't be removed.
1253 %% \end{enumerate}
1254
1255 XEmacs startup file will set the environment variables needed. XEmacs will also
1256 setup a temporary \acro{TDS} compliant texmf tree in the temporary area of your
1257 computer. It is needed to store files that may be built on the fly, such as
1258 \path|pk| bitmap fonts, or format files. Configuration files are copied from
1259 the \CD{} to this texmf tree, so that you can edit them if needed. The
1260 \path|ls-R| database is computed for this texmf tree. The AUC-\TeX{} mode will
1261 be entered Whenever you will visit or create a \TeX{} file, providing all the
1262 bells and whistles for \TeX{} support XEmacs is capable of.
1263
1264 If you run 'M-x shell' within XEmacs, then you will have access to all the TeXLive
1265 tools from the command line provided by XEmacs.
1266
1267 \smallskip {\small\noindent \textbf{[For advanced users:]} You can also
1268 use the small batch file \path|mkloctex.bat| to be called in a
1269 directory \path|bin\win32| of the \CD. From the Start menu select
1270 `Run', then browse the \acro{CD} drive and select
1271 \path|mkloctex.bat|. Before starting it, you should add two parameters
1272 separated by a space: the letter of your \acro{CD} drive and the
1273 letter of the drive where you want to install the \TeX\ directory.
1274 The whole line should read, e.g., \verb+d:\bin\win32\mkloctex.bat d c+.
1275 When installation is complete, please read carefully the information
1276 on screen. If you are running Windows 9x/\acro{ME}, then you will have to
1277 restart Windows.}
1278
1279 \subsection{Support packages for Windows}
1280 \label{sec:win-xemtex}
1281
1282 To be complete, a \TeXLive installation needs support packages that are not
1283 commonly found on a Windows machine.
1284 Many scripts are written using the Perl language. Some important tools require
1285 the Ghostscript \PS{} interpreter to render or to convert files. A graphic
1286 file toolbox is also needed in some cases. Last but not least, a \TeX-oriented
1287 editor makes it easy to type in your \TeX{} files.
1288
1289 All these tools are quite easy to find for Windows, but in order to try to make
1290 your life even easier, we have put such a set of tools on \TeXLive:
1291 \begin{itemize}
1292 \item \cmdname{Ghostscript} 7.07
1293 \item a minimal \cmdname{Perl} 5.8, sufficient to run all the \TeXLive{}
1294 Perl scripts
1295 \item a subset of \cmdname{ImageMagick} 5.5.6
1296 \item the \cmdname{ISpell} checker
1297 \item \cmdname{XEmacs} 21.5.14 with a selection of packages to support
1298 \TeX{} typesetting.
1299 \end{itemize}
1300
1301 These packages should be installed only all at once. The bundle is
1302 known as the \XEmTeX{} bundle.
1303
1304 If you didn't install \XEmTeX{}, \cmdname{Perl} and \cmdname{Ghostscript} are
1305 installed anyway if they are not detected on your machine. This is because they are
1306 required by many important tools. The \envname{PERL5LIB} and \verb|GS_LIB|
1307 environment variables will be set too.
1308
1309 When you are under
1310 \cmdname{XEmacs}, the tools provided shadow any other version you might
1311 have installed previously. The point here is that \path|TeXSetup.exe|
1312 will not install anything outside of the \TeXLive location, neither will
1313 it run foreign installers, nor will it try to autodetect installed
1314 products using unreliable rules of thumb. The \XEmTeX{} bundle is
1315 standalone and is meant to evolve in the future. The reference site is
1316 \url{http://www.fptex.org/xemtex/}.
1317
1318 If you don't want to install this bundle, then you are on your own to
1319 install the required tools to complete your \TeXLive{} system. Here is a
1320 list of places to get those tools:
1321
1322 \begin{description}
1323 \item[Ghostscript] \url{http://www.cs.wisc.edu/~ghost/}
1324 \item[Perl] \url{http://www.activestate.com/} (but you might need some
1325 supplementary packages from CPAN: \url{http://www.cpan.org/})
1326 \item[ImageMagick] \url{http://www.imagemagick.com}
1327 \item[NetPBM] alternatively, you could use NetPBM instead of ImageMagick to
1328 process or convert your graphic files. NetPBM home page is
1329 \url{http://netpbm.sourceforge.net/}
1330 \item[\TeX-oriented editors] There is a wide choice, and it is a matter of the
1331 user's taste. Here is a selection:
1332 \begin{itemize}
1333 \item \cmdname{GNU Emacs} is available natively under Windows, the
1334 reference url is
1335 \url{http://www.gnu.org/software/emacs/windows/ntemacs.html}
1336 \item \cmdname{XEmacs} is available natively under Windows, the
1337 reference url is \url{http://www.xemacs.org/}
1338 \item \cmdname{WinShell} is available on \TeXLive in the \path|support|
1339 directory, the reference url is \url{http://www.winshell.de}
1340 \item \cmdname{WinEdt} is shareware available from \url{http://www.winedt.com}
1341 \item TeXnicCenter is available from
1342 \url{http://www.toolscenter.org/products/texniccenter/}
1343 \item \cmdname{Vim} is available on \TeXLive{} in the
1344 \path|support\vim| directory and the
1345 reference site is \url{http://www.vim.org}
1346 \item \cmdname{SciTE} is available from \url{http://www.scintilla.org/SciTE.html}
1347 \end{itemize}
1348 \end{description}
1349
1350 You might want to install other tools that are not free\footnote{Not
1351 free, that is, in the sense of freedom to modify and redistribute,
1352 following Debian's guidelines. This does not mean you can't acquire
1353 them for no money.} and therefore not included on \TeXLive{}, such as
1354 \cmdname{GSView}, the \cmdname{Ghostscript} companion to more
1355 conveniently view PS/PDF files. \cmdname{GSView} is available from
1356 \url{http://www.cs.wisc.edu/~ghost/gsview/} or any \acro{CTAN} site.
1357
1358 %% \subsection{Installing editors or support packages}
1359 %% \label{sec:texlive-install}
1360
1361 %% You can use the \path|TeXSetup.exe| program to install a
1362 %% single (not \TeX{}-dependent) package. This might be an editor
1363 %% such as \cmdname{WinShell} or \cmdname{NTEmacs},
1364 %% or a support package like \cmdname{NetPBM}
1365 %% (graphics formats conversion) or \cmdname{Ghostscript}.
1366
1367 %% Some of the packages are not free, or not with the same meaning as for
1368 %% the rest of the \CD{}. These packages have been made available through
1369 %% the Internet. You need to enable an Internet connection in order to
1370 %% install them. Chosing the \path|Enable Internet access| subitem will
1371 %% search your system for an active Internet connection, or start one if
1372 %% possible. \emph{If your computer is not connected to the Internet,
1373 %% then the timeout might be long, 30s or more}. So try to enable it
1374 %% only if you know you have a connection.
1375
1376 %% Only a few packages are available from the \CD{}, but the most
1377 %% important of them: \cmdname{NTEmacs} and \cmdname{WinShell} for the
1378 %% editors, \cmdname{Ghostscript} and \cmdname{NetPBM} for the other
1379 %% support packages. \cmdname{NetPBM} is needed for running \TeX{}4ht.
1380
1381 %% The downloadable packages are sometimes huge: \cmdname{Perl} is 10Mb,
1382 %% \cmdname{XEmacs} is 50Mb, so be warned that it can take a lot of time
1383 %% to install such things. \path|TeXSetup.exe| does not yet provide an
1384 %% estimation of the time needed to complete the download.
1385
1386 %% When installing these packages, \path|TeXSetup| is working in
1387 %% unattended mode. However, the programs that have their own installer
1388 %% like WinEdt or Ghostscript for example will require human interaction.
1389
1390 %% Those packages who have no specific installer will be unpacked and configured
1391 %% for your system. You will be required to select some directory where
1392 %% they will be installed. The directory to select should be the root
1393 %% directory of the whole installation. Assuming you want to install
1394 %% NTEmacs and NetPBM, the archive files already contain the
1395 %% \path|NTEmacs\| and \path|NetPBM\| part, so the directory you have to
1396 %% select is something like \path|c:\Local| or \path|c:\Program Files|.
1397
1398 \subsection{Installing \TeXLive{} to disk}
1399
1400 \textbf{Warning: Win9x users must ensure they have enough environment
1401 space before undertaking installation. The \cmdname{TeXSetup.exe}
1402 program won't change the environment size for them. A few environment
1403 variables will be created and it is possible you run out of
1404 environment space. Add "SHELL=<path>COMMAND.COM /E:4096 /P" in the
1405 config.sys file in order to increase your environment size.}
1406
1407 Installation is started by letting the media autostart. The program run
1408 is \path|TeXSetup.exe| if you are using the inst disk. If you are using
1409 the live or the demo disk, you will have to select the item
1410 \path|TeXLive Software| from the menu, then the subitem \path|Install on
1411 Hard Disk|. This will invoke \path|TeXSetup.exe|. You can also find it
1412 in the \path|bin/win32| directory and run it, if the autostart fails for
1413 any reason. \path|TeXSetup.exe| is a Windows wizard and it will display
1414 several pages while running.
1415
1416 \begin{description}
1417 \item[Welcome Page]
1418 You can choose a \emph{quick} installation from
1419 here. In this case, the installation will run without any human
1420 assistance from beginning to end, with all the default settings
1421 (Figure~\ref{graph:setup-src},
1422 \ifnum \Status = 1
1423 on the left%
1424 \else\ifnum \Status=2
1425 at the top%
1426 \else
1427 on the left%
1428 \fi\fi
1429 ). If you have enough privileges (administrator or power user
1430 rights) under a Windows version where this is applicable, then you can
1431 decide to install the \TeXLive{} for all users or for yourself only by
1432 checking the appropriate box.
1433 For installing the whole \XEmTeX{} bundle (XEmacs, Ghost\-script,
1434 Perl, ImageMagick and Ispell) you can check \emph{Install XEmTeX
1435 Support} box.
1436 \begin{figure*}[!htb]
1437 The \cmdname{TeXSetup} Wizard\hfill
1438 Source directories for the \TeXLive{} files
1439
1440 \begin{center}
1441 \ifnum \Status=1
1442 \includegraphics[width=.48\textwidth]{../pictures/setup-wizard.jpg}\hfill%
1443 \includegraphics[width=.48\textwidth]{../pictures/source-for-texlive.jpg}
1444 \else
1445 \ifnum \Status=2
1446 \includegraphics[bb=0 0 506 403]{../pictures/setup-wizard.jpg}
1447 \includegraphics[bb=0 0 506 403]{../pictures/source-for-texlive.jpg}
1448 \else
1449 \includegraphics[width=.48\textwidth]{../pictures/setup-wizard}%
1450 \hfill%
1451 \includegraphics[width=.48\textwidth]{../pictures/source-for-texlive}
1452 \fi
1453 \fi
1454 \caption{The \TeXLive{} setup wizard}\label{graph:setup-src}
1455 \end{center}
1456 \end{figure*}
1457 \item[Source Page]
1458 This page is a bit complex. It will allow you to select two source
1459 directories for your \TeXLive{} system
1460 (Figure~\ref{graph:setup-src},
1461 \ifnum \Status = 1
1462 on the right%
1463 \else\ifnum \Status=2
1464 at the bottom%
1465 \else
1466 on the right%
1467 \fi\fi
1468 ). You will need a \emph{local
1469 source directory} and possibly a \emph{remote source directory}.
1470
1471 Why do we need both these directories? The files consisting of the
1472 \TeXLive{} system are on the \CD{}, of course, but some other useful
1473 packages are not, either because of space lacking or because their
1474 license was not compatible with \TeXLive{}. You need to enable Internet
1475 downloading if you want to install these packages that are marked with a
1476 specific ``remote'' icon.
1477
1478 However, don't panic: the default parameters of the setup will allow
1479 you to install a full system using the \CD{} only. Simply, you won't
1480 have \file{WinEdt} (for example), but you will be able to install it
1481 later.
1482
1483 So you can take your files from:
1484 \begin{itemize}
1485 \item the \CD{} or any similar flat tree of files, available through
1486 some standard directory (this means the \CD{} can be mounted on
1487 some remote machine and be made available through network
1488 sharing),
1489 \item a set of \file{.zip} files (this is the case when you are
1490 installing from the demo \CD{} or the \fpTeX{} distribution),
1491 \item the Internet; in this case, the program takes care of
1492 downloading the \file{.zip} files it needs for you.
1493 \end{itemize}
1494 This option is available only if you enable Internet file
1495 downloading in the right part of the page. You also need to
1496 configure this Internet access by selecting to connect either using
1497 Internet Explorer~5 \file{wininet.dll}, or using a direct connection (\texttt{ftp},
1498 \texttt{http}).
1499 % or using a proxy server.
1500 % Last, you can be assisted in defining the \emph{local source
1501 % directory} and \emph{remote source directory} which will be used
1502 % to copy the files onto your hard disk. The \texttt{browse} buttons
1503 % allow to select a directory for the former, and an url among a list
1504 % of mirrors for the latter.
1505 \item[Root Page]
1506 On this page, you will tell where you want the files to be
1507 installed (Figure~\ref{graph:root-schm},
1508 \ifnum \Status = 1
1509 on the left%
1510 \else\ifnum \Status=2
1511 at the top%
1512 \else
1513 on the left%
1514 \fi\fi
1515 ). Only the root directory really matters, the other ones
1516 are set according to the root one. You may want to make
1517 \path|$TEXMFEXTRA| point to some TDS compliant directory with other
1518 \TeX{} files or assign a different value to
1519 \path|$HOMETEXMF|, which is set by default to whatever Windows think
1520 is your `HOME' location.
1521 \begin{figure*}[!htb]
1522 Root and directories\hfill%
1523 Scheme selection
1524 \begin{center}
1525 \ifnum \Status=1
1526 \includegraphics[width=.46\textwidth]{../pictures/root-of-installation.jpg}\hfill%
1527 \includegraphics[width=.46\textwidth]{../pictures/scheme-selection.jpg}
1528 \else
1529 \ifnum \Status=2
1530 \includegraphics[bb=0 0 506 403]{../pictures/root-of-installation.jpg}
1531 \includegraphics[bb=0 0 506 403]{../pictures/scheme-selection.jpg}
1532 \else
1533 \includegraphics[width=.46\textwidth]{../pictures/root-of-installation}%
1534 \hfill%
1535 \includegraphics[width=.46\textwidth]{../pictures/scheme-selection}
1536 \fi
1537 \fi
1538 \caption{\TeXLive-Setup: Root and directories / Schemes}\label{graph:root-schm}
1539 \end{center}
1540 \end{figure*}
1541 \item[Get TPM Page]
1542 This page does not require any manual intervention. The \file{.tpm}
1543 files which describe collections and packages are retrieved
1544 (possibly from the Internet), unzipped if needed and parsed.
1545 \item[Schemes Page]
1546 On this page, you will select the global scheme of your
1547 installation (Figure~\ref{graph:root-schm},
1548 \ifnum \Status = 1
1549 on the right%
1550 \else\ifnum \Status=2
1551 at the bottom%
1552 \else
1553 on the right%
1554 \fi\fi
1555 ). A scheme is a large set of files targeted at some kind
1556 of usage. There are 3 generic schemes for basic, recommended and
1557 full installation. The other ones are devoted to LUGs (what GUST or
1558 GUTenberg propose for their members) or applications (XML and
1559 \TeX{}).
1560 When a scheme is selected, it is still possible to refine the
1561 selection by checking the appropriate box. If doing so, you will be
1562 presented the packages page to change your selection, else you will
1563 jump to the review page.
1564 \item[Packages Page]
1565 Collections and packages are presented in a tree form
1566 (Figure~\ref{graph:win32-support},
1567 \ifnum \Status = 1
1568 on the left%
1569 \else\ifnum \Status=2
1570 at the top%
1571 \else
1572 on the left%
1573 \fi\fi
1574 ). The links
1575 in the tree are dependency links. Collections \emph{depend on}
1576 packages and maybe other collections, and it is the same for each
1577 package. You can select any package or collection individually, but
1578 your request will be granted only if the object is not requested by
1579 another one which is selected. For example, you can't deselect
1580 \texttt{tex-basic} without deselecting all the collections that
1581 request it.
1582
1583 The \texttt{tex-xemtex} collection displayed on the picture is Win32 specific. It
1584 holds a number of bonus packages (Figure~\ref{graph:win32-support},
1585 \ifnum \Status = 1
1586 on the right%
1587 \else\ifnum \Status=2
1588 at the bottom%
1589 \else
1590 on the right%
1591 \fi\fi
1592 ) which can be installed
1593 automatically and individually: Ghostscript (the \PS{}
1594 interpreter), XEmacs editor preconfigured for \TeX{}, tools like Perl,
1595 ImageMagick, Ispell. \emph{None of these packages are selected by
1596 default}.
1597
1598 On this page, you also have the information about disk space
1599 needed, for each object, and for the set of those who are selected,
1600 and also the disk space available on the partition selected for the
1601 installation. Last, you can choose to install or not the
1602 documentation files and source files associated with each package.
1603 \item[Review Page]
1604 You will find there a summary of your choices
1605 (Figure~\ref{graph:review},
1606 \ifnum \Status = 1
1607 on the left%
1608 \else\ifnum \Status=2
1609 at the top%
1610 \else
1611 on the left%
1612 \fi\fi
1613 ). It is still possible to
1614 go back to change them.
1615 \begin{figure*}[!htb]
1616 Packages Page\hfill%
1617 Win32 Support
1618 \begin{center}
1619 \ifnum \Status=1
1620 \includegraphics[width=.48\textwidth]{../pictures/package-selection}\hfill%
1621 \includegraphics[width=.48\textwidth]{../pictures/win32-support}
1622 \else
1623 \ifnum \Status=2
1624 \includegraphics[bb=0 0 506 403]{../pictures/package-selection.jpg}\hfill%
1625 \includegraphics[bb=0 0 506 403]{../pictures/win32-support.jpg}
1626 \else
1627 \includegraphics[width=.48\textwidth]{../pictures/package-selection}%
1628 \hfill%
1629 \includegraphics[width=.48\textwidth]{../pictures/win32-support}
1630 \fi
1631 \fi
1632 \end{center}
1633 \caption{Packages Page / Win32 goodies}
1634 \label{graph:win32-support}
1635 \end{figure*}
1636 \item[Files Copy Page]
1637 The selected files are copied on your hard disk (Figure~\ref{graph:file-copy},
1638 \ifnum \Status = 1
1639 on the right%
1640 \else\ifnum \Status=2
1641 at the bottom%
1642 \else
1643 on the right%
1644 \fi\fi
1645 ). All the files not
1646 yet available on your local disk are first downloaded from the
1647 remote source directory on the Internet. Then every package is
1648 unpacked (if \path|.zip| files), or copied from the \CD{}.
1649 \item[Configuration Page] Several packages need some configuration
1650 step to make them usable (Figure~\ref{graph:configuration},
1651 \ifnum \Status = 1
1652 on the left%
1653 \else\ifnum \Status=2
1654 at the top%
1655 \else
1656 on the left%
1657 \fi\fi
1658 ). Also the \TeXLive{} system needs some post-processing step
1659 (format files generation, ls-R databases generation, environment
1660 variables, etc.). All these operations are done there, some of them
1661 can be lengthy.
1662 \begin{figure*}[!htb]
1663 \textbf{Review Page}\hfill%
1664 \textbf{File Copy Page}
1665 \begin{center}
1666 \ifnum \Status=1
1667 \includegraphics[width=.48\textwidth]{../pictures/review-settings}\hfill%
1668 \includegraphics[width=.48\textwidth]{../pictures/file-copy}
1669 \else
1670 \ifnum \Status=2
1671 \includegraphics[bb=0 0 506 403]{../pictures/review-settings.jpg}\hfill%
1672 \includegraphics[bb=0 0 506 403]{../pictures/file-copy.jpg}
1673 \else
1674 \includegraphics[width=.48\textwidth]{../pictures/review-settings}\hfill%
1675 \includegraphics[width=.48\textwidth]{../pictures/file-copy}%
1676 \fi
1677 \fi
1678 \end{center}
1679 \caption{Review Page / File Copy Page}
1680 \label{graph:review}\label{graph:file-copy}
1681 \end{figure*}
1682 \item[Final Page] The installation being over, you may want to display
1683 the Windows specific documentation (HTML format) and / or the log
1684 file of the setup process (Figure~\ref{graph:final}
1685 \ifnum \Status = 1
1686 on the right%
1687 \else\ifnum \Status=2
1688 at the bottom%
1689 \else
1690 on the right%
1691 \fi\fi
1692 ). If it is needed (Win9x/WinME), you will
1693 be asked to reboot your computer.
1694 \end{description}
1695
1696 \begin{figure*}[!htb]
1697 \textbf{Configuration Page}\hfill%
1698 \textbf{Final Page}
1699 \begin{center}
1700 \ifnum \Status=1
1701 \includegraphics[width=.48\textwidth]{../pictures/configuration}\hfill%
1702 \includegraphics[width=.48\textwidth]{../pictures/congratulations}
1703 \else
1704 \ifnum \Status=2
1705 \includegraphics[bb=0 0 506 403]{../pictures/configuration.jpg}\hfill%
1706 \includegraphics[bb=0 0 506 403]{../pictures/congratulations.jpg}
1707 \else
1708 \includegraphics[width=.48\textwidth]{../pictures/configuration}\hfill%
1709 \includegraphics[width=.48\textwidth]{../pictures/congratulations}%
1710 \fi
1711 \fi
1712 \end{center}
1713 \caption{Configuration Page / Final page}
1714 \label{graph:configuration}\label{graph:final}
1715 \end{figure*}
1716
1717 Please be aware that the choice of cluster size on DOS disk
1718 partitions can radically affect the size of your \TeX\
1719 installation. The support tree has hundreds of small files, and it is
1720 not unusual for a complete installation to take up to four times the
1721 amount of space used on the \CD.
1722
1723
1724 \section{Windows maintenance and post-installation}
1725
1726 \subsection{What's different in Windows?}
1727
1728 The Windows version of \Webc{} has some specific features that should be
1729 pointed out.
1730
1731 \begin{description}
1732 \item[\KPS{}] The hash-tables that \KPS{} builds are quite large for
1733 the \TeXLive{}. In order to cut down the starting time of any
1734 \KPS{}-enabled program, these hash-tables have been put in shared
1735 memory. This way, when you chain the execution of several such
1736 programs, like \path|tex| calling \path|mpost| calling \path|tex|,
1737 the overhead when starting each of the subprograms is
1738 reduced. This change is hidden to the user, except if you set the
1739 debug flag of kpathsea to the \path|-1| value: you will then trace
1740 access to the shared memory, which is not what you want (it is
1741 accessed very often!). What is useful in a log trace of the shared
1742 memory access is still to be defined, so the situation might evolve
1743 in the future.
1744 \item[\cmdname{kpsecheck}] This command provides some options that did
1745 not fit well into \cmdname{kpsewhich}. It will allow you to list all
1746 the files that occur multiple times across your texmf trees. This
1747 could be handy, but most of the time you will also get unwanted
1748 output (like dozens of \path|README| files)\footnote{It is noticeable
1749 that all these files result in clashes inside the \KPS{}-hashing
1750 mechanism; fortunately, \KPS{} never looks for these files.}. For
1751 this reason, you can combine the \path|-multiple-occurences| with 2
1752 other options for including or excluding any filename that match
1753 some pattern (you can request for several patterns).
1754
1755 The \cmdname{kpsecheck} command will also report the status of shared
1756 memory: in use or not used. That might be useful to know because if
1757 the status reported is \samp{in use}, that means one or several
1758 processes are working, and the effect of any \cmdname{mktexlsr}
1759 command will be delayed until the next time where no \KPS{} linked
1760 process will be running.
1761
1762 Last, this same command will report about the location it thinks
1763 Ghostscript can be found. Under Win32, for many programs, it is
1764 easier to use the Ghostscript dll, and find it by using the
1765 Ghostscript registry key than to change the \path|PATH|, which has a
1766 limited length anyway.
1767 \item[\Webc{}] The engines have a few more options than in Unix
1768 \Webc{}, and one option with a different behaviour:
1769 \begin{itemize}
1770 %% \item the \path|-fmt| option behaves differently. Previously and
1771 %% with the regular \Webc{} distribution, this option has 2 different
1772 %% meanings when you are in ``ini'' or ``vir'' mode. Under Win32, it
1773 %% has the same meaning: preload the format file specified with the
1774 %% argument. The meaning of building a format of such name in ini
1775 %% mode is obtained by the new \path|-job-name| option.
1776 %% \item \path|-job-name| option: allows to set the name of the file
1777 %% resulting from the compilation process. In normal mode, it will
1778 %% change the base name of all files produced (\path|.dvi|,
1779 %% \path|.aux|, etc.), while in ini mode, it will set the name of
1780 %% the format file written.
1781 \item \path|-halt-on-error| stop the compilation at the first error.
1782 \item \path|-job-time| set the job time to the same timestamp as the
1783 file given in argument.
1784 \item \path|-oem| use the DOS codepage for console output.
1785 \item \path|-output-directory| allow to write all the output files in the
1786 specified directory.
1787 \item \path|-time-statistics| print statistics about the job run
1788 time. It is to be noted that Win9x not being a true multitasking
1789 operating system, it has no reliable timer for short periods, so
1790 the value printed is an approximation. Under NT/2K/XP, the result
1791 is quite accurate with user time and system time values allocated
1792 for this run. For Unix
1793 users: the \path|time| command is not usually available to Windows
1794 users.
1795 \end{itemize}
1796 \end{description}
1797
1798 \subsection{Adding packages to your installation}
1799
1800 You will find an option in the \guiseq{TeXLive} menu (or go to
1801 \guiseq{Start\arw Programs \arw TeXLive \arw Add TeX package} menu) to
1802 run \file{TeXSetup.exe} in maintenance mode. The steps are almost the
1803 same as in the initial installation.
1804
1805 We'll discuss differences below, but first, whatever changes you make,
1806 \textbf{do not forget to rebuild the ls-R database files}. Otherwise,
1807 your new files will not be found. You can do this either via the
1808 \acro{GUI} (\guiseq{Start \arw Programs \arw TeXLive \arw Maintenance
1809 \arw Rebuild ls-R}), or manually running the \file{mktexlsr} command.
1810
1811 The main difference is in the packages selection page. In maintenance
1812 mode, the list of installed packages is compared to the list of packages
1813 available from your source directories. Packages that are not installed
1814 will be displayed in green, out of date packages will be displayed in
1815 red and up-to-date, installed packages are displayed in black.
1816
1817 This way, you can choose to add or upgrade components, either from
1818 \TeXLive{} or from the Internet, where you are likely to find some more
1819 recent version of your packages.
1820
1821 It is up to you to select which packages you want to install. The rest
1822 of the process is similar to the first installation.
1823
1824 If you want to add files that are not provided by the \TeXLive{} (or
1825 \fpTeX{}) distribution, it is recommended to put them in the
1826 \path|$TEXMFLOCAL| directory. This way, you will be safe against
1827 upgrades of the \TeXLive{} software.
1828
1829 The directory pointed to by \path|$TEXMFLOCAL| is initially empty. If,
1830 for example, you want to add the support file for the Maple symbolic
1831 computation program, you will have to put the style files in:\\
1832 \path|c:\Program Files\TeXLive\texmf-local\tex\latex\maple\|\\ and the
1833 documentation files in:\\ \path|c:\Program
1834 Files\TeXLive\texmf-local\doc\latex\maple\|
1835
1836 \subsection{Uninstalling \protect\TeXLive{}}
1837
1838 The uninstall procedure is available either from the \file{TeXLive.exe}
1839 program, from the \path|TeXLive| menu or from the control panel
1840 (\guiseq{Start \arw Control Panel, Add/Remove Programs}). This procedure
1841 will cleanup your hard disk of most of the \TeXLive{} files. However,
1842 \TeX{} is a system that is creating files and there is no mechanism to
1843 keep track of all of them. Moreover, Win32 support packages have their
1844 own uninstall procedure, which you will have to run separately (provided
1845 you want to get rid of them). Last, the files you may have stored in
1846 \path|$TEXMFLOCAL| won't be removed. So, even if the vast majority of
1847 files are automatically removed by the uninstall procedure, you will
1848 have to do some manual cleanup to actually remove all of them.
1849
1850 \subsection{Running \texttt{TeXSetup.exe} from the command line}
1851
1852 The \path|TeXSetup.exe| program has a number of other useful
1853 options. You can get the list by running:
1854 \begin{verbatim}
1855 c:\>TeXSetup --help
1856 \end{verbatim}
1857
1858 Here is the description:
1859 \begin{description}
1860 \item[\path|--automatic-reboot|] reboot without waiting user
1861 confirmation once installation is over;
1862 \item[\path|--dry-run|] do nothing, just log everything that will be
1863 done without this option;
1864 \item[\path|--quick|] use the recommended installation and default
1865 directories, ask nothing up to rebooting;
1866 \item[\path|--with-xemtex|] selects the \XEmTeX{} bundle;
1867 \item[\path|--net-method (=ie5/direct)|] enable to download components with
1868 restricted licenses from the Internet (either using direct
1869 connection of Internet Explorer 5 DLLs): you need to have an available
1870 network connection and some of the packages are huge;
1871 \item[\path|--remote-source-directory <url>|] this is the base url for the remote packages;
1872 \item[\path|--local-source-directory <dir>|] by default, \path|TeXSetup.exe|
1873 will guess the root directory of the set of files you want it to act on, if you ever
1874 upgrade \path|TeXSetup.exe|, you won't be able to copy the new version
1875 onto your \CD{}, so you will need to use this option to specify the
1876 root of the \CD{};
1877 \item[\path|--installation-directory <dir>|] this is the root of your
1878 installation, all files will be copied under this location. The
1879 default value is \verb+c:\Program Files\TeXLive+;
1880 \item[\path|--texmfmain-directory <dir>|]
1881 \item[\path|--texmflocal-directory <dir>|]
1882 \item[\path|--texmfextra-directory <dir>|]
1883 \item[\path|--texmfhome-directory <dir>|]
1884 \item[\path|--vartexmf-directory <dir>|]
1885 \item[\path|--vartexfonts-directory <dir>|] these are the directories
1886 used to configure the location of your files. They map directly to
1887 the \path|texmf.cnf| variables.
1888 \item[\path|--with-source-files(=yes/no)|] copy the source files
1889 for \TeX{} packages, default value is no;
1890 \item[\path|--with-documentation-files(=yes/no)|] copy documentation files for \TeX{}
1891 packages. Default value is yes. Beware: this is only documentation about specific
1892 packages, general documentation will be installed anyway;
1893 \item[\path|--program-folder <folder>|] the name of the folder under
1894 which you will find the menus;
1895 \item[\path|--add-package <pkg>|] this is used to add or update a specific
1896 package after a first regular installation;
1897 \item[\path|--scheme <pkg>|] install the named scheme instead of the
1898 default \path|texlive-recommended| scheme;
1899 \item[\path|--maintenance|] mostly the same as \path|--add-package|
1900 without specifying a package to add;
1901 \item[\path|--uninstall|] this option will remove anything \TeX{} related coming from
1902 the \CD{}, which means there can be files left if you added style
1903 files or format files, and also that supplementary tools will not be
1904 removed. This option is still a bit crude in this release;
1905 \item[\path|--help|] this option opens up a box with the list of options.
1906 \end{description}
1907
1908 \subsection{Network installation}
1909
1910 \KPS{} knows about UNC names, so you can use them to get your TEXMF
1911 tree from the network. But there is better than this.
1912 All the support files and configuration files, everything except the files in the
1913 \path|bin/win32| are shareable with a \teTeX{} or Unix \TeXLive{} installation. That means
1914 you can use Samba either to mount from an NT server to a Unix
1915 workstation or the converse. Several strategies are possible:
1916 \begin{itemize}
1917 \item Put everything on the server. Just add each set of files for the os and
1918 architecture you want to use in the \path|bin| directory. That means
1919 for example \path|bin/win32| and \path|bin/i386-linux|. Next configure
1920 your main variables. You can use UNC names to
1921 point to the right directories under Win32.
1922 \item Install a local copy for the binaries and format files. In this
1923 case, assign \path|$TEXMFMAIN| to the main \path|texmf| tree that
1924 will be accessed remotely. Set \path|$VARTEXMF| to be a local
1925 directory which will hold local configuration files and on-the-fly
1926 generated files.
1927 \end{itemize}
1928
1929 \subsection{Personal configurations}
1930
1931 \subsubsection{Dvips}
1932
1933 The configuration file for dvips can be found in\\
1934 \verb+C:\Program Files\TeXLive\texmf-var\dvips\config\config.ps+\\
1935 You may open it with any editor
1936 %(\cmdname{WinShell} will do fine)
1937 and change some parameters:
1938
1939 \begin{description}
1940 \item [fonts] you can change the default printer \MF{} mode or printer
1941 resolution in case \cmdname{dvips} needs to generate PK fonts. By default it
1942 is configured to use Type~1 versions of the CM fonts, so it should
1943 not call \cmdname{mktexpk} too often;
1944 \item[printer] you can tell dvips where you want to print by default. If
1945 the \optname{o} option is not followed by a printer name, then a
1946 \file{.ps} \PS{} file is written. You can give dvips a printer
1947 name such as:
1948 \begin{verbatim}
1949 o lpt1:
1950 % o | lpr -S server -P myprinter
1951 % o \\server\myprinter
1952 \end{verbatim}
1953 \item[paper] Next, you might want
1954 to change the paper size from European (A4) to US letter
1955 by making the US letter the first paper size mentioned in the file.
1956 Scroll to the group of lines beginning with \code{@}. Move
1957 the appropriate lines so that this section begins with the lines:\\
1958 \hspace*{1em} @ letterSize 8.5in 11in\\
1959 \hspace*{1em} @ letter 8.5in 11in\\
1960 \hspace*{1em} @+ \%\%BeginPaperSize: Letter\\
1961 \hspace*{1em} @+ letter\\
1962 \hspace*{1em} @+ \%\%EndPaperSize
1963 \end{description}
1964
1965 The current \TeXLive{} distribution implements the procedure of making
1966 always up-to-date fontmaps files for Dvips and Pdftex. This is done by
1967 the \cmdname{updmap} program during installation, as well as during any
1968 font package addition. If you add new packages by hand, edit the file
1969 \verb+updmap.cfg+ in \path|$VARTEXMF/web2c|.
1970
1971 \subsubsection{Pdftex}
1972
1973 If you use the program pdf{}latex to write \acro{PDF} format directly,
1974 and you are using \acro{US} letter-size paper, edit the file
1975 \verb+C:\Program Files\TeXLive\texmf-var\pdftex\config\pdftex.cfg+ and
1976 change \samp{page\_width} and \samp{page\_height}. These entries should read:
1977 \begin{alltt}
1978 page_width 8.5 true in
1979 page_height 11 true in
1980 \end{alltt}
1981 Save the file and exit the editor.
1982
1983 \subsubsection{GSView}
1984 GSView is now distributed under the Aladdin License, and therefore is no longer included in
1985 \TeXLive{}.
1986
1987 If you may want to change the page size to US letter size. If so, open
1988 GSView from the \guiseq{Start} menu, and select \guiseq{Media\arw Letter}.
1989
1990 Also, there are menu settings that are supposed to give you the most
1991 readable screen image. On \guiseq{Media \arw Display Settings}, set both
1992 \optname{Text Alpha} and \optname{Graphics Alpha} to 4~bits.
1993
1994 Note that the installation process has set all \code{.ps} and
1995 \code{.eps} files to automatically open with \cmdname{GSView}.
1996
1997 For printing instructions, see section~\ref{printing} below.
1998
1999 \subsubsection{WinDvi}
2000 \label{sub:windvi}
2001
2002 The \file{TeXSetup.exe} program takes care of associating the files
2003 with the \file{.dvi} extension with \file{Windvi}.
2004
2005 Open it with \guiseq{Start\arw Programs\arw TeXLive\arw DVI Viewer}.
2006
2007 You can set it for US letter-size paper by going to \guiseq{View\arw
2008 Options\arw Papertype} and selecting US (8.5\verb+"+ x 11\verb+"+) (and
2009 then \optname{OK}. Exit \cmdname{windvi}.
2010
2011 You can change other parameters from there as well, such as the ability
2012 to execute system commands specified by the document (disabled by
2013 default for security reasons). Also, the first time you view any .dvi
2014 file, you may find the magnification too large. Zoom out until you get
2015 an appropriate size.
2016
2017 %There are two important parameters related to printing that can't yet
2018 %be set from the dialog boxes, namely the resolution and the \MF{} mode
2019 %for the printer. You can set them once for all by specifying them on
2020 %the command line:
2021 %\begin{verbatim}
2022 %c:\>windvi -p 360 -mfmode canonbjc foo.dvi
2023 %\end{verbatim}
2024 %When you will exit Windvi, these parameters will be stored in the
2025 %configuration file. The available modes are found in this file:\\
2026 %\path|c:\Program Files\TeXLive\texmf\metafont\misc\modes.mf|
2027
2028 All configuration settings for \cmdname{Windvi} are stored in a file
2029 named \path|windvi.cnf| file. You can find it by running this command at
2030 the prompt:
2031 \begin{verbatim}
2032 c:\>kpsewhich --expand-var $HOME/windvi.cnf
2033 \end{verbatim}
2034
2035 Should you have problems with \cmdname{Windvi}, please remove the configuration
2036 file and test your problem against a vanilla configuration.
2037
2038 \subsection{Testing}
2039
2040 For generic verification procedures, see section~\ref{sec:test-install}
2041 on p.~\pageref{sec:test-install}. This section describes
2042 Windows-specific tests.
2043
2044 Open the file \verb+sample2e.tex+ in your editor (Xemacs, WinShell),
2045 found in \path|C:\Local\TeX\texmf\tex\latex\base|. The \LaTeX\ source
2046 should appear on the screen. Process it by clicking on the
2047 \guiseq{Command\arw LaTeX} menu (XEmacs) or \LaTeX\ icon on the toolbar
2048 (WinShell), then view it by clicking on the \guiseq{Command\arw View DVI}
2049 menu (XEmacs) or Preview (Windvi) icon (WinShell).
2050
2051 At first, when you preview files with Windvi, it will create fonts because
2052 screen fonts were not installed. After a while, you will have created most
2053 of the fonts you use, and you will rarely see the font-creation window.
2054
2055 \textbf{Hint for the future:} If a \LaTeX\ run stops because \LaTeX\
2056 cannot find a file, you can press Ctrl-z to quit.
2057
2058
2059 \subsection{Printing}
2060 \label{printing}
2061
2062 It is possible to print from Windvi. In this case, printing will be done
2063 using the Windows unified printer driver. By definition, it is
2064 compatible with all printers. However, there is some drawback: it can
2065 generate some huge spool files, and some (older) versions of Windows
2066 just don't like them. The advantage is that you can use features like
2067 embedding BMP or WMF images. You also need to make sure that the printer
2068 parameters are correctly set (subsection~\ref{sub:windvi}), else you
2069 will get scaled printing (printing at 600\dpi{} on a 300\dpi{} printer
2070 will give you only one quadrant of your page).
2071
2072
2073 Printing is faster and more reliable if you run \cmdname{dvips} to make
2074 a \filename{.ps} file and then print from \cmdname{GSView}. In
2075 \cmdname{GSview}, select \guiseq{File\arw Print\ldots}. A \guiseq{Print}
2076 window will appear.
2077
2078 If you are using a \PS{} printer, \textit{be sure to select
2079 \guiseq{\PS{} Printer}}. This is done in the \guiseq{Print Method} box
2080 at the bottom left of the \guiseq{Print} window. You can then select any
2081 of the printers that you have previously installed. If you fail to
2082 check the box for \optname{\PS{} Printer}, printing will not work.
2083
2084 If you will be using your own non-\PS{} printer, select
2085 \guiseq{Ghostscript device} in the \guiseq{Print Method} box, then click
2086 on the button to the right labelled \guiseq{djet500} and select your
2087 printer type from the list that pops up. (In the older version of
2088 \cmdname{GSView}, make sure \optname{\PS{} Printer} is \textit{not}
2089 selected, then select your printer type from the \guiseq{Device} list.)
2090
2091 %If you use \cmdname{WinShell} and a \PS{} printer, probably the
2092 %most convenient way to print is to add an icon to the \cmdname{WinShell}
2093 %toolbar that invokes dvips in a way that sends the output directly to a
2094 %default printer. For detailed instructions on how to do this, see
2095 %the next section.
2096
2097 %% \subsection{\cmdname{WinShell}}
2098 %% \label{winshell:more}
2099
2100 %% \subsubsection{Configuring \cmdname{WinShell}}
2101 %% \label{sec:winshell}
2102
2103 %% Start this program from the Start menu or from the Desktop shortcut.
2104 %% Go to \guiseq{Options \arw Program Calls}.
2105
2106 %% \begin{itemize}\itemsep 0pt
2107 %% \item In the DVIWin tab, if the filename is \filename{yap}, replace it
2108 %% with \filename{windvi.exe}.
2109 %% \item In the Ghostview tab, make sure it gives the correct path for
2110 %% gsview32.exe:\\
2111 %% \hspace*{1em} \verb+C:\ghostgum\gsview\gsview32.exe+ (for 3.6, the
2112 %% current version)\\
2113 %% or \\
2114 %% \hspace*{1em} \verb+C:\gstools\gsview\gsview32.exe+ (for the older
2115 %% version)
2116
2117 %% \end{itemize}
2118
2119 %% Click \guiseq{OK}.
2120
2121 %% Note that the install process sets all files with the \texttt{.tex}
2122 %% extension to open with \cmdname{WinShell}. Unless you plan to use another editor
2123 %% (such as WinEdt or Emacs), this is appropriate.
2124
2125 %% Unfortunately, \cmdname{WinShell} does not have a spell-checking
2126 %% feature. However, if you have installed the \path|tex-extrabin|
2127 %% collection, your installation includes \cmdname{Ispell} (a spell
2128 %% checking program found on most Unix systems). The executable is in your
2129 %% PATH so \verb+ispell.exe+ will be found if you invoke it from a DOS
2130 %% window. If you installed documentation, look at \path|C:\Program
2131 %% Files\TeXLive\texmf\doc\html\manpages\ispell.html|for information on
2132 %% Ispell. (Otherwise, you can find \verb+ispell.html+ on the CD.) If you
2133 %% rely on spell checking, you may want to add an Ispell icon to
2134 %% \cmdname{WinShell}. See subsection~\ref{winshell:ispell} of this
2135 %% document for how to do that.
2136
2137 %% For an excellent commercial (but inexpensive) spelling checker,
2138 %% see \url{http://www.microspell.com}.
2139
2140 %% \cmdname{WinShell} also has on-line help, which you can access via the
2141 %% $\textbf{\underbar{?}}$ on the menu bar.
2142
2143 %% Other information about using \cmdname{WinShell} can be found in
2144 %% section \ref{winshell:more} on p.~\pageref{winshell:more}.
2145
2146
2147 %% \subsubsection{Installing Bug Fixes}
2148
2149 %% \cmdname{WinShell}'s author (\href{mailto:[email protected]}{Ingo de Boer},
2150 %% thanks to him) sometimes releases beta versions of the next \cmdname{WinShell}
2151 %% version which are also bug fixes. You can grab them from
2152 %% \url{http://www.winshell.de}. Usually they are \file{.zip} files that
2153 %% only require to be unpacked in \cmdname{WinShell} directory (\path|c:\Program
2154 %% Files\WinShell| by default), either using WinZip or a similar tool, or
2155 %% by using \file{unzip} on the command line. If you got some
2156 %% \file{winshellbugfix.zip} file and that you saved it in the \cmdname{WinShell}
2157 %% directory, then you need to run:
2158 %% \begin{verbatim}
2159 %% c:\>cd c:\"Program Files"\WinShell
2160 %% c:\>c:\local\bin\unzip winshellbugfix.zip
2161 %% \end{verbatim}
2162 %% Say \optname{yes} if you are asked if some files should be overwritten. The
2163 %% \path|unzip.exe| programme can be found in the
2164 %% \path|support/gnu-utils| package. If you
2165 %% do not have it on your machine, you can use any archiver tool like
2166 %% WinZip to achieve the same effect.
2167
2168 %% \subsubsection{The \cmdname{Project} feature: organizing many files}
2169
2170 %% If your document is split into several files (for example a thesis),
2171 %% look into \cmdname{WinShell}'s \cmdname{Project} feature. From the
2172 %% \guiseq{Project} menu, you give the project a name (e.g., \code{Thesis}),
2173 %% supply the name of the main (or root) file, and then \code{add} other
2174 %% files. These filenames display on the left of the screen where you can
2175 %% double click the names to view and switch between them. Clicking the
2176 %% \guiseq{\LaTeX} icon always processes the main file.
2177
2178 %% Note the icons on the toolbar for toggling the project space (on the left)
2179 %% and the log space (at the bottom). If you are not using the Project
2180 %% feature, you may want to toggle off the space on the left, using the full
2181 %% screen width to display your file.
2182
2183 %% \subsubsection{Printing from \cmdname{WinShell} to a \PS{} Printer}
2184 %% \label{winshell:print}
2185
2186 %% The Dvips icon on the \cmdname{WinShell} toolbar puts the \PS{} output
2187 %% in a file, which you can then view with GSView and print from there if
2188 %% you choose. However, it's convenient to add a \cmdname{WinShell}
2189 %% ``program call'' to dvips which sends the output directly to a
2190 %% designated \PS{} printer. The steps below show how to do this for the
2191 %% printer \optname{vclw}; you should substitute the name of your most
2192 %% frequently-used printer.
2193 %% \begin{enumerate}
2194 %% \item Make the program aware of the printer:
2195 %% \begin{itemize}
2196
2197 %% \item Open \cmdname{WinShell}, go to \guiseq{Options\arw Program
2198 %% Calls\arw User defined}.
2199
2200 %% \item Click on \guiseq{Tool 1} in the list on the right and fill in the
2201 %% fields to the left as follows:\vspace{-6pt}
2202 %% \begin{quote}
2203 %% Name: \verb+Print+\\
2204 %% exe file: \verb+dvips+\\
2205 %% cmd-line: \verb+ -D600 %m -o vclw+\\
2206 %% Uncheck the box for \guiseq{DVIPS first}
2207 %% \end{quote}%\vspace{-12pt}
2208 %% \item Click \guiseq{OK}
2209 %% \end{itemize}
2210 %% \item Add \guiseq{Print} to the toolbar:
2211 %% \begin{itemize}
2212 %% \item Go to \guiseq{Options\arw View\arw Customize}.
2213 %% \item In the \guiseq{Category} box, select \guiseq{User-Programs}.
2214 %% \item Select \guiseq{Print} and drag it to the toolbar, placing it just to
2215 %% the right of the \cmdname{GSView} icon.
2216 %% \item You then have a choice of \guiseq{Image only}, \guiseq{Text only},
2217 %% or \guiseq{Image and Text}. The easiest is to select \guiseq{Text only}
2218 %% and click \guiseq{OK}. You should then see \guiseq{Print} on the
2219 %% toolbar. (If you prefer, you can select \guiseq{Image only\arw Edit},
2220 %% and edit the displayed picture to your satisfaction.)
2221 %% \end{itemize}
2222 %% \end{enumerate}
2223 %% Now, to print a \LaTeX\ document, just click on the \guiseq{Print} icon
2224 %% to send to your selected printer. To use a different printer, you will
2225 %% need to click on the \guiseq{Dvips} icon to print to a file. Then click
2226 %% on the \cmdname{GSView} icon and use \cmdname{GSView} to send to any
2227 %% printer you have installed on your \acro{PC}.
2228
2229 %% \subsubsection{Adding Ispell to \cmdname{WinShell}}
2230 %% \label{winshell:ispell}
2231 %% \begin{enumerate}
2232 %% \item Add Ispell to User Tools:
2233 %% \begin{itemize}
2234 %% \item Open \cmdname{WinShell}, go to \guiseq{Options\arw Program
2235 %% Calls\arw User defined}.
2236 %% \item In the list on the right, click on \guiseq{Tool~1} (or
2237 %% \guiseq{Tool~2} if you have already used \guiseq{Tool~1}) and fill in
2238 %% the fields to the left as follows:\vspace{-6pt}
2239 %% \begin{quote}
2240 %% Name: \verb+Ispell+\\
2241 %% exe file: \verb+ispell+\\
2242 %% cmd-line: \verb+ -t -d american %c.tex+\\
2243 %% Uncheck the boxes for \guiseq{LaTeX first} and \guiseq{DVIPS first}
2244 %% \end{quote}
2245 %% \item Click \guiseq{OK}.
2246 %% \end{itemize}
2247
2248 %% \item Add Ispell to the toolbar:
2249 %% \begin{itemize}\itemsep 0pt
2250 %% \item Go to \guiseq{Options\arw View\arw Customize}.
2251 %% \item In the \guiseq{Category} box, select \guiseq{User-Programs}.
2252 %% \item Select \guiseq{Ispell} and drag it to the toolbar, placing it just to
2253 %% the right of the \cmdname{GSView} icon (or the last icon you added).
2254 %% \item You then have a choice of `\guiseq{mage only}, \guiseq{Text only},
2255 %% or \guiseq{Image and Text}. The easiest is to select \guiseq{Text only}
2256 %% and click \guiseq{OK}. You should then see \guiseq{Ispell} on the
2257 %% toolbar. (If you prefer, you can select \guiseq{Image only\arw Edit},
2258 %% and edit the displayed picture to your satisfaction.)
2259 %% \end{itemize}
2260 %% \end{enumerate}
2261 %% Now, when you have a \LaTeX\ document open, you can click on
2262 %% \guiseq{Ispell} to perform spell checking. Ispell will open another
2263 %% window and display the first misspelled word on the left with the
2264 %% filename on the right. Below that you will see the context in which the
2265 %% misspelling appears; often several suggestions for replacements are also
2266 %% displayed. To replace the word, enter the number corresponding to the
2267 %% desired replacement. Other possible responses are listed below; for
2268 %% example, you can press the space bar to ignore the misspelled word. For
2269 %% more information on Ispell, read the manual page:
2270 %% \verb+C:\Program Files\TeXLive\texmf\doc\html\manpages\ispell.html+.
2271
2272 %% Note that when you replace a word, you will not see the correction in
2273 %% your \cmdname{WinShell} window until you close the file (click the
2274 %% \guiseq{X} in the upper right corner) and then open it again (use the
2275 %% \guiseq{File} menu).
2276
2277 \subsection{Tips and tricks for Win32}
2278
2279 \subsubsection{Different flavors of Win32}
2280
2281 What we call Win32 is not an operating system by itself. It is a large
2282 set of functions (around 12,000 in the header files of the Microsoft
2283 \acro{SDK}) that you can use to write programs for different operating
2284 systems of the Windows family.
2285
2286 Windows comes in different flavors:
2287 \begin{itemize}
2288 \item Win95, Win98 and Win\acro{ME}, which \emph{are not true multitasking,
2289 multithreading} environments. They are the latest\Dash and hopefully
2290 last\Dash metamorphosis of \acro{DOS}. This can be more or less proven
2291 by the fact that when booting, the PC will load the \path|command.com|
2292 interpreter, and if you stop the boot process at this point, you can
2293 ask for the current (\acro{DOS}) version and it will answer something
2294 like \samp{MS-DOS 7.0} (at least for the old versions of Win9x).
2295 \item Windows \acro{NT}, which is a new operating system written from
2296 scratch, capable of true multitasking behaviour, and including many
2297 high level features.
2298 \item Windows 2000, based on \acro{NT}, with all the bells and
2299 whistles of Win98.
2300 \item Windows \acro{XP}, which comes with Personal and Pro flavors. This is
2301 the last step in merging both lines of products (Win9x based and
2302 \acro{NT} based). \acro{XP} is based on \acro{NT}.
2303 \end{itemize}
2304
2305 Win9x are able to run 32~bits programs and 16~bits programs
2306 concurrently. But the operating system by itself is not entirely
2307 written in 32~bits mode, and does not support memory protection: 16bits
2308 applications can overwrite parts of the operating system memory! Some
2309 parts of the system like the \acro{GDI} (Graphical Device Interface)
2310 manage limited resources like bitmaps, fonts, pens and so on for the set
2311 of all programs that run concurrently. All the bitmaps headers available
2312 at the same time can't amount for more than 64kB. This explains the
2313 performance tool and the fact that you can put your system on his knees
2314 by making intensive use of graphic objects for example.
2315
2316 NT, 2K and XP do not suffer from these limitations, and neither from
2317 other Win9x limitations. They are true multitasking environments, with
2318 protected memory. They are much more responsive than Win9x because
2319 of better memory management, better file system and so on.
2320
2321 \subsubsection{Command line prompt}
2322
2323 You may wonder, ``Why would I need to use a command line prompt when
2324 I have Windows?''
2325
2326 Good question. The problem is of very general nature. Not all operations
2327 can be done easily using only a \acro{GUI}. Command line gives you
2328 programming power\Dash assuming a clever command interpreter.
2329
2330 But the problem here is more fundamental: \TeX{} is \emph{a batch}
2331 tool. Not an interactive one. \TeX{} needs to compute the best
2332 layout for each page, resolve cross-references and so on. This can be
2333 done only by a global processing of the document. It is not (yet) a
2334 task that can be done interactively.
2335
2336 This means that you should use \TeX{} from a command line. In fact the
2337 situation is not so bad. There is an advantage to write command line
2338 tools for complex processing: they are better debugged, because they are
2339 independent of any \acro{GUI} problems, and \acro{GUI} tools can be
2340 designed to interface to the command line tools. This is the case for
2341 \TeX{}, where you will mostly interact with it through a \acro{GUI} text
2342 editor.
2343
2344 However, you may need to use the command line prompt in a number of
2345 situations. One is when you are having difficulties and want to debug
2346 your setup.
2347
2348 \begin{description}
2349 \item[Win9x] You can open a command line prompt by looking either for
2350 the \acro{MS-DOS} icon in the \guiseq{Start\arw Programs} menu,
2351 or by choosing \guiseq{Start\arw Run} menu typing in
2352 \path|command.com| as the progrm name.
2353 \item[NT, 2K, XP] You can open a command line prompt by looking for
2354 \guiseq{Command Prompt} in the \guiseq{Start\arw Accessories} menu.
2355 You can also choose \guiseq{Start\arw Run} and type in
2356 \path|cmd.exe|, which is the name of the brand new command
2357 interpreter for \acro{NT} (thus, it is untrue to call this a
2358 \emph{DOS} box!).
2359 \end{description}
2360
2361 These locations may change across different Windows versions.
2362
2363
2364 \subsubsection{Path separators}
2365
2366 The Win32 API understands both \path|/| and \path|\| characters as PATH
2367 separators. But the command interpreters do not! So whenever a path name
2368 is used programmatically, you can use both separators, and even mix them
2369 up in the same path name. But on the command line, you must type
2370 \path|\| as path separator. The reason is compatibility: the command
2371 processor used \samp{/} to introduce arguments to commands.
2372
2373 All this to say: do not be surprised to read path names written using
2374 the Unix convention; \fpTeX{} is a port of \Webc, and aims to be compatible
2375 across platforms. For this reason, all the configuration files that
2376 need to specify path names use the Unix convention.
2377
2378 \subsubsection{File systems}
2379 \label{sec:clusters}
2380
2381 The worst feature of Win9x with regard to \TeX{} is probably the
2382 so-called FAT file system. \TeX{} uses many many small files, with size
2383 around 1--3kB. The \acro{FAT} file system is old, and predates by
2384 decades the multi-gigabytes hard disks we have today. As a result, it
2385 cannot manage efficiently the tens of thousands of \TeX{} files found in
2386 \TeXLive{}. The \acro{FAT} file system allocates a minimum of 32kB for
2387 \emph{any} file on a huge partition. It means that \TeX{} will use much
2388 more disk space than it actually needs.
2389
2390 The other, more modern, file systems available, \acro{FAT32} and
2391 \acro{NTFS}, do not have this drawback. They manage clusters of 4kB
2392 only. (You can lower the limit to 512 bytes on \acro{NTFS}.)
2393
2394 \subsubsection{How to add some directory to your PATH}
2395
2396 There are pairs of variables and values which behave much like global
2397 variables inside your programs. The set of those variables is called the
2398 environment. Each program is initialized with a copy of the
2399 environment when it is run. It can request and change the
2400 value of any variable. The changes happen in the copy of the
2401 environment, and is not at all propagated to the other running
2402 programs.
2403
2404 Your PATH is a special environment variable used to search for
2405 programs you want to run.
2406 There is a different procedure to change it for Win9x, WinME and NT/2K/XP:
2407
2408 \begin{description}
2409 \item[Windows 95/98] Edit your \path|autoexec.bat|. In this file should be a line
2410 starting with \texttt{PATH=} and followed by a list of directories separated
2411 by \path|;|. Please add the directory with the executables in this line.
2412 After this, this line could look as follows:
2413 \begin{verbatim}
2414 PATH=c:\windows;c:\windows\system;c:\"Program Files"\TeXLive\bin\win32
2415 \end{verbatim}
2416 \item[Windows ME] You need to run the special program
2417 \path|c:\windows\system\msconfig.exe| to be able to change any
2418 environment variable. From this program, select the `Environment'
2419 tab, and then add or modify the variable you want. You will be asked to reboot the
2420 machine upon any change.
2421 \item[Windows NT/2K/XP]
2422 Click left on \guiseq{Start \arw Settings \arw Control Panel}. Now the
2423 window with the control panel icons opens. Double click on System. The
2424 System Properties window opens. Click on the tab \textsf{Environment}
2425 or look for a button named \guiseq{Environment Variables} among the
2426 dialog boxes. Now you can change the environment variables for your
2427 user account. Note: There are also displayed the environment settings
2428 for the system. Normally, you can't change the system variables
2429 unless you have administrator rights on your machine. If you want to
2430 change the \texttt{PATH} for all users, you will have to contact your
2431 system administrator or be the system administrator yourself\Dash in
2432 the latter case you should know what you are doing.
2433
2434 If there is already a \texttt{PATH} setting for your user account,
2435 left click on \texttt{PATH}. In the field \textsf{Variable} appears
2436 \texttt{PATH} while the field Value shows the current setting of
2437 \texttt{PATH} as a list of directories separated by \path|;|. Add
2438 the directory where the executables are located (e.g.
2439 \path|c:\Program Files\TeXLive\bin\win32|). If there isn't a \texttt{PATH} variable
2440 for your user account, simply click in the field Variable and type
2441 in \texttt{PATH}, click in the field \textsf{Value}
2442 and type in the directory with the executables. Important: Click on
2443 the \textsf{Apply} button before clicking \textsf{Ok}, otherwise the
2444 changes to \texttt{PATH} won't apply to your system. Be careful when
2445 changing the environment settings.
2446 \end{description}
2447
2448 The best way to be sure that a variable has been properly set is to
2449 open a console and type:
2450 \begin{verbatim}
2451 set VARIABLE
2452 \end{verbatim}
2453 which should return the corresponding value.
2454
2455 \subsubsection{\TeX{} engines}
2456
2457 If you have a look at the \Webc{} documentation, you will read that all
2458 the various \TeX{} derived programs use the same base engine. For
2459 example, \path|tex.exe| and \path|latex.exe| are exact copies of the
2460 same program, but each one will use a different format file, based on
2461 its calling name.
2462
2463 Under Unix, this feature is implemented through \emph{symbolic
2464 links}. It saves up a bit of disk space, because some engines are
2465 used with many different format files.
2466
2467 The Win32 API does not know about file links. So to save up almost
2468 the same amount of memory, all the \TeX{} base engines have been put
2469 in DLLs (\emph{Dynamic Linked Library}). This means that you will have
2470 the following layout:
2471 \begin{alltt}
2472 13/05/2002 17:06 3 584 latex.exe
2473 13/05/2002 17:06 266 240 tex.dll
2474 13/05/2002 17:06 3 584 tex.exe
2475 \end{alltt}
2476 and the \path|latex.exe| file is nothing but a rough copy of
2477 \path|tex.exe| using the same core \path|tex.dll|.
2478 The same trick has been used for the \path|mktex*.exe| family of programs which are
2479 linked to the \path|mktex.dll| library.
2480
2481 In fact, a generic tool called \path|lnexe.exe| is provided to build the
2482 equivalent of Unix hard links for executable files only under Win32.
2483
2484 \subsection{In case of problems}
2485 \label{sec:troubleshooting}
2486
2487 \subsubsection{What to do if \texttt{latex} does not find your files?}
2488
2489 \begin{itemize}
2490
2491 \item \cmdname{kpsewhich} is the tool of choice to debug any
2492 problem. Unfortunately, \cmdname{kpsewhich} outputs debug information
2493 to stderr, and the Windows console does not know how to redirect stderr
2494 to a file\footnote{Well, NT and Win2k consoles know how to do that. But
2495 the trick will work for any console.}. For diagnostic purposes you can
2496 temporarily set an environment variable (in a \acro{DOS} box):
2497
2498 \begin{verbatim}
2499 SET KPATHSEA_DEBUG_OUTPUT=err.log
2500 \end{verbatim}
2501 You can also set the debug level:
2502 \begin{verbatim}
2503 SET KPATHSEA_DEBUG=-1
2504 \end{verbatim}
2505
2506 If you want to redirect stderr to stdout, which is not possible
2507 Windows, then do:
2508 \begin{verbatim}
2509 SET KPATHSEA_DEBUG_OUTPUT=con:
2510 \end{verbatim}
2511 This way you can capture both stdout and stderr in the same file.
2512
2513 \item Assuming the installation has been done in \path|c:/Program Files/TeXLive|, check
2514 the following values: \\
2515 {\small
2516 \begin{tabular}{ll}
2517 \path|kpsewhich -expand-path $SELFAUTOPARENT| & \path|c:/Program Files/TeXLive| \\
2518 \path|kpsewhich -expand-path $TEXMF| & \path|c:/Program Files/TeXLive/texmf| \\
2519 \path|kpsewhich -expand-path $TEXMFCNF| &
2520 \path|.;c:/Program Files/TeXLive/texmf/web2c;| \\
2521 & \path|c:/Program Files/TeXLive/bin/win32;| \\
2522 & \path|c:/Program Files/TeXLive/bin;| \\
2523 & \path|c:/Program Files/TeXLive| \\
2524 \path|kpsewhich -expand-var $TEXINPUTS| & \path|.;c:/Program Files/TeXLive/texmf/tex//|
2525 \end{tabular}
2526 }
2527 \item If you have other \TeX{}-related values already set in your
2528 environment, please, remove them. They are overriding the ones in
2529 texmf.cnf.
2530 \item Check the values from:\\
2531 {\small
2532 \begin{tabular}{ll}
2533 \texttt{kpsewhich cmr10.tfm} & \path|c:/Program Files/TeXLive/texmf/fonts/tfm/public/cm/cmr10.tfm|\\
2534 \texttt{kpsewhich latex.fmt}& \path|c:/Program Files/TeXLive/texmf/web2c/latex.fmt|
2535 \end{tabular}
2536 }
2537 \item At this point, if everything is correct, \TeX{} and friends
2538 should work. If it is not the case, you will need to play with
2539 the \path|-debug=n| option from \path|kpsewhich|, and check back all
2540 the values. Try to identify and report the problem.
2541 \end{itemize}
2542
2543 \subsubsection{What to do if your setup still does not work as expected?}
2544
2545 Here are several questions to investigate:
2546
2547 \begin{enumerate}
2548 \item Is \file{tex.exe} in my \path|PATH|?
2549
2550 \item Is the \path|TEXMFCNF| variable correctly set to
2551 \path|c:/Program Files/TeXLive/texmf-var/web2c| (default value)?
2552
2553 \item Are there any errors in the log file generated by the
2554 \file{TeXSetup.exe} program? You can find this by searching for the
2555 string \samp{Error}.
2556
2557 \item Are there any relevant bug fixes at \url{http://tug.org/texlive/}?
2558 (Unlikely, but it doesn't hurt to check.)
2559
2560 \item Check the web pages at
2561 \url{http://www.fptex.org/}, or consider subscribing to the \fpTeX{}
2562 mailing list, via \url{http://tug.org/mailman/listinfo/fptex}.
2563
2564 \end{enumerate}
2565
2566
2567 The \TeXLive{} software consists of hundreds and programs and tens of
2568 thousands of files, all from varying sources. So it is quite difficult to
2569 predict all possible causes for problems. Nevertheless, we will do our
2570 best to help you. (see section~\ref{sec:help} on p.~\pageref{sec:help}.)
2571
2572
2573 \subsection{Compiling the source files}
2574
2575 You have the whole set of source files, in the
2576 \path|source/source.tar.bz2| archive available in the distribution together with
2577 a patch file for Win32. To
2578 be able to compile the whole distribution for Windows, you will need:
2579
2580 \begin{itemize}
2581 \item Windows 2K/XP
2582 \item Microsoft Visual Studio .Net 2003
2583 \item a set of Unix tools (\texttt{sed},
2584 \texttt{grep}, \texttt{gawk}, etc.) and also Perl, Flex and Bison,
2585 \item to adjust the paths in the
2586 \path|win32/make/common.mak| file according to your installation
2587 \item to adjust the paths in the Perl script file
2588 \path|win32/perl/build.pl|,
2589 \item run the compilation from the \path|mswin32/| directory using this
2590 command:
2591 \begin{verbatim}
2592 c:\texlive\source\mswin32>perl ./perl/build.pl --install --log=install.log
2593 \end{verbatim}
2594 \end{itemize}
2595
2596 There is a lot of work to do to make this process easier and cleaner.
2597
2598 \subsection{Where to get more information}
2599
2600 The Windows \TeX{} system included on \TeXLive{} is also known as
2601 \fpTeX. The packaging differs, but \fpTeX{} is no more no less than the
2602 current \TeXLive\ release for Windows.
2603
2604 The \fpTeX{} home page is \url{http://www.fptex.org}.
2605
2606 The current \fpTeX release is available from any \CTAN site in
2607 \url{htp://www.ctan.org/tex-archive/systems/win32/fptex}.
2608
2609 The main ftp site for \fpTeX\ is \url{ftp://ftp.dante.de/pub/fptex/}
2610 from where beta versions of \fpTeX\ and additionnal tools are available.
2611 This main site is (partially) mirrored daily by all \CTAN{} sites at
2612 \path|systems/win32/fptex|.
2613
2614 The \TeX{} Users Group is kindly hosting a mailing list dedicated to
2615 \fpTeX. It is used for announcements, bug reports, enhancement requests,
2616 and general discussion about \fpTeX. To subscribe, visit
2617 \url{http://tug.org/mailman/listinfo/fptex}. The mailing list
2618 address is \email{[email protected]}.
2619
2620
2621 \section{A user's guide to \protect\Webc{}}
2622
2623 \Webc{} is an integrated collection of \TeX-related programs: \TeX{}
2624 itself, \MF{}, \MP, \BibTeX{}, etc. It is the heart of \TeXLive{}.
2625
2626 A bit of history: The original implementation was by Tomas Rokicki who,
2627 in 1987, developed a first \TeX{}-to-C system adapting change files
2628 under Unix, which were primarily the work of Howard Trickey and Pavel
2629 Curtis. Tim Morgan became the maintainer of the system, and during this
2630 period the name changed to Web-to-C\@. In 1990, Karl Berry took over
2631 the work, assisted by dozens of additional contributors, and in 1997 he
2632 handed the baton to Olaf Weber.
2633
2634 The \Webc{} system runs on Unix, 32-bit Windows systems, \MacOSX{}, and
2635 other operating systems. It uses Knuth's original sources for \TeX{} and
2636 other basic programs written in \web{} and translates them into C source
2637 code. The core \TeX{} programs are:
2638
2639 \begin{cmddescription}
2640 \item[bibtex] Maintaining bibliographies.
2641 \item[dmp] \cmdname{troff} to MPX (\MP{} pictures).
2642 \item[dvicopy] Expands virtual font references in \dvi{} files.
2643 \item[dvitomp] \dvi{} to MPX (MetaPost pictures).
2644 \item[dvitype] \dvi{} to human-readable text.
2645 \item[gftodvi] Generic font proofsheets.
2646 \item[gftopk] Generic to packed fonts.
2647 \item[gftype] GF to human-readable text.
2648 \item[makempx] \MP{} label typesetting.
2649 \item[mf] Creating typeface families.
2650 \item[mft] Prettyprinting \MF{} source.
2651 \item[mpost] Creating technical diagrams.
2652 \item[mpto] MetaPost label extraction.
2653 \item[newer] Compare modification times.
2654 \item[patgen] Creating hyphenation patterns.
2655 \item[pktogf] Packed to generic fonts.
2656 \item[pktype] PK to human-readable text.
2657 \item[pltotf] Plain text property list to TFM.
2658 \item[pooltype] Display \web{} pool files.
2659 \item[tangle] \web{} to Pascal.
2660 \item[tex] Typesetting.
2661 \item[tftopl] TFM to plain text property list.
2662 \item[vftovp] Virtual font to virtual property list.
2663 \item[vptovf] Virtual property list to virtual font.
2664 \item[weave] \web{} to \TeX.
2665 \end{cmddescription}
2666
2667 \noindent The precise functions and syntax of these programs are
2668 described in the documentation of the individual packages and of \Webc{}
2669 itself. However, knowing a few principles governing the whole family of
2670 programs will help you take advantage of your \Webc{} installation.
2671
2672 All programs honor these standard \acro{GNU} options:
2673 \begin{ttdescription}
2674 \item[-{}-help] print basic usage summary.
2675 \item[-{}-verbose] print detailed progress report.
2676 \item[-{}-version] print version information, then exit.
2677 \end{ttdescription}
2678
2679 For locating files the \Webc{} programs use the path searching library
2680 \KPS{}. This library uses a combination of environment variables and a
2681 configuration files to optimize searching the (huge) collection of
2682 \TeX{} files. \Webc{} can look at more than one directory tree
2683 simultaneously, which is useful in maintaining \TeX's standard
2684 distribution and local extensions in two distinct trees. To speed up
2685 file searches the root of each tree has a file \file{ls-R}, containing
2686 an entry showing the name and relative pathname for all files under that
2687 root.
2688
2689 \subsection{\protect\KPS\ path searching}
2690
2691 Let us first describe the generic path searching mechanism of the \KPS{}
2692 library.
2693
2694 We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list
2695 of \emph{path elements}, which are basically directory names. A
2696 search path can come from (a combination of) many sources. To look up
2697 a file \samp{my-file} along a path \samp{.:/dir}, \KPS{} checks each
2698 element of the path in turn: first \file{./my-file}, then
2699 \file{/dir/my-file}, returning the first match (or possibly all
2700 matches).
2701
2702 In order to adapt optimally to all operating systems' conventions, on
2703 non-Unix systems \KPS{} can use filename separators different from
2704 colon (\samp{:}) and slash (\samp{/}).
2705
2706 To check a particular path element \var{p}, \KPS{} first checks if a
2707 prebuilt database (see ``Filename data\-base'' on
2708 page~\pageref{Filename-database}) applies to \var{p}, i.e., if the database
2709 is in a directory that is a prefix of \var{p}. If so, the path
2710 specification is matched against the contents of the database.
2711
2712 If the database does not exist, or does not apply to this path
2713 element, or contains no matches, the filesystem is searched (if this
2714 was not forbidden by a specification starting with \samp{!!}\ and if
2715 the file being searched for must exist). \KPS{} constructs the list
2716 of directories that correspond to this path element, and then checks
2717 in each for the file being sought.
2718
2719 The ``file must exist'' condition comes into play with \samp{.vf} files and
2720 input files read by \TeX's \cs{openin} command. Such files may not
2721 exist (e.g., \file{cmr10.vf}), and so it would be wrong to search the
2722 disk for them. Therefore, if you fail to update \file{ls-R} when you
2723 install a new \samp{.vf} file, it will never be found.
2724 Each path element is checked in turn: first the database, then the
2725 disk. If a match is found, the search stops and the result is
2726 returned.
2727
2728 Although the simplest and most common path element is a directory
2729 name, \KPS{} supports additional features in search paths: layered
2730 default values, environment variable names, config file values, users'
2731 home directories, and recursive subdirectory searching. Thus, we say
2732 that \KPS{} \emph{expands} a path element, meaning it transforms all
2733 the specifications into basic directory name or names. This is
2734 described in the following sections in the same order as it takes
2735 place.
2736
2737 Note that if the filename being searched for is absolute or explicitly
2738 relative, i.e., starts with \samp{/} or \samp{./} or \samp{../},
2739 \KPS{} simply checks if that file exists.
2740
2741 \ifSingleColumn
2742 \else
2743 \begin{figure*}
2744 \verbatiminput{../examples/ex5.tex}
2745 \setlength{\abovecaptionskip}{0pt}
2746 \caption{An illustrative configuration file sample}
2747 \label{fig:config-sample}
2748 \end{figure*}
2749 \fi
2750
2751 \subsubsection{Path sources}
2752 \label{Path-sources}
2753
2754 A search path can come from many sources. In the order in which
2755 \KPS{} uses them:
2756
2757 \begin{enumerate}
2758 \item
2759 A user-set environment variable, for instance, \envname{TEXINPUTS}\@.
2760 Environment variables with a period and a program name appended
2761 override; e.g., if \samp{latex} is the name of the program being run,
2762 then \envname{TEXINPUTS.latex} will override \envname{TEXINPUTS}.
2763 \item
2764 A program-specific configuration file, for exam\-ple, a line
2765 \samp{S /a:/b} in \cmdname{dvips}'s \file{config.ps}.
2766 \item A \KPS{} configuration file \file{texmf.cnf}, containing a line like
2767 \samp{TEXINPUTS=/c:/d} (see below).
2768 \item The compile-time default.
2769 \end{enumerate}
2770 \noindent You can see each of these values for a given
2771 search path by using the debugging options (see ``Debugging actions''
2772 on page~\pageref{Debugging}).
2773
2774 \subsubsection{Config files}
2775
2776 \begingroup\tolerance=3500
2777 \KPS{} reads \emph{runtime configuration files} named \file{texmf.cnf}
2778 for search path and other definitions. The search path used to look
2779 for these files is named \envname{TEXMFCNF} (by default such a file lives
2780 in the \file{texmf/web2c} subdirectory). \emph{All}
2781 \file{texmf.cnf} files in the search path will be read and definitions
2782 in earlier files override those in later files. Thus, with a search
2783 path of \verb|.:$TEXMF|, values from \file{./texmf.cnf} override those
2784 from \verb|$TEXMF/texmf.cnf|.
2785 \endgroup
2786
2787 \begin{itemize}
2788 \item
2789 Comments start with \code{\%} and continue to the end of the line.
2790 \item
2791 Blank lines are ignored.
2792 \item
2793 A \bs{} at the end of a line acts as a continuation character,
2794 i.e., the next line is appended. Whitespace at the beginning of
2795 continuation lines is not ignored.
2796 \item
2797 Each remaining line has the form:
2798 \begin{alltt}
2799 \emph{variable}[.\emph{progname}] [=] \emph{value}
2800 \end{alltt}%
2801 where the \samp{=} and surrounding whitespace are optional.
2802 \item
2803 The \ttvar{variable} name may contain any character other
2804 than whitespace, \samp{=}, or \samp{.}, but sticking to
2805 \samp{A-Za-z\_} is safest.
2806 \item
2807 If \samp{.\var{progname}} is present, the definition only
2808 applies if the program that is running is named
2809 \texttt{\var{progname}} or \texttt{\var{progname}.exe}. This allows
2810 different flavors of \TeX{} to have different search paths, for
2811 example.
2812 \item \var{value} may contain any characters except
2813 \code{\%} and \samp{@}. The
2814 \code{\$\var{var}.\var{prog}} feature is not available on the
2815 right-hand side; instead, you must use an additional variable. A
2816 \samp{;}\ in \var{value} is translated to \samp{:}\ if
2817 running under Unix; this is useful to be able to have a single
2818 \file{texmf.cnf} for Unix, \acro{MS-DOS} and Windows systems.
2819 \item
2820 All definitions are read before anything is expanded, so
2821 variables can be referenced before they are defined.
2822 \end{itemize}
2823 A configuration file fragment illustrating most of these points is
2824 \ifSingleColumn
2825 shown below:
2826
2827 \verbatiminput{../examples/ex5.tex}
2828 \else
2829 shown in Figure~\ref{fig:config-sample}.
2830 \fi
2831
2832 \subsubsection{Path expansion}
2833 \label{Path-expansion}
2834
2835
2836 \KPS{} recognizes certain special characters and constructions in
2837 search paths, similar to those available in Unix shells. As a
2838 general example, the complex path,
2839 \verb+~$USER/{foo,bar}//baz+, expands to all subdirectories under
2840 directories \file{foo} and \file{bar} in \texttt{\$USER}'s home
2841 directory that contain a directory or file \file{baz}. These
2842 expansions are explained in the sections below.
2843 %$
2844 \subsubsection{Default expansion}
2845 \label{Default-expansion}
2846
2847 \tolerance=2500
2848 If the highest-priority search path (see ``Path sources'' on
2849 page~\pageref{Path-sources}) contains an \emph{extra colon} (i.e.,
2850 leading, trailing, or doubled), \KPS{} inserts at that point the
2851 next-highest-prio\-rity search path that is defined. If that inserted
2852 path has an extra colon, the same happens with the next highest. For
2853 example, given an environment variable setting
2854
2855 \tolerance=1500
2856
2857 \begin{alltt}
2858 > \Ucom{setenv TEXINPUTS /home/karl:}
2859 \end{alltt}
2860 and a \code{TEXINPUTS} value from \file{texmf.cnf} of
2861
2862 \begin{alltt}
2863 .:\$TEXMF//tex
2864 \end{alltt}
2865 then the final value used for searching will be:
2866
2867 \begin{alltt}
2868 /home/karl:.:\$TEXMF//tex
2869 \end{alltt}
2870
2871 Since it would be useless to insert the default value in more than one
2872 place, \KPS{} changes only one extra \samp{:}\ and leaves any others in
2873 place: it checks first for a leading \samp{:}, then a trailing
2874 \samp{:}, then a doubled \samp{:}.
2875
2876 \subsubsection{Brace expansion}
2877
2878 A useful feature is brace expansion, which means that, for instance,
2879 \verb+v{a,b}w+ expands to \verb+vaw:vbw+. Nesting is allowed.
2880 This can be used to implement multiple \TeX{} hierarchies, by
2881 assigning a brace list to \code{\$TEXMF}.
2882 For example, in \file{texmf.cnf}, you find
2883 the following definition:
2884 \begin{verbatim}
2885 TEXMF = {$HOMETEXMF,$TEXMFLOCAL,!!$VARTEXMF,!!$TEXMFMAIN}
2886 \end{verbatim}
2887 Using this you can then write something like
2888 \begin{verbatim}
2889 TEXINPUTS = .;$TEXMF/tex//
2890 \end{verbatim}
2891 %$
2892 which means that, after looking in the current directory, the
2893 \code{\$HOMETEXMF/tex}, \code{\$TEXMFLOCAL/tex}, \code{\$VARTEXMF/tex}
2894 and \code{\$TEXMFMAIN/tex} trees \emph{only}) will be searched (the
2895 last two use using \file{ls-R} data base files). It is a convenient
2896 way for running two parallel \TeX{} structures, one ``frozen'' (on a
2897 \CD, for instance) and the other being continuously updated with new
2898 versions as they become available. By using the \code{\$TEXMF}
2899 variable in all definitions, one is sure to always search the
2900 up-to-date tree first.
2901
2902 \subsubsection{Subdirectory expansion}
2903 \label{Subdirectory-expansion}
2904
2905 Two or more consecutive slashes in a path element following a directory
2906 \var{d} is replaced by all subdirectories of \var{d}: first those
2907 subdirectories directly under \var{d}, then the subsubdirectories under
2908 those, and so on. At each level, the order in which the directories are
2909 searched is \emph{unspecified}.
2910
2911 If you specify any filename components after the \samp{//}, only
2912 subdirectories with matching components are included. For example,
2913 \samp{/a//b} expands into directories \file{/a/1/b}, \file{/a/2/b},
2914 \file{/a/1/1/b}, and so on, but not \file{/a/b/c} or \file{/a/1}.
2915
2916 Multiple \samp{//} constructs in a path are possible, but
2917 \samp{//} at the beginning of a path is ignored.
2918
2919 \subsubsection{List of special characters and their meaning: a summary}
2920
2921 The following list summarises the meaning of special characters
2922 in \KPS{} configuration files.
2923
2924 \newcommand{\CODE}[1]{\makebox[2.5em][l]{\code{#1}}}
2925 \begin{ttdescription}
2926 \item[\CODE{:}] Separator in path specification; at the beginning or
2927 the end of a path it substitutes the default path expansion.
2928 \item[\CODE{;}] Separator on non-Unix systems (acts like \code{:}).
2929 \item[\CODE{\$}] Variable expansion.
2930 \item[\CODE{\string~}] Represents the user's home directory.
2931 \item[\CODE{\char`\{\dots\char`\}}] Brace expansion.
2932 \item[\CODE{//}] Subdirectory expansion (can occur anywhere in
2933 a path, except at its beginning).
2934 \item[\CODE{\%}] Start of comment.
2935 \item[\CODE{\bs}] Continuation character (allows multi-line entries).
2936 \item[\CODE{!!}] Search \emph{only} database to locate file, \emph{do
2937 not} search the disk.
2938 \end{ttdescription}
2939
2940
2941 \subsection{Filename databases}
2942 \label{Filename-database}
2943
2944 \KPS{} goes to some lengths to minimize disk accesses for searches.
2945 Nevertheless, at installations with enough directories, searching each
2946 possible directory for a given file can take an excessively long time
2947 (this is especially true if many hundreds of font directories have to
2948 be traversed.) Therefore, \KPS{} can use an externally-built plain text
2949 ``database'' file named \file{ls-R} that maps files to directories,
2950 thus avoiding the need to exhaustively search the disk.
2951
2952 A second database file \file{aliases} allows you to give additional
2953 names to the files listed in \file{ls-R}. This can be helpful to
2954 confirm to \acro{DOS} 8.3 filename conventions in source files.
2955
2956 \subsubsection{The filename database}
2957 \label{ls-R}
2958
2959 As explained above, the name of the main filename database must be
2960 \file{ls-R}. You can put one at the root of each \TeX{} hierarchy in
2961 your installation that you wish to be searched (\code{\$TEXMF} by
2962 default); most sites have only one hierarchy. \KPS{} looks for
2963 \file{ls-R} files along the \code{TEXMFDBS} path.
2964
2965 The recommended way to create and maintain \samp{ls-R} is to run the
2966 \code{mktexlsr} script included with the distribution. It is invoked
2967 by the various \samp{mktex}\dots\ scripts. In principle, this script
2968 just runs the command
2969 \begin{alltt}
2970 cd \var{/your/texmf/root} && ls -LAR ./ >ls-R
2971 \end{alltt}
2972 presuming your system's \code{ls} produces the right output format
2973 (\acro{GNU}'s \code{ls} is all right). To ensure that the database is always
2974 up-to-date, it is easiest to rebuild it regularly via \code{cron}, so
2975 that for changes in the installed files\Dash perhaps after installing or
2976 updating a \LaTeX{} package\Dash the file \file{ls-R} is automatically
2977 updated.
2978
2979 If a file is not found in the database, by default \KPS{} goes ahead
2980 and searches the disk. If a particular path element begins with
2981 \samp{!!}, however, \emph{only} the database will be searched for that
2982 element, never the disk.
2983
2984
2985 \subsubsection{kpsewhich: Standalone path searching}
2986 \label{Invoking-kpsewhich}
2987
2988 The \texttt{kpsewhich} program exercises path searching independent of any
2989 particular application. This can be useful as a sort of \code{find}
2990 program to locate files in \TeX{} hierarchies (this is used heavily in
2991 the distributed \samp{mktex}\dots\ scripts).
2992
2993 \begin{alltt}
2994 > \Ucom{kpsewhich \var{option}\dots{} \var{filename}\dots{}}
2995 \end{alltt}
2996 The options specified in \ttvar{option} start with either \samp{-}
2997 or \samp{-{}-}, and any unambiguous abbreviation is accepted.
2998
2999 \KPS{} looks up each non-option argument on the command line as a
3000 filename, and returns the first file found. There is no option to
3001 return all the files with a particular name (you can run the Unix
3002 \samp{find} utility for that).
3003
3004 The more important options are described next.
3005
3006 \begin{ttdescription}
3007 \item[\texttt{-{}-dpi=\var{num}}]\mbox{}
3008 Set the resolution to \ttvar{num}; this only affects \samp{gf}
3009 and \samp{pk} lookups. \samp{-D} is a synonym, for compatibility
3010 with \cmdname{dvips}. Default is 600.
3011
3012 \item[\texttt{-{}-format=\var{name}}]\mbox{}\\
3013 Set the format for lookup to \ttvar{name}. By default, the
3014 format is guessed from the filename. For formats which do not have
3015 an associated unambiguous suffix, such as \MP{} support files and
3016 \cmdname{dvips} configuration files, you have to specify the name as
3017 found in the first column of Table~\ref{tab:kpathsea}, which lists
3018 currently recognized names, a description, possible file extensions,
3019 and associated environment variables.
3020 \end{ttdescription}
3021
3022
3023 \def\KpathKey#1#2#3#4#5{% name, number, description, variables,
3024 % suffixes
3025 \SetRowColor#1 & #3 & #4 & #5\\}
3026 \def\HEAD#1{\multicolumn{1}{l}{\emph{#1}}}
3027 %
3028 \begin{small}
3029 % a footnoterule immediately under a bottom-of-page rule looks dead
3030 % silly, so we suppress it
3031 \renewcommand\footnoterule{\relax}
3032 %
3033 \begin{longtable}{@{}%
3034 >{\ttfamily}P{.16\textwidth}% Col.1
3035 P{.3\textwidth}% Col 2
3036 >{\ttfamily\footnotesize}P{.29\textwidth}% Col 3
3037 >{\ttfamily}P{.14\textwidth}% Col 4
3038 @{}}
3039 \caption{Kpathsea file types.}\label{tab:kpathsea}\\
3040 \emph{Name} & \HEAD{Description} & \HEAD{Variables}
3041 & \HEAD{Suffixes}\\
3042 \hline
3043 \endfirsthead
3044 \multicolumn{3}{l}{Kpathsea file types \emph{continued}}\\
3045 \emph{Name} & \HEAD{Description} & \HEAD{Variables}
3046 & \HEAD{Suffixes}\\
3047 \hline
3048 \noalign{\vspace{2pt}}
3049 \endhead
3050 \mbox{}\\
3051 \hline
3052 \endfoot
3053 \KpathKey
3054 {afm}
3055 {4}
3056 {Adobe font metrics}
3057 {AFMFONTS}
3058 {.afm}
3059 \KpathKey
3060 {base}
3061 {5}
3062 {Metafont memory dump}
3063 {MFBASES, TEXMFINI}
3064 {.base}
3065 \KpathKey
3066 {bib}
3067 {6}
3068 {\BibTeX{} bibliography source}
3069 {BIBINPUTS, TEXBIB}
3070 {.bib}
3071 \KpathKey
3072 {}
3073 {2}
3074 {bitmap fonts}
3075 {GLYPHFONTS, TEXFONTS}
3076 {}
3077 \KpathKey
3078 {bst}
3079 {7}
3080 {\BibTeX{} style files}
3081 {BSTINPUTS}
3082 {.bst}
3083 \KpathKey
3084 {cnf}
3085 {8}
3086 {Runtime configuration files}
3087 {TEXMFCNF}
3088 {.cnf}
3089 \KpathKey
3090 {dvips config}
3091 {34}
3092 {\textsf{dvips} configuration files, e.g., \file{config.ps}
3093 and \file{psfonts.map}}
3094 {TEXCONFIG}
3095 {.map}
3096 \KpathKey
3097 {fmt}
3098 {10}
3099 {\TeX{} memory dump}
3100 {TEXFORMATS, TEXMFINI}
3101 {.fmt, .efmt, .efm}
3102 \KpathKey
3103 {gf}
3104 {0}
3105 {generic font bitmap}
3106 {GFFONTS}
3107 {.gf}
3108 \KpathKey
3109 {graphic/figure}
3110 {25}
3111 {Encapsulated \PS{} figures}
3112 {TEXPICTS, TEXINPUTS}
3113 {.eps, .epsi}
3114 \KpathKey
3115 {ist}
3116 {35}
3117 {\textsf{makeindex} style files}
3118 {TEXINDEXSTYLE, INDEXSTYLE}
3119 {.ist}
3120 \KpathKey
3121 {ls-R}
3122 {9}
3123 {Filename databases}
3124 {TEXMFDBS}
3125 {}
3126 \KpathKey
3127 {map}
3128 {11}
3129 {Fontmaps}
3130 {TEXFONTMAPS}
3131 {.map}
3132 \KpathKey
3133 {mem}
3134 {12}
3135 {MetaPost memory dump}
3136 {MPMEMS, TEXMFINI}
3137 {.mem}
3138 \KpathKey
3139 {mf}
3140 {13}
3141 {Metafont source}
3142 {MFINPUTS}
3143 {.mf}
3144 \KpathKey
3145 {mfpool}
3146 {14}
3147 {Metafont program strings}
3148 {MFPOOL, TEXMFINI}
3149 {.pool}
3150 \KpathKey
3151 {mft}
3152 {15}
3153 {MFT style file}
3154 {MFTINPUTS}
3155 {.mft}
3156 \KpathKey
3157 {}
3158 {41}
3159 {miscellaneous fonts}
3160 {MISCFONTS}
3161 {}
3162 \KpathKey
3163 {mp}
3164 {16}
3165 {MetaPost source}
3166 {MPINPUTS}
3167 {.mp}
3168 \KpathKey
3169 {mppool}
3170 {17}
3171 {MetaPost program strings}
3172 {MPPOOL, TEXMFINI}
3173 {.pool}
3174 \KpathKey
3175 {MetaPost support}
3176 {18}
3177 {MetaPost support files, used by DMP}
3178 {MPSUPPORT}
3179 {}
3180 \KpathKey
3181 {ocp}
3182 {19}
3183 {\OMEGA{} compiled process files}
3184 {OCPINPUTS}
3185 {.ocp}
3186 \KpathKey
3187 {ofm}
3188 {20}
3189 {\OMEGA{} font metrics}
3190 {OFMFONTS, TEXFONTS}
3191 {.ofm, .tfm}
3192 \KpathKey
3193 {opl}
3194 {21}
3195 {\OMEGA{} property lists}
3196 {OPLFONTS, TEXFONTS}
3197 {.opl}
3198 \KpathKey
3199 {otp}
3200 {22}
3201 {\OMEGA{} translation process files}
3202 {OTPINPUTS}
3203 {.otp}
3204 \KpathKey
3205 {ovf}
3206 {23}
3207 {\OMEGA{} virtual fonts}
3208 {OVFFONTS, TEXFONTS}
3209 {.ovf}
3210 \KpathKey
3211 {ovp}
3212 {24}
3213 {\OMEGA{} virtual property lists}
3214 {OVPFONTS, TEXFONTS}
3215 {.ovp}
3216 \KpathKey
3217 {pk}
3218 {1}
3219 {packed bitmap fonts}
3220 {\emph{program}FONTS \textrm{(\texttt{\emph{program}} being
3221 \textsmaller{\cmdname{XDVI}},
3222 etc.)}, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS}
3223 {.pk}
3224 \KpathKey
3225 {\PS{} header}
3226 {30}
3227 {downloadable \PS{}}
3228 {TEXPSHEADERS, PSHEADERS}
3229 {.pro, .enc}
3230 \KpathKey
3231 {tex}
3232 {26}
3233 {\TeX{} source}
3234 {TEXINPUTS}
3235 {.tex, .cls, .sty, .clo, .def}
3236 \KpathKey
3237 {TeX system documentation}
3238 {27}
3239 {Documentation files for the \TeX{} system}
3240 {TEXDOCS}
3241 {}
3242 \KpathKey
3243 {TeX system sources}
3244 {29}
3245 {Source files for the \TeX{} system}
3246 {TEXSOURCES}
3247 {}
3248 \KpathKey
3249 {texpool}
3250 {28}
3251 {\TeX{} program strings}
3252 {TEXPOOL, TEXMFINI}
3253 {.pool}
3254 \KpathKey
3255 {tfm}
3256 {3}
3257 {\TeX{} font metrics}
3258 {TFMFONTS, TEXFONTS}
3259 {.tfm}
3260 \KpathKey
3261 {Troff fonts}
3262 {31}
3263 {Troff fonts, used by DMP}
3264 {TRFONTS}
3265 {}
3266 \KpathKey
3267 {truetype fonts}
3268 {36}
3269 {TrueType outline fonts}
3270 {TTFONTS}
3271 {.ttf, .ttc}
3272 \KpathKey
3273 {Type~1 fonts}
3274 {32}
3275 {Type 1 \PS{} outline fonts}
3276 {T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS}
3277 {.pfa, .pfb}
3278 \KpathKey
3279 {type42 fonts}
3280 {37}
3281 {Type 42 \PS{} outline fonts}
3282 {T42FONTS}
3283 {}
3284 \KpathKey
3285 {vf}
3286 {33}
3287 {virtual fonts}
3288 {VFFONTS, TEXFONTS}
3289 {.vf}
3290 \KpathKey
3291 {web2c files}
3292 {38}
3293 {\Webc{} support files}
3294 {WEB2C}
3295 {}
3296 \KpathKey
3297 {other text files}
3298 {39}
3299 {text files used by `\textsf{foo}'}
3300 {FOOINPUTS}
3301 {}
3302 \KpathKey
3303 {other binary files}
3304 {40}
3305 {binary files used by `\textsf{foo}'}
3306 {FOOINPUTS}
3307 {}
3308 \end{longtable}
3309 \end{small}
3310
3311
3312 \begin{multicols}{2}
3313
3314 The last two entries in Table~\ref{tab:kpathsea} are special
3315 cases, where the paths and environment variables depend on the name
3316 of the program: the variable name is constructed by converting the
3317 program name to upper case, and then appending \texttt{INPUTS}.
3318
3319 The environment variables are set by default in the configuration
3320 file \file{texmf.cnf}. It is only when you want to override one or
3321 more of the values specified in that file that you might want to set
3322 them explicitly in your execution environment.
3323
3324 The \samp{-{}-format} and \samp{-{}-path} options are mutually
3325 exclusive.
3326
3327 \begin{ttdescription}
3328
3329 \item[\texttt{-{}-mode=\var{string}}]\mbox{}\\
3330 Set the mode name to \ttvar{string}; this only affects \samp{gf}
3331 and \samp{pk} lookups. No default: any mode will be found.
3332 \item[\texttt{-{}-must-exist}]\mbox{}\\
3333 Do everything possible to find the files, notably including
3334 searching the disk. By default, only the \file{ls-R} database is
3335 checked, in the interest of efficiency.
3336 \item[\texttt{-{}-path=\var{string}}]\mbox{}\\
3337 Search along the path \ttvar{string} (colon-separated as usual),
3338 instead of guessing the search path from the filename. \samp{//} and
3339 all the usual expansions are supported. The options \samp{-{}-path}
3340 and \samp{-{}-format} are mutually exclusive.
3341 \item[\texttt{-{}-progname=\var{name}}]\mbox{}\\
3342 Set the program name to \texttt{\var{name}}.
3343 This can affect the search paths via the \texttt{.\var{progname}}
3344 feature.
3345 The default is \cmdname{kpsewhich}.
3346 \item[\texttt{-{}-show-path=\var{name}}]\mbox{}\\
3347 shows the path used for file lookups of file type \texttt{\var{name}}.
3348 Either a filename extension (\code{.pk}, \code{.vf}, etc.) or a
3349 name can be used, just as with \samp{-{}-format} option.
3350 \item[\texttt{-{}-debug=\var{num}}]\mbox{}\\
3351 sets the debugging options to \texttt{\var{num}}.
3352 \end{ttdescription}
3353
3354
3355 \subsubsection{Examples of use}
3356 \label{SExamplesofuse}
3357
3358 Let us now have a look at \KPS{} in action. Here's a straightforward search:
3359
3360 \begin{alltt}
3361 > \Ucom{kpsewhich article.cls}
3362 /usr/local/texmf/tex/latex/base/article.cls
3363 \end{alltt}
3364 We are looking for the file \file{article.cls}. Since the \samp{.cls}
3365 suffix is unambiguous we do not need to specify that we want to look for a
3366 file of type \optname{tex} (\TeX{} source file directories). We find it in
3367 the subdirectory \file{tex/latex/base} below the \samp{TEXMF} root
3368 directory. Similarly, all of the following are found without problems
3369 thanks to their unambiguous suffix.
3370 \begin{alltt}
3371 > \Ucom{kpsewhich array.sty}
3372 /usr/local/texmf/tex/latex/tools/array.sty
3373 > \Ucom{kpsewhich latin1.def}
3374 /usr/local/texmf/tex/latex/base/latin1.def
3375 > \Ucom{kpsewhich size10.clo}
3376 /usr/local/texmf/tex/latex/base/size10.clo
3377 > \Ucom{kpsewhich small2e.tex}
3378 /usr/local/texmf/tex/latex/base/small2e.tex
3379 > \Ucom{kpsewhich tugboat.bib}
3380 /usr/local/texmf/bibtex/bib/beebe/tugboat.bib
3381 \end{alltt}
3382
3383 The latter is a \BibTeX{} bibliography database for \textsl{TUGBoat} articles.
3384
3385 \begin{alltt}
3386 > \Ucom{kpsewhich cmr10.pk}
3387 \end{alltt}
3388 Font bitmap glyph files of type \file{.pk} are used by display
3389 programs like \cmdname{dvips} and \cmdname{xdvi}. Nothing is returned in
3390 this case since there are no pre-generated Computer Modern \samp{.pk}
3391 files on our system (since we use the Type~1 versions included in \TeXLive{}).
3392 \begin{alltt}
3393 > \Ucom{kpsewhich ecrm1000.pk}
3394 \ifSingleColumn /usr/local/texmf/fonts/pk/ljfour/jknappen/ec/ecrm1000.600pk
3395 \else
3396 /usr/local/texmf/fonts/pk/ljfour/jknappen/
3397 ... ec/ecrm1000.600pk
3398 \fi\end{alltt}
3399 For the extended Computer Modern files we had to generate \samp{.pk}
3400 files, and since the default \MF{} mode on our installation is
3401 \texttt{ljfour} with a base resolution of 600\dpi{} (dots per inch),
3402 this instantiation is returned.
3403 \begin{alltt}
3404 > \Ucom{kpsewhich -dpi=300 ecrm1000.pk}
3405 \end{alltt}
3406 In this case, when specifying that we are interested in a resolution
3407 of 300\dpi{} (\texttt{-dpi=300}) we see that no such font is available on
3408 the system. In fact, a program like \cmdname{dvips} or \cmdname{xdvi} would
3409 go off and actually build the \texttt{.pk} files at the required
3410 resolution using the script \cmdname{mktexpk}.
3411
3412 Next we turn our attention to \cmdname{dvips}'s header and configuration
3413 files. We first look at one of the commonly used files, the general
3414 prolog \file{tex.pro} for \TeX{} support, before turning our attention
3415 to the generic configuration file (\file{config.ps}) and the
3416 \PS{} font map \file{psfonts.map}. As the \samp{.ps} suffix is
3417 ambiguous we have to specify explicitly which type we are considering
3418 (\optname{dvips config}) for the file \texttt{config.ps}.
3419 \begin{alltt}
3420 > \Ucom{kpsewhich tex.pro}
3421 /usr/local/texmf/dvips/base/tex.pro
3422 > \Ucom{kpsewhich --format="dvips config" config.ps}
3423 /usr/local/texmf/config/config.ps
3424 > \Ucom{kpsewhich psfonts.map}
3425 /usr/local/texmf/dvips/base/psfonts.map
3426 \end{alltt}
3427
3428 We now take a closer look at the \acro{URW} Times \PS{} support
3429 files. The prefix for these in the standard font naming scheme is
3430 \samp{utm}. The first file we look at is the configuration file,
3431 which contains the name of the map file:
3432 \begin{alltt}
3433 > \Ucom{kpsewhich --format="dvips config" config.utm}
3434 /usr/local/texmf/dvips/psnfss/config.utm
3435 \end{alltt}
3436 The contents of that file is
3437 \begin{alltt}
3438 p +utm.map
3439 \end{alltt}
3440 which points to the file \file{utm.map}, which we want to
3441 locate next.
3442 \begin{alltt}
3443 > \Ucom{kpsewhich --format="dvips config" utm.map}
3444 /usr/local/texmf/dvips/psnfss/utm.map
3445 \end{alltt}
3446 This map file defines the file names of the Type~1 \PS{} fonts in
3447 the URW collection. Its contents look like (we only show part of the
3448 lines):
3449 \begin{alltt}
3450 utmb8r NimbusRomNo9L-Medi ... <utmb8a.pfb
3451 utmbi8r NimbusRomNo9L-MediItal... <utmbi8a.pfb
3452 utmr8r NimbusRomNo9L-Regu ... <utmr8a.pfb
3453 utmri8r NimbusRomNo9L-ReguItal... <utmri8a.pfb
3454 utmbo8r NimbusRomNo9L-Medi ... <utmb8a.pfb
3455 utmro8r NimbusRomNo9L-Regu ... <utmr8a.pfb
3456 \end{alltt}
3457 Let us, for instance, take the Times Roman instance
3458 \file{utmr8a.pfb} and find its position in the \file{texmf} directory
3459 tree with a search for Type~1 font files:
3460 \begin{alltt}
3461 > \Ucom{kpsewhich utmr8a.pfb}
3462 \ifSingleColumn /usr/local/texmf/fonts/type1/urw/utm/utmr8a.pfb
3463 \else /usr/local/texmf/fonts/type1/
3464 ...urw/utm/utmr8a.pfb
3465 \fi\end{alltt}
3466
3467 It should be evident from these few examples how you can easily locate
3468 the whereabouts of a given file. This is especially important if you
3469 suspect that the wrong version of a file is picked up somehow, since
3470 \cmdname{kpsewhich} will show you the first file encountered.
3471
3472 \subsubsection{Debugging actions}
3473 \label{Debugging}
3474
3475 Sometimes it is necessary to investigate how a program resolves file
3476 references. To make this practical, \KPS{} offers various levels of
3477 debugging output:
3478
3479 \begin{ttdescription}
3480 \item[\texttt{\ 1}] \texttt{stat} calls (disk lookups). When running
3481 with an up-to-date \file{ls-R} database this should almost give no
3482 output.
3483 \item[\texttt{\ 2}] References to hash tables (such as the \file{ls-R}
3484 database, map files, configuration files).
3485 \item[\texttt{\ 4}] File open and close operations.
3486 \item[\texttt{\ 8}] General path information for file types
3487 searched by \KPS. This is useful to find out where a particular
3488 path for the file was defined.
3489 \item[\texttt{16}] Directory list for each path element (only relevant
3490 for searches on disk).
3491 \item[\texttt{32}] File searches.
3492 \end{ttdescription}
3493 A value of \texttt{-1} will set all the above options; in practice,
3494 this is usually the most convenient value touse.
3495
3496 Similarly, with the \cmdname{dvips} program, by setting a combination of
3497 debug switches, one can follow in detail where files are being picked up
3498 from. Alternatively, when a file is not found, the debug trace shows in
3499 which directories the program looks for the given file, so that one can
3500 get an indication what the problem~is.
3501
3502 Generally speaking, as most programs call the \KPS{} library
3503 internally, one can select a debug option by using the
3504 \envname{KPATHSEA\_DEBUG} environment variable, and setting it to (a
3505 combination of) values as described in the above list.
3506
3507 (Note for Windows users: it is not easy to redirect
3508 all messages to a file in this system. For diagnostic purposes
3509 you can temporarily \texttt{SET KPATHSEA\_DEBUG\_OUTPUT=err.log}).
3510
3511 Let us consider, as an example, a small \LaTeX{} source file,
3512 \file{hello-world.tex}, which contains the following input.
3513 \begin{verbatim}
3514 \documentclass{article}
3515 \begin{document}
3516 Hello World!
3517 \end{document}
3518 \end{verbatim}
3519 This little file only uses the font \file{cmr10}, so let us look
3520 how \cmdname{dvips} prepares the \PS{} file (we want to use the Type~1
3521 version of the Computer Modern fonts, hence the option \texttt{-Pcms}).
3522 \begin{alltt}
3523 > \Ucom{dvips -d4100 hello-world -Pcms -o}
3524 \end{alltt}
3525 In this case we have combined \cmdname{dvips}'s debug class 4 (font
3526 paths) with \KPS's path element expansion (see \cmdname{dvips} Reference
3527 Manual, \OnCD{texmf/doc/html/dvips/dvips_toc.html}).
3528 The output (slightly rearranged) appears in
3529 Figure~\ref{fig:dvipsdbga}.
3530 \begin{figure*}[tp]
3531 \centering
3532 \input{../examples/ex6a.tex}
3533 \caption{Finding configuration files}\label{fig:dvipsdbga}
3534
3535 \bigskip
3536
3537 \input{../examples/ex6b.tex}
3538 \caption{Finding the prolog file}\label{fig:dvipsdbgb}
3539
3540 \bigskip
3541
3542 \input{../examples/ex6c.tex}
3543 \caption{Finding the font file}\label{fig:dvipsdbgc}
3544 \end{figure*}
3545
3546 \cmdname{dvips} starts by locating its working files. First,
3547 \file{texmf.cnf} is found, which gives the definitions of the search
3548 paths for the other files, then the file database \file{ls-R} (to
3549 optimize file searching) and the file \file{aliases}, which makes it
3550 possible to declare several names (e.g., a short \acro{DOS}-like 8.3 and
3551 a more natural longer version) for the same file. Then \cmdname{dvips}
3552 goes on to find the generic configuration file \file{config.ps}
3553 before looking for the customization file \file{.dvipsrc} (which, in
3554 this case is \emph{not found}). Finally, \cmdname{dvips} locates the
3555 config file for the Computer Modern \PS{} fonts \file{config.cms}
3556 (this was initiated with the \texttt{-Pcms} option on the \cmdname{dvips}
3557 command). This file contains the list of the map files which
3558 define the relation between the \TeX{}, \PS{} and file system
3559 names of the fonts.
3560 \begin{alltt}
3561 > \Ucom{more /usr/local/texmf/dvips/cms/config.cms}
3562 p +ams.map
3563 p +cms.map
3564 p +cmbkm.map
3565 p +amsbkm.map
3566 \end{alltt}
3567 \cmdname{dvips} thus goes on to find all these files, plus the generic
3568 map file \file{psfonts.map}, which is always loaded (it contains
3569 declarations for commonly used \PS{} fonts; see the last part of
3570 Section \ref{SExamplesofuse} for more details about \PS{} map
3571 file handling).
3572
3573 At this point \cmdname{dvips} identifies itself to the user:
3574 \begin{alltt}
3575 This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com)
3576 \end{alltt}
3577 \ifSingleColumn
3578 Then it goes on to look for the prolog file \file{texc.pro}:
3579 \begin{alltt}\small
3580 kdebug:start search(file=texc.pro, must\_exist=0, find\_all=0,
3581 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
3582 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
3583 kdebug:search(texc.pro) => /usr/local/texmf/dvips/base/texc.pro
3584 \end{alltt}
3585 \else
3586 Then it goes on to look for the prolog file \file{texc.pro} (see
3587 Figure~\ref{fig:dvipsdbgb}).
3588 \fi
3589
3590 After having found the file in question, \cmdname{dvips} outputs
3591 date and time, and informs us that it will generate the
3592 file \file{hello-world.ps}, then that it needs the font file
3593 \file{cmr10}, and that the latter is declared as ``resident'' (no
3594 bitmaps needed):
3595 \begin{alltt}\small
3596 TeX output 1998.02.26:1204' -> hello-world.ps
3597 Defining font () cmr10 at 10.0pt
3598 Font cmr10 <CMR10> is resident.
3599 \end{alltt}
3600 Now the search is on for the file \file{cmr10.tfm}, which is found,
3601 then a few more prolog files (not shown) are referenced, and finally
3602 the Type~1 instance \file{cmr10.pfb} of the font is located and
3603 included in the output file (see last line).
3604 \begin{alltt}\small
3605 kdebug:start search(file=cmr10.tfm, must\_exist=1, find\_all=0,
3606 path=.:~/tex/fonts/tfm//:!!/usr/local/texmf/fonts/tfm//:
3607 /var/tex/fonts/tfm//).
3608 kdebug:search(cmr10.tfm) => /usr/local/texmf/fonts/tfm/public/cm/cmr10.tfm
3609 kdebug:start search(file=texps.pro, must\_exist=0, find\_all=0,
3610 ...
3611 <texps.pro>
3612 kdebug:start search(file=cmr10.pfb, must\_exist=0, find\_all=0,
3613 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
3614 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
3615 kdebug:search(cmr10.pfb) => /usr/local/texmf/fonts/type1/public/cm/cmr10.pfb
3616 <cmr10.pfb>[1]
3617 \end{alltt}
3618
3619 \subsection{Runtime options}
3620
3621 Another useful feature of \Webc{} is its possibility to control a number
3622 of memory parameters (in particular, array sizes) via the runtime file
3623 \file{texmf.cnf} read by \KPS{}. The memory settings can be found in
3624 Part 3 of that file in the \TeXLive{} distribution. The more important
3625 are:
3626
3627 \begin{ttdescription}
3628 \item[\texttt{main\_memory}]
3629 Total words of memory available, for
3630 \TeX{}, \MF{} and \MP. You must make a new format file for each
3631 different setting. For instance, you could generate a ``huge''
3632 version of \TeX{}, and call the format file \texttt{hugetex.fmt}.
3633 Using the standard way of specifying the program name used by \KPS{},
3634 the particular value of the \texttt{main\_memory} variable will then
3635 be read from \file{texmf.cnf} (compare the generic value
3636 and the huge one instantiated by \texttt{hugetex},
3637 etc.).
3638 \item[\texttt{extra\_mem\_bot}]
3639 Extra space for ``large'' \TeX{} data structures:
3640 boxes, glue, breakpoints, etc. Especially useful if you use
3641 \PiCTeX{}.
3642 \item[\texttt{font\_mem\_size}]
3643 Number of words for font information available for \TeX. This
3644 is more or less the total size of all TFM files read.
3645 \item[\texttt{hash\_extra}]
3646 Additional space for the hash table of control sequence names.
3647 Approximately 10,000 control sequences can be stored in the main
3648 hash table; if you have a large book with numerous cross-references,
3649 this might not be enough. You can see that both the
3650 \cmdname{hugetex} and \cmdname{pdflatex} program invocations ask for
3651 an extra 15,000 control sequences (the default value of
3652 \texttt{hash\_extra} is zero).
3653 \end{ttdescription}
3654
3655 \noindent Of course, this facility is no substitute for truly dynamic
3656 arrays and memory allocation, but since this is extremely difficult to
3657 implement in the present \TeX{} source, these runtime parameters provide
3658 a practical compromise allowing some flexibility.
3659
3660
3661 \section{Building on a new Unix platform}
3662
3663 If you have a platform for which we have not created executables, you
3664 will need to compile \TeX{} and friends from scratch. This is not as
3665 hard as it sounds. What you need is all in the directory \texttt{source}
3666 in the distribution.
3667
3668 \subsection{Prerequisites}
3669
3670 You will need at least 100 megabytes of disk space to compile all of
3671 \TeX{} and its support programs. You'll also need an \acro{ANSI} C
3672 compiler, a \cmdname{make} utility, a lexical scanner, and a parser
3673 generator. We recommend the \acro{GNU} version of these programs
3674 (\cmdname{gcc}, \acro{GNU} \cmdname{make}, \cmdname{m4}, \cmdname{flex},
3675 \cmdname{bison}). You may be able to work with other C compilers and
3676 \cmdname{make} programs, but you will need a good understanding of
3677 building Unix programs to sort out problems.
3678
3679 Also, the command \texttt{uname} must return a sensible value.
3680
3681
3682 \subsection{Configuration}
3683
3684 To begin, perform a normal installation of \TeXLive{} to your disk (see
3685 section~\ref{sec:unix-install-disk} on
3686 p.~\pageref{sec:unix-install-disk}). You may wish to skip installing
3687 any of the prebuilt binaries.
3688
3689 Then, unpack the source from the compressed \texttt{tar} file in the
3690 directory \dirname{source} to your disk and change directory to where
3691 you placed it.
3692
3693 Next, run \cmdname{configure} with a command line like this:
3694 \begin{alltt}
3695 > \Ucom{sh configure -prefix=/usr/local/TeX}
3696 \end{alltt}
3697
3698 The \optname{-prefix} directory is the one where you installed the
3699 support tree; the directory layout will be as follows (where \$TEXDIR
3700 stands for the directory you chose):
3701
3702 \noindent
3703 \begin{tabular}{>{\ttfamily}ll@{}}
3704 \dirname{$TEXDIR/share/texmf} & main tree with fonts,\\
3705 & \qquad macros, etc\\
3706 \dirname{$TEXDIR/man} & Unix manual pages\\
3707 \dirname{$TEXDIR/info} & \acro{GNU} style Info manuals\\
3708 \dirname{$TEXDIR/bin/$PLATFORM} & binaries\\
3709 \end{tabular}
3710 %$
3711
3712 If you want to leave out the \dirname{$PLATFORM} directory level,
3713 i.e., put the binaries directly into \dirname{$TEXDIR/bin}, specify
3714 the \verb|--disable-multiplatform| option to \cmdname{configure}.
3715
3716 Have a look at the output of \verb|./configure --help| for more
3717 options you can use. For example, you can skip building of \OMEGA{} and
3718 \eTeX{}.
3719
3720
3721 \subsection{Running \cmdname{make}}
3722
3723 Make sure the shell variable or option \texttt{noclobber} is not set.
3724 Then, run the main \cmdname{make} like this:
3725 \begin{alltt}
3726 > \Ucom{make world}
3727 \end{alltt}
3728 and relax\ldots
3729
3730 Alternatively, you want to log all the output, as in:
3731 \begin{alltt}
3732 > \Ucom{sh -c "make world >world.log 2>\&1" \&}
3733 \end{alltt}
3734
3735 Before you believe that everything went ok, please check the log file
3736 for errors: \acro{GNU} \cmdname{make} always uses the string \samp{***}
3737 whenever a command fails. Also, check if all the programs were built:
3738
3739 \begin{alltt}
3740 > \Ucom{cd \emph{TEXDIR}/bin/\emph{archname}}
3741 > \Ucom{ls | wc}
3742 \end{alltt}
3743 The result should be over 200 (you can check the exact number with the
3744 \dirname{bin} directory contents in the distribution).
3745
3746 If you need special privileges for \texttt{make install}, you can
3747 separate the \samp{make world} into two different runs, like this:
3748 \begin{alltt}
3749 > \Ucom{make all}
3750 > \Ucom{su}
3751 > \Ucom{make install strip}
3752 \end{alltt}
3753
3754 After you've installed your new binaries, you should follow the normal
3755 post-installation procedures, given in section~\ref{sec:postinstall}
3756 on p.~\pageref{sec:postinstall}.
3757
3758
3759 \section{Last words}
3760
3761 This edition of \TeXLive{} is edited by Sebastian Rahtz, with the major
3762 contributors being Fabrice Popineau, who has worked away unceasingly at
3763 the Windows part of the package (especially the setup!)\ and contributed
3764 in many different ways with ideas, advice and code, and Staszek
3765 Wawrykiewicz, who provided great testing feedback, and co-ordinated the
3766 Polish contributions.
3767
3768 Kaja Christiansen performed a vital role in endless recompilations on
3769 assorted Unix platforms. Vladimir Volovich did great work on cleaning
3770 the source and making other improvements, while Gerben Wierda did all
3771 the work for \MacOSX.
3772
3773 \subsection{Acknowledgements}
3774
3775 \TeXLive{} is a joint effort by virtually all \TeX{} Users Groups. In
3776 particular, we are very grateful for past and present help from:
3777
3778 \begin{itemize}
3779
3780 \item The German-speaking \TeX{} Users (\acro{DANTE} e.V.), who provide
3781 the hardware the \TeXLive{} source repository; and Rainer Sch\"opf and
3782 Reinhard Zierke who look after it. \acro{DANTE} president Volker Schaa
3783 coordinated production with the Lehmann's Bookstore
3784 (\url{http://www.lob.de}).
3785
3786 \item The Perforce corporation (\url{http://www.perforce.com}), for providing
3787 a free copy of their excellent change management system, which we use to
3788 manage.
3789
3790 \item Karl Berry, who provided the original \Webc{} distribution, and
3791 has continued to give invaluable advice, encouragement, and help.
3792
3793 \item Mimi Burbank, who arranged access at the Florida State University
3794 School of Computational Science and Information Technology to a slew of
3795 different computers to compile \TeX{} on, and acted as an essential
3796 guinea-pig whenever asked.
3797
3798 \item Thomas Esser, without whose marvellous \teTeX{} package \TeXLive{}
3799 would certainly not exist, and whose continual help makes it a better
3800 product.
3801
3802 \item Michel Goossens, who co-authored the documentation.
3803
3804 \item Eitan Gurari, whose \TeX4ht was used to create the \HTML{}
3805 version of this documentation, and who worked tirelessly to improve
3806 it at short notice.
3807
3808 \item Petr Olsak, who coordinated and checked all the Czech and Slovak
3809 material very carefully.
3810
3811 \item Olaf Weber, for his patient assembly and maintenance of Web2c.
3812
3813 \item Graham Williams, on whose work the catalogue of packages depends.
3814
3815 \end{itemize}
3816
3817 In addition, Gerhard Wilhelms, Volker Schaa, Fabrice Popineau, Janka
3818 Chleb\'\i{}kov\'a, Staszek Wawrykiewicz, Erik Frambach, and Ulrik Vieth
3819 kindly translated documentation at various times into their respective
3820 languages, checked other documentation, and provided very welcome
3821 feedback.
3822
3823
3824 \subsection{Release history}
3825 \label{sec:history}
3826
3827 Discussion began in late 1993 when the Dutch \TeX{} Users Group was
3828 starting work on its 4All\TeX{} \CD{} for \acro{MS-DOS} users, and it
3829 was hoped at that time to issue a single, rational, \CD{} for all
3830 systems. This was too ambitious a target for the time, but it did spawn
3831 not only the very successful 4All\TeX{} \CD{}, but also the \acro{TUG}
3832 Technical Council working group on a \emph{\TeX{} Directory Structure}
3833 (\url{http://tug.org/tds}), which specified how to create consistent and
3834 manageable collections of \TeX{} support files. A complete draft of the
3835 \TDS{} was published in the December 1995 issue of \textsl{TUGboat}, and
3836 it was clear from an early stage that one desirable product would be a
3837 model structure on \CD{}. The distribution you now have is a very direct
3838 result of the working group's deliberations. It was also clear that the
3839 success of the 4All\TeX{} \CD{} showed that Unix users would benefit
3840 from a similarly easy system, and this is the other main strand of
3841 \TeXLive.
3842
3843 We first undertook to make a new Unix-based \TDS{} \CD{} in the autumn
3844 of 1995, and quickly identified Thomas Esser's \teTeX{} as the ideal
3845 setup, as it already had multi-platform support and was built with
3846 portability across file systems in mind. Thomas agreed to help, and work
3847 began seriously at the start of 1996. The first edition was released in
3848 May 1996. At the start of 1997, Karl Berry completed a major new release
3849 of Web2c, which included nearly all the features which Thomas Esser had
3850 added in \teTeX, and we decided to base the 2nd edition of the \CD{} on
3851 the standard \Webc, with the addition of \teTeX's \texttt{texconfig}
3852 script. The 3rd edition of the \CD{} was based on a major revision of
3853 \Webc, 7.2, by Olaf Weber; at the same time, a new revision of \teTeX
3854 was being made, and \TeXLive{} included almost all of its features. The
3855 4th edition followed the same pattern, using a new version of \teTeX,
3856 and a new release of \Webc{} (7.3). The system now included a complete
3857 Windows setup.
3858
3859 For the 5th edition (March 2000) many parts of the \CD{} were revised
3860 and checked, updating hundreds of packages. Package details were stored
3861 in XML files. But the major change for \TeX\ Live 5 was that all
3862 non-free software was removed. Everything in \TeXLive{} is now intended
3863 to be compatible with the Debian Free Software Guidelines
3864 (\url{http://www.debian.org/intro/free}); we have done our best to check
3865 the license conditions of all packages, but we would very much
3866 appreciate hearing of any mistakes.
3867
3868 The 6th edition (July 2001) had much more material updated. The major
3869 change was a new install concept: the user could select a more exact set
3870 of needed collections. Language-related collections were completely
3871 reorganized, so selecting any of them installs not only macros, fonts,
3872 etc., but also prepares an appropriate \texttt{language.dat}.
3873
3874 The 7th edition of 2002 had the notable addition of \MacOSX{} support,
3875 and the usual myriad of updates to all sorts of packages and
3876 programs. An important goal was integration of the source back with
3877 \teTeX, to correct the drift apart in versions~5 and~6.
3878
3879 In 2003, with the continuing flood of updates and additions, we found
3880 that \TeXLive{} had grown so large it could no longer be contained on a
3881 single \CD, so we split it into three different distributions (see
3882 section~\ref{sec:multiple-dist} on p.~\pageref{sec:multiple-dist}). In
3883 addition:
3884
3885 \begin{itemize}
3886 \item At the request of the \LaTeX{} team, we changed the standard
3887 \cmdname{latex} and \cmdname{pdflatex} commands to now use \eTeX{} (see
3888 p.~\pageref{text:etex}).
3889 \item The new Latin Modern fonts were included (and are recommended).
3890 \item Support for Alpha \acro{OSF} was removed
3891 (\acro{HPUX} support was removed previously), since no one had (or
3892 volunteered) hardware available on which to compile new binaries.
3893 \item Windows setup was substantially changed; for the first time
3894 an integrated environment based on XEmacs was introduced.
3895 \item Important supplementary programs for Windows
3896 (Perl, Ghost\-script, Image\-Magick, Ispell) are now installed
3897 in the \TeXLive{} installation directory.
3898 \item Font map files used by \cmdname{dvips}, \cmdname{dvipdfm}
3899 and \cmdname{pdftex} are now generated by the new program
3900 \cmdname{updmap} and installed into \dirname{texmf/fonts/map}.
3901 \item \TeX{}, \MF{}, and \MP{} now, by default, output 8-bit input
3902 characters as themselves in output (e.g., \verb|\write|) files,
3903 log files, and the terminal, i.e., \emph{not} translated using the
3904 \verb|^^| notation. In \TeXLive{}~7, this translation was
3905 dependent on the system locale settings; now, locale settings do
3906 not influence the \TeX{} programs' behavior. If for some reason
3907 you need the \verb|^^| output, rename the file
3908 \verb|texmf/web2c/cp8bit.tcx|. (Future releases will have cleaner
3909 ways to control this.)
3910 \item This documentation was substantially revised.
3911 \item Finally, since the edition numbers had grown unwieldy,
3912 the version is now simply identified by the year: \TeXLive{} 2003.
3913 \end{itemize}
3914
3915
3916 \subsection{Future releases}
3917
3918 \emph{\TeXLive{} is not perfect!} (And never will be.) We intend to
3919 continue to release new versions yearly, and would like to provide more
3920 help material, more utilities, more installation programs, and (of
3921 course) an ever-improved and checked tree of macros and fonts. This work
3922 is all done by hard-pressed volunteers in their limited spare time, and
3923 a great deal remains to be done. If you can help, don't hesitate to put
3924 your name forward!
3925
3926 Please send corrections, suggestions, and offers of help to:\hfill\null
3927 \begin{quote}
3928 Sebastian Rahtz \ / \ 7 Stratfield Road \ / \ Oxford OX2 7BG \ / \ UK \\
3929 \email{[email protected]} \\
3930 \url{http://tug.org/texlive}
3931 \end{quote}
3932
3933 \medskip
3934 \noindent \textsl{Happy \TeX'ing!}
3935
3936 \end{multicols}
3937 \end{document}