[latex3-commits] [latex3/latex2e] develop: add properties and MakeLinkTarget to clsguide (bc2b56b7)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : develop
Link       : https://github.com/latex3/latex2e/commit/bc2b56b7bc2ebc6a0f476a85180a8d195f440790

>---------------------------------------------------------------

commit bc2b56b7bc2ebc6a0f476a85180a8d195f440790
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Tue Oct 10 20:19:54 2023 +0200

    add properties and MakeLinkTarget to clsguide


>---------------------------------------------------------------

bc2b56b7bc2ebc6a0f476a85180a8d195f440790
 base/doc/clsguide.tex | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex
index 79194ce5..3697a005 100644
--- a/base/doc/clsguide.tex
+++ b/base/doc/clsguide.tex
@@ -1191,6 +1191,113 @@ 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, 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:
+\begin{verbatim}
+\label{A}\RecordProperties{A}{page}
+\end{verbatim}
+
+
+\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.
+
+\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:
+\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):
+   \begin{verbatim}
+     \pdfsavepos 
+     \RefProperty{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{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}. 
+
+\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}. 
+
+\begin{decl}
+ |\MakeLinkTarget|\oarg{prefix}\arg{counter}\\
+ |\MakeLinkTarget|\oarg{prefix}\{\}\\
+ |\MakeLinkTarget|*\arg{manual target}\\
+\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 created
+automatically by \cs{refstepcounter}.
+
+\begin{decl}
+ |\NextLinkTarget|\arg{manual target}
+\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