summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/base/clsguide.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/base/clsguide.tex')
-rw-r--r--Master/texmf-dist/doc/latex/base/clsguide.tex1872
1 files changed, 0 insertions, 1872 deletions
diff --git a/Master/texmf-dist/doc/latex/base/clsguide.tex b/Master/texmf-dist/doc/latex/base/clsguide.tex
deleted file mode 100644
index 4a926edf9cc..00000000000
--- a/Master/texmf-dist/doc/latex/base/clsguide.tex
+++ /dev/null
@@ -1,1872 +0,0 @@
-% \iffalse meta-comment
-%
-% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004
-% The LaTeX3 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.3
-% 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.3 or later is part of all distributions of LaTeX
-% version 2003/12/01 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--2003 The \LaTeX3 Project\\
- All rights reserved}
-
-\date{9 December 2003}
-
-\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{}, and an
-overview of more than 150 packages, is to be found in
-\emph{\LaTeXcomp} by Michel Goossens, Frank Mittelbach and Alexander
-Samarin~\cite{A-W:GMS94}.
-
-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}.
-
-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.
-Here are some useful addresses.
-\begin{quote}\small\label{addrs}
- \TeX{} Users Group, P.O. Box 1239, Three Rivers, CA~93271-1239, USA\\
- Fax:~+1~209~561~4584 \ Email: \texttt{tug@mail.tug.org}
-
- UK TUG, 1 Eymore Close, Selly Oak, Birmingham B29~4LB, UK\\
- Fax: +44 121 476 2159 \ Email: \texttt{uktug-enquiries@tex.ac.uk}
-\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|.
-
-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: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}
-
-\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}
-