Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 1993-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-historic.tex
30
31 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
32
33 \documentclass{ltxguide}[1995/11/28]
34
35 \title{\LaTeXe~for class and package writers --- historic version}
36
37 \author{Copyright \copyright~1995--2023 The \LaTeX\ Project\\
38 All rights reserved.%
39 \footnote{This file may be 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-historic.tex} for full details.}%
43 }
44
45 \date{09 November 2023}
46
47 \begin{document}
48
49 \maketitle
50
51 \tableofcontents
52
53 \section{Introduction}
54
55 This document is an introduction to writing classes and packages for
56 \LaTeX{}, with special attention given to upgrading existing
57 \LaTeX~2.09 packages to \LaTeXe{}. The latter subject is also
58 covered in an article by Johannes Braams published in TUGboat~15.3.
59
60 It is somewhat of an historical document now, since \LaTeXe{} came into
61 existence in 1994.
62
63 \subsection{Writing classes and packages for \LaTeXe}
64
65 \LaTeX{} is a document preparation system that enables the document
66 writer to concentrate on the contents of their text, without bothering
67 too much about the formatting of it. For example, chapters are
68 indicated by |\chapter{<title>}| rather than by selecting 18pt bold.
69
70 The file that contains the information about how to turn logical
71 structure (like `|\chapter|') into formatting (like `18pt bold ragged
72 right') is a \emph{document class}. In addition, some features (such
73 as colour or included graphics) are independent of the document class
74 and these are contained in \emph{packages}.
75
76 One of the largest differences between \LaTeX~2.09 and \LaTeXe{} is in
77 the commands used to write packages and classes. In \LaTeX~2.09,
78 there was very little support for writing |.sty| files, and so writers
79 had to resort to using low-level commands.
80
81 \LaTeXe{} provides high-level commands for structuring packages.
82 It is also much easier to build classes and packages on top of each
83 other, for example writing a local technical report class |cetechr|
84 (for the Chemical Engineering department) based on |article|.
85
86 \subsection{Overview}
87
88 This document contains an overview of how to write classes and
89 packages for \LaTeX{}. It does \emph{not} introduce all of the
90 commands necessary to write packages: these can be found in either
91 \emph{\LaTeXbook} or \emph{\LaTeXcomp}. But it does describe the new
92 commands for structuring classes and packages.
93
94 \begin{description}
95
96 \item[Section~\ref{Sec:general}] contains some general advice about
97 writing classes and packages. It describes the difference between
98 classes and packages, the command naming conventions, the use of
99 |doc| and |docstrip|, how \TeX's primitive file and box commands
100 interact with \LaTeX{}. It also contains some hints about general
101 \LaTeX{} style.
102
103 \item[Section~\ref{Sec:structure}] describes the structure of classes
104 and packages. This includes building classes and packages on top of
105 other classes and packages, declaring options and declaring
106 commands. It also contains example classes.
107
108 \item[Section~\ref{Sec:commands}] lists the new class and package
109 commands.
110
111 \item[Section~\ref{Sec:upgrade}] gives detailed advice on how to
112 upgrade existing \LaTeX~2.09 classes and packages to \LaTeXe{}.
113
114 \end{description}
115
116 \subsection{Further information}
117
118 For a general introduction to \LaTeX{}, including the new features of
119 \LaTeXe{}, you should read \emph{\LaTeXbook}
120 by Leslie Lamport~\cite{A-W:LLa94}.
121
122 A more detailed description of the new features of \LaTeX, including an
123 overview of more than 200 packages and nearly 1000 ready to run examples, is
124 to be found in \emph{\LaTeXcomp\ second edition} by Frank Mittelbach and
125 Michel Goossens~\cite{A-W:MG2004}.
126
127 The \LaTeX{} system is based on \TeX{}, which is
128 described in \emph{The \TeX book} by Donald E.~Knuth~\cite{A-W:DEK91}.
129
130 There are a number of documentation files which accompany every copy
131 of \LaTeX{}. A copy of \emph{\LaTeX{} News} will come out with each
132 six-monthly release of \LaTeX{}, and is found in the files
133 |ltnews*.tex|. The author's guide \emph{\usrguide} describes the new
134 \LaTeX{} document features; it is in |usrguide.tex|. The guide
135 \emph{\fntguide} describes the \LaTeX{} font selection scheme for
136 class- and package-writers; it is in |fntguide.tex|. Configuring
137 \LaTeX{} is covered by the guide \emph{\cfgguide} in
138 \texttt{cfgguide.tex} whilst the philosophy behind our policy on
139 modifying \LaTeX{} is described in \emph{\modguide} in
140 \texttt{modguide.tex}.
141
142 The documented source code (from the files used to produce the kernel
143 format via |latex.ltx|) is now available as
144 \emph{The \LaTeXe\ Sources}.
145 This very large document also includes an index of
146 \LaTeX{} commands. It can be typeset from the \LaTeX{} file
147 |source2e.tex| in the |base| directory, using the source files and
148 the class file |ltxdoc.cls| from this directory.
149
150 For more information about \TeX{} and \LaTeX{}, please contact your
151 local \TeX{} Users Group, or the international \TeX{} Users Group.
152 Addresses and other details can be found at:
153 \begin{quote}\small\label{addrs}
154 \texttt{http://www.tug.org/lugs.html}
155 \end{quote}
156
157
158 \subsection{Policy on standard classes}
159
160 Many of the problem reports we receive concerning the standard classes
161 are not concerned with bugs but are suggesting, more or less politely,
162 that the design decisions embodied in them are `not optimal' and
163 asking us to modify them.
164
165 There are several reasons why we should not make such changes to these
166 files.
167 \begin{itemize}
168 \item
169 However misguided, the current behaviour is clearly what was
170 intended when these classes were designed.
171 \item
172 It is not good practice to change such aspects of `standard classes'
173 because many people will be relying on them.
174 \end{itemize}
175
176 We have therefore decided not to even consider making such
177 modifications, nor to spend time justifying that decision. This does
178 not mean that we do not agree that there are many deficiencies in the
179 design of these classes, but we have many tasks with higher priority
180 than continually explaining why the standard classes for \LaTeX{}
181 cannot be changed.
182
183 We would, of course, welcome the production of better classes, or of
184 packages that can be used to enhance these classes. So your first
185 thought when you consider such a deficiency will, we hope, be ``what
186 can I do to improve this?''
187
188 Similar considerations apply to those parts of the kernel that are
189 implementing design decisions, many of which should be left to the
190 class file but are not in the current system. We realise that in such
191 cases it is much more difficult for you to rectify the problem
192 yourself but it is also the case that making such changes in the
193 kernel would probably be a major project for us; therefore such
194 enhancements will have to wait for \LaTeX3.
195
196 \section{Writing classes and packages}
197 \label{Sec:writing}
198
199 This section covers some general points concerned with writing
200 \LaTeX{} classes and packages.
201
202
203 \subsection{Old versions}
204
205 If you are upgrading an existing \LaTeX~2.09 style file then we
206 recommend freezing the 2.09 version and no longer maintaining it.
207 Experience with the various dialects of \LaTeX{} which existed in the
208 early 1990's suggests that maintaining packages for different versions
209 of \LaTeX{} is almost impossible. It will, of course, be necessary
210 for some organisations to maintain both versions in parallel for some
211 time but this is not essential for those packages and classes
212 supported by individuals: they should support only the new standard
213 \LaTeXe{}, not obsolete versions of \LaTeX{}.
214
215
216 \subsection{Using `docstrip' and `doc'}
217
218 If you are going to write a large class or package for \LaTeX{} then
219 you should consider using the |doc| software which comes with
220 \LaTeX{}.
221 \LaTeX{} classes and packages written using this can be
222 processed in two ways: they can be run through \LaTeX{}, to produce
223 documentation; and they can be processed with |docstrip|, to produce
224 the |.cls| or |.sty| file.
225
226 The |doc| software can automatically generate indexes of definitions,
227 indexes of command use, and change-log lists. It is very useful for
228 maintaining and documenting large \TeX{} sources.
229
230 The documented sources of the \LaTeX{} kernel itself, and of the
231 standard classes, etc, are |doc| documents; they are in the |.dtx|
232 files in the distribution. You can, in fact, typeset the source code
233 of the kernel as one long document, complete with index, by running
234 \LaTeX{} on |source2e.tex|. Typesetting these documents uses the
235 class file |ltxdoc.cls|.
236
237 For more information on |doc| and |docstrip|, consult the files
238 |docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}. For examples of its
239 use, look at the |.dtx| files.
240
241 \subsection{Is it a class or a package?}
242 \label{Sec:classorpkg}
243
244 The first thing to do when you want to put some new \LaTeX{} commands
245 in a file is to decide whether it should be a \emph{document class} or a
246 \emph{package}. The rule of thumb is:
247 \begin{quote}
248 If the commands could be used with any document class, then make
249 them a package; and if not, then make them a class.
250 \end{quote}
251
252 There are two major types of class: those like |article|, |report| or
253 |letter|, which are free-standing; and those which are extensions or
254 variations of other classes---for example, the |proc| document class,
255 which is built on the |article| document class.
256
257 Thus, a company might have a local |ownlet| class for printing letters
258 with their own headed note-paper. Such a class would build on top of
259 the existing |letter| class but it cannot be used with any other
260 document class, so we have |ownlet.cls| rather than |ownlet.sty|.
261
262 The |graphics| package, in contrast, provides commands for including
263 images into a \LaTeX{} document. Since these commands can be used
264 with any document class, we have |graphics.sty| rather than
265 |graphics.cls|.
266
267
268 \subsection{Command names}
269
270 \LaTeX{} has three types of command.
271
272 There are the author commands, such as |\section|, |\emph| and
273 |\times|: most of these have short names, all in lower case.
274
275 There are also the class and package writer commands:
276 most of these have long mixed-case names such as the following.
277 \begin{verbatim}
278 \InputIfFileExists \RequirePackage \PassOptionsToClass
279 \end{verbatim}
280
281 Finally, there are the internal commands used in the \LaTeX{}
282 implementation, such as |\@tempcnta|, |\@ifnextchar| and |\@eha|:
283 most of these commands contain |@| in their name, which means they
284 cannot be used in documents, only in class and package files.
285
286 Unfortunately, for historical reasons the distinction between these
287 commands is often blurred. For example, |\hbox| is an internal
288 command which should only be used in the \LaTeX{} kernel, whereas
289 |\m@ne| is the constant $-1$ and could have been |\MinusOne|.
290
291 However, this rule of thumb is still useful: if a command has |@| in
292 its name then it is not part of the supported \LaTeX{} language---and
293 its behaviour may change in future releases! If a command is
294 mixed-case, or is described in \emph{\LaTeXbook}, then you can rely on
295 future releases of \LaTeXe{} supporting the command.
296
297 \subsection{Box commands and colour}
298 \label{Sec:colour}
299
300 Even if you do not intend to use colour in your own documents, by
301 taking note of the points in this section you can ensure that your
302 class or package is compatible with the |color| package. This may
303 benefit people using your class or package who have access to colour
304 printers.
305
306 The simplest way to ensure `colour safety' is to always use \LaTeX{}
307 box commands rather than \TeX{} primitives, that is use |\sbox| rather
308 than |\setbox|, |\mbox| rather than |\hbox| and |\parbox| or
309 the |minipage| environment rather than |\vbox|.
310 The \LaTeX{} box commands have new options which mean that they are now
311 as powerful as the \TeX{} primitives.
312
313 As an example of what can go wrong, consider that in
314 |{\ttfamily <text>}|
315 the font is restored just \emph{before} the |}|, whereas in the
316 similar looking construction
317 |{\color{green} <text>}|
318 the colour is restored just \emph{after} the final |}|. Normally this
319 distinction does not matter at all; but consider a primitive \TeX{}
320 box assignment such as:
321 \begin{verbatim}
322 \setbox0=\hbox{\color{green} <text>}
323 \end{verbatim}
324 Now the colour-restore occurs after the |}| and so is \emph{not}
325 stored in the box. Exactly what bad effects this can have depends on
326 how colour is implemented: it can range from getting the wrong
327 colours in the rest of the document, to causing errors in the
328 dvi-driver used to print the document.
329
330 Also of interest is the command |\normalcolor|. This is
331 normally just |\relax| (i.e., does nothing)
332 but you can use it rather like |\normalfont| to
333 set regions of the page such as captions or section headings to the
334 `main document colour'.
335
336
337 \subsection{Defining text and math characters}
338 \label{Sec:chars}
339
340 Because \LaTeXe{} supports different encodings, definitions of commands
341 for producing symbols, accents, composite glyphs, etc.\ must be
342 defined using the commands provided for this purpose and described in
343 \emph{\fntguide}. This part of the system is still under development
344 so such tasks should be undertaken with great caution.
345
346 Also, |\DeclareRobustCommand| should be used for encoding-independent
347 commands of this type.
348
349 Note that it is no longer possible to refer to the math font set-up
350 outside math mode: for example, neither |\textfont 1| nor
351 |\scriptfont 2| are guaranteed to be defined in other modes.
352
353
354 \subsection{General style}
355 \label{Sec:general}
356
357 The new system provides many commands designed to help you produce
358 well-structured class and package files that are both robust and
359 portable. This section outlines some ways to make intelligent use of
360 these.
361
362 \subsubsection{Loading other files}
363 \label{Sec:loading}
364
365 \NEWdescription{1995/12/01}
366 \LaTeX{} provides these commands:
367 \begin{verbatim}
368 \LoadClass \LoadClassWithOptions
369 \RequirePackage \RequirePackageWithOptions
370 \end{verbatim}
371 for using classes or packages inside other classes or packages. We
372 recommend strongly that you use them, rather than the primitive
373 |\input| command, for a number of reasons.
374
375 Files loaded with |\input <filename>| will not be listed in the
376 |\listfiles| list.
377
378 If a package is always loaded with |\RequirePackage...| or |\usepackage|
379 then, even if its loading is requested several times, it will be
380 loaded only once. By contrast, if it is loaded with |\input| then it
381 can be loaded more than once; such an extra loading may waste time and
382 memory and it may produce strange results.
383
384 If a package provides option-processing then, again, strange results
385 are possible if the package is |\input| rather than loaded by means of
386 |\usepackage| or |\RequirePackage...|.
387
388 If the package |foo.sty| loads the package |baz.sty| by use of
389 |\input baz.sty| then the user will get a warning:
390 \begin{verbatim}
391 LaTeX Warning: You have requested package `foo',
392 but the package provides `baz'.
393 \end{verbatim}
394 Thus, for several reasons, using |\input| to load packages is not a
395 good idea.
396
397 Unfortunately, if you are upgrading the file |myclass.sty| to a class
398 file then you have to make sure that any old files which contain
399 |\input myclass.sty| still work.
400
401 This was also true for the standard classes (|article|, |book| and
402 |report|), since a lot of existing \LaTeX~2.09 document styles contain
403 |\input article.sty|. The approach which we use to solve this is
404 to provide minimal files |article.sty|, |book.sty| and |report.sty|,
405 which simply load the appropriate class files.
406
407 For example, |article.sty| contains just the following lines:
408 \begin{verbatim}
409 \NeedsTeXFormat{LaTeX2e}
410 \@obsoletefile{article.cls}{article.sty}
411 \LoadClass{article}
412 \end{verbatim}
413 You may wish to do the same or, if you think that it is safe to do so,
414 you may decide to just remove |myclass.sty|.
415
416 \subsubsection{Make it robust}
417
418 We consider it good practice, when writing packages and classes, to use
419 \LaTeX{} commands as much as possible.
420
421 Thus, instead of using |\def...| we recommend using one of
422 |\newcommand|, |\renewcommand| or |\providecommand|; |\CheckCommand| is
423 also useful. Doing this makes
424 it less likely that you will inadvertently redefine a command, giving
425 unexpected results.
426
427 When you define an environment, use |\newenvironment| or
428 |\renewenvironment| instead |\def\foo{...}| and |\def\endfoo{...}|.
429
430 If you need to set or change the value of a \m{dimen} or \m{skip}
431 register, use |\setlength|.
432
433 To manipulate boxes, use \LaTeX{} commands such as |\sbox|,
434 |\mbox| and |\parbox| rather than |\setbox|, |\hbox| and |\vbox|.
435
436 Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the
437 equivalent class commands) rather than |\@latexerr|, |\@warning| or
438 |\wlog|.
439
440 It is still possible to declare options by defining |\ds@<option>| and
441 calling |\@options|; but we recommend the |\DeclareOption| and
442 |\ProcessOptions| commands instead. These are more powerful and use
443 less memory. So rather than using:
444 \begin{verbatim}
445 \def\ds@draft{\overfullrule 5pt}
446 \@options
447 \end{verbatim}
448 you should use:
449 \begin{verbatim}
450 \DeclareOption{draft}{\setlength{\overfullrule}{5pt}}
451 \ProcessOptions\relax
452 \end{verbatim}
453
454 The advantage of this kind of practice is that your code is more
455 readable and, more important, that it is less likely to break when
456 used with future versions of \LaTeX{}.
457
458 \subsubsection{Make it portable}
459
460 It is also sensible to make your files are as portable as possible. To
461 ensure this; they should contain only visible 7-bit text; and the
462 filenames should contain at most eight characters (plus the three
463 letter extension). Also, of course, it \textbf{must not} have the
464 same name as a file in the standard \LaTeX{} distribution, however
465 similar its contents may be to one of these files.
466
467 It is also useful if local classes or packages have a common prefix,
468 for example the University of Nowhere classes might begin with |unw|.
469 This helps to avoid every University having its own thesis class, all
470 called |thesis.cls|.
471
472 If you rely on some features of the \LaTeX{} kernel, or on a package,
473 please specify the release-date you need. For example, the package
474 error commands were introduced in the June 1994 release so, if you use
475 them then you should put:
476 \begin{verbatim}
477 \NeedsTeXFormat{LaTeX2e}[1994/06/01]
478 \end{verbatim}
479
480 \subsubsection{Useful hooks}
481
482 Some packages and document styles had to redefine the command
483 |\document| or |\enddocument| to achieve their goal. This is no
484 longer necessary. You can now use the `hooks' |\AtBeginDocument| and
485 |\AtEndDocument| (see Section~\ref{Sec:delays}). Again, using these
486 hooks makes it less likely that your code breaks with future versions
487 of \LaTeX{}. It also makes it more likely that your package can work
488 together with someone else's.
489
490 \NEWdescription{1996/12/01}
491 However, note that code in the |\AtBeginDocument| hook is part of the
492 preamble. Thus there are restrictions on what can be put there; in
493 particular, no typesetting can be done.
494
495 \section{The structure of a class or package}
496 \label{Sec:structure}
497
498 \LaTeXe{} classes and packages have more structure than \LaTeX~2.09
499 style files did. The outline of a class or package file is:
500 \begin{description}
501 \item[Identification] The file says that it is a \LaTeXe{} package or
502 class, and gives a short description of itself.
503 \item[Preliminary declarations]
504 Here the file declares some commands and can also load
505 other files. Usually these commands will be just those needed for
506 the code used in the declared options.
507 \item[Options] The file declares and processes its options.
508 \item[More declarations] This is where the file does most of its work:
509 declaring new variables, commands and fonts; and loading other files.
510 \end{description}
511
512 \subsection{Identification}
513
514 The first thing a class or package file does is identify itself.
515 Package files do this as follows:
516 \begin{verbatim}
517 \NeedsTeXFormat{LaTeX2e}
518 \ProvidesPackage{<package>}[<date> <other information>]
519 \end{verbatim}
520 For example:
521 \begin{verbatim}
522 \NeedsTeXFormat{LaTeX2e}
523 \ProvidesPackage{latexsym}[1994/06/01 Standard LaTeX package]
524 \end{verbatim}
525 Class files do this as follows:
526 \begin{verbatim}
527 \NeedsTeXFormat{LaTeX2e}
528 \ProvidesClass{<class-name>}[<date> <other information>]
529 \end{verbatim}
530 For example:
531 \begin{verbatim}
532 \NeedsTeXFormat{LaTeX2e}
533 \ProvidesClass{article}[1994/06/01 Standard LaTeX class]
534 \end{verbatim}
535 \NEWdescription{1998/06/19}
536 The \m{date} should be given in the form `\textsc{yyyy/mm/dd}' and
537 must be present if the optional argument is used (this is also true
538 for the |\NeedsTeXFormat| command).
539 Any derivation from this syntax will result in low-level \TeX{}
540 errors---the commands expect a valid syntax to speed up the daily
541 usage of the package or class and make no provision for the case that
542 the developer made a mistake!
543
544 This date is checked whenever a user specifies a date in their
545 |\documentclass| or |\usepackage| command. For example, if you wrote:
546 \begin{verbatim}
547 \documentclass{article}[1995/12/23]
548 \end{verbatim}
549 then users at a different location
550 would get a warning that their copy of |article| was out of
551 date.
552
553 The description of a class is displayed when the class is used. The
554 description of a package is put into the log file. These descriptions
555 are also displayed by the |\listfiles| command. The phrase
556 \texttt{Standard LaTeX} \textbf{must not} be used in the identification
557 banner of any file other than those in the standard \LaTeX{}
558 distribution.
559
560
561 \subsection{Using classes and packages}
562
563 The first major difference between \LaTeX~2.09 style files and
564 \LaTeXe{} packages and classes is that \LaTeXe{} supports
565 \emph{modularity}, in the sense of building files from small
566 building-blocks rather than using large single files.
567
568 A \LaTeX{} package or class can load a package as follows:
569 \begin{verbatim}
570 \RequirePackage[<options>]{<package>}[<date>]
571 \end{verbatim}
572 For example:
573 \begin{verbatim}
574 \RequirePackage{ifthen}[1994/06/01]
575 \end{verbatim}
576 This command has the same syntax as the author command |\usepackage|.
577 It allows packages or classes to use features provided by other
578 packages. For example, by loading the |ifthen| package, a package
579 writer can use the `if\dots then\dots else\dots' commands provided
580 by that package.
581
582 A \LaTeX{} class can load one other class as follows:
583 \begin{verbatim}
584 \LoadClass[<options>]{<class-name>}[<date>]
585 \end{verbatim}
586 For example:
587 \begin{verbatim}
588 \LoadClass[twocolumn]{article}
589 \end{verbatim}
590 This command has the same syntax as the author command |\documentclass|.
591 It allows classes to be based on the syntax and appearance of another
592 class. For example, by loading the |article| class, a class writer
593 only has to change the bits of |article| they don't like, rather than
594 writing a new class from scratch.
595
596 \NEWfeature{1995/12/01}
597 The following commands can be used in the common case that you want to
598 simply load a class or package file with exactly those options that
599 are being used by the current class.
600 \begin{verbatim}
601 \LoadClassWithOptions{<class-name>}[<date>]
602 \RequirePackageWithOptions{<package>}[<date>]
603 \end{verbatim}
604 For example:
605 \begin{verbatim}
606 \LoadClassWithOptions{article}
607 \RequirePackageWithOptions{graphics}[1995/12/01]
608 \end{verbatim}
609
610 \subsection{Declaring options}
611
612 \NEWdescription{1998/12/01}
613 The other major difference between \LaTeX~2.09 styles and \LaTeXe{}
614 packages and classes is in option handling. Packages and classes can
615 now declare options and these can be specified by authors; for
616 example, the |twocolumn| option is declared by the |article| class.
617 Note that the name of an option should contain only those characters
618 allowed in a `\LaTeX{} name'; in particular it must not contain any
619 control sequences.
620
621 An option is declared as follows:
622 \begin{verbatim}
623 \DeclareOption{<option>}{<code>}
624 \end{verbatim}
625 For example, the |dvips| option (slightly simplified)
626 to the |graphics| package is implemented as:
627 \begin{verbatim}
628 \DeclareOption{dvips}{\input{dvips.def}}
629 \end{verbatim}
630 This means that when an author writes |\usepackage[dvips]{graphics}|,
631 the file |dvips.def| is loaded. As another example, the |a4paper|
632 option is declared in the |article| class to set the |\paperheight|
633 and |\paperwidth| lengths:
634 \begin{verbatim}
635 \DeclareOption{a4paper}{%
636 \setlength{\paperheight}{297mm}%
637 \setlength{\paperwidth}{210mm}%
638 }
639 \end{verbatim}
640 Sometimes a user will request an option which the class
641 or package has not explicitly declared. By default this will produce
642 a warning (for classes) or error (for packages); this behaviour
643 can be altered as follows:
644 \begin{verbatim}
645 \DeclareOption*{<code>}
646 \end{verbatim}
647 For example, to make the package |fred| produce a warning rather than
648 an error for unknown options, you could specify:
649 \begin{verbatim}
650 \DeclareOption*{%
651 \PackageWarning{fred}{Unknown option `\CurrentOption'}%
652 }
653 \end{verbatim}
654 Then, if an author writes |\usepackage[foo]{fred}|, they will get a
655 warning \texttt{Package fred Warning: Unknown option `foo'.} As
656 another example, the |fontenc| package tries to load a file
657 |<ENC>enc.def| whenever the \m{ENC} option is used. This
658 can be done by writing:
659 \begin{verbatim}
660 \DeclareOption*{%
661 \input{\CurrentOption enc.def}%
662 }
663 \end{verbatim}
664 \NEWdescription{1998/12/01}
665 It is possible to pass options on to another package or class, using
666 the command |\PassOptionsToPackage| or |\PassOptionsToClass| (note
667 that this is a specialised operation that works only for option
668 names). For example, to pass every unknown option on to the |article|
669 class, you can use:
670 \begin{verbatim}
671 \DeclareOption*{%
672 \PassOptionsToClass{\CurrentOption}{article}%
673 }
674 \end{verbatim}
675 If you do this then you should make sure you load the class at some
676 later point, otherwise the options will never be processed!
677
678 So far, we have explained only how to declare options, not how to
679 execute them. To process the options with which the file was called,
680 you should use:
681 \begin{verbatim}
682 \ProcessOptions\relax
683 \end{verbatim}
684 This executes the \m{code} for each option that was both specified and
685 declared (see Section~\ref{Sec:commands.options} for details of how
686 this is done).
687
688 For example, if the |jane| package file contains:
689 \begin{verbatim}
690 \DeclareOption{foo}{\typeout{Saw foo.}}
691 \DeclareOption{baz}{\typeout{Saw baz.}}
692 \DeclareOption*{\typeout{What's \CurrentOption?}}
693 \ProcessOptions\relax
694 \end{verbatim}
695 and an author writes |\usepackage[foo,bar]{jane}|, then they will see
696 the messages \texttt{Saw foo.} and \texttt{What's bar?}
697
698 \subsection{A minimal class file}
699
700 Most of the work of a class or package is in defining new commands, or
701 changing the appearance of documents. This is done in the body of the
702 package, using commands such as |\newcommand| or |\setlength|.
703
704 \LaTeXe{} provides several new commands to help class and package
705 writers; these are described in detail in Section~\ref{Sec:commands}.
706
707 There are four things that every class file \emph{must} contain: these
708 are a definition of |\normalsize|, values for |\textwidth| and
709 |\textheight| and a specification for page-numbering. So a minimal
710 document class file\footnote {This class is now in the standard
711 distribution, as \texttt{minimal.cls}.} looks like this:
712 \begin{verbatim}
713 \NeedsTeXFormat{LaTeX2e}
714 \ProvidesClass{minimal}[1995/10/30 Standard LaTeX minimal class]
715 \renewcommand{\normalsize}{\fontsize{10pt}{12pt}\selectfont}
716 \setlength{\textwidth}{6.5in}
717 \setlength{\textheight}{8in}
718 \pagenumbering{arabic} % needed even though this class will
719 % not show page numbers
720 \end{verbatim}
721 However, this class file will not support footnotes, marginals,
722 floats, etc., nor will it provide any of the 2-letter font commands
723 such as |\rm|; thus most classes will contain more than this minimum!
724
725 \subsection{Example: a local letter class}
726
727 A company may have its own letter class, for setting letters in the
728 company style. This section shows a simple implementation of such a
729 class, although a real class would need more structure.
730
731 The class begins by announcing itself as |neplet.cls|.
732 \begin{verbatim}
733 \NeedsTeXFormat{LaTeX2e}
734 \ProvidesClass{neplet}[1995/04/01 NonExistent Press letter class]
735 \end{verbatim}
736 Then this next bit passes any options on to the |letter| class, which
737 is loaded with the |a4paper| option.
738 \begin{verbatim}
739 \DeclareOption*{\PassOptionsToClass{\CurrentOption}{letter}}
740 \ProcessOptions\relax
741 \LoadClass[a4paper]{letter}
742 \end{verbatim}
743 In order to use the company letter head, it redefines the
744 |firstpage| page style: this is the page style that is used on
745 the first page of letters.
746 \begin{verbatim}
747 \renewcommand{\ps@firstpage}{%
748 \renewcommand{\@oddhead}{<letterhead goes here>}%
749 \renewcommand{\@oddfoot}{<letterfoot goes here>}%
750 }
751 \end{verbatim}
752 And that's it!
753
754 \subsection{Example: a newsletter class}
755
756 A simple newsletter can be typeset with \LaTeX{}, using a variant of the
757 |article| class.
758 The class begins by announcing itself as |smplnews.cls|.
759 \begin{verbatim}
760 \NeedsTeXFormat{LaTeX2e}
761 \ProvidesClass{smplnews}[1995/04/01 The Simple News newsletter class]
762
763 \newcommand{\headlinecolor}{\normalcolor}
764 \end{verbatim}
765 It passes most specified options on to the |article| class: apart from
766 the |onecolumn| option, which is switched off, and the |green| option,
767 which sets the headline in green.
768 \begin{verbatim}
769 \DeclareOption{onecolumn}{\OptionNotUsed}
770 \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}}
771
772 \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
773
774 \ProcessOptions\relax
775 \end{verbatim}
776 It then loads the class |article| with the option |twocolumn|.
777 \begin{verbatim}
778 \LoadClass[twocolumn]{article}
779 \end{verbatim}
780 Since the newsletter is to be printed in colour, it now loads the
781 |color| package. The class does not specify a device driver option
782 since this should be specified by the user of the |smplnews| class.
783 \begin{verbatim}
784 \RequirePackage{color}
785 \end{verbatim}
786 The class then redefines |\maketitle| to produce the title in 72pt
787 Helvetica bold oblique, in the appropriate colour.
788 \begin{verbatim}
789 \renewcommand{\maketitle}{%
790 \twocolumn[%
791 \fontsize{72}{80}\fontfamily{phv}\fontseries{b}%
792 \fontshape{sl}\selectfont\headlinecolor
793 \@title
794 ]%
795 }
796 \end{verbatim}
797 It redefines |\section| and switches off section numbering.
798 \begin{verbatim}
799 \renewcommand{\section}{%
800 \@startsection
801 {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}%
802 {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}%
803 }
804
805 \setcounter{secnumdepth}{0}
806 \end{verbatim}
807 It also sets the three essential things.
808 \begin{verbatim}
809 \renewcommand{\normalsize}{\fontsize{9}{10}\selectfont}
810 \setlength{\textwidth}{17.5cm}
811 \setlength{\textheight}{25cm}
812 \end{verbatim}
813 In practice, a class would need more than this: it would provide
814 commands for issue numbers, authors of articles, page styles and so
815 on; but this skeleton gives a start. The |ltnews| class file is not
816 much more complex than this one.
817
818 \section{Commands for class and package writers}
819 \label{Sec:commands}
820
821 This section describes briefly each of the new commands for class and
822 package writers. To find out about other aspects of the new system,
823 you should also read \emph{\LaTeXbook}, \emph{\LaTeXcomp} and
824 \emph{\usrguide}.
825
826 \subsection{Identification}
827
828 The first group of commands discussed here are those used
829 to identify your class or package file.
830
831 \begin{decl}
832 |\NeedsTeXFormat| \arg{format-name} \oarg{release-date}
833 \end{decl}
834 This command tells \TeX{} that this file should be processed using a
835 format with name \m{format-name}. You can use the optional argument
836 \m{release-date} to further specify the earliest release date of the
837 format that is needed. When the release date of the format is older
838 than the one specified a warning will be generated. The standard
839 \m{format-name} is \texttt{LaTeX2e}. The date, if present, must be in
840 the form \textsc{yyyy/mm/dd}.
841
842 Example:
843 \begin{verbatim}
844 \NeedsTeXFormat{LaTeX2e}[1994/06/01]
845 \end{verbatim}
846
847 \begin{decl}
848 |\ProvidesClass| \arg{class-name} \oarg{release-info} \\
849 |\ProvidesPackage| \arg{package-name} \oarg{release-info}
850 \end{decl}
851 This declares that the current file contains the definitions for the
852 document class \m{class-name} or package \m{package-name}.
853
854 The optional \m{release-info}, if used, must contain:
855 \begin{itemize}
856 \item the release date of
857 this version of the file, in the form \textsc{yyyy/mm/dd};
858 \item optionally followed by a space and a short description, possibly
859 including a version number.
860 \end{itemize}
861 The above syntax must be followed exactly so that this information
862 can be used by |\LoadClass| or |\documentclass| (for classes) or
863 |\RequirePackage| or |\usepackage| (for packages) to test that the
864 release is not too old.
865
866 The whole of this \m{release-info} information is displayed by
867 |\listfiles| and should therefore not be too long.
868
869 Example:
870 \begin{verbatim}
871 \ProvidesClass{article}[1994/06/01 v1.0 Standard LaTeX class]
872 \ProvidesPackage{ifthen}[1994/06/01 v1.0 Standard LaTeX package]
873 \end{verbatim}
874
875 \begin{decl}
876 |\ProvidesFile| \arg{file-name} \oarg{release-info}
877 \end{decl}
878 This is similar to the two previous commands except that here the full
879 filename, including the extension, must be given. It is used for
880 declaring any files other than main class and package files.
881
882 Example:
883 \begin{verbatim}
884 \ProvidesFile{T1enc.def}[1994/06/01 v1.0 Standard LaTeX file]
885 \end{verbatim}
886
887 Note that the phrase \texttt{Standard LaTeX} \textbf{must not} be used
888 in the identification banner of any file other than those in the
889 standard \LaTeX{} distribution.
890
891 \subsection{Loading files}
892 \label{Sec:loadf}
893
894 \NEWfeature{1995/12/01}
895 This group of commands can be used to create your own document class or
896 package by building on existing classes or packages.
897 \begin{decl}
898 |\RequirePackage| \oarg{options-list} \arg{package-name}
899 \oarg{release-info}\\
900 |\RequirePackageWithOptions| \arg{package-name}
901 \oarg{release-info}
902 \end{decl}
903 Packages and classes should use these commands to load other packages.
904
905 The use of |\RequirePackage| is the same as the author command
906 |\usepackage|.
907
908 Examples:
909 \begin{verbatim}
910 \RequirePackage{ifthen}[1994/06/01]
911 \RequirePackageWithOptions{graphics}[1995/12/01]
912 \end{verbatim}
913
914 \begin{decl}
915 |\LoadClass| \oarg{options-list} \arg{class-name}
916 \oarg{release-info}\\
917 |\LoadClassWithOptions| \arg{class-name}
918 \oarg{release-info}
919 \end{decl}
920 \NEWfeature{1995/12/01}
921 These commands are for use \emph{only} in class files, they cannot be
922 used in packages files;
923 they can be used at most once within a class file.
924
925 The use of |\LoadClass| is the same as
926 the use of |\documentclass| to load a class file.
927
928 Examples:
929 \begin{verbatim}
930 \LoadClass{article}[1994/06/01]
931 \LoadClassWithOptions{article}[1995/12/01]
932 \end{verbatim}
933
934 \NEWfeature{1995/12/01}
935 The two |WithOptions| versions simply load the class (or package) file
936 with exactly those options that are being used by the current file
937 (class or package). See below, in \ref{Sec:opmove}, for further
938 discussion of their use.
939
940
941 \subsection{Option declaration}
942 \label{Sec:commands.options.dec}
943
944 \NEWdescription{1998/12/01}
945 The following commands deal with the declaration and handling of
946 options to document classes and packages. Every option name must be a
947 `\LaTeX{} name'.
948
949 There are some commands designed especially for use within the
950 \m{code} argument of these commands (see below).
951
952 \begin{decl}
953 |\DeclareOption| \arg{option-name} \arg{code}
954 \end{decl}
955 This makes \m{option-name} a `declared option' of the class or package
956 in which it is put.
957
958 The \m{code} argument contains the code to be executed if that option
959 is specified for the class or package; it can contain any valid
960 \LaTeXe{} construct.
961
962 Example:
963 \begin{verbatim}
964 \DeclareOption{twoside}{\@twosidetrue}
965 \end{verbatim}
966
967 \begin{decl}
968 |\DeclareOption*| \arg{code}
969 \end{decl}
970 This declares the \m{code} to be executed for every option which is
971 specified for, but otherwise not explicitly declared by, the class or
972 package; this code is called the `default option code' and it can
973 contain any valid \LaTeXe{} construct.
974
975 If a class file contains no |\DeclareOption*| then, by default, all
976 specified but undeclared options for that class will be silently
977 passed to all packages (as will the specified and declared options for
978 that class).
979
980 If a package file contains no |\DeclareOption*| then, by default, each
981 specified but undeclared option for that package will produce an error.
982
983
984 \subsection{Commands within option code}
985 \label{Sec:within.code}
986
987 These two commands can be used only within the \m{code} argument of
988 either |\DeclareOption| or |\DeclareOption*|. Other commands commonly
989 used within these arguments can be found in the next few subsections.
990
991 \begin{decl}
992 |\CurrentOption|
993 \end{decl}
994 This expands to the name of the current option.
995
996 \begin{decl}
997 |\OptionNotUsed|
998 \end{decl}
999 This causes the current option to
1000 be added to the list of `unused options'.
1001
1002 \NEWfeature{1995/06/01}
1003 You can now include hash marks (\texttt{\#}) within these \m{code}
1004 arguments without special treatment (formerly, it had been
1005 necessary to double them).
1006
1007 \subsection{Moving options around}
1008 \label{Sec:opmove}
1009
1010 These two commands are also very useful within the \m{code} argument
1011 of |\DeclareOption| or |\DeclareOption*|:
1012 \begin{decl}
1013 |\PassOptionsToPackage| \arg{options-list} \arg{package-name}\\
1014 |\PassOptionsToClass| \arg{options-list} \arg{class-name}
1015 \end{decl}
1016 The command |\PassOptionsToPackage| passes the option names in
1017 \m{options-list} to package \m{package-name}.
1018 This means that it adds the \m{option-list} to the
1019 list of options used by any future |\RequirePackage| or |\usepackage|
1020 command for package \m{package-name}.
1021
1022 Example:
1023 \begin{verbatim}
1024 \PassOptionsToPackage{foo,bar}{fred}
1025 \RequirePackage[baz]{fred}
1026 \end{verbatim}
1027 is the same as:
1028 \begin{verbatim}
1029 \RequirePackage[foo,bar,baz]{fred}
1030 \end{verbatim}
1031
1032 Similarly, |\PassOptionsToClass| may be used in a class file to pass
1033 options to another class to be loaded with |\LoadClass|.
1034
1035 \NEWdescription{1995/12/01}
1036 The effects and use of these two commands should be contrasted with
1037 those of the following two (documented above, in \ref{Sec:loadf}):
1038 \begin{verbatim}
1039 \LoadClassWithOptions
1040 \RequirePackageWithOptions
1041 \end{verbatim}
1042 The command |\RequirePackageWithOptions| is similar to
1043 |\RequirePackage|, but it always loads the required package with
1044 exactly the same option list as that being used by the current class
1045 or package, rather than with any option explicitly supplied or passed
1046 on by |\PassOptionsToPackage|.
1047
1048 The main purpose of |\LoadClassWithOptions| is to allow one class to
1049 simply build on another, for example:
1050 \begin{verbatim}
1051 \LoadClassWithOptions{article}
1052 \end{verbatim}
1053 This should be compared with the slightly different construction
1054 \begin{verbatim}
1055 \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
1056 \ProcessOptions\relax
1057 \LoadClass{article}
1058 \end{verbatim}
1059 As used above, the effects are more or less the same, but the first is
1060 a lot less to type; also the |\LoadClassWithOptions| method runs
1061 slightly quicker.
1062
1063 If, however, the class declares options of its own then
1064 the two constructions are different. Compare, for example:
1065 \begin{verbatim}
1066 \DeclareOption{landscape}{\@landscapetrue}
1067 \ProcessOptions\relax
1068 \LoadClassWithOptions{article}
1069 \end{verbatim}
1070 with:
1071 \begin{verbatim}
1072 \DeclareOption{landscape}{\@landscapetrue}
1073 \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
1074 \ProcessOptions\relax
1075 \LoadClass{article}
1076 \end{verbatim}
1077 In the first example, the \textsf{article} class will be loaded with
1078 option |landscape| precisely when the current class is called with
1079 this option. By contrast, in the second example it will never be
1080 called with option \texttt{landscape} as in that case \textsf{article}
1081 is passed options only by the default option handler, but this handler
1082 is not used for |landscape| because that option is explicitly
1083 declared.
1084
1085 \subsection{Delaying code}
1086 \label{Sec:delays}
1087
1088 These first two commands are also intended primarily for use within
1089 the \m{code} argument of |\DeclareOption| or |\DeclareOption*|.
1090
1091 \begin{decl}
1092 |\AtEndOfClass| \arg{code}\\
1093 |\AtEndOfPackage| \arg{code}
1094 \end{decl}
1095 These commands declare \m{code} that is saved away internally and then
1096 executed after processing the whole of the current class or package
1097 file.
1098
1099 Repeated use of these commands is permitted: the code in the
1100 arguments is stored (and later executed) in the order of their
1101 declarations.
1102
1103 \begin{decl}
1104 |\AtBeginDocument| \arg{code}\\
1105 |\AtEndDocument| \arg{code}
1106 \end{decl}
1107 These commands declare \m{code} to be saved internally and executed
1108 while \LaTeX{} is executing |\begin{document}| or |\end{document}|.
1109
1110 The \m{code} specified in the argument to |\AtBeginDocument| is
1111 executed near the end of the |\begin{document}| code, \emph{after} the
1112 font selection tables have been set up. It is therefore a useful
1113 place to put code which needs to be executed after everything has been
1114 prepared for typesetting and when the normal font for the document is
1115 the current font.
1116
1117 \NEWdescription{1995/12/01}
1118 The |\AtBeginDocument| hook should not be used for code that does any
1119 typesetting since the typeset result would be unpredictable.
1120
1121 The \m{code} specified in the argument to |\AtEndDocument| is
1122 executed at the beginning of the |\end{document}| code,
1123 \emph{before} the final page is finished and before any leftover
1124 floating environments are processed. If some of the \m{code} is to be
1125 executed after these two processes, you should include a |\clearpage|
1126 at the appropriate point in \m{code}.
1127
1128 Repeated use of these commands is permitted: the code in the
1129 arguments is stored (and later executed) in the order of their
1130 declarations.
1131
1132 \begin{decl}[1994/12/01]
1133 |\AtBeginDvi| \arg{specials}
1134 \end{decl}
1135 These commands save in a box register things which are written to the
1136 |.dvi| file at the beginning of the `shipout' of the first page of the
1137 document.
1138
1139 This should not be used for anything that will add any typeset
1140 material to the |.dvi| file.
1141
1142 Repeated use of this command is permitted.
1143
1144
1145 \subsection{Option processing}
1146 \label{Sec:commands.options}
1147
1148 \begin{decl}
1149 |\ProcessOptions|
1150 \end{decl}
1151 This command executes the \m{code} for each selected option.
1152
1153 We shall first describe how |\ProcessOptions| works in a package file,
1154 and then how this differs in a class file.
1155
1156 To understand in detail what |\ProcessOptions| does in a package file,
1157 you have to know the difference between \emph{local} and \emph{global}
1158 options.
1159 \begin{itemize}
1160 \item \textbf{Local options} are those which have been explicitly
1161 specified for this particular package in the \m{options} argument of
1162 any of these:
1163 \begin{quote}
1164 |\PassOptionsToPackage{<options>}| \ |\usepackage[<options>]|\\
1165 |\RequirePackage[<options>]|
1166 \end{quote}
1167 \item \textbf{Global options} are any other options that are specified
1168 by the author in the \m{options} argument of
1169 |\documentclass[<options>]|.
1170 \end{itemize}
1171 For example, suppose that a document begins:
1172 \begin{verbatim}
1173 \documentclass[german,twocolumn]{article}
1174 \usepackage{gerhardt}
1175 \end{verbatim}
1176 whilst package |gerhardt| calls package |fred| with:
1177 \begin{verbatim}
1178 \PassOptionsToPackage{german,dvips,a4paper}{fred}
1179 \RequirePackage[errorshow]{fred}
1180 \end{verbatim}
1181 then:
1182 \begin{itemize}
1183 \item |fred|'s local options are |german|, |dvips|, |a4paper|
1184 and |errorshow|;
1185 \item |fred|'s only global option is |twocolumn|.
1186 \end{itemize}
1187
1188 When |\ProcessOptions| is called, the following happen.
1189 \begin{itemize}
1190 \item \emph{First}, for each option so far declared in |fred.sty|
1191 by |\DeclareOption|, it looks to see if that option is either a
1192 global or a local option for |fred|: if it is then the corresponding
1193 code is executed.
1194
1195 This is done in the order in which these options
1196 were declared in |fred.sty|.
1197 \item \emph{Then}, for each remaining \emph{local} option, the command
1198 |\ds@<option>| is executed if it has been defined somewhere (other
1199 than by a |\DeclareOption|); otherwise, the `default option code' is
1200 executed. If no default option code has been declared then an error
1201 message is produced.
1202
1203 This is done in the order in which these
1204 options were specified.
1205 \end{itemize}
1206 Throughout this process, the system ensures that the code declared for
1207 an option is executed at most once.
1208
1209 Returning to the example, if |fred.sty| contains:
1210 \begin{verbatim}
1211 \DeclareOption{dvips}{\typeout{DVIPS}}
1212 \DeclareOption{german}{\typeout{GERMAN}}
1213 \DeclareOption{french}{\typeout{FRENCH}}
1214 \DeclareOption*{\PackageWarning{fred}{Unknown `\CurrentOption'}}
1215 \ProcessOptions\relax
1216 \end{verbatim}
1217 then the result of processing this document will be:
1218 \begin{verbatim}
1219 DVIPS
1220 GERMAN
1221 Package fred Warning: Unknown `a4paper'.
1222 Package fred Warning: Unknown `errorshow'.
1223 \end{verbatim}
1224 Note the following:
1225
1226 \begin{itemize}
1227 \item the code for the |dvips| option is executed before that for the
1228 |german| option, because that is the order in which they are declared
1229 in |fred.sty|;
1230 \item the code for the |german| option is executed only once, when the
1231 declared options are being processed;
1232 \item the |a4paper| and |errorshow| options produce the warning from
1233 the code declared by |\DeclareOption*| (in the order in which they
1234 were specified), whilst the |twocolumn| option does not: this is
1235 because |twocolumn| is a global option.
1236 \end{itemize}
1237
1238 In a class file, |\ProcessOptions| works in the same way, except
1239 that: \emph{all} options are local; and the default value for
1240 |\DeclareOption*| is |\OptionNotUsed| rather than an error.
1241
1242 \NEWdescription{1995/12/01}
1243 Note that, because |\ProcessOptions| has a |*|-form, it is wise to
1244 follow the non-star form with |\relax|, as in the previous examples,
1245 since this prevents unnecessary look ahead and possibly misleading
1246 error messages being issued.
1247
1248 \begin{decl}
1249 |\ProcessOptions*| \\
1250 |\@options|
1251 \end{decl}
1252 This is like |\ProcessOptions| but it executes the options in the
1253 order specified in the calling commands, rather than in the order of
1254 declaration in the class or package. For a package this means that the
1255 global options are processed first.
1256
1257 The |\@options| command from \LaTeX~2.09 has been made equivalent to
1258 this in order to ease the task of updating old document styles to
1259 \LaTeXe{} class files.
1260
1261 \begin{decl}
1262 |\ExecuteOptions| \arg{options-list}
1263 \end{decl}
1264
1265 For each option in the \m{options-list}, in order,
1266 this command simply executes the command
1267 |\ds@<option>| (if this command is not defined, then that option is
1268 silently ignored).
1269
1270 It can be used to provide a `default option list' just before
1271 |\ProcessOptions|. For example, suppose that in a class file you want
1272 to set up the default design to be: two-sided printing; 11pt fonts;
1273 in two columns. Then it could specify:
1274 \begin{verbatim}
1275 \ExecuteOptions{11pt,twoside,twocolumn}
1276 \end{verbatim}
1277
1278
1279 \subsection{Safe file commands}
1280
1281 These commands deal with file input; they ensure that the non-existence
1282 of a requested file can be handled in a user-friendly way.
1283
1284 \begin{decl}
1285 |\IfFileExists| \arg{file-name} \arg{true} \arg{false}
1286 \end{decl}
1287 If the file exists then the code specified in \m{true} is
1288 executed.
1289
1290 If the file does not exist then the code specified in \m{false} is
1291 executed.
1292
1293 This command does \emph{not} input the file.
1294
1295 \begin{decl}
1296 |\InputIfFileExists| \arg{file-name} \arg{true} \arg{false}
1297 \end{decl}
1298 This inputs the file \m{file-name} if it exists and, immediately
1299 before the input, the code specified in \m{true} is executed.
1300
1301 If the file does not exist then the code specified in \m{false} is
1302 executed.
1303
1304 It is implemented using |\IfFileExists|.
1305
1306
1307 \subsection{Reporting errors, etc}
1308
1309 These commands should be used by third party classes and packages to
1310 report errors, or to provide information to authors.
1311
1312 \begin{decl}
1313 |\ClassError| \arg{class-name} \arg{error-text} \arg{help-text}\\
1314 |\PackageError| \arg{package-name} \arg{error-text} \arg{help-text}
1315 \end{decl}
1316 These produce an error message. The \m{error-text} is displayed and the
1317 |?| error prompt is shown. If the user types |h|, they will be shown
1318 the \m{help-text}.
1319
1320 Within the \m{error-text} and \m{help-text}: |\protect| can be used to
1321 stop a command from expanding; |\MessageBreak| causes a line-break;
1322 and |\space| prints a space.
1323
1324 Note that the \m{error-text} will have a full stop added to it, so do
1325 not put one into the argument.
1326
1327 For example:
1328 \begin{verbatim}
1329 \newcommand{\foo}{FOO}
1330 \PackageError{ethel}{%
1331 Your hovercraft is full of eels,\MessageBreak
1332 and \protect\foo\space is \foo
1333 }{%
1334 Oh dear! Something's gone wrong.\MessageBreak
1335 \space \space Try typing \space <<return>>
1336 \space to proceed, ignoring \protect\foo.
1337 }
1338 \end{verbatim}
1339 produces this display:
1340 \begin{verbatim}
1341 ! Package ethel Error: Your hovercraft is full of eels,
1342 (ethel) and \foo is FOO.
1343
1344 See the ethel package documentation for explanation.
1345 \end{verbatim}
1346 If the user types |h|, this will be shown:
1347 \begin{verbatim}
1348 Oh dear! Something's gone wrong.
1349 Try typing <<return>> to proceed, ignoring \foo.
1350 \end{verbatim}
1351
1352 \begin{decl}
1353 |\ClassWarning| \arg{class-name} \arg{warning-text}\\
1354 |\PackageWarning| \arg{package-name} \arg{warning-text}\\
1355 |\ClassWarningNoLine| \arg{class-name} \arg{warning-text}\\
1356 |\PackageWarningNoLine| \arg{package-name} \arg{warning-text}\\
1357 |\ClassInfo| \arg{class-name} \arg{info-text}\\
1358 |\PackageInfo| \arg{package-name} \arg{info-text}
1359 \end{decl}
1360 The four |Warning| commands are similar to the error commands, except
1361 that they produce only a warning on the screen, with no error prompt.
1362
1363 The first two, |Warning| versions, also show the line number where the
1364 warning occurred, whilst the second two, |WarningNoLine| versions, do
1365 not.
1366
1367 The two |Info| commands are similar except that they log the
1368 information only in the transcript file, including the line number.
1369 There are no |NoLine| versions of these two.
1370
1371 Within the \m{warning-text} and \m{info-text}: |\protect| can be used to
1372 stop a command from expanding; |\MessageBreak| causes a line-break;
1373 and |\space| prints a space.
1374 Also, these should not end with a full stop as one is
1375 automatically added.
1376
1377
1378 \subsection{Defining commands}
1379 \label{Sec:commands.define}
1380
1381 \LaTeXe{} provides some extra methods of (re)defining commands that are
1382 intended for use in class and package files.
1383
1384 \NEWfeature{1994/12/01}
1385 The \texttt{*}-forms of these commands should be used to define
1386 commands that are not, in \TeX{} terms, long. This can be useful for
1387 error-trapping with commands whose arguments are not intended to
1388 contain whole paragraphs of text.
1389
1390 \begin{decl}
1391 |\DeclareRobustCommand| \arg{cmd} \oarg{num} \oarg{default}
1392 \arg{definition}\\
1393 |\DeclareRobustCommand*| \arg{cmd} \oarg{num} \oarg{default}
1394 \arg{definition}
1395 \end{decl}
1396 This command takes the same arguments as |\newcommand| but it declares
1397 a robust command, even if some code within the \m{definition} is
1398 fragile. You can use this command to define new robust commands, or
1399 to redefine existing commands and make them robust. A log is put into
1400 the transcript file if a command is redefined.
1401
1402 For example, if |\seq| is defined as follows:
1403 \begin{verbatim}
1404 \DeclareRobustCommand{\seq}[2][n]{%
1405 \ifmmode
1406 #1_{1}\ldots#1_{#2}%
1407 \else
1408 \PackageWarning{fred}{You can't use \protect\seq\space in text}%
1409 \fi
1410 }
1411 \end{verbatim}
1412 Then the command |\seq| can be used in moving arguments, even though
1413 |\ifmmode| cannot, for example:
1414 \begin{verbatim}
1415 \section{Stuff about sequences $\seq{x}$}
1416 \end{verbatim}
1417
1418 Note also that there is no need to put a |\relax| before the
1419 |\ifmmode| at the beginning of the definition; this is because the
1420 protection given by this |\relax| against expansion at the wrong time
1421 will be provided internally.
1422
1423 \begin{decl}
1424 |\CheckCommand| \arg{cmd} \oarg{num} \oarg{default}
1425 \arg{definition}\\
1426 |\CheckCommand*| \arg{cmd} \oarg{num} \oarg{default}
1427 \arg{definition}
1428 \end{decl}
1429 This takes the same arguments as |\newcommand| but, rather than define
1430 \m{cmd}, it just checks that the current definition of \m{cmd} is
1431 exactly as given by \m{definition}. An error is raised if these
1432 definitions differ.
1433
1434 This command is useful for checking the state of the system before
1435 your package starts altering the definitions of commands. It allows
1436 you to check, in particular, that no other package has redefined the
1437 same command.
1438
1439 \subsection{Moving arguments}
1440
1441 \NEWdescription{1994/12/01}
1442 The setting of protect whilst processing (i.e.~moving) moving arguments
1443 has been reimplemented, as has the method of writing information from
1444 the |.aux| file to other files such as the |.toc| file. Details can
1445 be found in the file |ltdefns.dtx|.
1446
1447 We hope that these changes will not affect many packages.
1448
1449 \section{Miscellaneous commands, etc}
1450 \label{Sec:commands.misc}
1451
1452 \subsection{Layout parameters}
1453
1454 \begin{decl}
1455 |\paperheight|\\
1456 |\paperwidth|
1457 \end{decl}
1458 These two parameters are usually set by the class to be the size of
1459 the paper being used. This should be actual paper size, unlike
1460 |\textwidth| and |\textheight| which are the size of the main text
1461 body within the margins.
1462
1463
1464 \subsection{Case changing}
1465 \label{sec:case}
1466
1467 \begin{decl}
1468 |\MakeUppercase| \arg{text} \\
1469 |\MakeLowercase| \arg{text}
1470 \end{decl}
1471
1472 \NEWfeature{1995/06/01}
1473 \TeX{} provides two primitives |\uppercase| and |\lowercase| for
1474 changing the case of text. These are sometimes used in document
1475 classes, for example to set information in running heads in all
1476 capitals.
1477
1478 Unfortunately, these \TeX{} primitives do not change the case of
1479 characters accessed by commands like |\ae| or |\aa|. To overcome this
1480 problem, \LaTeX{} provides two new commands |\MakeUppercase| and
1481 |\MakeLowercase| to do this.
1482
1483 For example:
1484 \begin{quote}
1485 \begin{tabular}{rl}
1486 |\uppercase{aBcD\ae\AA\ss\OE}| & \uppercase{aBcD\ae\AA\ss\OE}\\
1487 |\lowercase{aBcD\ae\AA\ss\OE}| & \lowercase{aBcD\ae\AA\ss\OE}\\
1488 |\MakeUppercase{aBcD\ae\AA\ss\OE}| &
1489 \MakeUppercase{aBcD\ae\AA\ss\OE}\\
1490 |\MakeLowercase{aBcD\ae\AA\ss\OE}| & \MakeLowercase{aBcD\ae\AA\ss\OE}
1491 \end{tabular}
1492 \end{quote}
1493
1494 The commands |\MakeUppercase| and |\MakeLowercase| themselves are
1495 robust, but they have moving arguments.
1496
1497 The commands use the \TeX{} primitives |\uppercase| and |\lowercase|,
1498 and so have a number of unexpected `features'. In particular, they
1499 change the case of everything (except characters in the names of
1500 control-sequences) in their text argument: this includes mathematics,
1501 environment names, and label names.
1502
1503 For example:
1504 \begin{verbatim}
1505 \MakeUppercase{$x+y$ in \ref{foo}}
1506 \end{verbatim}
1507 produces $X+Y$ and the warning:
1508 \begin{verbatim}
1509 LaTeX Warning: Reference `FOO' on page ... undefined on ...
1510 \end{verbatim}
1511 In the long run, we would like to use all-caps fonts rather than any
1512 command like |\MakeUppercase| but this is not possible at the moment
1513 because such fonts do not exist.
1514
1515 \NEWdescription{1995/12/01}
1516 In order that upper/lower-casing will work reasonably well, and in
1517 order to provide any correct hyphenation, \LaTeXe{} \emph{must} use,
1518 throughout a document, the same fixed table for changing case.
1519 The table used is designed for the font encoding |T1|; this works well
1520 with the standard \TeX{} fonts for all Latin alphabets but will cause
1521 problems when using other alphabets.
1522
1523 \subsection{The `openany' option in the `book' class}
1524
1525 \NEWdescription{1996/06/01}
1526 The |openany| option allows chapter and similar openings to
1527 occur on left hand pages. Previously this option affected only
1528 |\chapter| and |\backmatter|. It now also affects
1529 |\part|, |\frontmatter| and |\mainmatter|.
1530
1531 \subsection{Better user-defined math display environments}
1532
1533 \begin{decl}
1534 |\ignorespacesafterend|
1535 \end{decl}
1536
1537 \NEWfeature{1996/12/01}
1538 \NEWdescription{2003/12/01}
1539 Suppose that you want to define an environment for displaying text
1540 that is numbered as an equation. A straightforward way to do this is
1541 as follows:
1542 \begin{verbatim}
1543 \newenvironment{texteqn}
1544 {\begin{equation}
1545 \begin{minipage}{0.9\linewidth}}
1546 {\end{minipage}
1547 \end{equation}}
1548 \end{verbatim}
1549 However, if you have tried this then you will probably have noticed
1550 that it does not work perfectly when used in the middle of a paragraph
1551 because an inter-word space appears at the beginning of the first
1552 line after the environment.
1553
1554 There is now an extra command (with a very long name) available that
1555 you can use to avoid this problem; it should be inserted as shown here:
1556 \begin{verbatim}
1557 \newenvironment{texteqn}
1558 {\begin{equation}
1559 \begin{minipage}{0.9\linewidth}}
1560 {\end{minipage}
1561 \end{equation}
1562 \ignorespacesafterend}
1563 \end{verbatim}
1564
1565 This command may also have other uses.
1566
1567 \subsection{Normalising spacing}
1568
1569 \begin{decl}
1570 |\normalsfcodes|
1571 \end{decl}
1572
1573 \NEWfeature{1997/06/01}
1574 This command should be used to restore the normal settings of the
1575 parameters that affect spacing between words, sentences, etc.
1576
1577 An important use of this feature is to correct a problem, reported by
1578 Donald Arseneau, that punctuation in page headers has always (in all
1579 known \TeX{} formats) been potentially wrong whenever a page break
1580 happens while a local setting of the space codes is in effect. These
1581 space codes are changed by, for example, the command
1582 \verb|\frenchspacing|) and the \textsf{verbatim} environment.
1583
1584 It is normally given the correct definition automatically in
1585 |\begin{document}| and so need not be explicitly set; however, if it
1586 is explicitly made nonempty in a class file then automatic
1587 default setting will be over-ridden.
1588
1589
1590 \section{Upgrading \LaTeX~2.09 classes and packages}
1591 \label{Sec:upgrade}
1592
1593 This section describes the changes you may need to make when you
1594 upgrade an existing \LaTeX{} style to a package or class but we shall
1595 start in optimistic mode.
1596
1597 Many existing style files will run with \LaTeXe{} without any
1598 modification to the file itself. When everything is running OK,
1599 please put a note in the newly created package or class file to record
1600 that it runs with the new standard \LaTeX{}; then distribute it to
1601 your users.
1602
1603 \subsection{Try it first!}
1604 \label{Sec:try-it}
1605
1606 The first thing you should do is to test your style in `compatibility
1607 mode'. The only change you need to make in order to do this is,
1608 possibly, to change the extension of the file to |.cls|: you should
1609 make this change only if your file was used as a main document style.
1610 Now, without any other modifications, run \LaTeXe{} on a document that
1611 uses your file. This assumes that you have a suitable collection of
1612 files that tests all the functionality provided by your style file.
1613 (If you haven't, now is the time to make one!)
1614
1615 You now need to change the test document files so that they are
1616 \LaTeXe{} documents: see \emph{\usrguide} for details of how to do
1617 this and then try them again. You have now tried the test documents
1618 in both \LaTeXe{} native mode and \LaTeX~2.09 compatibility mode.
1619
1620 \subsection{Troubleshooting}
1621 \label{Sec:trouble}
1622
1623 If your file does not work with \LaTeXe{}, there are two likely
1624 reasons.
1625 \begin{itemize}
1626 \item \LaTeX{} now has a robust, well-defined designer's interface for
1627 selecting fonts, which is very different from the \LaTeX~2.09
1628 internals.
1629 \item Your style file may have used some \LaTeX~2.09 internal commands
1630 which have changed, or which have been removed.
1631 \end{itemize}
1632
1633 When you are debugging your file, you will probably need more
1634 information than is normally displayed by \LaTeXe. This is achieved
1635 by resetting the counter |errorcontextlines| from its default value of
1636 $-1$ to a much higher value, e.g.~999.
1637
1638 \subsection{Accommodating compatibility mode}
1639
1640 Sometimes an existing collection of \LaTeX~2.09 documents makes it
1641 inconvenient or impossible to abandon the old commands entirely.
1642 If this is the case, then it is possible to accommodate both conventions
1643 by making special provision for documents processed in compatibility
1644 mode.
1645
1646 \begin{decl}
1647 |\if@compatibility|
1648 \end{decl}
1649 This switch is set when a document begins with |\documentstyle| rather
1650 than |\documentclass|. Appropriate code can be supplied for either
1651 condition, as follows:
1652 \begin{verbatim}
1653 \if@compatibility
1654 <code emulating LaTeX 2.09 behavior>
1655 \else
1656 <code suitable for LaTeX2e>
1657 \fi
1658 \end{verbatim}
1659
1660
1661 \subsection{Font commands}
1662
1663 Some font and size commands are now defined by the document class
1664 rather than by the \LaTeX{} kernel. If you are upgrading a
1665 \LaTeX~2.09 document style to a class that does not load one of the
1666 standard classes, then you will probably need to add definitions for
1667 these commands.
1668
1669 \begin{decl}
1670 |\rm| |\sf| |\tt| |\bf| |\it| |\sl| |\sc|
1671 \end{decl}
1672 None of these short-form font selection commands are defined in the
1673 \LaTeXe{} kernel. They are defined by all the standard class files.
1674
1675 If you want to define them in your class file, there are several
1676 reasonable ways to do this.
1677
1678 One possible definition is:
1679 \begin{verbatim}
1680 \newcommand{\rm}{\rmfamily}
1681 ...
1682 \newcommand{\sc}{\scshape}
1683 \end{verbatim}
1684 This would make the font commands orthogonal; for example
1685 |{\bf\it text}| would produce bold italic, thus: \textbf{\textit{text}}.
1686 It will also make them produce an error if used in math mode.
1687
1688 Another possible definition is:
1689 \begin{verbatim}
1690 \DeclareOldFontCommand{\rm}{\rmfamily}{\mathrm}
1691 ...
1692 \DeclareOldFontCommand{\sc}{\scshape}{\mathsc}
1693 \end{verbatim}
1694 This will make |\rm| act like |\rmfamily| in text mode (see above) and
1695 it will make |\rm| select the |\mathrm| math alphabet in math mode.
1696
1697 Thus |${\rm math} = X + 1$| will produce `${\rm math} = X + 1$'.
1698
1699 If you do not want font selection to be orthogonal then you can
1700 follow the standard classes and define:
1701 \begin{verbatim}
1702 \DeclareOldFontCommand{\rm}{\normalfont\rmfamily}{\mathrm}
1703 ...
1704 \DeclareOldFontCommand{\sc}{\normalfont\scshape}{\mathsc}
1705 \end{verbatim}
1706 This means, for example, that |{\bf\it text}| will produce medium
1707 weight (rather than bold) italic, thus: \textit{text}.
1708
1709 \begin{decl}
1710 |\normalsize| \\
1711 |\@normalsize|
1712 \end{decl}
1713 The command |\@normalsize| is retained for compatibility with
1714 \LaTeX~2.09 packages which may have used its value; but redefining it
1715 in a class file will have no effect since it is always reset to have
1716 the same meaning as |\normalsize|.
1717
1718 This means that classes \emph{must} now redefine |\normalsize| rather
1719 than redefining |\@normalsize|; for example (a rather incomplete one):
1720 \begin{verbatim}
1721 \renewcommand{\normalsize}{\fontsize{10}{12}\selectfont}
1722 \end{verbatim}
1723 Note that |\normalsize| is defined by the \LaTeX{} kernel to be an
1724 error message.
1725
1726 \begin{decl}
1727 |\tiny| |\footnotesize| |\small| |\large|\\
1728 |\Large| |\LARGE| |\huge| |\Huge|
1729 \end{decl}
1730 None of these other `standard' size-changing commands are defined in
1731 the kernel: each needs to be defined in a class file if you need it.
1732 They are all defined by the standard classes.
1733
1734 This means you should use |\renewcommand| for |\normalsize| and
1735 |\newcommand| for the other size-changing commands.
1736
1737
1738 \subsection{Obsolete commands}
1739
1740 Some packages will not work with \LaTeXe{}, normally because they relied
1741 on an internal \LaTeX{} command which was never supported and has now
1742 changed, or been removed.
1743
1744 In many cases there will now be a robust, high-level means of
1745 achieving what previously required low-level commands. Please consult
1746 Section~\ref{Sec:commands} to see if you can now use the \LaTeXe{}
1747 class and package writers commands.
1748
1749 Also, of course, if your package or class redefined any of the kernel
1750 commands (i.e.~those defined in the files |latex.tex|, |slitex.tex|,
1751 |lfonts.tex|, |sfonts.tex|) then you will need to check it very
1752 carefully against the new kernel in case the implementation has
1753 changed or the command no longer exists in the \LaTeX2e{} kernel.
1754
1755 Too many of the internal commands of \LaTeX~2.09 have been
1756 re-implemented or removed to be able to list them all here. You must
1757 check any that you have used or changed.
1758
1759 We shall, however, list some of the more important commands which are
1760 no longer supported.
1761
1762 \begin{decl}
1763 |\tenrm| |\elvrm| |\twlrm| \dots\\
1764 |\tenbf| |\elvbf| |\twlbf| \dots\\
1765 |\tensf| |\elvsf| |\twlsf| \dots\\
1766 \qquad$\vdots$
1767 \end{decl}
1768 The (approximately) seventy internal commands of this form are no longer
1769 defined. If your class or package uses them then \emph{please}
1770 replace them with new font commands described in \emph{\fntguide}.
1771
1772 For example, the command |\twlsf| should be replaced by:
1773 \begin{verbatim}
1774 \fontsize{12}{14}\normalfont\sffamily\selectfont
1775 \end{verbatim}
1776
1777 Another possibility is to use the |rawfonts| package, described in
1778 \emph{\usrguide}.
1779
1780 Also, remember that many of the fonts preloaded by \LaTeX~2.09
1781 are no longer preloaded.
1782
1783 \begin{decl}
1784 |\vpt| |\vipt| |\viipt| \dots
1785 \end{decl}
1786 These were the internal size-selecting commands in \LaTeX~2.09.
1787 (They can still be used in \LaTeX~2.09 compatibility mode.)
1788 Please use the command |\fontsize| instead: see \emph{\fntguide} for
1789 details.
1790
1791 For example, |\vpt| should be replaced by:
1792 \begin{verbatim}
1793 \fontsize{5}{6}\normalfont\selectfont
1794 \end{verbatim}
1795
1796 \begin{decl}
1797 |\prm|, |\pbf|, |\ppounds|, |\pLaTeX| \dots
1798 \end{decl}
1799 \LaTeX~2.09 used several commands beginning with |\p| in order to
1800 provide `protected' commands. For example, |\LaTeX| was defined to be
1801 |\protect\pLaTeX|, and |\pLaTeX| was defined to produce the \LaTeX{}
1802 logo. This made |\LaTeX| robust, even though |\pLaTeX| was not.
1803
1804 These commands have now been reimplemented using
1805 |\DeclareRobustCommand|
1806 (described in Section~\ref{Sec:commands.define}).
1807 If your package redefined one of the |\p|-commands then you must
1808 remove the redefinition and use |\DeclareRobustCommand| to redefine the
1809 non-|\p| command.
1810
1811 \begin{decl}
1812 |\footheight|\\
1813 |\@maxsep|\\
1814 |\@dblmaxsep|
1815 \end{decl}
1816 These parameters are not used by \LaTeXe{} so they have been removed,
1817 except in \LaTeX~2.09 compatibility mode. Classes should no longer
1818 set them.
1819
1820 \begin{thebibliography}{1}
1821
1822 \bibitem{A-W:DEK91}
1823 Donald~E. Knuth.
1824 \newblock {\em The \TeX book}.
1825 \newblock Addison-Wesley, Reading, Massachusetts, 1986.
1826 \newblock Revised to cover \TeX3, 1991.
1827
1828 \bibitem{A-W:LLa94}
1829 Leslie Lamport.
1830 \newblock {\em {\LaTeX:} A Document Preparation System}.
1831 \newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994.
1832
1833 \bibitem{A-W:MG2004}
1834 Frank Mittelbach and Michel Goossens.
1835 \newblock {\em The {\LaTeX} Companion second edition}.
1836 \newblock With Johannes Braams, David Carlisle, and Chris Rowley.
1837 \newblock Addison-Wesley, Reading, Massachusetts, 2004.
1838
1839 \end{thebibliography}
1840
1841 \newpage
1842 \thispagestyle{empty}
1843
1844 \section*{\LaTeXe{} Summary sheet: updating old styles}
1845
1846 Section references below are to \emph{\clsguide}.
1847
1848 \begin{enumerate}
1849
1850 \item Should it become a class or a package?
1851 See Section~\ref{Sec:classorpkg} for how to answer this question.
1852
1853 \item If it uses another style file, then you will need to obtain an
1854 updated version of this other file. Look at Section~\ref{Sec:loading}
1855 for information on how to load other class and package files.
1856
1857 \item Try it: see Section~\ref{Sec:try-it}.
1858
1859 \item It worked? Excellent, but there are probably still some things
1860 you should change in order to make your file into a well-structured
1861 \LaTeXe{} file that is both robust and portable. So you should now
1862 read Section~\ref{Sec:writing}, especially~\ref{Sec:general}. You
1863 will also find some useful examples in Section~\ref{Sec:structure}.
1864
1865 If your file sets up new fonts, font-changing commands or symbols,
1866 you should also read \emph{\fntguide}.
1867
1868 \item It did not work? There are three possibilities here:
1869 \begin{itemize}
1870 \item error messages are produced whilst reading your file;
1871 \item error messages are produced whilst processing test documents;
1872 \item there are no errors but the output is not as it should be.
1873 \end{itemize}
1874 Don't forget to check carefully for this last possibility.
1875
1876 If you have got to this stage then you will need to read
1877 Section~\ref{Sec:upgrade} to find the solutions that will make your
1878 file work.
1879 \end{enumerate}
1880
1881 \end{document}