[latex3-commits] [latex3/latex2e] ltnews38-car-fmi: CAR rewrite of section with changes by FMi (1376e775)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : ltnews38-car-fmi
Link       : https://github.com/latex3/latex2e/commit/1376e7755de59cc8f7fa8cd81feac3bae2e87df2

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

commit 1376e7755de59cc8f7fa8cd81feac3bae2e87df2
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Sun Oct 29 20:52:52 2023 +0100

    CAR rewrite of section with changes by FMi


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

1376e7755de59cc8f7fa8cd81feac3bae2e87df2
 base/doc/ltnews38.tex | 190 ++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 136 insertions(+), 54 deletions(-)

diff --git a/base/doc/ltnews38.tex b/base/doc/ltnews38.tex
index 4d2099ae..e54832a3 100644
--- a/base/doc/ltnews38.tex
+++ b/base/doc/ltnews38.tex
@@ -278,67 +278,149 @@ documentation see \texttt{texdoc ltsockets-doc}.
 
 
 
-\section{Extended cross-referencing of document properties}
-
-Traditionally \LaTeX{} allowed with \cs{label} to record two \enquote{local} 
-properties of the document: the representation of the current page number and 
-of the current counter. Their values could then be referenced with the 
-(non-expandable)  commands \cs{ref} and \cs{pageref} in arbitrary places of a 
-document.  With the summer 2023 release the \cs{label} was enhanced to record 
-also if set by packages like \pkg{nameref} or \pkg{hyperref} the title and 
-the name of the link target. 
-
-Over the years packages extended the label-ref system in various ways. 
-Examples are for example the \pkg{refcount} package to reference the values 
-expandably, the \pkg{smartref} package, which allows to store more counter 
-values and so to reference the current chapter together with the current 
-equation, the \pkg{cleveref} package, which stores in a second internal label 
-beside other the name of the counter,  the \pkg{hyperref} package whose 
-\cs{autoref} command tries to retrieve the name of the counter from the name 
-of the link target, the \pkg{tikzmarks} which records absolute positions on 
-the page, and the \pkg{zref} package which implements a general method to 
-record and reference properties. 
-
-Starting with this release the \LaTeX{} kernel contains now its own 
-extension. It is loosely based on \pkg{zref}. It allows to declare new 
-properties, to record arbitrary combinations of properties. The values are 
-retrieved expandably. 
-
-As an example to setup a new property which records the current chapter 
-number the following declaration could be used: 
+\section{Document properties and cross-referencing}
+
+Traditional \LaTeX{} uses \cs{label} to record the values of
+two \enquote{local}
+properties of the document: the textual representations of the
+%% FMi added back in, be cause it is the "current", see Lamport:
+\emph{current
+page number} and the
+%%FMi from Lamport
+the \emph{current \textup{\cs{ref}} value} set by
+\cs{refstepcounter} declarations~\cite[p.~209]{38:Lamport}.
+(These declarations are issued by
+sectioning commands, by numbered environments, and by \cs{item} in an
+\env{enumerate} or a similar environment.)
+
+These two recorded values can then be accessed and typeset
+(from anywhere in the next run of the document) by use of the
+(non-expandable) commands \cs{ref} and \cs{pageref}
+%%FMi new
+using the \emph{key} that was assigned to the values with the \cs{label} command.
+This supported basic cross-referencing (within a document) using
+these recorded values to provide both page-related and counter-related
+information (such as the page xvii or the subsection number 4.5.2).\footnote{In the Spring 2023 release of \LaTeX{}, the \cs{label} command was extended
+to record, in addition, both a title (such as the text used in a
+section head) and the \emph{logical name} used
+for an associated link target
+%%FMi new
+if these have been set by packages such as  \pkg{nameref} or \pkg{hyperref}.}
+
+
+%In the Spring 2023 release, the \cs{label} command was extended
+%to record, in addition, both a title (such as the text used in a
+%section head) and the \emph{logical name} used
+%for an associated link target
+%%FMi new
+%if these have been set by packages such as  \pkg{nameref} or \pkg{hyperref}.
+
+%%FMi: meanwhile sounds as if it just happened after 2023 Spring ...
+%%     So moved the above text into a footnote (is anyway old news) and
+%%    did some rewrites below.
+%%
+%Meanwhile, other packages had been extending
+%this \enquote{label-ref system} in various ways.
+
+Over the years \LaTeX{} packages appeared that extended
+this basic \enquote{label-ref system} in various ways.
+%
+For example, the \pkg{refcount} package made a small but significant change
+to the functions used to access recorded values, by making them expandable.
+And the \pkg{smart-ref} package supports the storage of a larger
+collection of counter values so that, for example, a cross-reference
+can refer to the relevant chapter together with an equation tag.
+The \pkg{cleveref} package stores (by means of a second, internal
+\enquote{logical label}) extra information such as the name of the counter.
+The \pkg{hyperref} package adds the \cs{autoref} command, which
+tries to retrieve the name of a counter from the  \emph{logical name}
+used for a link target.
+The \pkg{tikzmarks} package records information about
+ \emph{labelled positions} in pictures when using \pkg{tikz}.
+Finally, the \pkg{zref} package implements many related ideas, including a general
+idea of properties and lists of properties, with methods to record, and
+subsequently access, the value of any declared property.
+
+
+%%FMi some rewrite:
+Starting with this release, the \LaTeX{} kernel now offers the handling general document
+properties as a core functionality with standard interfaces.
+%
+This is based on concepts introduced by the \pkg{zref}
+package but with some differences in detail, particularly
+in the implementation.
+It supports the declaration of new properties, and the recording of
+the values of any list of properties. These values are retrieved expandably.
+
+To set up a new property that is the current chapter
+number, for example, here is the declaration to use.
 \begin{verbatim}
-\NewProperty{chapter}{now}{?}{\thechapter}
+  \NewProperty{chapter}{now}{?}{\thechapter}
 \end{verbatim}
-The second argument means that the property is recorded immediately 
-(\enquote{now}) and not at \cs{shipout}. The third argument sets a default if a 
-label is unknown. It is then possible to record a list of properties with 
-\cs{RecordProperties}: 
+The second argument means that the property value will be recorded
+immediately (\enquote{now}), and not \enquote{during the next \cs{shipout}}.
+The third argument sets a default
+to be used when, for example, an unknown label is supplied.
+%%FMi added
+The final argument contains the code that produces the current
+property value when when recording the value is requested.
+
+Then, to record the value of this new property,
+together with others, use this command.
 \begin{verbatim}
-\RecordProperties{mylabel}
-                 {chapter,page,currentlabel}
+  \RecordProperties{mylabel}
+                   {chapter,page,label}
 \end{verbatim}
-To reference the value the \cs{RefProperty} command is provided which takes 
-two arguments, the label and the property: 
+%%FMi added:
+This records the current values for the properties \texttt{chapter},
+\texttt{page}, and \texttt{label}, using \texttt{mylabel} as a label
+for the record.
+
+%%FMi changed: again following Lamport terminology
+To reference (i.e., to retrieve)
+this recorded value for use in a cross-reference to this chapter, use
+the \cs{RefProperty} command with two arguments: the label and the property.
 \begin{verbatim}
-\RefProperty{mylabel}{chapter}
+  \RefProperty{mylabel}{chapter}
 \end{verbatim}
 
-The new module pre-declares a set of generally useful properties:
-\texttt{label} (the standard counter representation), \texttt{page}
-(the page representation), \texttt{title} (the title if set e.g.~by
-\pkg{nameref}), \texttt{target} (the name of the link target if set,
-e.g., by \pkg{hyperref}), \texttt{pagetarget} (the name of target
-added each page by \pkg{hyperref}), \texttt{pagenum} (the page as an
-arabic number), \texttt{abspage} (the absolute page number),
-\texttt{counter} (the name of the current counter), and \texttt{xpos}
-and \texttt{ypos} (the position on the page as set by the most recent
-\cs{pdfsavepos}: recording the properties should occur as soon after
-saving the position as possible).
-  
-The module provides both \LaTeXe{} camel case commands and
-\LaTeX3 programming layer commands.    
-
-For documentation see \texttt{texdoc ltproperties-doc}. 
+The
+%%FMi changed
+%extension itself contains
+\LaTeX{} kernel itself already contains
+declarations for some generally useful properties,
+including these:
+\begin{description}
+%%FMi changed:
+%\texttt{label} (the textual representation of the counter);
+\item[\texttt{label}] the textual representation of the \emph{current \textup{\cs{ref}} value}, see above;
+\item[\texttt{page}] the textual representation of the page;
+\item[\texttt{title}] the title, if set by, e.g.,~\pkg{nameref};
+\item[\texttt{target}] the logical name of the associated link target, if set by,
+e.g.,~\pkg{hyperref};
+\item[\texttt{pagetarget}] the logical name of the target added
+by \pkg{hyperref} at the origin of each shipped out page;
+\item[\texttt{pagenum}] the value of the \LaTeX{} counter \texttt{page} in Arabic numerals;
+%% NOT as an Arabic number -- Arabic numbers are "something totally different"!!
+%%FMi changed:
+%\texttt{abspage} (the value of the \texttt{shipout count});
+\item[\texttt{abspage}] the current number of shipped out pages;
+%%FMi changed:
+%\texttt{counter}] (the name of the counter stepped in the (local) most recent \cs{refstepcounter});
+\item[\texttt{counter}] the name of the counter that produced the \emph{current \textup{\cs{ref}} value}, i.e.,
+                  from the most recent \cs{refstepcounter} within the current scope;
+\item[\texttt{xpos}, \texttt{ypos}] the position on the shipped out page as
+set by the most recent \cs{pdfsavepos}: recording these properties should
+be done as soon as possible after saving the position.
+\end{description}
+
+Both \LaTeXe{} commands (using camel-case names) and
+\LaTeX3 programming layer commands are provided.
+
+For the full documentation, see \texttt{texdoc ltproperties-doc}.
+
+
+
 
 \section{New or improved commands}