Debian Codegraph @

texmf-dist/doc/latex/base/clsguide.tex

raw
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}