[latex3-commits] [latex3/latex2e] ltnews38-car-fmi: added in further suggestions (05bd2013)

[github at latex-project.org]

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

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

commit 05bd201328a4244f264cb4958fa509a6e3561cfc
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Mon Oct 30 08:58:36 2023 +0100

    added in further suggestions


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

05bd201328a4244f264cb4958fa509a6e3561cfc
 base/doc/ltnews38.tex | 55 ++++++++++++---------------------------------------
 1 file changed, 13 insertions(+), 42 deletions(-)

diff --git a/base/doc/ltnews38.tex b/base/doc/ltnews38.tex
index 3c740229..212b3c71 100644
--- a/base/doc/ltnews38.tex
+++ b/base/doc/ltnews38.tex
@@ -283,10 +283,8 @@ documentation see \texttt{texdoc ltsockets-doc}.
 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
-%%FMi from Lamport
 the \emph{current \textup{\cs{ref}} value} set by
 \cs{refstepcounter} declarations~\cite[p.~209]{38:Lamport}.
 (These declarations are issued, for example, by
@@ -296,33 +294,18 @@ sectioning commands, by numbered environments like \env{equation}, and by \cs{it
 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.
+using the \emph{key} that was specified as the argument to \cs{label} when recording these values.
 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
+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
+Over the years \LaTeX{} packages have appeared that extend
 this basic \enquote{label-ref system} in various ways.
 %
 For example, the \pkg{refcount} package made a small but significant change
@@ -342,8 +325,7 @@ 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 of general document
+Starting with this release, the \LaTeX{} kernel provides handling of general document
 properties as a core functionality with standard interfaces.
 %
 This is based on concepts introduced by the \pkg{zref}
@@ -361,9 +343,8 @@ 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 recording the value is requested.
+%
+The final argument contains the code that will, as part of the recording process, be expanded to obtain the value to record for this property.
 
 Then, to record the value of this new property,
 together with others, use this command.
@@ -371,28 +352,22 @@ together with others, use this command.
   \RecordProperties{mylabel}
                    {chapter,page,label}
 \end{verbatim}
-%%FMi added:
 This records the current values for the properties \texttt{chapter},
-\texttt{page}, and \texttt{label}, using \texttt{mylabel} as a label
+\texttt{page}, and \texttt{label}, using \texttt{mylabel} as the label, or \emph{key}
 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.
+the \cs{RefProperty} command with two arguments: the label, \emph{key}, and the property.
 \begin{verbatim}
   \RefProperty{mylabel}{chapter}
 \end{verbatim}
 
 The
-%%FMi changed
-%extension itself contains
-\LaTeX{} kernel itself already contains
+\LaTeX{} kernel itself 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 number for the page currently under construction;
 \item[\texttt{title}] the title, if set by, e.g.,~\pkg{nameref};
@@ -401,14 +376,10 @@ 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 absolute page number of the page under construction, i.e., number of already shipped out pages plus 1;
-%%FMi changed:
-%\texttt{counter}] (the name of the counter stepped in the (local) most recent \cs{refstepcounter});
+\item[\texttt{abspage}] the absolute page number of the page under construction, i.e.,
+  one more than the number of pages shipped out so far (thus it starts at 1 and is increased by 1 whenever a page is shipped out);
 \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;
+                  the counter that was stepped in 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.