W3cubDocs

Class and package commands

These are the commands designed to help writers of classes or packages.

\AtBeginDvi{specials}

Save in a box register things that are written to the .dvi file at the beginning of the shipout of the first page of the document.

\AtEndOfClass{code}

\AtEndOfPackage{code}

Hook to insert code to be executed when LaTeX finishes processing the current class or package. You can use these hooks multiple times; the code will be executed in the order that you called it. See also \AtBeginDocument.

\CheckCommand{cmd}[num][default]{definition}

\CheckCommand*{cmd}[num][default]{definition}

Like \newcommand (see \newcommand & \renewcommand) but does not define cmd; instead it checks that the current definition of cmd is exactly as given by definition and is or is not long as expected. A long command is a command that accepts \par within an argument. The cmd command is expected to be long with the unstarred version of \CheckCommand. Raises an error when the check fails. This allows you to check before you start redefining cmd yourself that no other package has already redefined this command.

\ClassError{class name}{error text}{help text}

\PackageError{package name}{error text}{help text}

\ClassWarning{class name}{warning text}

\PackageWarning{package name}{warning text}

\ClassWarningNoLine{class name}{warning text}

\PackageWarningNoLine{package name}{warning text}

\ClassInfo{class name}{info text}

\PackageInfo{package name}{info text}

\ClassInfoNoLine{class name}{info text}

\PackageInfoNoLine{package name}{info text}

Produce an error message, or warning or informational messages.

For \ClassError and \PackageError the message is error text, followed by TeX’s ? error prompt. If the user then asks for help by typing h, they see the help text.

The four warning commands are similar except that they write warning text on the screen with no error prompt. The four info commands write info text only in the transcript file. The NoLine versions do not show the number of the line generating the message, while the other versions do show that number.

To format the messages, including the help text: use \protect to stop a command from expanding, get a line break with \MessageBreak, and get a space with \space when a space character does not allow it, like after a command. Note that LaTeX appends a period to the messages.

\CurrentOption

Expands to the name of the currently-being-processed option. Can only be used within the code argument of either \DeclareOption or \DeclareOption*.

\DeclareOption{option}{code}

\DeclareOption*{code}

Make an option available to a user to invoke in their \documentclass command. For example, the smcmemo class could have an option \documentclass[logo]{smcmemo} allowing users to put the institutional logo on the first page. The class file must contain \DeclareOption{logo}{code} (and later, \ProcessOptions).

If you request an option that has not been declared, by default this will produce a warning like Unused global option(s): [badoption]. Change this behavior with the starred version \DeclareOption*{code}. For example, many classes extend an existing class, using a command such as \LoadClass{article}, and for passing extra options to the underlying class use code such as this.

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

Another example is that the class smcmemo may allow users to keep lists of memo recipients in external files. Then the user could invoke \documentclass[math]{smcmemo} and it will read the file math.memo. This code handles the file if it exists and otherwise passes the option to the article class.

\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{%
    \PassOptionsToClass{\CurrentOption}{article}}}

\DeclareRobustCommand{cmd}[num][default]{definition}

\DeclareRobustCommand*{cmd}[num][default]{definition}

Like \newcommand and \newcommand* (see \newcommand & \renewcommand) but these declare a robust command, even if some code within the definition is fragile. (For a discussion of robust and fragile commands see \protect.) Use this command to define new robust commands or to redefine existing commands and make them robust. Unlike \newcommand these do not give an error if macro cmd already exists; instead, a log message is put into the transcript file if a command is redefined.

Commands defined this way are a bit less efficient than those defined using \newcommand so unless the command’s data is fragile and the command is used within a moving argument, use \newcommand.

The etoolbox package offers the commands \newrobustcmd, \newrobustcmd*, as well as the commands \renewrobustcmd, \renewrobustcmd*, and the commands \providerobustcmd, and \providerobustcmd*. These are similar to \newcommand, \newcommand*, \renewcommand, \renewcommand*, \providecommand, and \providecommand*, but define a robust cmd with two advantages as compared to \DeclareRobustCommand:

1. They use the low-level e-TeX protection mechanism rather than the higher level LaTeX \protect mechanism, so they do not incur the slight loss of performance mentioned above, and
2. They make the same distinction between \new…, \renew…, and \provide…, as the standard commands, so they do not just make a log message when you redefine cmd that already exists, in that case you need to use either \renew… or \provide… or you get an error.

\IfFileExists{filename}{true code}{false code}

\InputIfFileExists{filename}{true code}{false code}

Execute true code if LaTeX finds the file file name or false code otherwise. In the first case it executing true code and then inputs the file. Thus the command

\IfFileExists{img.pdf}{%
  \includegraphics{img.pdf}}{\typeout{!! img.pdf not found}

will include the graphic img.pdf if it is found and otherwise give a warning.

This command looks for the file in all search paths that LaTeX uses, not only in the current directory. To look only in the current directory do something like \IfFileExists{./filename}{true code}{false code}. If you ask for a filename without a .tex extension then LaTeX will first look for the file by appending the .tex; for more on how LaTeX handles file extensions see \input.

\LoadClass[options list]{class name}[release date]

\LoadClassWithOptions{class name}[release date]

Load a class, as with \documentclass[options list]{class name}[release info]. An example is \LoadClass[twoside]{article}.

The options list, if present, is a comma-separated list. The release date is optional. If present it must have the form YYYY/MM/DD.

If you request a release date and the date of the package installed on your system is earlier, then you get a warning on the screen and in the log like this.

You have requested, on input line 4, version `2038/01/19' of
document class article, but only version `2014/09/29 v1.4h
Standard LaTeX document class' is available.

The command version \LoadClassWithOptions uses the list of options for the current class. This means it ignores any options passed to it via \PassOptionsToClass. This is a convenience command that lets you build classes on existing ones, such as the standard article class, without having to track which options were passed.

\ExecuteOptions{options-list}

For each option option in the options-list, in order, this command executes the command \ds@option. If this command is not defined then that option is silently ignored.

It can be used to provide a default option list before \ProcessOptions. For example, if in a class file you want the default to be 11pt fonts then you could specify \ExecuteOptions{11pt}\ProcessOptions\relax.

\NeedsTeXFormat{format}[format date]

Specifies the format that this class must be run under. Often issued as the first line of a class file, and most often used as: \NeedsTeXFormat{LaTeX2e}. When a document using that class is processed, the format name given here must match the format that is actually being run (including that the format string is case sensitive). If it does not match then execution stops with an error like ‘This file needs format `LaTeX2e' but this is `xxx'.’

To specify a version of the format that you know to have certain features, include the optional format date on which those features were implemented. If present it must be in the form YYYY/MM/DD. If the format version installed on your system is earlier than format date then you get a warning like this.

You have requested release `2038/01/20' of LaTeX, but only
release `2016/02/01' is available.

\OptionNotUsed

Adds the current option to the list of unused options. Can only be used within the code argument of either \DeclareOption or \DeclareOption*.

\PassOptionsToClass{option list}{class name}

\PassOptionsToPackage{option list}{package name}

Adds the options in the comma-separated list option list to the options used by any future \RequirePackage or \usepackage command for package package name or the class class name.

The reason for these commands is: you may load a package any number of times with no options but if you want options then you may only supply them when you first load the package. Loading a package with options more than once will get you an error like Option clash for package foo. (LaTeX throws an error even if there is no conflict between the options.)

If your own code is bringing in a package twice then you can collapse that to once, for example replacing the two \RequirePackage[landscape]{geometry} and \RequirePackage[margins=1in]{geometry} with the single command \RequirePackage[landscape,margins=1in]{geometry}.

However, imagine that you are loading firstpkg and inside that package it loads secondpkg, and you need the second package to be loaded with option draft. Then before doing the first package you must queue up the options for the second package, like this.

\PassOptionsToPackage{draft}{secondpkg}
\RequirePackage{firstpkg}

(If firstpkg.sty loads an option in conflict with what you want then you may have to alter its source.)

These commands are useful for general users as well as class and package writers. For instance, suppose a user wants to load the graphicx package with the option draft and also wants to use a class foo that loads the graphicx package, but without that option. The user could start their LaTeX file with \PassOptionsToPackage{draft}{graphicx}\documentclass{foo}.

\ProcessOptions

\ProcessOptions*\@options

Execute the code for each option that the user has invoked. Include it in the class file as \ProcessOptions\relax (because of the existence of the starred command).

Options come in two types. Local options have been specified for this particular package in the options argument of \PassOptionsToPackage{options}, \usepackage[options], or \RequirePackage[options]. Global options are those given by the class user in \documentclass[options] (If an option is specified both locally and globally then it is local.)

When \ProcessOptions is called for a package pkg.sty, the following happens:

1. For each option option so far declared with \DeclareOption, it looks to see if that option is either a global or a local option for pkg. If so then it executes the declared code. This is done in the order in which these options were given in pkg.sty.
2. For each remaining local option, it executes the command \ds@option if it has been defined somewhere (other than by a \DeclareOption); otherwise, it executes the default option code given in \DeclareOption*. If no default option code has been declared then it gives an error message. This is done in the order in which these options were specified.

When \ProcessOptions is called for a class it works in the same way except that all options are local, and the default code for \DeclareOption* is \OptionNotUsed rather than an error.

The starred version \ProcessOptions* executes the options in the order specified in the calling commands, rather than in the order of declaration in the class or package. For a package this means that the global options are processed first.

\ProvidesClass{class name}[release date brief additional information]

\ProvidesClass{class name}[release date]

\ProvidesPackage{package name}[release date brief additional information]

\ProvidesPackage{package name}[release date]

Identifies the class or package, printing a message to the screen and the log file.

When you load a class or package, for example with \documentclass{smcmemo} or \usepackage{test}, LaTeX inputs a file. If the name of the file does not match the class or package name declared in it then you get a warning. Thus, if you invoke \documentclass{smcmemo}, and the file smcmemo.cls has the statement \ProvidesClass{xxx} then you get a warning like You have requested document class `smcmemo', but the document class provides 'xxx'. This warning does not prevent LaTeX from processing the rest of the class file normally.

If you include the optional argument then you must include a date, before any spaces, of the form YYYY/MM/DD. The rest of the optional argument is free-form, although it traditionally identifies the class, and is written to the screen during compilation and to the log file. Thus, if your file smcmemo.cls contains the line \ProvidesClass{smcmemo}[2008/06/01 v1.0 SMC memo class] and your document’s first line is \documentclass{smcmemo} then you will see Document Class: smcmemo 2008/06/01 v1.0 SMC memo class.

The date in the optional argument allows class and package users to ask to be warned if the version of the class or package is earlier than release date. For instance, a user could enter \documentclass{smcmemo}[2018/10/12] or \usepackage{foo}[[2017/07/07]] to require a class or package with certain features by specifying that it must be released no earlier than the given date. (Although, in practice package users only rarely include a date, and class users almost never do.)

\ProvidesFile{filename}[additional information]

Declare a file other than the main class and package files, such as configuration files or font definition files. Put this command in that file and you get in the log a string like File: test.config 2017/10/12 config file for test.cls for filename equal to ‘test.config’ and additional information equal to ‘2017/10/12 config file for test.cls’.

\RequirePackage[option list]{package name}[release date]

\RequirePackageWithOptions{package name}[release date]

Load a package, like the command \usepackage (see Additional packages). The LaTeX development team strongly recommends use of these commands over Plain TeX’s \input; see the Class Guide. An example is \RequirePackage[landscape,margin=1in]{geometry}.

The option list, if present, is a comma-separated list. The release date, if present, must have the form YYYY/MM/DD. If the release date of the package as installed on your system is earlier than release date then you get a warning like You have requested, on input line 9, version `2017/07/03' of package jhtest, but only version `2000/01/01' is available.

The \RequirePackageWithOptions version uses the list of options for the current class. This means it ignores any options passed to it via \PassOptionsToClass. This is a convenience command to allow easily building classes on existing ones without having to track which options were passed.

The difference between \usepackage and \RequirePackage is small. The \usepackage command is intended for the document file while \RequirePackage is intended for package and class files. Thus, using \usepackage before the \documentclass command causes LaTeX to give error like \usepackage before \documentclass, but you can use \RequirePackage there.