path: root/macros/latex-dev/base/clsguide.tex

% \iffalse meta-comment
%
% Copyright (C) 2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
% This file is part of the LaTeX base system.
% -------------------------------------------
%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%    http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008 or later.
%
% This file has the LPPL maintenance status "maintained".
%
% The list of all files belonging to the LaTeX base distribution is
% given in the file `manifest.txt'. See also `legal.txt' for additional
% information.
%
% The list of derived (unpacked) files belonging to the distribution
% and covered by LPPL is defined by the unpacking scripts (with
% extension .ins) which are part of the distribution.
%
% \fi
% Filename: clsguide.tex

\documentclass{ltxguide}

\usepackage[T1]{fontenc}  % needed for \textbackslash in tt
\usepackage{csquotes}

\title{\LaTeX\ for package and class authors --- current version}
\author{\copyright~Copyright 2023, \LaTeX\ Project Team.\\
   All rights reserved.%
   \footnote{This file may distributed and/or modified under the
     conditions of the \LaTeX{} Project Public License, either version 1.3c
     of this license or (at your option) any later version. See the source
    \texttt{clsguide.tex} for full details.}%
}

\date{2023-10-24}

\NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
\NewDocumentCommand\marg{m}{\arg{#1}}
\NewDocumentCommand\meta{m}{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}}
\NewDocumentCommand\pkg{m}{\textsf{#1}}
\NewDocumentCommand\text{m}{\ifmmode\mbox{#1}\else#1\fi}
% Fix a 'feature'
\makeatletter
\renewcommand \verbatim@font {\normalfont \ttfamily}
\makeatother
\providecommand\url[1]{\texttt{#1}}

\begin{document}

\maketitle

\tableofcontents

\section{Introduction}

\LaTeXe{} was released in 1994 and added a number of then-new concepts to
\LaTeX{}. For package and class authors, these are described in
\texttt{clsguide-historic}, which has largely remained unchanged. Since then,
the \LaTeX{} team have worked on a number of ideas, firstly a programming
language for \LaTeX{} (L3 programming layer) and then a range of tools for
authors which build on that language. Here, we describe the current, stable set
of tools provided by the \LaTeX{} kernel for package and class developers. We
assume familiarity with general \LaTeX{} usage as a document author, and that
the material here is read in conjunction with \texttt{usrguide}, which provides
information for general \LaTeX{} users on up-to-date approaches to creating
commands, etc.

\section{Writing classes and packages}
\label{Sec:writing}

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

\subsection{Is it a class or a package?}
\label{Sec:classorpkg}

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 \emph{document class} or a
\emph{package}.  The rule of thumb is:
\begin{quote}
  If the commands could be used with any document class, then make
  them a package; and if not, then make them a class.
\end{quote}

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|.

\subsection{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|.  Typesetting these documents uses the
class file |ltxdoc.cls|.

For more information on |doc| and |docstrip|, consult the files
|docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}.  For examples of its
use, look at the |.dtx| files.

\subsection{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.
\begin{itemize}
\item
  However misguided, the current behavior is clearly what was
  intended when these classes were designed.
\item
  It is not good practice to change such aspects of `standard classes'
  because many people will be relying on them.
\end{itemize}

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?''

\subsection{Command names}

Prior to the introduction of the L3~programming layer described in the next
section, \LaTeX{} had 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.
\begin{verbatim}
   \InputIfFileExists  \RequirePackage  \PassOptionsToClass
\end{verbatim}

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 behavior may change in future releases!  If a command is
mixed-case, or is described in \emph{\LaTeXbook}, then you can rely on
future releases of \LaTeX{} supporting the command.

\subsection{Programming support}

As noted in the introduction, the \LaTeX{} kernel today loads dedicated support
from programming, here referred to as the L3 programming layer but also often
called \pkg{expl3}. Details of the general approach taken by the L3
programming layer are given in the document \texttt{expl3}, while a reference
for all current code interfaces is available as \texttt{interface3}. This layer
contains two types of command: a documented set of commands making up the API
and a large number of private internal commands. The latter all start with two
underscores and should not be used outside of the code module which defines
them. This more structured approach means that using the L3 programming layer
does not suffer from the somewhat fluid situation mentioned above with
`\texttt{@} commands'.

We do not cover the detail of using the L3 programming layer here. A good
introduction to the approach is provided at
\url{https://www.alanshawn.com/latex3-tutorial/}.

\subsection{Box commands and color}
\label{Sec:color}

Even if you do not intend to use color 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 and wish to use color.

The simplest way to ensure `color 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 \emph{before} the |}|, whereas in the similar looking
construction |{\color{green} <text>}| the color is restored just \emph{after}
the final |}|. Normally this distinction does not matter at all; but consider a
primitive \TeX{} box assignment such as:
\begin{verbatim}
   \setbox0=\hbox{\color{green} <text>}
\end{verbatim}
Now the color-restore occurs after the |}| and so is \emph{not} stored in the
box. Exactly what bad effects this can have depends on how color is
implemented: it can range from getting the wrong colors 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
color'.

\subsection{General style}
\label{Sec:general}

\LaTeX{} 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.

\subsubsection{Loading other files}
\label{Sec:loading}

\LaTeX{} provides these commands:
\begin{verbatim}
   \LoadClass        \LoadClassWithOptions
   \RequirePackage   \RequirePackageWithOptions
\end{verbatim}
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:
\begin{verbatim}
   LaTeX Warning: You have requested package `foo',
                  but the package provides `baz'.
\end{verbatim}
Thus, for several reasons, using |\input| to load packages is not a good idea.

For example, |article.sty| contains just the following lines:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \@obsoletefile{article.cls}{article.sty}
   \LoadClass{article}
\end{verbatim}
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|.

\subsubsection{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| for programming and for defining document
interfaces |\NewDocumentCommand|, etc. (see \texttt{usrguide} for details of
these commands).

When you define an environment, use |\NewDocumentEnvironment|, etc., (or
|\newenvironment|, etc., for simple cases) instead of using |\def\foo{...}| and
|\def\endfoo{...}|.

If you need to set or change the value of a \m{dimen} or \m{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|.

The advantage of this kind of practice is that your code is more readable and
accessible to other experienced \LaTeX{} programmers.

\subsubsection{Make it portable}

It is also sensible to make your files are as portable as possible. To ensure
this, files 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 still lower risk to stick to file names which use only the ASCII range:
whilst \LaTeX{} works natively with UTF-8, the same cannot be said with
certainty for all tools. For the same reason, avoid spaces in file names.

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 2022 release so, if you use
them then you should put:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}[2022-06-01]
\end{verbatim}

\subsubsection{Useful hooks}

It is sometimes necessary for a package to arrange for code to be
executed at the start or end of the preamble, at the end of the document
or at the start of every use of an environment. This can be carried
out by using hooks. As a document author, you will likely be familiar with
|\AtBeginDocument|, a wrapper around the more powerful command |\AddToHook|.
The \LaTeX{} kernel provides a large number of dedicated hooks (applying in
a pre-defined location) and generic hooks (applying to arbitrary commands):
the interface for using these is described in \texttt{lthooks} . There are
also hooks to apply to files, described in \texttt{ltfilehooks}.

\section{The structure of a class or package}
\label{Sec:structure}

The outline of a class or package file is:
\begin{description}
\item[Identification] The file says that it is a \LaTeXe{} package or
   class, and gives a short description of itself.
\item[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.
\item[Options] The file declares and processes its options.
\item[More declarations] This is where the file does most of its work:
   declaring new variables, commands and fonts; and loading other files.
\end{description}

\subsection{Identification}

The first thing a class or package file does is identify itself.
Package files do this as follows:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesPackage{<package>}[<date> <other information>]
\end{verbatim}
For example:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesPackage{latexsym}[1998-08-17 Standard LaTeX package]
\end{verbatim}
Class files do this as follows:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{<class-name>}[<date> <other information>]
\end{verbatim}
For example:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{article}[2022-06-01 Standard LaTeX class]
\end{verbatim}
The \m{date} should be given in the form `\textsc{yyyy-mm-dd}' and must be
present if the optional argument is used (this is also true for the
|\NeedsTeXFormat| command). Any derivation from this syntax will result in
low-level \TeX{} errors---the commands expect a valid syntax to speed up the
daily usage of the package or class and make no provision for the case that the
developer made a mistake!

This date is checked whenever a user specifies a date in their |\documentclass|
or |\usepackage| command. For example, if you wrote:
\begin{verbatim}
   \documentclass{article}[2022-06-01]
\end{verbatim}
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 \texttt{Standard LaTeX} \textbf{must not}
be used in the identification banner of any file other than those in the
standard \LaTeX{} distribution.

\subsection{Using classes and packages}

A \LaTeX{} package or class can load a package as follows:
\begin{verbatim}
   \RequirePackage[<options>]{<package>}[<date>]
\end{verbatim}
For example:
\begin{verbatim}
   \RequirePackage{ifthen}[2022-06-01]
\end{verbatim}
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\dots then\dots
else\dots' commands provided by that package.

A \LaTeX{} class can load one other class as follows:
\begin{verbatim}
   \LoadClass[<options>]{<class-name>}[<date>]
\end{verbatim}
For example:
\begin{verbatim}
   \LoadClass[twocolumn]{article}
\end{verbatim}
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.
\begin{verbatim}
   \LoadClassWithOptions{<class-name>}[<date>]
   \RequirePackageWithOptions{<package>}[<date>]
\end{verbatim}
For example:
\begin{verbatim}
   \LoadClassWithOptions{article}
   \RequirePackageWithOptions{graphics}[1995/12/01]
\end{verbatim}

\subsection{Declaring options}

Packages and classes can 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
`\LaTeX{} name'; in particular it must not contain any control sequences.

\LaTeX{} supports two methods for creating options: a key--value system and a
`simple text' approach. The key--value system is recommended for new classes
and packages, and is more flexible in handling of option classes than the
simple text approach. Both option methods use the same basic structure within
the \LaTeX{} source: declaration of options first then processing options in a
second step. Both also allow options to be passed on to other packages or an
underlying class. As the `classical' simple text approach is conceptually more
straight-forward to illustrate, it is used here to show the general structure:
see Section~\ref{Sec:opt:keyval} for full details of the key--value approach.

An option is declared as follows:
\begin{verbatim}
   \DeclareOption{<option>}{<code>}
\end{verbatim}
For example, the |dvips| option (slightly simplified)
to the |graphics| package is implemented as:
\begin{verbatim}
   \DeclareOption{dvips}{\input{dvips.def}}
\end{verbatim}
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:
\begin{verbatim}
   \DeclareOption{a4paper}{%
      \setlength{\paperheight}{297mm}%
      \setlength{\paperwidth}{210mm}%
   }
\end{verbatim}
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 behavior can be altered as follows:
\begin{verbatim}
   \DeclareOption*{<code>}
\end{verbatim}
For example, to make the package |fred| produce a warning rather than an error
for unknown options, you could specify:
\begin{verbatim}
   \DeclareOption*{%
      \PackageWarning{fred}{Unknown option `\CurrentOption'}%
   }
\end{verbatim}
Then, if an author writes |\usepackage[foo]{fred}|, they will get a warning
\texttt{Package fred Warning: Unknown option `foo'.} As another example, the
|fontenc| package tries to load a file |<ENC>enc.def| whenever the \m{ENC}
option is used. This can be done by writing:
\begin{verbatim}
   \DeclareOption*{%
      \input{\CurrentOption enc.def}%
   }
\end{verbatim}

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): see
Section~\ref{Sec:opmove}. For example, to pass every unknown option on to the
|article| class, you can use:
\begin{verbatim}
   \DeclareOption*{%
      \PassOptionsToClass{\CurrentOption}{article}%
   }
\end{verbatim}
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:
\begin{verbatim}
   \ProcessOptions\relax
\end{verbatim}
This executes the \m{code} for each option that was both specified and declared
(see Section~\ref{Sec:commands.options} for details of how this is done).

For example, if the |jane| package file contains:
\begin{verbatim}
   \DeclareOption{foo}{\typeout{Saw foo.}}
   \DeclareOption{baz}{\typeout{Saw baz.}}
   \DeclareOption*{\typeout{What's \CurrentOption?}}
   \ProcessOptions\relax
\end{verbatim}
and an author writes |\usepackage[foo,bar]{jane}|, then they will see the
messages \texttt{Saw foo.} and \texttt{What's bar?}

\subsection{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|.

There are four things that every class file \emph{must} contain: these
are a definition of |\normalsize|, values for |\textwidth| and
|\textheight| and a specification for page-numbering.  So a minimal
document class file\footnote {This class is now in the standard
distribution, as \texttt{minimal.cls}.} looks like this:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{minimal}[2022-06-01 Standard LaTeX minimal class]
   \renewcommand{\normalsize}{\fontsize{10pt}{12pt}\selectfont}
   \setlength{\textwidth}{6.5in}
   \setlength{\textheight}{8in}
   \pagenumbering{arabic}       % needed even though this class will
                                % not show page numbers
\end{verbatim}
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!

\subsection{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|.
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{neplet}[2022-06-01 NonExistent Press letter class]
\end{verbatim}
Then this next bit passes any options on to the |letter| class, which is loaded
with the |a4paper| option.
\begin{verbatim}
   \DeclareOption*{\PassOptionsToClass{\CurrentOption}{letter}}
   \ProcessOptions\relax
   \LoadClass[a4paper]{letter}
\end{verbatim}
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.
\begin{verbatim}
   \renewcommand{\ps@firstpage}{%
      \renewcommand{\@oddhead}{<letterhead goes here>}%
      \renewcommand{\@oddfoot}{<letterfoot goes here>}%
   }
\end{verbatim}
And that's it!

\subsection{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|.
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}
   \ProvidesClass{smplnews}[2022-06-01 The Simple News newsletter class]

   \newcommand{\headlinecolor}{\normalcolor}
\end{verbatim}
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.
\begin{verbatim}
   \DeclareOption{onecolumn}{\OptionNotUsed}
   \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}}

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

   \ProcessOptions\relax
\end{verbatim}
It then loads the class |article| with the option |twocolumn|.
\begin{verbatim}
   \LoadClass[twocolumn]{article}
\end{verbatim}
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.
\begin{verbatim}
   \RequirePackage{color}
\end{verbatim}
The class then redefines |\maketitle| to produce the title in 72\,pt Helvetica
bold oblique, in the appropriate colour.
\begin{verbatim}
   \renewcommand{\maketitle}{%
      \twocolumn[%
         \fontsize{72}{80}\fontfamily{phv}\fontseries{b}%
         \fontshape{sl}\selectfont\headlinecolor
         \@title
      ]%
   }
\end{verbatim}
It redefines |\section| and switches off section numbering.
\begin{verbatim}
   \renewcommand{\section}{%
      \@startsection
         {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}%
         {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}%
   }

   \setcounter{secnumdepth}{0}
\end{verbatim}
It also sets the three essential things.
\begin{verbatim}
   \renewcommand{\normalsize}{\fontsize{9}{10}\selectfont}
   \setlength{\textwidth}{17.5cm}
   \setlength{\textheight}{25cm}
\end{verbatim}
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.

\section{Commands for class and package writers}
\label{Sec:commands}

This section describes briefly each of the commands for class and package
writers. To find out about other aspects of the system,
you should also read \emph{\LaTeXbook}, \emph{\LaTeXcomp} and
\emph{\usrguide}.

\subsection{Identification}

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

\begin{decl}
|\NeedsTeXFormat| \arg{format-name} \oarg{release-date}
\end{decl}
This command tells \TeX{} that this file should be processed using a format
with name \m{format-name}. You can use the optional argument \m{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 \m{format-name} is \texttt{LaTeX2e}. The date, if
present, must be in the form \textsc{yyyy-mm-dd}.

Example:
\begin{verbatim}
   \NeedsTeXFormat{LaTeX2e}[2022-06-01]
\end{verbatim}
People often don't know what date to put here. For the kernel, you can find out
the right one by consulting |changes.txt| and select the release date of a new
feature you are interested in. This is slightly different for packages as they
are released throughout the year: you will need to consult their change
history.

\begin{decl}
|\ProvidesClass| \arg{class-name} \oarg{release-info} \\
|\ProvidesPackage| \arg{package-name} \oarg{release-info}
\end{decl}
This declares that the current file contains the definitions for the document
class \m{class-name} or package \m{package-name}.

The optional \m{release-info}, if used, must contain:
\begin{itemize}
  \item the release date of this version of the file, in the form
    \textsc{yyyy-mm-dd};
\item optionally followed by a space and a short description, possibly
  including a version number.
\end{itemize}
The above syntax must 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 \m{release-info} information is displayed by |\listfiles| and
should therefore not be too long.

Example:
\begin{verbatim}
   \ProvidesClass{article}[2022-06-01 v1.0 Standard LaTeX class]
   \ProvidesPackage{ifthen}[2022-06-01 v1.0 Standard LaTeX package]
\end{verbatim}

\begin{decl}
  |\ProvidesFile| \arg{file-name} \oarg{release-info}
\end{decl}
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:
\begin{verbatim}
   \ProvidesFile{T1enc.def}[2022-06-01 v1.0 Standard LaTeX file]
\end{verbatim}

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

\subsection{Loading files}
\label{Sec:loadf}

This group of commands can be used to create your own document class or package
by building on existing classes or packages.
\begin{decl}
  |\RequirePackage| \oarg{options-list} \arg{package-name}
     \oarg{release-info}\\
  |\RequirePackageWithOptions| \arg{package-name}
     \oarg{release-info}
\end{decl}
Packages and classes should use these commands to load other packages.

The use of |\RequirePackage| is the same as the author command |\usepackage|.
Examples:
\begin{verbatim}
   \RequirePackage{ifthen}[2022-06-01]
   \RequirePackageWithOptions{graphics}[2022-06-01]
\end{verbatim}

\begin{decl}
  |\LoadClass| \oarg{options-list} \arg{class-name}
     \oarg{release-info}\\
  |\LoadClassWithOptions| \arg{class-name}
     \oarg{release-info}
\end{decl}
These commands are for use \emph{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:
\begin{verbatim}
   \LoadClass{article}[2022-06-01]
   \LoadClassWithOptions{article}[2022-06-01]
\end{verbatim}

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 \ref{Sec:opmove}, for further discussion of their use.

\subsection{Delaying code}
\label{Sec:delays}

As noted earlier, a sophisticated hook system is available and described in
\texttt{lthooks}. Here, we document a small set of convenient short names for
common hooks.

These first two commands are also intended primarily for use within the
\m{code} argument of |\DeclareOption| or |\DeclareOption*|.

\begin{decl}
  |\AtEndOfClass| \arg{code}\\
  |\AtEndOfPackage| \arg{code}
\end{decl}
These commands declare \m{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.

\begin{decl}
  |\AtBeginDocument| \arg{code}\\
  |\AtEndDocument| \arg{code}
\end{decl}
These commands declare \m{code} to be saved internally and executed while
\LaTeX{} is executing |\begin{document}| or |\end{document}|.

The \m{code} specified in the argument to |\AtBeginDocument| is executed near
the end of the |\begin{document}| code, \emph{after} the font selection tables
have been set up. It is therefore a useful place to put code which needs to be
executed after everything has been prepared for typesetting and when the normal
font for the document is the current font.

The |\AtBeginDocument| hook should not be used for code that does any
typesetting since the typeset result would be unpredictable.

The \m{code} specified in the argument to |\AtEndDocument| is executed at the
beginning of the |\end{document}| code, \emph{before} the final page is
finished and before any leftover floating environments are processed. If some
of the \m{code} is to be executed after these two processes, you should include
a |\clearpage| at the appropriate point in \m{code}.

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

\subsection{Creating and using keyval options}
\label{Sec:opt:keyval}

As with any key--value input, using key--value pairs as package or class
options has two parts: creating the key options and setting (using) them.
Options created in this way \emph{may} be used after package loading as general
key--value settings: this will depend on the nature of the underlying code.

\begin{decl}
  |\DeclareKeys| \oarg{family} \arg{declarations}
\end{decl}
This command creates a series of options from a comma-separated
\m{declarations} list. Each entry in this list is a key--value pair, with the
\m{key} having one or more \m{properties}. A small number of `basic'
\m{properties} are described below. The full range of properties, provided by
\texttt{l3keys}, can also be used for more powerful processing. See
\texttt{interface3} for the full details.

The basic properties provided here are
\begin{itemize}
  \item \texttt{.code} --- execute arbitrary code
  \item \texttt{.if} --- sets a \TeX{} |\if...| switch
  \item \texttt{.ifnot} --- sets an inverted \TeX{} |\if...| switch
  \item \texttt{.store} --- stores a value in a macro
  \item \texttt{.usage} -- defines whether the option can be given only
    when loading (\texttt{load}), in the preamble (\texttt{preamble}) or
    has no limitation on scope (\texttt{general})
\end{itemize}
The part of the \meta{key} before the \m{property} is the \m{name}, with the
\m{value} working with the \m{property} to define the behavior of the option.

For example, with
\begin{verbatim}
\DeclareKeys[mypkg]
 {
   draft.if          = @mypkg@draft      ,
   draft.usage       = preamble          ,
   name.store        = \@mypkg@name      ,
   name.usage        = load              ,
   second-name.store = \@mypkg@other@name
 }
\end{verbatim}
three options would be created. The option \texttt{draft} can be given anywhere
in the preamble, and will set a switch called |\if@mypkg@draft|. The option
\texttt{name} can only be given during package loading, and will save whatever
value it is given in |\@mypkg@name|. Finally, the option \texttt{second-name}
can be given anywhere, and will save its value in |\@mypkg@other@name|.

Keys created \emph{before} the use of |\ProcessKeyOptions| act as package
options.

\begin{decl}
  |\DeclareUnknownKeyHandler| \oarg{family} \arg{code}
\end{decl}
The command |\DeclareUnknownKeyHandler| may be used to define the behavior when
an undefined key is encountered. The \m{code} will receive the unknown key name
as |#1| and the value as |#2|. These can then be processed as appropriate,
e.g.~by forwarding to another package. The entire option is available as
\cs{CurrentOption}, should it be necessary to pass on options which may or
may not contain an |=|~sign. For example, this may be used to pass an
unknown option on to a non-keyval class such as \pkg{article}:
\begin{verbatim}
\DeclareUnknownKeyHandler{%
  \PassOptionsToClass{\CurrentOption}{article}
}
\end{verbatim}

\begin{decl}
  |\ProcessKeyOptions| \oarg{family}
\end{decl}
The |\ProcessKeyOptions| function is used to check the current option list
against the keys defined for \m{family}. Global (class) options and local
(package) options are checked when this function is called in a package.
The command will process \emph{all} options given the the current
package or class: there is no need to also apply \cs{ProcessOptions}.

\begin{decl}
  |\SetKeys| \oarg{family} \arg{keyvals}
\end{decl}
Sets (applies) the explicit list of \m{keyvals} for the \m{family}: if the
latter is not given, the value of |\@currname| is used. This command may be used
within a package to set options before or after using |\ProcessKeyOptions|.

\subsection{Passing options around}
\label{Sec:opmove}

These two commands are also very useful within the \m{code} argument of
options.
\begin{decl}
  |\PassOptionsToPackage| \arg{options-list} \arg{package-name}\\
  |\PassOptionsToClass| \arg{options-list} \arg{class-name}
\end{decl}
The command |\PassOptionsToPackage| passes the option names in \m{options-list}
to package \m{package-name}. This means that it adds the \m{option-list} to the
list of options used by any future |\RequirePackage| or |\usepackage| command
for package \m{package-name}.

Example:
\begin{verbatim}
   \PassOptionsToPackage{foo,bar}{fred}
   \RequirePackage[baz]{fred}
\end{verbatim}
is the same as:
\begin{verbatim}
   \RequirePackage[foo,bar,baz]{fred}
\end{verbatim}

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 \ref{Sec:loadf}):
\begin{verbatim}
   \LoadClassWithOptions
   \RequirePackageWithOptions
\end{verbatim}
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:
\begin{verbatim}
  \LoadClassWithOptions{article}
\end{verbatim}
This should be compared with the slightly different construction
\begin{verbatim}
  \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
  \ProcessOptions\relax
  \LoadClass{article}
\end{verbatim}
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:
\begin{verbatim}
  \DeclareOption{landscape}{\@landscapetrue}
  \ProcessOptions\relax
  \LoadClassWithOptions{article}
\end{verbatim}
with:
\begin{verbatim}
  \DeclareOption{landscape}{\@landscapetrue}
  \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
  \ProcessOptions\relax
  \LoadClass{article}
\end{verbatim}
In the first example, the \textsf{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 \textsf{article} is passed options only by the default option
handler, but this handler is not used for |landscape| because that option is
explicitly declared.

\subsection{Safe file commands}

These commands deal with file input; they ensure that the non-existence of a
requested file can be handled in a user-friendly way.

\begin{decl}
|\IfFileExists| \arg{file-name} \arg{true} \arg{false}
\end{decl}
If the file exists then the code specified in \m{true} is executed.

If the file does not exist then the code specified in \m{false} is executed.

This command does \emph{not} input the file.

\begin{decl}
  |\InputIfFileExists| \arg{file-name} \arg{true} \arg{false}
\end{decl}
This inputs the file \m{file-name} if it exists and, immediately before the
input, the code specified in \m{true} is executed.

If the file does not exist then the code specified in \m{false} is executed.

It is implemented using |\IfFileExists|.

\subsection{Reporting errors, etc}

These commands should be used by third party classes and packages to report
errors, or to provide information to authors.

\begin{decl}
  |\ClassError| \arg{class-name} \arg{error-text} \arg{help-text}\\
  |\PackageError| \arg{package-name} \arg{error-text} \arg{help-text}
\end{decl}
These produce an error message. The \m{error-text} is displayed and the |?|
error prompt is shown. If the user types |h|, they will be shown the
\m{help-text}.

Within the \m{error-text} and \m{help-text}: |\protect| can be used to stop a
command from expanding; |\MessageBreak| causes a line-break; and |\space|
prints a space.

Note that the \m{error-text} will have a full stop added to it, so do not put
one into the argument.

For example:
\begin{verbatim}
   \newcommand{\foo}{FOO}
   \PackageError{ethel}{%
      Your hovercraft is full of eels,\MessageBreak
      and \protect\foo\space is \foo
   }{%
      Oh dear! Something's gone wrong.\MessageBreak
      \space \space Try typing \space <<return>>
      \space to proceed, ignoring \protect\foo.
   }
\end{verbatim}
produces this display:
\begin{verbatim}
   ! Package ethel Error: Your hovercraft is full of eels,
   (ethel)                and \foo is FOO.

   See the ethel package documentation for explanation.
\end{verbatim}
If the user types |h|, this will be shown:
\begin{verbatim}
   Oh dear! Something's gone wrong.
     Try typing  <<return>>  to proceed, ignoring \foo.
\end{verbatim}

\begin{decl}
  |\ClassWarning| \arg{class-name} \arg{warning-text}\\
  |\PackageWarning| \arg{package-name} \arg{warning-text}\\
  |\ClassWarningNoLine| \arg{class-name} \arg{warning-text}\\
  |\PackageWarningNoLine| \arg{package-name} \arg{warning-text}\\
  |\ClassInfo| \arg{class-name} \arg{info-text}\\
  |\PackageInfo| \arg{package-name} \arg{info-text}
\end{decl}
The four |Warning| commands are similar to the error commands, except that they
produce only a warning on the screen, with no error prompt.

The first two, |Warning| versions, also show the line number where the warning
occurred, whilst the second two, |WarningNoLine| versions, do not.

The two |Info| commands are similar except that they log the information only
in the transcript file, including the line number. There are no |NoLine|
versions of these two.

Within the \m{warning-text} and \m{info-text}: |\protect| can be used to stop a
command from expanding; |\MessageBreak| causes a line-break; and |\space|
prints a space. Also, these should not end with a full stop as one is
automatically added.

\section{Miscellaneous commands, etc.}
\label{Sec:commands.misc}

\subsection{Layout parameters}

\begin{decl}
|\paperheight|\\
|\paperwidth|
\end{decl}
These two parameters are usually set by the class to be the size of the paper
being used. This should be actual paper size, unlike |\textwidth| and
|\textheight| which are the size of the main text body within the margins.

\subsection{Case changing}
\label{sec:case}

\begin{decl}
  |\MakeUppercase| \arg{text} \\
  |\MakeLowercase| \arg{text} \\
  |\MakeTitlecase| \arg{text}
\end{decl}

As described in \texttt{usrguide}, case changing for text should be carried out
using the commands |\MakeUppercase|, |\MakeLowercase| and
|\MakeTitlecase|. If you need to change the case of programmatic material, the
team strongly suggest using the L3 programming layer commands in the
\texttt{str} module. If you do not wish to do this, you should use the \TeX{}
|\uppercase| and |\lowercase| primitives \emph{in this situation only}.

\subsection{Better user-defined math display environments}

\begin{decl}
  |\ignorespacesafterend|
\end{decl}

Suppose that you want to define an environment for displaying text that is
numbered as an equation. A straightforward way to do this is as follows:
\begin{verbatim}
  \newenvironment{texteqn}
    {\begin{equation}
       \begin{minipage}{0.9\linewidth}}
      {\end{minipage}
     \end{equation}}
\end{verbatim}
However, if you have tried this then you will probably have noticed that it
does not work perfectly when used in the middle of a paragraph because an
inter-word space appears at the beginning of the first line after the
environment.

You can avoid this problem using |\ignorespacesafterend|; it should be
inserted as shown here:
\begin{verbatim}
  \newenvironment{texteqn}
    {\begin{equation}
       \begin{minipage}{0.9\linewidth}}
      {\end{minipage}
     \end{equation}
     \ignorespacesafterend}
\end{verbatim}

This command may also have other uses.

\subsection{Normalising spacing}

\begin{decl}
  |\normalsfcodes|
\end{decl}

This command should be used to restore the normal settings of the
parameters that affect spacing between words, sentences, etc.

An important use of this feature is to correct a problem, reported by Donald
Arseneau, that punctuation in page headers has always (in all known \TeX{}
formats) been potentially wrong whenever a page break happens while a local
setting of the space codes is in effect. These space codes are changed by, for
example, the command \verb|\frenchspacing|) and the \textsf{verbatim}
environment.

It is normally given the correct definition automatically in |\begin{document}|
and so need not be explicitly set; however, if it is explicitly made non-empty
in a class file then automatic default setting will be over-ridden.

\subsection{Querying localisation}

Localisation information is needed to customise a range of outputs. The
\LaTeX{} kernel does not itself manage localisation, which is well-served by
the bundles \pkg{babel} and \pkg{polyglossia}. To allow the kernel and other
packages to access the current localisation information provided by \pkg{babel}
or \pkg{polyglossia}, the command \cs{BCPdata} is defined by the kernel. The
initial kernel definition expands to tag parts for \texttt{en-US}, as the
kernel does not track localisation but does start out with a broadly US~English
setup. However, if \pkg{babel} or \pkg{polyglossia} are loaded, it is redefined
expand to the BCP-47 information from the appropriate package. The supported
arguments are the BCP-47 tag breakdowns:
\begin{itemize}
  \item \texttt{tag} The full BCP-47 tag (e.g.~\texttt{en-US})
  \item \texttt{language} (e.g.,~\texttt{de})
  \item \texttt{region} (e.g.,~\texttt{AT})
  \item \texttt{script} (e.g.,~\texttt{Latn})
  \item \texttt{variant} (e.g.,~\texttt{1901})
  \item \texttt{extension.t} (transformation, e.g.,~\texttt{en-t-ja})
  \item \texttt{extension.u} (additional locale
    information, e.g.,~\texttt{ar-u-nu-latn})
  \item \texttt{extension.x} (private use area, e.g.,~\texttt{la-x-classic})
\end{itemize}
The information for the \emph{main} language for a document is be provided
if these are prefixed by \texttt{main.}, e.g.~\texttt{main.language} will
expand to the main language even if another language is currently active.

In addition to the tag breakdown, the following semantic arguments are
supported
\begin{itemize}
  \item \texttt{casing} The tag for case changing, e.g.~\texttt{el-x-iota}
    could be selected rather than \texttt{el} to select a capital adscript
    iota on uppercasing an \emph{ypogegrammeni}
\end{itemize}

For example, the case changing command \cs{MakeUppercase} is (conceptually)
defined as
\begin{verbatim}
\ExpandArgs{e}\MakeUppercaseAux{\BCPdata{casing}}{#1}
\end{verbatim}
where |#1| is the user input and the first argument to
\cs{MakeUppercaseAux} takes two arguments, the locale and input text.

\subsection{Extended and expandable references of properties}

A property is something that \LaTeX{} can track while processing
the document, such as a page
number, a heading number, other counter values, a heading title, 
a position on the page, etc.
The current value of such properties can be labeled and
written to the \texttt{aux}-file. It can then be referenced in
the next compilation, similar to the way the standard \cs{label}/\cs{ref}
commands work (they record/reference a fixed set of properties: 
label, page, title, and target).

\begin{decl}
  |\RecordProperties|\arg{label}\arg{list of properties} 
\end{decl}
This command writes the value(s) of the \meta{list of properties}
\texttt{aux}-file labeled by \meta{label}.  Recorded are either the
values current when \cs{RecordProperties} is called or the value
current when the next shipout happens---which depends on the
declaration for each property.
%
The arguments \meta{label} and \meta{list of properties} can contain
commands that are expanded. \meta{label} can expand to an arbitrary
string (as long as it can safely be written to the \texttt{aux}-file)
but note that the label names of \cs{label} and \cs{RecordProperties}
share a singe namespace. This means that you get a \texttt{Label `A'
  multiply defined} warning with the following code:
\begin{verbatim}
\label{A}\RecordProperties{A}{abspage}
\end{verbatim}


\begin{decl}
 |\RefProperty|\arg{label}\arg{property}
\end{decl}
This command allows to reference the value of the property
\meta{property} recorded in the previous run and labeled by \meta{label}.
Differently to the standard
\cs{ref} command the command is expandable and the value can for
example---if it is a number---be used in an assignment.\footnote{For
this to work the default value for the property would need to be a number too,
because recorded values aren't known in the first \LaTeX{} run.}

\begin{verbatim}
\section{A section}
\RecordProperties{mylabel}{pagenum,counter}
\RefProperty{mylabel}{counter} % outputs section
\setcounter{mycounter}{\RefProperty{mylabel}{pagenum}} 
\end{verbatim}



As \cs{RefProperty} is expandable it can not issue a rerun warning if
a label is not found. If needed such a warning can be forced by the
following command:
\begin{decl}
 |\RefUndefinedWarn|\arg{label}\arg{property}
\end{decl}

\LaTeX{} predefines a set of properties, this set contains also the
properties stored by the standard \cs{label} command. In the list
below \enquote{default} indicates the value returned when the value is
not yet known (i.e., if it wasn't recorded in the previous run and
\enquote{at shipout} means that this property is not recorded
immediately when \cs{RecordProperties} is used but during the next
\cs{shipout}.

\begin{description}
 \item[\texttt{abspage} (default: \texttt{0}, at shipout)] The absolute value of the current page:
   starts at $1$ and increases monotonically at each shipout.
   
 \item[\texttt{page} (default: \texttt{0}, at shipout)] The current page as given by \cs{thepage}: this may or
   may not be a numerical value, depending on the current
   style. Contrast with \texttt{abspage}. You get this value also with
   the standard \cs{label}/\cs{pageref}.

 \item[\texttt{pagenum} (default: \texttt{0}, at shipout)] The current page as arabic number. This is
   suitable for integer operations and comparisions.

 \item[\texttt{label} (default: \texttt{??})] The content of \cs{@currentlabel}. This is the value 
     that you get also with the standard \cs{label}/\cs{ref}. 

 \item[\texttt{title} (default: \texttt{\cs{textbf}\{??\}})] The content of \cs{@currentlabelname}.  This
   command is filled beside others by the \pkg{nameref} package and
   some classes (e.g.~\pkg{memoir}) and typically gives 
   the title defined in the document by some sectioning command

 \item[\texttt{target} (default: \meta{\mdseries empty})] The content of \cs{@currentHref}.  This
   command is normally filled by \pkg{hyperref} and holds the name of
   the last destination it created.

\item[\texttt{pagetarget} (default: \meta{\mdseries empty}, at shipout)] 
    The content of \cs{@currentHpage}.  This command is filled by 
    \pkg{hyperref} (version v7.01c or newer) and holds the name of the last 
    page anchor it created. 

 \item[\texttt{counter} (default: \meta{\mdseries empty})] The content of \cs{@currentcounter}.  This
   command contains after a \cs{refstepcounter} the name of the
   counter.

 \item[\texttt{xpos}, \texttt{ypos} (default: \texttt{0}, at shipout)] These properties records the
   $x$~and $y$ coordinates of a point previously stored with
   \cs{pdfsavepos}/\cs{savepos}.  E.g.~(if \pkg{bidi} is used it can
   be necessary to save the position before and after the label):
   \begin{verbatim}
     \pdfsavepos 
     \RecordProperties{myposition}{xpos,ypos}%
     \pdfsavepos
   \end{verbatim}  
\end{description} 
 
Class and package authors can define more properties to store other
values they are interested in.
\begin{decl}
  |\NewProperty|\arg{name}\arg{setpoint}\arg{default}\arg{code}\\
  |\SetProperty|\arg{name}\arg{setpoint}\arg{default}\arg{code}
\end{decl}
These commands declare or change a property \meta{name}\footnote{Only change 
properties that you have declared. The declarations of standard properties of \LaTeX{} and 
properties of other packages should never be altered!}. If a new property is 
declared within a package it is suggested that its name is always structured 
as follows: \meta{package-name}\texttt{/}\meta{property-name}. 
\meta{setpoint} is either |now| or |shipout| and decides if the value is 
written directly or at the next shipout. \meta{default} is used if the 
property is referenced but not yet known, e.g., in the first run.  
\meta{code} is the code executed when storing the value. For example, the 
\texttt{pagenum} property is declared as 
\begin{verbatim}
\NewProperty{pagenum}{shipout}{0}{\the\value{page}}
\end{verbatim}

The commands related to properties are offered as a set of CamelCase
commands for traditional \LaTeXe{} packages (and for use in the
document preamble if needed) as well as \texttt{expl3} commands for
modern packages, that use the L3 programming layer of \LaTeX{}. The
\texttt{expl3} commands and more details can be found in
\texttt{ltproperties-doc.pdf}.

\subsection{Preparing link targets}

Active links in a document need targets to which they can jump to. Such
targets are often created automatically (if the package \pkg{hyperref}
is loaded) by the \cs{refstepcounter} command but there are also cases
where class or package authors need to add a target manually, for
example, in unnumbered sectioning commands or in environments. For this
\LaTeX{} provides the following commands. \emph{Without}
\pkg{hyperref} they do nothing or insert only a whatsits 
(to ensure that spacing doesn't change when hyperref is loaded), \emph{with}
\pkg{hyperref} they add the necessary targets. Details about the
behavior and the arguments of the following commands can by found in
the \pkg{hyperref} package in \texttt{hyperref-linktarget.pdf}.

\begin{decl}
 |\MakeLinkTarget|\oarg{prefix}\arg{counter}\\
 |\MakeLinkTarget|\oarg{prefix}\{\}\\
 |\MakeLinkTarget|*\arg{target name}
\end{decl}
This command prepares the creations of targets. 

\begin{decl}
 |\LinkTargetOn|\\
 |\LinkTargetOff|
\end{decl}
These commands allow to enable and disable locally the creation of
targets. This can be useful to suppress targets otherwise created automatically
by \cs{refstepcounter}.

\begin{decl}
 |\NextLinkTarget|\arg{target name}
\end{decl}
This changes the name of the next target that will be created.

\section{Commands superseded for new material}

A small number of commands were introduced as part of \LaTeXe{} in the
mid-1990s, are widely used but have been superseded by more modern
methods.  These are covered here as they are likely to be encountered
routinely in existing classes and packages.

\subsection{Defining commands}

The \texttt{*}-forms of these commands should be used to define
commands that are not, in \TeX{} terms, long.  This can be useful for
error-trapping with commands whose arguments are not intended to
contain whole paragraphs of text.

\begin{decl}
  |\DeclareRobustCommand| \arg{cmd} \oarg{num} \oarg{default}
     \arg{definition}\\
  |\DeclareRobustCommand*| \arg{cmd} \oarg{num} \oarg{default}
     \arg{definition}
\end{decl}
This command takes the same arguments as |\newcommand| but it declares a robust
command, even if some code within the \m{definition} is fragile. You can use
this command to define new robust commands, or to redefine existing commands
and make them robust. A log is put into the transcript file if a command is
redefined.

For example, if |\seq| is defined as follows:
\begin{verbatim}
   \DeclareRobustCommand{\seq}[2][n]{%
     \ifmmode
       #1_{1}\ldots#1_{#2}%
     \else
       \PackageWarning{fred}{You can't use \protect\seq\space in text}%
     \fi
   }
\end{verbatim}
Then the command |\seq| can be used in moving arguments, even though
|\ifmmode| cannot, for example:
\begin{verbatim}
   \section{Stuff about sequences $\seq{x}$}
\end{verbatim}

Note also that there is no need to put a |\relax| before the |\ifmmode| at the
beginning of the definition; this is because the protection given by this
|\relax| against expansion at the wrong time will be provided internally.

\begin{decl}
  |\CheckCommand| \arg{cmd} \oarg{num} \oarg{default}
     \arg{definition}\\
  |\CheckCommand*| \arg{cmd} \oarg{num} \oarg{default}
     \arg{definition}
\end{decl}
This takes the same arguments as |\newcommand| but, rather than define \m{cmd},
it just checks that the current definition of \m{cmd} is exactly as given by
\m{definition}. An error is raised if these definitions differ.

This command is useful for checking the state of the system before your package
starts altering the definitions of commands. It allows you to check, in
particular, that no other package has redefined the same command.

\subsection{Option declaration}
\label{Sec:commands.options.dec}

The following commands deal with the declaration and handling of options to
document classes and packages using a classical `simple text' approach. Every
option name must be a `\LaTeX{} name'.

There are some commands designed especially for use within the \m{code}
argument of these commands (see below).

\begin{decl}
  |\DeclareOption| \arg{option-name} \arg{code}
\end{decl}
This makes \m{option-name} a `declared option' of the class or package in which
it is put.

The \m{code} argument contains the code to be executed if that option is
specified for the class or package; it can contain any valid \LaTeXe{}
construct.

Example:
\begin{verbatim}
   \DeclareOption{twoside}{\@twosidetrue}
\end{verbatim}

\begin{decl}
  |\DeclareOption*| \arg{code}
\end{decl}
This declares the \m{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 \LaTeXe{}
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.

\subsection{Commands within option code}
\label{Sec:within.code}

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

\begin{decl}
  |\CurrentOption|
\end{decl}
This expands to the name of the current option.

\begin{decl}
  |\OptionNotUsed|
\end{decl}
This causes the current option to be added to the list of `unused options'.

\subsection{Option processing}
\label{Sec:commands.options}

\begin{decl}
  |\ProcessOptions|
\end{decl}
This command executes the \m{code} for each selected option.

We shall first describe how |\ProcessOptions| works in a package file, and then
how this differs in a class file.

To understand in detail what |\ProcessOptions| does in a package file, you have
to know the difference between \emph{local} and \emph{global} options.
\begin{itemize}
\item \textbf{Local options} are those which have been explicitly
  specified for this particular package in the \m{options} argument of
  any of these:
\begin{quote}
    |\PassOptionsToPackage{<options>}| \ |\usepackage[<options>]|\\
    |\RequirePackage[<options>]|
\end{quote}
\item \textbf{Global options} are any other options that are specified
  by the author in the \m{options} argument of
    |\documentclass[<options>]|.
\end{itemize}
For example, suppose that a document begins:
\begin{verbatim}
   \documentclass[german,twocolumn]{article}
   \usepackage{gerhardt}
\end{verbatim}
whilst package |gerhardt| calls package |fred| with:
\begin{verbatim}
   \PassOptionsToPackage{german,dvips,a4paper}{fred}
   \RequirePackage[errorshow]{fred}
\end{verbatim}
then:
\begin{itemize}
\item |fred|'s local options are |german|, |dvips|, |a4paper|
  and |errorshow|;
\item |fred|'s only global option is |twocolumn|.
\end{itemize}

When |\ProcessOptions| is called, the following happen.
\begin{itemize}
\item \emph{First}, for each option so far declared in |fred.sty|
  by |\DeclareOption|, it looks to see if that option is either a
  global or a local option for |fred|: if it is then the corresponding
  code is executed.

  This is done in the order in which these options
  were declared in |fred.sty|.
\item \emph{Then}, for each remaining \emph{local} option, the command
  |\ds@<option>| is executed if it has been defined somewhere (other
  than by a |\DeclareOption|); otherwise, the `default option code' is
  executed.  If no default option code has been declared then an error
  message is produced.

  This is done in the order in which these
  options were specified.
\end{itemize}
Throughout this process, the system ensures that the code declared for
an option is executed at most once.

Returning to the example, if |fred.sty| contains:
\begin{verbatim}
   \DeclareOption{dvips}{\typeout{DVIPS}}
   \DeclareOption{german}{\typeout{GERMAN}}
   \DeclareOption{french}{\typeout{FRENCH}}
   \DeclareOption*{\PackageWarning{fred}{Unknown `\CurrentOption'}}
   \ProcessOptions\relax
\end{verbatim}
then the result of processing this document will be:
\begin{verbatim}
   DVIPS
   GERMAN
   Package fred Warning: Unknown `a4paper'.
   Package fred Warning: Unknown `errorshow'.
\end{verbatim}
Note the following:

\begin{itemize}
\item the code for the |dvips| option is executed before that for the
  |german| option, because that is the order in which they are declared
  in |fred.sty|;
\item the code for the |german| option is executed only once, when the
  declared options are being processed;
\item the |a4paper| and |errorshow| options produce the warning from
  the code declared by |\DeclareOption*| (in the order in which they
  were specified), whilst the |twocolumn| option does not: this is
  because |twocolumn| is a global option.
\end{itemize}

In a class file, |\ProcessOptions| works in the same way, except that:
\emph{all} options are local; and the default value for |\DeclareOption*| is
|\OptionNotUsed| rather than an error.

Note that, because |\ProcessOptions| has a |*|-form, it is wise to follow the
non-star form with |\relax|, as in the previous examples, since this prevents
unnecessary look ahead and possibly misleading error messages being issued.

\begin{decl}
  |\ProcessOptions*|
\end{decl}
This is like |\ProcessOptions| but it 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.

\begin{decl}
  |\ExecuteOptions| \arg{options-list}
\end{decl}

It can be used to provide a `default option list' just before
|\ProcessOptions|. For example, suppose that in a class file you want to set up
the default design to be: two-sided printing; 11pt fonts; in two columns. Then
it could specify:
\begin{verbatim}
   \ExecuteOptions{11pt,twoside,twocolumn}
\end{verbatim}

\end{document}