| 1 |
% \iffalse meta-comment |
| 2 |
% |
| 3 |
% Copyright (C) 2023-2025 |
| 4 |
% The LaTeX Project and any individual authors listed elsewhere |
| 5 |
% in this file. |
| 6 |
% |
| 7 |
% This file is part of the LaTeX base system. |
| 8 |
% ------------------------------------------- |
| 9 |
% |
| 10 |
% It may be distributed and/or modified under the |
| 11 |
% conditions of the LaTeX Project Public License, either version 1.3c |
| 12 |
% of this license or (at your option) any later version. |
| 13 |
% The latest version of this license is in |
| 14 |
% http://www.latex-project.org/lppl.txt |
| 15 |
% and version 1.3c or later is part of all distributions of LaTeX |
| 16 |
% version 2008 or later. |
| 17 |
% |
| 18 |
% This file has the LPPL maintenance status "maintained". |
| 19 |
% |
| 20 |
% The list of all files belonging to the LaTeX base distribution is |
| 21 |
% given in the file `manifest.txt'. See also `legal.txt' for additional |
| 22 |
% information. |
| 23 |
% |
| 24 |
% The list of derived (unpacked) files belonging to the distribution |
| 25 |
% and covered by LPPL is defined by the unpacking scripts (with |
| 26 |
% extension .ins) which are part of the distribution. |
| 27 |
% |
| 28 |
% \fi |
| 29 |
% Filename: clsguide.tex |
| 30 |
|
| 31 |
\documentclass{ltxguide} |
| 32 |
|
| 33 |
\usepackage[T1]{fontenc} % needed for \textbackslash in tt |
| 34 |
\usepackage{csquotes} |
| 35 |
|
| 36 |
\title{\LaTeX\ for package and class authors\\current version} |
| 37 |
\author{\copyright~Copyright 2023--2025, \LaTeX\ Project Team.\\ |
| 38 |
All rights reserved.% |
| 39 |
\footnote{This file may distributed and/or modified under the |
| 40 |
conditions of the \LaTeX{} Project Public License, either version 1.3c |
| 41 |
of this license or (at your option) any later version. See the source |
| 42 |
\texttt{clsguide.tex} for full details.}% |
| 43 |
} |
| 44 |
|
| 45 |
\date{2025-10-02} |
| 46 |
|
| 47 |
\NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}} |
| 48 |
\NewDocumentCommand\marg{m}{\arg{#1}} |
| 49 |
\NewDocumentCommand\meta{m}{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}} |
| 50 |
\NewDocumentCommand\pkg{m}{\textsf{#1}} |
| 51 |
\NewDocumentCommand\text{m}{\ifmmode\mbox{#1}\else#1\fi} |
| 52 |
% Fix a 'feature' |
| 53 |
\makeatletter |
| 54 |
\renewcommand \verbatim@font {\normalfont \ttfamily} |
| 55 |
\makeatother |
| 56 |
\providecommand\url[1]{\texttt{#1}} |
| 57 |
|
| 58 |
\providecommand\hook[1]{\texttt{#1}} |
| 59 |
\providecommand\socket[1]{\texttt{#1}} |
| 60 |
\providecommand\plug[1]{\texttt{#1}} |
| 61 |
|
| 62 |
|
| 63 |
|
| 64 |
\begin{document} |
| 65 |
|
| 66 |
\maketitle |
| 67 |
|
| 68 |
\tableofcontents |
| 69 |
|
| 70 |
\section{Introduction} |
| 71 |
|
| 72 |
\LaTeXe{} was released in 1994 and added a number of then-new concepts to |
| 73 |
\LaTeX{}. For package and class authors, these are described in the document |
| 74 |
\texttt{clsguide-historic}, which has largely remained unchanged. Since then, |
| 75 |
the \LaTeX{} team have worked on a number of ideas, firstly a programming |
| 76 |
language for \LaTeX{} (L3 programming layer) and then a range of tools for |
| 77 |
authors which build on that language. Here, we describe the current, stable set |
| 78 |
of tools provided by the \LaTeX{} kernel for package and class developers. We |
| 79 |
assume familiarity with general \LaTeX{} usage as a document author, and that |
| 80 |
the material here is read in conjunction with \texttt{usrguide}, which provides |
| 81 |
information for general \LaTeX{} users on up-to-date approaches to creating |
| 82 |
commands, etc. |
| 83 |
|
| 84 |
\section{Writing classes and packages} |
| 85 |
\label{sec:writing} |
| 86 |
|
| 87 |
This section covers some general points concerned with writing |
| 88 |
\LaTeX{} classes and packages. |
| 89 |
|
| 90 |
\subsection{Is it a class or a package?} |
| 91 |
\label{sec:classorpkg} |
| 92 |
|
| 93 |
The first thing to do when you want to put some new \LaTeX{} commands |
| 94 |
in a file is to decide whether it should be a \emph{document class} or a |
| 95 |
\emph{package}. The rule of thumb is: |
| 96 |
\begin{quote} |
| 97 |
If the commands could be used with any document class, then make |
| 98 |
them a package; and if not, then make them a class. |
| 99 |
\end{quote} |
| 100 |
|
| 101 |
There are two major types of class: those like |article|, |report| or |
| 102 |
|letter|, which are free-standing; and those which are extensions or |
| 103 |
variations of other classes---for example, the |proc| document class, |
| 104 |
which is built on the |article| document class. |
| 105 |
|
| 106 |
Thus, a company might have a local |ownlet| class for printing letters |
| 107 |
with their own headed note-paper. Such a class would build on top of |
| 108 |
the existing |letter| class but it cannot be used with any other |
| 109 |
document class, so we have |ownlet.cls| rather than |ownlet.sty|. |
| 110 |
|
| 111 |
The |graphics| package, in contrast, provides commands for including |
| 112 |
images into a \LaTeX{} document. Since these commands can be used |
| 113 |
with any document class, we have |graphics.sty| rather than |
| 114 |
|graphics.cls|. |
| 115 |
|
| 116 |
\subsection{Using `docstrip' and `doc'} |
| 117 |
|
| 118 |
If you are going to write a large class or package for \LaTeX{} then |
| 119 |
you should consider using the |doc| software which comes with |
| 120 |
\LaTeX{}. |
| 121 |
\LaTeX{} classes and packages written using this can be |
| 122 |
processed in two ways: they can be run through \LaTeX{}, to produce |
| 123 |
documentation; and they can be processed with |docstrip|, to produce |
| 124 |
the |.cls| or |.sty| file. |
| 125 |
|
| 126 |
The |doc| software can automatically generate indexes of definitions, |
| 127 |
indexes of command use, and change-log lists. It is very useful for |
| 128 |
maintaining and documenting large \TeX{} sources. |
| 129 |
|
| 130 |
The documented sources of the \LaTeX{} kernel itself, and of the |
| 131 |
standard classes, etc., are |doc| documents; they are in the |.dtx| |
| 132 |
files in the distribution. You can, in fact, typeset the source code |
| 133 |
of the kernel as one long document, complete with index, by running |
| 134 |
\LaTeX{} on |source2e.tex|. Typesetting these documents uses the |
| 135 |
class file |ltxdoc.cls|. |
| 136 |
|
| 137 |
For more information on |doc| and |docstrip|, consult the files |
| 138 |
|docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}. For examples of its |
| 139 |
use, look at the |.dtx| files. |
| 140 |
|
| 141 |
\subsection{Policy on standard classes} |
| 142 |
|
| 143 |
Many of the problem reports we receive concerning the standard classes |
| 144 |
are not concerned with bugs but are suggesting, more or less politely, |
| 145 |
that the design decisions embodied in them are `not optimal' and |
| 146 |
asking us to modify them. |
| 147 |
|
| 148 |
There are several reasons why we should not make such changes to these |
| 149 |
files. |
| 150 |
\begin{itemize} |
| 151 |
\item |
| 152 |
However misguided, the current behavior is clearly what was |
| 153 |
intended when these classes were designed. |
| 154 |
\item |
| 155 |
It is not good practice to change such aspects of `standard classes' |
| 156 |
because many people will be relying on them. |
| 157 |
\end{itemize} |
| 158 |
|
| 159 |
We have therefore decided not to even consider making such |
| 160 |
modifications, nor to spend time justifying that decision. This does |
| 161 |
not mean that we do not agree that there are many deficiencies in the |
| 162 |
design of these classes, but we have many tasks with higher priority |
| 163 |
than continually explaining why the standard classes for \LaTeX{} |
| 164 |
cannot be changed. |
| 165 |
|
| 166 |
We would, of course, welcome the production of better classes, or of |
| 167 |
packages that can be used to enhance these classes. So your first |
| 168 |
thought when you consider such a deficiency will, we hope, be ``what |
| 169 |
can I do to improve this?'' |
| 170 |
|
| 171 |
\subsection{Command names} |
| 172 |
|
| 173 |
Prior to the introduction of the L3~programming layer described in the next |
| 174 |
section, \LaTeX{} had three types of command. |
| 175 |
|
| 176 |
There are the author commands, such as |\section|, |\emph| and |
| 177 |
|\times|: most of these have short names, all in lower case. |
| 178 |
|
| 179 |
There are also the class and package writer commands: |
| 180 |
most of these have long mixed-case names such as the following. |
| 181 |
\begin{verbatim} |
| 182 |
\InputIfFileExists \RequirePackage \PassOptionsToClass |
| 183 |
\end{verbatim} |
| 184 |
|
| 185 |
Finally, there are the internal commands used in the \LaTeX{} |
| 186 |
implementation, such as |\@tempcnta|, |\@ifnextchar| and |\@eha|: |
| 187 |
most of these commands contain |@| in their name, which means they |
| 188 |
cannot be used in documents, only in class and package files. |
| 189 |
|
| 190 |
Unfortunately, for historical reasons the distinction between these |
| 191 |
commands is often blurred. For example, |\hbox| is an internal |
| 192 |
command which should only be used in the \LaTeX{} kernel, whereas |
| 193 |
|\m@ne| is the constant $-1$ and could have been |\MinusOne|. |
| 194 |
|
| 195 |
However, this rule of thumb is still useful: if a command has |@| in |
| 196 |
its name then it is not part of the supported \LaTeX{} language---and |
| 197 |
its behavior may change in future releases! If a command is |
| 198 |
mixed-case, or is described in \emph{\LaTeXbook}, then you can rely on |
| 199 |
future releases of \LaTeX{} supporting the command. |
| 200 |
|
| 201 |
\subsection{Programming support} |
| 202 |
|
| 203 |
As noted in the introduction, the \LaTeX{} kernel today loads dedicated support |
| 204 |
from programming, here referred to as the L3 programming layer but also often |
| 205 |
called \pkg{expl3}. Details of the general approach taken by the L3 |
| 206 |
programming layer are given in the document \texttt{expl3}, while a reference |
| 207 |
for all current code interfaces is available as \texttt{interface3}. This layer |
| 208 |
contains two types of command: a documented set of commands making up the API |
| 209 |
and a large number of private internal commands. The latter all start with two |
| 210 |
underscores and should not be used outside of the code module which defines |
| 211 |
them. This more structured approach means that using the L3 programming layer |
| 212 |
does not suffer from the somewhat fluid situation mentioned above with |
| 213 |
`\texttt{@} commands'. |
| 214 |
|
| 215 |
We do not cover the detail of using the L3 programming layer here. A good |
| 216 |
introduction to the approach is provided at |
| 217 |
\url{https://www.alanshawn.com/latex3-tutorial/}. |
| 218 |
|
| 219 |
\subsection{Box commands and color} |
| 220 |
\label{sec:color} |
| 221 |
|
| 222 |
Even if you do not intend to use color in your own documents, by taking note of |
| 223 |
the points in this section you can ensure that your class or package is |
| 224 |
compatible with the |color| package. This may benefit people using your class |
| 225 |
or package and wish to use color. |
| 226 |
|
| 227 |
The simplest way to ensure `color safety' is to always use \LaTeX{} box |
| 228 |
commands rather than \TeX{} primitives, that is use |\sbox| rather than |
| 229 |
|\setbox|, |\mbox| rather than |\hbox| and |\parbox| or the |minipage| |
| 230 |
environment rather than |\vbox|. The \LaTeX{} box commands have new options |
| 231 |
which mean that they are now as powerful as the \TeX{} primitives. |
| 232 |
|
| 233 |
As an example of what can go wrong, consider that in |{\ttfamily <text>}| the |
| 234 |
font is restored just \emph{before} the |}|, whereas in the similar looking |
| 235 |
construction |{\color{green} <text>}| the color is restored just \emph{after} |
| 236 |
the final |}|. Normally this distinction does not matter at all; but consider a |
| 237 |
primitive \TeX{} box assignment such as: |
| 238 |
\begin{verbatim} |
| 239 |
\setbox0=\hbox{\color{green} <text>} |
| 240 |
\end{verbatim} |
| 241 |
Now the color-restore occurs after the |}| and so is \emph{not} stored in the |
| 242 |
box. Exactly what bad effects this can have depends on how color is |
| 243 |
implemented: it can range from getting the wrong colors in the rest of the |
| 244 |
document, to causing errors in the dvi-driver used to print the document. |
| 245 |
|
| 246 |
Also of interest is the command |\normalcolor|. This is normally just |\relax| |
| 247 |
(i.e., does nothing) but you can use it rather like |\normalfont| to set |
| 248 |
regions of the page such as captions or section headings to the `main document |
| 249 |
color'. |
| 250 |
|
| 251 |
\subsection{General style} |
| 252 |
\label{sec:general} |
| 253 |
|
| 254 |
\LaTeX{} provides many commands designed to help you produce well-structured |
| 255 |
class and package files that are both robust and portable. This section |
| 256 |
outlines some ways to make intelligent use of these. |
| 257 |
|
| 258 |
\subsubsection{Loading other files} |
| 259 |
\label{sec:loading} |
| 260 |
|
| 261 |
\LaTeX{} provides these commands: |
| 262 |
\begin{verbatim} |
| 263 |
\LoadClass \LoadClassWithOptions |
| 264 |
\RequirePackage \RequirePackageWithOptions |
| 265 |
\end{verbatim} |
| 266 |
for using classes or packages inside other classes or packages. We recommend |
| 267 |
strongly that you use them, rather than the primitive |\input| command, for a |
| 268 |
number of reasons. |
| 269 |
|
| 270 |
Files loaded with |\input <filename>| will not be listed in the |\listfiles| |
| 271 |
list. |
| 272 |
|
| 273 |
If a package is always loaded with |\RequirePackage...| or |\usepackage| then, |
| 274 |
even if its loading is requested several times, it will be loaded only once. By |
| 275 |
contrast, if it is loaded with |\input| then it can be loaded more than once; |
| 276 |
such an extra loading may waste time and memory and it may produce strange |
| 277 |
results. |
| 278 |
|
| 279 |
If a package provides option-processing then, again, strange results are |
| 280 |
possible if the package is |\input| rather than loaded by means of |
| 281 |
|\usepackage| or |\RequirePackage...|. |
| 282 |
|
| 283 |
If the package |foo.sty| loads the package |baz.sty| by use of |\input baz.sty| |
| 284 |
then the user will get a warning: |
| 285 |
\begin{verbatim} |
| 286 |
LaTeX Warning: You have requested package `foo', |
| 287 |
but the package provides `baz'. |
| 288 |
\end{verbatim} |
| 289 |
Thus, for several reasons, using |\input| to load packages is not a good idea. |
| 290 |
|
| 291 |
For example, |article.sty| contains just the following lines: |
| 292 |
\begin{verbatim} |
| 293 |
\NeedsTeXFormat{LaTeX2e} |
| 294 |
\@obsoletefile{article.cls}{article.sty} |
| 295 |
\LoadClass{article} |
| 296 |
\end{verbatim} |
| 297 |
You may wish to do the same or, if you think that it is safe to do so, you may |
| 298 |
decide to just remove |myclass.sty|. |
| 299 |
|
| 300 |
\subsubsection{Make it robust} |
| 301 |
|
| 302 |
We consider it good practice, when writing packages and classes, to use |
| 303 |
\LaTeX{} commands as much as possible. |
| 304 |
|
| 305 |
Thus, instead of using |\def...| we recommend using one of |\newcommand|, |
| 306 |
|\renewcommand| or |\providecommand| for programming and for defining document |
| 307 |
interfaces |\NewDocumentCommand|, etc. (see \texttt{usrguide} for details of |
| 308 |
these commands). |
| 309 |
|
| 310 |
When you define an environment, use |\NewDocumentEnvironment|, etc., (or |
| 311 |
|\newenvironment|, etc., for simple cases) instead of using |\def\foo{...}| and |
| 312 |
|\def\endfoo{...}|. |
| 313 |
|
| 314 |
If you need to set or change the value of a \m{dimen} or \m{skip} register, use |
| 315 |
|\setlength|. |
| 316 |
|
| 317 |
To manipulate boxes, use \LaTeX{} commands such as |\sbox|, |\mbox| and |
| 318 |
|\parbox| rather than |\setbox|, |\hbox| and |\vbox|. |
| 319 |
|
| 320 |
Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the equivalent |
| 321 |
class commands) rather than |\@latexerr|, |\@warning| or |\wlog|. |
| 322 |
|
| 323 |
The advantage of this kind of practice is that your code is more readable and |
| 324 |
accessible to other experienced \LaTeX{} programmers. |
| 325 |
|
| 326 |
\subsubsection{Make it portable} |
| 327 |
|
| 328 |
It is also sensible to make your files are as portable as possible. To ensure |
| 329 |
this, files must not have the same name as a file in the standard \LaTeX{} |
| 330 |
distribution, however similar its contents may be to one of these files. It is |
| 331 |
also still lower risk to stick to file names which use only the ASCII range: |
| 332 |
whilst \LaTeX{} works natively with UTF-8, the same cannot be said with |
| 333 |
certainty for all tools. For the same reason, avoid spaces in file names. |
| 334 |
|
| 335 |
It is also useful if local classes or packages have a common prefix, for |
| 336 |
example the University of Nowhere classes might begin with |unw|. This helps to |
| 337 |
avoid every University having its own thesis class, all called |thesis.cls|. |
| 338 |
|
| 339 |
If you rely on some features of the \LaTeX{} kernel, or on a package, |
| 340 |
please specify the release-date you need. For example, the keyval |
| 341 |
options (see Section~\ref{sec:opt:keyval}) were introduced in the June |
| 342 |
2022 release so, if you use them then you should put: |
| 343 |
\begin{verbatim} |
| 344 |
\NeedsTeXFormat{LaTeX2e}[2022-06-01] |
| 345 |
\end{verbatim} |
| 346 |
|
| 347 |
\subsubsection{Useful hooks} |
| 348 |
|
| 349 |
It is sometimes necessary for a package to arrange for code to be |
| 350 |
executed at the start or end of the preamble, at the end of the document |
| 351 |
or at the start of every use of an environment. This can be carried |
| 352 |
out by using hooks. As a document author, you will likely be familiar with |
| 353 |
|\AtBeginDocument|, a wrapper around the more powerful command |\AddToHook|. |
| 354 |
The \LaTeX{} kernel provides a large number of dedicated hooks (applying in |
| 355 |
a pre-defined location) and generic hooks (applying to arbitrary commands): |
| 356 |
the interface for using these is described in \texttt{lthooks}. There are |
| 357 |
also hooks to apply to files, described in \texttt{ltfilehooks}. |
| 358 |
|
| 359 |
\section{The structure of a class or package} |
| 360 |
\label{sec:structure} |
| 361 |
|
| 362 |
The outline of a class or package file is: |
| 363 |
\begin{description} |
| 364 |
\item[Identification] The file says that it is a \LaTeXe{} package or |
| 365 |
class, and gives a short description of itself. |
| 366 |
\item[Preliminary declarations] |
| 367 |
Here the file declares some commands and can also load |
| 368 |
other files. Usually these commands will be just those needed for |
| 369 |
the code used in the declared options. |
| 370 |
\item[Options] The file declares and processes its options. |
| 371 |
\item[More declarations] This is where the file does most of its work: |
| 372 |
declaring new variables, commands and fonts; and loading other files. |
| 373 |
\end{description} |
| 374 |
|
| 375 |
\subsection{Identification% |
| 376 |
\label{sec:ID}} |
| 377 |
|
| 378 |
The first thing a class or package file does is identify itself. |
| 379 |
Package files do this as follows: |
| 380 |
\begin{verbatim} |
| 381 |
\NeedsTeXFormat{LaTeX2e} |
| 382 |
\ProvidesPackage{<package>}[<date> <other information>] |
| 383 |
\end{verbatim} |
| 384 |
For example: |
| 385 |
\begin{verbatim} |
| 386 |
\NeedsTeXFormat{LaTeX2e} |
| 387 |
\ProvidesPackage{latexsym}[1998-08-17 Standard LaTeX package] |
| 388 |
\end{verbatim} |
| 389 |
Class files do this as follows: |
| 390 |
\begin{verbatim} |
| 391 |
\NeedsTeXFormat{LaTeX2e} |
| 392 |
\ProvidesClass{<class-name>}[<date> <other information>] |
| 393 |
\end{verbatim} |
| 394 |
For example: |
| 395 |
\begin{verbatim} |
| 396 |
\NeedsTeXFormat{LaTeX2e} |
| 397 |
\ProvidesClass{article}[2022-06-01 Standard LaTeX class] |
| 398 |
\end{verbatim} |
| 399 |
The \m{date} should be given in the form `\textsc{yyyy-mm-dd}' or |
| 400 |
`\textsc{yyyy/mm/dd}' and must be present if the optional argument is used. |
| 401 |
Exactly four digits are required for the year and two each for the month and |
| 402 |
day. Where necessary, zeros should be added to pad the month and day |
| 403 |
appropriately. If digits or separators are missing, the date will likely be |
| 404 |
misinterpreted: the commands expect a valid syntax to speed up the routine usage |
| 405 |
of the package or class and make no provision for the case there is an error |
| 406 |
in the date specification. |
| 407 |
|
| 408 |
This date is checked whenever a user specifies a date in their |\documentclass| |
| 409 |
or |\usepackage| command. For example, if you wrote: |
| 410 |
\begin{verbatim} |
| 411 |
\documentclass{article}[2022-06-01] |
| 412 |
\end{verbatim} |
| 413 |
then users at a different location would get a warning that their copy of |
| 414 |
|article| was out of date. |
| 415 |
|
| 416 |
The description of a class is displayed when the class is used. The description |
| 417 |
of a package is put into the log file. These descriptions are also displayed by |
| 418 |
the |\listfiles| command. The phrase \texttt{Standard LaTeX} \textbf{must not} |
| 419 |
be used in the identification banner of any file other than those in the |
| 420 |
standard \LaTeX{} distribution. |
| 421 |
|
| 422 |
\subsection{Using classes and packages} |
| 423 |
|
| 424 |
A \LaTeX{} package or class can load a package as follows: |
| 425 |
\begin{verbatim} |
| 426 |
\RequirePackage[<options>]{<package>}[<date>] |
| 427 |
\end{verbatim} |
| 428 |
For example: |
| 429 |
\begin{verbatim} |
| 430 |
\RequirePackage{ifthen}[2022-06-01] |
| 431 |
\end{verbatim} |
| 432 |
This command has the same syntax as the author command |\usepackage|. It allows |
| 433 |
packages or classes to use features provided by other packages. For example, by |
| 434 |
loading the |ifthen| package, a package writer can use the `if\dots then\dots |
| 435 |
else\dots' commands provided by that package. |
| 436 |
|
| 437 |
A \LaTeX{} class can load one other class as follows: |
| 438 |
\begin{verbatim} |
| 439 |
\LoadClass[<options>]{<class-name>}[<date>] |
| 440 |
\end{verbatim} |
| 441 |
For example: |
| 442 |
\begin{verbatim} |
| 443 |
\LoadClass[twocolumn]{article} |
| 444 |
\end{verbatim} |
| 445 |
This command has the same syntax as the author command |\documentclass|. It |
| 446 |
allows classes to be based on the syntax and appearance of another class. For |
| 447 |
example, by loading the |article| class, a class writer only has to change the |
| 448 |
bits of |article| they don't like, rather than writing a new class from |
| 449 |
scratch. |
| 450 |
|
| 451 |
The following commands can be used in the common case that you want to |
| 452 |
simply load a class or package file with exactly those options that |
| 453 |
are being used by the current class. |
| 454 |
\begin{verbatim} |
| 455 |
\LoadClassWithOptions{<class-name>}[<date>] |
| 456 |
\RequirePackageWithOptions{<package>}[<date>] |
| 457 |
\end{verbatim} |
| 458 |
For example: |
| 459 |
\begin{verbatim} |
| 460 |
\LoadClassWithOptions{article} |
| 461 |
\RequirePackageWithOptions{graphics}[1995/12/01] |
| 462 |
\end{verbatim} |
| 463 |
|
| 464 |
\subsection{Declaring options} |
| 465 |
|
| 466 |
Packages and classes can declare options and these can be specified by authors; |
| 467 |
for example, the |twocolumn| option is declared by the |article| class. Note |
| 468 |
that the name of an option should contain only those characters allowed in a |
| 469 |
`\LaTeX{} name'; in particular it must not contain any control sequences. |
| 470 |
|
| 471 |
\LaTeX{} supports two methods for creating options: a key--value system and a |
| 472 |
`simple text' approach. The key--value system is recommended for new classes |
| 473 |
and packages, and is more flexible in handling of option classes than the |
| 474 |
simple text approach. Both option methods use the same basic structure within |
| 475 |
the \LaTeX{} source: declaration of options first then processing options in a |
| 476 |
second step. Both also allow options to be passed on to other packages or an |
| 477 |
underlying class. As the `classical' simple text approach is conceptually more |
| 478 |
straight-forward to illustrate, it is used here to show the general structure: |
| 479 |
see Section~\ref{sec:opt:keyval} for full details of the key--value approach. |
| 480 |
|
| 481 |
An option is declared as follows: |
| 482 |
\begin{verbatim} |
| 483 |
\DeclareOption{<option>}{<code>} |
| 484 |
\end{verbatim} |
| 485 |
For example, the |dvips| option (slightly simplified) |
| 486 |
to the |graphics| package is implemented as: |
| 487 |
\begin{verbatim} |
| 488 |
\DeclareOption{dvips}{\input{dvips.def}} |
| 489 |
\end{verbatim} |
| 490 |
This means that when an author writes |\usepackage[dvips]{graphics}|, the file |
| 491 |
|dvips.def| is loaded. As another example, the |a4paper| option is declared in |
| 492 |
the |article| class to set the |\paperheight| and |\paperwidth| lengths: |
| 493 |
\begin{verbatim} |
| 494 |
\DeclareOption{a4paper}{% |
| 495 |
\setlength{\paperheight}{297mm}% |
| 496 |
\setlength{\paperwidth}{210mm}% |
| 497 |
} |
| 498 |
\end{verbatim} |
| 499 |
Sometimes a user will request an option which the class or package has not |
| 500 |
explicitly declared. By default this will produce a warning (for classes) or |
| 501 |
error (for packages); this behavior can be altered as follows: |
| 502 |
\begin{verbatim} |
| 503 |
\DeclareOption*{<code>} |
| 504 |
\end{verbatim} |
| 505 |
For example, to make the package |fred| produce a warning rather than an error |
| 506 |
for unknown options, you could specify: |
| 507 |
\begin{verbatim} |
| 508 |
\DeclareOption*{% |
| 509 |
\PackageWarning{fred}{Unknown option `\CurrentOption'}% |
| 510 |
} |
| 511 |
\end{verbatim} |
| 512 |
Then, if an author writes |\usepackage[foo]{fred}|, they will get a warning |
| 513 |
\texttt{Package fred Warning: Unknown option `foo'.} As another example, the |
| 514 |
|fontenc| package tries to load a file |<ENC>enc.def| whenever the \m{ENC} |
| 515 |
option is used. This can be done by writing: |
| 516 |
\begin{verbatim} |
| 517 |
\DeclareOption*{% |
| 518 |
\input{\CurrentOption enc.def}% |
| 519 |
} |
| 520 |
\end{verbatim} |
| 521 |
|
| 522 |
It is possible to pass options on to another package or class, using the |
| 523 |
command |\PassOptionsToPackage| or |\PassOptionsToClass| (note that this is a |
| 524 |
specialised operation that works only for option names): see |
| 525 |
Section~\ref{sec:opmove}. For example, to pass every unknown option on to the |
| 526 |
|article| class, you can use: |
| 527 |
\begin{verbatim} |
| 528 |
\DeclareOption*{% |
| 529 |
\PassOptionsToClass{\CurrentOption}{article}% |
| 530 |
} |
| 531 |
\end{verbatim} |
| 532 |
If you do this then you should make sure you load the class at some later |
| 533 |
point, otherwise the options will never be processed! |
| 534 |
|
| 535 |
So far, we have explained only how to declare options, not how to execute them. |
| 536 |
To process the options with which the file was called, you should use: |
| 537 |
\begin{verbatim} |
| 538 |
\ProcessOptions\relax |
| 539 |
\end{verbatim} |
| 540 |
This executes the \m{code} for each option that was both specified and declared |
| 541 |
(see Section~\ref{sec:commands.options} for details of how this is done). |
| 542 |
|
| 543 |
For example, if the |jane| package file contains: |
| 544 |
\begin{verbatim} |
| 545 |
\DeclareOption{foo}{\typeout{Saw foo.}} |
| 546 |
\DeclareOption{baz}{\typeout{Saw baz.}} |
| 547 |
\DeclareOption*{\typeout{What's \CurrentOption?}} |
| 548 |
\ProcessOptions\relax |
| 549 |
\end{verbatim} |
| 550 |
and an author writes |\usepackage[foo,bar]{jane}|, then they will see the |
| 551 |
messages \texttt{Saw foo.} and \texttt{What's bar?} |
| 552 |
|
| 553 |
\subsection{A minimal class file} |
| 554 |
|
| 555 |
Most of the work of a class or package is in defining new commands, or |
| 556 |
changing the appearance of documents. This is done in the body of the |
| 557 |
package, using commands such as |\newcommand| or |\setlength|. |
| 558 |
|
| 559 |
There are four things that every class file \emph{must} contain: these |
| 560 |
are a definition of |\normalsize|, values for |\textwidth| and |
| 561 |
|\textheight| and a specification for page-numbering. So a minimal |
| 562 |
document class file\footnote {This class is now in the standard |
| 563 |
distribution, as \texttt{minimal.cls}.} looks like this: |
| 564 |
\begin{verbatim} |
| 565 |
\NeedsTeXFormat{LaTeX2e} |
| 566 |
\ProvidesClass{minimal}[2022-06-01 Standard LaTeX minimal class] |
| 567 |
\renewcommand{\normalsize}{\fontsize{10pt}{12pt}\selectfont} |
| 568 |
\setlength{\textwidth}{6.5in} |
| 569 |
\setlength{\textheight}{8in} |
| 570 |
\pagenumbering{arabic} % needed even though this class will |
| 571 |
% not show page numbers |
| 572 |
\end{verbatim} |
| 573 |
However, this class file will not support footnotes, marginals, |
| 574 |
floats, etc., nor will it provide any of the 2-letter font commands |
| 575 |
such as |\rm|; thus most classes will contain more than this minimum! |
| 576 |
|
| 577 |
\subsection{Example: a local letter class} |
| 578 |
|
| 579 |
A company may have its own letter class, for setting letters in the |
| 580 |
company style. This section shows a simple implementation of such a |
| 581 |
class, although a real class would need more structure. |
| 582 |
|
| 583 |
The class begins by announcing itself as |neplet.cls|. |
| 584 |
\begin{verbatim} |
| 585 |
\NeedsTeXFormat{LaTeX2e} |
| 586 |
\ProvidesClass{neplet}[2022-06-01 NonExistent Press letter class] |
| 587 |
\end{verbatim} |
| 588 |
Then this next bit passes any options on to the |letter| class, which is loaded |
| 589 |
with the |a4paper| option. |
| 590 |
\begin{verbatim} |
| 591 |
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{letter}} |
| 592 |
\ProcessOptions\relax |
| 593 |
\LoadClass[a4paper]{letter} |
| 594 |
\end{verbatim} |
| 595 |
In order to use the company letter head, it redefines the |firstpage| page |
| 596 |
style: this is the page style that is used on the first page of letters. |
| 597 |
\begin{verbatim} |
| 598 |
\renewcommand{\ps@firstpage}{% |
| 599 |
\renewcommand{\@oddhead}{<letterhead goes here>}% |
| 600 |
\renewcommand{\@oddfoot}{<letterfoot goes here>}% |
| 601 |
} |
| 602 |
\end{verbatim} |
| 603 |
And that's it! |
| 604 |
|
| 605 |
\subsection{Example: a newsletter class} |
| 606 |
\label{subsec:newsletter} |
| 607 |
|
| 608 |
A simple newsletter can be typeset with \LaTeX{}, using a variant of the |
| 609 |
|article| class. The class begins by announcing itself as |smplnews.cls|. |
| 610 |
\begin{verbatim} |
| 611 |
\NeedsTeXFormat{LaTeX2e} |
| 612 |
\ProvidesClass{smplnews}[2022-06-01 The Simple News newsletter class] |
| 613 |
|
| 614 |
\newcommand{\headlinecolor}{\normalcolor} |
| 615 |
\end{verbatim} |
| 616 |
It passes most specified options on to the |article| class: apart from the |
| 617 |
|onecolumn| option, which is switched off, and the |green| option, which sets |
| 618 |
the headline in green. |
| 619 |
\begin{verbatim} |
| 620 |
\DeclareOption{onecolumn}{\OptionNotUsed} |
| 621 |
\DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}} |
| 622 |
|
| 623 |
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} |
| 624 |
|
| 625 |
\ProcessOptions\relax |
| 626 |
\end{verbatim} |
| 627 |
It then loads the class |article| with the option |twocolumn|. |
| 628 |
\begin{verbatim} |
| 629 |
\LoadClass[twocolumn]{article} |
| 630 |
\end{verbatim} |
| 631 |
Since the newsletter is to be printed in colour, it now loads the |color| |
| 632 |
package. The class does not specify a device driver option since this should be |
| 633 |
specified by the user of the |smplnews| class. |
| 634 |
\begin{verbatim} |
| 635 |
\RequirePackage{color} |
| 636 |
\end{verbatim} |
| 637 |
The class then redefines |\maketitle| to produce the title in 72\,pt Helvetica |
| 638 |
bold oblique, in the appropriate colour. |
| 639 |
\begin{verbatim} |
| 640 |
\renewcommand{\maketitle}{% |
| 641 |
\twocolumn[% |
| 642 |
\fontsize{72}{80}\fontfamily{phv}\fontseries{b}% |
| 643 |
\fontshape{sl}\selectfont\headlinecolor |
| 644 |
\@title |
| 645 |
]% |
| 646 |
} |
| 647 |
\end{verbatim} |
| 648 |
It redefines |\section| and switches off section numbering. |
| 649 |
\begin{verbatim} |
| 650 |
\renewcommand{\section}{% |
| 651 |
\@startsection |
| 652 |
{section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}% |
| 653 |
{1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}% |
| 654 |
} |
| 655 |
|
| 656 |
\setcounter{secnumdepth}{0} |
| 657 |
\end{verbatim} |
| 658 |
It also sets the three essential things. |
| 659 |
\begin{verbatim} |
| 660 |
\renewcommand{\normalsize}{\fontsize{9}{10}\selectfont} |
| 661 |
\setlength{\textwidth}{17.5cm} |
| 662 |
\setlength{\textheight}{25cm} |
| 663 |
\end{verbatim} |
| 664 |
In practice, a class would need more than this: it would provide commands for |
| 665 |
issue numbers, authors of articles, page styles and so on; but this skeleton |
| 666 |
gives a start. The |ltnews| class file is not much more complex than this one. |
| 667 |
|
| 668 |
\section{Commands for class and package writers} |
| 669 |
\label{sec:commands} |
| 670 |
|
| 671 |
This section describes briefly each of the commands for class and package |
| 672 |
writers. To find out about other aspects of the system, |
| 673 |
you should also read \emph{\LaTeXbook}, \emph{\LaTeXcomp} and |
| 674 |
\emph{\usrguide}. |
| 675 |
|
| 676 |
\subsection{Identification} |
| 677 |
|
| 678 |
The first group of commands discussed here are those used to identify your |
| 679 |
class or package file. |
| 680 |
|
| 681 |
\begin{decl} |
| 682 |
|\NeedsTeXFormat| \arg{format-name} \oarg{release-date} |
| 683 |
\end{decl} |
| 684 |
This command tells \TeX{} that this file should be processed using a format |
| 685 |
with name \m{format-name}. You can use the optional argument \m{release-date} |
| 686 |
to further specify the earliest release date of the format that is needed. When |
| 687 |
the release date of the format is older than the one specified a warning will |
| 688 |
be generated. The standard \m{format-name} is \texttt{LaTeX2e}. The |
| 689 |
\meta{release-date}, if |
| 690 |
present, must be in the form `\textsc{yyyy-mm-dd}' or |
| 691 |
`\textsc{yyyy/mm/dd}'. |
| 692 |
|
| 693 |
Example: |
| 694 |
\begin{verbatim} |
| 695 |
\NeedsTeXFormat{LaTeX2e}[2022-06-01] |
| 696 |
\end{verbatim} |
| 697 |
People often don't know what date to put here. For the kernel, you can find out |
| 698 |
the right one by consulting |changes.txt| and select the release date of a new |
| 699 |
feature you are interested in. This is slightly different for packages as they |
| 700 |
are released throughout the year: you will need to consult their change |
| 701 |
history. |
| 702 |
|
| 703 |
\begin{decl} |
| 704 |
|\ProvidesClass| \arg{class-name} \oarg{release-info} \\ |
| 705 |
|\ProvidesPackage| \arg{package-name} \oarg{release-info} |
| 706 |
\end{decl} |
| 707 |
This declares that the current file contains the definitions for the document |
| 708 |
class \m{class-name} or package \m{package-name}. |
| 709 |
|
| 710 |
The optional \m{release-info}, if used, must contain: |
| 711 |
\begin{itemize} |
| 712 |
\item the release date of this version of the file, in the form |
| 713 |
\textsc{yyyy-mm-dd}; |
| 714 |
\item optionally followed by a space and a short description, possibly |
| 715 |
including a version number. |
| 716 |
\end{itemize} |
| 717 |
The above syntax must be followed exactly so that this information can be used |
| 718 |
by |\LoadClass| or |\documentclass| (for classes) or |\RequirePackage| or |
| 719 |
|\usepackage| (for packages) to test that the release is not too old. |
| 720 |
|
| 721 |
The whole of this \m{release-info} information is displayed by |\listfiles| and |
| 722 |
should therefore not be too long. |
| 723 |
|
| 724 |
Example: |
| 725 |
\begin{verbatim} |
| 726 |
\ProvidesClass{article}[2022-06-01 v1.0 Standard LaTeX class] |
| 727 |
\ProvidesPackage{ifthen}[2022-06-01 v1.0 Standard LaTeX package] |
| 728 |
\end{verbatim} |
| 729 |
|
| 730 |
\begin{decl} |
| 731 |
|\ProvidesFile| \arg{file-name} \oarg{release-info} |
| 732 |
\end{decl} |
| 733 |
This is similar to the two previous commands except that here the full |
| 734 |
filename, including the extension, must be given. It is used for declaring any |
| 735 |
files other than main class and package files. |
| 736 |
|
| 737 |
Example: |
| 738 |
\begin{verbatim} |
| 739 |
\ProvidesFile{T1enc.def}[2022-06-01 v1.0 Standard LaTeX file] |
| 740 |
\end{verbatim} |
| 741 |
|
| 742 |
Note that the phrase \texttt{Standard LaTeX} \textbf{must not} be used in the |
| 743 |
identification banner of any file other than those in the standard \LaTeX{} |
| 744 |
distribution. |
| 745 |
|
| 746 |
\subsection{Loading files} |
| 747 |
\label{sec:loadf} |
| 748 |
|
| 749 |
This group of commands can be used to create your own document class or package |
| 750 |
by building on existing classes or packages. |
| 751 |
\begin{decl} |
| 752 |
|\RequirePackage| \oarg{options-list} \arg{package-name} |
| 753 |
\oarg{release-info}\\ |
| 754 |
|\RequirePackageWithOptions| \arg{package-name} |
| 755 |
\oarg{release-info} |
| 756 |
\end{decl} |
| 757 |
Packages and classes should use these commands to load other packages. |
| 758 |
|
| 759 |
The use of |\RequirePackage| is the same as the author command |\usepackage|. |
| 760 |
Examples: |
| 761 |
\begin{verbatim} |
| 762 |
\RequirePackage{ifthen}[2022-06-01] |
| 763 |
\RequirePackageWithOptions{graphics}[2022-06-01] |
| 764 |
\end{verbatim} |
| 765 |
|
| 766 |
\begin{decl} |
| 767 |
|\LoadClass| \oarg{options-list} \arg{class-name} |
| 768 |
\oarg{release-info}\\ |
| 769 |
|\LoadClassWithOptions| \arg{class-name} |
| 770 |
\oarg{release-info} |
| 771 |
\end{decl} |
| 772 |
These commands are for use \emph{only} in class files, they cannot be used in |
| 773 |
packages files; they can be used at most once within a class file. |
| 774 |
|
| 775 |
The use of |\LoadClass| is the same as the use of |\documentclass| to load a |
| 776 |
class file. |
| 777 |
|
| 778 |
Examples: |
| 779 |
\begin{verbatim} |
| 780 |
\LoadClass{article}[2022-06-01] |
| 781 |
\LoadClassWithOptions{article}[2022-06-01] |
| 782 |
\end{verbatim} |
| 783 |
|
| 784 |
The two |WithOptions| versions simply load the class (or package) file with |
| 785 |
exactly those options that are being used by the current file (class or |
| 786 |
package). See below, in \ref{sec:opmove}, for further discussion of their use. |
| 787 |
|
| 788 |
\subsection{Delaying code} |
| 789 |
\label{sec:delays} |
| 790 |
|
| 791 |
As noted earlier, a sophisticated hook system is available and described in |
| 792 |
\texttt{lthooks}. Here, we document a small set of convenient short names for |
| 793 |
common hooks. |
| 794 |
|
| 795 |
These first two commands are also intended primarily for use within the |
| 796 |
\m{code} argument of |\DeclareOption| or |\DeclareOption*|. |
| 797 |
|
| 798 |
\begin{decl} |
| 799 |
|\AtEndOfClass| \arg{code}\\ |
| 800 |
|\AtEndOfPackage| \arg{code} |
| 801 |
\end{decl} |
| 802 |
These commands declare \m{code} that is saved away internally and then executed |
| 803 |
after processing the whole of the current class or package file. |
| 804 |
|
| 805 |
Repeated use of these commands is permitted: the code in the arguments is |
| 806 |
stored (and later executed) in the order of their declarations. |
| 807 |
|
| 808 |
\begin{decl} |
| 809 |
|\AtBeginDocument| \arg{code}\\ |
| 810 |
|\AtEndDocument| \arg{code} |
| 811 |
\end{decl} |
| 812 |
These commands declare \m{code} to be saved internally and executed while |
| 813 |
\LaTeX{} is executing |\begin{document}| or |\end{document}|. |
| 814 |
|
| 815 |
The \m{code} specified in the argument to |\AtBeginDocument| is executed near |
| 816 |
the end of the |\begin{document}| code, \emph{after} the font selection tables |
| 817 |
have been set up. It is therefore a useful place to put code which needs to be |
| 818 |
executed after everything has been prepared for typesetting and when the normal |
| 819 |
font for the document is the current font. |
| 820 |
|
| 821 |
The |\AtBeginDocument| hook should not be used for code that does any |
| 822 |
typesetting since the typeset result would be unpredictable. |
| 823 |
|
| 824 |
The \m{code} specified in the argument to |\AtEndDocument| is executed at the |
| 825 |
beginning of the |\end{document}| code, \emph{before} the final page is |
| 826 |
finished and before any leftover floating environments are processed. If some |
| 827 |
of the \m{code} is to be executed after these two processes, you should include |
| 828 |
a |\clearpage| at the appropriate point in \m{code}. |
| 829 |
|
| 830 |
Repeated use of these commands is permitted: the code in the arguments is |
| 831 |
stored (and later executed) in the order of their declarations. |
| 832 |
|
| 833 |
\subsection{Creating and using keyval options} |
| 834 |
\label{sec:opt:keyval} |
| 835 |
|
| 836 |
As with any key--value input, using key--value pairs as package or class |
| 837 |
options has two parts: creating the key options and setting (using) them. |
| 838 |
Options created in this way \emph{may} be used after package loading as general |
| 839 |
key--value settings: this will depend on the nature of the underlying code. |
| 840 |
|
| 841 |
In the following, the \emph{family} for keys is a namespace used in creating |
| 842 |
the keys. At point of use, multiple families may be examined: see |
| 843 |
\cs{ProcessKeyOptions}. |
| 844 |
|
| 845 |
\begin{decl} |
| 846 |
|\DeclareKeys| \oarg{family} \arg{declarations} |
| 847 |
\end{decl} |
| 848 |
This command creates a series of options from a comma-separated |
| 849 |
\m{declarations} list. Each entry in this list is a key--value pair, with the |
| 850 |
\m{key} having one or more \m{properties}. A small number of `basic' |
| 851 |
\m{properties} are described below. The full range of properties, provided by |
| 852 |
\texttt{l3keys}, can also be used for more powerful processing. See |
| 853 |
\texttt{interface3} for the full details. |
| 854 |
|
| 855 |
The basic properties provided here are |
| 856 |
\begin{itemize} |
| 857 |
\item \texttt{.code} --- executes arbitrary code |
| 858 |
\item \texttt{.if} --- sets a \TeX{} |\if...| switch |
| 859 |
\item \texttt{.ifnot} --- sets an inverted \TeX{} |\if...| switch |
| 860 |
\item \texttt{.pass-to-packages} --- for class options, this specifies |
| 861 |
whether the option should be treated \enquote{global} (read by packages |
| 862 |
from the global list); for package options this property has no effect |
| 863 |
\item \texttt{.store} --- stores a value in a macro |
| 864 |
\item \texttt{.usage} -- defines whether the option can be given only |
| 865 |
when loading (\texttt{load}), in the preamble (\texttt{preamble}) or |
| 866 |
has no limitation on scope (\texttt{general}) |
| 867 |
\end{itemize} |
| 868 |
The part of the \meta{key} before the \m{property} is the \m{name}, with the |
| 869 |
\m{value} working with the \m{property} to define the behavior of the option. |
| 870 |
|
| 871 |
For example, with |
| 872 |
\begin{verbatim} |
| 873 |
\DeclareKeys[mypkg] |
| 874 |
{ |
| 875 |
draft.if = @mypkg@draft , |
| 876 |
draft.usage = preamble , |
| 877 |
name.store = \@mypkg@name , |
| 878 |
name.usage = load , |
| 879 |
second-name.store = \@mypkg@other@name |
| 880 |
} |
| 881 |
\end{verbatim} |
| 882 |
three options would be created. The option \texttt{draft} can be given anywhere |
| 883 |
in the preamble, and will set a switch called |\if@mypkg@draft|. The option |
| 884 |
\texttt{name} can only be given during package loading, and will save whatever |
| 885 |
value it is given in |\@mypkg@name|. Finally, the option \texttt{second-name} |
| 886 |
can be given anywhere, and will save its value in |\@mypkg@other@name|. |
| 887 |
|
| 888 |
Keys created \emph{before} the use of |\ProcessKeyOptions| act as package |
| 889 |
options. |
| 890 |
|
| 891 |
\begin{decl} |
| 892 |
|\DeclareUnknownKeyHandler| \oarg{family} \arg{code} |
| 893 |
\end{decl} |
| 894 |
The command |\DeclareUnknownKeyHandler| may be used to define the behavior when |
| 895 |
an undefined key is encountered. The \m{code} will receive the unknown key name |
| 896 |
as |#1| and the value as |#2|. These can then be processed as appropriate, |
| 897 |
e.g.~by forwarding to another package. The entire option is available as |
| 898 |
\cs{CurrentOption}, should it be necessary to pass on options which may or |
| 899 |
may not contain an |=|~sign. For example, this may be used to pass an |
| 900 |
unknown option on to a non-keyval class such as \pkg{article}: |
| 901 |
\begin{verbatim} |
| 902 |
\DeclareUnknownKeyHandler{% |
| 903 |
\PassOptionsToClass{\CurrentOption}{article} |
| 904 |
} |
| 905 |
\end{verbatim} |
| 906 |
|
| 907 |
\begin{decl} |
| 908 |
|\ProcessKeyOptions| \oarg{families} |
| 909 |
\end{decl} |
| 910 |
The |\ProcessKeyOptions| function is used to check the current option list |
| 911 |
against the keys defined for \m{families} (a comma-separated list). Global |
| 912 |
(class) options and local (package) options are checked when this function is |
| 913 |
called in a package. The command will process \emph{all} options given the |
| 914 |
current package or class: there is no need to also apply \cs{ProcessOptions}. |
| 915 |
\cs{ProcessKeyOptions} should appear \emph{only once} in a class or package |
| 916 |
file. |
| 917 |
|
| 918 |
\begin{decl} |
| 919 |
|\SetKeys| \oarg{family} \arg{keyvals} |
| 920 |
\end{decl} |
| 921 |
Sets (applies) the explicit list of \m{keyvals} for the \m{family}: if the |
| 922 |
latter is not given, the value of |\@currname| is used. This command may be used |
| 923 |
within a package to set options before or after using |\ProcessKeyOptions|. |
| 924 |
|
| 925 |
Here is the example from \ref{subsec:newsletter}, using the key-value approach: |
| 926 |
\begin{verbatim} |
| 927 |
\NeedsTeXFormat{LaTeX2e} |
| 928 |
\ProvidesClass{smplnews}[2022-06-01 The Simple News newsletter class] |
| 929 |
|
| 930 |
\newcommand{\headlinecolor}{\normalcolor} |
| 931 |
|
| 932 |
\DeclareKeys[samplnews] |
| 933 |
{ |
| 934 |
onecolumn .code = {\OptionNotUsed} , |
| 935 |
green .code = {\renewcommand{\headlinecolor}{\color{green}}} , |
| 936 |
} |
| 937 |
|
| 938 |
\DeclareUnknownKeyHandler{% |
| 939 |
\PassOptionsToClass{\CurrentOption}{article}} |
| 940 |
|
| 941 |
\ProcessKeyOptions |
| 942 |
|
| 943 |
\LoadClass[twocolumn]{article} |
| 944 |
... |
| 945 |
\end{verbatim} |
| 946 |
|
| 947 |
\subsection{Passing options around} |
| 948 |
\label{sec:opmove} |
| 949 |
|
| 950 |
These two commands are also very useful within the \m{code} argument of |
| 951 |
options. |
| 952 |
\begin{decl} |
| 953 |
|\PassOptionsToPackage| \arg{options-list} \arg{package-name}\\ |
| 954 |
|\PassOptionsToClass| \arg{options-list} \arg{class-name} |
| 955 |
\end{decl} |
| 956 |
The command |\PassOptionsToPackage| passes the option names in \m{options-list} |
| 957 |
to package \m{package-name}. This means that it adds the \m{option-list} to the |
| 958 |
list of options used by any future |\RequirePackage| or |\usepackage| command |
| 959 |
for package \m{package-name}. |
| 960 |
|
| 961 |
Example: |
| 962 |
\begin{verbatim} |
| 963 |
\PassOptionsToPackage{foo,bar}{fred} |
| 964 |
\RequirePackage[baz]{fred} |
| 965 |
\end{verbatim} |
| 966 |
is the same as: |
| 967 |
\begin{verbatim} |
| 968 |
\RequirePackage[foo,bar,baz]{fred} |
| 969 |
\end{verbatim} |
| 970 |
|
| 971 |
Similarly, |\PassOptionsToClass| may be used in a class file to pass options to |
| 972 |
another class to be loaded with |\LoadClass|. |
| 973 |
|
| 974 |
The effects and use of these two commands should be contrasted with those of |
| 975 |
the following two (documented above, in \ref{sec:loadf}): |
| 976 |
\begin{verbatim} |
| 977 |
\LoadClassWithOptions |
| 978 |
\RequirePackageWithOptions |
| 979 |
\end{verbatim} |
| 980 |
The command |\RequirePackageWithOptions| is similar to |\RequirePackage|, but |
| 981 |
it always loads the required package with exactly the same option list as that |
| 982 |
being used by the current class or package, rather than with any option |
| 983 |
explicitly supplied or passed on by |\PassOptionsToPackage|. |
| 984 |
|
| 985 |
The main purpose of |\LoadClassWithOptions| is to allow one class to simply |
| 986 |
build on another, for example: |
| 987 |
\begin{verbatim} |
| 988 |
\LoadClassWithOptions{article} |
| 989 |
\end{verbatim} |
| 990 |
This should be compared with the slightly different construction |
| 991 |
\begin{verbatim} |
| 992 |
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} |
| 993 |
\ProcessOptions\relax |
| 994 |
\LoadClass{article} |
| 995 |
\end{verbatim} |
| 996 |
or |
| 997 |
\begin{verbatim} |
| 998 |
\DeclareUnknownKeyHandler{\PassOptionsToClass{\CurrentOption}{article}} |
| 999 |
\ProcessKeyOptions |
| 1000 |
\LoadClass{article} |
| 1001 |
\end{verbatim} |
| 1002 |
As used above, the effects are more or less the same, but the first is a lot |
| 1003 |
less to type; also the |\LoadClassWithOptions| method runs slightly quicker. |
| 1004 |
|
| 1005 |
If, however, the class declares options of its own then the two constructions |
| 1006 |
are different. Compare, for example: |
| 1007 |
\begin{verbatim} |
| 1008 |
\DeclareOption{landscape}{\@landscapetrue} |
| 1009 |
\ProcessOptions\relax |
| 1010 |
\LoadClassWithOptions{article} |
| 1011 |
\end{verbatim} |
| 1012 |
or |
| 1013 |
\begin{verbatim} |
| 1014 |
\DeclareKeys[mypkg] |
| 1015 |
{ |
| 1016 |
landscape.if = @mypkg@landscape , |
| 1017 |
landscape.usage = load , |
| 1018 |
} |
| 1019 |
\ProcessKeyOptions |
| 1020 |
\LoadClassWithOptions{article} |
| 1021 |
\end{verbatim} |
| 1022 |
with: |
| 1023 |
\begin{verbatim} |
| 1024 |
\DeclareOption{landscape}{\@landscapetrue} |
| 1025 |
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} |
| 1026 |
\ProcessOptions\relax |
| 1027 |
\LoadClass{article} |
| 1028 |
\end{verbatim} |
| 1029 |
or |
| 1030 |
\begin{verbatim} |
| 1031 |
\DeclareKeys[mypkg] |
| 1032 |
{ |
| 1033 |
landscape.if = @mypkg@landscape , |
| 1034 |
landscape.usage = load , |
| 1035 |
} |
| 1036 |
\DeclareUnknownKeyHandler{\PassOptionsToClass{\CurrentOption}{article}} |
| 1037 |
\ProcessKeyOptions |
| 1038 |
\LoadClass{article} |
| 1039 |
\end{verbatim} |
| 1040 |
In the first two, the \textsf{article} class will be loaded with option |
| 1041 |
|landscape| precisely when the current class is called with this option. By |
| 1042 |
contrast, in the second two it will never be called with option |landscape| |
| 1043 |
as in that case \textsf{article} is passed options only by the default option |
| 1044 |
handler, but this handler is not used for |landscape| because that option is |
| 1045 |
explicitly declared. |
| 1046 |
|
| 1047 |
\subsection{Useful status tests} |
| 1048 |
|
| 1049 |
A number of status tests are available which can be used by package and |
| 1050 |
class authors to query the presence and date of other code, the current kernel |
| 1051 |
release and other related ideas. Three forms of each test are provided, one |
| 1052 |
requiring arguments for both \meta{true} and \meta{false} branches, one |
| 1053 |
requiring only a \meta{true} branch and one requiring only a \meta{false} |
| 1054 |
branch. These are indicated in their names as |TF|, |T| and |F|, respectively. |
| 1055 |
Here, we document only the |TF| versions: the other forms are however also |
| 1056 |
available. |
| 1057 |
|
| 1058 |
\begin{decl} |
| 1059 |
|\IfPackageLoadedTF| \arg{package-name} \arg{true code} \arg{false code}\\ |
| 1060 |
|\IfClassLoadedTF| \arg{class-name} \arg{true code} \arg{false code}\\ |
| 1061 |
|\IfFileLoadedTF| \arg{file-name} \arg{true code} \arg{false code} |
| 1062 |
\end{decl} |
| 1063 |
These commands test whether the named package, class or file has been loaded: this is |
| 1064 |
done by using information that must be contained in an appropriate |
| 1065 |
|\Provides...| line, as described in Section~\ref{sec:ID}. In the case of |
| 1066 |
\cs{IfFileLoadedTF}, the full \meta{file-name} must be provided; in contrast, |
| 1067 |
no extension should be given if testing for a package or class. |
| 1068 |
|
| 1069 |
\begin{decl} |
| 1070 |
|\IfPackageLoadedWithOptionsTF| \arg{package-name} \arg{options} \arg{true code} \arg{false code}\\ |
| 1071 |
|\IfClassLoadedWithOptionsTF| \arg{class-name} \arg{options} \arg{true code} \arg{false code} |
| 1072 |
\end{decl} |
| 1073 |
These commands test whether the named package or class has been loaded with |
| 1074 |
\emph{exactly} the \meta{options} specified. In order to take the \meta{true} |
| 1075 |
branch, the package or class must be loaded (giving a \meta{true} result for |
| 1076 |
\cs{If...LoadedT}) and the option list used when loading it must be identical |
| 1077 |
to the \meta{options}. |
| 1078 |
|
| 1079 |
\begin{decl} |
| 1080 |
|\IfPackageAtLeastTF| \arg{package-name} \arg{date} \arg{true code} \arg{false code}\\ |
| 1081 |
|\IfClassAtLeastTF| \arg{class-name} \arg{date} \arg{true code} \arg{false code}\\ |
| 1082 |
|\IfFileAtLeastTF| \arg{file-name} \arg{date} \arg{true code} \arg{false code} |
| 1083 |
\end{decl} |
| 1084 |
These tests are used to check whether the date information given in the |
| 1085 |
|\Provides...| line of a package, class or file is no earlier than the given |
| 1086 |
\meta{date}. The \meta{date} is compared with that in the |
| 1087 |
optional argument to \cs{Provides...} (as described in Section~\ref{sec:ID}); |
| 1088 |
if \cs{Provides...} was missing or had no optional argument, it is treated |
| 1089 |
as |0000/00/00| (i.e.~earlier than any other date). |
| 1090 |
As for \cs{Provides...}, the \meta{date} should be given in the form |
| 1091 |
`\textsc{yyyy-mm-dd}' or `\textsc{yyyy/mm/dd}'. If the package, class or file is not |
| 1092 |
loaded, the \meta{false} branch will be taken; in contrast, if the \meta{date} |
| 1093 |
is not given in the required form, the behavior is formally undefined. |
| 1094 |
|
| 1095 |
\begin{decl} |
| 1096 |
|\IfFormatAtLeastTF| \arg{date} \arg{true code} \arg{false code} |
| 1097 |
\end{decl} |
| 1098 |
Tests the release \meta{date} of the \LaTeX{} format and selects the |
| 1099 |
appropriate branch. The date used by the format is adjusted to incorporate any |
| 1100 |
roll forward or back that has been applied to it, so that the apparent date |
| 1101 |
of the format will be that after roll forward or back. |
| 1102 |
|
| 1103 |
\subsection{Safe file commands} |
| 1104 |
|
| 1105 |
These commands deal with file input; they ensure that the non-existence of a |
| 1106 |
requested file can be handled in a user-friendly way. |
| 1107 |
|
| 1108 |
\begin{decl} |
| 1109 |
|\IfFileExists| \arg{file-name} \arg{true} \arg{false} |
| 1110 |
\end{decl} |
| 1111 |
If the file exists then the code specified in \m{true} is executed. |
| 1112 |
|
| 1113 |
If the file does not exist then the code specified in \m{false} is executed. |
| 1114 |
|
| 1115 |
This command does \emph{not} input the file. |
| 1116 |
|
| 1117 |
\begin{decl} |
| 1118 |
|\InputIfFileExists| \arg{file-name} \arg{true} \arg{false} |
| 1119 |
\end{decl} |
| 1120 |
This inputs the file \m{file-name} if it exists and, immediately before the |
| 1121 |
input, the code specified in \m{true} is executed. |
| 1122 |
|
| 1123 |
If the file does not exist then the code specified in \m{false} is executed. |
| 1124 |
|
| 1125 |
It is implemented using |\IfFileExists|. |
| 1126 |
|
| 1127 |
\subsection{Reporting errors, etc} |
| 1128 |
|
| 1129 |
These commands should be used by third party classes and packages to report |
| 1130 |
errors, or to provide information to authors. |
| 1131 |
|
| 1132 |
\begin{decl} |
| 1133 |
|\ClassError| \arg{class-name} \arg{error-text} \arg{help-text}\\ |
| 1134 |
|\PackageError| \arg{package-name} \arg{error-text} \arg{help-text} |
| 1135 |
\end{decl} |
| 1136 |
These produce an error message. The \m{error-text} is displayed and the |?| |
| 1137 |
error prompt is shown. If the user types |h|, they will be shown the |
| 1138 |
\m{help-text}. |
| 1139 |
|
| 1140 |
Within the \m{error-text} and \m{help-text}: |\protect| can be used to stop a |
| 1141 |
command from expanding; |\MessageBreak| causes a line-break; and |\space| |
| 1142 |
prints a space. |
| 1143 |
|
| 1144 |
Note that the \m{error-text} will have a full stop added to it, so do not put |
| 1145 |
one into the argument. |
| 1146 |
|
| 1147 |
For example: |
| 1148 |
\begin{verbatim} |
| 1149 |
\newcommand{\foo}{FOO} |
| 1150 |
\PackageError{ethel}{% |
| 1151 |
Your hovercraft is full of eels,\MessageBreak |
| 1152 |
and \protect\foo\space is \foo |
| 1153 |
}{% |
| 1154 |
Oh dear! Something's gone wrong.\MessageBreak |
| 1155 |
\space \space Try typing \space <<return>> |
| 1156 |
\space to proceed, ignoring \protect\foo. |
| 1157 |
} |
| 1158 |
\end{verbatim} |
| 1159 |
produces this display: |
| 1160 |
\begin{verbatim} |
| 1161 |
! Package ethel Error: Your hovercraft is full of eels, |
| 1162 |
(ethel) and \foo is FOO. |
| 1163 |
|
| 1164 |
See the ethel package documentation for explanation. |
| 1165 |
\end{verbatim} |
| 1166 |
If the user types |h|, this will be shown: |
| 1167 |
\begin{verbatim} |
| 1168 |
Oh dear! Something's gone wrong. |
| 1169 |
Try typing <<return>> to proceed, ignoring \foo. |
| 1170 |
\end{verbatim} |
| 1171 |
|
| 1172 |
\begin{decl} |
| 1173 |
|\ClassWarning| \arg{class-name} \arg{warning-text}\\ |
| 1174 |
|\PackageWarning| \arg{package-name} \arg{warning-text}\\ |
| 1175 |
|\ClassWarningNoLine| \arg{class-name} \arg{warning-text}\\ |
| 1176 |
|\PackageWarningNoLine| \arg{package-name} \arg{warning-text}\\ |
| 1177 |
|\ClassInfo| \arg{class-name} \arg{info-text}\\ |
| 1178 |
|\PackageInfo| \arg{package-name} \arg{info-text} |
| 1179 |
\end{decl} |
| 1180 |
The four |Warning| commands are similar to the error commands, except that they |
| 1181 |
produce only a warning on the screen, with no error prompt. |
| 1182 |
|
| 1183 |
The first two, |Warning| versions, also show the line number where the warning |
| 1184 |
occurred, whilst the second two, |WarningNoLine| versions, do not. |
| 1185 |
|
| 1186 |
The two |Info| commands are similar except that they log the information only |
| 1187 |
in the transcript file, including the line number. There are no |NoLine| |
| 1188 |
versions of these two. |
| 1189 |
|
| 1190 |
Within the \m{warning-text} and \m{info-text}: |\protect| can be used to stop a |
| 1191 |
command from expanding; |\MessageBreak| causes a line-break; and |\space| |
| 1192 |
prints a space. Also, these should not end with a full stop as one is |
| 1193 |
automatically added. |
| 1194 |
|
| 1195 |
\section{Miscellaneous commands, etc.} |
| 1196 |
\label{sec:commands.misc} |
| 1197 |
|
| 1198 |
\subsection{Layout parameters} |
| 1199 |
|
| 1200 |
\begin{decl} |
| 1201 |
|\paperheight|\\ |
| 1202 |
|\paperwidth| |
| 1203 |
\end{decl} |
| 1204 |
These two parameters are usually set by the class to be the size of the paper |
| 1205 |
being used. This should be actual paper size, unlike |\textwidth| and |
| 1206 |
|\textheight| which are the size of the main text body within the margins. |
| 1207 |
|
| 1208 |
\subsection{Case changing} |
| 1209 |
\label{sec:case} |
| 1210 |
|
| 1211 |
\begin{decl} |
| 1212 |
|\MakeUppercase| \oarg{keyvals} \arg{text} \\ |
| 1213 |
|\MakeLowercase| \oarg{keyvals} \arg{text} \\ |
| 1214 |
|\MakeTitlecase| \oarg{keyvals} \arg{text} |
| 1215 |
\end{decl} |
| 1216 |
|
| 1217 |
As described in \texttt{usrguide}, case changing for text should be carried out |
| 1218 |
using the commands |\MakeUppercase|, |\MakeLowercase| and |
| 1219 |
|\MakeTitlecase|. If you need to change the case of programmatic material, the |
| 1220 |
team strongly suggest using the L3 programming layer commands in the |
| 1221 |
\texttt{l3str} module. If you do not wish to do this, you should use the \TeX{} |
| 1222 |
|\uppercase| and |\lowercase| primitives \emph{in this situation only}. |
| 1223 |
|
| 1224 |
\subsection{Better user-defined math display environments} |
| 1225 |
|
| 1226 |
\begin{decl} |
| 1227 |
|\ignorespacesafterend| |
| 1228 |
\end{decl} |
| 1229 |
|
| 1230 |
Suppose that you want to define an environment for displaying text that is |
| 1231 |
numbered as an equation. A straightforward way to do this is as follows: |
| 1232 |
\begin{verbatim} |
| 1233 |
\newenvironment{texteqn}{% |
| 1234 |
\begin{equation}% |
| 1235 |
\begin{minipage}{0.9\linewidth}% |
| 1236 |
}{% |
| 1237 |
\end{minipage}% |
| 1238 |
\end{equation}% |
| 1239 |
} |
| 1240 |
\end{verbatim} |
| 1241 |
However, if you have tried this then you will probably have noticed that it |
| 1242 |
does not work perfectly when used in the middle of a paragraph because an |
| 1243 |
inter-word space appears at the beginning of the first line after the |
| 1244 |
environment. |
| 1245 |
|
| 1246 |
You can avoid this problem using |\ignorespacesafterend|; it should be |
| 1247 |
inserted as shown here: |
| 1248 |
\begin{verbatim} |
| 1249 |
\newenvironment{texteqn}{% |
| 1250 |
\begin{equation}% |
| 1251 |
\begin{minipage}{0.9\linewidth}% |
| 1252 |
}{% |
| 1253 |
\end{minipage}% |
| 1254 |
\end{equation}% |
| 1255 |
\ignorespacesafterend |
| 1256 |
} |
| 1257 |
\end{verbatim} |
| 1258 |
|
| 1259 |
This command may also have other uses. |
| 1260 |
|
| 1261 |
\subsection{Normalising spacing} |
| 1262 |
|
| 1263 |
\begin{decl} |
| 1264 |
|\normalsfcodes| |
| 1265 |
\end{decl} |
| 1266 |
|
| 1267 |
This command should be used to restore the normal settings of the |
| 1268 |
parameters that affect spacing between words, sentences, etc. |
| 1269 |
|
| 1270 |
An important use of this feature is to correct a problem, reported by Donald |
| 1271 |
Arseneau, that punctuation in page headers has always (in all known \TeX{} |
| 1272 |
formats) been potentially wrong whenever a page break happens while a local |
| 1273 |
setting of the space codes is in effect. These space codes are changed by, for |
| 1274 |
example, the command \verb|\frenchspacing|) and the \textsf{verbatim} |
| 1275 |
environment. |
| 1276 |
|
| 1277 |
It is normally given the correct definition automatically in |\begin{document}| |
| 1278 |
and so need not be explicitly set; however, if it is explicitly made non-empty |
| 1279 |
in a class file then automatic default setting will be over-ridden. |
| 1280 |
|
| 1281 |
\subsection{Querying localisation} |
| 1282 |
|
| 1283 |
Localisation information is needed to customise a range of outputs. The |
| 1284 |
\LaTeX{} kernel does not itself manage localisation, which is well-served by |
| 1285 |
the bundles \pkg{babel} and \pkg{polyglossia}. To allow the kernel and other |
| 1286 |
packages to access the current localisation information provided by \pkg{babel} |
| 1287 |
or \pkg{polyglossia}, the command \cs{BCPdata} is defined by the kernel. The |
| 1288 |
initial kernel definition expands to tag parts for \texttt{en-US}, as the |
| 1289 |
kernel does not track localisation but does start out with a broadly US~English |
| 1290 |
setup. However, if \pkg{babel} or \pkg{polyglossia} are loaded, it is redefined |
| 1291 |
expand to the BCP-47 information from the appropriate package. The supported |
| 1292 |
arguments are the BCP-47 tag breakdowns: |
| 1293 |
\begin{itemize} |
| 1294 |
\item \texttt{tag} The full BCP-47 tag (e.g.~\texttt{en-US}) |
| 1295 |
\item \texttt{language} (e.g.,~\texttt{de}) |
| 1296 |
\item \texttt{region} (e.g.,~\texttt{AT}) |
| 1297 |
\item \texttt{script} (e.g.,~\texttt{Latn}) |
| 1298 |
\item \texttt{variant} (e.g.,~\texttt{1901}) |
| 1299 |
\item \texttt{extension.t} (transformation, e.g.,~\texttt{en-t-ja}) |
| 1300 |
\item \texttt{extension.u} (additional locale |
| 1301 |
information, e.g.,~\texttt{ar-u-nu-latn}) |
| 1302 |
\item \texttt{extension.x} (private use area, e.g.,~\texttt{la-x-classic}) |
| 1303 |
\end{itemize} |
| 1304 |
The information for the \emph{main} language for a document is be provided |
| 1305 |
if these are prefixed by \texttt{main.}, e.g.~\texttt{main.language} will |
| 1306 |
expand to the main language even if another language is currently active. |
| 1307 |
|
| 1308 |
In addition to the tag breakdown, the following semantic arguments are |
| 1309 |
supported |
| 1310 |
\begin{itemize} |
| 1311 |
\item \texttt{casing} The tag for case changing, e.g.~\texttt{el-x-iota} |
| 1312 |
could be selected rather than \texttt{el} to select a capital adscript |
| 1313 |
iota on uppercasing an \emph{ypogegrammeni} |
| 1314 |
\end{itemize} |
| 1315 |
|
| 1316 |
For example, the case changing command \cs{MakeUppercase} is (conceptually) |
| 1317 |
defined as |
| 1318 |
\begin{verbatim} |
| 1319 |
\ExpandArgs{e}\MakeUppercaseAux{\BCPdata{casing}}{#1} |
| 1320 |
\end{verbatim} |
| 1321 |
where |#1| is the user input and the first argument to |
| 1322 |
\cs{MakeUppercaseAux} takes two arguments, the locale and input text. |
| 1323 |
|
| 1324 |
\subsection{Extended and expandable references of properties} |
| 1325 |
|
| 1326 |
A property is something that \LaTeX{} can track while processing |
| 1327 |
the document, such as a page |
| 1328 |
number, a heading number, other counter values, a heading title, |
| 1329 |
a position on the page, etc. |
| 1330 |
The current value of such properties can be labeled and |
| 1331 |
written to the \texttt{aux}-file. It can then be referenced in |
| 1332 |
the next compilation, similar to the way the standard \cs{label}/\cs{ref} |
| 1333 |
commands work (they record/reference a fixed set of properties: |
| 1334 |
label, page, title, and target). |
| 1335 |
|
| 1336 |
\begin{decl} |
| 1337 |
|\RecordProperties|\arg{label}\arg{list of properties} |
| 1338 |
\end{decl} |
| 1339 |
This command writes the value(s) of the \meta{list of properties} |
| 1340 |
\texttt{aux}-file labeled by \meta{label}. Recorded are either the |
| 1341 |
values current when \cs{RecordProperties} is called or the value |
| 1342 |
current when the next shipout happens---which depends on the |
| 1343 |
declaration for each property. |
| 1344 |
% |
| 1345 |
The arguments \meta{label} and \meta{list of properties} can contain |
| 1346 |
commands that are expanded. \meta{label} can expand to an arbitrary |
| 1347 |
string (as long as it can safely be written to the \texttt{aux}-file) |
| 1348 |
but note that the label names of \cs{label} and \cs{RecordProperties} |
| 1349 |
share a single namespace. This means that you get a \texttt{Label `A' |
| 1350 |
multiply defined} warning with the following code: |
| 1351 |
\begin{verbatim} |
| 1352 |
\label{A}\RecordProperties{A}{abspage} |
| 1353 |
\end{verbatim} |
| 1354 |
|
| 1355 |
|
| 1356 |
\begin{decl} |
| 1357 |
|\RefProperty|\arg{label}\arg{property} |
| 1358 |
\end{decl} |
| 1359 |
This command allows to reference the value of the property |
| 1360 |
\meta{property} recorded in the previous run and labeled by \meta{label}. |
| 1361 |
Differently to the standard |
| 1362 |
\cs{ref} command the command is expandable and the value can for |
| 1363 |
example---if it is a number---be used in an assignment.\footnote{For |
| 1364 |
this to work the default value for the property would need to be a number too, |
| 1365 |
because recorded values aren't known in the first \LaTeX{} run.} |
| 1366 |
|
| 1367 |
\begin{verbatim} |
| 1368 |
\section{A section} |
| 1369 |
\RecordProperties{mylabel}{pagenum,counter} |
| 1370 |
\RefProperty{mylabel}{counter} % outputs section |
| 1371 |
\setcounter{mycounter}{\RefProperty{mylabel}{pagenum}} |
| 1372 |
\end{verbatim} |
| 1373 |
|
| 1374 |
|
| 1375 |
|
| 1376 |
As \cs{RefProperty} is expandable it can not issue a rerun warning if |
| 1377 |
a label is not found. If needed such a warning can be forced by the |
| 1378 |
following command: |
| 1379 |
\begin{decl} |
| 1380 |
|\RefUndefinedWarn|\arg{label}\arg{property} |
| 1381 |
\end{decl} |
| 1382 |
|
| 1383 |
\LaTeX{} predefines a set of properties, this set contains also the |
| 1384 |
properties stored by the standard \cs{label} command. In the list |
| 1385 |
below \enquote{default} indicates the value returned when the value is |
| 1386 |
not yet known (i.e., if it wasn't recorded in the previous run and |
| 1387 |
\enquote{at shipout} means that this property is not recorded |
| 1388 |
immediately when \cs{RecordProperties} is used but during the next |
| 1389 |
\cs{shipout}. |
| 1390 |
|
| 1391 |
\begin{description} |
| 1392 |
\item[\texttt{abspage} (default: \texttt{0}, at shipout)] The absolute value of the current page: |
| 1393 |
starts at $1$ and increases monotonically at each shipout. |
| 1394 |
|
| 1395 |
\item[\texttt{page} (default: \texttt{0}, at shipout)] The current page as given by \cs{thepage}: this may or |
| 1396 |
may not be a numerical value, depending on the current |
| 1397 |
style. Contrast with \texttt{abspage}. You get this value also with |
| 1398 |
the standard \cs{label}/\cs{pageref}. |
| 1399 |
|
| 1400 |
\item[\texttt{pagenum} (default: \texttt{0}, at shipout)] The current page as arabic number. This is |
| 1401 |
suitable for integer operations and comparisons. |
| 1402 |
|
| 1403 |
\item[\texttt{label} (default: \texttt{??})] The content of \cs{@currentlabel}. This is the value |
| 1404 |
that you get also with the standard \cs{label}/\cs{ref}. |
| 1405 |
|
| 1406 |
\item[\texttt{title} (default: \texttt{\cs{textbf}\{??\}})] The content of \cs{@currentlabelname}. This |
| 1407 |
command is filled beside others by the \pkg{nameref} package and |
| 1408 |
some classes (e.g.~\pkg{memoir}) and typically gives |
| 1409 |
the title defined in the document by some sectioning command |
| 1410 |
|
| 1411 |
\item[\texttt{target} (default: \meta{\mdseries empty})] The content of \cs{@currentHref}. This |
| 1412 |
command is normally filled by \pkg{hyperref} and holds the name of |
| 1413 |
the last destination it created. |
| 1414 |
|
| 1415 |
\item[\texttt{pagetarget} (default: \meta{\mdseries empty}, at shipout)] |
| 1416 |
The content of \cs{@currentHpage}. This command is filled by |
| 1417 |
\pkg{hyperref} (version v7.01c or newer) and holds the name of the last |
| 1418 |
page anchor it created. |
| 1419 |
|
| 1420 |
\item[\texttt{counter} (default: \meta{\mdseries empty})] The content of \cs{@currentcounter}. This |
| 1421 |
command contains after a \cs{refstepcounter} the name of the |
| 1422 |
counter. |
| 1423 |
|
| 1424 |
\item[\texttt{xpos}, \texttt{ypos} (default: \texttt{0}, at shipout)] These properties records the |
| 1425 |
$x$~and $y$ coordinates of a point previously stored with |
| 1426 |
\cs{pdfsavepos}/\cs{savepos}. E.g.~(if \pkg{bidi} is used it can |
| 1427 |
be necessary to save the position before and after the label): |
| 1428 |
\begin{verbatim} |
| 1429 |
\pdfsavepos |
| 1430 |
\RecordProperties{myposition}{xpos,ypos}% |
| 1431 |
\pdfsavepos |
| 1432 |
\end{verbatim} |
| 1433 |
\end{description} |
| 1434 |
|
| 1435 |
Class and package authors can define more properties to store other |
| 1436 |
values they are interested in. |
| 1437 |
\begin{decl} |
| 1438 |
|\NewProperty|\arg{name}\arg{setpoint}\arg{default}\arg{code}\\ |
| 1439 |
|\SetProperty|\arg{name}\arg{setpoint}\arg{default}\arg{code} |
| 1440 |
\end{decl} |
| 1441 |
These commands declare or change a property \meta{name}\footnote{Only change |
| 1442 |
properties that you have declared. The declarations of standard properties of \LaTeX{} and |
| 1443 |
properties of other packages should never be altered!}. If a new property is |
| 1444 |
declared within a package it is suggested that its name is always structured |
| 1445 |
as follows: \meta{package-name}\texttt{/}\meta{property-name}. |
| 1446 |
\meta{setpoint} is either |now| or |shipout| and decides if the value is |
| 1447 |
written directly or at the next shipout. \meta{default} is used if the |
| 1448 |
property is referenced but not yet known, e.g., in the first run. |
| 1449 |
\meta{code} is the code executed when storing the value. For example, the |
| 1450 |
\texttt{pagenum} property is declared as |
| 1451 |
\begin{verbatim} |
| 1452 |
\NewProperty{pagenum}{shipout}{0}{\the\value{page}} |
| 1453 |
\end{verbatim} |
| 1454 |
|
| 1455 |
The commands related to properties are offered as a set of CamelCase |
| 1456 |
commands for traditional \LaTeXe{} packages (and for use in the |
| 1457 |
document preamble if needed) as well as \texttt{expl3} commands for |
| 1458 |
modern packages, that use the L3 programming layer of \LaTeX{}. The |
| 1459 |
\texttt{expl3} commands and more details can be found in |
| 1460 |
\texttt{ltproperties-doc.pdf}. |
| 1461 |
|
| 1462 |
\subsubsection{Templates (prototype document commands)} |
| 1463 |
|
| 1464 |
\emph{Templates} as defined by \LaTeX{} are a mechanism to cleanly separate the |
| 1465 |
three layers needed for writing a document |
| 1466 |
\begin{enumerate} |
| 1467 |
\item authoring of the text with mark-up; |
| 1468 |
\item document layout design; |
| 1469 |
\item implementation (with \TeX{} programming) of the design. |
| 1470 |
\end{enumerate} |
| 1471 |
They allow document authors to modify design without altering code, and allow |
| 1472 |
programmers to make portable changes to classes. |
| 1473 |
|
| 1474 |
Implementing this mechanism requires a number of steps and a family of commands |
| 1475 |
which allow variation in outcomes. A typical use of templates will make use of |
| 1476 |
most or all of |\NewTemplateType|, |\DeclareTemplateInterface|, |
| 1477 |
|\DeclareTemplateCode|, |\DeclareInstance| and |\UseInstance|, plus potentially |
| 1478 |
some more specialised commands. These are described in \texttt{lttemplates-doc} |
| 1479 |
in full detail. |
| 1480 |
|
| 1481 |
\subsection{Preparing link targets} |
| 1482 |
|
| 1483 |
Active links in a document need targets to which they can jump to. Such |
| 1484 |
targets are often created automatically (if the package \pkg{hyperref} |
| 1485 |
is loaded) by the \cs{refstepcounter} command but there are also cases |
| 1486 |
where class or package authors need to add a target manually, for |
| 1487 |
example, in unnumbered sectioning commands or in environments. For this |
| 1488 |
\LaTeX{} provides the following commands. \emph{Without} |
| 1489 |
\pkg{hyperref} they do nothing or insert only a whatsits |
| 1490 |
(to ensure that spacing doesn't change when hyperref is loaded), \emph{with} |
| 1491 |
\pkg{hyperref} they add the necessary targets. Details about the |
| 1492 |
behavior and the arguments of the following commands can by found in |
| 1493 |
the \pkg{hyperref} package in \texttt{hyperref-linktarget.pdf}. |
| 1494 |
|
| 1495 |
\begin{decl} |
| 1496 |
|\MakeLinkTarget|\oarg{prefix}\arg{counter}\\ |
| 1497 |
|\MakeLinkTarget|\oarg{prefix}\{\}\\ |
| 1498 |
|\MakeLinkTarget|*\arg{target name} |
| 1499 |
\end{decl} |
| 1500 |
This command prepares the creations of targets. |
| 1501 |
|
| 1502 |
\begin{decl} |
| 1503 |
|\LinkTargetOn|\\ |
| 1504 |
|\LinkTargetOff| |
| 1505 |
\end{decl} |
| 1506 |
These commands allow to enable and disable locally the creation of |
| 1507 |
targets. This can be useful to suppress targets otherwise created automatically |
| 1508 |
by \cs{refstepcounter}. |
| 1509 |
|
| 1510 |
\begin{decl} |
| 1511 |
|\NextLinkTarget|\arg{target name} |
| 1512 |
\end{decl} |
| 1513 |
This changes the name of the next target that will be created. |
| 1514 |
|
| 1515 |
|
| 1516 |
\subsection{Querying document command argument specifications} |
| 1517 |
|
| 1518 |
There are some specialized cases in which a package author may need to query |
| 1519 |
the argument specification of a command. When commands are created using |
| 1520 |
\cs{NewDocumentCommand}, etc., this is possible using the \emph{code} level |
| 1521 |
function \cs{\detokenize{cmd_arg_spec:N}}. The function will \emph{expand} to |
| 1522 |
the argument specification if available, or \texttt{X} if this is not |
| 1523 |
available. The latter case is true for undefined commands and those created |
| 1524 |
using \cs{newcommand}, \cs{DeclareRobustCommand} or \cs{def}. |
| 1525 |
\section{Configuring the Output routine} |
| 1526 |
|
| 1527 |
For nearly 40 years \LaTeX's output routine (the mechanism to paginate |
| 1528 |
the document and attach footnotes, floats and headers \& footers) was |
| 1529 |
a largely hardwired algorithm with a limited number of configuration |
| 1530 |
possibilities. Packages or classes that attempted to alter one or the |
| 1531 |
other aspect of the process had to overwrite the internals with the |
| 1532 |
usual problems: incompatibilities and out of date code whenever |
| 1533 |
something was changed in \LaTeX{}. |
| 1534 |
|
| 1535 |
To improve this situation and to support the production of accessible |
| 1536 |
PDF documents we started in 2024 to refactor the output routine and |
| 1537 |
have added a number of hooks and sockets, so that packages that want |
| 1538 |
to adjust the output routine can do so safely without the dangers |
| 1539 |
associated with that in the past. |
| 1540 |
|
| 1541 |
For packages, we implemented the following hooks: |
| 1542 |
\begin{description} |
| 1543 |
\item[\hook{build/page/before}, \hook{build/page/after}] |
| 1544 |
These two hooks enable packages to prepend or append code to |
| 1545 |
the page processing in the output routine. They are |
| 1546 |
implemented as mirrored hooks. |
| 1547 |
|
| 1548 |
Technically, they are executed at the start and the end of the |
| 1549 |
internal \LaTeXe{} \cs{@outputpage} command, respectively. A |
| 1550 |
number of packages alter that command to place code in exactly |
| 1551 |
these two places---they can now simply add their code to the |
| 1552 |
hooks instead. |
| 1553 |
|
| 1554 |
\item[\hook{build/page/reset}] |
| 1555 |
Packages that set up special conventions for text in the main |
| 1556 |
galley (such as catcode changes, etc.)\ can use this hook to |
| 1557 |
undo these changes within the output routine, so that they |
| 1558 |
aren't applied to unrelated material, e.g., the text for |
| 1559 |
running header or footers. |
| 1560 |
|
| 1561 |
\item[\hook{build/column/before}, \hook{build/column/after}] |
| 1562 |
These two hooks enable packages to prepend or append code to |
| 1563 |
the column processing in the output routine. They are |
| 1564 |
implemented as mirrored hooks. |
| 1565 |
|
| 1566 |
Technically, they are executed at the start and the end of the |
| 1567 |
internal \LaTeXe{} \cs{@makecol} command, respectively. A |
| 1568 |
number of packages alter \cs{@makecol} to place code in exactly |
| 1569 |
these two places---they can now simply add their code to the |
| 1570 |
hooks instead. |
| 1571 |
\end{description} |
| 1572 |
|
| 1573 |
We also added a number of sockets for configuring the algorithm and to |
| 1574 |
support tagging. One socket that is of interest for class files but |
| 1575 |
also for user in the document preamble is |
| 1576 |
\socket{build/column/outputbox}. It defines how the column text, the |
| 1577 |
column floats (top and bottom) and the footnotes are combined, |
| 1578 |
i.e. their order and spacing. To change the layout all one has to do |
| 1579 |
is to assign a different predefined plug to the socket with |
| 1580 |
\begin{flushleft} |
| 1581 |
\verb= \AssignSocketPlug{build/column/outputbox}{=\meta{plug-name}\verb=}= |
| 1582 |
\end{flushleft} |
| 1583 |
The predeclared plugs are the following: |
| 1584 |
\begin{description} |
| 1585 |
\item[\plug{space-footnotes-floats}] |
| 1586 |
|
| 1587 |
After the galley text there is a vertical \cs{vfill} |
| 1588 |
followed by the footnotes, followed by the bottom floats, if any. |
| 1589 |
|
| 1590 |
\item[\plug{footnotes-space-floats}] |
| 1591 |
|
| 1592 |
As before but the \cs{vfill} is between footnotes and floats. |
| 1593 |
|
| 1594 |
\item[\plug{floats-space-footnotes}] |
| 1595 |
|
| 1596 |
Floats are directly after the text, then a space and then footnotes |
| 1597 |
at the bottom. |
| 1598 |
|
| 1599 |
\item[\plug{space-floats-footnotes}] |
| 1600 |
|
| 1601 |
Both floats and footnotes are pushed to the bottom with footnotes |
| 1602 |
coming last.\footnote{There are two more permutations, but neither |
| 1603 |
of them has ever been requested so they aren't set up by default |
| 1604 |
--- doing that in a class would be trivial though.} |
| 1605 |
|
| 1606 |
\item[\plug{floats-footnotes}] |
| 1607 |
|
| 1608 |
All excess space is distributed across the existing |
| 1609 |
glue on the page, e.g., within the text galley, the |
| 1610 |
separation between blocks, etc. |
| 1611 |
The order is text, floats, footnotes. |
| 1612 |
|
| 1613 |
\item[\plug{footnotes-floats}] |
| 1614 |
|
| 1615 |
As the previous one but floats and footnotes are swapped. This is |
| 1616 |
the \LaTeX{} default for newer documents, i.e., this plug is |
| 1617 |
assigned to the socket when \cs{DocumentMetadata} is used. |
| 1618 |
|
| 1619 |
\item[\plug{footnotes-floats-legacy}] |
| 1620 |
|
| 1621 |
As the previous one but \LaTeX{}'s bottom skip bug is not |
| 1622 |
corrected, i.e., in ragged bottom designs where footnotes |
| 1623 |
are supposed to be directly attached to the text, they suddenly |
| 1624 |
appear at the bottom of the page when the page is ended with |
| 1625 |
\cs{newpage} or \cs{clearpage}. |
| 1626 |
While this is clearly a bug, it was the case since the days |
| 1627 |
of \LaTeX~2.09; thus for |
| 1628 |
compatibility we continue to support this behavior. |
| 1629 |
\end{description} |
| 1630 |
There are a few more configuration possibilities but they are so |
| 1631 |
specialized that we have only documented them in the \LaTeX{} source |
| 1632 |
in chapter 54 (which can be viewed with \texttt{texdoc source2e}). |
| 1633 |
|
| 1634 |
|
| 1635 |
|
| 1636 |
\section{Commands superseded for new material} |
| 1637 |
|
| 1638 |
A small number of commands were introduced as part of \LaTeXe{} in the |
| 1639 |
mid-1990s, are widely used but have been superseded by more modern |
| 1640 |
methods. These are covered here as they are likely to be encountered |
| 1641 |
routinely in existing classes and packages. |
| 1642 |
|
| 1643 |
\subsection{Defining commands} |
| 1644 |
|
| 1645 |
The \texttt{*}-forms of these commands should be used to define |
| 1646 |
commands that are not, in \TeX{} terms, long. This can be useful for |
| 1647 |
error-trapping with commands whose arguments are not intended to |
| 1648 |
contain whole paragraphs of text. |
| 1649 |
|
| 1650 |
\begin{decl} |
| 1651 |
|\DeclareRobustCommand| \arg{cmd} \oarg{num} \oarg{default} |
| 1652 |
\arg{definition}\\ |
| 1653 |
|\DeclareRobustCommand*| \arg{cmd} \oarg{num} \oarg{default} |
| 1654 |
\arg{definition} |
| 1655 |
\end{decl} |
| 1656 |
This command takes the same arguments as |\newcommand| but it declares a robust |
| 1657 |
command, even if some code within the \m{definition} is fragile. You can use |
| 1658 |
this command to define new robust commands, or to redefine existing commands |
| 1659 |
and make them robust. A log is put into the transcript file if a command is |
| 1660 |
redefined. |
| 1661 |
|
| 1662 |
For example, if |\seq| is defined as follows: |
| 1663 |
\begin{verbatim} |
| 1664 |
\DeclareRobustCommand{\seq}[2][n]{% |
| 1665 |
\ifmmode |
| 1666 |
#1_{1}\ldots#1_{#2}% |
| 1667 |
\else |
| 1668 |
\PackageWarning{fred}{You can't use \protect\seq\space in text}% |
| 1669 |
\fi |
| 1670 |
} |
| 1671 |
\end{verbatim} |
| 1672 |
Then the command |\seq| can be used in moving arguments, even though |
| 1673 |
|\ifmmode| cannot, for example: |
| 1674 |
\begin{verbatim} |
| 1675 |
\section{Stuff about sequences $\seq{x}$} |
| 1676 |
\end{verbatim} |
| 1677 |
|
| 1678 |
Note also that there is no need to put a |\relax| before the |\ifmmode| at the |
| 1679 |
beginning of the definition; this is because the protection given by this |
| 1680 |
|\relax| against expansion at the wrong time will be provided internally. |
| 1681 |
|
| 1682 |
\begin{decl} |
| 1683 |
|\CheckCommand| \arg{cmd} \oarg{num} \oarg{default} |
| 1684 |
\arg{definition}\\ |
| 1685 |
|\CheckCommand*| \arg{cmd} \oarg{num} \oarg{default} |
| 1686 |
\arg{definition} |
| 1687 |
\end{decl} |
| 1688 |
This takes the same arguments as |\newcommand| but, rather than define \m{cmd}, |
| 1689 |
it just checks that the current definition of \m{cmd} is exactly as given by |
| 1690 |
\m{definition}. An error is raised if these definitions differ. |
| 1691 |
|
| 1692 |
This command is useful for checking the state of the system before your package |
| 1693 |
starts altering the definitions of commands. It allows you to check, in |
| 1694 |
particular, that no other package has redefined the same command. |
| 1695 |
|
| 1696 |
\subsection{Option declaration} |
| 1697 |
\label{sec:commands.options.dec} |
| 1698 |
|
| 1699 |
The following commands deal with the declaration and handling of options to |
| 1700 |
document classes and packages using a classical `simple text' approach. Every |
| 1701 |
option name must be a `\LaTeX{} name'. |
| 1702 |
|
| 1703 |
There are some commands designed especially for use within the \m{code} |
| 1704 |
argument of these commands (see below). |
| 1705 |
|
| 1706 |
\begin{decl} |
| 1707 |
|\DeclareOption| \arg{option-name} \arg{code} |
| 1708 |
\end{decl} |
| 1709 |
This makes \m{option-name} a `declared option' of the class or package in which |
| 1710 |
it is put. |
| 1711 |
|
| 1712 |
The \m{code} argument contains the code to be executed if that option is |
| 1713 |
specified for the class or package; it can contain any valid \LaTeXe{} |
| 1714 |
construct. |
| 1715 |
|
| 1716 |
Example: |
| 1717 |
\begin{verbatim} |
| 1718 |
\DeclareOption{twoside}{\@twosidetrue} |
| 1719 |
\end{verbatim} |
| 1720 |
|
| 1721 |
\begin{decl} |
| 1722 |
|\DeclareOption*| \arg{code} |
| 1723 |
\end{decl} |
| 1724 |
This declares the \m{code} to be executed for every option which is specified |
| 1725 |
for, but otherwise not explicitly declared by, the class or package; this code |
| 1726 |
is called the `default option code' and it can contain any valid \LaTeXe{} |
| 1727 |
construct. |
| 1728 |
|
| 1729 |
If a class file contains no |\DeclareOption*| then, by default, all specified |
| 1730 |
but undeclared options for that class will be silently passed to all packages |
| 1731 |
(as will the specified and declared options for that class). |
| 1732 |
|
| 1733 |
If a package file contains no |\DeclareOption*| then, by default, each |
| 1734 |
specified but undeclared option for that package will produce an error. |
| 1735 |
|
| 1736 |
\subsection{Commands within option code} |
| 1737 |
\label{sec:within.code} |
| 1738 |
|
| 1739 |
These two commands can be used only within the \m{code} argument of either |
| 1740 |
|\DeclareOption| or |\DeclareOption*|. Other commands commonly used within |
| 1741 |
these arguments can be found in the next few subsections. |
| 1742 |
|
| 1743 |
\begin{decl} |
| 1744 |
|\CurrentOption| |
| 1745 |
\end{decl} |
| 1746 |
This expands to the name of the current option. |
| 1747 |
|
| 1748 |
\begin{decl} |
| 1749 |
|\OptionNotUsed| |
| 1750 |
\end{decl} |
| 1751 |
This causes the current option to be added to the list of `unused options'. |
| 1752 |
|
| 1753 |
\subsection{Option processing} |
| 1754 |
\label{sec:commands.options} |
| 1755 |
|
| 1756 |
\begin{decl} |
| 1757 |
|\ProcessOptions| |
| 1758 |
\end{decl} |
| 1759 |
This command executes the \m{code} for each selected option. |
| 1760 |
|
| 1761 |
We shall first describe how |\ProcessOptions| works in a package file, and then |
| 1762 |
how this differs in a class file. |
| 1763 |
|
| 1764 |
To understand in detail what |\ProcessOptions| does in a package file, you have |
| 1765 |
to know the difference between \emph{local} and \emph{global} options. |
| 1766 |
\begin{itemize} |
| 1767 |
\item \textbf{Local options} are those which have been explicitly |
| 1768 |
specified for this particular package in the \m{options} argument of |
| 1769 |
any of these: |
| 1770 |
\begin{quote} |
| 1771 |
|\PassOptionsToPackage{<options>}| \ |\usepackage[<options>]|\\ |
| 1772 |
|\RequirePackage[<options>]| |
| 1773 |
\end{quote} |
| 1774 |
\item \textbf{Global options} are any other options that are specified |
| 1775 |
by the author in the \m{options} argument of |
| 1776 |
|\documentclass[<options>]|. |
| 1777 |
\end{itemize} |
| 1778 |
For example, suppose that a document begins: |
| 1779 |
\begin{verbatim} |
| 1780 |
\documentclass[german,twocolumn]{article} |
| 1781 |
\usepackage{gerhardt} |
| 1782 |
\end{verbatim} |
| 1783 |
whilst package |gerhardt| calls package |fred| with: |
| 1784 |
\begin{verbatim} |
| 1785 |
\PassOptionsToPackage{german,dvips,a4paper}{fred} |
| 1786 |
\RequirePackage[errorshow]{fred} |
| 1787 |
\end{verbatim} |
| 1788 |
then: |
| 1789 |
\begin{itemize} |
| 1790 |
\item |fred|'s local options are |german|, |dvips|, |a4paper| |
| 1791 |
and |errorshow|; |
| 1792 |
\item |fred|'s only global option is |twocolumn|. |
| 1793 |
\end{itemize} |
| 1794 |
|
| 1795 |
When |\ProcessOptions| is called, the following happen. |
| 1796 |
\begin{itemize} |
| 1797 |
\item \emph{First}, for each option so far declared in |fred.sty| |
| 1798 |
by |\DeclareOption|, it looks to see if that option is either a |
| 1799 |
global or a local option for |fred|: if it is then the corresponding |
| 1800 |
code is executed. |
| 1801 |
|
| 1802 |
This is done in the order in which these options |
| 1803 |
were declared in |fred.sty|. |
| 1804 |
\item \emph{Then}, for each remaining \emph{local} option, the command |
| 1805 |
|\ds@<option>| is executed if it has been defined somewhere (other |
| 1806 |
than by a |\DeclareOption|); otherwise, the `default option code' is |
| 1807 |
executed. If no default option code has been declared then an error |
| 1808 |
message is produced. |
| 1809 |
|
| 1810 |
This is done in the order in which these |
| 1811 |
options were specified. |
| 1812 |
\end{itemize} |
| 1813 |
Throughout this process, the system ensures that the code declared for |
| 1814 |
an option is executed at most once. |
| 1815 |
|
| 1816 |
Returning to the example, if |fred.sty| contains: |
| 1817 |
\begin{verbatim} |
| 1818 |
\DeclareOption{dvips}{\typeout{DVIPS}} |
| 1819 |
\DeclareOption{german}{\typeout{GERMAN}} |
| 1820 |
\DeclareOption{french}{\typeout{FRENCH}} |
| 1821 |
\DeclareOption*{\PackageWarning{fred}{Unknown `\CurrentOption'}} |
| 1822 |
\ProcessOptions\relax |
| 1823 |
\end{verbatim} |
| 1824 |
then the result of processing this document will be: |
| 1825 |
\begin{verbatim} |
| 1826 |
DVIPS |
| 1827 |
GERMAN |
| 1828 |
Package fred Warning: Unknown `a4paper'. |
| 1829 |
Package fred Warning: Unknown `errorshow'. |
| 1830 |
\end{verbatim} |
| 1831 |
Note the following: |
| 1832 |
|
| 1833 |
\begin{itemize} |
| 1834 |
\item the code for the |dvips| option is executed before that for the |
| 1835 |
|german| option, because that is the order in which they are declared |
| 1836 |
in |fred.sty|; |
| 1837 |
\item the code for the |german| option is executed only once, when the |
| 1838 |
declared options are being processed; |
| 1839 |
\item the |a4paper| and |errorshow| options produce the warning from |
| 1840 |
the code declared by |\DeclareOption*| (in the order in which they |
| 1841 |
were specified), whilst the |twocolumn| option does not: this is |
| 1842 |
because |twocolumn| is a global option. |
| 1843 |
\end{itemize} |
| 1844 |
|
| 1845 |
In a class file, |\ProcessOptions| works in the same way, except that: |
| 1846 |
\emph{all} options are local; and the default value for |\DeclareOption*| is |
| 1847 |
|\OptionNotUsed| rather than an error. |
| 1848 |
|
| 1849 |
Note that, because |\ProcessOptions| has a |*|-form, it is wise to follow the |
| 1850 |
non-star form with |\relax|, as in the previous examples, since this prevents |
| 1851 |
unnecessary look ahead and possibly misleading error messages being issued. |
| 1852 |
|
| 1853 |
\begin{decl} |
| 1854 |
|\ProcessOptions*| |
| 1855 |
\end{decl} |
| 1856 |
This is like |\ProcessOptions| but it executes the options in the order |
| 1857 |
specified in the calling commands, rather than in the order of declaration in |
| 1858 |
the class or package. For a package this means that the global options are |
| 1859 |
processed first. |
| 1860 |
|
| 1861 |
\begin{decl} |
| 1862 |
|\ExecuteOptions| \arg{options-list} |
| 1863 |
\end{decl} |
| 1864 |
|
| 1865 |
It can be used to provide a `default option list' just before |
| 1866 |
|\ProcessOptions|. For example, suppose that in a class file you want to set up |
| 1867 |
the default design to be: two-sided printing; 11pt fonts; in two columns. Then |
| 1868 |
it could specify: |
| 1869 |
\begin{verbatim} |
| 1870 |
\ExecuteOptions{11pt,twoside,twocolumn} |
| 1871 |
\end{verbatim} |
| 1872 |
|
| 1873 |
\end{document} |