diff options
author | Karl Berry <karl@freefriends.org> | 2023-06-09 20:19:52 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-06-09 20:19:52 +0000 |
commit | bea33e16f382ecf8188f0b613d553f8367f8d0d3 (patch) | |
tree | e88c683b3c53728bc08b661af5d42933f6614549 /Master/texmf-dist/doc/latex/base/clsguide.tex | |
parent | 31c338d4c559ed4bd789902a355068edc3bb9776 (diff) |
latex2e (9jun23)
git-svn-id: svn://tug.org/texlive/trunk@67314 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/base/clsguide.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/base/clsguide.tex | 1901 |
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} |