path: root/macros/latex/base/clsguide.tex

% \iffalse meta-comment
%
% Copyright (C) 1993-2022
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
% This file is part of the LaTeX base system.
% -------------------------------------------
%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%    http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008 or later.
%
% This file has the LPPL maintenance status "maintained".
%
% The list of all files belonging to the LaTeX base distribution is
% given in the file `manifest.txt'. See also `legal.txt' for additional
% information.
%
% The list of derived (unpacked) files belonging to the distribution
% and covered by LPPL is defined by the unpacking scripts (with
% extension .ins) which are part of the distribution.
%
% \fi
% Filename: clsguide.tex

\NeedsTeXFormat{LaTeX2e}[1995/12/01]

\documentclass{ltxguide}[1995/11/28]

\title{\LaTeXe~for class and package writers}

\author{Copyright \copyright~1995--2006 The \LaTeX\ Project\\
   All rights reserved.%
   \footnote{This file may distributed and/or modified under the
     conditions of the \LaTeX{} Project Public License, either version 1.3c
     of this license or (at your option) any later version. See the source
    \texttt{clsguide.tex} for full details.}%
}

\date{15 February 2006}

\begin{document}

\maketitle

\tableofcontents

\section{Introduction}

This document is an introduction to writing classes and packages for
\LaTeX{}, with special attention given to upgrading existing
\LaTeX~2.09 packages to \LaTeXe{}.  The latter subject is also
covered in an article by Johannes Braams published in TUGboat~15.3.

\subsection{Writing classes and packages for \LaTeXe}

\LaTeX{} is a document preparation system that enables the document
writer to concentrate on the contents of their text, without bothering
too much about the formatting of it.  For example, chapters are
indicated by |\chapter{<title>}| rather than by selecting 18pt bold.

The file that contains the information about how to turn logical
structure (like `|\chapter|') into formatting (like `18pt bold ragged
right') is a \emph{document class}.  In addition, some features (such
as colour or included graphics) are independent of the document class
and these are contained in \emph{packages}.

One of the largest differences between \LaTeX~2.09 and \LaTeXe{} is in
the commands used to write packages and classes.  In \LaTeX~2.09,
there was very little support for writing |.sty| files, and so writers
had to resort to using low-level commands.

\LaTeXe{} provides high-level commands for structuring packages.
It is also much easier to build classes and packages on top of each
other, for example writing a local technical report class |cetechr|
(for the Chemical Engineering department) based on |article|.

\subsection{Overview}

This document contains an overview of how to write classes and
packages for \LaTeX{}.  It does \emph{not} introduce all of the
commands necessary to write packages: these can be found in either
\emph{\LaTeXbook} or \emph{\LaTeXcomp}.  But it does describe the new
commands for structuring classes and packages.

\begin{description}

\item[Section~\ref{Sec:general}] contains some general advice about
  writing classes and packages.  It describes the difference between
  classes and packages, the command naming conventions, the use of
  |doc| and |docstrip|, how \TeX's primitive file and box commands
  interact with \LaTeX{}. It also contains some hints about general
  \LaTeX{} style.

\item[Section~\ref{Sec:structure}] describes the structure of classes
  and packages.  This includes building classes and packages on top of
  other classes and packages, declaring options and declaring
  commands.  It also contains example classes.

\item[Section~\ref{Sec:commands}] lists the new class and package
   commands.

 \item[Section~\ref{Sec:upgrade}] gives detailed advice on how to
   upgrade existing \LaTeX~2.09 classes and packages to \LaTeXe{}.

\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 200 packages and nearly 1000 ready to run examples, is
to be found in \emph{\LaTeXcomp\ second edition} by Frank Mittelbach and
Michel Goossens~\cite{A-W:MG2004}.

The \LaTeX{} system is based on \TeX{}, which is
described in \emph{The \TeX book} by Donald E.~Knuth~\cite{A-W:DEK91}.

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{}, and is found in the files
|ltnews*.tex|.  The author's guide \emph{\usrguide} describes the new
\LaTeX{} document features; it is in |usrguide.tex|.  The guide
\emph{\fntguide} describes the \LaTeX{} font selection scheme for
class- and package-writers; it is in |fntguide.tex|. Configuring
\LaTeX{} is covered by the guide \emph{\cfgguide} in
\texttt{cfgguide.tex} whilst the philosophy behind our policy on
modifying \LaTeX{} is described in \emph{\modguide} in
\texttt{modguide.tex}.

The documented source code (from the files used to produce the kernel
format via |latex.ltx|) is now available as
\emph{The \LaTeXe\ Sources}.
This very large document also includes an index of
\LaTeX{} commands.  It can be typeset from the \LaTeX{} file
|source2e.tex| in the |base| directory, using the source files and
the class file |ltxdoc.cls| from this directory.

For more information about \TeX{} and \LaTeX{}, please contact your
local \TeX{} Users Group, or the international \TeX{} Users Group.
Addresses and other details can be found at:
\begin{quote}\small\label{addrs}
    \texttt{http://www.tug.org/lugs.html}
\end{quote}


\subsection{Policy on standard classes}

Many of the problem reports we receive concerning the standard classes
are not concerned with bugs but are suggesting, more or less politely,
that the design decisions embodied in them are `not optimal' and
asking us to modify them.

There are several reasons why we should not make such changes to these
files.
\begin{itemize}
\item
  However misguided, the current behaviour is clearly what was
  intended when these classes were designed.
\item
  It is not good practice to change such aspects of `standard classes'
  because many people will be relying on them.
\end{itemize}

We have therefore decided not to even consider making such
modifications, nor to spend time justifying that decision.  This does
not mean that we do not agree that there are many deficiencies in the
design of these classes, but we have many tasks with higher priority
than continually explaining why the standard classes for \LaTeX{}
cannot be changed.

We would, of course, welcome the production of better classes, or of
packages that can be used to enhance these classes.  So your first
thought when you consider such a deficiency will, we hope, be ``what
can I do to improve this?''

Similar considerations apply to those parts of the kernel that are
implementing design decisions, many of which should be left to the
class file but are not in the current system.  We realise that in such
cases it is much more difficult for you to rectify the problem
yourself but it is also the case that making such changes in the
kernel would probably be a major project for us; therefore such
enhancements will have to wait for \LaTeX3.

\section{Writing classes and packages}
\label{Sec:writing}

This section covers some general points concerned with writing
\LaTeX{} classes and packages.


\subsection{Old versions}

If you are upgrading an existing \LaTeX~2.09 style file then we
recommend freezing the 2.09 version and no longer maintaining it.
Experience with the various dialects of \LaTeX{} which existed in the
early 1990's suggests that maintaining packages for different versions
of \LaTeX{} is almost impossible.  It will, of course, be necessary
for some organisations to maintain both versions in parallel for some
time but this is not essential for those packages and classes
supported by individuals: they should support only the new standard
\LaTeXe{}, not obsolete versions of \LaTeX{}.


\subsection{Using `docstrip' and `doc'}

If you are going to write a large class or package for \LaTeX{} then
you should consider using the |doc| software which comes with
\LaTeX{}.
\LaTeX{} classes and packages written using this can be
processed in two ways: they can be run through \LaTeX{}, to produce
documentation; and they can be processed with |docstrip|, to produce
the |.cls| or |.sty| file.

The |doc| software can automatically generate indexes of definitions,
indexes of command use, and change-log lists.  It is very useful for
maintaining and documenting large \TeX{} sources.

The documented sources of the \LaTeX{} kernel itself, and of the
standard classes, etc, are |doc| documents; they are in the |.dtx|
files in the distribution.  You can, in fact, typeset the source code
of the kernel as one long document, complete with index, by running
\LaTeX{} on |source2e.tex|.  Typesetting these documents uses the
class file |ltxdoc.cls|.

For more information on |doc| and |docstrip|, consult the files
|docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}.  For examples of its
use, look at the |.dtx| files.

\subsection{Is it a class or a package?}
\label{Sec:classorpkg}

The first thing to do when you want to put some new \LaTeX{} commands
in a file is to decide whether it should be a \emph{document class} or a
\emph{package}.  The rule of thumb is:
\begin{quote}
  If the commands could be used with any document class, then make
  them a package; and if not, then make them a class.
\end{quote}

There are two major types of class: those like |article|, |report| or
|letter|, which are free-standing; and those which are extensions or
variations of other classes---for example, the |proc| document class,
which is built on the |article| document class.

Thus, a company might have a local |ownlet| class for printing letters
with their own headed note-paper.  Such a class would build on top of
the existing |letter| class but it cannot be used with any other
document class, so we have |ownlet.cls| rather than |ownlet.sty|.

The |graphics| package, in contrast, provides commands for including
images into a \LaTeX{} document.  Since these commands can be used
with any document class, we have |graphics.sty| rather than
|graphics.cls|.


\subsection{Command names}

\LaTeX{} has three types of command.

There are the author commands, such as |\section|, |\emph| and
|\times|:  most of these have short names, all in lower case.

There are also the class and package writer commands:
most of these have long mixed-case names such as the following.
\begin{verbatim}
   \InputIfFileExists  \RequirePackage  \PassOptionsToClass
\end{verbatim}

Finally, there are the internal commands used in the \LaTeX{}
implementation, such as |\@tempcnta|, |\@ifnextchar| and |\@eha|:
most of these commands contain |@| in their name, which means they
cannot be used in documents, only in class and package files.

Unfortunately, for historical reasons the distinction between these
commands is often blurred.  For example, |\hbox| is an internal
command which should only be used in the \LaTeX{} kernel, whereas
|\m@ne| is the constant $-1$ and could have been |\MinusOne|.

However, this rule of thumb is still useful: if a command has |@| in
its name then it is not part of the supported \LaTeX{} language---and
its behaviour may change in future releases!  If a command is
mixed-case, or is described in \emph{\LaTeXbook}, then you can rely on
future releases of \LaTeXe{} supporting the command.

\subsection{Box commands and colour}
\label{Sec:colour}

Even if you do not intend to use colour in your own documents, by
taking note of the points in this section you can ensure that your
class or package is compatible with the |color| package. This may
benefit people using your class or package who have access to colour
printers.

The simplest way to ensure `colour safety' is to always use \LaTeX{}
box commands rather than \TeX{} primitives, that is use |\sbox| rather
than |\setbox|, |\mbox| rather than |\hbox| and |\parbox| or
the |minipage| environment rather than |\vbox|.
The \LaTeX{} box commands have new options which mean that they are now
as powerful as the \TeX{} primitives.

As an example of what can go wrong, consider that in
|{\ttfamily <text>}|
the font is restored just \emph{before} the |}|, whereas in the
similar looking construction
|{\color{green} <text>}|
the colour is restored just \emph{after} the final |}|. Normally this
distinction does not matter at all; but consider a primitive \TeX{}
box assignment such as:
\begin{verbatim}
   \setbox0=\hbox{\color{green} <text>}
\end{verbatim}
Now the colour-restore occurs after the |}| and so is \emph{not}
stored in the box. Exactly what bad effects this can have depends on
how colour is implemented: it can range from getting the wrong
colours in the rest of the document, to causing errors in the
dvi-driver used to print the document.

Also of interest is the command |\normalcolor|.   This is
normally just |\relax| (i.e., does nothing)
but you can use it rather like |\normalfont| to
set regions of the page such as captions or section headings to the
`main document colour'.


\subsection{Defining text and math characters}
\label{Sec:chars}

Because \LaTeXe{} supports different encodings, definitions of commands
for producing symbols, accents, composite glyphs, etc.\ must be
defined using the commands provided for this purpose and described in
\emph{\fntguide}.  This part of the system is still under development
so such tasks should be undertaken with great caution.

Also, |\DeclareRobustCommand| should be used for encoding-independent
commands of this type.

Note that it is no longer possible to refer to the math font set-up
outside math mode: for example, neither |\textfont 1| nor
|\scriptfont 2| are guaranteed to be defined in other modes.


\subsection{General style}
\label{Sec:general}

The new system provides many commands designed to help you produce
well-structured class and package files that are both robust and
portable.  This section outlines some ways to make intelligent use of
these.

\subsubsection{Loading other files}
\label{Sec:loading}

\NEWdescription{1995/12/01}
\LaTeX{} provides these commands:
\begin{verbatim}
   \LoadClass        \LoadClassWithOptions
   \RequirePackage   \RequirePackageWithOptions
\end{verbatim}
for using classes or packages inside other classes or packages.  We
recommend strongly that you use them, rather than the primitive
|\input| command, for a number of reasons.

Files loaded with |\input <filename>| will not be listed in the
|\listfiles| list.

If a package is always loaded with |\RequirePackage...| or |\usepackage|
then, even if its loading is requested several times, it will be
loaded only once.  By contrast, if it is loaded with |\input| then it
can be loaded more than once; such an extra loading may waste time and
memory and it may produce strange results.

If a package provides option-processing then, again, strange results
are possible if the package is |\input| rather than loaded by means of
|\usepackage| or |\RequirePackage...|.

If the package |foo.sty| loads the package |baz.sty| by use of
|\input baz.sty| then the user will get a warning:
\begin{verbatim}
   LaTeX Warning: You have requested package `foo',
                  but the package provides `baz'.
\end{verbatim}
Thus, for several reasons, using |\input| to load packages is not a
good idea.

Unfortunately, if you are upgrading the file |myclass.sty| to a class
file then you have to make sure that any old files which contain
|\input myclass.sty| still work.

This was also true for the standard classes (|article|, |book| and
|report|), since a lot of existing \LaTeX~2.09 document styles contain
|\input article.sty|.  The approach which we use to solve this is
to provide minimal files |article.sty|, |book.sty| and |report.sty|,
which simply load the appropriate class files.

For example, |article.sty| contains just the following lines:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \@obsoletefile{article.cls}{article.sty}
   \LoadClass{article}
\end{verbatim}
You may wish to do the same or, if you think that it is safe to do so,
you may decide to just remove |myclass.sty|.

\subsubsection{Make it robust}

We consider it good practice, when writing packages and classes, to use
\LaTeX{} commands as much as possible.

Thus, instead of using |\def...| we recommend using one of
|\newcommand|, |\renewcommand| or |\providecommand|; |\CheckCommand| is
also useful. Doing this makes
it less likely that you will inadvertently redefine a command, giving
unexpected results.

When you define an environment, use |\newenvironment| or
|\renewenvironment| instead |\def\foo{...}| and |\def\endfoo{...}|.

If you need to set or change the value of a \m{dimen} or \m{skip}
register, use |\setlength|.

To manipulate boxes, use \LaTeX{} commands such as |\sbox|,
|\mbox| and |\parbox| rather than |\setbox|, |\hbox| and |\vbox|.

Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the
equivalent class commands) rather than |\@latexerr|, |\@warning| or
|\wlog|.

It is still possible to declare options by defining |\ds@<option>| and
calling |\@options|; but we recommend the |\DeclareOption| and
|\ProcessOptions| commands instead.  These are more powerful and use
less memory.  So rather than using:
\begin{verbatim}
   \def\ds@draft{\overfullrule 5pt}
   \@options
\end{verbatim}
you should use:
\begin{verbatim}
   \DeclareOption{draft}{\setlength{\overfullrule}{5pt}}
   \ProcessOptions\relax
\end{verbatim}

The advantage of this kind of practice is that your code is more
readable and, more important, that it is less likely to break when
used with future versions of \LaTeX{}.

\subsubsection{Make it portable}

It is also sensible to make your files are as portable as possible. To
ensure this; they should contain only visible 7-bit text; and the
filenames should contain at most eight characters (plus the three
letter extension).  Also, of course, it \textbf{must not} have the
same name as a file in the standard \LaTeX{} distribution, however
similar its contents may be to one of these files.

It is also useful if local classes or packages have a common prefix,
for example the University of Nowhere classes might begin with |unw|.
This helps to avoid every University having its own thesis class, all
called |thesis.cls|.

If you rely on some features of the \LaTeX{} kernel, or on a package,
please specify the release-date you need.  For example, the package
error commands were introduced in the June 1994 release so, if you use
them then you should put:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}[1994/06/01]
\end{verbatim}

\subsubsection{Useful hooks}

Some packages and document styles had to redefine the command
|\document| or |\enddocument| to achieve their goal.  This is no
longer necessary. You can now use the `hooks' |\AtBeginDocument| and
|\AtEndDocument| (see Section~\ref{Sec:delays}).  Again, using these
hooks makes it less likely that your code breaks with future versions
of \LaTeX{}. It also makes it more likely that your package can work
together with someone else's.

\NEWdescription{1996/12/01}
However, note that code in the |\AtBeginDocument| hook is part of the
preamble.  Thus there are restrictions on what can be put there; in
particular, no typesetting can be done.

\section{The structure of a class or package}
\label{Sec:structure}

\LaTeXe{} classes and packages have more structure than \LaTeX~2.09
style files did.  The outline of a class or package file is:
\begin{description}
\item[Identification] The file says that it is a \LaTeXe{} package or
   class, and gives a short description of itself.
\item[Preliminary declarations]
   Here the file declares some commands and can also load
   other files.  Usually these commands will be just those needed for
   the code used in the declared options.
\item[Options] The file declares and processes its options.
\item[More declarations] This is where the file does most of its work:
   declaring new variables, commands and fonts; and loading other files.
\end{description}

\subsection{Identification}

The first thing a class or package file does is identify itself.
Package files do this as follows:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesPackage{<package>}[<date> <other information>]
\end{verbatim}
For example:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesPackage{latexsym}[1994/06/01 Standard LaTeX package]
\end{verbatim}
Class files do this as follows:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{<class-name>}[<date> <other information>]
\end{verbatim}
For example:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{article}[1994/06/01 Standard LaTeX class]
\end{verbatim}
\NEWdescription{1998/06/19}
The \m{date} should be given in the form `\textsc{yyyy/mm/dd}' and
must be present if the optional argument is used (this is also true
for the |\NeedsTeXFormat| command).
Any derivation from this syntax will result in low-level \TeX{}
errors---the commands expect a valid syntax to speed up the daily
usage of the package or class and make no provision for the case that
the developer made a mistake!

This date is checked whenever a user specifies a date in their
|\documentclass| or |\usepackage| command.  For example, if you wrote:
\begin{verbatim}
   \documentclass{article}[1995/12/23]
\end{verbatim}
then users at a different location
would get a warning that their copy of |article| was out of
date.

The description of a class is displayed when the class is used.  The
description of a package is put into the log file.  These descriptions
are also displayed by the |\listfiles| command.  The phrase
\texttt{Standard LaTeX} \textbf{must not} be used in the identification
banner of any file other than those in the standard \LaTeX{}
distribution.


\subsection{Using classes and packages}

The first major difference between \LaTeX~2.09 style files and
\LaTeXe{} packages and classes is that \LaTeXe{} supports
\emph{modularity}, in the sense of building files from small
building-blocks rather than using large single files.

A \LaTeX{} package or class can load a package as follows:
\begin{verbatim}
   \RequirePackage[<options>]{<package>}[<date>]
\end{verbatim}
For example:
\begin{verbatim}
   \RequirePackage{ifthen}[1994/06/01]
\end{verbatim}
This command has the same syntax as the author command |\usepackage|.
It allows packages or classes to use features provided by other
packages.  For example, by loading the |ifthen| package, a package
writer can use the `if\dots then\dots else\dots' commands provided
by that package.

A \LaTeX{} class can load one other class as follows:
\begin{verbatim}
   \LoadClass[<options>]{<class-name>}[<date>]
\end{verbatim}
For example:
\begin{verbatim}
   \LoadClass[twocolumn]{article}
\end{verbatim}
This command has the same syntax as the author command |\documentclass|.
It allows classes to be based on the syntax and appearance of another
class.  For example, by loading the |article| class, a class writer
only has to change the bits of |article| they don't like, rather than
writing a new class from scratch.

\NEWfeature{1995/12/01}
The following commands can be used in the common case that you want to
simply load a class or package file with exactly those options that
are being used by the current class.
\begin{verbatim}
   \LoadClassWithOptions{<class-name>}[<date>]
   \RequirePackageWithOptions{<package>}[<date>]
\end{verbatim}
For example:
\begin{verbatim}
   \LoadClassWithOptions{article}
   \RequirePackageWithOptions{graphics}[1995/12/01]
\end{verbatim}

\subsection{Declaring options}

\NEWdescription{1998/12/01}
The other major difference between \LaTeX~2.09 styles and \LaTeXe{}
packages and classes is in option handling.  Packages and classes can
now declare options and these can be specified by authors; for
example, the |twocolumn| option is declared by the |article| class.
Note that the name of an option should contain only those characters
allowed in a `\LaTeX{} name'; in particular it must not contain any
control sequences.

An option is declared as follows:
\begin{verbatim}
   \DeclareOption{<option>}{<code>}
\end{verbatim}
For example, the |dvips| option (slightly simplified)
to the |graphics| package is implemented as:
\begin{verbatim}
   \DeclareOption{dvips}{\input{dvips.def}}
\end{verbatim}
This means that when an author writes |\usepackage[dvips]{graphics}|,
the file |dvips.def| is loaded.  As another example, the |a4paper|
option is declared in the |article| class to set the |\paperheight|
and |\paperwidth| lengths:
\begin{verbatim}
   \DeclareOption{a4paper}{%
      \setlength{\paperheight}{297mm}%
      \setlength{\paperwidth}{210mm}%
   }
\end{verbatim}
Sometimes a user will request an option which the class
or package has not explicitly declared.  By default this will produce
a warning (for classes) or error (for packages); this behaviour
can be altered as follows:
\begin{verbatim}
   \DeclareOption*{<code>}
\end{verbatim}
For example, to make the package |fred| produce a warning rather than
an error for unknown options, you could specify:
\begin{verbatim}
   \DeclareOption*{%
      \PackageWarning{fred}{Unknown option `\CurrentOption'}%
   }
\end{verbatim}
Then, if an author writes |\usepackage[foo]{fred}|, they will get a
warning \texttt{Package fred Warning: Unknown option `foo'.}  As
another example, the |fontenc| package tries to load a file
|<ENC>enc.def| whenever the \m{ENC} option is used.  This
can be done by writing:
\begin{verbatim}
   \DeclareOption*{%
      \input{\CurrentOption enc.def}%
   }
\end{verbatim}
\NEWdescription{1998/12/01}
It is possible to pass options on to another package or class, using
the command |\PassOptionsToPackage| or |\PassOptionsToClass| (note
that this is a specialised operation that works only for option
names).  For example, to pass every unknown option on to the |article|
class, you can use:
\begin{verbatim}
   \DeclareOption*{%
      \PassOptionsToClass{\CurrentOption}{article}%
   }
\end{verbatim}
If you do this then you should make sure you load the class at some
later point, otherwise the options will never be processed!

So far, we have explained only how to declare options, not how to
execute them.  To process the options with which the file was called,
you should use:
\begin{verbatim}
   \ProcessOptions\relax
\end{verbatim}
This executes the \m{code} for each option that was both specified and
declared (see Section~\ref{Sec:commands.options} for details of how
this is done).

For example, if the |jane| package file contains:
\begin{verbatim}
   \DeclareOption{foo}{\typeout{Saw foo.}}
   \DeclareOption{baz}{\typeout{Saw baz.}}
   \DeclareOption*{\typeout{What's \CurrentOption?}}
   \ProcessOptions\relax
\end{verbatim}
and an author writes |\usepackage[foo,bar]{jane}|, then they will see
the messages \texttt{Saw foo.} and \texttt{What's bar?}

\subsection{A minimal class file}

Most of the work of a class or package is in defining new commands, or
changing the appearance of documents.  This is done in the body of the
package, using commands such as |\newcommand| or |\setlength|.

\LaTeXe{} provides several new commands to help class and package
writers; these are described in detail in Section~\ref{Sec:commands}.

There are four things that every class file \emph{must} contain: these
are a definition of |\normalsize|, values for |\textwidth| and
|\textheight| and a specification for page-numbering.  So a minimal
document class file\footnote {This class is now in the standard
distribution, as \texttt{minimal.cls}.} looks like this:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{minimal}[1995/10/30 Standard LaTeX minimal class]
   \renewcommand{\normalsize}{\fontsize{10pt}{12pt}\selectfont}
   \setlength{\textwidth}{6.5in}
   \setlength{\textheight}{8in}
   \pagenumbering{arabic}       % needed even though this class will
                                % not show page numbers
\end{verbatim}
However, this class file will not support footnotes, marginals,
floats, etc., nor will it provide any of the 2-letter font commands
such as |\rm|; thus most classes will contain more than this minimum!

\subsection{Example: a local letter class}

A company may have its own letter class, for setting letters in the
company style.  This section shows a simple implementation of such a
class, although a real class would need more structure.

The class begins by announcing itself as |neplet.cls|.
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{neplet}[1995/04/01 NonExistent Press letter class]
\end{verbatim}
Then this next bit passes any options on to the |letter| class, which
is loaded with the |a4paper| option.
\begin{verbatim}
   \DeclareOption*{\PassOptionsToClass{\CurrentOption}{letter}}
   \ProcessOptions\relax
   \LoadClass[a4paper]{letter}
\end{verbatim}
In order to use the company letter head, it redefines the
|firstpage| page style: this is the page style that is used on
the first page of letters.
\begin{verbatim}
   \renewcommand{\ps@firstpage}{%
      \renewcommand{\@oddhead}{<letterhead goes here>}%
      \renewcommand{\@oddfoot}{<letterfoot goes here>}%
   }
\end{verbatim}
And that's it!

\subsection{Example: a newsletter class}

A simple newsletter can be typeset with \LaTeX{}, using a variant of the
|article| class.
The class begins by announcing itself as |smplnews.cls|.
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{smplnews}[1995/04/01 The Simple News newsletter class]

   \newcommand{\headlinecolor}{\normalcolor}
\end{verbatim}
It passes most specified options on to the |article| class: apart from
the |onecolumn| option, which is switched off, and the |green| option,
which sets the headline in green.
\begin{verbatim}
   \DeclareOption{onecolumn}{\OptionNotUsed}
   \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}}

   \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}

   \ProcessOptions\relax
\end{verbatim}
It then loads the class |article| with the option |twocolumn|.
\begin{verbatim}
   \LoadClass[twocolumn]{article}
\end{verbatim}
Since the newsletter is to be printed in colour, it now loads the
|color| package.  The class does not specify a device driver option
since this should be specified by the user of the |smplnews| class.
\begin{verbatim}
   \RequirePackage{color}
\end{verbatim}
The class then redefines |\maketitle| to produce the title in 72pt
Helvetica bold oblique, in the appropriate colour.
\begin{verbatim}
   \renewcommand{\maketitle}{%
      \twocolumn[%
         \fontsize{72}{80}\fontfamily{phv}\fontseries{b}%
         \fontshape{sl}\selectfont\headlinecolor
         \@title
      ]%
   }
\end{verbatim}
It redefines |\section| and switches off section numbering.
\begin{verbatim}
   \renewcommand{\section}{%
      \@startsection
         {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}%
         {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}%
   }

   \setcounter{secnumdepth}{0}
\end{verbatim}
It also sets the three essential things.
\begin{verbatim}
   \renewcommand{\normalsize}{\fontsize{9}{10}\selectfont}
   \setlength{\textwidth}{17.5cm}
   \setlength{\textheight}{25cm}
\end{verbatim}
In practice, a class would need more than this: it would provide
commands for issue numbers, authors of articles, page styles and so
on; but this skeleton gives a start.  The |ltnews| class file is not
much more complex than this one.

\section{Commands for class and package writers}
\label{Sec:commands}

This section describes briefly each of the new commands for class and
package writers.  To find out about other aspects of the new system,
you should also read \emph{\LaTeXbook}, \emph{\LaTeXcomp} and
\emph{\usrguide}.

\subsection{Identification}

The first group of commands discussed here are those used
to identify your class or package file.

\begin{decl}
|\NeedsTeXFormat| \arg{format-name} \oarg{release-date}
\end{decl}
This command tells \TeX{} that this file should be processed using a
format with name \m{format-name}.  You can use the optional argument
\m{release-date} to further specify the earliest release date of the
format that is needed.  When the release date of the format is older
than the one specified a warning will be generated. The standard
\m{format-name} is \texttt{LaTeX2e}.  The date, if present, must be in
the form \textsc{yyyy/mm/dd}.

Example:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}[1994/06/01]
\end{verbatim}

\begin{decl}
|\ProvidesClass| \arg{class-name} \oarg{release-info} \\
|\ProvidesPackage| \arg{package-name} \oarg{release-info}
\end{decl}
This declares that the current file contains the definitions for the
document class \m{class-name} or package \m{package-name}.

The optional \m{release-info}, if used, must contain:
\begin{itemize}
  \item the release date of
  this version of the file, in the form \textsc{yyyy/mm/dd};
\item optionally followed by a space and a short description, possibly
  including a version number.
\end{itemize}
The above syntax must be followed exactly so that this information
can be used by |\LoadClass| or |\documentclass| (for classes) or
|\RequirePackage| or |\usepackage| (for packages) to test that the
release is not too old.

The whole of this \m{release-info} information is displayed by
|\listfiles| and should therefore not be too long.

Example:
\begin{verbatim}
   \ProvidesClass{article}[1994/06/01 v1.0 Standard LaTeX class]
   \ProvidesPackage{ifthen}[1994/06/01 v1.0 Standard LaTeX package]
\end{verbatim}

\begin{decl}
  |\ProvidesFile| \arg{file-name} \oarg{release-info}
\end{decl}
This is similar to the two previous commands except that here the full
filename, including the extension, must be given. It is used for
declaring any files other than main class and package files.

Example:
\begin{verbatim}
   \ProvidesFile{T1enc.def}[1994/06/01 v1.0 Standard LaTeX file]
\end{verbatim}

Note that the phrase \texttt{Standard LaTeX} \textbf{must not} be used
in the identification banner of any file other than those in the
standard \LaTeX{} distribution.

\subsection{Loading files}
\label{Sec:loadf}

\NEWfeature{1995/12/01}
This group of commands can be used to create your own document class or
package by building on existing classes or packages.
\begin{decl}
  |\RequirePackage| \oarg{options-list} \arg{package-name}
     \oarg{release-info}\\
  |\RequirePackageWithOptions| \arg{package-name}
     \oarg{release-info}
\end{decl}
Packages and classes should use these commands to load other packages.

The use of |\RequirePackage| is the same as the author command
|\usepackage|.

Examples:
\begin{verbatim}
   \RequirePackage{ifthen}[1994/06/01]
   \RequirePackageWithOptions{graphics}[1995/12/01]
\end{verbatim}

\begin{decl}
  |\LoadClass| \oarg{options-list} \arg{class-name}
     \oarg{release-info}\\
  |\LoadClassWithOptions| \arg{class-name}
     \oarg{release-info}
\end{decl}
\NEWfeature{1995/12/01}
These commands are for use \emph{only} in class files, they cannot be
used in packages files;
they can be used at most once within a class file.

The use of |\LoadClass| is the same as
the use of |\documentclass| to load a class file.

Examples:
\begin{verbatim}
   \LoadClass{article}[1994/06/01]
   \LoadClassWithOptions{article}[1995/12/01]
\end{verbatim}

\NEWfeature{1995/12/01}
The two |WithOptions| versions simply load the class (or package) file
with exactly those options that are being used by the current file
(class or package).  See below, in \ref{Sec:opmove}, for further
discussion of their use.


\subsection{Option declaration}
\label{Sec:commands.options.dec}

\NEWdescription{1998/12/01}
The following commands deal with the declaration and handling of
options to document classes and packages.  Every option name must be a
`\LaTeX{} name'.

There are some commands designed especially for use within the
\m{code} argument of these commands (see below).

\begin{decl}
  |\DeclareOption| \arg{option-name} \arg{code}
\end{decl}
This makes \m{option-name} a `declared option' of the class or package
in which it is put.

The \m{code} argument contains the code to be executed if that option
is specified for the class or package; it can contain any valid
\LaTeXe{} construct.

Example:
\begin{verbatim}
   \DeclareOption{twoside}{\@twosidetrue}
\end{verbatim}

\begin{decl}
  |\DeclareOption*| \arg{code}
\end{decl}
This declares the \m{code} to be executed for every option which is
specified for, but otherwise not explicitly declared by, the class or
package; this code is called the `default option code' and it can
contain any valid \LaTeXe{} construct.

If a class file contains no |\DeclareOption*| then, by default, all
specified but undeclared options for that class will be silently
passed to all packages (as will the specified and declared options for
that class).

If a package file contains no |\DeclareOption*| then, by default, each
specified but undeclared option for that package will produce an error.


\subsection{Commands within option code}
\label{Sec:within.code}

These two commands can be used only within the \m{code} argument of
either |\DeclareOption| or |\DeclareOption*|.  Other commands commonly
used within these arguments can be found in the next few subsections.

\begin{decl}
  |\CurrentOption|
\end{decl}
This expands to the name of the current option.

\begin{decl}
  |\OptionNotUsed|
\end{decl}
This causes the current option to
be added to the list of `unused options'.

\NEWfeature{1995/06/01}
  You can now include hash marks (\texttt{\#}) within these \m{code}
  arguments without special treatment (formerly, it had been
  necessary to double them).

\subsection{Moving options around}
\label{Sec:opmove}

These two commands are also very useful within the \m{code} argument
of |\DeclareOption| or |\DeclareOption*|:
\begin{decl}
  |\PassOptionsToPackage| \arg{options-list} \arg{package-name}\\
  |\PassOptionsToClass| \arg{options-list} \arg{class-name}
\end{decl}
The command |\PassOptionsToPackage| passes the option names in
\m{options-list} to package \m{package-name}.
This means that it adds the \m{option-list} to the
list of options used by any future |\RequirePackage| or |\usepackage|
command for package \m{package-name}.

Example:
\begin{verbatim}
   \PassOptionsToPackage{foo,bar}{fred}
   \RequirePackage[baz]{fred}
\end{verbatim}
is the same as:
\begin{verbatim}
   \RequirePackage[foo,bar,baz]{fred}
\end{verbatim}

Similarly, |\PassOptionsToClass| may be used in a class file to pass
options to another class to be loaded with |\LoadClass|.

\NEWdescription{1995/12/01}
The effects and use of these two commands should be contrasted with
those of the following two (documented above, in \ref{Sec:loadf}):
\begin{verbatim}
   \LoadClassWithOptions
   \RequirePackageWithOptions
\end{verbatim}
The command |\RequirePackageWithOptions| is similar to
|\RequirePackage|, but it always loads the required package with
exactly the same option list as that being used by the current class
or package, rather than with any option explicitly supplied or passed
on by |\PassOptionsToPackage|.

The main purpose of |\LoadClassWithOptions| is to allow one class to
simply build on another, for example:
\begin{verbatim}
  \LoadClassWithOptions{article}
\end{verbatim}
This should be compared with the slightly different construction
\begin{verbatim}
  \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
  \ProcessOptions\relax
  \LoadClass{article}
\end{verbatim}
As used above, the effects are more or less the same, but the first is
a lot less to type; also the |\LoadClassWithOptions| method runs
slightly quicker.

If, however, the class declares options of its own then
the two constructions are different.  Compare, for example:
\begin{verbatim}
  \DeclareOption{landscape}{\@landscapetrue}
  \ProcessOptions\relax
  \LoadClassWithOptions{article}
\end{verbatim}
with:
\begin{verbatim}
  \DeclareOption{landscape}{\@landscapetrue}
  \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
  \ProcessOptions\relax
  \LoadClass{article}
\end{verbatim}
In the first example, the \textsf{article} class will be loaded with
option |landscape| precisely when the current class is called with
this option. By contrast, in the second example it will never be
called with option \texttt{landscape} as in that case \textsf{article}
is passed options only by the default option handler, but this handler
is not used for |landscape| because that option is explicitly
declared.

\subsection{Delaying code}
\label{Sec:delays}

These first two commands are also intended primarily for use within
the \m{code} argument of |\DeclareOption| or |\DeclareOption*|.

\begin{decl}
  |\AtEndOfClass| \arg{code}\\
  |\AtEndOfPackage| \arg{code}
\end{decl}
These commands declare \m{code} that is saved away internally and then
executed after processing the whole of the current class or package
file.

Repeated use of these commands is permitted: the code in the
arguments is stored (and later executed) in the order of their
declarations.

\begin{decl}
  |\AtBeginDocument| \arg{code}\\
  |\AtEndDocument| \arg{code}
\end{decl}
These commands declare \m{code} to be saved internally and executed
while \LaTeX{} is executing |\begin{document}| or |\end{document}|.

The \m{code} specified in the argument to |\AtBeginDocument| is
executed near the end of the |\begin{document}| code, \emph{after} the
font selection tables have been set up.  It is therefore a useful
place to put code which needs to be executed after everything has been
prepared for typesetting and when the normal font for the document is
the current font.

\NEWdescription{1995/12/01}
The |\AtBeginDocument| hook should not be used for code that does any
typesetting since the typeset result would be unpredictable.

The \m{code} specified in the argument to |\AtEndDocument| is
executed at the beginning of the |\end{document}| code,
\emph{before} the final page is finished and before any leftover
floating environments are processed. If some of the \m{code} is to be
executed after these two processes, you should include a |\clearpage|
at the appropriate point in \m{code}.

Repeated use of these commands is permitted: the code in the
arguments is stored (and later executed) in the order of their
declarations.

\begin{decl}[1994/12/01]
  |\AtBeginDvi| \arg{specials}
\end{decl}
These commands save in a box register things which are written to the
|.dvi| file at the beginning of the `shipout' of the first page of the
document.

This should not be used for anything that will add any typeset
material to the |.dvi| file.

Repeated use of this command is permitted.


\subsection{Option processing}
\label{Sec:commands.options}

\begin{decl}
  |\ProcessOptions|
\end{decl}
This command executes the \m{code} for each selected option.

We shall first describe how |\ProcessOptions| works in a package file,
and then how this differs in a class file.

To understand in detail what |\ProcessOptions| does in a package file,
you have to know the difference between \emph{local} and \emph{global}
options.
\begin{itemize}
\item \textbf{Local options} are those which have been explicitly
  specified for this particular package in the \m{options} argument of
  any of these:
\begin{quote}
    |\PassOptionsToPackage{<options>}| \ |\usepackage[<options>]|\\
    |\RequirePackage[<options>]|
\end{quote}
\item \textbf{Global options} are any other options that are specified
  by the author in the \m{options} argument of
    |\documentclass[<options>]|.
\end{itemize}
For example, suppose that a document begins:
\begin{verbatim}
   \documentclass[german,twocolumn]{article}
   \usepackage{gerhardt}
\end{verbatim}
whilst package |gerhardt| calls package |fred| with:
\begin{verbatim}
   \PassOptionsToPackage{german,dvips,a4paper}{fred}
   \RequirePackage[errorshow]{fred}
\end{verbatim}
then:
\begin{itemize}
\item |fred|'s local options are |german|, |dvips|, |a4paper|
  and |errorshow|;
\item |fred|'s only global option is |twocolumn|.
\end{itemize}

When |\ProcessOptions| is called, the following happen.
\begin{itemize}
\item \emph{First}, for each option so far declared in |fred.sty|
  by |\DeclareOption|, it looks to see if that option is either a
  global or a local option for |fred|: if it is then the corresponding
  code is executed.

  This is done in the order in which these options
  were declared in |fred.sty|.
\item \emph{Then}, for each remaining \emph{local} option, the command
  |\ds@<option>| is executed if it has been defined somewhere (other
  than by a |\DeclareOption|); otherwise, the `default option code' is
  executed.  If no default option code has been declared then an error
  message is produced.

  This is done in the order in which these
  options were specified.
\end{itemize}
Throughout this process, the system ensures that the code declared for
an option is executed at most once.

Returning to the example, if |fred.sty| contains:
\begin{verbatim}
   \DeclareOption{dvips}{\typeout{DVIPS}}
   \DeclareOption{german}{\typeout{GERMAN}}
   \DeclareOption{french}{\typeout{FRENCH}}
   \DeclareOption*{\PackageWarning{fred}{Unknown `\CurrentOption'}}
   \ProcessOptions\relax
\end{verbatim}
then the result of processing this document will be:
\begin{verbatim}
   DVIPS
   GERMAN
   Package fred Warning: Unknown `a4paper'.
   Package fred Warning: Unknown `errorshow'.
\end{verbatim}
Note the following:

\begin{itemize}
\item the code for the |dvips| option is executed before that for the
  |german| option, because that is the order in which they are declared
  in |fred.sty|;
\item the code for the |german| option is executed only once, when the
  declared options are being processed;
\item the |a4paper| and |errorshow| options produce the warning from
  the code declared by |\DeclareOption*| (in the order in which they
  were specified), whilst the |twocolumn| option does not: this is
  because |twocolumn| is a global option.
\end{itemize}

In a class file, |\ProcessOptions| works in the same way, except
that: \emph{all} options are local; and the default value for
|\DeclareOption*| is |\OptionNotUsed| rather than an error.

\NEWdescription{1995/12/01}
Note that, because |\ProcessOptions| has a |*|-form, it is wise to
follow the non-star form with |\relax|, as in the previous examples,
since this prevents unnecessary look ahead and possibly misleading
error messages being issued.

\begin{decl}
  |\ProcessOptions*| \\
  |\@options|
\end{decl}
This is like |\ProcessOptions| but it executes the options in the
order specified in the calling commands, rather than in the order of
declaration in the class or package. For a package this means that the
global options are processed first.

The |\@options| command from \LaTeX~2.09 has been made equivalent to
this in order to ease the task of updating old document styles to
\LaTeXe{} class files.

\begin{decl}
  |\ExecuteOptions| \arg{options-list}
\end{decl}

For each option in the \m{options-list}, in order,
this command simply executes the command
|\ds@<option>| (if this command is not defined, then that option is
silently ignored).

It can be used to provide a `default option list' just before
|\ProcessOptions|.  For example, suppose that in a class file you want
to set up the default design to be: two-sided printing; 11pt fonts;
in two columns. Then it could specify:
\begin{verbatim}
   \ExecuteOptions{11pt,twoside,twocolumn}
\end{verbatim}


\subsection{Safe file commands}

These commands deal with file input; they ensure that the non-existence
of a requested file can be handled in a user-friendly way.

\begin{decl}
|\IfFileExists| \arg{file-name} \arg{true} \arg{false}
\end{decl}
If the file exists then the code specified in \m{true} is
executed.

If the file does not exist then the code specified in \m{false} is
executed.

This command does \emph{not} input the file.

\begin{decl}
  |\InputIfFileExists| \arg{file-name} \arg{true} \arg{false}
\end{decl}
This inputs the file \m{file-name} if it exists and, immediately
before the input, the code specified in \m{true} is executed.

If the file does not exist then the code specified in \m{false} is
executed.

It is implemented using |\IfFileExists|.


\subsection{Reporting errors, etc}

These commands should be used by third party classes and packages to
report errors, or to provide information to authors.

\begin{decl}
  |\ClassError| \arg{class-name} \arg{error-text} \arg{help-text}\\
  |\PackageError| \arg{package-name} \arg{error-text} \arg{help-text}
\end{decl}
These produce an error message.  The \m{error-text} is displayed and the
|?| error prompt is shown.  If the user types |h|, they will be shown
the \m{help-text}.

Within the \m{error-text} and \m{help-text}: |\protect| can be used to
stop a command from expanding; |\MessageBreak| causes a line-break;
and |\space| prints a space.

Note that the \m{error-text} will have a full stop added to it, so do
not put one into the argument.

For example:
\begin{verbatim}
   \newcommand{\foo}{FOO}
   \PackageError{ethel}{%
      Your hovercraft is full of eels,\MessageBreak
      and \protect\foo\space is \foo
   }{%
      Oh dear! Something's gone wrong.\MessageBreak
      \space \space Try typing \space <<return>>
      \space to proceed, ignoring \protect\foo.
   }
\end{verbatim}
produces this display:
\begin{verbatim}
   ! Package ethel Error: Your hovercraft is full of eels,
   (ethel)                and \foo is FOO.

   See the ethel package documentation for explanation.
\end{verbatim}
If the user types |h|, this will be shown:
\begin{verbatim}
   Oh dear! Something's gone wrong.
     Try typing  <<return>>  to proceed, ignoring \foo.
\end{verbatim}

\begin{decl}
  |\ClassWarning| \arg{class-name} \arg{warning-text}\\
  |\PackageWarning| \arg{package-name} \arg{warning-text}\\
  |\ClassWarningNoLine| \arg{class-name} \arg{warning-text}\\
  |\PackageWarningNoLine| \arg{package-name} \arg{warning-text}\\
  |\ClassInfo| \arg{class-name} \arg{info-text}\\
  |\PackageInfo| \arg{package-name} \arg{info-text}
\end{decl}
The four |Warning| commands are similar to the error commands, except
that they produce only a warning on the screen, with no error prompt.

The first two, |Warning| versions, also show the line number where the
warning occurred, whilst the second two, |WarningNoLine| versions, do
not.

The two |Info| commands are similar except that they log the
information only in the transcript file, including the line number.
There are no |NoLine| versions of these two.

Within the \m{warning-text} and \m{info-text}: |\protect| can be used to
stop a command from expanding; |\MessageBreak| causes a line-break;
and |\space| prints a space.
Also, these should not end with a full stop as one is
automatically added.


\subsection{Defining commands}
\label{Sec:commands.define}

\LaTeXe{} provides some extra methods of (re)defining commands that are
intended for use in class and package files.

\NEWfeature{1994/12/01}
The \texttt{*}-forms of these commands should be used to define
commands that are not, in \TeX{} terms, long.  This can be useful for
error-trapping with commands whose arguments are not intended to
contain whole paragraphs of text.

\begin{decl}
  |\DeclareRobustCommand| \arg{cmd} \oarg{num} \oarg{default}
     \arg{definition}\\
  |\DeclareRobustCommand*| \arg{cmd} \oarg{num} \oarg{default}
     \arg{definition}
\end{decl}
This command takes the same arguments as |\newcommand| but it declares
a robust command, even if some code within the \m{definition} is
fragile.  You can use this command to define new robust commands, or
to redefine existing commands and make them robust.  A log is put into
the transcript file if a command is redefined.

For example, if |\seq| is defined as follows:
\begin{verbatim}
   \DeclareRobustCommand{\seq}[2][n]{%
     \ifmmode
       #1_{1}\ldots#1_{#2}%
     \else
       \PackageWarning{fred}{You can't use \protect\seq\space in text}%
     \fi
   }
\end{verbatim}
Then the command |\seq| can be used in moving arguments, even though
|\ifmmode| cannot, for example:
\begin{verbatim}
   \section{Stuff about sequences $\seq{x}$}
\end{verbatim}

Note also that there is no need to put a |\relax| before the
|\ifmmode| at the beginning of the definition; this is because the
protection given by this |\relax| against expansion at the wrong time
will be provided internally.

\begin{decl}
  |\CheckCommand| \arg{cmd} \oarg{num} \oarg{default}
     \arg{definition}\\
  |\CheckCommand*| \arg{cmd} \oarg{num} \oarg{default}
     \arg{definition}
\end{decl}
This takes the same arguments as |\newcommand| but, rather than define
\m{cmd}, it just checks that the current definition of \m{cmd} is
exactly as given by \m{definition}.  An error is raised if these
definitions differ.

This command is useful for checking the state of the system before
your package starts altering the definitions of commands.  It allows
you to check, in particular, that no other package has redefined the
same command.

\subsection{Moving arguments}

\NEWdescription{1994/12/01}
The setting of protect whilst processing (i.e.~moving) moving arguments
has been reimplemented, as has the method of writing information from
the |.aux| file to other files such as the |.toc| file.  Details can
be found in the file |ltdefns.dtx|.

We hope that these changes will not affect many packages.

\section{Miscellaneous commands, etc}
\label{Sec:commands.misc}

\subsection{Layout parameters}

\begin{decl}
|\paperheight|\\
|\paperwidth|
\end{decl}
These two parameters are usually set by the class to be the size of
the paper being used. This should be actual paper size, unlike
|\textwidth| and |\textheight| which are the size of the main text
body within the margins.


\subsection{Case changing}
\label{sec:case}

\begin{decl}
  |\MakeUppercase| \arg{text} \\
  |\MakeLowercase| \arg{text}
\end{decl}

\NEWfeature{1995/06/01}
\TeX{} provides two primitives |\uppercase| and |\lowercase| for
changing the case of text.  These are sometimes used in document
classes, for example to set information in running heads in all
capitals.

Unfortunately, these \TeX{} primitives do not change the case of
characters accessed by commands like |\ae| or |\aa|.  To overcome this
problem, \LaTeX{} provides two new commands |\MakeUppercase| and
|\MakeLowercase| to do this.

For example:
\begin{quotation}
\begin{tabular}{rl}
   |\uppercase{aBcD\ae\AA\ss\OE}| & \uppercase{aBcD\ae\AA\ss\OE}\\
   |\lowercase{aBcD\ae\AA\ss\OE}| & \lowercase{aBcD\ae\AA\ss\OE}\\
   |\MakeUppercase{aBcD\ae\AA\ss\OE}| &
                                      \MakeUppercase{aBcD\ae\AA\ss\OE}\\
   |\MakeLowercase{aBcD\ae\AA\ss\OE}| & \MakeLowercase{aBcD\ae\AA\ss\OE}
\end{tabular}
\end{quotation}

The commands |\MakeUppercase| and |\MakeLowercase| themselves are
robust, but they have moving arguments.

The commands use the \TeX{} primitives |\uppercase| and |\lowercase|,
and so have a number of unexpected `features'.  In particular, they
change the case of everything (except characters in the names of
control-sequences) in their text argument: this includes mathematics,
environment names, and label names.

For example:
\begin{verbatim}
   \MakeUppercase{$x+y$ in \ref{foo}}
\end{verbatim}
produces $X+Y$ and the warning:
\begin{verbatim}
   LaTeX Warning: Reference `FOO' on page ... undefined on ...
\end{verbatim}
In the long run, we would like to use all-caps fonts rather than any
command like |\MakeUppercase| but this is not possible at the moment
because such fonts do not exist.

\NEWdescription{1995/12/01}
In order that upper/lower-casing will work reasonably well, and in
order to provide any correct hyphenation, \LaTeXe{} \emph{must} use,
throughout a document, the same fixed table for changing case.
The table used is designed for the font encoding |T1|; this works well
with the standard \TeX{} fonts for all Latin alphabets but will cause
problems when using other alphabets.

\subsection{The `openany' option in the `book' class}

\NEWdescription{1996/06/01}
The |openany| option allows chapter and similar openings to
occur on left hand pages. Previously this option affected only
|\chapter| and |\backmatter|.  It now also affects
|\part|, |\frontmatter| and |\mainmatter|.

\subsection{Better user-defined math display environments}

\begin{decl}
  |\ignorespacesafterend|
\end{decl}

\NEWfeature{1996/12/01}
\NEWdescription{2003/12/01}
Suppose that you want to define an environment for displaying text
that is numbered as an equation.  A straightforward way to do this is
as follows:
\begin{verbatim}
  \newenvironment{texteqn}
    {\begin{equation}
       \begin{minipage}{0.9\linewidth}}
      {\end{minipage}
     \end{equation}}
\end{verbatim}
However, if you have tried this then you will probably have noticed
that it does not work perfectly when used in the middle of a paragraph
because an inter-word space appears at the beginning of the first
line after the environment.

There is now an extra command (with a very long name) available that
you can use to avoid this problem; it should be inserted as shown here:
\begin{verbatim}
  \newenvironment{texteqn}
    {\begin{equation}
       \begin{minipage}{0.9\linewidth}}
      {\end{minipage}
     \end{equation}
     \ignorespacesafterend}
\end{verbatim}

This command may also have other uses.

\subsection{Normalising spacing}

\begin{decl}
  |\normalsfcodes|
\end{decl}

\NEWfeature{1997/06/01}
This command should be used to restore the normal settings of the
parameters that affect spacing between words, sentences, etc.

An important use of this feature is to correct a problem, reported by
Donald Arseneau, that punctuation in page headers has always (in all
known \TeX{} formats) been potentially wrong whenever a page break
happens while a local setting of the space codes is in effect.  These
space codes are changed by, for example, the command
\verb|\frenchspacing|) and the \textsf{verbatim} environment.

It is normally given the correct definition automatically in
|\begin{document}| and so need not be explicitly set; however, if it
is explicitly made nonempty in a class file then automatic
default setting will be over-ridden.


\section{Upgrading \LaTeX~2.09 classes and packages}
\label{Sec:upgrade}

This section describes the changes you may need to make when you
upgrade an existing \LaTeX{} style to a package or class but we shall
start in optimistic mode.

Many existing style files will run with \LaTeXe{} without any
modification to the file itself.  When everything is running OK,
please put a note in the newly created package or class file to record
that it runs with the new standard \LaTeX{}; then distribute it to
your users.

\subsection{Try it first!}
\label{Sec:try-it}

The first thing you should do is to test your style in `compatibility
mode'.  The only change you need to make in order to do this is,
possibly, to change the extension of the file to |.cls|: you should
make this change only if your file was used as a main document style.
Now, without any other modifications, run \LaTeXe{} on a document that
uses your file.  This assumes that you have a suitable collection of
files that tests all the functionality provided by your style file.
(If you haven't, now is the time to make one!)

You now need to change the test document files so that they are
\LaTeXe{} documents: see \emph{\usrguide} for details of how to do
this and then try them again.  You have now tried the test documents
in both \LaTeXe{} native mode and \LaTeX~2.09 compatibility mode.

\subsection{Troubleshooting}
\label{Sec:trouble}

If your file does not work with \LaTeXe{}, there are two likely
reasons.
\begin{itemize}
\item \LaTeX{} now has a robust, well-defined designer's interface for
  selecting fonts, which is very different from the \LaTeX~2.09
  internals.
\item Your style file may have used some \LaTeX~2.09 internal commands
  which have changed, or which have been removed.
\end{itemize}

When you are debugging your file, you will probably need more
information than is normally displayed by \LaTeXe.  This is achieved
by resetting the counter |errorcontextlines| from its default value of
$-1$ to a much higher value, e.g.~999.

\subsection{Accommodating compatibility mode}

Sometimes an existing collection of \LaTeX~2.09 documents makes it
inconvenient or impossible to abandon the old commands entirely.
If this is the case, then it is possible to accommodate both conventions
by making special provision for documents processed in compatibility
mode.

\begin{decl}
|\if@compatibility|
\end{decl}
This switch is set when a document begins with |\documentstyle| rather
than |\documentclass|.  Appropriate code can be supplied for either
condition, as follows:
\begin{verbatim}
   \if@compatibility
     <code emulating LaTeX 2.09 behavior>
   \else
     <code suitable for LaTeX2e>
   \fi
\end{verbatim}


\subsection{Font commands}

Some font and size commands are now defined by the document class
rather than by the \LaTeX{} kernel.  If you are upgrading a
\LaTeX~2.09 document style to a class that does not load one of the
standard classes, then you will probably need to add definitions for
these commands.

\begin{decl}
   |\rm| |\sf| |\tt| |\bf| |\it| |\sl| |\sc|
\end{decl}
None of these short-form font selection commands are defined in the
\LaTeXe{} kernel.  They are defined by all the standard class files.

If you want to define them in your class file, there are several
reasonable ways to do this.

One possible definition is:
\begin{verbatim}
   \newcommand{\rm}{\rmfamily}
   ...
   \newcommand{\sc}{\scshape}
\end{verbatim}
This would make the font commands orthogonal; for example
|{\bf\it text}| would produce bold italic, thus: \textbf{\textit{text}}.
It will also make them produce an error if used in math mode.

Another possible definition is:
\begin{verbatim}
   \DeclareOldFontCommand{\rm}{\rmfamily}{\mathrm}
   ...
   \DeclareOldFontCommand{\sc}{\scshape}{\mathsc}
\end{verbatim}
This will make |\rm| act like |\rmfamily| in text mode (see above) and
it will make |\rm| select the |\mathrm| math alphabet in math mode.

Thus |${\rm math} = X + 1$| will produce `${\rm math} = X + 1$'.

If you do not want font selection to be orthogonal then you can
follow the standard classes and define:
\begin{verbatim}
   \DeclareOldFontCommand{\rm}{\normalfont\rmfamily}{\mathrm}
   ...
   \DeclareOldFontCommand{\sc}{\normalfont\scshape}{\mathsc}
\end{verbatim}
This means, for example, that |{\bf\it text}| will produce medium
weight (rather than bold) italic, thus: \textit{text}.

\begin{decl}
   |\normalsize| \\
   |\@normalsize|
\end{decl}
The command |\@normalsize| is retained for compatibility with
\LaTeX~2.09 packages which may have used its value; but redefining it
in a class file will have no effect since it is always reset to have
the same meaning as |\normalsize|.

This means that classes \emph{must} now redefine |\normalsize| rather
than redefining |\@normalsize|; for example (a rather incomplete one):
\begin{verbatim}
   \renewcommand{\normalsize}{\fontsize{10}{12}\selectfont}
\end{verbatim}
Note that |\normalsize| is defined by the \LaTeX{} kernel to be an
error message.

\begin{decl}
   |\tiny| |\footnotesize| |\small| |\large|\\
   |\Large| |\LARGE| |\huge| |\Huge|
\end{decl}
None of these other `standard' size-changing commands are defined in
the kernel: each needs to be defined in a class file if you need it.
They are all defined by the standard classes.

This means you should use |\renewcommand| for |\normalsize| and
|\newcommand| for the other size-changing commands.


\subsection{Obsolete commands}

Some packages will not work with \LaTeXe{}, normally because they relied
on an internal \LaTeX{} command which was never supported and has now
changed, or been removed.

In many cases there will now be a robust, high-level means of
achieving what previously required low-level commands.  Please consult
Section~\ref{Sec:commands} to see if you can now use the \LaTeXe{}
class and package writers commands.

Also, of course, if your package or class redefined any of the kernel
commands (i.e.~those defined in the files |latex.tex|, |slitex.tex|,
|lfonts.tex|, |sfonts.tex|) then you will need to check it very
carefully against the new kernel in case the implementation has
changed or the command no longer exists in the \LaTeX2e{} kernel.

Too many of the internal commands of \LaTeX~2.09 have been
re-implemented or removed to be able to list them all here. You must
check any that you have used or changed.

We shall, however, list some of the more important commands which are
no longer supported.

\begin{decl}
   |\tenrm| |\elvrm| |\twlrm| \dots\\
   |\tenbf| |\elvbf| |\twlbf| \dots\\
   |\tensf| |\elvsf| |\twlsf| \dots\\
   \qquad$\vdots$
\end{decl}
The (approximately) seventy internal commands of this form are no longer
defined.  If your class or package uses them then \emph{please}
replace them with new font commands described in \emph{\fntguide}.

For example, the command |\twlsf| should be replaced by:
\begin{verbatim}
   \fontsize{12}{14}\normalfont\sffamily\selectfont
\end{verbatim}

Another possibility is to use the |rawfonts| package, described in
\emph{\usrguide}.

Also, remember that many of the fonts preloaded by \LaTeX~2.09
are no longer preloaded.

\begin{decl}
   |\vpt| |\vipt| |\viipt| \dots
\end{decl}
These were the internal size-selecting commands in \LaTeX~2.09.
(They can still be used in \LaTeX~2.09 compatibility mode.)
Please use the command |\fontsize| instead: see \emph{\fntguide} for
details.

For example, |\vpt| should be replaced by:
\begin{verbatim}
   \fontsize{5}{6}\normalfont\selectfont
\end{verbatim}

\begin{decl}
  |\prm|, |\pbf|, |\ppounds|, |\pLaTeX| \dots
\end{decl}
\LaTeX~2.09 used several commands beginning with |\p| in order to
provide `protected' commands.  For example, |\LaTeX| was defined to be
|\protect\pLaTeX|, and |\pLaTeX| was defined to produce the \LaTeX{}
logo.  This made |\LaTeX| robust, even though |\pLaTeX| was not.

These commands have now been reimplemented using
|\DeclareRobustCommand|
(described in Section~\ref{Sec:commands.define}).
If your package redefined one of the |\p|-commands then you must
remove the redefinition and use |\DeclareRobustCommand| to redefine the
non-|\p| command.

\begin{decl}
|\footheight|\\
|\@maxsep|\\
|\@dblmaxsep|
\end{decl}
These parameters are not used by \LaTeXe{} so they have been removed,
except in \LaTeX~2.09 compatibility mode.  Classes should no longer
set them.

\begin{thebibliography}{1}

\bibitem{A-W:DEK91}
Donald~E. Knuth.
\newblock {\em The \TeX book}.
\newblock Addison-Wesley, Reading, Massachusetts, 1986.
\newblock Revised to cover \TeX3, 1991.

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

\bibitem{A-W:MG2004}
Frank Mittelbach and Michel Goossens.
\newblock {\em The {\LaTeX} Companion second edition}.
\newblock With Johannes Braams, David Carlisle, and Chris Rowley.
\newblock Addison-Wesley, Reading, Massachusetts, 2004.

\end{thebibliography}

\newpage
\thispagestyle{empty}

\section*{\LaTeXe{} Summary sheet: updating old styles}

Section references below are to \emph{\clsguide}.

\begin{enumerate}

\item Should it become a class or a package?
  See Section~\ref{Sec:classorpkg} for how to answer this question.

\item If it uses another style file, then you will need to obtain an
  updated version of this other file.  Look at Section~\ref{Sec:loading}
  for information on how to load other class and package files.

\item Try it: see Section~\ref{Sec:try-it}.

\item It worked?  Excellent, but there are probably still some things
  you should change in order to make your file into a well-structured
  \LaTeXe{} file that is both robust and portable. So you should now
  read Section~\ref{Sec:writing}, especially~\ref{Sec:general}.  You
  will also find some useful examples in Section~\ref{Sec:structure}.

  If your file sets up new fonts, font-changing commands or symbols,
  you should also read \emph{\fntguide}.

\item It did not work?  There are three possibilities here:
  \begin{itemize}
  \item  error messages are produced whilst reading your file;
  \item  error messages are produced whilst processing test documents;
  \item  there are no errors but the output is not as it should be.
  \end{itemize}
  Don't forget to check carefully for this last possibility.

  If you have got to this stage then you will need to read
  Section~\ref{Sec:upgrade} to find the solutions that will make your
  file work.
\end{enumerate}

\end{document}