[latex3-commits] [latex3/latex2e] update-clsguide: more newlines (not text change) (0bebf347)
github at latex-project.org
github at latex-project.org
Wed Oct 11 11:27:25 CEST 2023
Repository : https://github.com/latex3/latex2e
On branch : update-clsguide
Link : https://github.com/latex3/latex2e/commit/0bebf347043dd3161d387c7f09c70de7dc6cbfb6
>---------------------------------------------------------------
commit 0bebf347043dd3161d387c7f09c70de7dc6cbfb6
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Wed Oct 11 11:27:25 2023 +0200
more newlines (not text change)
>---------------------------------------------------------------
0bebf347043dd3161d387c7f09c70de7dc6cbfb6
base/doc/clsguide.tex | 129 +++++++++++++++++++++++++++++++++-----------------
1 file changed, 86 insertions(+), 43 deletions(-)
diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex
index fc769efa..acad2703 100644
--- a/base/doc/clsguide.tex
+++ b/base/doc/clsguide.tex
@@ -1183,14 +1183,23 @@ where |#1| is the user input and the first argument to
\subsection{Extended and expandable references of properties}
-A property is something that \LaTeX{} can track, such as a page number, a section number or a name. Such properties
-can be labeled, their current value written to the \texttt{aux}-file and referenced in the next compilation, similar to the standard \cs{label}/\cs{ref} commands.
+A property is something that \LaTeX{} can track, such as a page
+number, a section number or a name. Such properties can be labeled,
+their current value written to the \texttt{aux}-file and referenced in
+the next compilation, similar to the standard \cs{label}/\cs{ref}
+commands.
\begin{decl}
|\RecordProperties|\arg{label}\arg{list of properties}
\end{decl}
-This command writes the current or shipout value (depending on the declaration of the property)
-of the properties in the list into the \texttt{aux}-file labeled by \meta{label}. The arguments can contain commands which 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. That means that you get a \texttt{Label `A' multiply defined} warning with the following code:
+This command writes the current or shipout value (depending on the
+declaration of the property) of the properties in the list into the
+\texttt{aux}-file labeled by \meta{label}. The arguments can contain
+commands which 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. That means that you get a \texttt{Label `A'
+ multiply defined} warning with the following code:
\begin{verbatim}
\label{A}\RecordProperties{A}{page}
\end{verbatim}
@@ -1199,7 +1208,10 @@ of the properties in the list into the \texttt{aux}-file labeled by \meta{label}
\begin{decl}
|\RefProperty|\arg{label}\arg{property}
\end{decl}
-This command allows to reference the value of the property \meta{property} 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.
+This command allows to reference the value of the property
+\meta{property} 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.
\begin{verbatim}
\section{A section}
@@ -1210,34 +1222,48 @@ This command allows to reference the value of the property \meta{property} label
-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:
+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:
+\LaTeX{} predefines a set of properties, this set contains also the
+properties stored by the standard \cs{label} command:
\begin{description}
- \item[\texttt{abspage}] The absolute value of the current page: starts at $1$ and increases
- monotonically at each shipout.
- \item[page] 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}] The current page as arabic number. This is suitable for integer operations and
- comparisions.
- \item[\texttt{currentlabel}] The content of \cs{@currentlabel}. This is the value that
- you get also with the standard \cs{label}/\cs{ref}.
- \item[\texttt{title}] 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 of some sectioning command.
- \item[\texttt{target}] The content of \cs{@currentHref}.
- This command is normally filled by \pkg{hyperref} and gives the name of the last destination it created.
- \item[\texttt{counter}] The content of \cs{@currentcounter}.
- This command contains after a \cs{refstepcounter} the name of the counter.
- \item[\texttt{xpos}, \texttt{ypos}] 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):
+ \item[\texttt{abspage}] The absolute value of the current page:
+ starts at $1$ and increases monotonically at each shipout.
+
+ \item[page] 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}] The current page as arabic number. This is
+ suitable for integer operations and comparisions.
+
+ \item[\texttt{currentlabel}] The content of \cs{@currentlabel}. This
+ is the value that you get also with the standard
+ \cs{label}/\cs{ref}.
+
+ \item[\texttt{title}] 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 of
+ some sectioning command.
+
+ \item[\texttt{target}] The content of \cs{@currentHref}. This
+ command is normally filled by \pkg{hyperref} and gives the name of
+ the last destination it created.
+
+ \item[\texttt{counter}] The content of \cs{@currentcounter}. This
+ command contains after a \cs{refstepcounter} the name of the
+ counter.
+
+ \item[\texttt{xpos}, \texttt{ypos}] 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
\RefProperty{myposition}{xpos,ypos}%
@@ -1245,29 +1271,45 @@ standard \cs{label} command:
\end{verbatim}
\end{description}
-Class and package authors can define more properties to store other values they are interested in.
+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{The standard set of properties and properties of other package should not be changed!}. 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.
-\meta{code} is the code executed when storing the value. For example the \texttt{pagenum} property is declare as
+These commands declare or change a property \meta{name}\footnote{The
+standard set of properties and properties of other package should not
+be changed!}. 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. \meta{code} is the code executed when
+storing the value. For example the \texttt{pagenum} property is
+declare 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 by found in \texttt{ltproperties-doc.pdf}.
+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 by found in
+\texttt{ltproperties-doc.pdf}.
\subsection{Preparing link targets}
-Active links in a document need targets where 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, \emph{with} \pkg{hyperref} they add the necessary targets. Details about the behaviour and the arguments of the following commands can by found in the \pkg{hyperref} package in \texttt{hyperref-linktarget.pdf}.
+Active links in a document need targets where 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, \emph{with}
+\pkg{hyperref} they add the necessary targets. Details about the
+behaviour 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}\\
@@ -1280,8 +1322,9 @@ This command prepares the creations of targets.
|\LinkTargetOn|\\
|\LinkTargetOff|
\end{decl}
-These commands allow to enable and disable locally the creation of targets. This can be useful to suppress targets created
-automatically by \cs{refstepcounter}.
+These commands allow to enable and disable locally the creation of
+targets. This can be useful to suppress targets created automatically
+by \cs{refstepcounter}.
\begin{decl}
|\NextLinkTarget|\arg{manual target}
@@ -1291,9 +1334,9 @@ 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}
More information about the latex3-commits
mailing list.