% \iffalse meta-comment % % Copyright (C) 1994 by LaTeX3 project. All rights reserved. % For additional copyright information see further down in this file. % % This file is part of the LaTeX2e system (PRELIMINARY TEST RELEASE). % ------------------------------------------------------------------- % % This system is distributed in the hope that it will be useful, % but WITHOUT ANY WARRANTY; without even the implied warranty of % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. % % % IMPORTANT NOTICE: % % For error reports in case of UNCHANGED versions see readme files. % % Please do not request updates from us directly. Distribution is % done through Mail-Servers and TeX organizations. % % You are not allowed to change this file. % % You are allowed to distribute this file under the condition that % it is distributed together with all files mentioned in 00readme.l2e. % % If you receive only some of these files from someone, complain! % % You are NOT ALLOWED to distribute this file alone. You are NOT % ALLOWED to take money for the distribution or use of either this % file or a changed version, except for a nominal charge for copying % etc. % \fi LaTeX2e Installation Guide Test Version 28 January 1994 SUMMARY ======= This file contains the installation instructions for LaTeX2e, the latest version of the LaTeX document preparation system. To install LaTeX, you should: 1. Run iniTeX on unpack2e.ins, which produces the files that LaTeX needs, including latex2e.ltx. 2. Run iniTeX on latex2e.ltx, which produces the LaTeX format. 3. Put the files where LaTeX can read them. 4. Test the installation by running LaTeX on the file ltxcheck.tex. 5. Run latex2e (or plain TeX) on l2extra.ins to unpack various extra packages (ifthen, oldgerm, etc). 6. Move the files produced from l2extra.ins, as for the main LaTeX files in step 3. NOTE: LaTeX2e and LaTeX2.09 =========================== LaTeX2e is intended to completely replace the old LaTeX 2.09 system; however, during this testing phase we would recommend that, if you have an existing LaTeX 2.09 system, you keep both running. This will allow you to fall back on the old system if a bug in the new system prevents you processing a document, and more generally it will allow you to compare the behaviour of the two versions, which may be helpful when compiling bug reports. Details of how to do this on certain systems are in the section `LaTeX2e and LaTeX2.09' below. NOTE: Some parts of this document contain information specific to particular TeX systems. This does not cover all systems and may be incomplete. Updates and corrections of this information are therefore appreciated. OVERVIEW ======== The rest of this document describes: * What prerequisites you will need in order to install LaTeX. * How to create the files that LaTeX needs. * How to customize your LaTeX installation. * How to create the LaTeX format. * What to do with the created files. * How to create the LaTeX system documentation. * How to install additional packages. * What to do if anything goes wrong. PREREQUISITES ============= In order to install LaTeX, you will need: * The iniTeX application program. * The Computer Modern fonts. * The LaTeX distribution. * The file hyphen.tex. iniTeX ------ The iniTeX application should be part of every TeX distribution: * in Unix TeX (Web2C), it is a program called initex; * in emTeX, it is started by typing tex /i; * in OzTeX, you run Plain TeX to select the LaTeX2e distribution folder, then cancel your selection. Then select INITEX from the TeX pull-down menu and type the name of the file you wish to run INITEX on; * in Textures, it is the VirTeX option on the Typeset pull-down menu. Computer Modern Fonts --------------------- IniTeX needs to be able to access the .tfm files for the basic fonts. The Computer Modern fonts should be part of every TeX distribution. Computer Modern Fonts in Cork encoding -------------------------------------- The Computer Modern fonts in Cork encoding (known as `dc' fonts) can be obtained from servers and from TeX organisations. You can install LaTeX without them but they are strongly recommended. LaTeX distribution ------------------ The file manifest.l2e contains a list of all the files in the distribution. (The file you are reading is part of the LaTeX distribution.) The file hyphen.tex ------------------- IniTeX needs to be able to input some hyphenation patterns. The US-English hyphenation patterns are in the file hyphen.tex, which should be part of every TeX distribution. ============================================== Now you are ready to start the installation... If this is possible on your system, you should first put all the distributed files into an otherwise empty directory (or folder). CREATING THE LATEX FILES ======================== The LaTeX distribution comes as a number of archive files, using the `docstrip' archive system. The LaTeX files can be extracted from the archives using iniTeX (or an existing plain or LaTeX format). To extract the files, run iniTeX on the file unpack2e.ins. This will create the files that LaTeX needs to run. If you get any error messages during this installation, see the section on `Problems'. NOTE: On relatively slow computers, this unpacking can take a long time. The longest we have heard of is 3 hours!...but it is more like 5 minutes on a moderately busy Sparcstation 10. CUSTOMISATION ============= There are five places where you can customise your LaTeX installation. You can: * Specify what hyphenation rules to load by writing a lhyphen.cfg file (this will be read instead of the file lhyphen.ltx). * Specify the default fonts used by writing a fontdef.cfg file (and a similar sfontdef.cfg file for the fonts used for slides). (these will be read instead of the files fontdef.ltx and sfontdef.ltx, respectively). * Specify which fonts are preloaded in your format by writing a preload.cfg file (this will be read instead of the file preload.ltx). * Alter the behaviour of LaTeX 2.09 documents by writing a latex209.cfg file (this will be read after reading the file latex209.def). * Alter how LaTeX searches for files by editing the file texsys.cfg. These customisations are normally not necessary and you should first gain some experience with the standard system before attempting to customise it. Detailed descriptions of how to write such files can be found in these documentation files: lhyphen.dtx, fontdef.dtx, preload.dtx and dircheck.dtx. If your TeX has the `feature' that it cannot find out if a file exists anywhere other than in the current directory then you will need to edit the file texsys.cfg. Look carefully at the documentation in dircheck.dtx, which may be typeset by running LaTeX2e on dircheck.drv. It should give you examples of how to deal with this feature for your operating system. The latex209.cfg file is read in whenever LaTeX2e processes a document which begins with \documentstyle rather than \documentclass. If your LaTeX 2.09 installation had some non-standard features then you can put them in the latex209.cfg file, so that old documents can still be processed by the new system. In particular, when making the format for earlier versions of LaTeX, it stopped with a prompt `* Input any local modifications here.' just before the format was made (by issuing \dump). LaTeX2e does not allow such arbitrary modifications to the format because they can make portability of documents very difficult. If previously you did input such modifications, add them to latex209.cfg so that they will be loaded for any documents run in compatability mode. In addition you may customise the way the documentation is typeset by creating a ltxdoc.cfg file; this is described below in the section on `Documentation'. CREATING THE LATEX FORMAT ========================= One of the files created by unpack2e.ins is called latex2e.ltx. To create the LaTeX format, run iniTeX on this file. What happens next depends on your TeX implementation: * In Unix TeX, a file called latex2e.fmt is created. You should copy this to the TEXFORMATS directory. Then either make latex2e a symbolic link to virtex or, if you are also running LaTeX2.09 as `latex', create a shell script `latex2e' as described below. * In emTeX, a file called latex2e.fmt is created. You should copy this to the BTEXFMTS or TEXFMTS directory, respectively, depending on whether you are working with BigTeX or not. * In OzTeX, a dialogue box asks you where to save the LaTeX format. You should save it as LaTeX2e.fmt in the TeX-formats folder. * In Textures, a dialogue box asks you where to save the LaTeX format. you should save it as LaTeX2e.fmt in the TeX formats folder. Then you should use the Add Format... option from the File pull-down menu to add the LaTeX2e option to the Typeset pull-down menu. NOTE: This preliminary distribution creates a format called LaTeX2e. The full distribution will create a format called LaTeX, at which point the LaTeX 2.09 format will be out of date. INSTALLING THE LATEX FILES ========================== The final step in the installation of LaTeX is to move the files that LaTeX needs into a `standard input directory' where TeX can find them. NOTE: Before doing this, see the note above and the section `LaTeX2e and LaTeX2.09' below * In Unix TeX, this is a directory listed in the TEXINPUTS environment variable. (Or, if you are not also using LaTeX2.09, one of the directories specified in the default input path when TeX was compiled.) * In emTeX, it is usually something like c:\emtex\texinput. (As described below, you may wish to use a special `standard input directory' for latex2e.) * In OzTeX, it is the folder specified in your Configs file, usually TeX-inputs. (As described below, you may wish to use a special `standard input folder' for latex2e.) * In CMacTeX it is the folder specified by tex.config, usually texinputs. * In Textures, it is the TeX inputs folder in the Textures folder. The files you should move to the `standard input directory' are the files: * docstrip.tex latexbug.tex testpage.tex * slides.ltx sfontdef.ltx and any files with the following extensions: * .cls, the document class files; * .clo, the document class options files; * .sty, the package files NOTE: move these files only if the `standard input directory' is *not* also being used by LaTeX2.09; * .fd, the font definition files; * .def, files of definitions which may be read by LaTeX while processing documents; * .cfg, configuration files that you have produced. You should also move gglo.ist and gind.ist to the MakeIndex directory: * In Unix makeindex and in DOS/OS2 makeindx, this is a directory listed in the INDEXSTYLE environment variable. * In MacMakeIndex, this is the MakeIndex folder. You may want to create a directory for storing the documentation for this release. You should then move to this directory all the files with the following extensions: * .fdd, .dtx .drv You can then produce printed documentation of the code as described below. The file features.tex could also be put in this directory. You may also want to move all the ASCII documentation files to the same place; these are the files with extension: * .l2e. The file ltxcheck.tex is used to check out the system (see below). This should leave files with the following extensions, which are not used by latex after the installation is complete and checked. You may want to keep some of these for reference. * .log (or .lis on some systems) TeX's log files. * .ltx Files used to create the format: no longer required. * .ins The installation scripts: no longer required. RESTARTING ========== If you want to `go back' to the initial distribution and re-start, then you need to keep the files with the following extension: * .l2e .dtx .fdd .ins and the files: * features.tex latexbug.tex testpage.tex * ot1.def t1.def * t1enc.sty t10t1.sty tracefnt.sty and remove everything else. ================================================ You can now run LaTeX, but first a few checks... CHECKING THE FORMAT =================== Because of certain differences between TeX implementations, LaTeX needs a configuration file texsys.cfg which describes how TeX searches for files to be opened, and the syntax of file names on the system. For most sites the default texsys.cfg (which only contains comments) will be acceptable. However, on some implementations it will produce a LaTeX format which lacks certain features, the most important one being that it will not be able to input any files that are not in the current directory. By running ltxcheck.tex with the new format you have made, you will be warned if you need to edit the file texsys.cfg. If you do need to edit it then you can later rebuild the format by just running initex on latex2e.ltx and then moving latex2e.fmt to the formats directory. You do not need to unpack the whole distribution again. There is a lot of information in texsys.cfg, and more in dircheck.dtx, that explains how to write a texsys.cfg file. Note that texsys.cfg is read very early in the process of making LaTeX, before the usual LaTeX commands such as \newcommand have been defined. Therefore you must use only primitive TeX commands in this file. Before running LaTeX2e on ltxcheck.tex you should ensure that article.cls is not in the current directory. (You should by now have moved it to the `standard input directory'). If article.cls is present in the local directory, LaTeX2e will definitely be able to read it, so LaTeX will not be able to check whether it is possible to read files which are *not* in the current directory. When LaTeX2e processes ltxcheck.tex, no .dvi file is produced. It will pause at certain points and display the results of its tests on the terminal. Each result will be described as `OK' or `BAD'. In the latter case you need to edit texsys.cfg. Here is a description of the checks run by ltxcheck. 1) The \@currdir check. It is useful for LaTeX to know the syntax for the `current directory (or folder)', or `default directory', if the operating system has such a concept. For example, file abc.tex in this directory, or folder, is specified by: ./abc.tex on unix and most DOS/OS2 TeX's, []abc.tex on VMS :abc.tex on a Macintosh. The above possibilities will be found automatically during the installation. However, if none of these syntaxes works on your system then the internal macro \@currdir will be set to be empty and ltxcheck will report this. If your system does have a notion of a current directory, you can define \@currdir in texsys.cfg. You could also report this to the latex-bug address, so that later releases can automatically cope with your system. 2) The \input@path check. On some systems TeX cannot check whether a file exists before trying to input it, unless the filename is expressed as a full path name, including the directory. On these systems LaTeX needs to be given a list of directories in which to look for files; the internal macro \input@path holds this information. When run, ltxcheck will try to locate the file article.cls. If it fails to find this file (and you have placed it in the `standard input directory') then you must define \input@path in texsys.cfg. The files texsys.cfg and dircheck.dtx contain examples of how to do this but only you know the directories and syntax that should be used for your installation. We hope to build up a better collection of examples in future releases of LaTeX2e, as it is tested on more TeX systems. 3) TeX version check. The final checks test that you are running a recent version of TeX. If ltxcheck reports that you have TeX2, then you should try to upgrade TeX (and rebuild LaTeX) as soon as possible. LaTeX2e may be used with TeX2, but certain features will be missing and you will not be able to use the new (8-bit) font families that are now available. If ltxcheck reports that your TeX version is older than 3.141, you will see some strange messages during the installation. This is because earlier TeXs printed certain line-breaks in messages on the terminal as ^^J rather than starting a new line. DOCUMENTATION ============= A short overview of the features of the new LaTeX release can be found in the file features.tex. This file can be processed by an old LaTeX, so it is not necessary to make the new format first. 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 will also be covered by the second edition of: * LaTeX: A Document Preparation System, Leslie Lamport, Addison-Wesley DOCUMENTATION OF THE CODE ========================= To typeset the documented code files run the corresponding driver files (.drv) through LaTeX (you must use the new version for this). You are allowed to change the driver files to get a special layout, etc. Instead of changing individual files you can change the layout of all the documentation files by writing a ltxdoc.cfg file. For example, putting the following line into this file will format the documentation for A4 paper: \PassOptionsToClass{a4paper}{article} The doc package, which is used by the documentation files, writes index files and change-history files that can be processed by the program MakeIndex. If this program is part of your TeX installation, you can get an index and history listing for a documentation file by running the .idx and .glo files through this program. Please note that you need to specify a style file for MakeIndex: gind.ist for the index file (result should be named *.ind) gglo.ist for the history file (result should be named *.gls) * In Unix MakeIndex, you should say: makeindex -s gind.ist FILENAME makeindex -s gglo.ist -o FILENAME.gls FILENAME.glo * In MacMakeIndex, you should select the `Options' pull-down menu to select the MakeIndex style and the output filename. * In DOS/OS2 makeindx, you should type: makeindx -s gind.ist FILENAME makeindx -s gglo.ist -o FILENAME.gls FILENAME.glo ADDITIONAL PACKAGES =================== In addition to the core system, the LaTeX2e distribution contains several additional packages which are not unpacked by the previous steps. To unpack them all, run the script l2extra.ins through LaTeX (not iniTeX). Alternatively, you can run individual scripts through LaTeX to unpack only some packages. Some of these scripts will ask questions: for example, whether you have certain fonts installed or intend to install them. Some of the files unpacked by these scripts should be moved to other places on your system. If this is the case, the installation script will inform you. LaTeX2e and LaTeX2.09 ===================== LaTeX2e provides updated versions of certain files which were distributed with LaTeX2.09. As these new versions will not work with the old system, in order to run both systems you must keep separated the files which are available to the two formats. At various points below we refer to a `standard input directory'. By this, we mean a directory (or folder, etc) in which you can put files that will be found by all LaTeX2e runs. You may want to configure your system such that this `standard input directory' is *not* searched when running `old latex', ie LaTeX2.09. Of course, the exact method of setting your up system like this depends on the operating system and on the TeX system that you are using. NOTE: If you do not do this, then you *must not* install the LaTeX2e .sty files in the normal `standard input directory' as this may destroy some files needed by LaTeX2.09. * On Unix (web2c) --------------- By default LaTeX will look in a list of directories (and subdirectories) that was specified when initex was installed. This may be overridden by the TEXINPUTS environment variable. Create a new directory (say /usr/local/lib/tex/latex2e/inputs) that is not on TeX's default TEXINPUTS path but that you want to be the `standard input directory' for LaTeX2e. Once the format is made, rather than making the command `latex2e' a link to virtex, make a shell script something like the following: ============== #!/bin/sh TEXINPUTS=.:/usr/local/lib/tex/latex2e/inputs:$TEXINPUTS: export TEXINPUTS virtex \&latex2e $* ============== This will make latex2e look first in the current directory, then in its `standard input directory', then finally in all the places that latex looks. * On DOS/OS2 (emTeX) ------------------ Here TeX's behaviour is very similar to the UNIX case. You need to make a file latex2e.bat (or latex2e.cmd) which sets the environment variable TEXINPUT to a path which includes LaTeX2e's `standard input directory' before calling TeX with the LaTeX2e format file (and to then reset TEXINPUT if necessary). * On VMS ------ There appears to be no standardisation for VMS TeX setups, so it is not possible to give useful advice here. * On Macintosh (OzTeX) -------------------- Create a LaTeX2e-inputs folder, which will be the standard input directory. Then create two configuration files `LaTeX2e' and `LaTeX209' in the Configs folder. These should set nothing but: * the TeX inputs path * the TeX formats. (See the OzTeX documentation for how to edit Config files.) The LaTeX2e configuration file should: * include :LaTeX2e-inputs: at the front of the inputs path. * replace the LaTeX format by LaTeX2e. The LaTeX209 configuration file should: * not include :LaTeX2e-inputs: in the inputs path. * include the LaTeX format. Add these two configuration files to the Configs line of the Default configuration file, and edit the Default configuration to be the same as the LaTeX2e configuration (this will make LaTeX2e the default). Once you have created the LaTeX2e format, you will then have two new configuration options: LaTeX2e and LaTeX209, which you can use to select either version of LaTeX. NOTE: If it is impossible (or difficult) for you to arrange that latex2e has a different `standard input directory' to latex 2.09 then, if you want to maintain a working LaTeX2.09 system, you should *not* move the .sty files during the final stage of the installation. (You can move all the other files as they will not clash with old files.) In order to process certain documents with LaTeX2e, it will then be necessary to copy the LaTeX2e versions of the .sty files used into the directory containing the document, so that LaTeX2e does not attempt to load the old LaTeX2.09 files. PROBLEMS ======== On most systems the installation should proceed smoothly. However, you may get some errors. `texsys.cfg': While running iniTeX on latex2e.ltx you may get an error reporting a problem with texsys.cfg. If this happens then you have obtained (or produced) a texsys.cfg that is not suitable for your system. Remove the file texsys.cfg and remake the format. You should not get these errors if there is no file texsys.cfg. When you have made the new format, run ltxcheck.tex as described above; this will inform you if you do need a texsys.cfg file. Note that it should always be possible to produce a format if you remove the file texsys.cfg. However, on some systems, the resulting LaTeX2e will not be able to find files which are not in the current directory. Nevertheless, you should be able to use it to run dircheck.drv; this will produce a file dircheck.dvi which you can print and read. This document will, we hope, show you how to edit texsys.cfg so a to obtain a fully functional format. `File missing': Some of the files from the LaTeX distribution are missing. There are a number of possible reasons for this: * the files are missing. You should get the files from the same place you got the rest of the distribution. If you can't, 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 iniTeX can read. * the files are present, and in the right directory. IniTeX may have been set up incorrectly. You may be able to correct this, depending on your TeX implementation. See the notes above on how to configure where TeX looks for files. `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; some systems have an environment variable (eg TEXFONTS) which is used to control this. `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 happened during the unpacking of the distribution (i.e. when you run iniTeX on unpack2e.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: * ask your local TeX guru; * if this fails, try asking a local TeX mailing list; * if this fails, mail a bug report to: latex-bugs@rus.uni-stuttgart.de. A template for sending such a report may be made by running iniTeX on the file latexbug.tex. This is a test release of LaTeX2e. The full release will be available later this year. --- Copyright 1994 the LaTeX3 project. All rights reserved ---