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}
¶\ClassWarning{class name}{warning text}
\ClassWarningNoLine{class name}{warning text}
\ClassInfo{class name}{info text}
\ClassInfoNoLine{class name}{info text}
\PackageError{package name}{error text}{help text}
\PackageWarning{package name}{warning text}
\PackageWarningNoLine{package name}{warning text}
\PackageInfo{package 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
:
\protect
mechanism, so they do not incur
the slight loss of performance mentioned above, and
\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:
\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.
\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.