% \iffalse meta-comment
%
% Copyright 1994 the LaTeX3 project and the individual authors.
% All rights reserved. For further copyright information see the file
% legal.txt, and any other copyright indicated in this file.
% 
% This file is part of the LaTeX2e system.
% ----------------------------------------
% 
%  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 bugs.txt.
% 
% 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 manifest.txt.
% 
% 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
% Filename: usrguide.tex

\NeedsTeXFormat{LaTeX2e}[1994/06/01]

\documentclass{ltxguide}[1994/05/24]

\title{\LaTeXe~for authors}

\author{\copyright~Copyright 1994, \LaTeX3 Project Team.\\
   All rights reserved.}

\date{13.\ July 1994}

\begin{document}

\maketitle

\tableofcontents

\section{Introduction}

Welcome to \LaTeXe, the new standard version of the \LaTeX{} Document
Preparation System.

This document describes how to take advantage of the new features of
\LaTeX, and how to process your old \LaTeX{} documents with
\LaTeXe. However, this document is only a brief introduction to the
new facilities and is intended for authors who are already familiar
with the old version of \LaTeX{}.  It is \emph{neither} a user-guide
\emph{nor} a reference manual for \LaTeXe.

\subsection{\LaTeXe---The new \LaTeX~release}

The previous version of \LaTeX{} was known as \LaTeX~2.09.  Over the
years many extensions have been developed for \LaTeX.  This is, of
course, a sure sign of its continuing popularity but it has had one
unfortunate result: incompatible \LaTeX{} formats came into use at
different sites.  This included `standard \LaTeX~2.09', \LaTeX{} built
with the \emph{New Font Selection Scheme}~(\NFSS), \SLiTeX, \AmSLaTeX,
and so on.  Thus, to process documents from various places, a site
maintainer was forced to keep multiple versions of the \LaTeX{}
program.  In addition, when looking at a source file it was not always
clear for which format the document was written.

To put an end to this unsatisfactory situation, \LaTeXe{} has been
produced; it brings all such extensions back under a single format and
thus prevents the proliferation of mutually incompatible dialects of
\LaTeX~2.09.  With \LaTeXe{} the `new font selection scheme' is
standard and, for example, \textsf{amstex} (formerly the \AmSLaTeX{}
format) or \textsf{slides} (formerly the \SLiTeX{} format) are simply
extension packages, all working with the same base format.

The introduction of a new release also made it possible to add a small
number of often-requested features and to make the task of writing
packages and classes simpler.

\subsection{\LaTeX3---The long-term future of \LaTeX}
\label{Sec:ltx3}

\LaTeXe{} is the consolidation step in a comprehensive
reimplementation of the \LaTeX{} system.  The next major release of
\LaTeX{} will be \LaTeX3, which will include a radical overhaul of the
document designers' and package writers' interface to \LaTeX.

\LaTeX3 is a long-term research project but, until it is completed,
the project team are committed to the active maintenance of \LaTeXe{}.
Thus the experience gained from the production and maintenance of
\LaTeXe{} will be a major influence on the design of \LaTeX3.

If you would like to support the project then you are welcome to send
donations to the \LaTeX3 Project Fund; this has been set up to help
the research team by financing various expenses associated with this
voluntary work of maintaining the current \LaTeX{} and developing
\LaTeX3. 

The fund is administered by The \TeX{} Users Group and by various
local user groups.  Information about making donations and joining
these groups is available from:

\begin{quote}
\TeX{} Users Group\\
P.~O.~Box~869, Santa~Barbara, CA~93102-0869, USA\\
Fax:~+1~805~963~8358\\
E-Mail: \texttt{tug@tug.org}
\end{quote}

\subsection{Overview}

This document contains an overview of the new structure and features
of \LaTeX.  It is \emph{not} a self-contained document, as it contains
only the features of \LaTeX{} which have changed since version 2.09.
You should read this document in conjunction with an introduction to
\LaTeX{}.

\begin{description}

\item[Section~\ref{Sec:class+packages}]
   contains an overview of the new structure of
   \LaTeX{} documents.  It describes how classes and packages work and
   how class and package options can be used.  It lists the standard
   packages and classes which come with \LaTeX.

\item[Section~\ref{Sec:commands}] describes the new commands available
   to authors in \LaTeXe.

\item[Section~\ref{Sec:209}] shows how to process old \LaTeX{}
   documents with \LaTeXe.

\item[Section~\ref{Sec:problems}] contains advice on dealing with
   problems you may encounter in running \LaTeXe.
   It lists some error messages which are new in \LaTeXe{} and
   it describes some of the more common problems and how to cure them,
   or where to find further information.

\end{description}

\subsection{Further information}

For a general introduction to \LaTeX, including the new features of
\LaTeXe, you should read \emph{\LaTeXbook}
by Leslie Lamport~\cite{A-W:LLa94}.

A more detailed description of the new features of \LaTeX, including
an overview of more than 150 packages, is to be found in
\emph{\LaTeXcomp} by Michel Goossens, Frank Mittelbach and Alexander
Samarin~\cite{A-W:GMS94}.

For more information about the many new \LaTeX{} packages you should
read the package documentation, which should be available from the
same source as your copy of \LaTeX.

There are a number of documentation files which accompany every copy
of \LaTeX.  A copy of \emph{\LaTeX{} News} will come out with each
six-monthly release of \LaTeX; it will be found in the files
|ltnews*.tex|.  The class- and package-writer's guide \emph{\clsguide}
describes the new \LaTeX{} features for writers of document classes
and packages; it is in |clsguide.tex|.  The guide \emph{\fntguide}
describes the \LaTeX{} font selection scheme for class- and
package-writers; it is in |fntguide.tex|.

We are gradually turning the source code for \LaTeX{} into a \LaTeX{}
document \emph{\sourcecode}.  This document includes an index of
\LaTeX{} commands and can be typeset from |source2e.tex|.

For more information about \TeX{} and \LaTeX, please contact your
local \TeX{} Users Group, or the international \TeX{} Users Group,
P.~O.\ Box~869, Santa Barbara, CA 93102-0869, USA, Fax:~+1 805 963
8358, E-mail:~tug@tug.org.

\section{Classes and packages}
\label{Sec:class+packages}

This section describes the new structure of \LaTeX{} documents and the
new types of file: \emph{classes} and \emph{packages}.

\subsection{What are classes and packages?}

The main difference between \LaTeX~2.09 and \LaTeXe{} is in the
commands before |\begin{document}|.

In \LaTeX~2.09, documents had \emph{styles},
such as |article| or |book|, and \emph{options}, such as |twoside|
or |epsfig|.
These were indicated by the |\documentstyle| command:
\begin{quote}
   |\documentstyle|\oarg{options}\arg{style}
\end{quote}
For example, to specify a two-sided article with encapsulated
PostScript figures, you said:
\begin{verbatim}
   \documentstyle[twoside,epsfig]{article}
\end{verbatim}
However, there were two different types of document style option:
\emph{built-in options} such as |twoside|; and \emph{packages} such as
|epsfig.sty|.  These were very different, since any \LaTeX{} document
style could use the |epsfig| package but only document styles which
declared the |twoside| option could use it.

To avoid this confusion, \LaTeXe{} differentiates between built-in
options and packages.  These are given by the new |\documentclass| and
|\usepackage| commands:
\begin{quote}
   |\documentclass|\oarg{options}\arg{class} \\
   |\usepackage|\oarg{options}\arg{packages}
\end{quote}
For example, to specify a two-sided article with encapsulated
PostScript figures, you now write:
\begin{verbatim}
   \documentclass[twoside]{article}
   \usepackage{epsfig}
\end{verbatim}
You can load more than one package with a single |\usepackage|
command; for example, rather than writing:
\begin{verbatim}
   \usepackage{epsfig}
   \usepackage{multicol}
\end{verbatim}
you can specify:
\begin{verbatim}
   \usepackage{epsfig,multicol}
\end{verbatim}
Note that \LaTeXe{} still understands the \LaTeX~2.09 |\documentstyle|
command.  This command causes \LaTeXe{} to enter \emph{\LaTeX~2.09
compatibility mode}, which is described in Section~\ref{Sec:209}.

You should not, however, use the |\documentstyle| command for new
documents because this compatibility mode is very slow and the new
features of \LaTeXe{} are not available in this mode.

To help differentiate between classes and packages, document classes
now end with |.cls| rather than |.sty|.  Packages still end with
|.sty|, since most \LaTeX~2.09 packages work well with \LaTeXe.

\subsection{Class and package options}

In \LaTeX~2.09, only document styles could have options such as
|twoside| or |draft|.  In \LaTeXe{}, both classes and packages are
allowed to have options.  For example, to specify a two-sided article
with graphics using the |dvips| driver, you write:

\begin{verbatim}
   \documentclass[twoside]{article}
   \usepackage[dvips]{graphics}
\end{verbatim}
It is possible for packages to share common options.  For example,
you may could, in addition, load the |color| package by specifying:
\begin{verbatim}
   \documentclass[twoside]{article}
   \usepackage[dvips]{graphics}
   \usepackage[dvips]{color}
\end{verbatim}
But because |\usepackage| allows more than one package to be listed,
this can be shortened to:
\begin{verbatim}
   \documentclass[twoside]{article}
   \usepackage[dvips]{graphics,color}
\end{verbatim}
In addition, packages will also use each option given to
the |\documentclass| command (if they know what to do with it), so you
could also write:
\begin{verbatim}
   \documentclass[twoside,dvips]{article}
   \usepackage{graphics,color}
\end{verbatim}
Class and package options are covered in more detail in
\emph{\LaTeXcomp} and in \emph{\clsguide}.

\subsection{Standard classes}

The following classes are distributed with \LaTeX:
\begin{description}

\item[article]  The |article| class described in \emph{\LaTeXbook}.
\item[book]     The |book| class described in \emph{\LaTeXbook}.
\item[report]   The |report| class described in \emph{\LaTeXbook}.
\item[letter]   The |letter| class described in \emph{\LaTeXbook}.
\item[slides]   The |slides| class described in \emph{\LaTeXbook},
   formerly \SLiTeX.
\item[proc]     A document class for proceedings, based on |article|.
   Formerly the |proc| package.
\item[ltxdoc]   The document class for documenting the \LaTeX{}
   program, based on |article|.
\item[ltxguide] The document class for \emph{\usrguide} and
   \emph{\clsguide}, based on |article|.  The document you are reading
   now uses the |ltxguide| class. The layout for this class is likely
   to change in future releases of \LaTeX.
\item[ltnews]   The document class for the \emph{\LaTeX{} News}
   information sheet, based on |article|. The layout for this class
    is likely to change in future releases of \LaTeX.

\end{description}

\subsection{Standard packages}
\label{Sec:st-pack}

The following packages are distributed with \LaTeX:
\begin{description}
\item[doc] Allows the documentation of \LaTeX{} programs.\\
  Described in |doc.dtx| and in \emph{\LaTeXcomp}.
\item[exscale]  Provides scaled versions of the math extension font.\\
   Described in |ltexscale.dtx|.
\item[fontenc]  Specifies which font encoding \LaTeX{} should use.\\
   Described in |ltoutenc.dtx|.
\item[ifthen]   Provides commands of the form `if\dots then do\dots
   otherwise do\dots'.\\
   Described in |ifthen.dtx| and \emph{\LaTeXcomp}.
\item[latexsym] \LaTeXe{} no longer loads the \LaTeX{} symbol font by
   default.  To access it, you should use the |latexsym| package.
   Described in |latexsym.dtx| and in \emph{\LaTeXcomp}; see also
   Section~\ref{Sec:problems}.
\item[makeidx] Provides commands for producing indexes.  Described in
   \emph{\LaTeXbook} and in \emph{\LaTeXcomp}.
\item[newlfont] Emulates the font commands of \LaTeX~2.09 with the New
   Font Selection Scheme.  Described in  \emph{\LaTeXcomp}.
\item[oldlfont] Emulates the font commands of \LaTeX~2.09.\\
   Described in  \emph{\LaTeXcomp}.
\item[syntonly] Processes a document without typesetting it.\\
   Described in |syntonly.dtx| and in \emph{\LaTeXcomp}.
\item[tracefnt] Allows you to control how much information about
   \LaTeX's font loading is displayed.  Described in  \emph{\LaTeXcomp}.
\end{description}

\subsection{Related software}

In addition, the following software should be available from the same
distributor as your copy of \LaTeXe:
\begin{description}
\item[amslatex]  Advanced mathematical typesetting from the American
                 Mathematical Society
\item[babel]     Supports typesetting in many languages.
\item[color]     Provides support for colour.
\item[graphics]  Inclusion of graphics files.
\item[mfnfss]    Typesetting with bit-map (Metafont) fonts.
\item[psnfss]    Typesetting with Type~1 (PostScript) fonts.
\item[tools]     Miscellaneous packages written by the \LaTeX3
                 project team.
\end{description}
These packages come with documentation and each of them is also
described in at least one of the books \emph{\LaTeXcomp} and
\emph{\LaTeXbook}.

\subsubsection{Tools}

This collection of packages includes, at least, the following (some
files may have slightly different names on certain systems):

\begin{description}
\item[array]
        Extended versions of the environments |array|, |tabular|
        and |tabular*|, with many extra features.
\item[dcolumn]
        Alignment on `decimal points' in tabular entries. Requires the
        |array| package.
\item[delarray]
        Adds `large delimiters' around arrays. Requires |array|.
\item[hhline]
        Finer control over horizontal rules in tables. Requires |array|.
\item[longtable]
        Multi-page tables. (Does not require |array|, but it uses the
        extended features if both are loaded.)  
\item[tabularx]
        Defines a |tabularx| environment that is similar to |tabular*|
        but it modifies the column widths, rather than the inter-column
        space, to achieve the desired table width.
\item[afterpage]
        Place text after the current page.
\item[enumerate]
        Extended version of the |enumerate| environment.
\item[fontsmpl]
        Package and test file for producing `font samples'.
\item[ftnright]
        Place all footnotes in the right-hand column in two-column mode.
\item[indentfirst]
        Indent The first paragraph of sections, etc.
\item[multicol]
        Typeset text in columns, with the length of the columns
        `balanced'.
\item[rawfonts]
        Preload fonts using the old internal font names of LaTeX2.09.
        See Section~\ref{Sec:oldinternals}.
\item[somedefs]
       Selective handling of package options. (Used by the rawfonts
       package.)
\item[showkeys]
        Prints the `keys' used by |\label|, |\ref|, |\cite| etc.; useful
        whilst drafting.
\item[theorem]
       Flexible declaration of `theorem-like' environments.
\item[varioref]
       `Smart' handling of page references.
\item[verbatim]
        Flexible extension of the verbatim environment.
\item[xspace]
       `Smart space' command that helps you to avoid the common mistake
       of missing spaces after command names.
\end{description}


\section{Commands}
\label{Sec:commands}

This section describes the new commands available in \LaTeXe.
They are covered in more detail in \emph{\LaTeXbook} and in
\emph{\LaTeXcomp}.

\subsection{Initial commands}

Initial commands can appear only before the |\documentclass|
line.

\begin{decl}
|\begin{filecontents}| \arg{file-name} \\
  \m{file-contents} \\
|\end{filecontents}|
\end{decl}

The |filecontents| environment is intended for bundling within a
single document file the contents of packages, options, or other
files.  When the document file is run through \LaTeXe{} the body of
this environment is written verbatim (preceded by a comment line) to a
file whose name is given as the environment's only argument.  However,
if that file already exists then nothing happens except for an
information message.

Only normal ASCII text characters (i.e.~7-bit visible text) should be
included in a |filecontents| environment.  Anything else, such as tab
characters, form-feeds or 8-bit characters, should not be included in a
|filecontents| environment.

Tabs and form feeds produce a warning, explaining that they are turned
into spaces or blank lines, respectively.
What happens to 8-bit characters depends on the \TeX{} installation and
is in general unpredictable.

The |filecontents| environment is used for including \LaTeX{} files.
For other plain text files (such as Encapsulated PostScript files),
you should use the |filecontents*| environment which does not add a
comment line.

These environments are allowed only before |\documentclass|.  This
ensures that any packages that have been bundled in the document are
present when needed.

\subsection{Preamble commands}
\label{Sec:pre}

The changes to the preamble commands are intentionally designed to make
\LaTeXe{} documents look clearly different from old documents.  The
commands should be used only before |\begin{document}|.

\begin{decl}
|\documentclass| \oarg{option-list} \arg{class-name}
   \oarg{release-date}
\end{decl}

This command replaces the
\LaTeX2.09 command |\documentstyle|.

There must be exactly one |\documentclass| command in a document; and
it must come after the |filecontents| environments, if any, but before
any other commands.

The \m{option-list} is a list of options, each of which may modify the
formatting of elements which are defined in the \m{class-name} file,
as well as those in all following |\usepackage| commands (see
below).

The optional argument \m{release-date} can be used to specify the
earliest desired release date of the class file; it should contain a
date in the format \textsc{yyyy/mm/dd}.  If a version of the class
older than this date is found, a warning is issued.

For example, to specify a two-column article, using a version of
|article.cls| released after June 1994, you specify:
\begin{verbatim}
   \documentclass[twocolumn]{article}[1994/06/01]
\end{verbatim}

\begin{decl}
|\documentstyle| \oarg{option-list} \arg{class-name}
\end{decl}

This command is still supported for compatibility with old files.  It
is essentially the same as |\documentclass| except that it invokes
\emph{\LaTeX~2.09 compatibility mode}.  It also causes any options in
the \m{option-list} that are not processed by the class file to be
loaded as packages after the class has been loaded. See
Section~\ref{Sec:209} for more details on \LaTeX~2.09 compatibility
mode.

\begin{decl}
|\usepackage| \oarg{option-list} \arg{package-name} \oarg{release-date}
\end{decl}

Any number of |\usepackage| commands is allowed. Each package file
(as denoted by \m{package-name}) defines new elements (or modifies
those defined in the class file loaded by the \m{class-name} argument
of the |\documentclass| command).  A package file thus extends the
range of documents which can be processed.

The \m{option-list} argument can contain a list of options, each of
which can modify the formatting of elements which are defined in this
\m{package-name} file.

As above, \m{release-date} can contain the earliest desired release
date of the package file in the format \textsc{yyyy/mm/dd}; if an
older version of the package is found, a warning is issued.

For example, to load the |graphics| package for the |dvips| driver,
using a version of |graphics.sty| released after June 1994, you write:
\begin{verbatim}
   \usepackage[dvips]{graphics}[1994/06/01]
\end{verbatim}
Each package is loaded only once.  If the same package is requested
more than once, nothing happens in the second or following attempt
unless the package has been requested with options that were not given
in the original |\usepackage|. If such extra options are specified
then an error message is produced. See Section \ref{Sec:problems} how
to resolve this problem.

As well as processing the options given in the \m{option-list} of the
|\usepackage| command, each package processes the
\m{option-list} of the |\documentclass| command as well. This
means that any option which should be processed by every package (to
be precise, by every package that specifies an action for it) can be
specified just once, in the |\documentclass| command, rather than
being repeated for each package that needs it.

\begin{decl}
|\listfiles|
\end{decl}

If this command is placed in the preamble then a list of the files
read in (as a result of processing the document) will be displayed
on the terminal (and in the log file) at the end of the run. Where
possible, a short description will also be produced.

\emph{Warning}: this command will list only files which were read
using \LaTeX{} commands such as |\input|\arg{file} or
|\include|\arg{file}.  If the file was read using the primitive \TeX{}
file input command then it will not be listed.

\begin{decl}
|\setcounter{errorcontextlines}| \arg{num}
\end{decl}

\TeX3 introduced a new primitive |\errorcontextlines| which controls
the format of error messages. \LaTeXe\ provides an interface to this
through the standard |\setcounter| command. As most \LaTeX\ users do
not want to see the internal definitions of \LaTeX\ commands each time
they make an error, \LaTeXe{} sets this to $-1$ by default.

\subsection{Document structure}

The |book| document class introduces new commands to indicate
document structure.
\begin{decl}
|\frontmatter| \\ |\mainmatter| \\ |\backmatter|
\end{decl}
These commands indicate the beginning of the front matter (title page,
table of contents and prefaces), main matter (main text) and back
matter (bibliography, indexes and colophon).

\subsection{Definitions}

In \LaTeX, commands can have both mandatory and optional arguments,
for example in:
\begin{verbatim}
   \documentclass[11pt]{article}
\end{verbatim}
the |11pt| argument is optional, whereas the |article| class name is
mandatory.

In \LaTeX~2.09 users could define commands with arguments, but these
had to be mandatory arguments.  With \LaTeXe, users can now define
commands and environments which also have one optional argument.

\begin{decl}
|\newcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\
|\renewcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
\end{decl}

These commands have a new, second, optional argument; this is used for
defining commands which themselves take one optional argument.  This
new argument is best introduced by means of a simple (and hence not
very practical) example:
\begin{verbatim}
   \newcommand{\example}[2][YYY]{Mandatory arg: #2;
                                 Optional arg: #1.}
\end{verbatim}
This defines |\example| to be a command with two arguments, referred
to as |#1| and |#2| in the \arg{definition}---nothing new so far.  But
by adding a second optional argument to this |\newcommand| (the
|[YYY]|) the first argument (|#1|) of the newly defined command
|\example| is made optional with its default value being |YYY|.

Thus the usage of |\example| is either:
\begin{verbatim}
   \example{BBB}
\end{verbatim}
which prints:
\begin{quote}
   Mandatory arg: BBB;
   Optional arg: YYY.
\end{quote}
or:
\begin{verbatim}
   \example[XXX]{AAA}
\end{verbatim}
which prints:
\begin{quote}
   Mandatory arg: AAA;
   Optional arg: XXX.
\end{quote}

The default value of the optional argument is \texttt{YYY}.
This value is specified as the \oarg{default} argument of the
|\newcommand| that created |\example|.

As another more useful example, the definition:
\begin{verbatim}
   \newcommand{\seq}[2][n]{\lbrace #2_{0},\ldots,\,#2_{#1} \rbrace}
\end{verbatim}
means that the input |$\seq{a}$| produces
the formula $\lbrace a_{0},\ldots,\,a_{n} \rbrace$,
whereas the input |$\seq[k]{x}$| produces the formula
$\lbrace x_{0},\ldots,\,x_{k} \rbrace$.

In summary, the command:
\begin{quote}
   |\newcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
\end{quote}
defines \m{cmd} to be a command with \m{num} arguments, the first of
which is optional and has default value \m{default}.

Note that there can only be one optional argument but, as before,
there can be up to nine arguments in total.

\begin{decl}
|\newenvironment|
 \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} \\
|\renewenvironment|
 \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def}
\end{decl}
\LaTeXe\ also supports the creation of environments that have one
optional argument.  Thus the syntax of these two commands has
been extended in the same way as that of |\newcommand|.


\begin{decl}
|\providecommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
\end{decl}
This takes the same arguments as |\newcommand|. If \m{cmd} is already
defined then the existing definition is kept; but if it is currently
undefined then the effect of |\providecommand| is to define \m{cmd}
just as if |\newcommand| had been used.

\subsection{Boxes}

These next three commands for making LR-boxes all existed in
\LaTeX~2.09.  They have been enhanced in two ways.

\begin{decl}
|\makebox| \oarg{width} \oarg{pos}  \arg{text} \\
|\framebox| \oarg{width} \oarg{pos}  \arg{text} \\
|\savebox| \arg{cmd} \oarg{width} \oarg{pos}  \arg{text}
\end{decl}

One small but far-reaching change for \LaTeXe\ is that, within the
\m{width} argument only, four special lengths can be used.  These are
all dimensions of the box that would be produced by using simply
|\mbox|\arg{text}:
\begin{itemize}
\item []   |\height|\quad its height above the baseline;
\item []   |\depth|\quad its depth below the baseline;
\item []   |\totalheight|\quad the sum of |\height| and |\depth|;
\item []   |\width|\quad its width.
\end{itemize}
Thus, to put `hello' in the centre of a box of twice its natural
width, you would use:
\begin{verbatim}
   \makebox[2\width]{hello}
\end{verbatim}
Or you could put \textit{f} into a square box, like
this:
   \framebox{\makebox[\totalheight]{\itshape f\/}}
\begin{verbatim}
   \framebox{\makebox[\totalheight]{\itshape f\/}}
\end{verbatim}
Note that it is the total width of the framed box, including the
frame, which is set to |\totalheight|.

The other change is a new possibility for \m{pos}: |s| has been added
to |l| and |r|.  If \m{pos} is |s| then the text is stretched the
full length of the box, making use of any `rubber lengths' (including
any inter-word spaces) in the box's contents.  If no such `rubber
length' is present, an `underfull box' will probably be produced.

\begin{decl}
|\parbox| \oarg{pos} \oarg{height} \oarg{inner-pos} \arg{width}
         \arg{text} \\
|\begin{minipage}|
         \oarg{pos} \oarg{height} \oarg{inner-pos} \arg{width}\\
\m{text}\\
|\end{minipage}|
\end{decl}

As for the box commands above, |\height|, |\width|, etc.~may be used
in the \oarg{height} argument to denote the natural dimensions of the
box.

The \m{inner-pos} argument is new in \LaTeXe.  It is the vertical
equivalent to the \m{pos} argument for |\makebox|, etc, determining
the position of \m{text} within the box.  The \m{inner-pos} may be any
one of |t|, |b|, |c|, or |s|, denoting top, bottom, centred, or
`stretched' alignment respectively.  When the \m{inner-pos} argument
is not specified, \LaTeX\ gives it same  value as \m{pos} (this could be
the latter's default value).


\begin{decl}
|\begin{lrbox}| \arg{cmd}\\
\m{text}\\
|\end{lrbox}|
\end{decl}

This is an environment which does not directly print anything.
Its effect is to save the typeset \m{text} in the bin \m{cmd}. Thus
it is like |\sbox| \arg{cmd} \arg{text}, except that any white space
before or after the contents \m{text} is ignored.

This is very useful as it enables both the |\verb| command and the
\texttt{verbatim} environment to be used within \m{text}.

It also makes it possible to define, for example, a `framed box'
environment.  This is done by first using this environment to save
some text in a bin \m{cmd} and then calling
|\fbox{\usebox{|\m{cmd}|}}|.

The following example defines an environment, called |fmpage|, that is
a framed version of |minipage|.
\begin{verbatim}
   \newsavebox{\fmbox}
   \newenvironment{fmpage}[1]
     {\begin{lrbox}{\fmbox}\begin{minipage}{#1}}
     {\end{minipage}\end{lrbox}\fbox{\usebox{\fmbox}}}
\end{verbatim}


\subsection{Measuring things}

The first of these next commands was in \LaTeX~2.09. The two new
commands are the obvious analogues.

\begin{decl}
|\settowidth|  \arg{length-cmd} \arg{lr text} \\
|\settoheight| \arg{length-cmd} \arg{lr text} \\
|\settodepth|  \arg{length-cmd} \arg{lr text}
\end{decl}

\subsection{Controlling page breaks}

Sometimes it is necessary, for a final version of a document, to
`help' \LaTeX\ break the pages in the best way. \LaTeX~2.09 had a
variety of commands for this situation: |\clearpage|, |\pagebreak|
etc.  \LaTeXe\ provides, in addition, commands which can produce
longer pages as well as shorter ones.


\begin{decl}
|\enlargethispage| \arg{size} \\
|\enlargethispage*| \arg{size}
\end{decl}

These commands increase the height of a page (from its normal value of
|\textheight|) by the specified amount \m{size}, a rigid length. This
change affects \emph{only} the current page.

This can be used, for example, to allow an extra line to be fitted
onto the page or, with a negative length, to produce a page
shorter than normal.

The star form also shrinks any vertical white space on the page as
much as possible, so as to fit the maximum amount of text on the
page.

\subsection{Floats}

There is a new command, |\suppressfloats|, and a new `float
specifier'.  These will enable people to gain better
control of \LaTeX's float placement algorithm.

\begin{decl}
|\suppressfloats| \oarg{placement}
\end{decl}

This command stops any further floating environments from being placed
on the current page. With an optional argument, which should be either
|t| or |b| (not both), this restriction applies only to putting
further floats at the top or at the bottom.  Any floats which would
normally be placed on this page are placed on the next page instead.

\begin{decl}
The extra float location specifier: \ \texttt{!}
\end{decl}

This can be used, along with at least one of \texttt{h}, \texttt{t},
\texttt{b} and \texttt{p}, in the location optional argument of a
float.

If a \texttt{!} is present then, just for this particular float,
whenever it is processed by the float mechanism the following are
ignored:
\begin{itemize}
\item  all restrictions on the number of floats which can appear;
\item all explicit restrictions on the amount of space on a text page
which may be occupied by floats or must be occupied by text.
\end{itemize}
The mechanism will, however, still attempt to ensure that pages are
not overfull and that floats of the same type are printed in the
correct order.

Note that its presence has no effect on the production of float pages.

A \texttt{!} specifier overrides the effect of any |\suppressfloats|
command for this particular float.

\subsection{Font changing: text}

\LaTeXe{} has a very different font selection scheme to \LaTeX~2.09.  In
this section, we give a brief description of the new commands.
A more detailed description with examples is given in \emph{\LaTeXcomp},
and the interface for class- and package-writers is described in
\emph{\fntguide}.

\begin{decl}
|\rmfamily|\\
|\sffamily|\\
|\ttfamily|\\
|\mdseries|\\
|\bfseries|\\
|\upshape|\\
|\itshape|\\
|\slshape|\\
|\scshape|
\end{decl}

These are font commands whose use is the same as the commands |\rm|,
|\bf|, etc.  The difference is that each command changes just one
attribute of the font (the attribute changed is part of the name).
One result of this is that, for example, |\bfseries\itshape| produces
both a change of series and a change of shape, to give a bold italic
font.

\begin{decl}
|\textrm|\arg{text}\\
|\textsf|\arg{text}\\
|\texttt|\arg{text}\\
|\textmd|\arg{text}\\
|\textbf|\arg{text}\\
|\textup|\arg{text}\\
|\textit|\arg{text}\\
|\textsl|\arg{text}\\
|\textsc|\arg{text}\\
|\emph|\arg{text}
\end{decl}

These are one-argument commands; they take as an argument the
text which is to be typeset in the particular font. They also
automatically insert italic corrections where appropriate; if you do
not like the result, you can add an italic correction with |\/| or
remove it with |\nocorr|.  The |\nocorr| should always be the first or
last thing within the \arg{text} argument.

\subsection{Font changing: math}

Most of the fonts used within math mode do not need to be explicitly
invoked; but to use letters from a range of fonts, the following
class of commands is provided.

\begin{decl}
|\mathrm| \arg{letters}\\
|\mathnormal| \arg{letters}\\
|\mathcal| \arg{letters}\\
|\mathbf| \arg{letters}\\
|\mathsf| \arg{letters}\\
|\mathtt| \arg{letters}\\
|\mathit| \arg{letters}
\end{decl}

These are also one-argument commands which take as an argument the
letters which are to be typeset in the particular font.  The argument
is processed in math mode so spaces within it will be ignored.  Only
letters, digits and accents have their font changed, for example
|$\mathbf{\tilde A \times 1}$| produces $\mathbf{\tilde A \times 1}$.

\subsection{Ensuring math mode}

\begin{decl}
|\ensuremath| \arg{math commands}
\end{decl}

In \LaTeX~2.09, if you wanted a command to work both in math mode and
in text mode, the suggested method was to define something like:
\begin{verbatim}
   \newcommand{\Gp}{\mbox{$G_p$}}
\end{verbatim}
Unfortunately, the |\mbox| stops |\Gp| changing size correctly in (for
instance) subscripts or a fraction.

In \LaTeXe{} you can define it thus:
\begin{verbatim}
   \newcommand{\Gp}{\ensuremath{G_p}}
\end{verbatim}
Now |\Gp| will work correctly in all contexts.

This is because the |\ensuremath| does nothing, producing simply
|G_p|, when |\Gp| is used within math mode; but it ensures that math
mode is entered (and exited) as required when |\Gp| is used in text
mode.

\subsection{Logos}

\begin{decl}
|\LaTeX|\\
|\LaTeXe|
\end{decl}

|\LaTeX| (producing `\LaTeX') is still the `main' logo command,
but if you need to refer to the new features, you can write
|\LaTeXe| (producing `\LaTeXe').

\subsection{Picture commands}

\begin{decl}
   |\qbezier[<N>](<AX>,<AY>)(<BX>,<BY>)(<CX>,<CY>)| \\
   | \bezier{<N>}(<AX>,<AY>)(<BX>,<BY>)(<CX>,<CY>)|
\end{decl}
The |\qbezier| command can be used in |picture| mode to draw a
quadratic bezier curve from position |(<AX>,<AY>)| to |(<CX>,<CY>)| with
control point |(<BX>,<BY>)|.  The optional argument \m{N} gives the
number of points on the curve.

For example, the diagram:
\begin{center}
   \begin{picture}(50,50)
      \thicklines
      \qbezier(0,0)(0,50)(50,50)
      \qbezier[20](0,0)(50,0)(50,50)
      \thinlines
      \put(0,0){\line(1,1){50}}
   \end{picture}
\end{center}
is drawn with:
\begin{verbatim}
   \begin{picture}(50,50)
      \thicklines
      \qbezier(0,0)(0,50)(50,50)
      \qbezier[20](0,0)(50,0)(50,50)
      \thinlines
      \put(0,0){\line(1,1){50}}
   \end{picture}
\end{verbatim}
The |\bezier| command is the same, except that the argument \m{N} is not
optional.  It is provided for compatibility with the \LaTeX~2.09
|bezier| document style option.

\subsection{Old commands}

\begin{decl}
|\samepage|
\end{decl}

The |\samepage| command still exists but is no longer being
maintained.
This is because it only ever worked erratically; it does not
guarantee that there will be no page-breaks within its scope; and
it can cause footnotes and marginals to be wrongly placed.

We recommend using |\enlargethispage| in conjunction with page-break
commands such as |\newpage| and |\pagebreak| to help control page
breaks.

\begin{decl}
   |\SLiTeX|
\end{decl}
Since \SLiTeX{} no longer exists, the logo is no longer defined in the
\LaTeX{} kernel.  A suitable replacement is |\textsc{Sli\TeX}|.  The
\SLiTeX{} logo is defined in \LaTeX~2.09 compatibility mode.

\begin{decl}
|\mho| |\Join| |\Box| |\Diamond| |\leadsto| \\
|\sqsubset| |\sqsupset| |\lhd| |\unlhd| |\rhd| |\unrhd|
\end{decl}

These symbols are contained in the \LaTeX{} symbol font, which was
automatically loaded by \LaTeX~2.09.  However, \TeX{} has room for
only sixteen math font families; thus many users discovered that they
ran out.  Because of this, \LaTeX{} does not load the \LaTeX{} symbol
font unless you use the |latexsym| package.

These symbols are also made available, using different fonts, by the
|amsfonts| package, which also defines a large number of other symbols.
It is supplied by the American Mathematical Society.

The |latexsym| package is loaded automatically in \LaTeX~2.09
compatibility mode.

\section{\LaTeX~2.09 documents}
\label{Sec:209}

\LaTeXe{} can process (almost) any \LaTeX~2.09 document, by entering
\emph{\LaTeX~2.09 compatibility mode}.  Nothing has changed, you run
\LaTeX{} in the same way you always did, and you will get much the
same results.

The reason for the `almost' is that some \LaTeX~2.09 packages made use
of low-level unsupported features of \LaTeX.  If you discover such a
package, you should find out if it has been updated to work with
\LaTeXe.  Most packages will still work with \LaTeXe---the easiest way
to find out whether a package still works is to try it!

\LaTeX~2.09 compatibility mode is a comprehensive emulation of
\LaTeX~2.09, but at the cost of time.  Documents can run up to 50\%
slower in compatibility mode than they did under \LaTeX~2.09.
In addition, many of the new features of \LaTeXe{} are not available in
\LaTeX~2.09 compatibility mode.


\subsection{Font selection problems}
\label{Sec:fsprob}

When using compatibility mode, it is possible that you will find
problems with font-changing commands in some old documents.  These
problems are of two types:

\begin{itemize}
\item producing error messages;
\item not producing the font changes you expected.
\end{itemize}

In case of error messages it is possible that the document (or an old
style file used therein) contains references to old internal commands
which are no longer defined, see Section~\ref{Sec:oldinternals} for
more information if this is the case.


\LaTeX~2.09 allowed sites to customize their \LaTeX{} installation,
which resulted in documents producing different results on different
\LaTeX{} installations.  \LaTeXe{} no longer allows so much
customization but, for compatibility with old documents, the local
configuration file |latex209.cfg| is loaded every time \LaTeXe{}
enters \LaTeX~2.09 compatibility mode.

For example, if your site was customized to use the New Font
Selection Scheme (\NFSS) with the |oldlfont| option, then you can
make \LaTeXe{} emulate this by creating a |latex209.cfg| file
containing the command |\ds@oldlfont|.
Similarly, to emulate \NFSS{} with the |newlfont| option, you can
create a |latex209.cfg| file containing |\ds@newlfont|.

\subsection{Native mode}
\label{Sec:native}

To run an old documents faster, and use the new features of
\LaTeXe, you should try using \emph{\LaTeXe{} native mode}.
This is done by replacing the command:
\begin{quote}
   |\documentstyle[|\m{options}|,|\m{packages}|]|\arg{class}
\end{quote}
with:
\begin{quote}
   |\documentclass|\oarg{options}\arg{class} \\
   |\usepackage{latexsym,|\m{packages}|}|
\end{quote}
However, some documents which can be processed in \LaTeX~2.09
compatibility mode may not work in native mode.  Some \LaTeX~2.09
packages will only work with \LaTeXe{} in 2.09 compatibility mode.
Some documents will cause errors because of \LaTeXe's improved error
detection abilities.

But most \LaTeX~2.09 documents can be processed by \LaTeXe{}'s native
mode with the above change.  Again, the easiest way to find out
whether your documents can be processed in native mode is to try it!

\section{Problems}
\label{Sec:problems}

This section describes some of the things which may go wrong when
using \LaTeXe, and what you can do about it.

\subsection{New error messages}

\LaTeXe{} has a number of new error messages.
Please also note that many error messages now produce further helpful
information if you press |h| in response to the error prompt.

\begin{decl}
|Option clash for package |\m{package}|.|
\end{decl}
The named package has been loaded twice with different options.  If
you enter |h| you will be told what the options were, for example, if
your document contained:
\begin{verbatim}
   \usepackage[foo]{fred}
   \usepackage[baz]{fred}
\end{verbatim}
then you will get the error message:
\begin{verbatim}
   Option clash for package fred.
\end{verbatim}
and typing |h| at the |?| prompt will give you:
\begin{verbatim}
   The package fred has already been loaded with options:
     [foo]
   There has now been an attempt to load it with options:
     [baz]
   Adding the line:
     \usepackage[foo,baz]{fred}
   to your document may fix this.
   Try typing <<return>> to proceed.
\end{verbatim}
The cure is, as suggested, to load the package with both sets of
options.  Note that since \LaTeX{} packages can call other packages,
it is possible to get a package option clash without explicitly
requesting the same package twice.

\begin{decl}
   |Command |\m{command}| not provided in base NFSS.|
\end{decl}
The \m{command} is not provided by default in \LaTeXe.  This error is
generated by using one of the commands:
\begin{verbatim}
   \mho \Join \Box \Diamond \leadsto
   \sqsubset \sqsupset \lhd \unlhd \rhd \unrhd
\end{verbatim}
which are now part of the |latexsym| package.  The cure is to add:
\begin{verbatim}
   \usepackage{latexsym}
\end{verbatim}
in the preamble of your document.

\begin{decl}
   |LaTeX2e command <command> in LaTeX 2.09 document.|
\end{decl}
The \m{command} is a \LaTeXe{} command but this is a \LaTeX~2.09
document.  The cure is to replace the command by a \LaTeX~2.09
command, or to run document in native mode, as described in
Section~\ref{Sec:native}.

\begin{decl}
   |NFSS release 1 command \newmathalphabet found.|
\end{decl}
The command |\newmathalphabet| was used by the New Font Selection
Scheme Release 1 but it has now been replaced by
|\DeclareMathAlphabet|, the use of which is described in
\emph{\fntguide}.

The best cure is to update the package which contained the
|\newmathalphabet| command.  Find out if there is a new release of
the package, or (if you wrote the package yourself) consult
\emph{\fntguide} for the new syntax of font commands.

If there is no updated version of the package then you can cure this
error by using the |newlfont| or |oldlfont| package, which tells
\LaTeX{} which version of |\newmathalphabet| should be emulated.

You should use |oldlfont| if the document selects math fonts with
syntax such as this:
\begin{quote}
  |{\cal A}|, etc.
\end{quote}
Use |newlfont| if the document's syntax is like this:
\begin{quote}
  |\cal{A}|, etc.
\end{quote}


\begin{decl}
   |Text for \verb command ended by end of line.|
\end{decl}
The |\verb| command has been begun but not ended on that line.  This
usually means that you have forgotten to put in the end-character of
the |\verb| command.

\begin{decl}
   |Illegal use of \verb command.|
\end{decl}
The |\verb| command has been used inside the argument of another
command.  This has never been allowed in \LaTeX{}---often producing
incorrect output without any warning---and so \LaTeXe{} produces
an error message.

\subsection{Old internal commands}
\label{Sec:oldinternals}

A number of \LaTeX~2.09 internal commands have been removed, since
their functionality is now provided in a different way.  See
\emph{\clsguide} for more details of the new, supported interface for
class and package writers.

\begin{decl}
   |\tenrm| |\elvrm| |\twlrm| \dots\\
   |\tenbf| |\elvbf| |\twlbf| \dots\\
   |\tensf| |\elvsf| |\twlsf| \dots\\
   $\vdots$
\end{decl}
These commands provided access to the seventy fonts pre-loaded by
\LaTeX~2.09.  In contrast, \LaTeXe{} normally pre-loads at most
fourteen fonts, which saves a lot of font memory; but a consequence is
that any \LaTeX{} file which used the above commands to directly
access fonts will no longer work.

Their use will usually produce an error message such as:
\begin{verbatim}
   ! Undefined control sequence.
   l.5 \tenrm
\end{verbatim}
The cure for this is to update the document to use the new
font-changing commands provided by \LaTeXe; these are described in
\emph{\fntguide}.

If this is not possible then, as a last resort, you can
use the |rawfonts| package, which loads the
seventy \LaTeX~2.09 fonts and provides direct access to them using the
old commands.  This takes both time and memory.  If you do not
wish to load all seventy fonts, you can select some of them by using the
|only| option to |rawfonts|.  For example, to load only |tenrm| and
|tenbf| you write:
\begin{verbatim}
   \usepackage[only,tenrm,tenbf]{rawfonts}
\end{verbatim}

The |rawfonts| package is distributed with the \LaTeX{} tools
software, see Section \ref{Sec:st-pack}.

\subsection{Old files}

One of the more common mistakes in running \LaTeX{} is to read in old
versions of packages instead of the new versions.  If you get an
incomprehensible error message from a standard package, make sure you
are loading the most recent version of the package.  You can find out
which version of the package has been loaded by looking in the log
file for a line like:
\begin{verbatim}
   Package `fred' 1994/06/01 v0.01 Fred's package.
\end{verbatim}
You can use the \m{release-date} options to |\documentclass| and
|\usepackage| to make sure that you are getting a suitably recent copy
of the document class or package.  This is useful when sending a
document to another site, which may have out-of-date software.

\subsection{Where to go for more help}

If you can't find the answer for your problem here, try looking in
\emph{\LaTeXbook} or \emph{\LaTeXcomp}.  If you have a problem with
installing \LaTeX, look in the installation guide files which come with
the distribution.

If this doesn't help, contact your local \LaTeX{} guru or local
\LaTeX{} mailing list.

If you think you've discovered a bug then please report it!  First,
you should find out if the problem is with a third-party package or
class.  If the problem is caused by a package or class other than
those listed in Section~\ref{Sec:class+packages} then please report
the problem to the author of the package or class, not to the \LaTeX3
project team.

If the bug really is with core \LaTeX{} then you should create a
\emph{short}, \emph{self-contained} document which exhibits the
problem.  You should run a \emph{recent} (less than a year old)
version of \LaTeX{} on the file and then run \LaTeX{} on
|latexbug.tex|.  This will create an error report which you should
send, together with the sample document and log file, to the
\LaTeX{} bugs address which can be found in the file
|latexbug.tex| or |bugs.txt|.


\section{Enjoy!}
\label{Sec:enjoy}

We certainly hope you will enjoy using the new standard \LaTeX{} but,
if this is not possible, we hope that you will enjoy success and
fulfilment as a result of the documents which it will help you to
create.

If you find that the contribution of \LaTeX{} to your life is such
that you would like to support the work of the project team, then
please read Section~\ref{Sec:ltx3} and discover practical ways to do
this.

\begin{thebibliography}{1}

\bibitem{A-W:GMS94}
Michel Goossens, Frank Mittelbach and Alexander Samarin.
\newblock {\em The {\LaTeX} Companion}.
\newblock Addison-Wesley, Reading, Massachusetts, 1994.

\bibitem{tub:DKn89}
Donald~E. Knuth.
\newblock Typesetting concrete mathematics.
\newblock {\em {TUG}boat}, 10(1):31--36, April 1989.

\bibitem{A-W:LLa94}
Leslie Lamport.
\newblock {\em {\LaTeX:} A Document Preparation System}.
\newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994.

\end{thebibliography}

\end{document}