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.tex1901
1 files changed, 722 insertions, 1179 deletions
diff --git a/Master/texmf-dist/doc/latex/base/clsguide.tex b/Master/texmf-dist/doc/latex/base/clsguide.tex
index 0ed5e60817e..7225425ec8a 100644
--- a/Master/texmf-dist/doc/latex/base/clsguide.tex
+++ b/Master/texmf-dist/doc/latex/base/clsguide.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
@@ -28,13 +28,13 @@
% \fi
% Filename: clsguide.tex
-\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\documentclass{ltxguide}
-\documentclass{ltxguide}[1995/11/28]
+\usepackage[T1]{fontenc} % needed for \textbackslash in tt
+\usepackage{csquotes}
-\title{\LaTeXe~for class and package writers}
-
-\author{Copyright \copyright~1995--2006 The \LaTeX\ Project\\
+\title{\LaTeX\ for package and class authors --- current version}
+\author{\copyright~Copyright 2023, \LaTeX\ Project Team.\\
All rights reserved.%
\footnote{This file may distributed and/or modified under the
conditions of the \LaTeX{} Project Public License, either version 1.3c
@@ -42,7 +42,18 @@
\texttt{clsguide.tex} for full details.}%
}
-\date{15 February 2006}
+\date{2023-01-12}
+
+\NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
+\NewDocumentCommand\marg{m}{\arg{#1}}
+\NewDocumentCommand\meta{m}{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}}
+\NewDocumentCommand\pkg{m}{\textsf{#1}}
+\NewDocumentCommand\text{m}{\ifmmode\mbox{#1}\else#1\fi}
+% Fix a 'feature'
+\makeatletter
+\renewcommand \verbatim@font {\normalfont \ttfamily}
+\makeatother
+\providecommand\url[1]{\texttt{#1}}
\begin{document}
@@ -52,105 +63,74 @@
\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}.
+\LaTeXe{} was released in 1994 and added a number of then-new concepts to
+\LaTeX{}. For package and class authors, these are described in
+\texttt{clsguide-historic}, which has largely remained unchanged. Since then,
+the \LaTeX{} team have worked on a number of ideas, firstly a programming
+language for \LaTeX{} (L3 programming layer) and then a range of tools for
+authors which build on that language. Here, we describe the current, stable set
+of tools provided by the \LaTeX{} kernel for package and class developers. We
+assume familiarity with general \LaTeX{} usage as a document author, and that
+the material here is read in conjunction with \texttt{usrguide}, which provides
+information for general \LaTeX{} users on up-to-date approaches to creating
+commands, etc.
-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.
+\section{Writing classes and packages}
+\label{Sec:writing}
-\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|.
+This section covers some general points concerned with writing
+\LaTeX{} classes and packages.
-\subsection{Overview}
+\subsection{Is it a class or a package?}
+\label{Sec:classorpkg}
-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.
+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}
-\begin{description}
+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.
-\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.
+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|.
-\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.
+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|.
-\item[Section~\ref{Sec:commands}] lists the new class and package
- commands.
+\subsection{Using `docstrip' and `doc'}
- \item[Section~\ref{Sec:upgrade}] gives detailed advice on how to
- upgrade existing \LaTeX~2.09 classes and packages to \LaTeXe{}.
+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.
-\end{description}
+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.
-\subsection{Further information}
-
-For a general introduction to \LaTeX{}, including the new features of
-\LaTeXe{}, you should read \emph{\LaTeXbook}
-by Leslie Lamport~\cite{A-W:LLa94}.
-
-A more detailed description of the new features of \LaTeX, including an
-overview of more than 200 packages and nearly 1000 ready to run examples, is
-to be found in \emph{\LaTeXcomp\ second edition} by Frank Mittelbach and
-Michel Goossens~\cite{A-W:MG2004}.
-
-The \LaTeX{} system is based on \TeX{}, which is
-described in \emph{The \TeX book} by Donald E.~Knuth~\cite{A-W:DEK91}.
-
-There are a number of documentation files which accompany every copy
-of \LaTeX{}. A copy of \emph{\LaTeX{} News} will come out with each
-six-monthly release of \LaTeX{}, and is found in the files
-|ltnews*.tex|. The author's guide \emph{\usrguide} describes the new
-\LaTeX{} document features; it is in |usrguide.tex|. The guide
-\emph{\fntguide} describes the \LaTeX{} font selection scheme for
-class- and package-writers; it is in |fntguide.tex|. Configuring
-\LaTeX{} is covered by the guide \emph{\cfgguide} in
-\texttt{cfgguide.tex} whilst the philosophy behind our policy on
-modifying \LaTeX{} is described in \emph{\modguide} in
-\texttt{modguide.tex}.
-
-The documented source code (from the files used to produce the kernel
-format via |latex.ltx|) is now available as
-\emph{The \LaTeXe\ Sources}.
-This very large document also includes an index of
-\LaTeX{} commands. It can be typeset from the \LaTeX{} file
-|source2e.tex| in the |base| directory, using the source files and
-the class file |ltxdoc.cls| from this directory.
-
-For more information about \TeX{} and \LaTeX{}, please contact your
-local \TeX{} Users Group, or the international \TeX{} Users Group.
-Addresses and other details can be found at:
-\begin{quote}\small\label{addrs}
- \texttt{http://www.tug.org/lugs.html}
-\end{quote}
+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{Policy on standard classes}
@@ -182,89 +162,10 @@ packages that can be used to enhance these classes. So your first
thought when you consider such a deficiency will, we hope, be ``what
can I do to improve this?''
-Similar considerations apply to those parts of the kernel that are
-implementing design decisions, many of which should be left to the
-class file but are not in the current system. We realise that in such
-cases it is much more difficult for you to rectify the problem
-yourself but it is also the case that making such changes in the
-kernel would probably be a major project for us; therefore such
-enhancements will have to wait for \LaTeX3.
-
-\section{Writing classes and packages}
-\label{Sec:writing}
-
-This section covers some general points concerned with writing
-\LaTeX{} classes and packages.
-
-
-\subsection{Old versions}
-
-If you are upgrading an existing \LaTeX~2.09 style file then we
-recommend freezing the 2.09 version and no longer maintaining it.
-Experience with the various dialects of \LaTeX{} which existed in the
-early 1990's suggests that maintaining packages for different versions
-of \LaTeX{} is almost impossible. It will, of course, be necessary
-for some organisations to maintain both versions in parallel for some
-time but this is not essential for those packages and classes
-supported by individuals: they should support only the new standard
-\LaTeXe{}, not obsolete versions of \LaTeX{}.
-
-
-\subsection{Using `docstrip' and `doc'}
-
-If you are going to write a large class or package for \LaTeX{} then
-you should consider using the |doc| software which comes with
-\LaTeX{}.
-\LaTeX{} classes and packages written using this can be
-processed in two ways: they can be run through \LaTeX{}, to produce
-documentation; and they can be processed with |docstrip|, to produce
-the |.cls| or |.sty| file.
-
-The |doc| software can automatically generate indexes of definitions,
-indexes of command use, and change-log lists. It is very useful for
-maintaining and documenting large \TeX{} sources.
-
-The documented sources of the \LaTeX{} kernel itself, and of the
-standard classes, etc, are |doc| documents; they are in the |.dtx|
-files in the distribution. You can, in fact, typeset the source code
-of the kernel as one long document, complete with index, by running
-\LaTeX{} on |source2e.tex|. Typesetting these documents uses the
-class file |ltxdoc.cls|.
-
-For more information on |doc| and |docstrip|, consult the files
-|docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}. For examples of its
-use, look at the |.dtx| files.
-
-\subsection{Is it a class or a package?}
-\label{Sec:classorpkg}
-
-The first thing to do when you want to put some new \LaTeX{} commands
-in a file is to decide whether it should be a \emph{document class} or a
-\emph{package}. The rule of thumb is:
-\begin{quote}
- If the commands could be used with any document class, then make
- them a package; and if not, then make them a class.
-\end{quote}
-
-There are two major types of class: those like |article|, |report| or
-|letter|, which are free-standing; and those which are extensions or
-variations of other classes---for example, the |proc| document class,
-which is built on the |article| document class.
-
-Thus, a company might have a local |ownlet| class for printing letters
-with their own headed note-paper. Such a class would build on top of
-the existing |letter| class but it cannot be used with any other
-document class, so we have |ownlet.cls| rather than |ownlet.sty|.
-
-The |graphics| package, in contrast, provides commands for including
-images into a \LaTeX{} document. Since these commands can be used
-with any document class, we have |graphics.sty| rather than
-|graphics.cls|.
-
-
\subsection{Command names}
-\LaTeX{} has three types of command.
+Prior to the introduction of the L3~programming layer described in the next
+section, \LaTeX{} had 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.
@@ -289,117 +190,97 @@ 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:
+future releases of \LaTeX{} supporting the command.
+
+\subsection{Programming support}
+
+As noted in the introduction, the \LaTeX{} kernel today loads dedicated support
+from programming, here referred to as the L3 programming layer but also often
+called \pkg{expl3}. Details of the general approach taken by the L3
+programming layer are given in the document \texttt{expl3}, while a reference
+for all current code interfaces is available as \texttt{interface3}. This layer
+contains two types of command: a documented set of commands making up the API
+and a large number of private internal commands. The latter all start with two
+underscores and should not be used outside of the code module which defines
+them. This more structured approach means that using the L3 programming layer
+does not suffer from the somewhat fluid situation mentioned above with
+`\texttt{@} commands'.
+
+We do not cover the detail of using the L3 programming layer here. A good
+introduction to the approach is provided at
+\url{https://www.alanshawn.com/latex3-tutorial/}.
+
+\subsection{Box commands and color}
+\label{Sec:color}
+
+Even if you do not intend to use color 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 and wish to use color.
+
+The simplest way to ensure `color 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 color 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.
+Now the color-restore occurs after the |}| and so is \emph{not} stored in the
+box. Exactly what bad effects this can have depends on how color is
+implemented: it can range from getting the wrong colors 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
+color'.
\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.
+\LaTeX{} 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.
+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.
+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 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
+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:
+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.
+Thus, for several reasons, using |\input| to load packages is not a good idea.
For example, |article.sty| contains just the following lines:
\begin{verbatim}
@@ -407,93 +288,72 @@ For example, |article.sty| contains just the following lines:
\@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|.
+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.
+Thus, instead of using |\def...| we recommend using one of |\newcommand|,
+|\renewcommand| or |\providecommand| for programming and for defining document
+interfaces |\NewDocumentCommand|, etc. (see \texttt{usrguide} for details of
+these commands).
-When you define an environment, use |\newenvironment| or
-|\renewenvironment| instead |\def\foo{...}| and |\def\endfoo{...}|.
+When you define an environment, use |\NewDocumentEnvironment|, etc., (or
+|\newenvironment|, etc., for simple cases) instead of using |\def\foo{...}| and
+|\def\endfoo{...}|.
-If you need to set or change the value of a \m{dimen} or \m{skip}
-register, use |\setlength|.
+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|.
+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}
+Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the equivalent
+class commands) rather than |\@latexerr|, |\@warning| or |\wlog|.
-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{}.
+The advantage of this kind of practice is that your code is more readable and
+accessible to other experienced \LaTeX{} programmers.
\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 sensible to make your files are as portable as possible. To ensure
+this, files 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 still lower risk to stick to file names which use only the ASCII range:
+whilst \LaTeX{} works natively with UTF-8, the same cannot be said with
+certainty for all tools. For the same reason, avoid spaces in file names.
-It is also useful if local classes or packages have a common prefix,
-for example the University of Nowhere classes might begin with |unw|.
-This helps to avoid every University having its own thesis class, all
-called |thesis.cls|.
+It is 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
+error commands were introduced in the June 2022 release so, if you use
them then you should put:
\begin{verbatim}
- \NeedsTeXFormat{LaTeX2e}[1994/06/01]
+ \NeedsTeXFormat{LaTeX2e}[2022-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.
+It is sometimes necessary for a package to arrange for code to be
+executed at the start or end of the preamble, at the end of the document
+or at the start of every use of an environment. This can be carried
+out by using hooks. As a document author, you will likely be familiar with
+|\AtBeginDocument|, a wrapper around the more powerful command |\AddToHook|.
+The \LaTeX{} kernel provides a large number of dedicated hooks (applying in
+a pre-defined location) and generic hooks (applying to arbitrary commands):
+the interface for using these is described in \texttt{lthooks} . There are
+also hooks to apply to files, described in \texttt{ltfilehooks}.
\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:
+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.
@@ -517,7 +377,7 @@ Package files do this as follows:
For example:
\begin{verbatim}
\NeedsTeXFormat{LaTeX2e}
- \ProvidesPackage{latexsym}[1994/06/01 Standard LaTeX package]
+ \ProvidesPackage{latexsym}[1998-08-17 Standard LaTeX package]
\end{verbatim}
Class files do this as follows:
\begin{verbatim}
@@ -527,40 +387,30 @@ Class files do this as follows:
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.
+ \ProvidesClass{article}[2022-06-01 Standard LaTeX class]
+\end{verbatim}
+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}[2022-06-01]
+\end{verbatim}
+then users at a different location would get a warning that their copy of
+|article| was out of date.
-\subsection{Using classes and packages}
+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.
-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.
+\subsection{Using classes and packages}
A \LaTeX{} package or class can load a package as follows:
\begin{verbatim}
@@ -568,13 +418,12 @@ A \LaTeX{} package or class can load a package as follows:
\end{verbatim}
For example:
\begin{verbatim}
- \RequirePackage{ifthen}[1994/06/01]
+ \RequirePackage{ifthen}[2022-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.
+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}
@@ -584,13 +433,12 @@ 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.
+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.
@@ -606,14 +454,20 @@ For example:
\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.
+Packages and classes can 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.
+
+\LaTeX{} supports two methods for creating options: a key--value system and a
+`simple text' approach. The key--value system is recommended for new classes
+and packages, and is more flexible in handling of option classes than the
+simple text approach. Both option methods use the same basic structure within
+the \LaTeX{} source: declaration of options first then processing options in a
+second step. Both also allow options to be passed on to other packages or an
+underlying class. As the `classical' simple text approach is conceptually more
+straight-forward to illustrate, it is used here to show the general structure:
+see Section~\ref{Sec:opt:keyval} for full details of the key--value approach.
An option is declared as follows:
\begin{verbatim}
@@ -624,63 +478,58 @@ 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:
+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:
+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:
+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:
+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:
+
+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): see
+Section~\ref{Sec:opmove}. 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!
+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:
+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).
+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}
@@ -689,8 +538,8 @@ For example, if the |jane| package file contains:
\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?}
+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}
@@ -698,9 +547,6 @@ 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
@@ -708,7 +554,7 @@ 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]
+ \ProvidesClass{minimal}[2022-06-01 Standard LaTeX minimal class]
\renewcommand{\normalsize}{\fontsize{10pt}{12pt}\selectfont}
\setlength{\textwidth}{6.5in}
\setlength{\textheight}{8in}
@@ -728,18 +574,17 @@ 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]
+ \ProvidesClass{neplet}[2022-06-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.
+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.
+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>}%
@@ -751,17 +596,16 @@ 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|.
+|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]
+ \ProvidesClass{smplnews}[2022-06-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.
+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}}}
@@ -774,14 +618,14 @@ 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.
+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.
+The class then redefines |\maketitle| to produce the title in 72\,pt Helvetica
+bold oblique, in the appropriate colour.
\begin{verbatim}
\renewcommand{\maketitle}{%
\twocolumn[%
@@ -807,90 +651,91 @@ It also sets the three essential things.
\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.
+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,
+This section describes briefly each of the commands for class and package
+writers. To find out about other aspects of the 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.
+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}.
+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]
+ \NeedsTeXFormat{LaTeX2e}[2022-06-01]
\end{verbatim}
+People often don't know what date to put here. For the kernel, you can find out
+the right one by consulting |changes.txt| and select the release date of a new
+feature you are interested in. This is slightly different for packages as they
+are released throughout the year: you will need to consult their change
+history.
\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}.
+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 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 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.
+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]
+ \ProvidesClass{article}[2022-06-01 v1.0 Standard LaTeX class]
+ \ProvidesPackage{ifthen}[2022-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.
+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]
+ \ProvidesFile{T1enc.def}[2022-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.
+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.
+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}\\
@@ -899,13 +744,11 @@ package by building on existing classes or packages.
\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|.
-
+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]
+ \RequirePackage{ifthen}[2022-06-01]
+ \RequirePackageWithOptions{graphics}[2022-06-01]
\end{verbatim}
\begin{decl}
@@ -914,107 +757,153 @@ Examples:
|\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.
+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.
+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]
+ \LoadClass{article}[2022-06-01]
+ \LoadClassWithOptions{article}[2022-06-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.
-
+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}
+\subsection{Delaying code}
+\label{Sec:delays}
-\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'.
+As noted earlier, a sophisticated hook system is available and described in
+\texttt{lthooks}. Here, we document a small set of convenient short names for
+common hooks.
-There are some commands designed especially for use within the
-\m{code} argument of these commands (see below).
+These first two commands are also intended primarily for use within the
+\m{code} argument of |\DeclareOption| or |\DeclareOption*|.
\begin{decl}
- |\DeclareOption| \arg{option-name} \arg{code}
+ |\AtEndOfClass| \arg{code}\\
+ |\AtEndOfPackage| \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.
+These commands declare \m{code} that is saved away internally and then executed
+after processing the whole of the current class or package file.
-Example:
-\begin{verbatim}
- \DeclareOption{twoside}{\@twosidetrue}
-\end{verbatim}
+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}
- |\DeclareOption*| \arg{code}
+ |\AtBeginDocument| \arg{code}\\
+ |\AtEndDocument| \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.
+These commands declare \m{code} to be saved internally and executed while
+\LaTeX{} is executing |\begin{document}| or |\end{document}|.
-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).
+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.
-If a package file contains no |\DeclareOption*| then, by default, each
-specified but undeclared option for that package will produce an error.
+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}.
-\subsection{Commands within option code}
-\label{Sec:within.code}
+Repeated use of these commands is permitted: the code in the arguments is
+stored (and later executed) in the order of their declarations.
+
+\subsection{Creating and using keyval options}
+\label{Sec:opt:keyval}
-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.
+As with any key--value input, using key--value pairs as package or class
+options has two parts: creating the key options and setting (using) them.
+Options created in this way \emph{may} be used after package loading as general
+key--value settings: this will depend on the nature of the underlying code.
\begin{decl}
- |\CurrentOption|
+ |\DeclareKeys| \oarg{family} \arg{declarations}
\end{decl}
-This expands to the name of the current option.
+This command creates a series of options from a comma-separated
+\m{declarations} list. Each entry in this list is a key--value pair, with the
+\m{key} having one or more \m{properties}. A small number of `basic'
+\m{properties} are described below. The full range of properties, provided by
+\texttt{l3keys}, can also be used for more powerful processing. See
+\texttt{interface3} for the full details.
+
+The basic properties provided here are
+\begin{itemize}
+ \item \texttt{.code} --- execute arbitrary code
+ \item \texttt{.if} --- sets a \TeX{} |\if...| switch
+ \item \texttt{.ifnot} --- sets an inverted \TeX{} |\if...| switch
+ \item \texttt{.store} --- stores a value in a macro
+ \item \texttt{.usage} -- defines whether the option can be given only
+ when loading (\texttt{load}), in the preamble (\texttt{preamble}) or
+ has no limitation on scope (\texttt{general})
+\end{itemize}
+The part of the \meta{key} before the \m{property} is the \m{name}, with the
+\m{value} working with the \m{property} to define the behaviour of the option.
+
+For example, with
+\begin{verbatim}
+\DeclareKeys[mypkg]
+ {
+ draft.if = @mypkg@draft ,
+ draft.usage = preamble ,
+ name.store = \@mypkg@name ,
+ name.usage = load ,
+ second-name.store = \@mypkg@other@name
+ }
+\end{verbatim}
+three options would be created. The option \texttt{draft} can be given anywhere
+in the preamble, and will set a switch called |\if@mypkg@draft|. The option
+\texttt{name} can only be given during package loading, and will save whatever
+value it is given in |\@mypkg@name|. Finally, the option \texttt{second-name}
+can be given anywhere, and will save its value in |\@mypkg@other@name|.
+
+Keys created \emph{before} the use of |\ProcessKeyOptions| act as package
+options.
\begin{decl}
- |\OptionNotUsed|
+ |\DeclareUnknownKeyHandler| \oarg{family} \arg{code}
\end{decl}
-This causes the current option to
-be added to the list of `unused options'.
+The command |\DeclareUnknownKeyHandler| may be used to define the behavior when
+an undefined key is encountered. The \m{code} will receive the unknown key name
+as |#1| and the value as |#2|. These can then be processed as appropriate,
+e.g.~by forwarding to another package.
-\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).
+\begin{decl}
+ |\ProcessKeyOptions| \oarg{family}
+\end{decl}
+The |\ProcessKeyOptions| function is used to check the current option list
+against the keys defined for \m{family}. Global (class) options and local
+(package) options are checked when this function is called in a package.
-\subsection{Moving options around}
+\begin{decl}
+ |\SetKeys| \oarg{family} \arg{keyvals}
+\end{decl}
+Sets (applies) the explicit list of \m{keyvals} for the \m{family}: if the
+latter is not given, the value of |\@currname| is used. This command may be used
+within a package to set options before or after using |\ProcessKeyOptions|.
+
+\subsection{Passing options around}
\label{Sec:opmove}
-These two commands are also very useful within the \m{code} argument
-of |\DeclareOption| or |\DeclareOption*|:
+These two commands are also very useful within the \m{code} argument of
+options.
\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}.
+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}
@@ -1026,24 +915,22 @@ is the same as:
\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|.
+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}):
+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 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:
+The main purpose of |\LoadClassWithOptions| is to allow one class to simply
+build on another, for example:
\begin{verbatim}
\LoadClassWithOptions{article}
\end{verbatim}
@@ -1053,12 +940,11 @@ This should be compared with the slightly different construction
\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.
+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:
+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
@@ -1071,255 +957,56 @@ with:
\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}
-
+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 |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{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.
+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 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.
+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.
+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.
+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.
+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}.
+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.
+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.
+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}
@@ -1354,96 +1041,22 @@ If the user types |h|, this will be shown:
|\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 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 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.
+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
+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}
+\section{Miscellaneous commands, etc.}
\label{Sec:commands.misc}
\subsection{Layout parameters}
@@ -1452,78 +1065,25 @@ We hope that these changes will not affect many packages.
|\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.
-
+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}
+ |\MakeLowercase| \arg{text} \\
+ |\MakeTitlecase| \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|.
+As described in \texttt{usrguide}, case changing for text should be carried out
+using the commands |\MakeUppercase|, |\MakeLowercase| and
+|\MakeTitlecase|. If you need to change the case of programmatic material, the
+team strongly suggest using the L3 programming layer commands in the
+\texttt{str} module. If you do not wish to do this, you should use the \TeX{}
+|\uppercase| and |\lowercase| primitives \emph{in this situation only}.
\subsection{Better user-defined math display environments}
@@ -1531,11 +1091,8 @@ occur on left hand pages. Previously this option affected only
|\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:
+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}
@@ -1543,13 +1100,13 @@ as follows:
{\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.
+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:
+You can avoid this problem using |\ignorespacesafterend|; it should be
+inserted as shown here:
\begin{verbatim}
\newenvironment{texteqn}
{\begin{equation}
@@ -1567,312 +1124,298 @@ This command may also have other uses.
|\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.
+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 non-empty
+in a class file then automatic default setting will be over-ridden.
+
+\subsection{Querying localisation}
+
+Localisation information is needed to customise a range of outputs. The
+\LaTeX{} kernel does not itself manage localisation, which is well-served by
+the bundles \pkg{babel} and \pkg{polyglossia}. To allow the kernel and other
+packages to access the current localisation information provided by \pkg{babel}
+or \pkg{polyglossia}, the command \cs{BCPdata} is defined by the kernel. The
+initial kernel definition expands to tag parts for \texttt{en-US}, as the
+kernel does not track localisation but does start out with a broadly US~English
+setup. However, if \pkg{babel} or \pkg{polyglossia} are loaded, it is redefined
+expand to the BCP-47 information from the appropriate package. The supported
+arguments are the BCP-47 tag breakdowns:
\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.
+ \item \texttt{tag} The full BCP-47 tag (e.g.~\texttt{en-US})
+ \item \texttt{language} (e.g.,~\texttt{de})
+ \item \texttt{region} (e.g.,~\texttt{AT})
+ \item \texttt{script} (e.g.,~\texttt{Latn})
+ \item \texttt{variant} (e.g.,~\texttt{1901})
+ \item \texttt{extension.t} (transformation, e.g.,~\texttt{en-t-ja})
+ \item \texttt{extension.u} (additional locale
+ information, e.g.,~\texttt{ar-u-nu-latn})
+ \item \texttt{extension.x} (private use area, e.g.,~\texttt{la-x-classic})
\end{itemize}
+The information for the \emph{main} language for a document is be provided
+if these are prefixed by \texttt{main.}, e.g.~\texttt{main.language} will
+expand to the main language even if another language is currently active.
-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.
+In addition to the tag breakdown, the following semantic arguments are
+supported
+\begin{itemize}
+ \item \texttt{casing} The tag for case changing, e.g.~\texttt{el-x-iota}
+ could be selected rather than \texttt{el} to select a capital adscript
+ iota on uppercasing an \emph{ypogegrammeni}
+\end{itemize}
-\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:
+For example, the case changing command \cs{MakeUppercase} is (conceptually)
+defined as
\begin{verbatim}
- \if@compatibility
- <code emulating LaTeX 2.09 behavior>
- \else
- <code suitable for LaTeX2e>
- \fi
+\ExpandArgs{e}\MakeUppercaseAux{\BCPdata{casing}}{#1}
\end{verbatim}
+where |#1| is the user input and the first argument to
+\cs{MakeUppercaseAux} takes two arguments, the locale and input text.
+
+\section{Commands superseded for new material}
+A small number of commands were introduced as part of \LaTeXe{} in the
+mid-1990s, are widely used but have been superseded by more modern methods.
+These are covered here as they are likely to be encountered routinely in
+existing classes and packages.
-\subsection{Font commands}
+\subsection{Defining 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.
+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}
- |\rm| |\sf| |\tt| |\bf| |\it| |\sl| |\sc|
+ |\DeclareRobustCommand| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}\\
+ |\DeclareRobustCommand*| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}
\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.
+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.
-Another possible definition is:
+For example, if |\seq| is defined as follows:
\begin{verbatim}
- \DeclareOldFontCommand{\rm}{\rmfamily}{\mathrm}
- ...
- \DeclareOldFontCommand{\sc}{\scshape}{\mathsc}
+ \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}
-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:
+Then the command |\seq| can be used in moving arguments, even though
+|\ifmmode| cannot, for example:
\begin{verbatim}
- \DeclareOldFontCommand{\rm}{\normalfont\rmfamily}{\mathrm}
- ...
- \DeclareOldFontCommand{\sc}{\normalfont\scshape}{\mathsc}
+ \section{Stuff about sequences $\seq{x}$}
\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.
+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}
- |\tiny| |\footnotesize| |\small| |\large|\\
- |\Large| |\LARGE| |\huge| |\Huge|
+ |\CheckCommand| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}\\
+ |\CheckCommand*| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}
\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.
-
+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.
-\subsection{Obsolete commands}
+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.
-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.
+\subsection{Option declaration}
+\label{Sec:commands.options.dec}
-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.
+The following commands deal with the declaration and handling of options to
+document classes and packages using a classical `simple text' approach. Every
+option name must be a `\LaTeX{} name'.
-We shall, however, list some of the more important commands which are
-no longer supported.
+There are some commands designed especially for use within the \m{code}
+argument of these commands (see below).
\begin{decl}
- |\tenrm| |\elvrm| |\twlrm| \dots\\
- |\tenbf| |\elvbf| |\twlbf| \dots\\
- |\tensf| |\elvsf| |\twlsf| \dots\\
- \qquad$\vdots$
+ |\DeclareOption| \arg{option-name} \arg{code}
\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}.
+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.
-For example, the command |\twlsf| should be replaced by:
+Example:
\begin{verbatim}
- \fontsize{12}{14}\normalfont\sffamily\selectfont
+ \DeclareOption{twoside}{\@twosidetrue}
\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
+ |\DeclareOption*| \arg{code}
\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.
+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.
-For example, |\vpt| should be replaced by:
-\begin{verbatim}
- \fontsize{5}{6}\normalfont\selectfont
-\end{verbatim}
+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}
- |\prm|, |\pbf|, |\ppounds|, |\pLaTeX| \dots
+ |\CurrentOption|
\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.
+This expands to the name of the current option.
\begin{decl}
-|\footheight|\\
-|\@maxsep|\\
-|\@dblmaxsep|
+ |\OptionNotUsed|
\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}
+This causes the current option to be added to the list of `unused options'.
-\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.
+\subsection{Option processing}
+\label{Sec:commands.options}
-\bibitem{A-W:MG2004}
-Frank Mittelbach and Michel Goossens.
-\newblock {\em The {\LaTeX} Companion second edition}.
-\newblock With Johannes Braams, David Carlisle, and Chris Rowley.
-\newblock Addison-Wesley, Reading, Massachusetts, 2004.
+\begin{decl}
+ |\ProcessOptions|
+\end{decl}
+This command executes the \m{code} for each selected option.
-\end{thebibliography}
+We shall first describe how |\ProcessOptions| works in a package file, and then
+how this differs in a class file.
-\newpage
-\thispagestyle{empty}
+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}
-\section*{\LaTeXe{} Summary sheet: updating old styles}
+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.
-Section references below are to \emph{\clsguide}.
+ 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.
-\begin{enumerate}
+ 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.
-\item Should it become a class or a package?
- See Section~\ref{Sec:classorpkg} for how to answer this question.
+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:
-\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.
+\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}
-\item Try it: see Section~\ref{Sec:try-it}.
+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.
-\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}.
+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.
- If your file sets up new fonts, font-changing commands or symbols,
- you should also read \emph{\fntguide}.
+\begin{decl}
+ |\ProcessOptions*|
+\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.
-\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.
+\begin{decl}
+ |\ExecuteOptions| \arg{options-list}
+\end{decl}
- 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}
+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}
\end{document}