LaTeX Installation Guide 1 June 1997 SUMMARY ======= This file contains the installation instructions for the latest version of the LaTeX document preparation system. The rest of this document describes: * How to find out about installing LaTeX for your version of TeX. * How the installation works. * What to do if anything goes wrong. TeX experts who want to know more about how the LaTeX installation works and how it can be customized should read texpert.txt. DOCUMENTATION ============= Brief introductions to various aspects of the new LaTeX release can be found in the distributed files with names guide.tex. You will need to install the new version before you can typeset these files. A full description of the new LaTeX release (and of more than 100 packages that can be used with LaTeX) can be found in: * The LaTeX Companion, Goossens, Mittelbach and Samarin, Addison-Wesley ISBN 0-201-54199-8. The new release is also described in the second edition of: * LaTeX A Document Preparation System, Leslie Lamport, Addison-Wesley REQUIREMENTS ============ In addition to the LaTeX distribution files, you will also need the following: * a TeX system, including iniTeX (see `Your Version of TeX', below); * the file `hyphen.tex', or some other hyphenation files (see `Creating the LaTeX Format', below); * the font files (normally .tfm files) for the Computer Modern fonts, including some non-standard ones (see `Fonts needed', below); * about 6.5MB of spare disk space for use during the installation. YOUR VERSION OF TEX =================== LaTeX is based upon Donald Knuth's TeX typesetting system. This is available for almost every make of computer, from microcomputers through workstations to large main-frames. Further details about how to install LaTeX for your version of TeX may be available in a file called .txt. At present the following such files exist (at least): * amiweb2c.txt for Amiga web2c TeX on the Amiga. * cstex.txt for CS-TeX on the Atari. * decustex.txt for TeX from DECUS on VAX/VMS. * directex.txt for DirectTeX on the Macintosh. * emtex.txt for emTeX on IBM PC compatibles. * lindner.txt for Lindner's TeX on the Atari. * microtex.txt for MicroTeX (uTeX) on IBM PC compatibles. * multitex.txt for MultiTeX on the Atari. * oztex.txt for OzTeX on the Macintosh. * pastex.txt for PasTeX on the Amiga. * pctex.txt for PCTeX on IBM PC compatibles. * textures.txt for Textures on the Macintosh. * web2ctex.txt for web2c TeX on Unix platforms. * yandytex.txt for Y&YTeX on IBM PC compatibles. You should finish reading this file before reading the .txt file for your version. If there is no such file then this file alone is your installation guide. If you have bought a commercial version of TeX/LaTeX and there is no file for your system then you could ask the company which sells your version of TeX to supply one. Note to TeX implementors/suppliers: ---------------------------------- If you can supply us with a .txt file for your implementation we shall be very grateful and we shall add it to our distribution. HOW THE INSTALLATION WORKS ========================== The LaTeX installation is in five stages: * Saving any old version of LaTeX. * Unpacking the distribution (this may not be necessary). * Creating the LaTeX format. * Putting the files where LaTeX can read them. * Checking the installation. SAVING YOUR OLD VERSION OF LaTeX ================================ If you are currently using the old LaTeX version, 2.09, you may wish to save it before installing the new version of LaTeX. If it exists, the .txt file will describe in detail how to do this; in some of these files, the new version is referred to as LaTeX2e in order to clearly distinguish it from the old version. The details of how to do everything in this section will depend to a very large extent on your TeX implementation. First you should find the LaTeX format file on your system (usually called `latex.fmt' or `lplain.fmt') and rename it to `latex209.fmt'. You should then save a copy of the current LaTeX system files. These may be kept in a TeX inputs directory or folder, which is usually called something like one of these: tex\texinput tex/inputs TeX-inputs or they may be kept in a separate LaTeX inputs location, possibly a subdirectory or subfolder of the TeX inputs location, called `latex'. There are thus two possibilities, depending on whether the LaTeX inputs have been kept separate from the other TeX inputs or not. * If the LaTeX inputs are separated from the other TeX inputs, then you should make a new directory that is a copy of the whole of the LaTeX inputs directory, and call it `latex209'. * If the LaTeX inputs are kept with the other TeX inputs, then you should create a new directory called `latex209' and then copy to it any file ending with .sty from the LaTeX inputs directory. It may be possible to run both the new LaTeX and LaTeX 2.09 in parallel. To do this, you should create a `latex209' command, or menu entry, that is similar to `latex' except that: * The `latex209' format is used rather than `latex'. * The `latex209' directory is searched before the LaTeX inputs directory. The details of how to do this vary according to your system so you may find more information in a .txt file. BEFORE UNPACKING THE DISTRIBUTION ================================= Latex needs a number of files to run, for example `article.cls' contains the `article' document class. However, these files are NOT themselves the source files produced by the LaTeX3 Project Team. We write documented sources in `docstrip archive files' which can be unpacked to produce the files that LaTeX needs. For example, classes.dtx contains the documented sources for all the LaTeX document classes, including article.cls. The FIRST thing to do is to check whether you need to unpack these archive files, as follows. Before reading any further, you should check to see whether the LaTeX distribution you have contains the unpacked files. You can do this by looking to see if you have got the file latex.ltx. If you do, then you should have all the unpacked files and so you can move on to the section entitled `Creating the LaTeX format'. The unpacking will create and write files only into the current directory (or current folder, or default directory). This helps to prevent it overwriting existing files or causing problems with your system files. It is therefore sensible to carry out the installation in a directory reserved for this purpose; on a multi-user system you should ensure that you have read and write permissions for files in this directory. UNPACKING THE DISTRIBUTION ========================== The archive files are unpacked by running iniTeX on the file unpack.ins. NOTE: On relatively slow computers, this unpacking can take a long time. On a Macintosh SE it takes about 3 hours. On a Macintosh Duo 230 or a 12MHz 80286 PC it takes about 30 minutes. On a moderately busy SparcStation 10 or a fast 80486 PC it takes about 5 minutes. NOTE: Using LaTeX with old DC Fonts. ------------------------------------ By default LaTeX uses the `ec' font collection for its T1 (Cork) encoded fonts. If you are using the pre-release versions of the ec fonts known as `dc' then you could update your fonts to ec, or unpack suitable fd files for the dc fonts at this point. For versions of the dc fonts older than release 1.2 (issued during 1995) then at this point you should unpack the fd files for the old dc fonts by running plain TeX or LaTeX on the file olddc.ins For release 1.3 of the dc fonts you should unpack fd files by running plain TeX or LaTeX on the file newdc.ins You need to do this even if you have obtained the `unpacked' distribution and so have not processed the unpack.ins file described above. If this is your first installation, so you do not yet have a format, or if you are unsure of which release of the T1 encoded fonts you have, ignore this step and build the LaTeX format as described below. This will build a format using the current ec font names. The test document ltxcheck.tex will report any problems with the ec or dc fonts and report whether you need to unpack either olddc.ins or newdc.ins. CREATING THE LATEX FORMAT ========================= To create the LaTeX format, you should run iniTeX on the file `latex.ltx'. A hyphenation file such as `hyphen.tex' is read by this run so it should be accessible by iniTeX. It also needs to be able to read the `.tfm' font files for the basic fonts. These font files and hyphenation file(s) should be part of your TeX system. You should save the resulting format file `latex.fmt' in the TeX formats directory. You may also have to create and/or install a program called `latex', a `LaTeX' option to your TeX implementation, or a batch file or shell script. The details of this stage will depend on your TeX implementation; note that the name of the format file differs from that normally used in LaTeX 2.09. Note: TeX experts may wish to customize LaTeX (for example, to allow non-American hyphenation). They should read cfgguide.tex to find out how to do this. If you are still using a very old version of TeX (pre 1990) then you must now read tex2.txt. If you have the problem of running out of TeX memory then you may find that the experimental version of LaTeX described in autoload.txt wil help you. PUTTING THE FILES WHERE LaTeX CAN READ THEM =========================================== The next step in the installation of LaTeX is to move the files needed to run the system into the correct directories (or folders). These are: * the directory containing the format files. * the LaTeX inputs directory, which contains LaTeX system files. * the MakeIndex inputs directory, which contains MakeIndex files. You should move to the formats directory: * latex.fmt. You should move to the LaTeX input directory the files: * latexbug.tex, testpage.tex, lablst.tex, idx.tex, nfssfont.tex small2e.tex, sample2e.tex and docstrip.tex. and any files whose name ends with: * .cls, document class files. * .clo, document class options files. * .sty, package files. * .fd, font definition files. * .def, files of definitions which may be read by LaTeX while processing documents. * .cfg, TeX expert configuration files. You should move to the MakeIndex input directory all files whose name ends with: * .ist, MakeIndex style files. You have now installed LaTeX! GETTING A WORKING LaTeX ======================= You may now need to set up your system to use the new version of LaTeX; e.g. by configuring the environment, adding menu items, writing batch files or shell scripts. Details may be found in a .txt file for your system. CHECKING THAT THE INSTALLATION WORKED ===================================== To make sure that the installation has worked, you should run the new LaTeX on the document `ltxcheck.tex'. How this is done varies according to your system; you may find the necessary detailed instructions in a .txt file. This will produce a number of messages, each of which should be `OK'. If any of them are `BAD', then read the `PROBLEMS' section below. If all the messages are `OK' then you are finished! Fonts needed ------------ One thing that is checked by running ltxcheck.tex is the existence of certain fonts on your system. The new LaTeX format assumes that you have on your system more font files from the Computer Modern families than did previous versions. It is not essential to get all these fonts immediately but, if you do not have the .tfm files for some of them then you will get several error messages when you try to typeset any of the documentation files, such as `usrguide.tex'. Here are some examples: ! Font OML/cmm/b/it/8=cmmib8 at 8.0pt not loadable: Metric (TFM) file not found ! Font OMS/cmsy/b/n/8=cmbsy8 at 8.0pt not loadable: Metric (TFM) file not found You can, in fact, ignore all these messages (however awful they may sound) as far as typesetting the file is concerned: the results, whilst not perfect, will be little different to what was intended. However, you should install these fonts as soon as possible (they are in the sub-directory `fonts/tfm' of the LaTeX directory on CTAN). They are: cmmib5 cmmib6 cmmib7 cmmib8 cmmib9 cmbsy5 cmbsy6 cmbsy7 cmbsy8 cmbsy9 PROBLEMS ======== On most systems the installation should proceed smoothly. However, you may get some errors. `texsys.cfg': While running iniTeX on latex.ltx you may get an error message that reports a problem with texsys.cfg. If this happens then you have obtained (or produced) a texsys.cfg file that is not suitable for your system. First, if it exists read the .txt file. This may tell you how to customize the file texsys.cfg. If the .txt file does not mention texsys.cfg then you should not need a texsys.cfg file. Try deleting texsys.cfg and building the LaTeX format again. If you still get errors, try using LaTeX to typeset ltdirchk.dtx and then read this document. The details of how to do this vary according to your system so you may find more details in a .txt file. `File missing': Some of the files from the LaTeX distribution are missing. There are a number of possible reasons for this: * The files really are missing. You should get the missing files from the same place you got the rest of the distribution. If you cannot do this then you should complain to whoever gave you this distribution. * The files are present, but in the wrong directory. You should move the files to a directory that iniTeX can read. * The files are present, and in the right directory. Your iniTeX may have been set up incorrectly. You may be able to correct this, depending on your TeX implementation. See the documentation of your TeX implementation for more details. `Font missing': Some of the fonts (.tfm files) required by LaTeX are missing. As above, either you have not got the required files, or iniTeX is not able to find them. So you may need to move them or to configure iniTeX to look in the correct places. See the documentation of your TeX implementation for more details. `Out of memory': On TeX implementations with small memory, you may exhaust iniTeX's memory whilst installing LaTeX. You may be able to correct this: * Some TeX implementations allow the amount of memory allocated to TeX to be increased. See the documentation of your TeX implementation for more details. * Some iniTeX implementations allow more memory than others; so you may be able to run iniTeX on a larger machine and then move the files across to the smaller machine. * If the error happens during the unpacking of the distribution (i.e. when you run iniTeX on unpack.ins) then try running this file with normal TeX, for example plain TeX or an old version of LaTeX. If you have any problems installing LaTeX, you should: * read the .txt file, if one exists; * if this does not help, ask your local TeX guru; * if this fails, try asking a local TeX mailing list; * if this fails, run iniTeX on the file latexbug.tex, fill in the resulting bug report form, and send it to the address given in that file. CLEARING UP =========== You may now be wondering what to do with all the remaining files that are not needed to run LaTeX. This is, of course, a matter of personal taste and availability of disk space but here is some guidance. * The files with extension .dtx, together with source2e.tex, can be used to typeset the documented source code (see texpert.txt for further information). * The files with extension .fdd contain the documented sources for the font definition files. * The files ltnews.tex and ltnews.ps both contain the latest LaTeX newsletter. * The file ltx3info.tex contains information about the LaTeX3 project and how you can support it. * The files with extension .txt contain information about (amongst other things) copyright, installation, patches and bug-reports; and those with extension .err contain errata lists for various publications: see 00readme.txt for further details. * The files with names of the form guide.tex contain reference information covering only those features new to this version of LaTeX: they are not intended to be either a user guide or a complete reference for the system. * The files with extension .ltx, together with ltxcheck.tex, are used to create and test the format; therefore you should keep these if you expect to remake the format before getting the next full distribution. * The files with extension .ins are used to unpack the code from the .dtx and .fdd files. * We recommend that you keep, in the formats directory, the transcript file that was produced whilst creating the format; this file is called latex.log or latex.lis. FINALLY ======= Once you have installed LaTeX for your TeX implementation, you might like to write a .txt file explaining how you did it. If you want to do this, you should edit the file template.txt. If you would like your .txt file to be included with the LaTeX distribution, please mail it to the project at the address given in the file bugs.txt and latexbug.tex. --- Copyright 1994, 1995, 1996 The LaTeX3 Project. All rights reserved ---