Writing classes and packages for L A TEX 2ε
Overview
It describes the difference between classes and packages, command naming conventions, the use of doc and docstrip, how TEX's primitive file and box commands interact with LATEX. This includes building classes and packages on top of other classes and packages, declaring options, and declaring commands.
Further information
It can be set from the LATEX file source2e.tex in the base directory, using the source files and class fileltxdoc.cls from this directory. For more information about TEX and LATEX, please contact your local TEX Users Group or the international TEX Users Group.
Policy on standard classes
Experience with the various dialects of LATEX that existed in the early 1990s suggests that it is almost impossible to maintain packages for different versions of LATEX. Of course, it will be necessary for some organizations to maintain both versions in parallel for some time, but this is not critical for the packages and classes supported by individuals: they should only support the new standard LATEX 2ε, not obsolete versions of LATEX.
Using ‘docstrip’ and ‘doc’
If you are upgrading an existing LATEX 2.09 style file, then we recommend that you upgrade to version 2.09 and no longer maintain it.
Is it a class or a package?
If the commands can be used with any document class, then make them a package; and if not, then make it a class. Since these commands can be used with any document class, we kemigraphics.styrather sesagraphics.cls.
Command names
There are two main types of teaching: those such as the article, report or letter, which are free-standing; and those that are extensions or variations of other classes—for example, the proc document class, which is built on the article document class. Such a class would build on top of the existing letter class, but it cannot be used with any other document class, so we harownlet.cls instead of ownlet.sty.
Box commands and colour
Defining text and math characters
General style
Note, however, that the code in\AtBeginDocumenthook is part of the pream- New description ble. Usually, these commands will be just those needed for the code used in the declared options.
Using classes and packages
Declaring options
It is possible to pass options to another package or class, using com-Description new mand\PassOptionsToPackage or \PassOptionsToClass (note that this is a specialized . operation that only works on option names). If you do this, then you need to make sure you load the class at a later point, otherwise the options will never be processed. So far, we've only explained how to declare options, not how to execute them.
It executes thehcodei for each option both specified and declared (see Section 4.7 for details of how this is done).
A minimal class file
However, this class file does not support footnotes, margins, floats, etc., nor will it provide any of the 2-letter font commands such as \rm; thus, most classes will contain more than this minimum.
Example: a local letter class
Example: a newsletter class
The class then redefines \maketitle to produce the title in 72pt Helvetica bold italic, in the appropriate color. In practice, a class will need more than this: it will provide assignments for issue numbers, authors of articles, page styles and so on; but this skeleton gives a start. To find out about other aspects of the new system, you should also read LATEX: A Document Preparation System, The LATEX Companion and LATEX 2ε for Writers.
You can use the optional hrlease-datei argument to further specify the earliest format release date needed. When the release date of the format is older than the specified one, a warning will be generated. The above syntax must be followed exactly so that this information can be used by \LoadClass or \documentclass (for classes) or \RequirePackage or.
This is similar to the previous two commands, except that the full file name, including the extension, must be given here. Note that the phrase Standard LaTeX should not be used in the identifier banner of any files other than those in the standard LATEX distribution.
Loading files
These commands are for use in class files only, they cannot be used in packages New function files; they can be used at most once in a class file.
Option declaration
Commands within option code
Moving options around
The \RequirePackageWithOptions command is similar to \RequirePackage, but always loads the required package with exactly the same option list used by the current class or package, rather than an option explicitly provided or passed by \PassOptionsToPackage. As used above, the effects are more or less the same, but the first one is a lot less for typing; also the \LoadClassWithOptions method works slightly faster. In the first example, the article class is loaded with the landscape option exactly when the current class is called with this option.
Conversely, in the second example it will never be called with the landscape option, because in that case the item is only passed options by the default option handler, but this handler is not used for landscape because that option is explicitly declared.
Delaying code
Option processing
Then, for each remaining local option, the command\ds@hoptioni is executed if it is defined somewhere (other than by a\DeclareOption);. During this process, the system ensures that the code declared for an option is executed at most once. In a class file, \ProcessOptions works the same way, except that: all options are local; and the default value for\DeclareOption*is\OptionNotUsedrather as an error.
Note that since \ProcessOptions has the form *, it is wise to follow the unstarred form of the New Description with \relax as in the previous examples, as this prevents this. This is like \ProcessOptions, but executes the options in the order specified in the calling commands instead of in the order of declaration in the class or package. The \@options command from LATEX 2.09 was equivalent to make the task of updating old document styles into LATEX 2ε class files easier.
For each option in the hoptions-list, in order, this command simply executes the \ds@hoptioni command (if this command is not defined, this option is silently ignored). For example, suppose in a class file you want to set the default design to be: two-sided printing; 11 pt fonts; in two columns.
Safe file commands
Reporting errors, etc
Within therror-text andhhelp-text: \protect can be used to stop the expansion of a command;\MessageBreak causes a line break; and\spaceprints a space. Note that herror-text will have a dot appended to it, so don't put it in the argument. The four warning commands are similar to the error commands, except that they produce only a warning on the screen, with no error prompts.
The first two, WarningVersions, also show the line number where the warning occurred, while the other two, WarningNoLineversions, do not. The two Info commands are similar except that they only log the information in the transcript file, including the line number. Within hwarning-texti and hininfo-texti: \protect can be used to prevent a command from expanding; \MessageBreak causes a line break; and \space prints a space.
Defining commands
This takes the same arguments as \newcommand but, instead of definehcmdi, it simply checks that the current hcmdi definition is exactly as given by hdefinition. This allows you to check, in particular, that no other package has redefined the same command.
Moving arguments
Case changing
The commands use the TEX primitives \uppercase and \lowercase, and thus have a number of unexpected 'features'. In particular, they change the case of everything (except characters in control sequence names) in their text argument: this includes math, environment names, and tag names. In the long run, we would like to use full-case fonts instead of some command like \MakeUppercase, but this is not possible at the moment because such fonts do not exist.
In order for upper/lower case to work reasonably well, and for new description to provide any correct hyphens, LATEX must use 2ε throughout a document.
The ‘openany’ option in the ‘book’ class
Better user-defined math display environments
But if you've tried it, you've probably noticed that it doesn't work perfectly when used in the middle of a paragraph, because the space between words appears at the beginning of the first line after the environment.
Normalising spacing
The only change you need to make for this may be to change the extension of the file to .cls: you should only make this change if your file was used as the master document style. This assumes you have a suitable set of files that test all the functionality of your style file. You now need to change the test document files so they are LATEX 2ε documents: see LATEX 2ε for Authors for details on how to do this and then try them again.
You have now tried the test documents in both native LATEX 2ε mode and LATEX 2.09 compatibility mode.
Troubleshooting
Accommodating compatibility mode
Font commands
The \@normalsize command is retained for compatibility with LATEX 2.09 packages that may have used its value; but redefining it in a class file has no effect as it always resets to have the same meaning as\normalsize.
Obsolete commands
This means, for example, that {\bf\it text} will produce medium-weight italics (instead of bold), so: text. However, we will list some of the more important commands that are no longer supported. If your class or package uses them, please replace them with the new font commands described in LATEX 2ε Font Selection.
For example, \LaTeX was defined to be \protect\pLaTeX, and \pLaTeX was defined to produce the LATEX logo. If your package redefined one of the \p commands, remove the redefinition and use \DeclareRobustCommand to redefine the non-\p command. These parameters are not used by LATEX 2ε, so they have been removed, except in LATEX 2.09 compatibility mode.
