[latex3-commits] [git/LaTeX3-latex3-latex2e] clsguide-cleanup: Add section 'commands' (5f490719)
Joseph Wright
joseph.wright at morningstar2.co.uk
Thu Jan 12 10:59:20 CET 2023
Repository : https://github.com/latex3/latex2e
On branch : clsguide-cleanup
Link : https://github.com/latex3/latex2e/commit/5f4907197741f8e82e7400cfdcd9f73205e07975
>---------------------------------------------------------------
commit 5f4907197741f8e82e7400cfdcd9f73205e07975
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Thu Jan 12 09:59:20 2023 +0000
Add section 'commands'
Largely copied, but I have dropped \DeclareRobustCommand and \CheckCommand:
better to use ltcmd features and hooks.
>---------------------------------------------------------------
5f4907197741f8e82e7400cfdcd9f73205e07975
base/doc/clsguide.tex | 499 +++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 498 insertions(+), 1 deletion(-)
diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex
index eca19a94..c2fe499e 100644
--- a/base/doc/clsguide.tex
+++ b/base/doc/clsguide.tex
@@ -355,7 +355,7 @@ For example:
\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{article}[2002-06-01 Standard LaTeX class]
\end{verbatim}
-The \m{date} should be given in the form `\textsc{YYYY-MM-DD}' and must be
+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
@@ -586,4 +586,501 @@ 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.
+
+\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}
+
+\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{Option declaration}
+\label{Sec:commands.options.dec}
+
+The following commands deal with the declaration and handling of options to
+document classes and packages. 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{Moving options around}
+\label{Sec:opmove}
+
+These two commands are also very useful within the \m{code} argument of
+|\DeclareOption| or |\DeclareOption*|:
+\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
+\texttt{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{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{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}
+
+\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.
+
\end{document}
More information about the latex3-commits
mailing list.