This document describes the main features of the TEX Live software distribution — TEX and friends for GNU/Linux and other Unix flavors, Mac OS X, and (32-bit) Windows systems. (Warning: it is not especially useful for older Mac or MS-DOS systems.)
TEX Live includes executables for TEX, LaTeX2e, ConTEXt, Metafont, MetaPost, BibTeX and many other programs; an extensive collection of macros, fonts and documentation; and support for typesetting in many different scripts from around the world. It is part of the even larger TEX Collection (briefly described below in section 2, p. 6). Both are cooperative efforts by the TEX user groups.
For newer versions of the packages included here, please check CTAN: http://www.ctan.org.
For a brief summary of the major changes in this edition of TEX Live, see the end of the document, section 10 (p. 68).
You can use TEX Live in three principal ways:
All of these are described in detail in the OS-specific installation sections following, but here is a quick start:
The TEX community is both active and friendly, and virtually all serious questions end up getting answered. However, the support is informal, done by volunteers and casual readers, so it’s especially important that you do your homework before asking. (If you prefer guaranteed commercial support, you can forego TEX Live completely and purchase a vendor’s system; http://tug.org/interest.html#vendors has a list.)
Here is a list of resources, approximately in the order we recommend using them:
The other side of the coin is helping others who have questions. Both comp.text.tex and texhax are open to anyone, so feel free to join, start reading, and help out where you can. Welcome to TEX!
This section describes the structure and contents of TEX Live and the TEX Collection of which it is a part.
Space limitations of CD-ROM format have forced us to divide TEX Collection into several distributions, as follows.
CTAN, protext, MacTEX, and texmf-extra do not follow the same copying conditions as TEX Live, so be careful when redistributing or modifying.
ProTEXt is provided as both the top level of the live DVD and on its own CD (for those who cannot use the DVD).
You can tell which type of distribution you’re in by looking for a 00type.TL file at the top of the TEX Live directory. This file also contains the TEX Live release date.
Naturally, each user group chooses what to distribute to its own members.
Here is a brief listing and description of the top level directories in the TEX Live distribution. On the live DVD, the entire TEX Live hierarchy is in a subdirectory texliveYYYY, not at the top level of the disc.
| bin | The TEX system programs, arranged by platform. |
| source | The source of all programs, including the main Web2C TEX and Metafont distributions. These are stored in a bzip2-compressed tar archive. |
| setuptl | Installation programs for Linux and Windows. |
| support | Assorted auxiliary packages and programs. These are not installed automatically. This includes assorted editors and TEX shells. |
| texmf | Tree for the programs, along with their support files and documentation. Does not include TEX formats and packages. (TEXMFMAIN in the next section.) |
| texmf-dist | The main tree of formats and packages. (TEXMFDIST in the next section.) |
| texmf-doc | Tree for self-contained pure documentation, arranged by language. |
| texmf-var | Tree for files automatically generated and stored. (TEXMFSYSVAR in the next section.) |
In addition to the directories above, the installation scripts and README files (in various languages) are at the top level of the distribution.
The texmf-doc directory contains only documentation, but it does not contain all the documentation. The documentation for the programs (manuals, man pages, Info files) is in texmf/doc, since the programs are in texmf. Similarly, the documentation for TEX packages and formats is in texmf-dist/doc. You can use the texdoc or texdoctk programs to find any documentation wherever it’s located. The comprehensive links in the top-level file doc.html may also be helpful.
This section lists all predefined variables specifying texmf trees used by the system, and their intended purpose. The command texconfig conf shows you the values of these variables, so that you can easily find out how they map to directory names in your installation.
The tree which holds vital parts of the system such as helper scripts (e.g., web2c/mktexdir), pool files and other support files.
The tree which holds the main set of macro packages, fonts, etc., as originally distributed.
The tree which administrators can use for system-wide installation of additional or updated macros, fonts, etc.
The tree which users can use for their own individual installations of additional or updated macros, fonts, etc. The expansion of this variable depends on $HOME by default, which dynamically adjusts for each user to an individual directory.
The tree used by teTEX’s utilities texconfig, updmap, and fmtutil to store modified configuration data. Under $HOME by default.
The tree used by teTEX’s utilities texconfig-sys, updmap-sys, and fmtutil-sys to store modified configuration data.
The tree used by texconfig, updmap and fmtutil to store (cached) runtime data such as format files and generated map files. Under $HOME by default.
The tree used by texconfig-sys, updmap-sys and fmtutil-sys to store (cached) runtime data such as format files and generated map files.
For more discussion of texconfig and related utilities, please see section 4.1, p. 28.
TEX Live contains several extended versions of TEX:
Here are a few other commonly-used programs included in TEX Live:
bibliography support.
index support.
convert DVI to PostScript.
DVI previewer for the X Window System.
DVI drive for the HP LaserJet family.
convert DVI to/from plain text.
cut and paste pages from DVI files.
convert DVI to PDF, an alternative approach to pdfTEX (mentioned above). See the ps4pdf and pdftricks packages for still more alternatives.
PostScript utilities.
LATEX syntax checker.
ConTEXt and PDF processor.
TEX to HTML converter.
As introduced in section 1.1 (p. 4), TEX Live has three principal uses:
The following sections describes the Unix-specific procedures for each of these.
|
Warning: The TEX Collection CDs and DVD are in ISO 9660 (High Sierra) format, with Rock Ridge (and Joliet, for Windows) extensions. Therefore, in order to take full advantage of the TEX Collection under Unix, your system needs to be able to use the Rock Ridge extensions. Please consult the documentation for your mount command to see how to do this. If you have several different machines on a local network, you may be able to mount the discs on one which does support Rock Ridge, and use this with the others. Modern systems should be able to use the discs without problems. If troubles, let us know. The discussion below assumes you have been able to mount the CDs with full Rock Ridge compatibility.
|
It is possible to use the TEX system directly from the live DVD, without installing the distribution to disk. (Thus the name TEX ‘Live’, in fact.) It is not possible to run TEX directly from the other CDs (see section 2.1, p. 6). To start, you mount the CD or DVD, with Rock Ridge extensions enabled. The exact command to do this varies from system to system; the following works under Linux, except the name of the device (/dev/cdrom, here) may vary. (All our examples will use > as the shell prompt; user input is underlined.)
Change the current directory to the mount point:
Under Mac OS X, the directory is typically under /Volumes, and the media will be mounted automatically. Run the installation script install-tl.sh:
After various greeting messages and a list of the main menu options, the installation will ask you to enter a command. Do this by typing the desired character and hitting return; don’t type the angle brackets shown. Either uppercase or lowercase is ok; we’ll use lowercase in our examples.
For running live, our first command will be d and then the subcommand 1 to set directories. Even in this case, we must choose a directory on the local disk to place files that the TEX system itself generates, such as fonts and formats, and also to provide a place for updated configuration files, if need be.
We’ll use /opt/texlive2007 in this example. It’s good to include the year in the name, as these generated files are not in general compatible from release to release. (If the default value of /usr/local/texlive/2007 works for you, then you can skip this step.)
Back at the main menu, our second and last command is r, to set up for running live off the media without installing to disk:
And we are back at the system prompt, as shown.
Next, it is necessary to alter two environment variables: PATH, to an architecture-dependent value (so that we can run the programs), and TEXMFSYSVAR, to the value specified above. See table 1 for a list of the architecture names for the different systems.
After the main installation has completed, and environment variables have been set, the last step is to run texconfig or texconfig-sys to customize your installation to your needs. This is explained in section 4.1, p. 28.
|
The syntax for setting the environment variables, and the initialization file to put them in, depends on the shell you use. If you use a Bourne-compatible shell (sh, bash, ksh, et al.), put the following into your $HOME/.profile file:
For C shell-compatible shells (csh, tcsh), put the following into your $HOME/.cshrc file:
Then log out, log back in, and test your installation (see section 4.2, p. 29).
If in doubt, please ask any local system gurus to help you with problems; for example, the way to mount the TEX Live media, which directory or directories to use, and precise details of the changes to your personal initialization files can and do vary from site to site.
It is possible, indeed typical, to install the TEX Live distribution to hard disk. This can be done from either the live or inst distributions. (See section 2.1, p. 6, for an explanation of the different distributions.)
To start, you mount the CD or DVD, with Rock Ridge extensions enabled. The exact command to do this varies from system to system; the following works under Linux, except the name of the device (/dev/cdrom, here) may vary. (All our examples will use > as the shell prompt; user input is underlined.)
Change the current directory to the mount point:
Under Mac OS X, the directory is typically under /Volumes, and the media will be mounted automatically. Run the installation script install-tl.sh:
After various greeting messages and a list of the main menu options, the installation will ask you to enter a command. Do this by typing the desired character and hitting return; don’t type the angle brackets shown. Either uppercase or lowercase is ok; we’ll use lowercase in our examples.
Table 2 briefly lists the options in the main menu. The order in which you select the options makes little difference, except that i must be last. It’s reasonable to go through them in the order presented here.
|
Here are further details on each option.
p – Current platform. Since the installation script automatically guesses which platform you’re running on, it is usually unnecessary to use this option. It’s there in case you need to override the automatic detection.
b – Binary architectures. By default, only the binaries for your current platform will be installed. From this menu, you can select installation of binaries for other architectures as well (or omit installing the current platform). This can be useful if you are sharing a TEX tree across a network of heterogenous machines. For a list of the supported architectures, see table 1, p. 16.
s – Base installation scheme. From this menu, you can choose an overall set of package collections, called a “scheme”. The default full scheme installs everything available, but you can also choose the basic scheme for a minimal system, or medium to get something in between. There are also specific sets for Omega and XML.
c – Individual collections. From this menu, you can override the scheme’s set of collections to install. Collections are one level more detailed than schemes — collections consist of one or more packages, where packages (the lowest level grouping in TEX Live) contain the actual TEX macro files, font families, and so on. In this menu, selection letters are case-sensitive.
l – Language collections. This menu has the same basic purpose as c, to override the collection set in the chosen scheme. In this case, the collections are specifically for different languages. Selection letters are case-sensitive here too. Here is a list of the language collections in TEX Live:
| (some) African scripts | Arabic | Armenian | Chinese Japanese Korean |
| Croatian | Cyrillic | Czech/Slovak | Danish |
| Dutch | Finnish | French | German |
| Greek | Hebrew | Hungarian | Indic |
| Italian | Latin | Manju | Mongolian |
| Norwegian | Polish | Portuguese | Spanish |
| Swedish | Tibetan | UK English | Vietnamese |
Language collections typically include fonts, macros, hyphenation patterns, and other support files. (For instance, frenchle.sty is installed if you select the French collection.) In addition, installing a language collection will alter the language.dat configuration file controlling which hyphenation patterns are loaded.
d – Installation directories. Three directories can be changed here:
The top-level directory under which everything else will be installed. The default value is /usr/local/texlive/2007, and is often changed. We recommend including the year in the name, to keep different releases of TEX Live separate. (You may wish to make a version-independent name such /usr/local/texlive via a symbolic link, which you can then update after testing the new release.)
Under Mac OS X, the usual frontends look for TEX in /usr/local/teTeX, so you may wish to install TEX Live there.
This tree is where the TEX system (not as part of the initial installation, but rather as time goes by) puts non-version-specific files, primarily fonts. The default value is /usr/local/texlive/texmf-local, independent of the current TEX Live release, because it’s also the recommended location to put any local packages or configuration settings.
This tree is where texconfig-sys puts files that are version-specific. The default value is TEXDIR/texmf-var, and there’s generally no reason to change it. There is also TEXMFSYSCONFIG, which is where texconfig looks for modified configuration data. See section 4.1, p. 28 for more information.
o – Other options. From this menu, you can select the following general options:
Specify an alternate directory for generated fonts. The default is to use the TEXMFVAR tree, as explained above. Setting this is useful if you plan to mount the main tree read-only, and therefore you need another location (perhaps host-specific) for dynamically created fonts.
Create symbolic links for the binaries, man pages, and/or GNU Info files in other locations. For example, you may wish to make the man pages available under /usr/local/man and the Info files available under /usr/local/info. (Of course you need appropriate privileges to write in the specified directories.)
It is not advisable to overwrite a TEX system that came with your system with this option. It’s intended primarily for creating the links in standard directories that are known to users, such as /usr/local/bin, which don’t already contain any TEX files.
Skip installation of the font/macro documentation tree. This is useful if you need to save space, or if you’ve previously installed the documentation elsewhere.
Skip installation of the main font/macro source tree. This is useful if you are arranging to share that tree between machines and/or architectures in some other way, such as NFS.
i – Perform installation. When you’re satisfied with your configuration options, enter i to actually do the installation from the media to your chosen locations.
After the installation completes, your next step is to include the architecture-specific subdirectory of TEXDIR/bin in your PATH, so the newly-installed programs can be found. The architecture names are listed in table 1, p. 16, or you can simply list the directory TEXDIR/bin.
The syntax for doing this, and the initialization file to use, depends on your shell. If you use a Bourne-compatible shell (sh, bash, ksh, et al.), put the following into your $HOME/.profile file:
For C shell-compatible shells (csh, tcsh), put the following into your $HOME/.cshrc file:
After the main installation has completed, and environment variables have been set, the last step is to run texconfig or texconfig-sys to customize your installation to your needs. This is explained in section 4.1, p. 28.
Here is a minimal annotated example which accepts the default directories and installs binaries for the current system only. Thus, only one command is needed, i for install. The > is the shell prompt as usual.
If your Unix system supports the manpath command (type man manpath to learn more), you can make the TEX Live manual pages available system-wide via the normal man command by editing the file /etc/manpath.config; you might need root permissions for this. With the following entry in /etc/manpath.config the TEX Live manual pages will be found at their original places within the TEX Live tree (adapt the binary path for your system architecture):
If in doubt, please ask any local system gurus to help you with problems; for example, the way to mount the TEX Live media, which directory or directories to use, and precise details of the changes to your personal initialization files can and do vary from site to site.
It is possible to override the default directories with environment variables, and then install non-interactively. Example:
The TEXLIVE_INSTALL_PREFIX variable overrides the default location of /usr/local/texlive, leaving all else unchanged—so with the above invocation, the main installation will go to /opt/texlive/2007.
In the usual Unix way, the final echo i can be replaced by any sequence of input commands via a here document, so any sequence of commands can be scripted.
Here are all the possible overrides:
Override /usr/local/texlive.
Override $TEXLIVE_INSTALL_PREFIX/2007.
Override $TEXLIVE_INSTALL_PREFIX/texmf-var.
Override $TEXLIVE_INSTALL_TEXDIR/texmf-var.
Override $HOME/texmf.
It would be better to support a standard GNU-style configure with options, instead of these environment variables. Volunteers are welcome!
You can add individual packages or collections from the current distribution to an existing non-TEX Live setup, or an earlier TEX Live installation.
To start, you mount the CD or DVD, with Rock Ridge extensions enabled. The exact command to do this varies from system to system; the following works under Linux, except the name of the device (/dev/cdrom, here) may vary. (All our examples will use > as the shell prompt; user input is underlined.)
Change the current directory to the mount point:
Under Mac OS X, the directory is typically under /Volumes, and the media will be mounted automatically.
Run the installation script install-pkg.sh (not install-tl.sh, which is intended for complete installations only):
The first set of options controls what gets read:
The individual package to work on.
The individual collection to work on.
Exclude documentation files from the operation.
Exclude source files from the operation.
Source directory to read from; defaults to the current directory. If you followed the instructions above, that will be the distribution directory, and won’t need to be changed.
The so-called ‘lists’ directory within cddir from which to read the package information. The only reason to change the default is if you’re making changes to TEX Live yourself.
What actually happens is controlled by the following options. If neither of these are specified, the default action is to install the selected files. The main destination tree is found by expanding $TEXMFMAIN with kpsewhich. You can override it by setting either the environment variable TEXMFMAIN or TEXMF.
List the files that would be installed, but don’t actually install anything.
Instead of installing the files into the TEX system, make a tar archive.
Additional options:
After installation, run texconfig init.
After installation, don’t run mktexlsr to rebuild the filename database.
Give more information as the script runs.
Here are some usage examples:
If in doubt, please ask any local system gurus to help you with problems; for example, the way to mount the TEX Live media, which directory or directories to use, and precise details of the changes to your personal initialization files can and do vary from site to site.
After the main installation is done, for any operating system, the remaining steps are to configure the system for your local needs, and perform some basic tests.
Another sort of post-installation is to acquire packages, fonts, or programs that were not included in TEX Live. The basic idea is to install such additions in the TEXMFLOCAL tree (if you installed to disk), or TEXMFSYSVAR (if you are running live). See the “Installation directories” option on p. 21.
Unfortunately, the details can and do vary widely, and so we do not attempt to address them here. Here are some external links to descriptions:
At any time after installation, you can and should use the program texconfig to configure the system to fit your local needs. It is installed in the architecture-specific subdirectory TEXDIR/bin/arch along with everything else.
If you run it without arguments, it will enter full-screen mode and allow you to view and change options interactively.
You can also run it with various command-line options. Here are some of the most common (TEX Live is configured for the A4 paper size by default):
Set default paper size for various programs and drivers (pdftex, dvips, dvipdfm, xdvi) to be US letter. The other allowable size is a4, which is the default.
Update all the TEX “filename databases”, after adding or removing files.
Show the teTEX FAQ. (See also the main TEX FAQ in texmf-doc/doc/english/FAQ-en.)
Output help information for texconfig.
Of course, texconfig can only support changing a few of the many options and configuration parameters in a TEX system. The main configuration file for the base Web2C programs is named texmf.cnf. You can find its location by running ‘kpsewhich texmf.cnf’; it contains many comments explaining the default settings and useful alternatives.
texconfig alters files in a user-specific directory, as in $HOME/.texlive2007. If you install TEX just for yourself, that is unlikely to make a difference. But if you install TEX on a multi-user system, you will want to change the configuration for the whole system. In this case, run texconfig-sys instead of texconfig.
Likewise, the updmap and fmtutil scripts were changed, to work under $HOME/.texliveYYYY. To alter system directories, use updmap-sys and fmtutil-sys.
In particular, for multi-user systems, you will probably want to pregenerate the standard formats with fmtutil-sys –missing. Otherwise, each user will end up with their own formats.
Also, if you have a personally-modified copy of fmtutil.cnf or updmap.cfg, instead of using the ones generated by installation, they must be installed in the tree referenced by the variable TEXMFSYSCONFIG.
The variables specifying the directories altered by these commands are listed in section 2.3, p. 8. You can see the actual directories by running texconfig conf, and you can change them by editing texmf.cnf.
After installing TEX Live as best you can, you naturally want to test it out, so you can start creating beautiful documents and/or fonts.
This section gives some basic procedures for testing that the new system is functional. We give Unix commands; under Mac OS X and Windows, you’re more likely to run the tests through a graphical interface, but the principles are the same.
A simpler document than sample2e, to reduce the input size if you’re having troubles.
Test if your printer introduces any offsets.
For printing font tables and tests.
Also for font tables, but using plain TEX.
The most canonical (plain) TEX test file of all. You must type ‘\bye’ to the * prompt after ‘tex story.tex’.
You can process these in the same way as we did with sample2e.tex.
If you are new to TEX, or otherwise need help with actually constructing TEX or LATEX documents, please visit http://tug.org/begin.html for some introductory resources.
The recommended way to install TEX on Mac OS X is from the MacTEX distribution, new in 2005. This is provided on the live DVD in the top-level mactex/ directory. It contains its own (native) installer for a full TEX distribution, based on a combination of teTEX and TEX Live, along with many additional applications and documentation. The project web page is http://tug.org/mactex.
If you prefer, installation of TEX under Mac OS X can also be done directly from TEX Live, using the install* scripts, as follows.
In order to run the installation scripts under Mac OS X, you need to have the bash shell installed. If you are running Mac OS X 10.2 or later, you have bash, and can proceed. If you’re running an earlier Mac OS X version, however, the default shell is zsh, which won’t work; you’ll need to get bash from the Internet, or more likely upgrade your system.
Once you have bash, the Unix installation documentation in the previous section can be followed. See section 3 on p. 10; Mac OS X-specific notes are included there where needed.
In this release of TEX Live, happily, the distribution once again has a native Windows installer, named tlpmgui.exe. (See section 2.1, p. 6, for an explanation of the different distributions.)
tlpmgui has essentially the same options as the Unix installer, only done through a GUI interface: selecting schemes, individual collections, installation directories, and so on. Section 3.2 on p. 17 describes the basic elements. It also allows some post-installation activities such as adding/removing packages, updating the filename database and building formats. Moreover, tlpmgui can setup the system for running programs directly from the DVD.
For those who like to look underneath the hood, tlpmgui uses as its “engine” a command-line Windows program named tlpm.
The Windows TEX system included in TEX Live is based on new binaries borrowed from the W32TEX distribution, kindly provided by Akira Kakuto. It also includes some older (but still working) tools made by Fabrice Popineau, and also a new dvi previewer, dviout by Toshio Oshima.
TEX Live can be installed on systems running Windows 98, ME, NT, 2K or XP. Older versions of Windows (3.1x) and MS-DOS are not supported.
Warning: Win9.x users must ensure they have enough environment space before undertaking installation. The tlpmgui.exe program won’t change the environment size for them. A few environment variables will be created and it is possible you run out of environment space. Add SHELL=<path>COMMAND.COM /E:4096 /P in the config.sys file in order to increase your environment size.
After inserting the TEX Live CD into the CD drive, autostart should activate tlpmgui. If it does not, click Start!Run, then type <drive letter>:\setuptl\tplmgui.exe (or <drive letter>:\texlive\setuptl\tplmgui.exe if you are installing from the TEX Collection DVD), where <drive letter> is the drive letter with the TEX Live CD (or TeX Collection DVD), and then click OK.
The installation window titled TeX Live installation and maintenance utility should open. It contains the following sections: Main customization, Install, Select a scheme, Select systems, Directories and Options.
By default, tlpmgui tries to detect if TEX is already installed and depending on the result starts either in fresh installation or maintenance mode. If you have TEX already installed but want to install the new version nevertheless, you can use tlpmgui –install-mode to force installation mode; but you should know what you are doing, as the new TEX Live installation will override the environment variables and other settings of the existing installation; reverting to your old installation is not automatically supported.
Diagnostic information is collected by tlpmgui in a log file which is deleted at the end of the run, along with any other temporary files. Invoking with –debug displays the names and contents of all tlpmgui temporary files in a separate window.
In the Directories section the installation drive (directory) next to the CD/DVD button should be displayed (e.g., F:/ or F:/texlive/ for the DVD), but if it is not, then click the CD/DVD button and select the CD/DVD drive, with the TEX Live CD (or TEX Collection DVD).
The directory in which you wish to install the software can be set by clicking the TLroot button. This directory will be set as TLroot environment variable for later usage.
In the Select a scheme section the desired TEX Live installation scheme should be chosen by clicking the radio button labelled with the installation scheme name (e.g., scheme-gust). Each scheme is accompanied by an Info button which, when clicked, displays a short description of the relevant scheme.
A scheme is a large set of files targeted at some kind of usage. There are generic schemes for basic, medium and full installations. The remaining ones are either targeted at certain LUGs (i.e., what GUST or GUTenberg propose for their members) or application targeted (e.g., for XML and TEX cooperation). A preselected scheme can be refined. This is done in the Main customization section by choosing additional collections from Standard collections or Language collections. For example, by clicking the Select button labelled Standard collections, additional collections like Metapost, Omega or documentation in different languages can be selected.
Wintools collection is selected by default as it contains many small programs, usually absent in Windows, which can be handy, like graphics converters: sam2p, jpeg2ps, tiff2png; (de)compression programs: bzip2, gzip, unzip, and wget which is needed for getnonfreefonts (new) utility.
Next, clicking the Select button labelled Language Collections in the Main customization section opens the Language collections window in which the installation language can be chosen by ticking the box next to the language.
Next, click the Install button in the Install section to start the installation proper process.
Note: The Perl and Ghostscript are installed only on demand. They should be installed unless they are already installed and you really know what you are doing. Both programs are required by many important tools. The PERL5LIB and GS_LIB environment variables will be set too, as well the path to Ghostscript binaries will be added to the PATH variable.
The TEX Live system needs some post-processing steps (format files generation, ls-R databases generation, environment variables, etc.). All these operations are done there, some of them can be lengthy. So please wait until you see a statement about the successfully finished installation.
The shortcut for tlpmgui (and also dviout, if installed) will be added to the menu Start!Programs!TeXLive2007.
If it is needed (Win9x/WinME), you will be asked to reboot your computer.