diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/base/clsguide.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/base/clsguide.tex | 200 |
1 files changed, 191 insertions, 9 deletions
diff --git a/Master/texmf-dist/doc/latex/base/clsguide.tex b/Master/texmf-dist/doc/latex/base/clsguide.tex index 7225425ec8a..457f74f2876 100644 --- a/Master/texmf-dist/doc/latex/base/clsguide.tex +++ b/Master/texmf-dist/doc/latex/base/clsguide.tex @@ -42,7 +42,7 @@ \texttt{clsguide.tex} for full details.}% } -\date{2023-01-12} +\date{2023-10-24} \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}} \NewDocumentCommand\marg{m}{\arg{#1}} @@ -143,7 +143,7 @@ There are several reasons why we should not make such changes to these files. \begin{itemize} \item - However misguided, the current behaviour is clearly what was + 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' @@ -188,7 +188,7 @@ command which should only be used in the \LaTeX{} kernel, whereas 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 behaviour may change in future releases! If a command is +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. @@ -489,7 +489,7 @@ the |article| class to set the |\paperheight| and |\paperwidth| lengths: \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 behaviour can be altered as follows: +error (for packages); this behavior can be altered as follows: \begin{verbatim} \DeclareOption*{<code>} \end{verbatim} @@ -847,7 +847,7 @@ The basic properties provided here are 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 behaviour of the option. +\m{value} working with the \m{property} to define the behavior of the option. For example, with \begin{verbatim} @@ -875,7 +875,15 @@ options. 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. +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} @@ -883,6 +891,8 @@ e.g.~by forwarding to another package. 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} @@ -1181,12 +1191,184 @@ defined as 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. +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} |