summaryrefslogtreecommitdiff
path: root/macros/latex/base/clsguide.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-02-03 03:02:01 +0000
committerNorbert Preining <norbert@preining.info>2020-02-03 03:02:01 +0000
commit34897eebd22c3de968b64f09bb4a371d96cb0b89 (patch)
tree19a50e54fca63f1f6482d6cb4c2fdee676fd97b1 /macros/latex/base/clsguide.tex
parente05dc0bb38b16bfb9ba35591285e40af0adaadc4 (diff)
CTAN sync 202002030302
Diffstat (limited to 'macros/latex/base/clsguide.tex')
-rw-r--r--macros/latex/base/clsguide.tex321
1 files changed, 160 insertions, 161 deletions
diff --git a/macros/latex/base/clsguide.tex b/macros/latex/base/clsguide.tex
index 2b3c4b3b00..d778bf9ff4 100644
--- a/macros/latex/base/clsguide.tex
+++ b/macros/latex/base/clsguide.tex
@@ -1,30 +1,30 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2019
+% Copyright (C) 1993-2020
% The LaTeX3 Project and any individual authors listed elsewhere
-% in this file.
-%
+% 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
+% 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
+%
+% 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
@@ -37,46 +37,46 @@
\author{Copyright \copyright~1995--2006 The \LaTeX3 Project\\
All rights reserved}
-\date{15 February 2006}
+\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
@@ -84,33 +84,33 @@ commands necessary to write packages: these can be found in either
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
@@ -118,7 +118,7 @@ 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
@@ -127,7 +127,7 @@ six-monthly release of \LaTeX{}, and is found in the files
\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
+\texttt{cfgguide.tex} whilst the philosophy behind our policy on
modifying \LaTeX{} is described in \emph{\modguide} in
\texttt{modguide.tex}.
@@ -175,7 +175,7 @@ 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?''
+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
@@ -187,7 +187,7 @@ 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.
@@ -206,33 +206,33 @@ supported by individuals: they should support only the new standard
\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{}.
\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:
@@ -250,59 +250,59 @@ 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
+
+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
@@ -318,11 +318,11 @@ 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
+
+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
+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'.
@@ -349,13 +349,13 @@ outside math mode: for example, neither |\textfont 1| nor
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.
+these.
\subsubsection{Loading other files}
\label{Sec:loading}
\NEWdescription{1995/12/01}
-\LaTeX{} provides these commands:
+\LaTeX{} provides these commands:
\begin{verbatim}
\LoadClass \LoadClassWithOptions
\RequirePackage \RequirePackageWithOptions
@@ -363,20 +363,20 @@ these.
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}
@@ -385,7 +385,7 @@ If the package |foo.sty| loads the package |baz.sty| by use of
\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.
@@ -404,7 +404,7 @@ For example, |article.sty| contains just the following lines:
\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
@@ -415,20 +415,20 @@ Thus, instead of using |\def...| we recommend using one of
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
@@ -460,7 +460,7 @@ 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
@@ -486,7 +486,7 @@ 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}
@@ -500,9 +500,9 @@ style files did. The outline of a class or package file is:
\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}
@@ -527,7 +527,7 @@ For example:
\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).
+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
@@ -538,10 +538,10 @@ This date is checked whenever a user specifies a date in their
\begin{verbatim}
\documentclass{article}[1995/12/23]
\end{verbatim}
-then users at a different location
+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
@@ -549,14 +549,14 @@ are also displayed by the |\listfiles| command. The phrase
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>]
@@ -570,7 +570,7 @@ 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>]
@@ -600,7 +600,7 @@ For example:
\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
@@ -666,7 +666,7 @@ class, you can use:
\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:
@@ -676,7 +676,7 @@ you should use:
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.}}
@@ -686,16 +686,16 @@ For example, if the |jane| package file contains:
\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
@@ -713,13 +713,13 @@ distribution, as \texttt{minimal.cls}.} looks like this:
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}
@@ -742,9 +742,9 @@ the first page of letters.
}
\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|.
@@ -793,7 +793,7 @@ It redefines |\section| and switches off section numbering.
{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.
@@ -806,20 +806,20 @@ 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}
@@ -830,12 +830,12 @@ 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}
@@ -857,25 +857,25 @@ 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.
@@ -896,13 +896,13 @@ 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}\\
@@ -913,7 +913,7 @@ Examples:
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.
@@ -945,7 +945,7 @@ There are some commands designed especially for use within the
|\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.
+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
@@ -955,7 +955,7 @@ Example:
\begin{verbatim}
\DeclareOption{twoside}{\@twosidetrue}
\end{verbatim}
-
+
\begin{decl}
|\DeclareOption*| \arg{code}
\end{decl}
@@ -984,7 +984,7 @@ used within these arguments can be found in the next few subsections.
|\CurrentOption|
\end{decl}
This expands to the name of the current option.
-
+
\begin{decl}
|\OptionNotUsed|
\end{decl}
@@ -997,7 +997,7 @@ be added to the list of `unused options'.
necessary to double them).
\subsection{Moving options around}
-\label{Sec:opmove}
+\label{Sec:opmove}
These two commands are also very useful within the \m{code} argument
of |\DeclareOption| or |\DeclareOption*|:
@@ -1010,7 +1010,7 @@ The command |\PassOptionsToPackage| passes the option names in
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}
@@ -1023,7 +1023,7 @@ is the same as:
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}):
@@ -1077,7 +1077,7 @@ declared.
\subsection{Delaying code}
\label{Sec:delays}
-These first two commands are also intended primarily for use within
+These first two commands are also intended primarily for use within
the \m{code} argument of |\DeclareOption| or |\DeclareOption*|.
\begin{decl}
@@ -1087,18 +1087,18 @@ the \m{code} argument of |\DeclareOption| or |\DeclareOption*|.
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
@@ -1116,11 +1116,11 @@ executed at the beginning of the |\end{document}| code,
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}
@@ -1130,21 +1130,21 @@ 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.
@@ -1226,7 +1226,7 @@ Note the following:
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.
@@ -1244,7 +1244,7 @@ error messages being issued.
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.
+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
@@ -1254,8 +1254,8 @@ this in order to ease the task of updating old document styles to
|\ExecuteOptions| \arg{options-list}
\end{decl}
-For each option in the \m{options-list}, in order,
-this command simply executes the command
+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).
@@ -1269,19 +1269,19 @@ in two columns. Then it could specify:
\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}
@@ -1292,15 +1292,15 @@ 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}
@@ -1308,7 +1308,7 @@ report errors, or to provide information to authors.
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.
@@ -1340,7 +1340,7 @@ If the user types |h|, this will be shown:
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}\\
@@ -1365,11 +1365,11 @@ 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.
@@ -1390,7 +1390,7 @@ 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]{%
@@ -1422,7 +1422,7 @@ 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
@@ -1442,7 +1442,7 @@ We hope that these changes will not affect many packages.
\label{Sec:commands.misc}
\subsection{Layout parameters}
-
+
\begin{decl}
|\paperheight|\\
|\paperwidth|
@@ -1477,7 +1477,7 @@ For example:
\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}| &
\MakeUppercase{aBcD\ae\AA\ss\OE}\\
|\MakeLowercase{aBcD\ae\AA\ss\OE}| & \MakeLowercase{aBcD\ae\AA\ss\OE}
\end{tabular}
@@ -1581,11 +1581,11 @@ 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
@@ -1617,7 +1617,7 @@ 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.
+ internals.
\item Your style file may have used some \LaTeX~2.09 internal commands
which have changed, or which have been removed.
\end{itemize}
@@ -1651,13 +1651,13 @@ condition, as follows:
\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}
@@ -1676,7 +1676,7 @@ One possible definition is:
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}
@@ -1696,7 +1696,7 @@ follow the standard classes and define:
\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}.
+weight (rather than bold) italic, thus: \textit{text}.
\begin{decl}
|\normalsize| \\
@@ -1728,11 +1728,11 @@ This means you should use |\renewcommand| for |\normalsize| and
\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{}
@@ -1750,7 +1750,7 @@ 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\\
@@ -1769,7 +1769,7 @@ For example, the command |\twlsf| should be replaced by:
Another possibility is to use the |rawfonts| package, described in
\emph{\usrguide}.
-Also, remember that many of the fonts preloaded by \LaTeX~2.09
+Also, remember that many of the fonts preloaded by \LaTeX~2.09
are no longer preloaded.
\begin{decl}
@@ -1799,7 +1799,7 @@ These commands have now been reimplemented using
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|\\
@@ -1808,20 +1808,20 @@ non-|\p| command.
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}.
@@ -1856,7 +1856,7 @@ Section references below are to \emph{\clsguide}.
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;
@@ -1871,4 +1871,3 @@ Section references below are to \emph{\clsguide}.
\end{enumerate}
\end{document}
-