LaTeX2e for class and package writers

Copyright © 1995-1997 The LaTeX3 Project
All rights reserved

8 June 1997

  • Introduction

    • Writing classes and packages for LaTeX2e
    • Overview
    • Further information
    • Policy on standard classes
  • Writing classes and packages
    • Old versions
    • Using `docstrip' and `doc'
    • Is it a class or a package?
    • Command names
    • Box commands and colour
    • Defining text and math characters
    • General style
      • Loading other files
      • Make it robust
      • Make it portable
      • Useful hooks
  • The structure of a class or package
    • Identification
    • Using classes and packages
    • Declaring options
    • A minimal class file
    • Example: a local letter class
    • Example: a newsletter class
  • Commands for class and package writers
    • Identification
    • Loading files
    • Option declaration
    • Commands within option code
    • Moving options around
    • Delaying code


Introduction

This document is an introduction to writing classes and packages for LaTeX, with special attention given to upgrading existing LaTeX 2.09 packages to LaTeX2e. The latter subject is also covered in an article by Johannes Braams published in TUGboat 15.3.

  • Policy on standard classes


Writing classes and packages for LaTeX2e

LaTeX is a document preparation system that enables the document writer to concentrate on the contents of their text, without bothering too much about the formatting of it. For example, chapters are indicated by \chapter{<title>} rather than by selecting 18pt bold.

The file that contains the information about how to turn logical structure (like `\chapter') into formatting (like `18pt bold ragged right') is a document class. In addition, some features (such as colour or included graphics) are independent of the document class and these are contained in packages.

One of the largest differences between LaTeX 2.09 and LaTeX2e is in the commands used to write packages and classes. In LaTeX 2.09, there was very little support for writing .sty files, and so writers had to resort to using low-level commands.

LaTeX2e provides high-level commands for structuring packages. It is also much easier to build classes and packages on top of each other, for example writing a local technical report class cetechr (for the Chemical Engineering department) based on article.


The structure of a class or package

LaTeX2e classes and packages have more structure than LaTeX 2.09 style files did. The outline of a class or package file is:

Identification

The file says that it is a LaTeX2e package or class, and gives a short description of itself.

Preliminary declarations

Here the file declares some commands and can also load other files. Usually these commands will be just those needed for the code used in the declared options.

Options

The file declares and processes its options.

More declarations

This is where the file does most of its work: declaring new variables, commands and fonts; and loading other files.

  • Identification

  • Using classes and packages
  • Declaring options
  • A minimal class file
  • Example: a local letter class
  • Example: a newsletter class


Commands for class and package writers

This section describes briefly each of the new commands for class and package writers. To find out about other aspects of the new system, you should also read LaTeX: A Document Preparation System, The LaTeX Companion and LaTeX2e for Authors.

  • Identification

  • Loading files
  • Option declaration
  • Commands within option code
  • Moving options around
  • Delaying code


Overview

This document contains an overview of how to write classes and packages for LaTeX. It does not introduce all of the commands necessary to write packages: these can be found in either LaTeX: A Document Preparation System or The LaTeX Companion. But it does describe the new commands for structuring classes and packages.

Section 2.7

contains some general advice about writing classes and packages. It describes the difference between classes and packages, the command naming conventions, the use of doc and docstrip, how TeX's primitive file and box commands interact with LaTeX. It also contains some hints about general LaTeX style.

Section 3

describes the structure of classes and packages. This includes building classes and packages on top of other classes and packages, declaring options and declaring commands. It also contains example classes.

Section 4

lists the new class and package commands.

Section 6

gives detailed advice on how to upgrade existing LaTeX 2.09 classes and packages to LaTeX2e.


Further information

For a general introduction to LaTeX, including the new features of LaTeX2e, you should read LaTeX: A Document Preparation System by Leslie Lamport [].

A more detailed description of the new features of LaTeX, and an overview of more than 150 packages, is to be found in The LaTeX Companion by Michel Goossens, Frank Mittelbach and Alexander Samarin [].

The LaTeX system is based on TeX, which is described in The TeXbook by Donald E. Knuth [].

There are a number of documentation files which accompany every copy of LaTeX. A copy of LaTeX News will come out with each six-monthly release of LaTeX, and is found in the files ltnews*.tex. The author's guide LaTeX2e for Authors describes the new LaTeX document features; it is in usrguide.tex. The guide LaTeX2e Font Selection describes the LaTeX font selection scheme for class- and package-writers; it is in fntguide.tex. Configuring LaTeX is covered by the guide Configuration options for LaTeX2e in cfgguide.tex whilst the philosophy behind our policy on modifying LaTeX is described in Modifying LaTeX in modguide.tex.

We are gradually turning the source code for LaTeX into a LaTeX document LaTeX: the program. This document includes an index of LaTeX commands and can be typeset from source2e.tex.

For more information about TeX and LaTeX, please contact your local TeX Users Group, or the international TeX Users Group. Here are some useful addresses.

TeX Users Group, P.O. Box 1239, Three Rivers, CA 93271-1239, USA
Fax: +1 209 561 4584 Email: tug@mail.tug.org

UK TUG, 1 Eymore Close, Selly Oak, Birmingham B29 4LB, UK
Fax: +44 121 476 2159 Email: uktug-enquiries@tex.ac.uk


Policy on standard classes

Many of the problem reports we receive concerning the standard classes are not concerned with bugs but are suggesting, more or less politely, that the design decisions embodied in them are `not optimal' and asking us to modify them.

There are several reasons why we should not make such changes to these files.

  • However misguided, the current behaviour is clearly what was intended when these classes were designed.

  • It is not good practice to change such aspects of `standard classes' because many people will be relying on them.

We have therefore decided not to even consider making such modifications, nor to spend time justifying that decision. This does not mean that we do not agree that there are many deficiencies in the design of these classes, but we have many tasks with higher priority than continually explaining why the standard classes for LaTeX cannot be changed.

We would, of course, welcome the production of better classes, or of packages that can be used to enhance these classes. So your first thought when you consider such a deficiency will, we hope, be ``what can I do to improve this?''

Similar considerations apply to those parts of the kernel that are implementing design decisions, many of which should be left to the class file but are not in the current system. We realise that in such cases it is much more difficult for you to rectify the problem yourself but it is also the case that making such changes in the kernel would probably be a major project for us; therefore such enhancements will have to wait for LaTeX3.


Writing classes and packages

This section covers some general points concerned with writing LaTeX classes and packages.

  • Old versions

  • Using `docstrip' and `doc'
  • Is it a class or a package?
  • Command names
  • Box commands and colour
  • Defining text and math characters
  • General style
    • Loading other files
    • Make it robust
    • Make it portable
    • Useful hooks


Old versions

If you are upgrading an existing LaTeX 2.09 style file then we recommend freezing the 2.09 version and no longer maintaining it. Experience with the various dialects of LaTeX which existed in the early 1990's suggests that maintaining packages for different versions of LaTeX is almost impossible. It will, of course, be necessary for some organisations to maintain both versions in parallel for some time but this is not essential for those packages and classes supported by individuals: they should support only the new standard LaTeX2e, not obsolete versions of LaTeX.


Using `docstrip' and `doc'

If you are going to write a large class or package for LaTeX then you should consider using the doc software which comes with LaTeX. LaTeX classes and packages written using this can be processed in two ways: they can be run through LaTeX, to produce documentation; and they can be processed with docstrip, to produce the .cls or .sty file.

The doc software can automatically generate indexes of definitions, indexes of command use, and change-log lists. It is very useful for maintaining and documenting large TeX sources.

The documented sources of the LaTeX kernel itself, and of the standard classes, etc, are doc documents; they are in the .dtx files in the distribution. You can, in fact, typeset the source code of the kernel as one long document, complete with index, by running LaTeX on source2e.tex.

For more information on doc and docstrip, consult the files docstrip.dtx, doc.dtx, and The LaTeX Companion. For examples of its use, look at the .dtx files.


Is it a class or a package?

The first thing to do when you want to put some new LaTeX commands in a file is to decide whether it should be a document class or a package. The rule of thumb is:

If the commands could be used with any document class, then make them a package; and if not, then make them a class.

There are two major types of class: those like article, report or letter, which are free-standing; and those which are extensions or variations of other classes--for example, the proc document class, which is built on the article document class.

Thus, a company might have a local ownlet class for printing letters with their own headed note-paper. Such a class would build on top of the existing letter class but it cannot be used with any other document class, so we have ownlet.cls rather than ownlet.sty.

The graphics package, in contrast, provides commands for including images into a LaTeX document. Since these commands can be used with any document class, we have graphics.sty rather than graphics.cls.


Command names

LaTeX has three types of command.

There are the author commands, such as \section, \emph and \times: most of these have short names, all in lower case.

There are also the class and package writer commands: most of these have long mixed-case names such as the following.

   \InputIfFileExists  \RequirePackage  \PassOptionsToClass

Finally, there are the internal commands used in the LaTeX implementation, such as \@tempcnta, \@ifnextchar and \@eha: most of these commands contain @ in their name, which means they cannot be used in documents, only in class and package files.

Unfortunately, for historical reasons the distinction between these commands is often blurred. For example, \hbox is an internal command which should only be used in the LaTeX kernel, whereas \m@ne is the constant -1 and could have been \MinusOne.

However, this rule of thumb is still useful: if a command has @ in its name then it is not part of the supported LaTeX language--and its behaviour may change in future releases! If a command is mixed-case, or is described in LaTeX: A Document Preparation System, then you can rely on future releases of LaTeX2e supporting the command.


Box commands and colour

Even if you do not intend to use colour in your own documents, by taking note of the points in this section you can ensure that your class or package is compatible with the color package. This may benefit people using your class or package who have access to colour printers.

The simplest way to ensure `colour safety' is to always use LaTeX box commands rather than TeX primitives, that is use \sbox rather than \setbox, \mbox rather than \hbox and \parbox or the minipage environment rather than \vbox. The LaTeX box commands have new options which mean that they are now as powerful as the TeX primitives.

As an example of what can go wrong, consider that in {\ttfamily <text>} the font is restored just before the }, whereas in the similar looking construction {\color{green} <text>} the colour is restored just after the final }. Normally this distinction does not matter at all; but consider a primitive TeX box assignment such as:

   \setbox0=\hbox{\color{green} <text>}

Now the colour-restore occurs after the } and so is not stored in the box. Exactly what bad effects this can have depends on how colour is implemented: it can range from getting the wrong colours in the rest of the document, to causing errors in the dvi-driver used to print the document.

Also of interest is the command \normalcolor. This is normally just \relax (i.e., does nothing) but you can use it rather like \normalfont to set regions of the page such as captions or section headings to the `main document colour'.


Defining text and math characters

Because LaTeX2e supports different encodings, definitions of commands for producing symbols, accents, composite glyphs, etc. must be defined using the commands provided for this purpose and described in LaTeX2e Font Selection. This part of the system is still under development so such tasks should be undertaken with great caution.

Also, \DeclareRobustCommand should be used for encoding-independent commands of this type.

Note that it is no longer possible to refer to the math font set-up outside math mode: for example, neither \textfont 1 nor \scriptfont 2 are guaranteed to be defined in other modes.


General style

The new system provides many commands designed to help you produce well-structured class and package files that are both robust and portable. This section outlines some ways to make intelligent use of these.

  • Useful hooks


Loading other files

LaTeX provides these commands:

   \LoadClass        \LoadClassWithOptions
   \RequirePackage   \RequirePackageWithOptions

for using classes or packages inside other classes or packages. We recommend strongly that you use them, rather than the primitive \input command, for a number of reasons.

Files loaded with \input <filename> will not be listed in the \listfiles list.

If a package is always loaded with \RequirePackage... or \usepackage then, even if its loading is requested several times, it will be loaded only once. By contrast, if it is loaded with \input then it can be loaded more than once; such an extra loading may waste time and memory and it may produce strange results.

If a package provides option-processing then, again, strange results are possible if the package is \input rather than loaded by means of \usepackage or \RequirePackage....

If the package foo.sty loads the package baz.sty by use of \input baz.sty then the user will get a warning:

   LaTeX Warning: You have requested package `foo',
                  but the package provides `baz'.

Thus, for several reasons, using \input to load packages is not a good idea.

Unfortunately, if you are upgrading the file myclass.sty to a class file then you have to make sure that any old files which contain \input myclass.sty still work.

This was also true for the standard classes (article, book and report), since a lot of existing LaTeX 2.09 document styles contain \input article.sty. The approach which we use to solve this is to provide minimal files article.sty, book.sty and report.sty, which simply load the appropriate class files.

For example, article.sty contains just the following lines:

   \NeedsTeXFormat{LaTeX2e}
   \@obsoletefile{article.cls}{article.sty}
   \LoadClass{article}

You may wish to do the same or, if you think that it is safe to do so, you may decide to just remove myclass.sty.


Make it robust

We consider it good practice, when writing packages and classes, to use LaTeX commands as much as possible.

Thus, instead of using \def... we recommend using one of \newcommand, \renewcommand or \providecommand; \CheckCommand is also useful. Doing this makes it less likely that you will inadvertently redefine a command, giving unexpected results.

When you define an environment, use \newenvironment or \renewenvironment instead \def\foo{...} and \def\endfoo{...}.

If you need to set or change the value of a <dimen> or <skip> register, use \setlength.

To manipulate boxes, use LaTeX commands such as \sbox, \mbox and \parbox rather than \setbox, \hbox and \vbox.

Use \PackageError, \PackageWarning or \PackageInfo (or the equivalent class commands) rather than \@latexerr, \@warning or \wlog.

It is still possible to declare options by defining \ds@<option> and calling \@options; but we recommend the \DeclareOption and \ProcessOptions commands instead. These are more powerful and use less memory. So rather than using:

   \def\ds@draft{\overfullrule 5pt}
   \@options

you should use:

   \DeclareOption{draft}{\setlength{\overfullrule}{5pt}}
   \ProcessOptions\relax

The advantage of this kind of practice is that your code is more readable and, more important, that it is less likely to break when used with future versions of LaTeX.


Make it portable

It is also sensible to make your files are as portable as possible. To ensure this; they should contain only visible 7-bit text; and the filenames should contain at most eight characters (plus the three letter extension). Also, of course, it must not have the same name as a file in the standard LaTeX distribution, however similar its contents may be to one of these files.

It is also useful if local classes or packages have a common prefix, for example the University of Nowhere classes might begin with unw. This helps to avoid every University having its own thesis class, all called thesis.cls.

If you rely on some features of the LaTeX kernel, or on a package, please specify the release-date you need. For example, the package error commands were introduced in the June 1994 release so, if you use them then you should put:

   \NeedsTeXFormat{LaTeX2e}[1994/06/01]


Useful hooks

Some packages and document styles had to redefine the command \document or \enddocument to achieve their goal. This is no longer necessary. You can now use the `hooks' \AtBeginDocument and \AtEndDocument (see Section 4.6). Again, using these hooks makes it less likely that your code breaks with future versions of LaTeX. It also makes it more likely that your package can work together with someone else's.

However, note that code in the \AtBeginDocument hook is part of the preamble. Thus there are restrictions on what can be put there; in particular, no typesettting can be done.


Identification

The first thing a class or package file does is identify itself. Package files do this as follows:

   \NeedsTeXFormat{LaTeX2e}
   \ProvidesPackage{<package>}[<date> <other information>]

For example:

   \NeedsTeXFormat{LaTeX2e}
   \ProvidesPackage{latexsym}[1994/06/01 Standard LaTeX package]

Class files do this as follows:

   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{<class-name>}[<date> <other information>]

For example:

   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{article}[1994/06/01 Standard LaTeX class]

The <date> should be given in the form `YYYY/MM/DD'. This date is checked whenever a user specifies a date in their \documentclass or \usepackage command. For example, if you wrote:

   \documentclass{article}[1995/12/23]

then users at a different location would get a warning that their copy of article was out of date.

The description of a class is displayed when the class is used. The description of a package is put into the log file. These descriptions are also displayed by the \listfiles command. The phrase Standard LaTeX must not be used in the identification banner of any file other than those in the standard LaTeX distribution.


Using classes and packages

The first major difference between LaTeX 2.09 style files and LaTeX2e packages and classes is that LaTeX2e supports modularity, in the sense of building files from small building-blocks rather than using large single files.

A LaTeX package or class can load a package as follows:

   \RequirePackage[<options>]{<package>}[<date>]

For example:

   \RequirePackage{ifthen}[1994/06/01]

This command has the same syntax as the author command \usepackage. It allows packages or classes to use features provided by other packages. For example, by loading the ifthen package, a package writer can use the `if...then...else...' commands provided by that package.

A LaTeX class can load one other class as follows:

   \LoadClass[<options>]{<class-name>}[<date>]

For example:

   \LoadClass[twocolumn]{article}

This command has the same syntax as the author command \documentclass. It allows classes to be based on the syntax and appearance of another class. For example, by loading the article class, a class writer only has to change the bits of article they don't like, rather than writing a new class from scratch.

The following commands can be used in the common case that you want to simply load a class or package file with exactly those options that are being used by the current class.

   \LoadClassWithOptions{<class-name>}[<date>]
   \RequirePackageWithOptions{<package>}[<date>]

For example:

   \LoadClassWithOptions{article}
   \RequirePackageWithOptions{graphics}[1995/12/01]


Declaring options

The other major difference between LaTeX 2.09 styles and LaTeX2e packages and classes is in option handling. Packages and classes can now declare options and these can be specified by authors; for example, the twocolumn option is declared by the article class.

An option is declared as follows:

   \DeclareOption{<option>}{<code>}

For example, the dvips option (slightly simplified) to the graphics package is implemented as:

This means that when an author writes \usepackage[dvips]{graphics}, the file dvips.def is loaded. As another example, the a4paper option is declared in the article class to set the \paperheight and \paperwidth lengths:

   \DeclareOption{a4paper}{%
      \setlength{\paperheight}{297mm}%
      \setlength{\paperwidth}{210mm}%
   }

Sometimes a user will request an option which the class or package has not explicitly declared. By default this will produce a warning (for classes) or error (for packages); this behaviour can be altered as follows:

   \DeclareOption*{<code>}

For example, to make the package fred produce a warning rather than an error for unknown options, you could specify:

   \DeclareOption*{%
      \PackageWarning{fred}{Unknown option `\CurrentOption'}%
   }

Then, if an author writes \usepackage[foo]{fred}, they will get a warning Package fred Warning: Unknown option `foo'. As another example, the fontenc package tries to load a file <ENC>enc.def whenever the <ENC> option is used. This can be done by writing:

   \DeclareOption*{%
}%
   }

It is possible to pass options on to another package or class, using the command \PassOptionsToPackage or \PassOptionsToClass. For example, to pass every unknown option on to the article class, you can use:

   \DeclareOption*{%
      \PassOptionsToClass{\CurrentOption}{article}%
   }

If you do this then you should make sure you load the class at some later point, otherwise the options will never be processed!

So far, we have explained only how to declare options, not how to execute them. To process the options with which the file was called, you should use:

   \ProcessOptions\relax

This executes the <code> for each option that was both specified and declared (see Section 4.7 for details of how this is done).

For example, if the jane package file contains:

   \DeclareOption{foo}{\typeout{Saw foo.}}
   \DeclareOption{baz}{\typeout{Saw baz.}}
   \DeclareOption*{\typeout{What's \CurrentOption?}}
   \ProcessOptions\relax

and an author writes \usepackage[foo,bar]{jane}, then they will see the messages Saw foo. and What's bar?


A minimal class file

Most of the work of a class or package is in defining new commands, or changing the appearance of documents. This is done in the body of the package, using commands such as \newcommand or \setlength.

LaTeX2e provides several new commands to help class and package writers; these are described in detail in Section 4.

There are three things that every class file must contain: these are a definition of \normalsize and values for \textwidth and \textheight. So a minimal document class file looks like this:

   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{minimal}[1995/10/30 Standard LaTeX minimal class]
   \renewcommand{\normalsize}{\fontsize{10pt}{12pt}\selectfont}
   \setlength{\textwidth}{6.5in}
   \setlength{\textheight}{8in}

However, this class file will not support footnotes, marginals, 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

A company may have its own letter class, for setting letters in the company style. This section shows a simple implementation of such a class, although a real class would need more structure.

The class begins by announcing itself as neplet.cls.

   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{neplet}[1995/04/01 NonExistent Press letter class]

Then this next bit passes any options on to the letter class, which is loaded with the a4paper option.

   \DeclareOption*{\PassOptionsToClass{\CurrentOption}{letter}}
   \ProcessOptions\relax
   \LoadClass[a4paper]{letter}

In order to use the company letter head, it redefines the firstpage page style: this is the page style that is used on the first page of letters.

   \renewcommand{\ps@firstpage}{%
      \renewcommand{\@oddhead}{<letterhead goes here>}%
      \renewcommand{\@oddfoot}{<letterfoot goes here>}%
   }

And that's it!


Example: a newsletter class

A simple newsletter can be typeset with LaTeX, using a variant of the article class. The class begins by announcing itself as smplnews.cls.

   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{smplnews}[1995/04/01 The Simple News newsletter class]

   \newcommand{\headlinecolor}{\normalcolor}

It passes most specified options on to the article class: apart from the onecolumn option, which is switched off, and the green option, which sets the headline in green.

   \DeclareOption{onecolumn}{\OptionNotUsed}
   \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}}

   \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}

   \ProcessOptions\relax

It then loads the class article with the option twocolumn.

   \LoadClass[twocolumn]{article}

Since the newsletter is to be printed in colour, it now loads the color package. The class does not specify a device driver option since this should be specified by the user of the smplnews class.

   \RequirePackage{color}

The class then redefines \maketitle to produce the title in 72pt Helvetica bold oblique, in the appropriate colour.

   \renewcommand{\maketitle}{%
      \twocolumn[%
         \fontsize{72}{80}\fontfamily{phv}\fontseries{b}%
         \fontshape{sl}\selectfont\headlinecolor
         \@title
      ]%
   }

It redefines \section and switches off section numbering.

   \renewcommand{\section}{%
      \@startsection
         {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}%
         {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}%
   }

   \setcounter{secnumdepth}{0}

It also sets the three essential things.

   \renewcommand{\normalsize}{\fontsize{9}{10}\selectfont}
   \setlength{\textwidth}{17.5cm}
   \setlength{\textheight}{25cm}

In practice, a class would need more than this: it would provide commands for issue numbers, authors of articles, page styles and so on; but this skeleton gives a start. The ltnews class file is not much more complex than this one.


Identification

The first group of commands discussed here are those used to identify your class or package file.

\NeedsTeXFormat {<format-name>} [<release-date>]

This command tells TeX that this file should be processed using a format with name <format-name>. You can use the optional argument <release-date> to further specify the earliest release date of the format that is needed. When the release date of the format is older than the one specified a warning will be generated. The standard <format-name> is LaTeX2e. The date, if present, must be in the form YYYY/MM/DD.

Example:

   \NeedsTeXFormat{LaTeX2e}[1994/06/01]

\ProvidesClass {<class-name>} [<release-info>]
\ProvidesPackage {<package-name>} [<release-info>]

This declares that the current file contains the definitions for the document class <class-name> or package <package-name>.

The optional <release-info>, if used, must contain:

  • the release date of this version of the file, in the form YYYY/MM/DD;

  • optionally followed by a space and a short description, possibly including a version number.

The above syntax should be followed exactly so that this information can be used by \LoadClass or \documentclass (for classes) or \RequirePackage or \usepackage (for packages) to test that the release is not too old.

The whole of this <release-info> information is displayed by \listfiles and should therefore not be too long.

Example:

   \ProvidesClass{article}[1994/06/01 v1.0 Standard LaTeX class]
   \ProvidesPackage{ifthen}[1994/06/01 v1.0 Standard LaTeX package]

\ProvidesFile {<file-name>} [<release-info>]

This is similar to the two previous commands except that here the full filename, including the extension, must be given. It is used for declaring any files other than main class and package files.

Example:

   \ProvidesFile{T1enc.def}[1994/06/01 v1.0 Standard LaTeX file]

Note that the phrase Standard LaTeX must not be used in the identification banner of any file other than those in the standard LaTeX distribution.


Loading files

This group of commands can be used to create your own document class or package by building on existing classes or packages.

\RequirePackage [<options-list>] {<package-name>} [<release-info>]
\RequirePackageWithOptions {<package-name>} [<release-info>]

Packages and classes should use these commands to load other packages.

The use of \RequirePackage is the same as the author command \usepackage.

Examples:

   \RequirePackage{ifthen}[1994/06/01]
   \RequirePackageWithOptions{graphics}[1995/12/01]

\LoadClass [<options-list>] {<class-name>} [<release-info>]
\LoadClassWithOptions {<class-name>} [<release-info>]

These commands are for use only in class files, they cannot be used in packages files; they can be used at most once within a class file.

The use of\LoadClass is the same as the use of \documentclass to load a class file.

Examples:

   \LoadClass{article}[1994/06/01]
   \LoadClassWithOptions{article}[1995/12/01]

The two WithOptions versions simply load the class (or package) file with exactly those options that are being used by the current file (class or package). See below, in 4.5, for further discussion of their use.


Option declaration

The following commands deal with the declaration and handling of options to document classes and packages.

There are some commands designed especially for use within the <code> argument of these commands (see below).

\DeclareOption {<option-name>} {<code>}

This makes <option-name> a `declared option' of the class or package in which it is put.

The <code> argument contains the code to be executed if that option is specified for the class or package; it can contain any valid LaTeX2e construct.

Example:

   \DeclareOption{twoside}{\@twosidetrue}

\DeclareOption* {<code>}

This declares the <code> to be executed for every option which is specified for, but otherwise not explicitly declared by, the class or package; this code is called the `default option code' and it can contain any valid LaTeX2e construct.

If a class file contains no \DeclareOption* then, by default, all specified but undeclared options for that class will be silently passed to all packages (as will the specified and declared options for that class).

If a package file contains no \DeclareOption* then, by default, each specified but undeclared option for that package will produce an error.


Commands within option code

These two commands can be used only within the <code> argument of either \DeclareOption or \DeclareOption*. Other commands commonly used within these arguments can be found in the next few subsections.

\CurrentOption

This expands to the name of the current option.

\OptionNotUsed

This causes the current option to be added to the list of `unused options'.

You can now include hash marks (#) within these <code> arguments without special treatment (formerly, it had been necessary to double them).


Moving options around

These two commands are also very useful within the <code> argument of \DeclareOption or \DeclareOption*:

\PassOptionsToPackage {<options-list>} {<package-name>}
\PassOptionsToClass {<options-list>} {<class-name>}

The command \PassOptionsToPackage passes the options in <options-list> to package <package-name>. This means that it adds the <option-list> to the list of options used by any future \RequirePackage or \usepackage command for package <package-name>.

Example:

   \PassOptionsToPackage{foo,bar}{fred}
   \RequirePackage[baz]{fred}

is the same as:

   \RequirePackage[foo,bar,baz]{fred}

Similarly, \PassOptionsToClass may be used in a class file to pass options to another class to be loaded with \LoadClass.

The effects and use of these two commands should be contrasted with those of the following two (documented above, in 4.2):

   \LoadClassWithOptions
   \RequirePackageWithOptions

The command\RequirePackageWithOptions is similar to \RequirePackage, but it always loads the required package with exactly the same option list as that being used by the current class or package, rather than with any option explicitly supplied or passed on by \PassOptionsToPackage.

The main purpose of \LoadClassWithOptions is to allow one class to simply build on another, for example:

  \LoadClassWithOptions{article}

This should be compared with the slightly different construction

  \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
  \ProcessOptions\relax
  \LoadClass{article}

As used above, the effects are more or less the same, but the first is a lot less to type; also the \LoadClassWithOptions method runs slightly quicker.

If, however, the class declares options of its own then the two constructions are different. Compare, for example:

  \DeclareOption{landscape}{\@landscapetrue}
  \ProcessOptions\relax
  \LoadClassWithOptions{article}

with:

  \DeclareOption{landscape}{\@landscapetrue}
  \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
  \ProcessOptions\relax
  \LoadClass{article}

In the first example, the article class will be loaded with option landscape precisely when the current class is called with this option. By contrast, in the second example it will never be called with option landscape as in that case article is passed options only by the default option handler, but this handler is not used for landscape because that option is explicitly declared.


Delaying code

These first two commands are also intended primarily for use within the <code> argument of \DeclareOption or \DeclareOption*.

\AtEndOfClass {<code>}
\AtEndOfPackage {<code>}

These commands declare <code> that is saved away internally and then executed after processing the whole of the current class or package file.

Repeated use of these commands is permitted: the code in the arguments is stored (and later executed) in the order of their declarations.

\AtBeginDocument {<code>}
\AtEndDocument {<code>}

These commands declare <code> to be saved internally and executed while LaTeX is executing \begin{document} or |