[latex3-commits] [latex3/latex2e] ltnews38-car-fmi: done, ready for merge (49908c64)

[github at latex-project.org]

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

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

commit 49908c64d3654eb53c031144d98c0ec8cf2ed164
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Mon Oct 30 12:22:22 2023 +0100

    done, ready for merge


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

49908c64d3654eb53c031144d98c0ec8cf2ed164
 base/doc/ltnews38.tex | 125 ++++++++++++++++++++++++++++----------------------
 1 file changed, 71 insertions(+), 54 deletions(-)

diff --git a/base/doc/ltnews38.tex b/base/doc/ltnews38.tex
index 212b3c71..1a504523 100644
--- a/base/doc/ltnews38.tex
+++ b/base/doc/ltnews38.tex
@@ -280,29 +280,27 @@ documentation see \texttt{texdoc ltsockets-doc}.
 
 \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
-\emph{current
-page number} and
-the \emph{current \textup{\cs{ref}} value} set by
-\cs{refstepcounter} declarations~\cite[p.~209]{38:Lamport}.
-(These declarations are issued, for example, by
-sectioning commands, by numbered environments like \env{equation}, 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}
-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
-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
-if these have been set by packages such as  \pkg{nameref} or \pkg{hyperref}.}
+Traditional \LaTeX{} uses \cs{label} to record the values of two
+\enquote{local} properties of the document: the textual
+representations of the \emph{current page number} and the
+\emph{current \textup{\cs{ref}} value} set by \cs{refstepcounter}
+declarations~\cite[p.~209]{38:Lamport}.  (These declarations are
+issued, for example, by sectioning commands, by numbered environments
+like \env{equation}, 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} 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 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 provided these
+have been set by packages such as \pkg{nameref} or \pkg{hyperref}.}
 
 
 Over the years \LaTeX{} packages have appeared that extend
@@ -325,14 +323,15 @@ idea of properties and lists of properties, with methods to record, and
 subsequently access, the value of any declared property.
 
 
-Starting with this release, the \LaTeX{} kernel provides handling of general document
-properties as a core functionality with standard interfaces.
+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}
-package but with some differences in detail, particularly
-in the implementation.
+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.
+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.
@@ -340,11 +339,13 @@ number, for example, here is the declaration to use.
   \NewProperty{chapter}{now}{?}{\thechapter}
 \end{verbatim}
 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.
+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.
 %
-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.
+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.
@@ -353,12 +354,12 @@ together with others, use this command.
                    {chapter,page,label}
 \end{verbatim}
 This records the current values for the properties \texttt{chapter},
-\texttt{page}, and \texttt{label}, using \texttt{mylabel} as the label, or \emph{key}
-for the record.
+\texttt{page}, and \texttt{label}, using \texttt{mylabel} as the
+label, or \emph{key}, for the record.
 
-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, \emph{key}, and the property.
+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, or \emph{key}, and the property.
 \begin{verbatim}
   \RefProperty{mylabel}{chapter}
 \end{verbatim}
@@ -368,27 +369,43 @@ The
 declarations for some generally useful properties,
 including these:
 \begin{description}
-\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{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};
-\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;
-\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.,
-                  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.
+
+\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;
+
+\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., 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.
 \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}.
+%
+For a more complete documentation, see \texttt{texdoc ltproperties-doc}.