% \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: clsguide.tex

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

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

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

\author{Copyright \copyright~1994 The \LaTeX3 Project\\
   All rights reserved}

   \date{\emph{Preliminary draft} June 1994}

\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 will also be covered in an
article by Johannes Braams to be published in TUGboat later this year.


\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 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 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, which are described in \emph{\LaTeXbook}
and \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
   docstrip, how \TeX's primitive file and box commands interact with
   \LaTeX, and some hits 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 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, and an 
overview of over 150 packages, is to be found in \emph{\LaTeXcomp} by 
Michel Goossens, Frank Mittelbach and Alexander 
Samarin~\cite{A-W:GMS94}.
 
The \LaTeX{} font selection scheme 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, and is kept in |usrguide.tex|.  
\emph{\fntguide} describes the \LaTeX{} font selection scheme for 
class- and package-writers, and 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{Writing classes and packages}
\label{Sec:general}
 
This section gives some general points about writing \LaTeX{} classes and
packages.
 
\subsection{Is it a class or a package?}
 
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 document class or a
package.  The rule of thumb is \emph{if the commands could be used
with any document class, then make them a package, and if not, make
them a class}.
 
For example, the |proc| document class changes the appearance of the
|article| document class.  It is of no use with any other document
class, so we have |proc.cls| rather than |proc.sty|.
 
The |graphics| package, however, 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|.
 
A company might have a local |ownlet| class for printing letters with
their own headed notepaper.  Such a class would build on top of the
existing |letter| class, but cannot be used with any other document
class, so we have |ownlet.cls| rather than |ownlet.sty|.
 
\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 the class and package writer commands, such as
|\InputIfFileExists|, |\RequirePackage| and |\PassOptionsToClass|.  Most
of these have long mixed-case names.
 
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 accessed in documents, only in classes and packages.
 
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|.
 
The rule of thumb still applies: 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{Using docstrip}
 
If you are going to write a large class or package for \LaTeX, you
should consider using the |docstrip| software which comes with \LaTeX.
 
\LaTeX{} classes and packages written using |docstrip| 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 |docstrip| 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 \LaTeX{} kernel itself is a |docstrip| document---you can read the
source code as one long document by running \LaTeX{} on
|source2e.tex|.
 
For more information on |docstrip|, consult the |docstrip| 
documentation or \emph{\LaTeXcomp}.
 
\subsection{Loading other files}
 
\LaTeX{} provides the commands |\LoadClass| and |\RequirePackage| for
using classes or packages inside other classes or packages.  We highly
recommend 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
|\filecontents| list.
 
If a package is requested more than once with |\RequirePackage| or
|\usepackage| it will only be loaded once.  If it is loaded with
|\input|, then it will be loaded more than once, which may waste time and
memory, and produce strange results.
 
If a package provides option-processing, then this can produces strange
results if the package is |\input| rather than loaded with |\usepackage|
or |\RequirePackage|.
 
If the package |foo.sty| loads the package |baz.sty| with
|\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}
So using |\input| to load packages is not a good idea.
 
Unfortunately, if you are upgrading a class file |myclass|, you have to
make sure that any old files which contain |\input myclass.sty| still
work.  This is particularly true of 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 took was to provide
minimal files |article.sty|, |book.sty| and |report.sty|, which load the
appropriate class files.  For example, |article.sty| contains:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \@obsoletefile{article.sty}{article.cls}
   \LoadClass{article}
\end{verbatim}
You may wish to do the same, or if you think that it's safe to do so, 
you may decide to just remove |myclass.sty|.
 
\subsection{Box commands and 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 other
people using your class who may 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 |\minipage| rather than |\vbox|.  The \LaTeX{} box commands have new
options which mean they are now as powerful as the \TeX{} primitives.
 
As an example of what can go wrong, consider that in a
|{\ttfamily <text>}|
the font is restored just \emph{before} the |}|, whereas in the
similar looking
|{\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, but 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|.  Again this is 
normally just |\relax| 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{General style}
 
Apart from the changes you need to make to get your document class
or package running again there are also a few changes that we encourage
you to make.
 
We consider it good practice, when writing packages and classes, to use
\LaTeX\ commands as much as possible. So instead of using |\def...| we
recommend using one of |\newcommand|, |\renewcommand| or
|\providecommand|. Doing that makes it less likely that you
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|.
 
The advantage of this practice is that your code is more readable
and, more important, that it is less likely to break when future
versions of \LaTeX\ are made available.
 
Some packages and document styles had to redefine the command
|\begin{document}| or |\end{document}| to acheive their goal.
This is no longer necessary. You can now use the `hooks'
|\AtBeginDocument| and |\AtEndDocument|. Again, using these hooks
makes it less likely that your code breaks when future versions of
\LaTeX\ arrive. It makes it also more likely that your package can work
together with someone else's.
 
Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the
equivalent class commands) rather than |\@latexerr|, |\@warning| or
|\wlog|.
 
It is very useful for exchanging files if your files are as portable as
possible.  They should only contain visible 7-bit text, and the filenames
should be eight letters (plus the three letter extension).  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|.
 
It is still possible to declare options by defining |\ds@<option>| and
calling |\@options|, but we recommend using the |\DeclareOptions| and
|\ProcessOptions| commands instead.  These are more powerful and use
less memory.  So rather than saying:
\begin{verbatim}
   \def\ds@draft{\overfullrule 5pt}
   \@options
\end{verbatim}
you should say:
\begin{verbatim}
   \DeclareOption{draft}{\setlength{\overfullrule}{5pt}}
   \ProcessOptions
\end{verbatim}
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,
you should say:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}[1994/06/01]
\end{verbatim}
If you are upgrading an existing \LaTeX~2.09 style file, 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.  We recommend maintaining classes and packages
only for \LaTeXe, and not for obsolete versions of \LaTeX.
 
\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 is:
\begin{description}
\item[identification] The file says that it is a \LaTeXe{} package or
   class, and gives a short description of itself.
\item[declarations] The file declares some commands, and can also load
   other files.  Usually these commands will be just for defining
   commands used in the 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, fonts, and loading other files.
\end{description}
 
\subsection{Identification}
 
The first thing a class or package does is identify itself.  Packages
do this by saying:
\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}
Classes do this by saying:
\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}
The <date> should be given in the form `\textsc{yyyy/mm/dd}'.  This
date is checked whenever a user specifies a date in their
|\documentclass| or |\usepackage| command.  For example, if a user
said:
\begin{verbatim}
   \documentclass{article}[1995/12/23]
\end{verbatim}
then they would get a warning that their copy of |article| was out of
date.
 
The description of a class is printed out when the class is used.  The
description of a package is put into the log file.  These descriptions
are also produced by |\listfiles|.
 
\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}, that is building files from small building-blocks
rather than large single files.
 
A \LaTeX{} package or class can load a package by saying:
\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 another class by saying:
\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.
 
\subsection{Declaring options}
 
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, which can be used by authors, for example the
|twocolumn| option to the |article| class.
 
An option is declared by saying:
\begin{verbatim}
   \DeclareOption{<option>}{<code>}
\end{verbatim}
for example the |dvips| option to the |graphics| package is
implemented as:
\begin{verbatim}
   \DeclareOption{dvips}{\input{dvips.def}}
\end{verbatim}
This means that when an author says |\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), but this behaviour
can be altered, by saying:
\begin{verbatim}
   \DeclareOption*{<code>}
\end{verbatim}
for example to make the package |fred| produce a warning rather than
an error, you could say:
\begin{verbatim}
   \DeclareOption*{%
      \PackageWarning{fred}{Unknown option `\CurrentOption'}%
   }
\end{verbatim}
then if an author says |\usepackage[foo]{fred}| they will get a
warning \texttt{Package fred Warning: Unknown option `foo'.}  As
another example, the |fontenc| package troes to load a file
|<encoding>enc.def| whenever the <encoding> option is used.  This
can be done by saying:
\begin{verbatim}
   \DeclareOption*{%
      \input{\CurrentOption enc.def}%
   }
\end{verbatim}
It is possible to pass options on to another package or class, using
the command |\PassOptionsToPackage| or |\PassOptionsToClass|.  For
example, to pass every unknown option on to the |article| class, you
can say:
\begin{verbatim}
   \DeclareOption*{%
      \PassOptionsToClass{\CurrentOption}{article}%
   }
\end{verbatim}
If you do this, you should make sure you load the class, otherwise the
options will never be processed!
 
So far, we have only seen how to declare options, and not how to
execute them.  To process the options which the file was called with,
you say:
\begin{verbatim}
   \ProcessOptions
\end{verbatim}
This executes the <code> for each option that was declared (see
Section~\ref{Sec:commands.options} for details of how this is done).
 
For example, if the |jane| package says:
\begin{verbatim}
   \DeclareOption{foo}{\typeout{Saw foo.}}
   \DeclareOption{baz}{\typeout{Saw baz.}}
   \DeclareOption*{\typeout{What's \CurrentOption?}}
   \ProcessOptions
\end{verbatim}
and an author says |\usepackage[foo,bar]{jane}|, then they will see
the messages \texttt{Saw foo} and \texttt{What's bar?}
 
\subsection{Declarations}
 
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|, |\setlength|
and |\setbox|.
 
However, there are some new commands for helping class and package
writers.  These are described in detail in Section~\ref{Sec:commands}.
 
There are three definitions that every class \emph{must} provide.  These
are |\normalsize|, |\textwidth| and |\textheight|.  So a minimal
document class file is:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{minimal}[1994/04/01 Minimal class]
   \renewcommand{\normalsize}{\fontsize{10}{12}\selectfont}
   \setlength{\textwidth}{6.5in}
   \setlength{\textheight}{8in}
\end{verbatim}
However, most classes will provide more than this!
 
\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 it passes any options on to the |letter| class, which is loaded
with the |a4paper| option.
\begin{verbatim}
   \DeclareOption*{\PassOptionsToClass{\CurrentOption}{letter}}
   \ProcessOptions
   \LoadClass[a4paper]{letter}
\end{verbatim}
Then it uses the comany letter head.  This is done by redefining the
|firstpage| page style, since 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 set in \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]
\end{verbatim}
Then it passes any 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}
   \newcommand{\headlinecolor}{\normalcolor}
   \DeclareOption{onecolumn}{\OptionNotUsed}
   \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}}
   \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
   \ProcessOptions
   \LoadClass[twocolumn]{article}
\end{verbatim}
Since we're using colour, we load the |color| package.  We don't specify
a device driver, which 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}
In practice, a class would need more than this: it ought to set the page
sizes, provide commands for issue numbers, authors of articles, page
styles and so on, but this skeleton gives a start.  The |ltnews| class is
not much more complex than this one.
 
\section{Commands for class and package writers}
\label{Sec:commands}
 
This section describes each of the new commands for class and package
writers.  You should also read the commands described in
\emph{\LaTeXbook}, \emph{\LaTeXcomp} and \emph{\usrguide}.
 
\subsection{Identification}
 
The first group of commands to be discussed are the ones that are used
in identifying your class or package file.
 
\begin{decl}
|\NeedsTeXFormat| \arg{format-name} \oarg{release-date}
\end{decl}
This command tells \TeX\ that it has to be processed using a format
with name \m{format-name}. With \m{release-date} one can specify the
earliest release date of the format that should still work.  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} contains the release date in the form
\textsc{yyyy/mm/dd}, followed by the version of the file, optionally
followed by a short description. The date information can be used by
|\LoadClass| or |\documentclass| (for classes) or |\RequirePackage| or
|\usepackage| (for packages) to test if the release is not obsolete.
The full 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}
As for the two previous commands, but here the full filename,
including the extension must be given. Used for declaring any files
other than main class and package files.
 
Example:
\begin{verbatim}
   \ProvidesFile{T1enc.def}[1994/06/01 Standard LaTeX file]
\end{verbatim}
 
\subsection{Loading files}
 
This group of commands can be used to build your own document class or
package upon existing classes or packages.
\begin{decl}
  |\RequirePackage| \oarg{options-list} \arg{package-name}
     \oarg{release-info}
\end{decl}
With this command, packages and classes can load other packages and 
classes.  Its use is the same as the author command |\usepackage|.
 
Example:
\begin{verbatim}
   \RequirePackage{ifthen}[1994/06/01]
\end{verbatim}
 
\begin{decl}
   |\LoadClass| \oarg{options-list} \arg{package-name}
     \oarg{release-info}
\end{decl}
This command is similar to |\RequirePackage|, but it is for use by
classes only, and must not be used in packages files.
 
Example:
\begin{verbatim}
   \LoadClass{article}[1994/06/01]
\end{verbatim}
 
\begin{decl}
  |\PassOptionsToClass| \arg{options-list} \arg{class-name}\\
  |\PassOptionsToPackage| \arg{options-list} \arg{package-name}
\end{decl}
With this command, packages can pass options to another package. This
adds the \m{option-list} to the list of options of 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 to pass options to
a class.
 
\subsection{Option handling}
\label{Sec:commands.options}
 
The following commands deal with the declaration and handling of
options to document classes and packages.
 
\begin{decl}
  |\DeclareOption| \arg{option-name} \arg{code}
\end{decl}
Declares \m{option-name} to be an option for the current class or
package and \m{code} the code to be executed if that option is
specified.
 
The \m{code} can contain any valid \LaTeXe{} construct, plus some
special commands for use within this argument which are described
below.
 
Example:
\begin{verbatim}
   \DeclareOption{twoside}{\@twosidetrue}
\end{verbatim}
 
 
\begin{decl}
  |\DeclareOption*| \arg{code}
%\\
%  |\OptionNotUsed|
\end{decl}
Declares \m{code} to be executed for every option which is otherwise
not explicitly declared.  By default, undeclared options to a class
will be silently passed to all packages (just like the declared
options for the class); undeclared options to a package will produce
an error.
 
The \m{code} can contain any valid \LaTeXe{} construct, plus some
special commands for use within this argument which are described
below.
 
 
\begin{decl}
  |\CurrentOption|
\end{decl}
Refers to the name of the current option within the \m{code} of
|\DeclareOption| or |\DeclareOption*|.
 
 
\begin{decl}
  |\ProcessOptions|
\end{decl}
These commands execute the <code> for each selected option.
 
We shall first describe how |\ProcessOptions| works in packages, and
then describe classes.
 
To understand in detail what |\ProcessOptions| does, you have to know
the difference between \emph{local} and \emph{global} options.  Local
options are those which have been explicitly passed to the package
with |\PassOptionsToPackage|, |\usepackage[<options>]| or
|\RequirePackage[<options>]|.  For example if the |fred| package is
called with:
\begin{verbatim}
   \documentclass[german,twocolumn]{article}
   \PassOptionsToPackage{dvips}{fred}
   \RequirePackage[errorshow]{fred}
\end{verbatim}
then |fred|'s local options are |german|, |errorshow| and |dvips|, and
the only global option is |twocolumn|.  Then when |\ProcessOptions| is
called, the following happen:
\begin{itemize}
\item For each option declared by |\DeclareOption|, it looks to see if
   that option has been requested.  If it has, the corresponding code
   is executed.
\item \emph{Then} for each remaining option in the \emph{local} option
   list, |\ds@<option>| is executed if it exits, otherwise
   the default option is executed.  If no default option has been
   declared, then an error is raised.
\end{itemize}
For 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
\end{verbatim}
then the result will be:
\begin{verbatim}
   DVIPS
   GERMAN
   Package fred Warning: Unknown `errorshow'.
\end{verbatim}
Note that the |dvips| option is executed before the |german| option,
because that is the order they are declared in |fred.sty|.  Also note
that the |errorshow| option produces a warning, but the |twocolumn|
option does not, because |twocolumn| is a global option.
 
In classes, |\ProcessOptions| is the same, except that \emph{all}
options are local, and that the default value for |\DeclareOption*| is
|\OptionNotUsed| rather than an error.
 
\begin{decl}
  |\ProcessOptions*|
\end{decl}
Like |\ProcessOptions| but executes the options in the order specified
in the calling command, rather than in the order specified in the
class or package. 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.
 
\subsection{Delaying code}
 
\begin{decl}
  |\AtEndOfClass| \arg{code}\\
  |\AtEndOfPackage| \arg{code}
\end{decl}
These commands cause \m{code} to be saved away in an internal hook,
and then executed at the end of the current class or package. Repeated
use of the commands work, and the arguments are executed in the order
they are declared.
 
\begin{decl}
  |\AtBeginDocument| \arg{code}\\
  |\AtEndDocument| \arg{code}
\end{decl}
These commands cause \m{code} to be saved internally and executed
while \LaTeX\ is executing |\begin{document}| or |\end{document}|.
 
Note that the \m{code} specified in the argumnent to |\AtEndDocument|
is executed \emph{before} any leftover floating environments are
processed. If you need your code to be executed after that you may
want to include a |\clearpage| in \m{code}.
 
\subsection{Safe Input Commands}
 
These commands deal with reading a file; they have been implemented in
such a way that the case that the file doesn't existed can be handled
in a user-friendly way.
 
\begin{decl}
  |\InputIfFileExists| \arg{file-name} \arg{true} \arg{false}
\end{decl}
Inputs the file \m{file-name} if it exists. Immediately before the
input, the code specified in \m{true} is executed. Otherwise the code
specified in \m{false} is executed.
 
\begin{decl}
|\IfFileExists| \arg{file-name} \arg{true} \arg{false}
\end{decl}
As above, but this command does not input the file.
One thing that you might like to put in the \m{false} clause is:
 
 
\subsection{Generating errors}
 
These commands are used by third party classes and packages to report
errors, or to provide information to authors.
 
\begin{decl}
  |\ClassError| \arg{class-name} \arg{error} \arg{help}\\
  |\PackageError| \arg{package-name} \arg{error} \arg{help}
\end{decl}
These produce an error message.  The <error> is displayed, and the error
prompt is shown.  If the user types |h|, they will be shown the <help>
information.
 
Within the <error> or <class-name>, |\protect| can be used to stop a command
from expanding, |\MessageBreak| causes a line-break, and |\space| prints
a space.  For example:
\begin{verbatim}
   \newcommand{\foo}{FOO}
   \PackageError{ethel}{%
      Your hovercraft is full of eels,\MessageBreak
      and \protect\foo\space is \foo
   }{%
      Oh dear.\MessageBreak Something's gone wrong.
   }
\end{verbatim}
produces:
\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|, they will be shown:
\begin{verbatim}
   Oh dear.
   Something's gone wrong.
\end{verbatim}
 
\begin{decl}
  |\ClassWarning| \arg{class-name} \arg{warning}\\
  |\PackageWarning| \arg{package-name} \arg{warning}\\
  |\ClassWarningNoLine| \arg{class-name} \arg{warning}\\
  |\PackageWarningNoLine| \arg{package-name} \arg{warning}
\end{decl}
These commands are similar, but produce warnings on the screen.  The
|Warning| versions show the line number where the warning ocurred, and
the |NoLine| versions do not.
 
\begin{decl}
  |\ClassInfo| \arg{class-name} \arg{info}\\
  |\PackageInfo| \arg{package-name} \arg{info}
\end{decl}
These commands are similar, but produce information in the log file.
 
\begin{decl}
   |\MessageBreak|
\end{decl}
Produces a line-break in an error, warning or info message.
 
\subsection{Defining commands}
\label{Sec:commands.define}
 
\LaTeXe\ contains a number of new commands that are meant to be used
in class and package files.
 
\begin{decl}
  |\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 the <definition> is fragile.  You can use
this command to define new commands, or redefine existing commands.
 
Example:
\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}
Now |\seq| can be used in moving arguments, even though
|\ifmmode| cannot, for example:
\begin{verbatim}
   \section{Stuff about sequences $\seq{x}$}
\end{verbatim}
 
\begin{decl}
  |\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 checks that the current definition of \m{cmd}
is \m{definition}. An error is raised if the definition is different.
 
This command may be useful for checking the state of the system before
your package starts altering command definitions. It allows you to
check that no other package has redefined the same command.
 
\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.
 
 
\section{Upgrading \LaTeX~2.09 classes and packages}
\label{Sec:upgrade}
 
This section describes how to upgrade any existing \LaTeX{} styles to
packages or classes.
 
\subsection{Try it first!}
 
The first thing you should do with an old style is try
to run a \LaTeXe{} document that uses it
unmodified. This assumes that you have a suitable test set that tests
all functionality provided by the style file. (If you haven't,
now is the time to make one!)  Please run the test document in both
\LaTeXe{} native mode, and \LaTeX~2.09 compatibility mode, since some
old styles will only work in compatibility mode.
 
Many existing style files will run with \LaTeXe\ without any
modification.  If it does run, please enter a note into the file
that you have checked that it runs, and distribute it to your users.
You might like to take the opportunity to make use of the new document
structuring commands.
 
If your style file does not work with \LaTeXe, there are two likely
reasons.  \LaTeX{} now has a robust, well-defined designer's interface
for selecting fonts, which is very different from the \LaTeX~2.09
internals.  And your style file may have used some \LaTeX~2.09 internal
commands which have changed, or which have been removed.
 
\subsection{Font commands}
 
Some commands are now defined by the document class rather than by the
\LaTeX{} kernel.  If you are upgrading a \LaTeX~2.09 document style, you
should add definitions for these commands.
 
\begin{decl}
   |\rm| |\sf| |\tt| |\bf| |\it| |\sl| |\sc|
\end{decl}
The \LaTeX~2.09 font selection commands are now defined in the document
class.  They are defined in the kernel to produce an error message.
 
\begin{decl}
   |\normalsize| \\
   |\@normalsize|
\end{decl}
The command |\@normalsize| is retained for compatibility with \LaTeX~2.09
packages which may have used it, but it is now defined in the kernel by:
\begin{verbatim}
   \newcommand{\@normalsize}{\normalsize}
\end{verbatim}
This means that classes should now define |\normalsize| rather than
|\@normalsize|, for example:
\begin{verbatim}
   \renewcommand{\normalsize}{\fontsize{10}{12}\selectfont}
\end{verbatim}
Note that |\normalsize| is defined by the \LaTeX{} kernel to be an error
message, whereas the other size-changing commands |\tiny|,
|\footnotesize|, |\small|, |\large|, |\Large|, |\LARGE|, |\huge| and
|\Huge| are not defined at all.  This means you should use
|\renewcommand| for |\normalsize| and |\newcommand| for the other 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 use the \LaTeXe{} class and
package writers commands.
 
Too many of the internal commands of \LaTeX~2.09 have been re-implemented
to list here.  We will 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 seventy pre-loaded \LaTeX~2.09 fonts are now no longer pre-loaded.
If your package uses them, then \emph{please} replace them with new
font commands described in \emph{\fntguide}.  For example the 
command |\twlsf| could be replaced by: 
\begin{verbatim}
   \fontsize{12}{14}\sffamily
\end{verbatim}
Another possibility is to use the |rawfonts| package, described in
\emph{\usrguide}.
 
\begin{decl}
   |\prm|, |\pbf|, |\ppounds|, |\pLaTeX| \dots
\end{decl}
\LaTeX~2.09 used commands beginning with |\p| for `protected' 
commands.  For example, |\LaTeX| was defined to be |\protect\pLaTeX|, 
and |\pLaTeX| produced 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, you should replace the redefinition by one using 
|\DeclareProtectedCommand|.
 
\begin{decl}
   |\vpt| |\vipt| |\viipt| \dots
\end{decl}
These commands used to be the internal size-selecting commands in
\LaTeX~2.09.  They are still supported in \LaTeX~2.09 compatibility mode,
but not in native mode.  Please use the command |\fontsize| instead 
(see \emph{\fntguide} for details) for
example replace |\vpt| with |\fontsize{5}{6}\selectfont|.
 
\begin{decl}
|\footheight|\\
|\@maxsep|\\
|\@dblmaxsep|
\end{decl}
These parameters are not used by \LaTeXe, and so have been removed,
except for in \LaTeX~2.09 compatibility mode.  Classes should no longer
set them.
 
\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{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.
 
\end{thebibliography}
 
\end{document}