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