[latex3-commits] [latex3/latex2e] develop: CAR rewrite of section with changes by FMi (#1158) (b87d4af9)
github at latex-project.org
github at latex-project.org
Mon Oct 30 17:22:38 CET 2023
Repository : https://github.com/latex3/latex2e
On branch : develop
Link : https://github.com/latex3/latex2e/commit/b87d4af94099a4fe9c19e75b630c3ebd90c0ef69
>---------------------------------------------------------------
commit b87d4af94099a4fe9c19e75b630c3ebd90c0ef69
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Mon Oct 30 17:22:38 2023 +0100
CAR rewrite of section with changes by FMi (#1158)
* CAR rewrite of section with changes by FMi
* entered suggestions
* more update suggestions
* added in further suggestions
* done, ready for merge
* one more ...
* sigh, done?
>---------------------------------------------------------------
b87d4af94099a4fe9c19e75b630c3ebd90c0ef69
base/doc/ltnews38.tex | 178 +++++++++++++++++++++++++++++++++++---------------
1 file changed, 124 insertions(+), 54 deletions(-)
diff --git a/base/doc/ltnews38.tex b/base/doc/ltnews38.tex
index 4d2099ae..918a2028 100644
--- a/base/doc/ltnews38.tex
+++ b/base/doc/ltnews38.tex
@@ -278,67 +278,137 @@ 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}\Arg{key} 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
+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} library records information about
+ \emph{labelled positions} on the page 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.
+
+
+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.
+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.
+%
+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.
\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:
+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.
+
+To \emph{reference} (i.e., 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}
+ \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
+\LaTeX{} kernel itself contains
+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{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.
+\end{description}
+
+Both \LaTeXe{} commands (using camel-case names) and
+\LaTeX3 programming layer commands are provided.
+%
+For a more complete documentation, see \texttt{texdoc ltproperties-doc}.
+
+
+
\section{New or improved commands}
More information about the latex3-commits
mailing list.