The T X Live Guide, 3rd edition E Sebastian Rahtz 8 History and acknowledgements 28 9 Future versions 29 A The texmf.cnf file 31 B Catalogue of Packages 40 List of Tables 1 Kpathsea file types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 2 TEX Live packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 1 Introduction This documentation describes the main features of the TEX Live 3 CD-ROM—a TEX/LATEX distribution for Unix, Windows32 and Amiga systems that includes TEX, LATEX 2ε, METAFONT, MetaPost, Makeindex, and BIBTEX; and a wide-ranging set of macros, fonts and documentation conforming to the TEX Directory Standard (TDS)—which can be used with nearly every TEX setup. This TEX package uses the Web2c (version 7.2) implementation of the programs, which tries to make TEXing as easy as possible, and takes full advantage of the efficient and highly customizable Kpathsea library from Karl Berry and Olaf Weber. It can be run either directly from the CD-ROM or installed on a hard disk. Most of the runnable systems on the CD-ROM include a large set of drivers and support programs for TEX, including dvips (PostScript driver), xdvi (X Windows previewer), dvilj (HP LaserJet driver), lacheck (LATEX syntax checker), tex4ht (TEX to HTML converter), dviconcat and dviselect, dv2dt and dt2dv (dvi to ASCII and vice versa), and Angus Duggan’s PostScript utilities. 1.1 Extensions to TEX The TEX Live runnable systems contain three experimental extensions to normal TEX: 1. ε-TEX, which adds a small but powerful set of new primitives, and the TEX--XET extensions for left to right typesetting; in default mode, ε-TEX is 100% compatible with ordinary TEX. See texmf/etex/doc/base/etex_man.tex on the CD-ROM for details. 2. pdfTEX, which can optionally write Acrobat PDF format instead of DVI; there is no formal documentation for this yet, but the file texmf/pdftex/plain/misc/example.tex shows how it is used. The LATEX hyperref package has an option ‘pdftex’, which turns on all the program features. 3. Ω (Omega), which works internally with 16-bit characters, using Unicode; this allows it to directly work with almost all the world’s scripts simultaneously. It also supports dynamically loaded ‘Ω Translation Processes’ (OTPs), which allow the user to define complex transformations to be performed on arbitrary streams of input. See texmf/doc/omega/base/doc2.tex for documentation. 2 ε-TEX is stable (version 2.0), although subsequent releases will add new functionality. pdfTEX (version 0.12h) and Ω (version 1.5) are under continual development; the versions on this CD-ROM are those current as of mid March 1998. 1.2 Other packages The following complete packages are included on the CD-ROM: • OzTEX for Macintosh. • CMacTeX for Macintosh. • Macintosh utilities (Alpha, Excalibur, etc.). • MikTeX for Windows 95. • emTeX for DOS and OS/2. • The DJGPP version of the Web2c TEX system, which works under DOS and all Windows versions. • TEX shells for Windows and DOS (Winedt, TeXtelmExtel, emTeXgi). These are provided unchanged from CTAN, and have not been integrated in any way with the rest of the CD-ROM. To use the packages, go to the relevant directory and follow the installation instructions. 2 Structure and contents of the CD-ROM The important CD-ROM top-level directories are listed below. bin The TEX family programs, arranged in separate platform directories. doc Documentation for TEX Live. cstug Material for the Czech/Slovak TEX Users Group. FAQ Frequently Asked Questions, in English, French and German. info Documentation in GNU ‘info’ format for the TEX system. man Documentation in the form of Unix man pages for the TEX system. source The source of all programs, including the main Web2c TEX and METAFONT distributions. support Various bits of TEX-related software which are not installed by default, such as MusixTEX, support programs, and a complete distribution of Ghostscript. systems Packaged TEX systems which are separate from the main TEX Live. Subdirectories in here are: amiga Extra support programs for the Amiga. macintosh The OzTEX and CMacTeX packages ready to install, plus some other utilities. msdos DOS TEX packages—djgppTEX, emTeX, and three TEX shells. 3 win32 TEX packages for Windows 95 and NT users —MikTeX, and the editor/shell WinEdt. wingut The GUTenberg TEX distribution for Windows texmf The main support tree of macros, fonts and documentation; TUG Material about the TEX Users Group. winedt A ready to run installation of WinEdt for Windows 95/NT. There are also two installation scripts for Unix systems, install-cd.sh and install-pkg.sh; we discuss them on in section refsec:install on p. 5. 2.1 The TDS tree The TEX Live texmf tree consists of various ‘collections’, each of which has a set of ‘packages’, of which there are over 400 on the CD-ROM. Normal installation allows the user to copy all of a collection to a local hard disk from the CD-ROM, but it is also possible to install just one package of a collection. The collections are: ams The American Mathematical Society macro packages and fonts. bibtex BIBTEX styles and databases. doc General guides and documentation in various formats, including HTML and PDF. dvips Support for Rokicki’s DVI-to-PostScript driver. etex Support for ε-TEX. fonts Font sources, metrics, PostScript and bitmap forms. formats Eplain, RevTEX, physxx, texsis, alatex, text1, lollipop, etc. generic Extra macros for use with any format. graphics Macro packages for graphics. lang Support for non-English languages. latex LATEX, including official tools and all LATEX 2ε contributed packages. metapost Support for MetaPost. omega Support for Ω. plain Macros for plain TEX. systems Binaries for Unix, Amiga and Win32 platforms. texlive Basic material for the distribution. Each of the collections is divided into basic (1), recommended (2) and other (3). The appendix starting on page 40 lists all the packages in alphabetical order with the collection they are found in, and a brief description. Thus all packages in collection latex1 are what one must have to get started with LATEX, packages in latex2 are recommended for most users, and latex3 contains optional packages. The directory texmf/lists contains lists of all files in each package (used by the installation programs). 4 3 Installation and use under Unix You can use the TEX Live CD-ROM in three ways: 1. You can mount the CD-ROM on your file system, adjust your PATH, and run everything off the CD-ROM; this takes very little disk space, and gives you immediate access to everything on the CD-ROM; although the performance will not be optimal, it is perfectly acceptable on, for instance, PCs running Linux. 2. You can install all or part of the system to your local hard disk; this is the best method for many people, if they have enough disk space to spare (a minimum of about 10 megabytes, or 100 megabytes for a recommended good-sized system). 3. You can install selected packages to work either with your existing TEX system or a TEX Live system you installed earlier. Each of these methods is described in more detail in the following sections. Warning: This CD-ROM is in ISO 9660 (High Sierra) format, with Rock Ridge and Joliet extensions. In order to take full advantage of the CD-ROM on a Unix system, your system needs to be able to use the Rock Ridge extensions. Please consult the documentation for your mount command to see if it is possible. If you have several different machines on a local network, see if you can mount the CD-ROM on one which does support Rock Ridge, and use this with the others. Linux, FreeBSD, Sun, SGI and DEC Alpha systems should be able to use the CD-ROM with no problems. We would appreciate receiving detailed advice from other system users who also succeed, for future versions of this documentation. The discussion below about installation assumes you have been able to mount the CD-ROM with full Rock Ridge compatibility. 3.1 Running TEX Live from the CD-ROM The organisation of Web2c means that you can run programs simply by adding the appropriate directory under bin on the CD-ROM to your PATH, and the support files will all be found with no further ado. The following shows the list of available systems and the corresponding directories. DEC Alpha (3.2 and 4.0) alpha-osf3.2 alpha-osf4.0 Amiga m68000-amigaos2.1 HP9000 HPUX 10.10 hppa11-hpux10.10 Linux (on Intel Pentium) i386-linux SGI IRIX (5.3 and 6.2) mips-irix5.3 mips-irix6.2 IBM RS 6000 AIX (3.2.5 and 4.1.1) rs6000-aix3.2.5 rs6000-aix4.1.1 Sun Sparc Sunos 4.1.3 sparc-sunos4.1.3 Sun Sparc Solaris (2.5.1 and 2.6) sparc-solaris2.5.1 sparc-solaris2.6 Windows 95 or NT (Intel machines) win32 You may worry that when you subsequently make fonts or change configuration, things will go wrong because you cannot change files on the CD-ROM. However, you can maintain a parallel, writeable, TEX 5 tree on your hard disk; this is searched before the main tree on the CD-ROM. The default location is /usr/TeX.local, but you can override this by setting the TEXMFLOCAL environment variable. Thus sh or bash users on an Intel PC running Linux can mount the TEX Live CD-ROM on /cdrom by issuing the command: >> mount -t iso9660 /dev/cdrom /cdrom Then they should include the directory containing the binaries for the given architecture into the search path by updating the PATH variable. PATH=/cdrom/bin/i386-linux:$PATH export PATH For convenience, these statements can also be entered into the .profile script. If in doubt, ask your local system support guru to help you work out how to mount your CD-ROM or which directory to use for your system. Appropriate support files will be installed on your hard disk the first time you need them. It is a good idea to immediately run the texconfig script to initialize things, and check it all works. 3.2 Installing T X Live to a hard disk E All of the necessary steps to install all or part of the distribution on your hard disk are achieved by mounting the CD-ROM, changing to the top-level directory, and typing: >> sh install-cd.sh (On some Unix systems, you may need to use sh5 or bsh.) This script works by accessing lists of collections and packages from the CD-ROM, and trying to guess what sort of computer system you are on. It should start by displaying the following: Initializing collections... Done. Counting selected collections... Done. Calculating disk space requirements for collections...Done. Initializing system packages... Done. It will then show the main control screen (Figure 1(a)), which lets you change four things: 1. the type of system you are on, or want to install for; 2. the collections you want to install, at the basic, recommended or other level; 3. the location on your hard disk to put the files; 4. some runtime behaviour features. You choose options by typing a letter or number and pressing ‘return’. In the example, a Linux ELF system has been detected, the default of all collections to recommended level has been chosen, and the default installation directory is /usr/local; note that the disk space required for the current installation configuration is also displayed. If you make a suggested setup, you need about 100 megabytes of disk 6 ===================> TeX Live installation procedure <================== ===> Note: Letters/digits in <angle brackets> indicate menu items <=== ===> for commands or configurable options <=== Proposed platform: Intel x86 with Linux (ELF) <P> over-ride system detection and choose platform <C> collections: 23 out of 33, disk space required: 176108 kB <S> systems: 1 out of 13, disk space required: 6359 kB total disk space required: 182467 kB <D> directories: TEXMFMAIN = /usr/TeX (where the main TeX system will live) TEXMFLOCAL = /var/TeX (where you will install your own styles and site changes) <O> options: [ ] alternate directory for automatically generated fonts () [ ] create symlinks in standard directories Other commands: <I> start installation, <H> help, <Q> quit (a) Main control screen Current collections setup: total size : 171901 kB ============================================================= name selection size <1> ams [recommended] 6359 kB <2> bibtex [recommended] 6584 kB <3> doc [recommended] 26531 kB <4> dvips [recommended] 563 kB <5> fonts [recommended] 21862 kB <6> formats [recommended] 1003 kB <7> generic [recommended] 501 kB <8> graphics [recommended] 10373 kB <9> lang [recommended] 3287 kB <W> metapost [recommended] 1280 kB <X> latex [recommended] 28333 kB <Y> plain [recommended] 756 kB <Z> texlive [recommended] 56523 kB SUM: 163955 kB ================================================== global commands: select <n>one / <b>asic / r<e>commended / <a>ll for all collections <R> return to platform menu <Q> quit Enter command to modify current selection: 7 (b) Selecting collections Figure 1: Examples of screens used by the installation script Collection: Fonts ==================================================== Fonts, including metrics, virtual fonts and sources ==================================================== <N> no packages <B> basic packages [ 2007 kB] <E> basic + recommended packages [ 21862 kB] <A> all packages [ 34303 kB] ==================================================== <R> return to collection menu <Q> quit Enter command: (c) Customizing a collection Figure 1: Examples of screens used by the installation script (contd.) free; however, the basic setup will only take about 10 megabytes, and you can enhance it with selected packages as you need them. Under the directory you choose for installation, the installation script will put the binaries in a subdirectory of bin, and the support tree in texmf. The options item lets you decide whether to make new fonts be created in another location (if you want the main package mounted read-only for most users), and whether to make symbolic links for the man and GNU info pages in the ‘standard’ locations. When you choose <C> for ‘collections’, you will see the display of available collections, the level of installation selected, and the disk space required (Figure 1(b)). You can set alternative levels of installation for each collection, ranging from none to all. You can either set this for all collections at once, or choose a particular collection and set its level (Figure 1(c)). When you are finished, return to the main screen, and ask the installation to start. It will take each of the collections and systems that you requested, consult the list of files on the CD-ROM, and build a master list of files to transfer. These will then be copied to your hard disk. If you installed a system, an initialization sequence is now run (creating format files, etc.). When this has finished, all you need do is add the correct subdirectory of bin in the T X installation to your path, and start using T X. E E If you want, you can move the binaries up one level, e.g. from /usr/local/bin/alpha-osf3.2 to /usr/local/bin; if you do this, however, you must edit texmf/web2c/texmf.cnf (see Appendix A) and change line 50: TEXMFMAIN = $SELFAUTOPARENT to TEXMFMAIN = $SELFAUTODIR If you move the binaries to another directory tree entirely, you need to edit TEXMFMAIN to specify the support tree explicitly, and set TEXMFCNF in your environment to $TEXMFMAIN/texmf/web2c. 8 3.3 Installing individual packages from T X Live to a hard disk E You may want to use the TEX Live CD-ROM to either update an existing setup, or add features to an earlier installation from the CD-ROM. The main installation program is intended for the first time only, and subsequently you should use the install-pkg.sh script on the CD-ROM. Run this by mounting the CD-ROM, changing to the mounted directory, and typing >> sh install-pkg.sh options The script supports nine options; the first four let you set the individual package you want to install, the whole collection (i.e., ams2), the name of the mounted CD-ROM directory, and the name of the directory containing the list files (normally these latter two will be set automatically): --package=name --collection=name --cddir=name --listdir=name What actually happens is controlled by four more switches; the first two allow you to exclude documentation or source files from the installation, the third stops the default action of running mktexlsr on completion to rebuild the file database, and the last does nothing but list the files that would be installed: --nodoc --nosrc --nohash --listonly Finally, you can specify that, instead of installing the files, the script should make a tar archive in a specified location: --archive=name Thus, if we simply wanted to see the files that make up the package fancyhdr before we installed it, our command and output would be as follows: >> sh install-pkg.sh --package=fancyhdr --listonly texmf/doc/latex/fancyhdr/fancyhdr.dvi texmf/doc/latex/fancyhdr/fancyhdr.tex texmf/lists/latex3/fancyhdr texmf/source/latex/fancyhdr/README texmf/source/latex/fancyhdr/fancyheadings.new texmf/tex/latex/fancyhdr/extramarks.sty texmf/tex/latex/fancyhdr/fancyhdr.sty texmf/tex/latex/fancyhdr/fixmarks.sty Other examples of usage are: • Install the LATEX package natbib: >> sh install-pkg.sh --package=natbib • Install the LATEX package alg with no source files and no documentation: 9 >> sh install-pkg.sh --package=alg --nosrc --nodoc • Install all the packages available in the other Plain TEX collection: >> sh install-pkg.sh --collection=plain3 • Place all files which are needed for PSTricks in a tar file in /tmp: >> sh install-pkg.sh --package=pstricks --archive=/tmp/pstricks.tar 3.4 The texconfig program After the installation program has copied all files to their final locations, you can use a program called texconfig that allows you to configure the system to fit your local needs. This can be called at any other time to change your setup, with a full-screen (which requires the dialog program) or command-line interface. It should be used for all maintenance, such as changes of installed printers, or rebuilding the file database. Both modes have help text to guide you through the facilities. 4 Installation and use under Windows This section only applies to systems running Windows 9x or NT. If you run Windows 3.1, you will have to install emTeX, DJGPP TEX, or wingut (in the top level systems directory) by hand. It is also necessary to have your Windows set up so that it uses the Microsoft Joliet extensions for reading CD-ROMs; simply look at the CD-ROM in Explorer and see whether it shows long, mixed-case, file names. If it does not, you cannot use the ready-to-run system on the CD-ROM. This Win32 TEX systems includes a new dvi previewer, Windvi, which is similar in usage to the established Unix xdvi. The documentation can be found in texmf/doc/windvi/windvi.html. 4.1 Running from the CD-ROM You can run all the TEX programs directly off the CD-ROM, and have access to all the macros and fonts immediately, at the price of a slower performance than if you install on the hard disk. To do this, you must add the bin/win32 directory of the CD-ROM to your PATH, using the Windows configuration software. Now you can run the programs at a command prompt, or use the shareware WinEdt editor, which runs the programs from convenient menus. Copy the entire winedt directory from the CD-ROM to your hard disk, and run winedt.exe from that copy. Please respect the shareware status of WinEdt and register your copy if you intend to carry on using it. 4.2 Installing to your hard disk Installation is started by running the program install.exe in the CD-ROM top level, which works by accessing lists of collections and packages from the CD-ROM. It will allow you to select the level at which each collection is installed (see section 2.1 for a description of ‘collections’ and ‘packages’, and permits you to omit the documentation and/or source segments of the packages if your disk space is 10