Declaring options

The other major difference between L^ATEX 2.09 styles and L^ATEX2_e 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. Note that the name of an option should contain only those characters allowed in a `L^ATEX name'; in particular it must not contain any control sequences.

An option is declared as follows:

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

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

   \DeclareOption{dvips}{\input{dvips.def}}

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*{%
      \input{\CurrentOption enc.def}%
   }

It is possible to pass options on to another package or class, using the command \PassOptionsToPackage or \PassOptionsToClass (note that this is a specialised operation that works only for option names). 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?