Debian Codegraph @

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

raw
1 % $Id: texlive-en.tex 33865 2014-05-05 22:37:40Z karl $
2 % TeX Live documentation. Originally written by Sebastian Rahtz and
3 % Michel Goossens, now maintained by Karl Berry and others.
4 % Public domain.
5 %
6 \documentclass{article}
7 \let\tldocenglish=1 % for live4ht.cfg
8 \usepackage{tex-live}
9 \usepackage[latin1]{inputenc} % translators: use your preferred encodings.
10 \usepackage[T1]{fontenc}
11
12 \begin{document}
13
14 \title{%
15 {\huge \textit{The \TeX\ Live Guide---2014}}
16 }
17
18 \author{Karl Berry, editor \\[3mm]
19 \url{http://tug.org/texlive/}
20 }
21
22 \date{May 2014}
23
24 \maketitle
25
26 \begin{multicols}{2}
27 \tableofcontents
28 %\listoftables
29 \end{multicols}
30
31 \section{Introduction}
32 \label{sec:intro}
33
34 \subsection{\TeX\ Live and the \TeX\ Collection}
35
36 This document describes the main features of the \TL{} software
37 distribution\Dash \TeX{} and related programs for \GNU/Linux
38 and other Unix flavors, \MacOSX, and Windows systems.
39
40 You may have acquired \TL{} by downloading, or on the \TK{} \DVD, which
41 \TeX{} user groups distribute among their members, or in other ways.
42 Section \ref{sec:tl-coll-dists} briefly describes the contents of the
43 \DVD. Both \TL{} and the \TK{} are cooperative efforts by the \TeX{}
44 user groups. This document mainly describes \TL{} itself.
45
46 \TL{} includes executables for \TeX{}, \LaTeXe{}, \ConTeXt,
47 \MF, \MP, \BibTeX{} and many other programs; an extensive collection
48 of macros, fonts and documentation; and support for typesetting in
49 many different scripts from around the world.
50
51 For a brief summary of the major changes in this edition of \TL{},
52 see the end of the document, section~\ref{sec:history}
53 (\p.\pageref{sec:history}).
54
55
56 \htmlanchor{platforms}
57 \subsection{Operating system support}
58 \label{sec:os-support}
59
60 \TL{} contains binaries for many Unix-based platforms, including
61 \GNU/Linux, \MacOSX, and Cygwin. The included sources can be compiled
62 on platforms for which we do not provide binaries.
63
64 As to Windows: Windows \acro{XP} and later are supported. Windows~2000
65 will probably still mostly work. There are no special 64-bit
66 executables for Windows, but the 32-bit executables should run on 64-bit
67 systems.
68
69 See section~\ref{sec:tl-coll-dists} for alternate solutions
70 for Windows and \MacOSX.
71
72 \subsection{Basic installation of \protect\TL{}}
73 \label{sec:basic}
74
75 You can install \TL{} either from \DVD{} or over the Internet
76 (\url{http://tug.org/texlive/acquire.html}). The net installer itself is
77 small, and downloads everything requested from the Internet.
78
79 The \DVD{} installer lets you install to a local disk. You cannot run
80 \TL{} directly from the \TK{} \DVD{} (or its \code{.iso} image), but you
81 can prepare a runnable installation on, e.g., a \USB{} stick (see
82 section~\ref{sec:portable-tl}). Installation is described in later
83 sections (\p.\pageref{sec:install}), but here is a quick start:
84
85 \begin{itemize*}
86
87 \item The installation script is named \filename{install-tl}. It can
88 operate in a ``wizard mode'' given the option \code{-gui=wizard}
89 (default for Windows), a text mode given \code{-gui=text} (default for
90 everything else), and an expert \GUI{} mode given \code{-gui=perltk}.
91
92 \item One of the installed items is the `\TL\ Manager' program,
93 named \prog{tlmgr}. Like the installer, it can be used in both \GUI{}
94 mode and in text mode. You can use it to install and uninstall
95 packages and do various configuration tasks.
96
97 \end{itemize*}
98
99
100 \htmlanchor{security}
101 \subsection{Security considerations}
102 \label{sec:security}
103
104 To the best of our knowledge, the core \TeX\ programs themselves are
105 (and always have been) extremely robust. However, the contributed
106 programs in \TeX\ Live may not reach the same level, despite everyone's
107 best efforts. As always, you should be careful when running programs on
108 untrusted input; for maximum safety, use a new subdirectory.
109
110 This need for care is especially urgent on Windows, since in general
111 Windows finds programs in the current directory before anything else,
112 regardless of the search path. This opens up a wide variety of possible
113 attacks. We have closed many holes, but undoubtedly some remain,
114 especially with third-party programs. Thus, we recommend checking for
115 suspicious files in the current directory, especially executables
116 (binaries or scripts). Ordinarily they should not be present, and
117 definitely should not normally be created by merely processing a document.
118
119 Finally, \TeX\ (and its companion programs) are able to write files when
120 processing documents, a feature that can also be abused in a wide
121 variety of ways. Again, processing unknown documents in a new
122 subdirectory is the safest bet.
123
124
125 \subsection{Getting help}
126 \label{sec:help}
127
128 The \TeX{} community is active and friendly, and most serious questions
129 end up getting answered. However, the support is informal, done by
130 volunteers and casual readers, so it's especially important that you do
131 your homework before asking. (If you prefer guaranteed commercial
132 support, you can forgo \TL{} completely and purchase a vendor's system;
133 \url{http://tug.org/interest.html#vendors} has a list.)
134
135 Here is a list of resources, approximately in the order we recommend
136 using them:
137
138 \begin{description}
139 \item [Getting Started] If you are new to \TeX, the web page
140 \url{http://tug.org/begin.html} gives a brief introduction to the system.
141
142 \item [\TeX{} \acro{FAQ}] The \TeX{} \acro{FAQ} is a huge compendium
143 of answers to all sorts of questions, from the most basic to the
144 most arcane. It is included on \TL{} in
145 \OnCD{texmf-dist/doc/generic/FAQ-en/}, and is available
146 on the Internet through \url{http://www.tex.ac.uk/faq}. Please
147 check here first.
148
149 \item [\TeX{} Catalogue] If you are looking for a specific package,
150 font, program, etc., the \TeX{} Catalogue is the place to look. It is a
151 huge collection of all \TeX{}-related items. See
152 \url{http://mirror.ctan.org/help/Catalogue/}.
153
154 \item [\TeX{} Web Resources] The web page
155 \url{http://tug.org/interest.html} has many \TeX{}-related links, in
156 particular for numerous books, manuals, and articles on all aspects of
157 the system.
158
159 \item [support archives] Principal support forums include the
160 Usenet newsgroup \url{news:comp.text.tex}, the mailing list
161 \email{[email protected]}, and \url{http://tex.stackexchange.com}, a
162 collaboratively edited question and answer site. Their archives have
163 years of past questions and answers for your searching pleasure, via
164 \url{http://groups.google.com/group/comp.text.tex/topics} and
165 \url{http://tug.org/mail-archives/texhax}, respectively. And a general
166 web search, for example on \url{http://google.com}, never hurts.
167
168 \item [asking questions] If you cannot find an answer, you can post to
169 \dirname{comp.text.tex} through Google or your newsreader, or to
170 \email{[email protected]} through email. But before you post,
171 \emph{please} read this \acro{FAQ} entry, to maximize
172 your chances of getting a useful answer:
173 \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=askquestion}.
174 Also worth mentioning are the \LaTeX{} Community site at
175 \url{http://www.latex-community.org/} and its forum
176 \url{http://www.latex-community.org/forum/}, and
177 \TeX\ StackExchange at \url{http://tex.stackexchange.com/}.
178
179 \item [\TL{} support] If you want to report a bug or have
180 suggestions or comments on the \TL{} distribution, installation, or
181 documentation, the mailing list is \email{[email protected]}. However,
182 if your question is about how to use a particular program included in
183 \TL{}, please write to that program's maintainer or
184 mailing list. Often running a program with the \code{-{}-help} option
185 will provide a bug reporting address.
186
187 \end{description}
188
189 The other side of the coin is helping others who have questions. Both
190 \dirname{comp.text.tex} and \code{texhax} are open to anyone, so feel
191 free to join, start reading, and help out where you can.
192
193
194 % don't use \TL so the \uppercase in the headline works. Also so
195 % tex4ht ends up with the right TeX. Likewise the \protect's.
196 \section{Overview of \protect\TeX\protect\ Live}
197 \label{sec:overview-tl}
198
199 This section describes the contents of \TL{} and the \TK{} of which it
200 is a part.
201
202 \subsection{The \protect\TeX\protect\ Collection: \TL, pro\TeX{}t, Mac\TeX}
203 \label{sec:tl-coll-dists}
204
205 The \TK{} \DVD{} comprises the following:
206
207 \begin{description}
208
209 \item [\TL] A complete \TeX{} system to be installed to disk. Home
210 page: \url{http://tug.org/texlive/}.
211
212 \item [Mac\TeX] for \MacOSX, this adds a native \MacOSX\ installer and other
213 Mac applications to \TL{}. Home page:
214 \url{http://tug.org/mactex/}.
215
216 \item [pro\TeX{}t] An enhancement of the \MIKTEX\ distribution for Windows,
217 \ProTeXt\ adds a few extra tools to \MIKTEX, and simplifies
218 installation. It is entirely independent of \TL{}, and has its own
219 installation instructions. Home page:
220 \url{http://tug.org/protext/}.
221
222 \item [CTAN] A snapshot of the \CTAN{} repository (\url{http://www.ctan.org/}).
223
224 \end{description}
225
226 \CTAN{} and \pkgname{protext} do not follow the same copying conditions
227 as \TL{}, so be careful when redistributing or modifying.
228
229
230 \subsection{Top level \TL{} directories}
231 \label{sec:tld}
232
233 Here is a brief listing and description of the top level directories in a
234 \TL{} installation.
235
236 \begin{ttdescription}
237 \item[bin] The \TeX{} system programs, arranged by platform.
238 %
239 \item[readme-*.dir] Quick overview and useful links for \TL{},
240 in various languages, in both \HTML{} and plain text.
241 %
242 \item[source] The source to all included programs, including the main
243 \Webc{}-based \TeX{} distributions.
244 %
245 \item[texmf-dist] The principal tree; see \dirname{TEXMFDIST} below.
246 %
247 \item[tlpkg] Scripts, programs and data for managing the
248 installation, and special support for Windows.
249 \end{ttdescription}
250
251 In addition to the directories above, the installation scripts and
252 \filename{README} files (in various languages) are at the top level of
253 the distribution.
254
255 For documentation, the comprehensive links in the top-level file
256 \OnCD{doc.html} may be helpful. The documentation for nearly everything
257 (packages, formats, fonts, program manuals, man pages, Info files) is in
258 \dirname{texmf-dist/doc}. You can use the \cmdname{texdoc} program to
259 find documentation wherever it is located.
260
261 This \TL\ documentation itself is in \dirname{texmf-dist/doc/texlive},
262 available in several languages:
263
264 \begin{itemize*}
265 \item{Czech/Slovak:} \OnCD{texmf-dist/doc/texlive/texlive-cz}
266 \item{German:} \OnCD{texmf-dist/doc/texlive/texlive-de}
267 \item{English:} \OnCD{texmf-dist/doc/texlive/texlive-en}
268 \item{French:} \OnCD{texmf-dist/doc/texlive/texlive-fr}
269 \item{Italian:} \OnCD{texmf-dist/doc/texlive/texlive-it}
270 \item{Polish:} \OnCD{texmf-dist/doc/texlive/texlive-pl}
271 \item{Russian:} \OnCD{texmf-dist/doc/texlive/texlive-ru}
272 \item{Serbian:} \OnCD{texmf-dist/doc/texlive/texlive-sr}
273 \item{Simplified Chinese:} \OnCD{texmf-dist/doc/texlive/texlive-zh-cn}
274 \end{itemize*}
275
276 \subsection{Overview of the predefined texmf trees}
277 \label{sec:texmftrees}
278
279 This section lists the predefined variables specifying the texmf trees
280 used by the system, and their intended purpose, and the default layout
281 of \TL{}. The command \texttt{tlmgr~conf} shows the values of these
282 variables, so that you can easily find out how they map to particular
283 directories in your installation.
284
285 All of the trees, including the personal ones, should follow the \TeX\
286 Directory Structure (\TDS, \url{http://tug.org/tds}), with all its
287 myriad subdirectories, or files may not be found. Section
288 \ref{sec:local-personal-macros} (\p.\pageref{sec:local-personal-macros})
289 describes this in more detail.
290
291 \begin{ttdescription}
292 \item [TEXMFDIST] The tree which holds nearly all of the files in the original
293 distribution---configuration files, scripts, packages, fonts, etc.
294 (The main exception are the per-platform executables, which are stored
295 in a sibling directory \code{bin/}.)
296 \item [TEXMFLOCAL] The tree which administrators can use for system-wide
297 installation of additional or updated macros, fonts, etc.
298 \item [TEXMFHOME] The tree which users can use for their own individual
299 installations of additional or updated macros, fonts, etc.
300 The expansion of this variable dynamically adjusts for each user to
301 their own individual directory.
302 \item [TEXMFCONFIG] The (personal) tree used by the utilities
303 \verb+texconfig+, \verb+updmap+, and \verb+fmtutil+ to store modified
304 configuration data.
305 \item [TEXMFSYSCONFIG] The (site-wide) tree used by the utilities
306 \verb+texconfig-sys+, \verb+updmap-sys+, and \verb+fmtutil-sys+ to
307 store modified configuration data.
308 \item [TEXMFVAR] The (personal) tree used by \verb+texconfig+,
309 \verb+updmap+ and \verb+fmtutil+ to store (cached) runtime data such
310 as format files and generated map files.
311 \item [TEXMFSYSVAR] The (site-wide) tree used by \verb+texconfig-sys+,
312 \verb+updmap-sys+ and \verb+fmtutil-sys+, and also by \verb+tlmgr+, to
313 store (cached) runtime data such as format files and generated map files.
314 \item [TEXMFCACHE] The tree(s) used by \ConTeXt\ Mk\acro{IV} and Lua\LaTeX\
315 to store (cached) runtime data; defaults to \code{TEXMFSYSVAR},
316 or (if that's not writable), \code{TEXMFVAR}.
317 \end{ttdescription}
318
319 \noindent
320 The default layout is:
321 \begin{description}
322 \item[system-wide root] can span multiple \TL{} releases:
323 \begin{ttdescription}
324 \item[2013] A previous release.
325 \item[2014] The current release.
326 \begin{ttdescription}
327 \item [bin] ~
328 \begin{ttdescription}
329 \item [i386-linux] \GNU/Linux binaries
330 \item [...]
331 \item [universal-darwin] \MacOSX\ binaries
332 \item [win32] Windows binaries
333 \end{ttdescription}
334 \item [texmf-dist\ \ ] \envname{TEXMFDIST} and \envname{TEXMFMAIN}
335 \item [texmf-var \ \ ] \envname{TEXMFSYSVAR}, \envname{TEXMFCACHE}
336 \item [texmf-config] \envname{TEXMFSYSCONFIG}
337 \end{ttdescription}
338 \item [texmf-local] \envname{TEXMFLOCAL}, intended to be
339 retained from release to release.
340 \end{ttdescription}
341 \item[user's home directory] (\texttt{\$HOME} or
342 \texttt{\%USERPROFILE\%})
343 \begin{ttdescription}
344 \item[.texlive2013] Privately generated and configuration data
345 for a previous release.
346 \item[.texlive2014] Privately generated and configuration data
347 for the current release.
348 \begin{ttdescription}
349 \item [texmf-var\ \ \ ] \envname{TEXMFVAR}, \envname{TEXMFCACHE}
350 \item [texmf-config] \envname{TEXMFCONFIG}
351 \end{ttdescription}
352 \item[texmf] \envname{TEXMFHOME} Personal macros, etc.
353 \end{ttdescription}
354 \end{description}
355
356
357 \subsection{Extensions to \protect\TeX}
358 \label{sec:tex-extensions}
359
360 Knuth's original \TeX{} itself is frozen, apart from rare bug fixes. It
361 is present in \TL\ as the program \prog{tex}, and will remain so
362 for the foreseeable future. \TL{} also contains several extended versions of
363 \TeX (also known as \TeX\ engines):
364
365 \begin{description}
366
367 \item [\eTeX] adds a set of new primitives
368 \label{text:etex} (related to macro expansion, character scanning,
369 classes of marks, additional debugging features, and more) and the
370 \TeXXeT{} extensions for bidirectional typesetting. In default mode,
371 \eTeX{} is 100\% compatible with ordinary \TeX. See
372 \OnCD{texmf-dist/doc/etex/base/etex_man.pdf}.
373
374 \item [pdf\TeX] builds on the \eTeX\ extensions, adding support for
375 writing \acro{PDF} output as well as \dvi{}, and many non-output-related
376 extensions. This is the program invoked for most formats, e.g.,
377 \prog{etex}, \prog{latex}, \prog{pdflatex}. Its web site is
378 \url{http://www.pdftex.org/}. See
379 \OnCD{texmf-dist/doc/pdftex/manual/pdftex-a.pdf} for the manual, and
380 \OnCD{texmf-dist/doc/pdftex/manual/samplepdf/samplepdf.tex} for example
381 usage of some of its features.
382
383 \item [Lua\TeX] is the designated successor of pdf\TeX,
384 and is mostly (but not entirely) backward-compatible. It is also
385 intended to be a functional superset of Aleph (see below), though
386 technical compatibility is not intended. The incorporated Lua
387 interpreter (\url{http://www.lua.org/}) enables elegant solutions for
388 many thorny \TeX{} problems. When called as \filename{texlua}, it
389 functions as a standalone Lua interpreter, and is already used as such
390 within \TL. Its web site is \url{http://www.luatex.org/}, and the
391 reference manual is \OnCD{texmf-dist/doc/luatex/base/luatexref-t.pdf}.
392
393 \item [\XeTeX] adds support for Unicode input and OpenType- and system
394 fonts, implemented using standard third-party libraries. See
395 \url{http://tug.org/xetex}.
396
397 \item [\OMEGA\ (Omega)] is based on Unicode (16-bit characters), thus
398 supports working with almost all the world's scripts simultaneously. It
399 also supports so-called `\OMEGA{} Translation Processes' (\acro{OTP}s),
400 for performing complex transformations on arbitrary input. Omega is no
401 longer included in \TL{} as a separate program; only Aleph is provided:
402
403 \item [Aleph] combines the \OMEGA\ and \eTeX\ extensions.
404 See \OnCD{texmf-dist/doc/aleph/base}.
405
406 \end{description}
407
408
409 \subsection{Other notable programs in \protect\TL}
410
411 Here are a few other commonly-used programs included in \TL{}:
412
413 \begin{cmddescription}
414
415 \item [bibtex, bibtex8] bibliography support.
416
417 \item [makeindex, xindy] index support.
418
419 \item [dvips] convert \dvi{} to \PS{}.
420
421 \item [xdvi] \dvi{} previewer for the X Window System.
422
423 \item [dvilj] \dvi{} drive for the HP LaserJet family.
424
425 \item [dviconcat, dviselect] cut and paste pages
426 from \dvi{} files.
427
428 \item [dvipdfmx] convert \dvi{} to \acro{PDF}, an alternative approach
429 to pdf\TeX\ (mentioned above).
430
431 \item [psselect, psnup, \ldots] \PS{} utilities.
432
433 \item [pdfjam, pdfjoin, \ldots] \acro{PDF} utilities.
434
435 \item [context, mtxrun] Con\TeX{}t and \acro{PDF} processor.
436
437 \item [htlatex, \ldots] \cmdname{tex4ht}: \AllTeX{} to \acro{HTML} (and
438 \acro{XML} and more) converter.
439
440 \end{cmddescription}
441
442
443 \htmlanchor{installation}
444 \section{Installation}
445 \label{sec:install}
446
447 \subsection{Starting the installer}
448 \label{sec:inst-start}
449
450 To begin, get the \TK{} \DVD{} or download the \TL{} net installer. See
451 \url{http://tug.org/texlive/acquire.html} for more information and other
452 methods of getting the software.
453
454 \begin{description}
455 \item [Net installer, .zip or .tar.gz:] Download from \CTAN, under
456 \dirname{systems/texlive/tlnet}; the url
457 \url{http://mirror.ctan.org/systems/texlive/tlnet} will automatically
458 redirect to a nearby, up-to-date, mirror. You can retrieve either
459 \filename{install-tl.zip} which can be used under Unix and Windows, or
460 the considerably smaller \filename{install-unx.tar.gz} for Unix
461 only. After unpacking, \filename{install-tl} and
462 \filename{install-tl-windows.bat} will be in the \dirname{install-tl}
463 subdirectory.
464
465 \item[Net installer, Windows .exe:] Download from \CTAN{} as above,
466 and double-click. This starts up a first-stage installer and unpacker;
467 see Figure~\ref{fig:nsis}. It gives three choices: ``Simple install''
468 starts up the wizard installer, ``Custom install'' the expert GUI
469 installer, as described in section~\ref{sec:wininst}. A third option is
470 just unpacking.
471
472 \item [\TeX{} Collection \DVD:] go to the \DVD's \dirname{texlive}
473 subdirectory. Under Windows, the installer normally starts automatically
474 when you insert the \DVD. You can get the \DVD\ by becoming a member of
475 a \TeX\ user group (highly recommended,
476 \url{http://tug.org/usergroups.html}), or purchasing it separately
477 (\url{http://tug.org/store}), or burning your own from the \ISO\ image.
478 You can also mount the \ISO\ directly on most systems. After installing
479 from \DVD\ or \ISO, if you want to get continuing updates from the
480 Internet, please see \ref{sec:dvd-install-net-updates}.
481
482 \end{description}
483
484 \begin{figure}[tb]
485 \tlpng{nsis_installer}{.6\linewidth}
486 \caption{First stage of Windows .exe installer}\label{fig:nsis}
487 \end{figure}
488
489 The same installer program is run, whatever the source. The most
490 visible difference between the two is that with the net installer, what
491 you end up with is the packages that are currently available. This is
492 in contrast to the \DVD\ and \ISO\ images, which are not updated between
493 the major public releases.
494
495 \noindent
496 The following sections explain installer start-up in more detail.
497
498 \subsubsection{Unix}
499
500 Below, \texttt{>} denotes the shell prompt; user input is
501 \Ucom{\texttt{bold}}.
502 The script \filename{install-tl} is a Perl script. The simplest way
503 to start it on a Unix-compatible system is as follows:
504 \begin{alltt}
505 > \Ucom{perl /path/to/installer/install-tl}
506 \end{alltt}
507 (Or you can invoke \Ucom{/path/to/installer/install-tl} if it stayed
508 executable, or \texttt{cd} to the directory first, etc.; we won't repeat
509 all the variations.) You may have to enlarge your terminal window so
510 that it shows the full text installer screen
511 (Figure~\ref{fig:text-main}).
512
513 To install in expert \GUI\ mode (figure~\ref{fig:gui-main}), you'll
514 need the \dirname{Perl::TK} module compiled with \acro{XFT} support,
515 which is generally the case with \GNU/Linux, but often not so with other
516 systems. Given that, you can run:
517 \begin{alltt}
518 > \Ucom{perl install-tl -gui}
519 \end{alltt}
520
521 For a complete listing of the various options:
522 \begin{alltt}
523 > \Ucom{perl install-tl -help}
524 \end{alltt}
525
526 \textbf{Warning about Unix permissions:} Your \code{umask} at the time
527 of installation will be respected by the \TL{} installer. Therefore, if
528 you want your installation to be usable by users other than you, make
529 sure your setting is sufficiently permissive, for instance, \code{umask
530 002}. For more information about \code{umask}, consult your system
531 documentation.
532
533 \textbf{Special considerations for Cygwin:} Unlike other
534 Unix-compatible systems, Cygwin does not by default include all of the
535 prerequisite programs needed by the \TL{} installer. See
536 Section~\ref{sec:cygwin}.
537
538
539 \subsubsection{MacOSX}
540 \label{sec:macosx}
541
542 As mentioned in section~\ref{sec:tl-coll-dists}, a separate distribution
543 is prepared for \MacOSX, named Mac\TeX\ (\url{http://tug.org/mactex}).
544 We recommend using the native Mac\TeX\ installer instead of the \TL\
545 installer on \MacOSX, because the native installer makes a few
546 Mac-specific adjustments, in particular to allow easily switching
547 between the various \TeX\ distributions for \MacOSX\ (Mac\TeX, Fink,
548 MacPorts, \ldots) using the so-called \TeX{}Dist data structure.
549
550 Mac\TeX\ is firmly based on \TL, and the main \TeX\ trees and binaries
551 are precisely the same. It adds a few extra folders with Mac-specific
552 documentation and applications.
553
554
555 \subsubsection{Windows}\label{sec:wininst}
556
557 If you are using the unpacked downloaded zip file, or the \DVD\
558 installer failed to start automatically, double-click
559 \filename{install-tl-windows.bat}. If you want more customization
560 options, e.g., selection of specific package collections, run
561 \filename{install-tl-advanced.bat} instead.
562
563 You can also start the installer from the command-prompt. Below,
564 \texttt{>} denotes the prompt; user input is \Ucom{\texttt{bold}}. If
565 you are in the installer directory, run just:
566 \begin{alltt}
567 > \Ucom{install-tl-windows}
568 \end{alltt}
569
570 Or you can invoke it with an absolute location, such as:
571 \begin{alltt}
572 > \Ucom{D:\bs{}texlive\bs{}install-tl-windows}
573 \end{alltt}
574 for the \TK\ \DVD, supposing that \dirname{D:} is the optical
575 drive. Figure~\ref{fig:wizard-w32} displays the wizard installer, which
576 is the default for Windows.
577
578 To install in text mode, use:
579 \begin{alltt}
580 > \Ucom{install-tl-windows -no-gui}
581 \end{alltt}
582
583 For a complete listing of the various options:
584 \begin{alltt}
585 > \Ucom{install-tl-windows -help}
586 \end{alltt}
587
588 \begin{figure}[tb]
589 \begin{boxedverbatim}
590 Installing TeX Live 2014 from: ...
591 Platform: i386-linux => 'Intel x86 with GNU/Linux'
592 Distribution: inst (compressed)
593 ...
594 Detected platform: Intel x86 with GNU/Linux
595
596 <B> binary platforms: 1 out of 21
597
598 <S> set installation scheme (scheme-full)
599
600 <C> customizing installation collections
601 47 collections out of 48, disk space required: 3641 MB
602
603 <D> directories:
604 TEXDIR (the main TeX directory):
605 /usr/local/texlive/2014
606 ...
607
608 <O> options:
609 [ ] use letter size instead of A4 by default
610 ...
611
612 <V> set up for portable installation
613
614 Actions:
615 <I> start installation to hard disk
616 <H> help
617 <Q> quit
618 \end{boxedverbatim}
619 \caption{Main text installer screen (\GNU/Linux)}\label{fig:text-main}
620 \end{figure}
621
622 \begin{figure}[tb]
623 \tlpng{install-lnx-main}{\linewidth}
624 \caption{Expert \GUI{} installer screen (\GNU/Linux)}\label{fig:gui-main}
625 \end{figure}
626
627 \begin{figure}[tb]
628 \tlpng{wizard-w32}{\linewidth}
629 \caption{Wizard installer screen (Windows)}\label{fig:wizard-w32}
630 \end{figure}
631
632
633 \htmlanchor{cygwin}
634 \subsubsection{Cygwin}
635 \label{sec:cygwin}
636
637 Before beginning the installation, use Cygwin's \filename{setup.exe} program to
638 install the \filename{perl} and \filename{wget} packages if you have
639 not already done so. The following additional packages are
640 recommended:
641 \begin{itemize*}
642 \item \filename{fontconfig} [needed by \XeTeX\ and Lua\TeX]
643 \item \filename{ghostscript} [needed by various utilities]
644 \item \filename{libXaw7} [needed by \code{xdvi}]
645 \item \filename{ncurses} [provides the \code{clear} command used by the installer]
646 \end{itemize*}
647
648
649 \subsubsection{The text installer}
650
651 Figure~\ref{fig:text-main} displays the main text mode screen under
652 Unix. The text installer is the default on Unix.
653
654 This is only a command-line installer; there is no cursor support at
655 all. For instance, you cannot tab around checkboxes or input fields.
656 You just type something (case-sensitive) at the prompt and press the
657 Enter key, and then the entire terminal screen will be rewritten, with
658 adjusted content.
659
660 The text installer interface is this primitive for a reason: it
661 is designed to run on as many platforms as possible, even with a
662 very barebones Perl.
663
664 \subsubsection{The expert graphical installer}
665
666 Figure~\ref{fig:gui-main} displays the expert graphical installer under
667 \GNU/Linux. Other than using buttons and menus, this does
668 not differ much from the text installer.
669
670 This mode can be invoked explicitly with
671 \begin{alltt}
672 > \Ucom{install-tl -gui=perltk}
673 \end{alltt}
674
675
676 \subsubsection{The simple wizard installer}
677
678 Under Windows, the default is to run the simplest installation method we
679 could devise, called the ``wizard'' installer
680 (figure~\ref{fig:wizard-w32}). It installs everything and asks almost
681 no questions. If you want to customize your setup, you should run one
682 of the other installers.
683
684 On other platforms, this mode can be invoked explicitly with
685 \begin{alltt}
686 > \Ucom{install-tl -gui=wizard}
687 \end{alltt}
688
689
690 \subsection{Running the installer}
691 \label{sec:runinstall}
692
693 The installer is intended to be mostly self-explanatory, but following are a
694 few notes about the various options and submenus.
695
696 \subsubsection{Binary systems menu (Unix only)}
697 \label{sec:binary}
698
699 \begin{figure}[tb]
700 \begin{boxedverbatim}
701 Available platforms:
702 ===============================================================================
703 a [ ] alpha-linux DEC Alpha with GNU/Linux
704 b [ ] amd64-freebsd x86_64 with FreeBSD
705 c [ ] amd64-kfreebsd x86_64 with GNU/kFreeBSD
706 d [ ] amd64-netbsd x86_64 with NetBSD
707 e [ ] armel-linux ARM with GNU/Linux
708 f [ ] armhf-linux ARMhf with GNU/Linux
709 g [ ] i386-cygwin Intel x86 with Cygwin
710 h [ ] i386-freebsd Intel x86 with FreeBSD
711 i [ ] i386-kfreebsd Intel x86 with GNU/kFreeBSD
712 j [ ] i386-linux Intel x86 with GNU/Linux
713 k [ ] i386-netbsd Intel x86 with NetBSD
714 l [ ] i386-solaris Intel x86 with Solaris
715 m [ ] mipsel-linux mipsel with Linux
716 o [ ] powerpc-linux PowerPC with GNU/Linux
717 p [ ] sparc-solaris Sparc with Solaris
718 s [ ] universal-darwin universal binaries for MacOSX/Darwin
719 t [ ] win32 Windows
720 u [ ] x86_64-cygwin x86_64 with Cygwin
721 v [ ] x86_64-darwin x86_64 with MacOSX/Darwin
722 w [ ] x86_64-linux x86_64 with GNU/Linux
723 x [ ] x86_64-solaris x86_64 with Solaris
724 \end{boxedverbatim}
725 \caption{Binaries menu}\label{fig:bin-text}
726 \end{figure}
727
728 Figure~\ref{fig:bin-text} displays the text mode binaries menu. By
729 default, only the binaries for your current platform will be installed.
730 From this menu, you can select installation of binaries for other
731 platforms as well. This can be useful if you are sharing a \TeX\
732 tree across a network of heterogeneous machines, or for a dual-boot
733 system.
734
735 \subsubsection{Selecting what is to be installed}
736 \label{sec:components}
737
738 \begin{figure}[tbh]
739 \begin{boxedverbatim}
740 Select scheme:
741 ===============================================================================
742 a [X] full scheme (everything)
743 b [ ] medium scheme (small + more packages and languages)
744 c [ ] small scheme (basic + xetex, metapost, a few languages)
745 d [ ] basic scheme (plain and latex)
746 e [ ] minimal scheme (plain only)
747 f [ ] ConTeXt scheme
748 g [ ] GUST TeX Live scheme
749 h [ ] teTeX scheme (more than medium, but nowhere near full)
750 i [ ] XML scheme
751 j [ ] custom selection of collections
752 \end{boxedverbatim}
753 \caption{Scheme menu}\label{fig:scheme-text}
754 \end{figure}
755
756 Figure~\ref{fig:scheme-text} displays the \TL\ scheme menu; from here,
757 you choose a ``scheme'', which is an overall set of package collections.
758 The default \optname{full} scheme installs everything available. This
759 is recommended, but you can also choose the \optname{basic} scheme for a
760 small system, \optname{minimal} for testing purposes, and
761 \optname{medium} or \optname{teTeX} to get something in between. There
762 are also various specialized and country-specific schemes.
763
764 \begin{figure}[tb]
765 \centering \tlpng{stdcoll}{.7\linewidth}
766 \caption{Collections menu}\label{fig:collections-gui}
767 \end{figure}
768
769 You can refine your scheme selection with the `collections' menu
770 (figure~\ref{fig:collections-gui}, shown in \GUI\ mode for a change).
771
772 Collections are one level more detailed than schemes\Dash in essence, a
773 scheme consists of several collections, a collection consists of one or
774 more packages, and a package (the lowest level grouping in \TL) contains
775 the actual \TeX\ macro files, font files, and so on.
776
777 If you want more control than the collection menus provide, you can use
778 the \TeX\ Live Manager (\prog{tlmgr}) program after installation (see
779 section~\ref{sec:tlmgr}); using that, you can control the installation
780 at the package level.
781
782 \subsubsection{Directories}
783 \label{sec:directories}
784
785 The default layout is described in section~\ref{sec:texmftrees},
786 \p.\pageref{sec:texmftrees}. The default location of
787 \dirname{TEXDIR} is \dirname{/usr/local/texlive/2014} on Unix
788 and |%SystemDrive%\texlive\2014| on Windows.
789 Thus, by default, you will have parallel \TL\ installations, one for
790 each release, and can switch between them merely by altering your
791 search path.
792
793 This can be overridden by setting \dirname{TEXDIR} in the installer.
794 The main reason to change it is if you lack write permission for the
795 default location. You don't have to be root or administrator to install
796 \TL, but you do need write access to the target directory.
797
798 A reasonable alternative choice is a directory under your home directory,
799 especially if you will be the sole user. Use
800 `|~|' to indicate this, as in `|~/texlive/2014|'.
801
802 We recommend including the year in the name, to enable keeping different
803 releases of \TL{} side by side. (You may wish to also have a
804 version-independent name, such as \dirname{/usr/local/texlive-cur}, via a
805 symbolic link, which you can then repoint after testing the new release.)
806
807 Changing \dirname{TEXDIR} in the installer will also change
808 \dirname{TEXMFLOCAL}, \dirname{TEXMFSYSVAR} and
809 \dirname{TEXMFSYSCONFIG}.
810
811 \dirname{TEXMFHOME} is the recommended location for personal macro files
812 or packages. The default value is |~/texmf|. In contrast to
813 \dirname{TEXDIR}, here a |~| is preserved in the newly-written
814 configuration files, since it usefully refers to the home directory of
815 the user running \TeX. It expands to \dirname{$HOME} on Unix and
816 \verb|%USERPROFILE%| on Windows. Special redundant note:
817 \envname{TEXMFHOME}, like all trees, must be organized according to the
818 \TDS, or files may not be found.
819
820 \dirname{TEXMFVAR} is the location for storing most cached runtime data
821 specific to each user. \dirname{TEXMFCACHE} is the variable name used
822 for that purpose by Lua\LaTeX and \ConTeXt\ Mk\acro{IV} (see
823 section~\ref{sec:context-mkiv}, \p.\pageref{sec:context-mkiv}); its
824 default value is \dirname{TEXMFSYSVAR}, or (if that's not writable),
825 \dirname{TEXMFVAR}.
826
827
828 \subsubsection{Options}
829 \label{sec:options}
830
831 \begin{figure}[tbh]
832 \begin{boxedverbatim}
833 Options setup:
834 ===============================================================================
835 <P> use letter size instead of A4 by default: [ ]
836 <E> execution of restricted list of programs: [X]
837 <F> create format files: [X]
838 <D> install font/macro doc tree: [X]
839 <S> install font/macro source tree: [X]
840 <L> create symlinks in standard directories: [ ]
841 binaries to:
842 manpages to:
843 info to:
844 <Y> after installation, get package updates from CTAN: [X]
845 \end{boxedverbatim}
846 \caption{Options menu (Unix)}\label{fig:options-text}
847 \end{figure}
848
849 Figure~\ref{fig:options-text} shows the text mode options menu.
850 More info on each:
851
852 \begin{description}
853 \item[use letter size instead of A4 by default:] The default paper
854 size selection. Of course, individual documents can and should
855 specify a specific paper size, if desired.
856
857 \item[execution of restricted list of programs:] As of \TL\ 2010,
858 execution of a few external programs is allowed by default. The (very
859 short) list of allowed programs is given in the \filename{texmf.cnf}.
860 See the 2010 news (section~\ref{sec:2010news}) for more details.
861
862 \item[create format files:] Although unnecessary format files
863 take time to generate and disk space to store, it is still recommended
864 to leave this option checked: if you don't, then format files will be
865 generated in people's private \dirname{TEXMFVAR} tree as they are
866 needed. In that location, they will not be updated automatically if
867 (say) binaries or hyphenation patterns are updated in the
868 installation, and thus you could end up with incompatible format files.
869
870 \item[install font/macro \ldots\ tree:] Omit downloading/installing the
871 documentation and source files included in most packages. Not recommended.
872
873 \item[create symlinks in standard directories:]
874 This option (Unix only) bypasses the need to change environment
875 variables. Without this option, \TL{} directories usually have to be
876 added to \envname{PATH}, \envname{MANPATH} and \envname{INFOPATH}. You
877 will need write permissions to the target directories. It is strongly
878 advised \emph{not} to overwrite a \TeX\ system that came with your
879 system with this option. It is intended primarily for accessing the
880 \TeX\ system through directories that are already known to users, such
881 as \dirname{/usr/local/bin}, which don't already contain any \TeX\
882 files.
883
884 \item[after installation \ldots\ \CTAN:] When installing from \DVD, this
885 option is enabled by default, since usually one wants to take any
886 subsequent package updates from the \CTAN\ area that is updated
887 throughout the year. The only likely reason to disable it is if you
888 install only a subset from the \DVD\ and plan to augment the
889 installation later. In any case, the package repository for the
890 installer, and for updates after installation, can be set
891 independently as needed; see section~\ref{sec:location} and
892 section~\ref{sec:dvd-install-net-updates}.
893 \end{description}
894
895 When all the settings are to your liking, you can type `I' to start the
896 installation process. When it is done, skip to
897 section~\ref{sec:postinstall} to read what else needs to be done, if
898 anything.
899
900 \subsection{Command-line install-tl options}
901 \label{sec:cmdline}
902
903 Type
904 \begin{alltt}
905 > \Ucom{install-tl -help}
906 \end{alltt}
907 for a listing of command-line options. Either |-| or |--| can be used
908 to introduce option names. These are the most common ones:
909
910 \begin{ttdescription}
911 \item[-gui] If possible, use the \GUI{} installer. This requires the
912 Perl/Tk module (\url{http://tug.org/texlive/distro.html#perltk})
913 compiled with \acro{XFT} support; if Perl/Tk is not available,
914 installation continues in text mode.
915
916 \item[-no-gui] Force using the text mode installer, even under
917 Windows.
918
919 \item[-lang {\sl LL}] Specify the installer interface
920 language as a standard (usually two-letter) code. The installer tries
921 to automatically determine the right language but if it fails, or if
922 the right language is not available, then it uses English as a
923 fallback. Run \verb|install-tl --help| to get the list of available
924 languages.
925
926 \item[-portable] Install for portable use on, e.g., a \USB{} stick.
927 Also selectable from within the text installer with the \code{V}
928 command, and from the \GUI{} installer. See
929 section~\ref{sec:portable-tl}.
930
931 \item[-profile {\sl file}] Load the installation profile \var{file} and
932 do the installation with no user interaction. The installer always
933 writes a file \filename{texlive.profile} to the \dirname{tlpkg}
934 subdirectory of your installation. That file can be given as the
935 argument to redo the exact same installation on a different system,
936 for example. Alternatively, you can use a custom profile, most easily
937 created by starting from a generated one and changing values, or an
938 empty file, which will take all the defaults.
939
940 \item [-repository {\sl url-or-directory}] Specify package
941 repository from which to install; see following.
942
943 \htmlanchor{opt-in-place}
944 \item[-in-place] (Documented only for completeness: Do not use this
945 unless you know what you are doing.) If you already have an rsync, svn,
946 or other copy of \TL{} (see
947 \url{http://tug.org/texlive/acquire-mirror.html}) then this option
948 will use what you've got, as-is, and do only the necessary
949 post-install. Be warned that the file \filename{tlpkg/texlive.tlpdb}
950 may be overwritten; saving it is your responsibility. Also, package
951 removal has to be done manually. This option cannot be toggled via the
952 installer interface.
953 \end{ttdescription}
954
955
956 \subsubsection{The \optname{-repository} option}
957 \label{sec:location}
958
959 The default network package repository is a \CTAN{} mirror chosen
960 automatically via \url{http://mirror.ctan.org}.
961
962 If you want to override that, the location value can be a url starting
963 with \texttt{ftp:}, \texttt{http:}, or \texttt{file:/}, or a plain
964 directory path. (When giving an \texttt{http:}\ or \texttt{ftp:}\
965 location, trailing `\texttt{/}' characters and/or a trailing
966 `\texttt{/tlpkg}' component are ignored.)
967
968 For example, you could choose a particular \CTAN\ mirror with something
969 like: \url{http://ctan.example.org/tex-archive/systems/texlive/tlnet/},
970 substituting a real hostname and its particular top-level \CTAN\ path
971 for |ctan.example.org/tex-archive|. The list of \CTAN\ mirrors is
972 maintained at \url{http://ctan.org/mirrors}.
973
974 If the given argument is local (either a path or a \texttt{file:/} url),
975 compressed files in an \dirname{archive} subdirectory of the repository
976 path are used (even if uncompressed files are available as well).
977
978
979 \subsection{Post-install actions}
980 \label{sec:postinstall}
981
982 Some post-installation may be required.
983
984 \subsubsection{Environment variables for Unix}
985 \label{sec:env}
986
987 If you elected to create symlinks in standard directories (described in
988 section~\ref{sec:options}), then there is no need to edit environment
989 variables. Otherwise, on Unix systems, the directory of the binaries
990 for your platform must be added to the search path. (On Windows, the
991 installer takes care of this.)
992
993 Each supported platform has its own subdirectory under
994 \dirname{TEXDIR/bin}. See figure~\ref{fig:bin-text} for the list of
995 subdirectories and corresponding platforms.
996
997 Optionally, you can also add the documentation man and Info directories
998 to their respective search paths, if you want the system tools to find
999 them. The man pages might be found automatically after the addition to
1000 \envname{PATH}.
1001
1002 For Bourne-compatible shells such as \prog{bash}, and using Intel x86
1003 GNU/Linux and a default directory setup as an example, the file to edit
1004 might be \filename{$HOME/.profile} (or another file sourced by
1005 \filename{.profile}, and the lines to add would look like this:
1006
1007 \begin{sverbatim}
1008 PATH=/usr/local/texlive/2014/bin/i386-linux:$PATH; export PATH
1009 MANPATH=/usr/local/texlive/2014/texmf-dist/doc/man:$MANPATH; export MANPATH
1010 INFOPATH=/usr/local/texlive/2014/texmf-dist/doc/info:$INFOPATH; export INFOPATH
1011 \end{sverbatim}
1012
1013 For csh or tcsh, the file to edit is typically \filename{$HOME/.cshrc}, and
1014 the lines to add might look like:
1015
1016 \begin{sverbatim}
1017 setenv PATH /usr/local/texlive/2014/bin/i386-linux:$PATH
1018 setenv MANPATH /usr/local/texlive/2014/texmf-dist/doc/man:$MANPATH
1019 setenv INFOPATH /usr/local/texlive/2014/texmf-dist/doc/info:$INFOPATH
1020 \end{sverbatim}
1021
1022 If you already have settings somewhere in your ``dot'' files, naturally
1023 the \TL\ directories should be merged in as appropriate.
1024
1025
1026 \subsubsection{Environment variables: Global configuration}
1027 \label{sec:envglobal}
1028
1029 If you want to make these changes globally, or for a user newly added to
1030 the system, then you are on your own; there is just too much variation
1031 between systems in how and where these things are configured.
1032
1033 Our two hints are: 1)~you may want to check for a file
1034 \filename{/etc/manpath.config} and, if present, add lines such as
1035
1036 \begin{sverbatim}
1037 MANPATH_MAP /usr/local/texlive/2014/bin/i386-linux \
1038 /usr/local/texlive/2014/texmf-dist/doc/man
1039 \end{sverbatim}
1040
1041 And 2)~check for a file \filename{/etc/environment} which may define the
1042 search path and other default environment variables.
1043
1044 In each (Unix) binary directory, we also create a symbolic link named
1045 \code{man} to the directory \dirname{texmf-dist/doc/man}. Some \code{man}
1046 programs, such as the standard \MacOSX\ \code{man}, will automatically
1047 find that, obviating the need for any man page setup.
1048
1049
1050 \subsubsection{Internet updates after \DVD\ installation}
1051 \label{sec:dvd-install-net-updates}
1052
1053 If you installed \TL\ from \DVD\ and then wish to get updates from the
1054 Internet, you need to run this command---\emph{after} you've updated
1055 your search path (as described in the previous section):
1056
1057 \begin{alltt}
1058 > \Ucom{tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet}
1059 \end{alltt}
1060
1061 This tells \cmdname{tlmgr} to use a nearby \CTAN\ mirror for future updates.
1062 This is done by default when installing from \DVD, via the option
1063 described in section~\ref{sec:options}.
1064
1065 If there are problems with the automatic mirror selection, you can
1066 specify a particular \CTAN\ mirror from the list at
1067 \url{http://ctan.org/mirrors}. Use the exact path to the
1068 \dirname{tlnet} subdir on that mirror, as shown above.
1069
1070
1071 \htmlanchor{xetexfontconfig} % keep historical anchor working
1072 \htmlanchor{sysfontconfig}
1073 \subsubsection{System font configuration for \XeTeX\ and Lua\TeX}
1074 \label{sec:font-conf-sys}
1075
1076 \XeTeX\ and Lua\TeX\ can use any font installed on the system, not just
1077 those in the \TeX\ trees. They do these via related but not identical
1078 methods.
1079
1080 On Windows, fonts shipped with \TL\ are made available to \XeTeX\
1081 automatically. But if you have installed the \filename{xetex} package
1082 on a Unix-compatible system, you need to configure your system to be
1083 able to find the fonts shipped with \TL\ via system name lookup, and not
1084 just filename lookup.
1085
1086 To facilitate this, when the \pkgname{xetex} package is installed
1087 (either at initial installation or later), the necessary configuration
1088 file is created in
1089 \filename{TEXMFSYSVAR/fonts/conf/texlive-fontconfig.conf}.
1090
1091 To set up the \TL{} fonts for system-wide use (assuming you have
1092 suitable privileges), proceed as follows:
1093 \begin{enumerate*}
1094 \item Copy the \filename{texlive-fontconfig.conf} file to
1095 \dirname{/etc/fonts/conf.d/09-texlive.conf}.
1096 \item Run \Ucom{fc-cache -fsv}.
1097 \end{enumerate*}
1098
1099 If you do not have sufficient privileges to carry out the steps above,
1100 or if you want to make the \TL{} fonts available to only one user,
1101 you can do the following:
1102 \begin{enumerate*}
1103 \item Copy the \filename{texlive-fontconfig.conf} file to
1104 \filename{~/.fonts.conf}, where \filename{~} is your home directory.
1105 \item Run \Ucom{fc-cache -fv}.
1106 \end{enumerate*}
1107
1108 You can run \code{fc-list} to see the names of the system fonts. The
1109 incantation \code{fc-list : family style file spacing} (all arguments
1110 are literal strings) shows some generally interesting information.
1111
1112
1113 \subsubsection{\ConTeXt{} Mark IV}
1114 \label{sec:context-mkiv}
1115
1116 Both the `old' \ConTeXt{} (Mark \acro{II}) and the `new' \ConTeXt{}
1117 (Mark \acro{IV}) should run out of the box after \TL{} installation,
1118 and should need no special attention as long as you stick to
1119 using \verb+tlmgr+ for updates.
1120
1121 However, because \ConTeXt{} Mk\acro{IV} does not use the kpathsea
1122 library, some setup will be required whenever you install new
1123 files manually (without using \verb+tlmgr+). After each such
1124 installation, each Mk\acro{IV} user must run:
1125 \begin{sverbatim}
1126 context --generate
1127 \end{sverbatim}
1128 to refresh the \ConTeXt{} disk cache data.
1129 The resulting files are stored under \code{TEXMFCACHE}.
1130 whose default value in \TL\ is \verb+TEXMSYSVAR;TEXMFVAR+.
1131
1132 \ConTeXt\ Mk\acro{IV} will read from
1133 all paths mentioned in \verb+TEXMFCACHE+, and write to the first
1134 path that is writable. While reading, the last found match will
1135 take precedence in the case of duplicated cache data.
1136
1137 For more information, see
1138 \url{http://wiki.contextgarden.net/Running_Mark_IV}.
1139
1140
1141 \subsubsection{Integrating local and personal macros}
1142 \label{sec:local-personal-macros}
1143
1144 This is already mentioned implicitly in section~\ref{sec:texmftrees}:
1145 \dirname{TEXMFLOCAL} (by default,
1146 \dirname{/usr/local/texlive/texmf-local} or
1147 \verb|%SystemDrive%\texlive\texmf-local| on Windows)
1148 is intended for system-wide local fonts and macros; and
1149 \dirname{TEXMFHOME} (by default, \dirname{$HOME/texmf} or
1150 \verb|%USERPROFILE%\texmf|), is for personal fonts and macros. These
1151 directories are intended to stick around from release to release, and
1152 have their content seen automatically by a new \TL{} release.
1153 Therefore, it is best to refrain from changing the definition of
1154 \dirname{TEXMFLOCAL} to be too far away from the main \TL{} directory,
1155 or you will need to manually change future releases.
1156
1157 For both trees, files should be placed in their proper \TeX\ Directory
1158 Structure (\TDS) subdirectories; see \url{http://tug.org/tds} or consult
1159 \filename{texmf-dist/web2c/texmf.cnf}. For instance, a \LaTeX{} class file or
1160 package should be placed in \dirname{TEXMFLOCAL/tex/latex} or
1161 \dirname{TEXMFHOME/tex/latex}, or a subdirectory thereof.
1162
1163 \dirname{TEXMFLOCAL} requires an up-to-date filename database, or files
1164 will not be found. You can update it with the command
1165 \cmdname{mktexlsr} or use the `Reinit file database' button on the
1166 configuration tab of the \TeX\ Live Manager \GUI.
1167
1168 By default, each of these variables is defined to be a single directory,
1169 as shown. This is not a hard-and-fast requirement. If you need to
1170 easily switch back and forth between different versions of large
1171 packages, for example, you can maintain multiple trees for your own
1172 purposes. This is done by setting \dirname{TEXMFHOME} to the
1173 list of directories, within braces, separated by commas:
1174
1175 \begin{verbatim}
1176 TEXMFHOME = {/my/dir1,/mydir2,/a/third/dir}
1177 \end{verbatim}
1178
1179 Section~\ref{sec:brace-expansion} describes brace expansion further.
1180
1181
1182 \subsubsection{Integrating third-party fonts}
1183
1184 This is unfortunately a messy topic. Forget about it unless you want to
1185 delve into many details of the \TeX{} installation. Many fonts are
1186 included in \TL\ already, so take a look if you don't already know
1187 that what you want isn't there.
1188
1189 A possible alternative is to use \XeTeX\ or Lua\TeX\ (see
1190 section~\ref{sec:tex-extensions}), which let you use operating system
1191 fonts without any installation in \TeX.
1192
1193 If you do need to do this, see
1194 \url{http://tug.org/fonts/fontinstall.html} for our best effort at
1195 describing the procedure.
1196
1197
1198 \subsection{Testing the installation}
1199 \label{sec:test-install}
1200
1201 After installing \TL{}, you naturally want to test it out, so you can
1202 start creating beautiful documents and\slash or fonts.
1203
1204 One thing you may immediately be looking for is a front-end with which to
1205 edit files. \TL{} installs \TeX{}works (\url{http://tug.org/texworks})
1206 on Windows, and Mac\TeX\ installs TeXShop
1207 (\url{http://pages.uoregon.edu/koch/texshop}. On other Unix systems,
1208 it's left up to you to choose an editor. Of course there are many other
1209 choices available, some of which are listed in the next section; see
1210 also \url{http://tug.org/interest.html#editors}. In principle, any
1211 plain text editor will work.
1212
1213 The rest of this section gives some basic procedures for testing that
1214 the new system is functional. We give Unix commands here; under
1215 \MacOSX{} and Windows, you're more likely to run the tests through a
1216 graphical interface, but the principles are the same.
1217
1218 \begin{enumerate}
1219
1220 \item Make sure that you can run the \cmdname{tex} program in the first
1221 place:
1222 \begin{alltt}
1223 > \Ucom{tex -{}-version}
1224 TeX 3.14159265 (TeX Live ...)
1225 Copyright ... D.E. Knuth.
1226 ...
1227 \end{alltt}
1228 If this comes back with `command not found' instead of version and
1229 copyright information, or with an older version, most likely you don't
1230 have the correct \dirname{bin} subdirectory in your \envname{PATH}. See
1231 the environment-setting information on \p.\pageref{sec:env}.
1232
1233 \item Process a basic \LaTeX{} file:
1234 \begin{alltt}
1235 > \Ucom{latex sample2e.tex}
1236 This is pdfTeX 3.14...
1237 ...
1238 Output written on sample2e.dvi (3 pages, 7484 bytes).
1239 Transcript written on sample2e.log.
1240 \end{alltt}
1241 If this fails to find \filename{sample2e.tex} or other files, most
1242 likely you have interference from old environment variables or
1243 configuration files; we recommend unsetting all \TeX-related environment
1244 variables for a start. (For a deep analysis, you can ask \TeX{} to
1245 report on exactly what it is searching for, and finding; see ``Debugging
1246 actions'' on page~\pageref{sec:debugging}.)
1247
1248 \item Preview the result online:
1249 \begin{alltt}
1250 > \Ucom{xdvi sample2e.dvi} # Unix
1251 > \Ucom{dviout sample2e.dvi} # Windows
1252 \end{alltt}
1253 You should see a new window with a nice document explaining some of the
1254 basics of \LaTeX{}. (Well worth reading, by the way, if you're new to
1255 \TeX.) You do have to be running under X for \cmdname{xdvi} to work; if
1256 you're not, or your \envname{DISPLAY} environment variable is set
1257 incorrectly, you'll get an error \samp{Can't open display}.
1258
1259 \item Create a \PS{} file for printing or display:
1260 \begin{alltt}
1261 > \Ucom{dvips sample2e.dvi -o sample2e.ps}
1262 \end{alltt}
1263
1264 \item Create a \acro{PDF} file instead of \dvi{}; this processes the
1265 \filename{.tex} file and writes \acro{PDF} directly:
1266 \begin{alltt}
1267 > \Ucom{pdflatex sample2e.tex}
1268 \end{alltt}
1269
1270 \item Preview the \acro{PDF} file:
1271 \begin{alltt}
1272 > \Ucom{gv sample2e.pdf}
1273 \textrm{or:}
1274 > \Ucom{xpdf sample2e.pdf}
1275 \end{alltt}
1276 Neither \cmdname{gv} nor \cmdname{xpdf} are included in \TL{}, so you
1277 must install them separately. See \url{http://www.gnu.org/software/gv}
1278 and \url{http://www.foolabs.com/xpdf}, respectively. There are plenty
1279 of other \acro{PDF} viewers, too. For Windows, we recommend trying
1280 Sumatra PDF (\url{http://blog.kowalczyk.info/software/sumatrapdf}).
1281
1282 \item Standard test files you may find useful in addition to
1283 \filename{sample2e.tex}:
1284
1285 \begin{ttdescription}
1286 \item [small2e.tex] A simpler document than \filename{sample2e}, to
1287 reduce the input size if you're having troubles.
1288 \item [testpage.tex] Test if your printer introduces any offsets.
1289 \item [nfssfont.tex] For printing font tables and tests.
1290 \item [testfont.tex] Also for font tables, but using plain \TeX{}.
1291 \item [story.tex] The most canonical (plain) \TeX{} test file of all.
1292 You must type \samp{\bs bye} to the \code{*} prompt after \samp{tex
1293 story.tex}.
1294 \end{ttdescription}
1295
1296 \item If you have installed the \filename{xetex} package, you can test
1297 its access to system fonts as follows:
1298 \begin{alltt}
1299 > \Ucom{xetex opentype-info.tex}
1300 This is XeTeX, Version 3.14\dots
1301 ...
1302 Output written on opentype-info.pdf (1 page).
1303 Transcript written on opentype-info.log.
1304 \end{alltt}
1305
1306 If you get an error message saying ``Invalid fontname `Latin Modern
1307 Roman/ICU'\dots'', then you need to configure your system so that the
1308 fonts shipped with \TL\ can be found. See
1309 Section~\ref{sec:font-conf-sys}.
1310
1311 \end{enumerate}
1312
1313 \subsection{Links for additional downloadable software}
1314
1315 If you are new to \TeX{}, or otherwise need help with actually writing
1316 \TeX{} or \LaTeX{} documents, please visit
1317 \url{http://tug.org/begin.html} for some introductory resources.
1318
1319 Links for some other tools you may consider installing:
1320 \begin{description}
1321 \item[Ghostscript] \url{http://www.cs.wisc.edu/~ghost/}
1322 \item[Perl] \url{http://www.perl.org/} with
1323 supplementary packages from \acro{CPAN}, \url{http://www.cpan.org/}
1324 \item[ImageMagick] \url{http://www.imagemagick.com}, for graphics
1325 processing and conversion
1326 \item[NetPBM] \url{http://netpbm.sourceforge.net/}, also for graphics.
1327
1328 \item[\TeX-oriented editors] There is a wide choice, and it is a matter of the
1329 user's taste. Here is a selection in alphabetical order (a few
1330 here are for Windows only).
1331 \begin{itemize*}
1332 \item \cmdname{GNU Emacs} is available natively under Windows, see
1333 \url{http://www.gnu.org/software/emacs/windows/ntemacs.html}.
1334 \item \cmdname{Emacs with Auc\TeX} for Windows is available from \CTAN.
1335 The AuC\TeX\ home page is \url{http://www.gnu.org/software/auctex}.
1336 \item \cmdname{LEd} is available from
1337 \url{http://mirror.ctan.org/support/LEd}.
1338 \item \cmdname{SciTE} is available from
1339 \url{http://www.scintilla.org/SciTE.html}.
1340 \item \cmdname{Texmaker} is free software, available from
1341 \url{http://www.xm1math.net/texmaker}.
1342 \item \cmdname{TeXstudio} started out as a fork of \cmdname{Texmaker} with
1343 additional features; \url{http://texstudio.sourceforge.net}.
1344 \item \cmdname{TeXnicCenter} is free software, available from
1345 \url{http://www.texniccenter.org} and in the pro\TeX{}t distribution.
1346 \item \cmdname{TeXworks} is free software, available from
1347 \url{http://tug.org/texworks} and installed for Windows and
1348 \MacOSX\ as part of \TL.
1349 \item \cmdname{Vim} is free software, available from
1350 \url{http://www.vim.org}.
1351 \item \cmdname{WinEdt} is shareware available though
1352 \url{http://tug.org/winedt} or \url{http://www.winedt.com}.
1353 \item \cmdname{WinShell} is available from \url{http://www.winshell.de}.
1354 \end{itemize*}
1355 \end{description}
1356 For a much longer list of packages and programs, see
1357 \url{http://tug.org/interest.html}.
1358
1359
1360 \section{Specialized installations}
1361
1362 The previous sections described the basic installation process. Here we
1363 turn to some specialized cases.
1364
1365 \htmlanchor{tlsharedinstall}
1366 \subsection{Shared-user (or cross-machine) installations}
1367 \label{sec:sharedinstall}
1368
1369 \TL{} has been designed to be sharable between different users on one
1370 system, and/or between different systems on a network. With a standard
1371 directory layout, no hard paths are configured: the locations for files
1372 needed by \TL{} programs are found relative to the programs. You can
1373 see this in the principal configuration file
1374 \filename{$TEXMFDIST/web2c/texmf.cnf}, which contains lines such as
1375 \begin{sverbatim}
1376 TEXMFROOT = $SELFAUTOPARENT
1377 ...
1378 TEXMFDIST = $TEXMFROOT/texmf-dist
1379 ...
1380 TEXMFLOCAL = $SELFAUTOPARENT/../texmf-local
1381 \end{sverbatim}
1382 This means that adding the directory for \TL{} executables for their
1383 platform to their search path is sufficient to get a working setup.
1384
1385 By the same token, you can also install \TL{} locally and then move
1386 the entire hierarchy afterwards to a network location.
1387
1388 For Windows, a sample network installation script named
1389 \filename{w32client} can be downloaded through
1390 \url{http://tug.org/texlive/w32client.html}. It creates settings and
1391 menu shortcuts for using an existing \TL{} installation on a \acro{LAN}.
1392 It also registers an uninstaller \filename{w32unclient}, available
1393 in the same zip file. See the web page for more information.
1394
1395
1396 \htmlanchor{tlportable}
1397 \subsection{Portable (\USB{}) installations}
1398 \label{sec:portable-tl}
1399
1400 The \code{-portable} installer option (or \code{V} command in the text
1401 installer or corresponding \GUI{} option) creates a completely
1402 self-contained \TL{} installation under a common root and forgoes system
1403 integration. You can create such an installation directly on a \USB{}
1404 stick, or copy it to a \USB{} stick afterwards.
1405
1406 To run \TeX\ using this portable installation, you need to add the
1407 appropriate binary directory to the search path during your terminal
1408 session, as usual. On Windows, you can double-click
1409 \filename{tl-tray-menu} at the root of the installation to choose
1410 between a few common tasks, as shown in this screenshot:
1411
1412 \medskip
1413 \tlpng{tray-menu}{4cm}
1414 \smallskip
1415
1416 \noindent The `More\ldots' entry explains how you can customize this menu.
1417
1418
1419 \htmlanchor{tlisoinstall}
1420 \subsection{\ISO\ (or \DVD) installations}
1421 \label{sec:isoinstall}
1422
1423 If you don't need to update or otherwise modify your installation often,
1424 and\slash or have several systems on which to use \TL{}, it may be
1425 convenient to create an \ISO\ of your \TL{} installation, because:
1426
1427 \begin{itemize}
1428 \item Copying an \ISO\ between different computers is much
1429 faster than copying a normal installation.
1430 \item If you are dual-booting between different operating systems
1431 and want them to share a \TL{} installation, an \ISO
1432 installation is not tied to the idiosyncrasies and limitations of
1433 other mutually supported filesystems (\acro{FAT32}, \acro{NTFS},
1434 \acro{HFS+}).
1435 \item Virtual machines can simply mount such an \ISO.
1436 \end{itemize}
1437
1438 Of course you can also burn an \ISO\ to \DVD, if that is useful for you.
1439
1440 Desktop \GNU/Linux/Unix systems, including \MacOSX, are able to
1441 mount an \ISO. Windows 8 is the first(!) Windows version which can
1442 do this. Apart from that, nothing changes compared to a normal hard
1443 disk installation, see section \ref{sec:env}.
1444
1445 When preparing such an \ISO\ installation, it is best to omit the
1446 subdirectory for the release year, and have
1447 \filename{texmf-local} at the same level as the other trees
1448 (\filename{texmf-dist}, \filename{texmf-var}, etc.). You can do this with
1449 the normal directory options in the installer.
1450
1451 For a physical (rather than virtual) Windows system, you can burn
1452 the \ISO\ to \acro{DVD}. However, it may be worth your while to
1453 investigate free \ISO-mounting options such as WinCDEmu at
1454 \url{http://wincdemu.sysprogs.org/}.
1455
1456 For Windows system integration, you can include the \filename{w32client}
1457 scripts described in section~\ref{sec:sharedinstall} and at
1458 \url{http://tug.org/texlive/w32client.html}, which work just as well for
1459 an \ISO\ as for a network installation.
1460
1461 On \MacOSX, TeXShop will be able to use the \acro{DVD}
1462 installation if a symlink \filename{/usr/texbin} points to the
1463 appropriate binary directory, e.g.,
1464 \begin{verbatim}
1465 sudo ln -s /Volumes/MyTeXLive/bin/universal-darwin /usr/texbin
1466 \end{verbatim}
1467
1468 Historical note: \TL{} 2010 was the first \TL{} edition which was no
1469 longer distributed `live'. However, it always required some acrobatics
1470 to run from \DVD\ or \ISO; in particular, there was no way around
1471 setting at least one extra environment variable. If you create your
1472 \ISO\ from an existing installation then there is no need for this.
1473
1474
1475 \htmlanchor{tlmgr}
1476 \section{\cmdname{tlmgr}: Managing your installation}
1477 \label{sec:tlmgr}
1478
1479 \begin{figure}[tb]
1480 \tlpng{tlmgr-gui}{\linewidth}
1481 \caption{\prog{tlmgr} in \GUI\ mode: main window, after `Load'.}
1482 \label{fig:tlmgr-gui}
1483 \end{figure}
1484
1485 \begin{figure}[tb]
1486 \hbox to \hsize{%
1487 \vtop{\hsize=.59\linewidth
1488 \null % make figures align at the top
1489 \tlpng{tlmgr-general-options}{\hsize}
1490 \caption{\texttt{tlmgr} in \GUI\ mode: General options}
1491 \label{fig:tlmgr-general-options}
1492 }
1493 \hfil
1494 \vtop{\hsize=.39\linewidth
1495 \null
1496 \tlpng{tlmgr-paper-options}{\hsize}
1497 \caption{\texttt{tlmgr} in \GUI\ mode: Paper size options}
1498 \label{fig:tlmgr-paper-options}
1499 }
1500 }
1501 \end{figure}
1502
1503 \TL{} includes a program named \prog{tlmgr} for managing \TL{} after the
1504 initial installation. Its capabilities include:
1505
1506 \begin{itemize*}
1507 \item installing, updating, backing up, restoring, and uninstalling
1508 individual packages, optionally taking dependencies into account;
1509 \item searching for and listing packages and their descriptions;
1510 \item listing, adding, and removing platforms;
1511 \item changing installation options such as paper size and source
1512 location (see section~\ref{sec:location}).
1513 \end{itemize*}
1514
1515 \prog{tlmgr}'s functionality completely subsumes the \prog{texconfig}
1516 program. We still distribute and maintain \prog{texconfig} for the sake
1517 of anyone used to its interface, but we recommend using \prog{tlmgr}
1518 nowadays.
1519
1520 \subsection{\cmdname{tlmgr} GUI mode}
1521 \prog{tlmgr} can be started in \GUI{} mode (figure~\ref{fig:tlmgr-gui}) with
1522 \begin{alltt}
1523 > \Ucom{tlmgr -gui}
1524 \end{alltt}
1525 or in Windows via the Start menu: \texttt{Start}, \texttt{Programs},
1526 \texttt{TeX Live ...}, \texttt{TeX Live Manager}. After clicking `Load'
1527 it displays a list of available and installed packages. This assumes of
1528 course that the installation source is valid and reachable.
1529
1530 Figures~\ref{fig:tlmgr-general-options} and~\ref{fig:tlmgr-paper-options}
1531 show the general and paper size option screens.
1532
1533 \subsection{Sample \cmdname{tlmgr} command-line invocations}
1534
1535 After the initial installation, you can update your system to the latest
1536 versions available with:
1537 \begin{alltt}
1538 > \Ucom{tlmgr update -all}
1539 \end{alltt}
1540 If this makes you nervous, first try
1541 \begin{alltt}
1542 > \Ucom{tlmgr update -all -dry-run}
1543 \end{alltt}
1544 or (less verbose):
1545 \begin{alltt}
1546 > \Ucom{tlmgr update -list}
1547 \end{alltt}
1548
1549 This more complex example adds a collection, for the engine \XeTeX, from
1550 a local directory:
1551
1552 \begin{alltt}
1553 > \Ucom{tlmgr -repository /local/mirror/tlnet install collection-xetex}
1554 \end{alltt}
1555 It generates the following output (abridged):
1556 \begin{fverbatim}
1557 install: collection-xetex
1558 install: arabxetex
1559 ...
1560 install: xetex
1561 install: xetexconfig
1562 install: xetex.i386-linux
1563 running post install action for xetex
1564 install: xetex-def
1565 ...
1566 running mktexlsr
1567 mktexlsr: Updating /usr/local/texlive/2014/texmf-dist/ls-R...
1568 ...
1569 running fmtutil-sys --missing
1570 ...
1571 Transcript written on xelatex.log.
1572 fmtutil: /usr/local/texlive/2014/texmf-var/web2c/xetex/xelatex.fmt installed.
1573 \end{fverbatim}
1574
1575 As you can see, \prog{tlmgr} installs dependencies, and takes care of any
1576 necessary post-install actions, including updating the filename database
1577 and (re)generating formats. In the above, we generated new formats for
1578 \XeTeX.
1579
1580 To describe a package (or collection or scheme):
1581 \begin{alltt}
1582 > \Ucom{tlmgr show collection-latexextra}
1583 \end{alltt}
1584 which produces output like this:
1585 \begin{fverbatim}
1586 package: collection-latexextra
1587 category: Collection
1588 shortdesc: LaTeX supplementary packages
1589 longdesc: A very large collection of add-on packages for LaTeX.
1590 installed: Yes
1591 revision: 32768
1592 \end{fverbatim}
1593
1594 Last and most important, for full documentation see
1595 \url{http://tug.org/texlive/tlmgr.html}, or:
1596 \begin{alltt}
1597 > \Ucom{tlmgr -help}
1598 \end{alltt}
1599
1600
1601 \section{Notes on Windows}
1602 \label{sec:windows}
1603
1604 \subsection{Windows-specific features}
1605 \label{sec:winfeatures}
1606
1607 Under Windows, the installer does some extra things:
1608 \begin{description}
1609 \item[Menus and shortcuts.] A new `\TL{}' submenu of the
1610 Start menu is installed, which contains entries for some \GUI{}
1611 programs (\prog{tlmgr}, \prog{texdoctk}, the PS\_View (\prog{psv})
1612 PostScript previewer) and some documentation.
1613 \item[File associations.] If enabled, \prog{TeXworks}, \prog{Dviout}
1614 and \prog{PS\_view} become either the default program for
1615 their respective filetypes, or get an entry in the `Open with'
1616 right-click menus of those filetypes.
1617 \item[Bitmap to eps converter.] Various bitmapped formats get an
1618 entry \cmdname{bitmap2eps} in their `Open with' right-click
1619 menu. Bitmap2eps is a simple script which lets \cmdname{sam2p} or
1620 \cmdname{bmeps} do the real work.
1621 \item[Automatic path adjustment.] No manual configuration steps are required.
1622 \item[Uninstaller.] The installer creates an entry under `Add/Remove
1623 Programs' for \TL. The uninstall tab of the \TeX\ Live Manager \GUI\
1624 refers to this.
1625 \end{description}
1626
1627 \subsection{Additional software included on Windows}
1628
1629 To be complete, a \TL{} installation needs support packages that are not
1630 commonly found on a Windows machine. \TL{} provides the missing
1631 pieces:
1632 \begin{description}
1633 \item[Perl and Ghostscript.] Because of the importance of Perl and
1634 Ghostscript, \TL{} includes `hidden' copies of these
1635 programs. \TL{} programs that need them know where to find them,
1636 but they don't betray their presence through environment variables
1637 or registry settings. They aren't full-scale installations, and
1638 shouldn't interfere with any system installations of Perl or
1639 Ghostscript.
1640
1641 \item[PS\_View.] Also installed is PS\_View, a \PS{} and \acro{PDF}
1642 viewer; see figure~\ref{fig:psview}.
1643
1644 \begin{figure}[tb]
1645 \tlpng{psview}{.6\linewidth}
1646 \caption{PS\_View: very high magnifications available!}\label{fig:psview}
1647 \end{figure}
1648
1649 \item[dviout.] Also installed is \prog{dviout}, a \acro{DVI} viewer.
1650 At first, when you preview files with \cmdname{dviout}, it will create
1651 fonts, because screen fonts were not installed. After a while, you
1652 will have created most of the fonts you use, and you will rarely see
1653 the font-creation window. More information can be found in the
1654 (highly recommended) on-line help.
1655
1656 \item[\TeX{}works.] \TeX{}works is a \TeX-oriented editor with
1657 an integrated \acro{PDF} viewer.
1658
1659 \item[Command-line tools.] A number of Windows ports of common Unix
1660 command-line programs are installed along with the usual \TL{}
1661 binaries. These include \cmdname{gzip}, \cmdname{unzip} and the
1662 utilities from the \cmdname{xpdf} suite (\cmdname{pdfinfo},
1663 \cmdname{pdffonts}, \ldots). The \cmdname{xpdf} viewer itself is not
1664 available for Windows. Instead, you can download the Sumatra
1665 \acro{PDF} viewer, which is based on \cmdname{xpdf}, from
1666 \url{http://blog.kowalczyk.info/software/sumatrapdf}, among other options.
1667
1668 \item[fc-list, fc-cache, \ldots] The tools from the fontconfig library allow
1669 \XeTeX{} to handle system fonts on Windows. You can use
1670 \prog{fc-list} to determine the font names to pass to \XeTeX's
1671 extended \cs{font} command. If necessary, run \prog{fc-cache}
1672 first to update font information.
1673
1674 \end{description}
1675
1676
1677 \subsection{User Profile is Home}
1678 \label{sec:winhome}
1679
1680 The Windows counterpart of a Unix home directory is the
1681 \verb|%USERPROFILE%| directory. Under Windows \acro{XP}, this
1682 is usually \verb|C:\Documents and Settings\<username>|, and under
1683 Windows Vista and later it is \verb|C:\Users\<username>|. In the
1684 \filename{texmf.cnf} file, and \KPS{} in general, \verb|~| will expand
1685 appropriately on both Windows and Unix.
1686
1687
1688 \subsection{The Windows registry}
1689 \label{sec:registry}
1690
1691 Windows stores nearly all configuration data in its registry. The
1692 registry contains a set of hierarchically organized keys, with several
1693 root keys. The most important ones for installation programs are
1694 \path{HKEY_CURRENT_USER} and \path{HKEY_LOCAL_MACHINE}, \path{HKCU} and
1695 \path{HKLM} in short. The \path{HKCU} part of the registry is in the
1696 user's home directory (see section~\ref{sec:winhome}). \path{HKLM} is
1697 normally in a subdirectory of the Windows directory.
1698
1699 In some cases, system information could be obtained from environment
1700 variables but for other information, for example the location of
1701 shortcuts, it is necessary to consult the registry. Setting environment
1702 variables permanently also requires registry access.
1703
1704
1705 \subsection{Windows permissions}
1706 \label{sec:winpermissions}
1707
1708 In later versions of Windows, a distinction is made between regular
1709 users and administrators, where only the latter have free access to the
1710 entire operating system. We have made an effort to make \TL{}
1711 installable without administrative privileges.
1712
1713 If the installer is started with administrative permissions, there is an
1714 option to install for all users. If this option is chosen, shortcuts
1715 are created for all users, and the system environment is
1716 modified. Otherwise, shortcuts and menu entries are created for the
1717 current user, and the user environment is modified.
1718
1719 Regardless of administrator status, the default root of \TL{} proposed
1720 by the installer is always under \verb|%SystemDrive%|. The installer
1721 always tests whether the root is writable for the current user.
1722
1723 A problem may arise if the user is not an administrator and \TeX{}
1724 already exists in the search path. Since the effective path
1725 consists of the system path followed by the user path, the new \TL{}
1726 would never get precedence. As a safeguard, the installer creates a
1727 shortcut to the command-prompt in which the new \TL{} binary
1728 directory is prepended to the local search path. The new \TL{} will
1729 be always usable from within such a command-prompt. The shortcut for
1730 \TeX{}works, if installed, also prepends \TL{} to the search path, so it
1731 should also be immune to this path problem.
1732
1733 For Windows Vista and later, you should be aware that even if you are
1734 logged in as administrator, you need to explicitly ask for administrator
1735 privileges. In fact, there is not much point in logging in as
1736 administrator. Instead, right-clicking on the program or shortcut that
1737 you want to run usually gives you a choice `Run as administrator'.
1738
1739 \subsection{Increasing maximum memory on Windows and Cygwin}
1740 \label{sec:cygwin-maxmem}
1741
1742 Windows and Cygwin (see section~\ref{sec:cygwin} for Cygwin installation
1743 specifics) users may find that they run out of memory when running some
1744 of the programs shipped with \TL. For example, \prog{asy} might run out
1745 of memory if you try to allocate an array of 25,000,000 reals, and
1746 Lua\TeX\ might run out of memory if you try to process a document with a
1747 lot of big fonts.
1748
1749 For Cygwin, you can increase the amount of available memory by following
1750 the instructions in the Cygwin User's Guide
1751 (\url{http://www.cygwin.com/cygwin-ug-net/setup-maxmem.html}).
1752
1753 For Windows, you have to create a file, say \code{moremem.reg}, with
1754 these four lines:
1755
1756 \begin{sverbatim}
1757 Windows Registry Editor Version 5.00
1758
1759 [HKEY_LOCAL_MACHINE\Software\Cygwin]
1760 "heap_chunk_in_mb"=dword:ffffff00
1761 \end{sverbatim}
1762
1763 \noindent and then execute the command \code{regedit /s moremem.reg} as
1764 administrator. (If you want to change memory only for the current user
1765 instead of system-wide, use \code{HKEY\_CURRENT\_USER}.)
1766
1767
1768 \section{A user's guide to Web2C}
1769
1770 \Webc{} is an integrated collection of \TeX-related programs: \TeX{}
1771 itself, \MF{}, \MP, \BibTeX{}, etc. It is the heart of \TL{}. The home
1772 page for \Webc{}, with the current manual and more, is
1773 \url{http://tug.org/web2c}.
1774
1775 A bit of history: The original implementation was by Tomas Rokicki who,
1776 in 1987, developed a first \TeX{}-to-C system based on change files
1777 under Unix, which were primarily the original work of Howard Trickey and
1778 Pavel Curtis. Tim Morgan became the maintainer of the system, and
1779 during this period the name changed to Web-to-C\@. In 1990, Karl Berry
1780 took over the work, assisted by dozens of additional contributors, and
1781 in 1997 he handed the baton to Olaf Weber, who returned it to Karl in
1782 2006.
1783
1784 The \Webc{} system runs on Unix, 32-bit Windows systems, \MacOSX{}, and
1785 other operating systems. It uses Knuth's original sources for \TeX{} and
1786 other basic programs written in the \web{} literate programming system
1787 and translates them into C source code. The core \TeX{} programs
1788 handled in this way are:
1789
1790 \begin{cmddescription}
1791 \item[bibtex] Maintaining bibliographies.
1792 \item[dvicopy] Expands virtual font references in \dvi{} files.
1793 \item[dvitomp] \dvi{} to MPX (MetaPost pictures).
1794 \item[dvitype] \dvi{} to human-readable text.
1795 \item[gftodvi] Generic font proofsheets.
1796 \item[gftopk] Generic to packed fonts.
1797 \item[gftype] GF to human-readable text.
1798 \item[mf] Creating typeface families.
1799 \item[mft] Prettyprinting \MF{} source.
1800 \item[mpost] Creating technical diagrams.
1801 \item[patgen] Creating hyphenation patterns.
1802 \item[pktogf] Packed to generic fonts.
1803 \item[pktype] PK to human-readable text.
1804 \item[pltotf] Plain text property list to TFM.
1805 \item[pooltype] Display \web{} pool files.
1806 \item[tangle] \web{} to Pascal.
1807 \item[tex] Typesetting.
1808 \item[tftopl] TFM to plain text property list.
1809 \item[vftovp] Virtual font to virtual property list.
1810 \item[vptovf] Virtual property list to virtual font.
1811 \item[weave] \web{} to \TeX.
1812 \end{cmddescription}
1813
1814 \noindent The precise functions and syntax of these programs are
1815 described in the documentation of the individual packages and of \Webc{}
1816 itself. However, knowing a few principles governing the whole family of
1817 programs will help you take advantage of your \Webc{} installation.
1818
1819 All programs honor these standard \GNU options:
1820 \begin{ttdescription}
1821 \item[-{}-help] print basic usage summary.
1822 \item[-{}-verbose] print detailed progress report.
1823 \item[-{}-version] print version information, then exit.
1824 \end{ttdescription}
1825
1826 For locating files the \Webc{} programs use the path searching library
1827 \KPS{} (\url{http://tug.org/kpathsea}). This library uses a combination
1828 of environment variables and a configuration files to optimize searching
1829 the (huge) collection of \TeX{} files. \Webc{} can look at many
1830 directory trees simultaneously, which is useful in maintaining \TeX's
1831 standard distribution and local and personal extensions in distinct
1832 trees. To speed up file searches, the root of each tree has a file
1833 \file{ls-R}, containing an entry showing the name and relative pathname
1834 for all files under that root.
1835
1836
1837 \subsection{Kpathsea path searching}
1838 \label{sec:kpathsea}
1839
1840 Let us first describe the generic path searching mechanism of the \KPS{}
1841 library.
1842
1843 We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list
1844 of \emph{path elements}, which are basically directory names. A
1845 search path can come from (a combination of) many sources. To look up
1846 a file \samp{my-file} along a path \samp{.:/dir}, \KPS{} checks each
1847 element of the path in turn: first \file{./my-file}, then
1848 \file{/dir/my-file}, returning the first match (or possibly all
1849 matches).
1850
1851 In order to adapt optimally to all operating systems' conventions, on
1852 non-Unix systems \KPS{} can use filename separators different from
1853 colon (\samp{:}) and slash (\samp{/}).
1854
1855 To check a particular path element \var{p}, \KPS{} first checks if a
1856 prebuilt database (see ``Filename data\-base'' on
1857 page~\pageref{sec:filename-database}) applies to \var{p}, i.e., if the
1858 database is in a directory that is a prefix of \var{p}. If so, the path
1859 specification is matched against the contents of the database.
1860
1861 If the database does not exist, or does not apply to this path
1862 element, or contains no matches, the filesystem is searched (if this
1863 was not forbidden by a specification starting with \samp{!!}\ and if
1864 the file being searched for must exist). \KPS{} constructs the list
1865 of directories that correspond to this path element, and then checks
1866 in each for the file being sought.
1867
1868 The ``file must exist'' condition comes into play with \samp{.vf} files and
1869 input files read by \TeX's \cs{openin} command. Such files may not
1870 exist (e.g., \file{cmr10.vf}), and so it would be wrong to search the
1871 disk for them. Therefore, if you fail to update \file{ls-R} when you
1872 install a new \samp{.vf} file, it will never be found.
1873 Each path element is checked in turn: first the database, then the
1874 disk. If a match is found, the search stops and the result is
1875 returned.
1876
1877 Although the simplest and most common path element is a directory
1878 name, \KPS{} supports additional features in search paths: layered
1879 default values, environment variable names, config file values, users'
1880 home directories, and recursive subdirectory searching. Thus, we say
1881 that \KPS{} \emph{expands} a path element, meaning it transforms all
1882 the specifications into basic directory name or names. This is
1883 described in the following sections in the same order as it takes
1884 place.
1885
1886 Note that if the filename being searched for is absolute or explicitly
1887 relative, i.e., starts with \samp{/} or \samp{./} or \samp{../},
1888 \KPS{} simply checks if that file exists.
1889
1890 \ifSingleColumn
1891 \else
1892 \begin{figure*}
1893 \verbatiminput{examples/ex5.tex}
1894 \setlength{\abovecaptionskip}{0pt}
1895 \caption{An illustrative configuration file sample}
1896 \label{fig:config-sample}
1897 \end{figure*}
1898 \fi
1899
1900 \subsubsection{Path sources}
1901 \label{sec:path-sources}
1902
1903 A search path can come from many sources. In the order in which
1904 \KPS{} uses them:
1905
1906 \begin{enumerate}
1907 \item
1908 A user-set environment variable, for instance, \envname{TEXINPUTS}\@.
1909 Environment variables with a period and a program name appended
1910 override; e.g., if \samp{latex} is the name of the program being run,
1911 then \envname{TEXINPUTS.latex} will override \envname{TEXINPUTS}.
1912 \item
1913 A program-specific configuration file, for exam\-ple, a line
1914 \samp{S /a:/b} in \cmdname{dvips}'s \file{config.ps}.
1915 \item A \KPS{} configuration file \file{texmf.cnf}, containing a line like
1916 \samp{TEXINPUTS=/c:/d} (see below).
1917 \item The compile-time default.
1918 \end{enumerate}
1919 \noindent You can see each of these values for a given search path by
1920 using the debugging options (see ``Debugging actions'' on
1921 page~\pageref{sec:debugging}).
1922
1923 \subsubsection{Config files}
1924
1925 \KPS{} reads \emph{runtime configuration files} named \file{texmf.cnf}
1926 for search path and other definitions. The search path used to look
1927 for these files is named \envname{TEXMFCNF}, but we do not recommend
1928 setting this (or any) environment variable.
1929
1930 Instead, normal installation results in a file
1931 \file{.../2014/texmf.cnf}. If you must make changes to the defaults
1932 (not normally necessary), this is the place to put them. The main
1933 configuration file is in \file{.../2014/texmf-dist/web2c/texmf.cnf}.
1934 You should not edit this latter file, as your changes will be lost when
1935 the distributed version is updated.
1936
1937 \emph{All} \file{texmf.cnf} files in the search path will be read and
1938 definitions in earlier files override those in later files. For
1939 example, with a search path of \verb|.:$TEXMF|, values from
1940 \file{./texmf.cnf} override those from \verb|$TEXMF/texmf.cnf|.
1941
1942 \begin{itemize}
1943 \item
1944 Comments start with \code{\%} and continue to the end of the line.
1945 \item
1946 Blank lines are ignored.
1947 \item
1948 A \bs{} at the end of a line acts as a continuation character,
1949 i.e., the next line is appended. Whitespace at the beginning of
1950 continuation lines is not ignored.
1951 \item
1952 Each remaining line has the form:
1953 \begin{alltt}
1954 \var{variable}[.\var{progname}] [=] \var{value}
1955 \end{alltt}%
1956 where the \samp{=} and surrounding whitespace are optional.
1957 \item
1958 The \ttvar{variable} name may contain any character other
1959 than whitespace, \samp{=}, or \samp{.}, but sticking to
1960 \samp{A-Za-z\_} is safest.
1961 \item
1962 If \samp{.\var{progname}} is present, the definition only
1963 applies if the program that is running is named
1964 \texttt{\var{progname}} or \texttt{\var{progname}.exe}. This allows
1965 different flavors of \TeX{} to have different search paths, for
1966 example.
1967 \item \var{value} may contain any characters except
1968 \code{\%} and \samp{@}. The
1969 \code{\$\var{var}.\var{prog}} feature is not available on the
1970 right-hand side; instead, you must use an additional variable. A
1971 \samp{;}\ in \var{value} is translated to \samp{:}\ if
1972 running under Unix; this is useful to be able to have a single
1973 \file{texmf.cnf} for Unix, \acro{MS-DOS} and Windows systems.
1974 \item
1975 All definitions are read before anything is expanded, so
1976 variables can be referenced before they are defined.
1977 \end{itemize}
1978 A configuration file fragment illustrating most of these points is
1979 \ifSingleColumn
1980 shown below:
1981
1982 \verbatiminput{examples/ex5.tex}
1983 \else
1984 shown in Figure~\ref{fig:config-sample}.
1985 \fi
1986
1987 \subsubsection{Path expansion}
1988 \label{sec:path-expansion}
1989
1990
1991 \KPS{} recognizes certain special characters and constructions in
1992 search paths, similar to those available in Unix shells. As a
1993 general example, the complex path,
1994 \verb+~$USER/{foo,bar}//baz+, expands to all subdirectories under
1995 directories \file{foo} and \file{bar} in \texttt{\$USER}'s home
1996 directory that contain a directory or file \file{baz}. These
1997 expansions are explained in the sections below.
1998 %$
1999 \subsubsection{Default expansion}
2000 \label{sec:default-expansion}
2001
2002 If the highest-priority search path (see ``Path sources'' on
2003 page~\pageref{sec:path-sources}) contains an \emph{extra colon} (i.e.,
2004 leading, trailing, or doubled), \KPS{} inserts at that point the
2005 next-highest-prio\-rity search path that is defined. If that inserted
2006 path has an extra colon, the same happens with the next highest. For
2007 example, given an environment variable setting
2008
2009 \begin{alltt}
2010 > \Ucom{setenv TEXINPUTS /home/karl:}
2011 \end{alltt}
2012 and a \code{TEXINPUTS} value from \file{texmf.cnf} of
2013
2014 \begin{alltt}
2015 .:\$TEXMF//tex
2016 \end{alltt}
2017 then the final value used for searching will be:
2018
2019 \begin{alltt}
2020 /home/karl:.:\$TEXMF//tex
2021 \end{alltt}
2022
2023 Since it would be useless to insert the default value in more than one
2024 place, \KPS{} changes only one extra \samp{:}\ and leaves any others in
2025 place. It checks first for a leading \samp{:}, then a trailing
2026 \samp{:}, then a doubled \samp{:}.
2027
2028 \subsubsection{Brace expansion}
2029 \label{sec:brace-expansion}
2030
2031 A useful feature is brace expansion, which means that, for instance,
2032 \verb+v{a,b}w+ expands to \verb+vaw:vbw+. Nesting is allowed.
2033 This is used to implement multiple \TeX{} hierarchies, by
2034 assigning a brace list to \code{\$TEXMF}.
2035 For example, in \file{texmf.cnf}, a definition like this
2036 (simplified for this example) is made:
2037 \begin{verbatim}
2038 TEXMF = {$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFDIST}
2039 \end{verbatim}
2040 We can then use this to define, for example, the \TeX\ input path:
2041 \begin{verbatim}
2042 TEXINPUTS = .;$TEXMF/tex//
2043 \end{verbatim}
2044 %$
2045 which means that, after looking in the current directory, the
2046 \code{\$TEXMFVAR/tex}, \code{\$TEXMFHOME/tex}, \code{\$TEXMFLOCAL/tex}
2047 and \code{\$TEXMFDIST/tex} trees \emph{only}) will be searched (the
2048 last two using \file{ls-R} data base files). It is a convenient
2049 way for running two parallel \TeX{} structures, one ``frozen'' (on a
2050 \CD, for instance) and the other being continuously updated with new
2051 versions as they become available. By using the \code{\$TEXMF}
2052 variable in all definitions, one is sure to always search the
2053 up-to-date tree first.
2054
2055 \subsubsection{Subdirectory expansion}
2056 \label{sec:subdirectory-expansion}
2057
2058 Two or more consecutive slashes in a path element following a directory
2059 \var{d} is replaced by all subdirectories of \var{d}: first those
2060 subdirectories directly under \var{d}, then the subsubdirectories under
2061 those, and so on. At each level, the order in which the directories are
2062 searched is \emph{unspecified}.
2063
2064 If you specify any filename components after the \samp{//}, only
2065 subdirectories with matching components are included. For example,
2066 \samp{/a//b} expands into directories \file{/a/1/b}, \file{/a/2/b},
2067 \file{/a/1/1/b}, and so on, but not \file{/a/b/c} or \file{/a/1}.
2068
2069 Multiple \samp{//} constructs in a path are possible, but
2070 \samp{//} at the beginning of a path is ignored.
2071
2072 \subsubsection{List of special characters and their meaning: a summary}
2073
2074 The following list summarizes the special characters in \KPS{}
2075 configuration files.
2076
2077 % need a wider space for the item labels here.
2078 \newcommand{\CODE}[1]{\makebox[3em][l]{\code{#1}}}
2079 \begin{ttdescription}
2080 \item[\CODE{:}] Separator in path specification; at the beginning or
2081 the end of a path it substitutes the default path expansion.\par
2082 \item[\CODE{;}] Separator on non-Unix systems (acts like \code{:}).
2083 \item[\CODE{\$}] Variable expansion.
2084 \item[\CODE{\string~}] Represents the user's home directory.
2085 \item[\CODE{\char`\{...\char`\}}] Brace expansion.
2086 \item[\CODE{//}] Subdirectory expansion (can occur anywhere in
2087 a path, except at its beginning).
2088 \item[\CODE{\%}] Start of comment.
2089 \item[\CODE{\bs}] Continuation character (allows multi-line entries).
2090 \item[\CODE{!!}] Search \emph{only} database to locate file, \emph{do
2091 not} search the disk.
2092 \end{ttdescription}
2093
2094
2095 \subsection{Filename databases}
2096 \label{sec:filename-database}
2097
2098 \KPS{} goes to some lengths to minimize disk accesses for searches.
2099 Nevertheless, at installations with enough directories, searching each
2100 possible directory for a given file can take an excessively long time
2101 (this is especially true if many hundreds of font directories have to
2102 be traversed.) Therefore, \KPS{} can use an externally-built plain text
2103 ``database'' file named \file{ls-R} that maps files to directories,
2104 thus avoiding the need to exhaustively search the disk.
2105
2106 A second database file \file{aliases} allows you to give additional
2107 names to the files listed in \file{ls-R}. This can be helpful to
2108 confirm to \acro{DOS} 8.3 filename conventions in source files.
2109
2110 \subsubsection{The filename database}
2111 \label{sec:ls-R}
2112
2113 As explained above, the name of the main filename database must be
2114 \file{ls-R}. You can put one at the root of each \TeX{} hierarchy in
2115 your installation that you wish to be searched (\code{\$TEXMF} by
2116 default). \KPS{} looks for
2117 \file{ls-R} files along the \code{TEXMFDBS} path.
2118
2119 The recommended way to create and maintain \samp{ls-R} is to run the
2120 \code{mktexlsr} script included with the distribution. It is invoked
2121 by the various \samp{mktex}\dots\ scripts. In principle, this script
2122 just runs the command
2123 \begin{alltt}
2124 cd \var{/your/texmf/root} && \path|\|ls -1LAR ./ >ls-R
2125 \end{alltt}
2126 presuming your system's \code{ls} produces the right output format
2127 (\GNU \code{ls} is all right). To ensure that the database is
2128 always up-to-date, it is easiest to rebuild it regularly via
2129 \code{cron}, so that it is automatically updated when the installed
2130 files change, such as after installing or updating a \LaTeX{} package.
2131
2132 If a file is not found in the database, by default \KPS{} goes ahead
2133 and searches the disk. If a particular path element begins with
2134 \samp{!!}, however, \emph{only} the database will be searched for that
2135 element, never the disk.
2136
2137
2138 \subsubsection{kpsewhich: Standalone path searching}
2139 \label{sec:invoking-kpsewhich}
2140
2141 The \texttt{kpsewhich} program exercises path searching independent of any
2142 particular application. This can be useful as a sort of \code{find}
2143 program to locate files in \TeX{} hierarchies (this is used heavily in
2144 the distributed \samp{mktex}\dots\ scripts).
2145
2146 \begin{alltt}
2147 > \Ucom{kpsewhich \var{option}\dots{} \var{filename}\dots{}}
2148 \end{alltt}
2149 The options specified in \ttvar{option} start with either \samp{-}
2150 or \samp{-{}-}, and any unambiguous abbreviation is accepted.
2151
2152 \KPS{} looks up each non-option argument on the command line as a
2153 filename, and returns the first file found. There is no option to
2154 return all the files with a particular name (you can run the Unix
2155 \samp{find} utility for that).
2156
2157 The most common options are described next.
2158
2159 \begin{ttdescription}
2160 \item[\texttt{-{}-dpi=\var{num}}]\mbox{}
2161 Set the resolution to \ttvar{num}; this only affects \samp{gf}
2162 and \samp{pk} lookups. \samp{-D} is a synonym, for compatibility
2163 with \cmdname{dvips}. Default is 600.
2164
2165 \item[\texttt{-{}-format=\var{name}}]\mbox{}\\
2166 Set the format for lookup to \ttvar{name}. By default, the
2167 format is guessed from the filename. For formats which do not have
2168 an associated unambiguous suffix, such as \MP{} support files and
2169 \cmdname{dvips} configuration files, you have to specify the name as
2170 known to \KPS{}, such as \texttt{tex} or \texttt{enc files}. Run
2171 \texttt{kpsewhich -{}-help} for a list.
2172
2173 \item[\texttt{-{}-mode=\var{string}}]\mbox{}\\
2174 Set the mode name to \ttvar{string}; this only affects \samp{gf}
2175 and \samp{pk} lookups. No default: any mode will be found.
2176 \item[\texttt{-{}-must-exist}]\mbox{}\\
2177 Do everything possible to find the files, notably including
2178 searching the disk. By default, only the \file{ls-R} database is
2179 checked, in the interest of efficiency.
2180 \item[\texttt{-{}-path=\var{string}}]\mbox{}\\
2181 Search along the path \ttvar{string} (colon-separated as usual),
2182 instead of guessing the search path from the filename. \samp{//} and
2183 all the usual expansions are supported. The options \samp{-{}-path}
2184 and \samp{-{}-format} are mutually exclusive.
2185 \item[\texttt{-{}-progname=\var{name}}]\mbox{}\\
2186 Set the program name to \texttt{\var{name}}.
2187 This can affect the search paths via the \texttt{.\var{progname}}
2188 feature.
2189 The default is \cmdname{kpsewhich}.
2190 \item[\texttt{-{}-show-path=\var{name}}]\mbox{}\\
2191 shows the path used for file lookups of file type \texttt{\var{name}}.
2192 Either a filename extension (\code{.pk}, \code{.vf}, etc.) or a
2193 name can be used, just as with \samp{-{}-format} option.
2194 \item[\texttt{-{}-debug=\var{num}}]\mbox{}\\
2195 sets the debugging options to \texttt{\var{num}}.
2196 \end{ttdescription}
2197
2198
2199 \subsubsection{Examples of use}
2200 \label{sec:examples-of-use}
2201
2202 Let us now have a look at \KPS{} in action. Here's a straightforward search:
2203
2204 \begin{alltt}
2205 > \Ucom{kpsewhich article.cls}
2206 /usr/local/texmf-dist/tex/latex/base/article.cls
2207 \end{alltt}
2208 We are looking for the file \file{article.cls}. Since the \samp{.cls}
2209 suffix is unambiguous we do not need to specify that we want to look for a
2210 file of type \optname{tex} (\TeX{} source file directories). We find it in
2211 the subdirectory \file{tex/latex/base} below the \samp{texmf-dist} \TL\
2212 directory. Similarly, all of the following are found without problems
2213 thanks to their unambiguous suffix.
2214 \begin{alltt}
2215 > \Ucom{kpsewhich array.sty}
2216 /usr/local/texmf-dist/tex/latex/tools/array.sty
2217 > \Ucom{kpsewhich latin1.def}
2218 /usr/local/texmf-dist/tex/latex/base/latin1.def
2219 > \Ucom{kpsewhich size10.clo}
2220 /usr/local/texmf-dist/tex/latex/base/size10.clo
2221 > \Ucom{kpsewhich small2e.tex}
2222 /usr/local/texmf-dist/tex/latex/base/small2e.tex
2223 > \Ucom{kpsewhich tugboat.bib}
2224 /usr/local/texmf-dist/bibtex/bib/beebe/tugboat.bib
2225 \end{alltt}
2226
2227 By the way, that last is a \BibTeX{} bibliography database for
2228 \textsl{TUGboat} articles.
2229
2230 \begin{alltt}
2231 > \Ucom{kpsewhich cmr10.pk}
2232 \end{alltt}
2233 Font bitmap glyph files of type \file{.pk} are used by display
2234 programs like \cmdname{dvips} and \cmdname{xdvi}. Nothing is returned in
2235 this case since there are no pre-generated Computer Modern \samp{.pk}
2236 files in \TL{}\Dash the Type~1 variants are used by default.
2237 \begin{alltt}
2238 > \Ucom{kpsewhich wsuipa10.pk}
2239 \ifSingleColumn /usr/local/texmf-var/fonts/pk/ljfour/public/wsuipa/wsuipa10.600pk
2240 \else /usr/local/texmf-var/fonts/pk/ljfour/public/
2241 ... wsuipa/wsuipa10.600pk
2242 \fi\end{alltt}
2243 For these fonts (a phonetic alphabet from the University of Washington)
2244 we had to generate \samp{.pk} files, and since the default \MF{} mode on
2245 our installation is \texttt{ljfour} with a base resolution of 600\dpi{}
2246 (dots per inch), this instantiation is returned.
2247 \begin{alltt}
2248 > \Ucom{kpsewhich -dpi=300 wsuipa10.pk}
2249 \end{alltt}
2250 In this case, when specifying that we are interested in a resolution
2251 of 300\dpi{} (\texttt{-dpi=300}) we see that no such font is available on
2252 the system. A program like \cmdname{dvips} or \cmdname{xdvi} would
2253 go off and actually build the required \texttt{.pk} files
2254 using the script \cmdname{mktexpk}.
2255
2256 Next we turn our attention to \cmdname{dvips}'s header and configuration
2257 files. We first look at one of the commonly used files, the general
2258 prologue \file{tex.pro} for \TeX{} support, before turning our attention
2259 to the generic configuration file (\file{config.ps}) and the \PS{} font
2260 map \file{psfonts.map}\Dash as of 2004, map and encoding files have
2261 their own search paths and new location in \dirname{texmf} trees. As
2262 the \samp{.ps} suffix is ambiguous we have to specify explicitly which
2263 type we are considering (\optname{dvips config}) for the file
2264 \texttt{config.ps}.
2265 \begin{alltt}
2266 > \Ucom{kpsewhich tex.pro}
2267 /usr/local/texmf/dvips/base/tex.pro
2268 > \Ucom{kpsewhich --format="dvips config" config.ps}
2269 /usr/local/texmf/dvips/config/config.ps
2270 > \Ucom{kpsewhich psfonts.map}
2271 /usr/local/texmf/fonts/map/dvips/updmap/psfonts.map
2272 \end{alltt}
2273
2274 We now take a closer look at the \acro{URW} Times \PS{} support
2275 files. The prefix for these in the standard font naming scheme is
2276 \samp{utm}. The first file we look at is the configuration file,
2277 which contains the name of the map file:
2278 \begin{alltt}
2279 > \Ucom{kpsewhich --format="dvips config" config.utm}
2280 /usr/local/texmf-dist/dvips/psnfss/config.utm
2281 \end{alltt}
2282 The contents of that file is
2283 \begin{alltt}
2284 p +utm.map
2285 \end{alltt}
2286 which points to the file \file{utm.map}, which we want to
2287 locate next.
2288 \begin{alltt}
2289 > \Ucom{kpsewhich utm.map}
2290 /usr/local/texmf-dist/fonts/map/dvips/times/utm.map
2291 \end{alltt}
2292 This map file defines the file names of the Type~1 \PS{} fonts in
2293 the URW collection. Its contents look like (we only show part of the
2294 lines):
2295 \begin{alltt}
2296 utmb8r NimbusRomNo9L-Medi ... <utmb8a.pfb
2297 utmbi8r NimbusRomNo9L-MediItal... <utmbi8a.pfb
2298 utmr8r NimbusRomNo9L-Regu ... <utmr8a.pfb
2299 utmri8r NimbusRomNo9L-ReguItal... <utmri8a.pfb
2300 utmbo8r NimbusRomNo9L-Medi ... <utmb8a.pfb
2301 utmro8r NimbusRomNo9L-Regu ... <utmr8a.pfb
2302 \end{alltt}
2303 Let us, for instance, take the Times Roman instance
2304 \file{utmr8a.pfb} and find its position in the \file{texmf} directory
2305 tree with a search for Type~1 font files:
2306 \begin{alltt}
2307 > \Ucom{kpsewhich utmr8a.pfb}
2308 \ifSingleColumn /usr/local/texmf-dist/fonts/type1/urw/times/utmr8a.pfb
2309 \else /usr/local/texmf-dist/fonts/type1/
2310 ... urw/utm/utmr8a.pfb
2311 \fi\end{alltt}
2312
2313 It should be evident from these examples how you can easily locate the
2314 whereabouts of a given file. This is especially important if you suspect
2315 that the wrong version of a file is picked up somehow, since
2316 \cmdname{kpsewhich} will show you the first file encountered.
2317
2318 \subsubsection{Debugging actions}
2319 \label{sec:debugging}
2320
2321 Sometimes it is necessary to investigate how a program resolves file
2322 references. To make this practical, \KPS{} offers various levels of
2323 debugging output:
2324
2325 \begin{ttdescription}
2326 \item[\texttt{\ 1}] \texttt{stat} calls (disk lookups). When running
2327 with an up-to-date \file{ls-R} database this should almost give no
2328 output.
2329 \item[\texttt{\ 2}] References to hash tables (such as \file{ls-R}
2330 databases, map files, configuration files).
2331 \item[\texttt{\ 4}] File open and close operations.
2332 \item[\texttt{\ 8}] General path information for file types
2333 searched by \KPS. This is useful to find out where a particular
2334 path for the file was defined.
2335 \item[\texttt{16}] Directory list for each path element (only relevant
2336 for searches on disk).
2337 \item[\texttt{32}] File searches.
2338 \item[\texttt{64}] Variable values.
2339 \end{ttdescription}
2340 A value of \texttt{-1} will set all the above options; in practice,
2341 this is usually the most convenient.
2342
2343 Similarly, with the \cmdname{dvips} program, by setting a combination of
2344 debug switches, one can follow in detail where files are being picked up
2345 from. Alternatively, when a file is not found, the debug trace shows in
2346 which directories the program looks for the given file, so that one can
2347 get an indication what the problem~is.
2348
2349 Generally speaking, as most programs call the \KPS{} library
2350 internally, one can select a debug option by using the
2351 \envname{KPATHSEA\_DEBUG} environment variable, and setting it to (a
2352 combination of) values as described in the above list.
2353
2354 (Note for Windows users: it is not easy to redirect
2355 all messages to a file in this system. For diagnostic purposes
2356 you can temporarily \texttt{SET KPATHSEA\_DEBUG\_OUTPUT=err.log}).
2357
2358 Let us consider, as an example, a small \LaTeX{} source file,
2359 \file{hello-world.tex}, which contains the following input.
2360 \begin{verbatim}
2361 \documentclass{article}
2362 \begin{document}
2363 Hello World!
2364 \end{document}
2365 \end{verbatim}
2366 This little file only uses the font \file{cmr10}, so let us look at
2367 how \cmdname{dvips} prepares the \PS{} file (we want to use the Type~1
2368 version of the Computer Modern fonts, hence the option \texttt{-Pcms}).
2369 \begin{alltt}
2370 > \Ucom{dvips -d4100 hello-world -Pcms -o}
2371 \end{alltt}
2372 In this case we have combined \cmdname{dvips}'s debug class 4 (font
2373 paths) with \KPS's path element expansion (see the \cmdname{dvips}
2374 reference manual).
2375 The output (slightly rearranged) appears in
2376 Figure~\ref{fig:dvipsdbga}.
2377 \begin{figure*}[tp]
2378 \centering
2379 \input{examples/ex6a.tex}
2380 \caption{Finding configuration files}\label{fig:dvipsdbga}
2381
2382 \bigskip
2383
2384 \input{examples/ex6b.tex}
2385 \caption{Finding the prolog file}\label{fig:dvipsdbgb}
2386
2387 \bigskip
2388
2389 \input{examples/ex6c.tex}
2390 \caption{Finding the font file}\label{fig:dvipsdbgc}
2391 \end{figure*}
2392
2393 \cmdname{dvips} starts by locating its working files. First,
2394 \file{texmf.cnf} is found, which gives the definitions of the search
2395 paths for the other files, then the file database \file{ls-R} (to
2396 optimize file searching) and the file \file{aliases}, which makes it
2397 possible to declare several names (e.g., a short \acro{DOS}-like 8.3 and
2398 a more natural longer version) for the same file. Then \cmdname{dvips}
2399 goes on to find the generic configuration file \file{config.ps}
2400 before looking for the customization file \file{.dvipsrc} (which, in
2401 this case is \emph{not found}). Finally, \cmdname{dvips} locates the
2402 config file for the Computer Modern \PS{} fonts \file{config.cms}
2403 (this was initiated with the \texttt{-Pcms} option on the \cmdname{dvips}
2404 command). This file contains the list of the map files which
2405 define the relation between the \TeX{}, \PS{} and file system
2406 names of the fonts.
2407 \begin{alltt}
2408 > \Ucom{more /usr/local/texmf/dvips/cms/config.cms}
2409 p +ams.map
2410 p +cms.map
2411 p +cmbkm.map
2412 p +amsbkm.map
2413 \end{alltt}
2414 \cmdname{dvips} thus goes on to find all these files, plus the generic
2415 map file \file{psfonts.map}, which is always loaded (it contains
2416 declarations for commonly used \PS{} fonts; see the last part of
2417 Section \ref{sec:examples-of-use} for more details about \PS{} map
2418 file handling).
2419
2420 At this point \cmdname{dvips} identifies itself to the user:
2421 \begin{alltt}
2422 This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com)
2423 \end{alltt}
2424 \ifSingleColumn
2425 Then it goes on to look for the prolog file \file{texc.pro}:
2426 \begin{alltt}\small
2427 kdebug:start search(file=texc.pro, must\_exist=0, find\_all=0,
2428 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
2429 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
2430 kdebug:search(texc.pro) => /usr/local/texmf/dvips/base/texc.pro
2431 \end{alltt}
2432 \else
2433 Then it goes on to look for the prolog file \file{texc.pro} (see
2434 Figure~\ref{fig:dvipsdbgb}).
2435 \fi
2436
2437 After having found the file in question, \cmdname{dvips} outputs
2438 the date and time, and informs us that it will generate the
2439 file \file{hello-world.ps}, then that it needs the font file
2440 \file{cmr10}, and that the latter is declared as ``resident'' (no
2441 bitmaps needed):
2442 \begin{alltt}\small
2443 TeX output 1998.02.26:1204' -> hello-world.ps
2444 Defining font () cmr10 at 10.0pt
2445 Font cmr10 <CMR10> is resident.
2446 \end{alltt}
2447 Now the search is on for the file \file{cmr10.tfm}, which is found,
2448 then a few more prolog files (not shown) are referenced, and finally
2449 the Type~1 instance \file{cmr10.pfb} of the font is located and
2450 included in the output file (see last line).
2451 \begin{alltt}\small
2452 kdebug:start search(file=cmr10.tfm, must\_exist=1, find\_all=0,
2453 path=.:~/tex/fonts/tfm//:!!/usr/local/texmf/fonts/tfm//:
2454 /var/tex/fonts/tfm//).
2455 kdebug:search(cmr10.tfm) => /usr/local/texmf/fonts/tfm/public/cm/cmr10.tfm
2456 kdebug:start search(file=texps.pro, must\_exist=0, find\_all=0,
2457 ...
2458 <texps.pro>
2459 kdebug:start search(file=cmr10.pfb, must\_exist=0, find\_all=0,
2460 path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
2461 ~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
2462 kdebug:search(cmr10.pfb) => /usr/local/texmf/fonts/type1/public/cm/cmr10.pfb
2463 <cmr10.pfb>[1]
2464 \end{alltt}
2465
2466 \subsection{Runtime options}
2467
2468 Another useful feature of \Webc{} is its possibility to control a number
2469 of memory parameters (in particular, array sizes) via the runtime file
2470 \file{texmf.cnf} read by \KPS{}. The memory settings can be found in
2471 Part~3 of that file in the \TL{} distribution. The more important
2472 are:
2473
2474 \begin{ttdescription}
2475 \item[\texttt{main\_memory}]
2476 Total words of memory available, for
2477 \TeX{}, \MF{} and \MP. You must make a new format file for each
2478 different setting. For instance, you could generate a ``huge''
2479 version of \TeX{}, and call the format file \texttt{hugetex.fmt}.
2480 Using the standard way of specifying the program name used by \KPS{},
2481 the particular value of the \texttt{main\_memory} variable will then
2482 be read from \file{texmf.cnf}.
2483 \item[\texttt{extra\_mem\_bot}]
2484 Extra space for ``large'' \TeX{} data structures:
2485 boxes, glue, breakpoints, etc. Especially useful if you use
2486 \PiCTeX{}.
2487 \item[\texttt{font\_mem\_size}]
2488 Number of words for font information available for \TeX. This
2489 is more or less the total size of all \acro{TFM} files read.
2490 \item[\texttt{hash\_extra}]
2491 Additional space for the hash table of control sequence names.
2492 Only $\approx$10,000 control sequences can be stored in the main
2493 hash table; if you have a large book with numerous cross-references,
2494 this might not be enough. The default value of
2495 \texttt{hash\_extra} is \texttt{50000}.
2496 \end{ttdescription}
2497
2498 \noindent Of course, this facility is no substitute for truly dynamic
2499 arrays and memory allocation, but since these are extremely difficult to
2500 implement in the present \TeX{} source, these runtime parameters provide
2501 a practical compromise allowing some flexibility.
2502
2503
2504 \begin{comment}
2505 \section{Building on a new Unix platform}
2506
2507 If you have a platform for which executables are not included, you will
2508 need to compile \TeX{} and friends. This is not as hard as it
2509 sounds. What you need is all in the directory \texttt{source} in the
2510 distribution.
2511
2512 \subsection{Prerequisites}
2513
2514 You will need at least 100 megabytes of disk space to compile all of
2515 \TeX{} and its support programs. You'll also need an \acro{ANSI} C
2516 compiler, a \cmdname{make} utility, a lexical scanner, and a parser
2517 generator. We recommend the \GNU version of these programs
2518 (\cmdname{gcc}, \GNU \cmdname{make}, \cmdname{m4}, \cmdname{flex},
2519 \cmdname{bison}). You may be able to work with other C compilers and
2520 \cmdname{make} programs, but you will need a good understanding of
2521 building Unix programs to sort out problems.
2522
2523 Also, the command \texttt{uname} must return a sensible value.
2524
2525
2526 \subsection{Configuration}
2527
2528 To begin, perform a normal installation of \TL{} to your disk (see
2529 section~\ref{sec:install-disk} on
2530 \p.\pageref{sec:install-disk}). You may wish to skip installing
2531 all of the prebuilt binaries.
2532
2533 Then, unpack the source from the compressed \texttt{tar} file in the
2534 directory \dirname{source} to your disk and change directory to where
2535 you placed it.
2536
2537 Next, run \cmdname{configure} with a command line like this:
2538 \begin{alltt}
2539 > \Ucom{sh configure -prefix=/usr/local/TeX}
2540 \end{alltt}
2541
2542 The \optname{-prefix} directory is the one where you installed the
2543 support tree; the directory layout will be as follows (where \$TEXDIR
2544 stands for the directory you chose):
2545
2546 \noindent
2547 \begin{tabular}{>{\ttfamily}ll@{}}
2548 \dirname{$TEXDIR/share/texmf} & main tree with fonts,\\
2549 & \qquad macros, etc\\
2550 \dirname{$TEXDIR/man} & Unix manual pages\\
2551 \dirname{$TEXDIR/info} & \GNU style Info manuals\\
2552 \dirname{$TEXDIR/bin/$PLATFORM} & binaries\\
2553 \end{tabular}
2554 %$
2555
2556 If you want to leave out the \dirname{$PLATFORM} directory level,
2557 i.e., put the binaries directly into \dirname{$TEXDIR/bin}, specify
2558 the \verb|--disable-multiplatform| option to \cmdname{configure}.
2559
2560 Have a look at the output of \verb|./configure --help| for more
2561 options you can use. For example, you can skip building of \OMEGA{} and
2562 \eTeX{}.
2563
2564
2565 \subsection{Running \cmdname{make}}
2566
2567 Make sure the shell variable or option \texttt{noclobber} is not set.
2568 Then, run the main \cmdname{make} like this:
2569 \begin{alltt}
2570 > \Ucom{make world}
2571 \end{alltt}
2572 and relax\ldots
2573
2574 Alternatively, you want to log all the output, as in:
2575 \begin{alltt}
2576 > \Ucom{sh -c "make world >world.log 2>\&1" \&}
2577 \end{alltt}
2578
2579 Before you believe that everything went ok, please check the log file
2580 for errors: \GNU \cmdname{make} always uses the string \samp{***}
2581 whenever a command fails. Also, check if all the programs were built:
2582
2583 \begin{alltt}
2584 > \Ucom{cd \var{TEXDIR}/bin/\var{archname}}
2585 > \Ucom{ls | wc}
2586 \end{alltt}
2587 The result should be over 200 (you can check the exact number with the
2588 \dirname{bin} directory contents in the distribution).
2589
2590 If you need special privileges for \texttt{make install}, you can
2591 separate the \samp{make world} into two different runs, like this:
2592 \begin{alltt}
2593 > \Ucom{make all}
2594 > \Ucom{su}
2595 > \Ucom{make install strip}
2596 \end{alltt}
2597
2598 After you've installed your new binaries, you should follow the normal
2599 post-installation procedures, given in section~\ref{sec:postinstall}
2600 (\p.\pageref{sec:postinstall}).
2601
2602 Also, if you'd like to make your binaries available to others, please
2603 contact us. We'll be happy to put them on the \TL\ web pages.
2604 \end{comment}
2605
2606 \htmlanchor{ack}
2607 \section{Acknowledgements}
2608
2609 \TL{} is a joint effort by virtually all of the \TeX{} user groups.
2610 This edition of \TL{} was overseen by Karl Berry. The other principal
2611 contributors, past and present, are listed below.
2612
2613 \begin{itemize*}
2614
2615 \item The English, German, Dutch, and Polish \TeX{} user groups
2616 (\acro{TUG}, \acro{DANTE} e.V., \acro{NTG}, and \acro{GUST},
2617 respectively), which provide the necessary technical and administrative
2618 infrastructure. Please join the \TeX\ user group near you! (See
2619 \url{http://tug.org/usergroups.html}.)
2620
2621 \item The \acro{CTAN} team, notably Robin Fairbairns and Rainer
2622 Sch\"opf, which distributes the \TL{} images and provides the common
2623 infrastructure for package updates, upon which \TL{} depends.
2624
2625 \item Nelson Beebe, for making many platforms available to \TL\
2626 developers, and his own comprehensive testing.
2627
2628 \item John Bowman, for making many changes to his advanced graphics
2629 program Asymptote to make it work in \TL.
2630
2631 \item Peter Breitenlohner and the \eTeX\ team for the stable foundation
2632 of future \TeX's, and Peter specifically for stellar help with \GNU\
2633 autotools usage throughout \TL.
2634
2635 \item Jin-Hwan Cho and all of the DVIPDFM$x$ team, for their
2636 excellent driver and responsiveness to configuration issues.
2637
2638 \item Thomas Esser, without whose marvelous \teTeX{} package \TL{}
2639 would have never existed.
2640
2641 \item Michel Goossens, who co-authored the original documentation.
2642
2643 \item Eitan Gurari, whose \TeX4ht is used to create the \HTML{}
2644 version of this documentation, and who worked tirelessly to improve it
2645 at short notice, every year. Eitan prematurely passed away in June
2646 2009, and we dedicate this documentation to his memory.
2647
2648 \item Hans Hagen, for much testing and making his \ConTeXt\ format
2649 (\url{http://pragma-ade.com}) work within \TL's framework.
2650
2651 \item \Thanh, Martin Schr\"oder, and the pdf\TeX\ team
2652 (\url{http://pdftex.org}) for continuing enhancements of \TeX's
2653 abilities.
2654
2655 \item Hartmut Henkel, for significant development contributions to
2656 pdf\TeX\, Lua\TeX, and more.
2657
2658 \item Taco Hoekwater, for major renewed development efforts on MetaPost and
2659 (Lua)\TeX\ (\url{http://luatex.org}) itself, incorporating
2660 \ConTeXt\ into \TL, giving Kpathsea multi-threaded functionality, and
2661 much more.
2662
2663 \item Pawe{\l} Jackowski, for the Windows installer \cmdname{tlpm},
2664 and Tomasz {\L}uczak, for \cmdname{tlpmgui}, used in past releases.
2665
2666 \item Akira Kakuto, for providing the Windows
2667 binaries from his \acro{W32TEX} distribution for Japanese \TeX\
2668 (\url{http://w32tex.org}), and many other development contributions.
2669
2670 \item Jonathan Kew, for developing the remarkable \XeTeX{} engine and
2671 taking the time and trouble to integrate it in \TL{}, as well as the
2672 initial version of the Mac\TeX\ installer, and also for our recommended
2673 front-end \TeX{}works.
2674
2675 \item Dick Koch, for maintaining Mac\TeX\ (\url{http://tug.org/mactex})
2676 in very close tandem with \TL{}, and for his great good cheer in doing
2677 so.
2678
2679 \item Reinhard Kotucha, for major contributions to the \TL{} 2008
2680 infrastructure and installer, as well as Windows research efforts, the
2681 \texttt{getnonfreefonts} script, and more.
2682
2683 \item Siep Kroonenberg, also for major contributions to the \TL{} 2008
2684 infrastructure and installer, especially on Windows, and for the bulk of
2685 work updating this manual describing those features.
2686
2687 \item Mojca Miklavec, for much help with \ConTeXt.
2688
2689 \item Heiko Oberdiek, for the \pkgname{epstopdf} package and many
2690 others, compressing the huge \pkgname{pst-geo} data files so we could
2691 include them, and most of all, for his remarkable work on
2692 \pkgname{hyperref}.
2693
2694 \item Petr Ol\v{s}ak, who coordinated and checked all the Czech and Slovak
2695 material very carefully.
2696
2697 \item Toshio Oshima, for his \cmdname{dviout} previewer for Windows.
2698
2699 \item Manuel P\'egouri\'e-Gonnard, for helping with package updates,
2700 documentation improvements, and \cmdname{texdoc} development.
2701
2702 \item Fabrice Popineau, for the original Windows support in \TL{} and
2703 work on the French documentation.
2704
2705 \item Norbert Preining, the principal architect of the \TL{} 2008
2706 infrastructure and installer, and also for coordinating the Debian
2707 version of \TL{} (together with Frank K\"uster), making many suggestions
2708 along the way.
2709
2710 \item Sebastian Rahtz, for originally creating \TL{} and maintaining it
2711 for many years.
2712
2713 \item Phil Taylor, for setting up the BitTorrent downloads.
2714
2715 \item Tomasz Trzeciak, for wide-ranging help with Windows.
2716
2717 \item Vladimir Volovich, for substantial help with porting and other
2718 maintenance issues, and especially for making it feasible to include
2719 \cmdname{xindy}.
2720
2721 \item Staszek Wawrykiewicz, the principal tester for all of \TL{},
2722 and coordinator of the many major Polish contributions: fonts, Windows
2723 installation, and more.
2724
2725 \item Olaf Weber, for his patient maintenance of \Webc.
2726
2727 \item Gerben Wierda, for creating and maintaining the original \MacOSX\
2728 support.
2729
2730 \item Graham Williams, the originator of the \TeX\ Catalogue.
2731
2732 \end{itemize*}
2733
2734 Builders of the binaries:
2735 Ettore Aldrovandi (\pkgname{i386-solaris}, \pkgname{x86\_64-solaris}),
2736 Marc Baudoin (\pkgname{amd64-netbsd}, \pkgname{i386-netbsd}),
2737 Karl Berry (\pkgname{i386-linux}),
2738 Alan Braslau (\pkgname{amd64-kfreebsd}, \pkgname{i386-kfreebsd}),
2739 Peter Breitenlohner (\pkgname{x86\_64-linux}),
2740 Ken Brown (\pkgname{i386-cygwin}, \pkgname{x86\_64-cygwin}),
2741 Simon Dales (\pkgname{armhf-linux}),
2742 %Christian Mensing (\pkgname{mips-irix}),
2743 Akira Kakuto (\pkgname{win32}),
2744 Dick Koch (\pkgname{universal-darwin}, \pkgname{x86\_64-darwin}),
2745 Nikola Le\v{c}i\'c (\pkgname{amd64-freebsd}, \pkgname{i386-freebsd}),
2746 Mojca Miklavec (\pkgname{mipsel-linux}), \pkgname{sparc-solaris}),
2747 Norbert Preining (\pkgname{alpha-linux}),
2748 Thomas Schmitz (\pkgname{powerpc-linux}),
2749 Boris Veytsman (\pkgname{armel-linux}).
2750 For information on the \TL{} build process, see
2751 \url{http://tug.org/texlive/build.html}.
2752
2753 Translators of this manual:
2754 Boris Veytsman (Russian),
2755 Jjgod Jiang, Jinsong Zhao, Yue Wang, \& Helin Gai (Chinese),
2756 Uwe Ziegenhagen (German),
2757 Manuel P\'egouri\'e-Gonnard (French),
2758 Marco Pallante (Italian),
2759 Nikola Le\v{c}i\'c (Serbian),
2760 Petr Sojka \& Jan Busa (Czech\slash Slovak),
2761 Staszek Wawrykiewicz (Polish). The \TL{} documentation web page
2762 is \url{http://tug.org/texlive/doc.html}.
2763
2764 Of course the most important acknowledgement must go to Donald Knuth,
2765 first for inventing \TeX, and then for giving it to the world.
2766
2767
2768
2769 \section{Release history}
2770 \label{sec:history}
2771
2772 \subsection{Past}
2773
2774 Discussion began in late 1993 when the Dutch \TeX{} Users Group was
2775 starting work on its 4All\TeX{} \CD{} for \acro{MS-DOS} users, and it
2776 was hoped at that time to issue a single, rational, \CD{} for all
2777 systems. This was too ambitious a target for the time, but it did spawn
2778 not only the very successful 4All\TeX{} \CD{}, but also the \acro{TUG}
2779 Technical Council working group on a \emph{\TeX{} Directory Structure}
2780 (\url{http://tug.org/tds}), which specified how to create consistent and
2781 manageable collections of \TeX{} support files. A complete draft of the
2782 \TDS{} was published in the December 1995 issue of \textsl{TUGboat}, and
2783 it was clear from an early stage that one desirable product would be a
2784 model structure on \CD{}. The distribution you now have is a very direct
2785 result of the working group's deliberations. It was also clear that the
2786 success of the 4All\TeX{} \CD{} showed that Unix users would benefit
2787 from a similarly easy system, and this is the other main strand of
2788 \TL.
2789
2790 We first undertook to make a new Unix-based \TDS{} \CD{} in the autumn
2791 of 1995, and quickly identified Thomas Esser's \teTeX{} as the ideal
2792 setup, as it already had multi-platform support and was built with
2793 portability across file systems in mind. Thomas agreed to help, and work
2794 began seriously at the start of 1996. The first edition was released in
2795 May 1996. At the start of 1997, Karl Berry completed a major new release
2796 of Web2c, which included nearly all the features which Thomas Esser had
2797 added in \teTeX, and we decided to base the 2nd edition of the \CD{} on
2798 the standard \Webc, with the addition of \teTeX's \texttt{texconfig}
2799 script. The 3rd edition of the \CD{} was based on a major revision of
2800 \Webc, 7.2, by Olaf Weber; at the same time, a new revision of \teTeX
2801 was being made, and \TL{} included almost all of its features. The
2802 4th edition followed the same pattern, using a new version of \teTeX,
2803 and a new release of \Webc{} (7.3). The system now included a complete
2804 Windows setup.
2805
2806 For the 5th edition (March 2000) many parts of the \CD{} were revised
2807 and checked, updating hundreds of packages. Package details were stored
2808 in XML files. But the major change for \TeX\ Live 5 was that all
2809 non-free software was removed. Everything in \TL{} is now intended
2810 to be compatible with the Debian Free Software Guidelines
2811 (\url{http://www.debian.org/intro/free}); we have done our best to check
2812 the license conditions of all packages, but we would very much
2813 appreciate hearing of any mistakes.
2814
2815 The 6th edition (July 2001) had much more material updated. The major
2816 change was a new install concept: the user could select a more exact set
2817 of needed collections. Language-related collections were completely
2818 reorganized, so selecting any of them installs not only macros, fonts,
2819 etc., but also prepares an appropriate \texttt{language.dat}.
2820
2821 The 7th edition of 2002 had the notable addition of \MacOSX{} support,
2822 and the usual myriad of updates to all sorts of packages and
2823 programs. An important goal was integration of the source back with
2824 \teTeX, to correct the drift apart in versions~5 and~6.
2825
2826 \subsubsection{2003}
2827
2828 In 2003, with the continuing flood of updates and additions, we found
2829 that \TL{} had grown so large it could no longer be contained on a
2830 single \CD, so we split it into three different distributions (see
2831 section~\ref{sec:tl-coll-dists}, \p.\pageref{sec:tl-coll-dists}). In
2832 addition:
2833
2834 \begin{itemize*}
2835 \item At the request of the \LaTeX{} team, we changed the standard
2836 \cmdname{latex} and \cmdname{pdflatex} commands to now use \eTeX{} (see
2837 \p.\pageref{text:etex}).
2838 \item The new Latin Modern fonts were included (and are recommended).
2839 \item Support for Alpha \acro{OSF} was removed
2840 (\acro{HPUX} support was removed previously), since no one had (or
2841 volunteered) hardware available on which to compile new binaries.
2842 \item Windows setup was substantially changed; for the first time
2843 an integrated environment based on XEmacs was introduced.
2844 \item Important supplementary programs for Windows
2845 (Perl, Ghost\-script, Image\-Magick, Ispell) are now installed
2846 in the \TL{} installation directory.
2847 \item Font map files used by \cmdname{dvips}, \cmdname{dvipdfm}
2848 and \cmdname{pdftex} are now generated by the new program
2849 \cmdname{updmap} and installed into \dirname{texmf/fonts/map}.
2850 \item \TeX{}, \MF{}, and \MP{} now, by default, output most input
2851 characters (32 and above) as themselves in output (e.g.,
2852 \verb|\write|) files,
2853 log files, and the terminal, i.e., \emph{not} translated using the
2854 \verb|^^| notation. In \TL{}~7, this translation was
2855 dependent on the system locale settings; now, locale settings do
2856 not influence the \TeX{} programs' behavior. If for some reason
2857 you need the \verb|^^| output, rename the file
2858 \verb|texmf/web2c/cp8bit.tcx|. (Future releases will have cleaner
2859 ways to control this.)
2860 \item This documentation was substantially revised.
2861 \item Finally, since the edition numbers had grown unwieldy,
2862 the version is now simply identified by the year: \TL{} 2003.
2863 \end{itemize*}
2864
2865
2866 \subsubsection{2004}
2867
2868 2004 saw many changes:
2869
2870 \begin{itemize}
2871
2872 \item If you have locally-installed fonts which use their own
2873 \filename{.map} or (much less likely) \filename{.enc} support files, you
2874 may need to move those support files.
2875
2876 \filename{.map} files are now searched for in subdirectories of
2877 \dirname{fonts/map} only (in each \filename{texmf} tree), along the
2878 \envname{TEXFONTMAPS} path. Similarly, \filename{.enc} files are now
2879 searched for in subdirectories of \dirname{fonts/enc} only, along the
2880 \envname{ENCFONTS} path. \cmdname{updmap} will attempt to warn about
2881 problematic files.
2882
2883 For methods of handling this and other information, please see
2884 \url{http://tug.org/texlive/mapenc.html}.
2885
2886 \item The \TK\ has been expanded with the addition of a \MIKTEX-based
2887 installable \CD, for those who prefer that implementation to Web2C.
2888 See section~\ref{sec:overview-tl} (\p.\pageref{sec:overview-tl}).
2889
2890 \item Within \TL, the single large \dirname{texmf} tree of previous
2891 releases has been replaced by three: \dirname{texmf},
2892 \dirname{texmf-dist}, and \dirname{texmf-doc}. See
2893 section~\ref{sec:tld} (\p.\pageref{sec:tld}), and the \filename{README}
2894 files for each.
2895
2896 \item All \TeX-related input files are now collected in
2897 the \dirname{tex} subdirectory of \dirname{texmf*} trees, rather than
2898 having separate sibling directories \dirname{tex}, \dirname{etex},
2899 \dirname{pdftex}, \dirname{pdfetex}, etc. See
2900 \CDref{texmf-dist/doc/generic/tds/tds.html\#Extensions}
2901 {\texttt{texmf-dist/doc/generic/tds/tds.html\#Extensions}}.
2902
2903 \item Helper scripts (not meant to be invoked by users) are now located
2904 in a new \dirname{scripts} subdirectory of \dirname{texmf*} trees, and
2905 can be searched for via \verb|kpsewhich -format=texmfscripts|. So if you have
2906 programs which call such scripts, they'll need to be adjusted. See
2907 \CDref{texmf-dist/doc/generic/tds/tds.html\#Scripts}
2908 {\texttt{texmf-dist/doc/generic/tds/tds.html\#Scripts}}.
2909
2910 \item Almost all formats leave most characters printable as
2911 themselves via the ``translation file'' \filename{cp227.tcx}, instead of
2912 translating them with the \verb|^^| notation. Specifically, characters
2913 at positions 32--256, plus tab, vertical tab, and form feed are
2914 considered printable and not translated. The exceptions are plain \TeX\
2915 (only 32--126 printable), \ConTeXt\ (0--255 printable), and the
2916 \OMEGA-related formats. This default behavior is almost the same as in
2917 \TL\,2003, but it's implemented more cleanly, with more possibilities
2918 for customization. See \CDref{texmf-dist/doc/web2c/web2c.html\#TCX-files}
2919 {\texttt{texmf-dist/doc/web2c/web2c.html\#TCX-files}}.
2920 (By the way, with Unicode input, \TeX\ may output partial character
2921 sequences when showing error contexts, since it is byte-oriented.)
2922
2923 \item \textsf{pdfetex} is now the default engine for all formats
2924 except (plain) \textsf{tex} itself. (Of course it generates \acro{DVI}
2925 when run as \textsf{latex}, etc.) This means, among other things, that
2926 the microtypographic features of \textsf{pdftex} are available in
2927 \LaTeX, \ConTeXt, etc., as well as the \eTeX\ features
2928 (\OnCD{texmf-dist/doc/etex/base/}).
2929
2930 It also means it's \emph{more important than ever} to use the
2931 \pkgname{ifpdf} package (works with both plain and \LaTeX) or equivalent
2932 code, because simply testing whether \cs{pdfoutput} or some other
2933 primitive is defined is not a reliable way to determine if \acro{PDF}
2934 output is being generated. We made this backward compatible as best we
2935 could this year, but next year, \cs{pdfoutput} may be defined even when
2936 \acro{DVI} is being written.
2937
2938 \item pdf\TeX\ (\url{http://pdftex.org}) has many new features:
2939
2940 \begin{itemize*}
2941
2942 \item \cs{pdfmapfile} and \cs{pdfmapline} provide font map support
2943 from within a document.
2944
2945 \item Microtypographic font expansion can be used more easily.\\
2946 \url{http://www.ntg.nl/pipermail/ntg-pdftex/2004-May/000504.html}
2947
2948 \item All parameters previously set through the special configuration
2949 file \filename{pdftex.cfg} must now be set through primitives,
2950 typically in \filename{pdftexconfig.tex}; \filename{pdftex.cfg} is no
2951 longer supported. Any extant \filename{.fmt} files must be redumped
2952 when \filename{pdftexconfig.tex} is changed.
2953
2954 \item See the pdf\TeX\ manual for more: \OnCD{texmf-dist/doc/pdftex/manual/pdftex-a.pdf}.
2955
2956 \end{itemize*}
2957
2958 \item The \cs{input} primitive in \cmdname{tex} (and \cmdname{mf} and
2959 \cmdname{mpost}) now accepts double quotes containing spaces and other
2960 special characters. Typical examples:
2961 \begin{verbatim}
2962 \input "filename with spaces" % plain
2963 \input{"filename with spaces"} % latex
2964 \end{verbatim}
2965 See the Web2C manual for more: \OnCD{texmf-dist/doc/web2c}.
2966
2967 \item enc\TeX\ support is now included within Web2C and consequently all
2968 \TeX\ programs, via the \optname{-enc} option\Dash \emph{only when
2969 formats are built}. enc\TeX\ supports general re-encoding of input and
2970 output, enabling full support of Unicode (in \acro{UTF}-8). See
2971 \OnCD{texmf-dist/doc/generic/enctex/} and
2972 \url{http://www.olsak.net/enctex.html}.
2973
2974 \item Aleph, a new engine combining \eTeX\ and \OMEGA, is available.
2975 A little information is available in \OnCD{texmf-dist/doc/aleph/base}
2976 and \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=aleph}. The
2977 \LaTeX-based format for Aleph is named \textsf{lamed}.
2978
2979 \item The latest \LaTeX\ release has a new version of the
2980 \acro{LPPL}\Dash now officially a Debian-approved license. Assorted
2981 other updates, see the \filename{ltnews} files in
2982 \OnCD{texmf-dist/doc/latex/base}.
2983
2984 \item \cmdname{dvipng}, a new program for converting \acro{DVI} to
2985 \acro{PNG} image files, is included. See
2986 \url{http://www.ctan.org/pkg/dvipng}.
2987
2988 \item We reduced the \pkgname{cbgreek} package to a ``medium'' sized set
2989 of fonts, with the assent and advice of the author (Claudio Beccari).
2990 The excised fonts are the invisible, outline, and transparency ones,
2991 which are relatively rarely used, and we needed the space. The full set
2992 is of course available from \acro{CTAN}
2993 (\url{http://mirror.ctan.org/tex-archive/fonts/greek/cbfonts}).
2994
2995 \item \cmdname{oxdvi} has been removed; just use \cmdname{xdvi}.
2996
2997 \item The \cmdname{ini} and \cmdname{vir} commands (links) for
2998 \cmdname{tex}, \cmdname{mf}, and \cmdname{mpost} are no longer created,
2999 such as \cmdname{initex}. The \cmdname{ini} functionality has been
3000 available through the command-line option \optname{-ini} for years now.
3001
3002 \item \textsf{i386-openbsd} platform support was removed. Since the
3003 \pkgname{tetex} package in the \acro{BSD} Ports system is available, and
3004 \acro{GNU/}Linux and Free\acro{BSD} binaries were available, it seemed
3005 volunteer time could be better spent elsewhere.
3006
3007 \item On \textsf{sparc-solaris} (at least), you may have to set the
3008 \envname{LD\_LIBRARY\_PATH} environment variable to run the
3009 \pkgname{t1utils} programs. This is because they are compiled with C++,
3010 and there is no standard location for the runtime libraries. (This is
3011 not new in 2004, but wasn't previously documented.) Similarly, on
3012 \textsf{mips-irix}, the \acro{MIPS}pro 7.4 runtimes are required.
3013
3014 \end{itemize}
3015
3016 \subsubsection{2005}
3017
3018 2005 saw the usual huge number of updates to packages and programs.
3019 The infrastructure stayed relatively stable from 2004, but inevitably
3020 there were some changes there as well:
3021
3022 \begin{itemize}
3023
3024 \item New scripts \cmdname{texconfig-sys}, \cmdname{updmap-sys}, and
3025 \cmdname{fmtutil-sys} were introduced, which modify the
3026 configuration in the system trees. The \cmdname{texconfig},
3027 \cmdname{updmap}, and \cmdname{fmtutil} scripts now modify
3028 user-specific files, under \dirname{$HOME/.texlive2005}.
3029
3030 \item Corresponding new variables \envname{TEXMFCONFIG} and
3031 \envname{TEXMFSYSCONFIG} to specify the trees where configuration
3032 files (user or system, respectively) are found. Thus, you may
3033 need to move personal versions of \filename{fmtutil.cnf} and
3034 \filename{updmap.cfg} to these places; another option is to
3035 redefine \envname{TEXMFCONFIG} or \envname{TEXMFSYSCONFIG} in
3036 \filename{texmf.cnf}. In any case the real location of these files
3037 and the values of \envname{TEXMFCONFIG} and \envname{TEXMFSYSCONFIG}
3038 must agree.
3039 See section~\ref{sec:texmftrees}, \p.\pageref{sec:texmftrees}.
3040
3041 \item Last year, we kept \verb|\pdfoutput| and other primitives undefined
3042 for \dvi\ output, even though the \cmdname{pdfetex} program was
3043 being used. This year, as promised, we undid that compatibility
3044 measure. So if your document uses \verb|\ifx\pdfoutput\undefined|
3045 to test if PDF is being output, it will need to be changed. You
3046 can use the package \pkgname{ifpdf.sty} (which works under both
3047 plain \TeX\ and \LaTeX) to do this, or steal its logic.
3048
3049 \item Last year, we changed most formats to output (8-bit) characters as
3050 themselves (see previous section). The new TCX file
3051 \filename{empty.tcx} now provides an easier way to get the
3052 original \verb|^^| notation if you so desire, as in:
3053 \begin{verbatim}
3054 latex --translate-file=empty.tcx yourfile.tex
3055 \end{verbatim}
3056
3057 \item The new program \cmdname{dvipdfmx} is included for translation of
3058 DVI to PDF; this is an actively maintained update of
3059 \cmdname{dvipdfm} (which is also still available for now, though
3060 no longer recommended).
3061
3062 \item The new programs \cmdname{pdfopen} and \cmdname{pdfclose} are included
3063 to allow reloading of pdf files in the Adobe Acrobat Reader without
3064 restarting the program. (Other pdf readers, notably \cmdname{xpdf},
3065 \cmdname{gv}, and \cmdname{gsview}, have never suffered from this
3066 problem.)
3067
3068 \item For consistency, the variables \envname{HOMETEXMF} and
3069 \envname{VARTEXMF} have been renamed to \envname{TEXMFHOME} and
3070 \envname{TEXMFSYSVAR}, respectively. There is also
3071 \envname{TEXMFVAR}, which is by default user-specific. See the
3072 first point above.
3073
3074 \end{itemize}
3075
3076
3077 \subsubsection{2006--2007}
3078
3079 In 2006--2007, the major new addition to \TL{} was the \XeTeX{} program,
3080 available as the \texttt{xetex} and \texttt{xelatex} programs; see
3081 \url{http://scripts.sil.org/xetex}.
3082
3083 MetaPost also received a notable update, with more planned for the
3084 future (\url{http://tug.org/metapost/articles}), likewise pdf\TeX{}
3085 (\url{http://tug.org/applications/pdftex}).
3086
3087 The \TeX\ \filename{.fmt} (high-speed format) and the similar files for
3088 MetaPost and \MF\ are now stored in subdirectories of \dirname{texmf/web2c},
3089 instead of in the directory itself (although the directory is still
3090 searched, for the sake of existing \filename{.fmt}'s). The
3091 subdirectories are named for the `engine' in use, such as \filename{tex}
3092 or \filename{pdftex} or \filename{xetex}. This change should be
3093 invisible in normal use.
3094
3095 The (plain) \texttt{tex} program no longer reads \texttt{\%\&} first
3096 lines to determine what format to run; it is the pure Knuthian \TeX.
3097 (\LaTeX\ and everything else do still read \texttt{\%\&} lines).
3098
3099 Of course the year also saw (the usual) hundreds of other updates to
3100 packages and programs. As usual, please check \acro{CTAN}
3101 (\url{http://mirror.ctan.org}) for updates.
3102
3103 Internally, the source tree is now stored in Subversion, with a standard
3104 web interface for viewing the tree, as linked from our home page.
3105 Although not visible in the final distribution, we expect this will
3106 provide a stable development foundation for future years.
3107
3108 Finally, in May 2006 Thomas Esser announced that he would no longer be
3109 updating te\TeX{} (\url{http://tug.org/tetex}). As a result, there was
3110 been a surge of interest in \TL{}, especially among \GNU/Linux
3111 distributors. (There is a new \texttt{tetex} installation scheme in
3112 \TL{}, which provides an approximate equivalent.) We hope this will
3113 eventually translate to improvements in the \TeX\ environment for
3114 everyone.
3115
3116 \subsubsection{2008}
3117
3118 In 2008, the entire \TL{} infrastructure was redesigned and
3119 reimplemented. Complete information about an installation is now stored
3120 in a plain text file \filename{tlpkg/texlive.tlpdb}.
3121
3122 Among other things, this finally makes possible upgrading a \TL{}
3123 installation over the Internet after the initial installation, a feature
3124 MiK\TeX\ has provided for many years. We expect to regularly update new
3125 packages as they are released to \CTAN.
3126
3127 The major new engine Lua\TeX\ (\url{http://luatex.org}) is included;
3128 besides a new level of flexibility in typesetting, this provides an
3129 excellent scripting language for use both inside and outside of \TeX\
3130 documents.
3131
3132 Support among Windows and the Unix-based platforms is now much more
3133 uniform. In particular, most Perl and Lua scripts are now available on
3134 Windows, using the Perl internally distributed with \TL.
3135
3136 The new \cmdname{tlmgr} script (section~\ref{sec:tlmgr}) is the
3137 general interface for managing \TL{} after the initial installation.
3138 It handles package updates and consequent regeneration of formats, map
3139 files, and language files, optionally including local additions.
3140
3141 With the advent of \cmdname{tlmgr}, the \cmdname{texconfig} actions to
3142 edit the format and hyphenation configuration files are now disabled.
3143
3144 The \cmdname{xindy} indexing program
3145 (\url{http://xindy.sourceforge.net/}) is now included on most platforms.
3146
3147 The \cmdname{kpsewhich} tool can now report all matches for a given file
3148 (option \optname{--all}) and limit matches to a given subdirectory
3149 (option \optname{--subdir}).
3150
3151 The \cmdname{dvipdfmx} program now includes functionality to extract
3152 bounding box information, via the command name \cmdname{extractbb}; this
3153 was one of the last features provided by \cmdname{dvipdfm} not in
3154 \cmdname{dvipdfmx}.
3155
3156 The font aliases \filename{Times-Roman}, \filename{Helvetica}, and so on
3157 have been removed. Different packages expected them to behave
3158 differently (in particular, to have different encodings), and there was
3159 no good way to resolve this.
3160
3161 The \pkgname{platex} format has been removed, to resolve a name conflict
3162 with a completely different Japanese \pkgname{platex}; the
3163 \pkgname{polski} package is now the main Polish support.
3164
3165 Internally, the \web\ string pool files are now compiled into the
3166 binaries, to ease upgrades.
3167
3168 Finally, the changes made by Donald Knuth in his `\TeX\ tuneup of 2008'
3169 are included in this release. See
3170 \url{http://tug.org/TUGboat/Articles/tb29-2/tb92knut.pdf}.
3171
3172 \subsubsection{2009}
3173
3174 In 2009, the default output format for Lua\AllTeX\ is now PDF, to take
3175 advantage of Lua\TeX's OpenType support, et al. New executables named
3176 \code{dviluatex} and \code{dvilualatex} run Lua\TeX\ with DVI output.
3177 The Lua\TeX\ home page is \url{http://luatex.org}.
3178
3179 The original Omega engine and Lambda format have been excised, after
3180 discussions with the Omega authors. The updated Aleph and Lamed remain,
3181 as do the Omega utilities.
3182
3183 A new release of the AMS \TypeI\ fonts is included, including Computer
3184 Modern: a few shape changes made over the years by Knuth in the Metafont
3185 sources have been integrated, and the hinting has been updated. The
3186 Euler fonts have been thoroughly reshaped by Hermann Zapf (see
3187 \url{http://tug.org/TUGboat/Articles/tb29-2/tb92hagen-euler.pdf}). In
3188 all cases, the metrics remain unchanged. The AMS fonts home page is
3189 \url{http://www.ams.org/tex/amsfonts.html}.
3190
3191 The new GUI front end \TeX{}works is included for Windows, and also in
3192 Mac\TeX. For other platforms, and more information, see the \TeX{}works
3193 home page, \url{http://tug.org/texworks}. It is a cross-platform front
3194 end inspired by the \MacOSX\ TeXShop editor, aiming at ease-of-use.
3195
3196 The graphics program Asymptote is included for several platforms. This
3197 implements a text-based graphics description language vaguely akin to
3198 MetaPost, but with advanced 3D support and other features. Its home
3199 page is \url{http://asymptote.sourceforge.net}.
3200
3201 The separate \code{dvipdfm} program has been replaced by
3202 \code{dvipdfmx}, which operates in a special compatibility mode under
3203 that name. \code{dvipdfmx} includes \acro{CJK} support and has
3204 accumulated many other fixes over the years since the last
3205 \code{dvipdfm} release. The DVIPDFMx home page is
3206 \url{http://project.ktug.or.kr/dvipdfmx}.
3207
3208 Executables for the \pkgname{cygwin} and \pkgname{i386-netbsd} platforms
3209 are now included, while we were advised that Open\acro{BSD} users get
3210 \TeX\ through their package systems, plus there were difficulties in
3211 making binaries that have a chance of working on more than one version.
3212
3213 A miscellany of smaller changes: we now use \pkgname{xz} compression,
3214 the stable replacement for \pkgname{lzma}
3215 (\url{http://tukaani.org/xz/}); a literal |$| is allowed in filenames
3216 when it does not introduce a known variable name; the Kpathsea library
3217 is now multi-threaded (made use of in MetaPost); the entire \TL{} build
3218 is now based on Automake.
3219
3220 Final note on the past: all releases of \TL{}, along with ancillary
3221 material such as \CD\ labels, are available at
3222 \url{ftp://tug.org/historic/systems/texlive}.
3223
3224
3225 \subsubsection{2010}
3226 \label{sec:2010news} % keep with 2010
3227
3228 In 2010, the default version for PDF output is now 1.5, enabling more
3229 compression. This applies to all the \TeX\ engines when used to produce
3230 PDF and to \code{dvipdfmx}. Loading the \pkgname{pdf14} \LaTeX\ package
3231 changes back to PDF~1.4, or set |\pdfminorversion=4|.
3232
3233 pdf\AllTeX\ now \emph{automatically} converts a requested Encapsulated
3234 PostScript (EPS) file to PDF, via the \pkgname{epstopdf} package, when
3235 and if the \LaTeX\ \code{graphics.cfg} configuration file is loaded, and
3236 PDF is being output. The default options are intended to eliminate any
3237 chance of hand-created PDF files being overwritten, but you can also
3238 prevent \code{epstopdf} from being loaded at all by putting
3239 |\newcommand{\DoNotLoadEpstopdf}{}| (or |\def...|) before the
3240 \cs{documentclass} declaration. It is also not loaded if the
3241 \pkgname{pst-pdf} package is used. For more details, see the
3242 \pkgname{epstopdf} package documentation
3243 (\url{http://ctan.org/pkg/epstopdf-pkg}).
3244
3245 A related change is that execution of a very few external commands from
3246 \TeX, via the \cs{write18} feature, is now enabled by default. These
3247 are commands are \code{repstopdf}, \code{makeindex}, \code{kpsewhich},
3248 \code{bibtex}, and \code{bibtex8}; the list is defined in
3249 \code{texmf.cnf}. Environments which must disallow all such external
3250 commands can deselect this option in the installer (see
3251 section~\ref{sec:options}), or override the value after installation by
3252 running |tlmgr conf texmf shell_escape 0|.
3253
3254 Yet another related change is that \BibTeX\ and Makeindex now refuse to
3255 write their output files to an arbitrary directory (like \TeX\ itself),
3256 by default. This is so they can now be enabled for use by the
3257 restricted \cs{write18}. To change this, the \envname{TEXMFOUTPUT}
3258 environment variable can be set, or the |openout_any| setting changed.
3259
3260 \XeTeX\ now supports margin kerning along the same lines as pdf\TeX.
3261 (Font expansion is not presently supported.)
3262
3263 By default, \prog{tlmgr} now saves one backup of each package updated
3264 (\code{tlmgr option autobackup 1}), so broken packages updates can be
3265 easily reverted with \code{tlmgr restore}. If you do post-install
3266 updates, and don't have the disk space for the backups, run \code{tlmgr
3267 option autobackup 0}.
3268
3269 New programs included: the p\TeX\ engine and related utilities for
3270 typesetting Japanese; the \BibTeX{}U program for Unicode-enabled
3271 \BibTeX; the \prog{chktex} utility
3272 (\url{http://baruch.ev-en.org/proj/chktex}) for checking \AllTeX\
3273 documents; the \prog{dvisvgm} (\url{http://dvisvgm.sourceforge.net})
3274 DVI-to-SVG translator.
3275
3276 Executables for these new platforms are now included: \code{amd64-freebsd},
3277 \code{amd64-kfreebsd}, \code{i386-freebsd}, \code{i386-kfreebsd},
3278 \code{x86\_64-darwin}, \code{x86\_64-solaris}.
3279
3280 A change in \TL{} 2009 that we failed to note: numerous \TeX4ht-related
3281 executables (\url{http://tug.org/tex4ht}) were removed from the binary
3282 directories. The generic \code{mk4ht} program can be used to run any of
3283 the various \code{tex4ht} combinations.
3284
3285 Finally, the \TL{} release on the \TK\ \DVD\ can no longer be run live
3286 (oddly enough). A single \DVD\ no longer has enough room. One
3287 beneficial side effect is that installation from the physical \DVD\ is
3288 much faster.
3289
3290 \subsubsection{2011}
3291
3292 The \MacOSX\ binaries (\code{universal-darwin} and
3293 \code{x86\_64-darwin}) now work only on Leopard or later; Panther and
3294 Tiger are no longer supported.
3295
3296 The \code{biber} program for bibliography processing is included on
3297 common platforms. Its development is closely coupled with the
3298 \code{biblatex} package, which completely reimplements the
3299 bibliographical facilities provided by LaTeX.
3300
3301 The MetaPost (\code{mpost}) program no longer creates or uses
3302 \code{.mem} files. The needed files, such as \code{plain.mp}, are
3303 simply read on every run. This is related to supporting MetaPost as a
3304 library, which is another significant though not user-visible change.
3305
3306 The \code{updmap} implementation in Perl, previously used only on
3307 Windows, has been revamped and is now used on all platforms. There
3308 shouldn't be any user-visible changes as a result, except that it runs
3309 much faster.
3310
3311 The \cmdname{initex} and \cmdname{inimf} programs were restored (but no
3312 other \cmdname{ini*} variants).
3313
3314 %
3315 \subsubsection{2012}
3316
3317 \code{tlmgr} supports updates from multiple network repositories. The
3318 section on multiple repositories in the \code{tlmgr help} output has
3319 more.
3320
3321 The parameter \cs{XeTeXdashbreakstate} is set to~1 by default, for both
3322 \code{xetex} and \code{xelatex}. This allows line breaks after
3323 em-dashes and en-dashes, which has always been the behavior of plain
3324 \TeX, \LaTeX, Lua\TeX, etc. Existing \XeTeX\ documents which must
3325 retain perfect line-break compatibility will need to set
3326 \cs{XeTeXdashbreakstate} to~0 explicitly.
3327
3328 The output files generated by \code{pdftex} and \code{dvips}, among
3329 others, can now exceed 2gb.
3330
3331 The 35 standard PostScript fonts are included in the output of
3332 \code{dvips} by default, since so many different versions of them are
3333 extant.
3334
3335 In the restricted \cs{write18} execution mode, set by default,
3336 \code{mpost} is now an allowed program.
3337
3338 A \code{texmf.cnf} file is also found in \filename{../texmf-local},
3339 e.g., \filename{/usr/local/texlive/texmf-local/web2c/texmf.cnf}, if it
3340 exists.
3341
3342 The \code{updmap} script reads a per-tree \code{updmap.cfg} instead of
3343 one global config. This change should be invisible, unless you edited
3344 your updmap.cfg's directly. The \verb|updmap --help| output has more.
3345
3346 Platforms: \pkgname{armel-linux} and \pkgname{mipsel-linux} added;
3347 \pkgname{sparc-linux} and \pkgname{i386-netbsd} are no longer in the
3348 main distribution.
3349
3350
3351 \subsubsection{2013}
3352 Distribution layout: the top-level \code{texmf/} directory has been
3353 merged into \code{texmf-dist/}, for simplicity. Both the
3354 \code{TEXMFMAIN} and \code{TEXMFDIST} Kpathsea variables now point to
3355 \code{texmf-dist}.
3356
3357 Many small language collections have been merged together, to simplify
3358 installation.
3359
3360 \MP: native support for PNG output and floating-point (IEEE double) has
3361 been added.
3362
3363 Lua\TeX: updated to Lua 5.2, and includes a new library
3364 (\code{pdfscanner}) to process external PDF page content, among much
3365 else (see its web pages).
3366
3367 \XeTeX\ (also see its web pages for more):
3368 \begin{itemize}
3369 \item The HarfBuzz library now used for font layout instead of
3370 ICU. (ICU is still used to support input encodings, bidirectionality,
3371 and the optional Unicode line breaking.)
3372 \item Graphite2 and HarfBuzz are used instead of SilGraphite for Graphite
3373 layout.
3374 \item On Macs, Core Text is used instead of the (deprecated) ATSUI.
3375 \item Prefer TrueType/OpenType fonts to Type1 when the names are the same.
3376 \item Fix occasional mismatch in font finding between \XeTeX\ and
3377 \code{xdvipdfmx}.
3378 \item Support OpenType math cut-ins.
3379 \end{itemize}
3380
3381 \cmdname{xdvi}: now uses FreeType instead of \code{t1lib} for rendering.
3382
3383 \pkgname{microtype.sty}: some support for \XeTeX\ (protrusion) and
3384 Lua\TeX\ (protrusion, font expansion, tracking), among other
3385 enhancements.
3386
3387 \cmdname{tlmgr}: new \code{pinning} action to ease configuring multiple
3388 repositories; that section in \verb|tlmgr --help| has more, online at
3389 \url{http://tug.org/texlive/doc/tlmgr.html#MULTIPLE-REPOSITORIES}.
3390
3391 Platforms: \pkgname{armhf-linux}, \pkgname{mips-irix},
3392 \pkgname{i386-netbsd}, and \pkgname{amd64-netbsd} added or revived;
3393 \pkgname{powerpc-aix} removed.
3394
3395
3396 \htmlanchor{news}
3397 \subsection{Present---2014}
3398 \label{sec:tlcurrent}
3399
3400 2014 saw another \TeX\ tune-up from Knuth; this affected all engines,
3401 but the only visible change likely is the restoration of the
3402 \code{preloaded format} string on the banner line. Per Knuth, this now
3403 reflects the format that \emph{would} be loaded by default, rather than
3404 an undumped format that is actually preloaded in the binary; it may be
3405 overridden in various ways.
3406
3407 pdf\TeX: new warning-suppression parameter
3408 \cs{pdfsuppresswarningpagegroup}; new primitives for fake interword
3409 spaces to help with \acro{PDF} text reflowing: \cs{pdfinterwordspaceon},
3410 \cs{pdfinterwordspaceoff}, \cs{pdffakespace}.
3411
3412 Lua\TeX: Notable changes and fixes were made to font loading and
3413 hyphenation. The biggest addition is a new engine variant,
3414 \code{luajittex} (\url{http://foundry.supelec.fr/projects/luajittex})
3415 and its siblings \code{texluajit} and \code{texluajitc}. This uses a
3416 just-in-time Lua compiler (detailed TUGboat article at
3417 \url{http://tug.org/TUGboat/tb34-1/tb106scarso.pdf}). \code{luajittex} is
3418 still in development, is not available on all platforms, and is
3419 considerably less stable than \code{luatex}. Neither we nor its
3420 developers recommend using it except for the specific purpose of
3421 experimenting with jit on Lua code.
3422
3423 \XeTeX: The same image formats are now supported on all platforms
3424 (including Mac); avoid Unicode compatibility decomposition fallback (but
3425 not other variants); prefer OpenType to Graphite fonts, for
3426 compatibility with previous \XeTeX\ versions.
3427
3428 \MP: A new numbersystem \code{decimal} is supported, along with a
3429 companion internal \code{numberprecision}; a new definition of
3430 \code{drawdot} in \filename{plain.mp}, per Knuth; bug fixes in
3431 \acro{SVG} and \acro{PNG} output, among others.
3432
3433 The \cmdname{pstopdf} Con\TeX{}t utility will be removed as a standalone
3434 command at some point after the release, due to conflicts with OS
3435 utilities of the same name. It can still (and now) be invoked as
3436 \code{mtxrun --script pstopdf}.
3437
3438 \cmdname{psutils} has been substantially revised by a new maintainer.
3439 As a result, several seldom-used utilities (\code{fix*}, \code{getafm},
3440 \code{psmerge}, \code{showchar}) are now only in the \dirname{scripts/}
3441 directory rather than being user-level executables (this can be reversed
3442 if it turns out to be problematic). A new script, \code{psjoin}, has
3443 been added.
3444
3445 The Mac\TeX\ redistribution of \TeX\ Live (section~\ref{sec:macosx}) no
3446 longer includes the optional Mac-only packages for the Latin Modern and
3447 \TeX\ Gyre fonts, since it is easy enough for individual users to make
3448 them available to the system. The \cmdname{convert} program from
3449 ImageMagick has also been excised, since \TeX4ht (specifically
3450 \code{tex4ht.env}) now uses Ghostscript directly.
3451
3452 The \pkgname{langcjk} collection for Chinese, Japanese, and Korean
3453 support has been split into individual language collections for the sake
3454 of more moderate sizes.
3455
3456 Platforms: \pkgname{x86\_64-cygwin} added, \pkgname{mips-irix} removed;
3457 Microsoft no longer supports Windows XP, so our programs may start
3458 failing there at any time.
3459
3460 Support for some additional platforms is available as custom binaries
3461 (\url{http://tug.org/texlive/custom-bin.html}). In addition, some
3462 platforms are omitted from the \DVD\ (simply to save space), but can be
3463 installed normally over the net.
3464
3465
3466 \subsection{Future}
3467
3468 \emph{\TL{} is not perfect!} (And never will be.) We intend to
3469 continue to release new versions, and would like to provide more help
3470 material, more utilities, more installation programs, and (of course) an
3471 ever-improved and better-checked tree of macros and fonts. This work is
3472 all done by volunteers in their spare time, and so there is always more
3473 to do. Please see \url{http://tug.org/texlive/contribute.html}.
3474
3475 Please send corrections, suggestions, and offers of help to:
3476 \begin{quote}
3477 \email{[email protected]} \\
3478 \url{http://tug.org/texlive}
3479 \end{quote}
3480
3481 \medskip
3482 \noindent \textsl{Happy \TeX ing!}
3483
3484 \end{document}