path: root/Master/texmf-dist/doc/latex/base/install.txt

                   LaTeX Installation Guide
 
                        2003/12/01
 
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 <xxx>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, ISBN 0-201-52983-1

Also possibly of interest (describing package and programs related to
graphical applications, Postscript font usage, etc.):

 * The LaTeX Graphics Companion, Goossens, Rathz and Mittelbach,
   Addison-Wesley ISBN 0-201-85469-4.
 
 
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 <system>.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.

 * emtextds.txt for Schmidt's emTeX/TDS for OS/2.

 * 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.

 * truetex.txt for TrueTeX for Windows 95/98/NT.

 * vtex.txt for MicroPress's VTeX.

 * vtexfree.txt for MicroPress's VTeX/Free for Linux-x86 (VTeX/Lnx)
   and OS/2 (VTeX/2).

 * 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 <system>.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 <system>.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 <system>.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 <system>.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.

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.

Note that the experimental variant of LaTeX described in autoload.txt
is no longer supported.

 
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 <system>.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 <system>.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 <system>.txt file.  This may tell you
   how to customize the file texsys.cfg.
   
   If the <system>.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 <system>.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 <system>.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<xx>.tex and ltnews<xx>.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 <xxx>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 <system>.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 <system>.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 ---