[latex3-commits] [latex3/latex2e] update-clsguide: some docu changes (dff37bbf)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : update-clsguide
Link       : https://github.com/latex3/latex2e/commit/dff37bbfaa9a32315eaefeb76bf71841700c250e

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

commit dff37bbfaa9a32315eaefeb76bf71841700c250e
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Tue Oct 24 23:33:14 2023 +0200

    some docu changes


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

dff37bbfaa9a32315eaefeb76bf71841700c250e
 base/doc/clsguide.tex | 75 ++++++++++++++++++++++++++++++---------------------
 1 file changed, 45 insertions(+), 30 deletions(-)

diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex
index 09eefaa6..5c22f81f 100644
--- a/base/doc/clsguide.tex
+++ b/base/doc/clsguide.tex
@@ -42,7 +42,7 @@
     \texttt{clsguide.tex} for full details.}%
 }
 
-\date{2023-10-10}
+\date{2023-10-24}
 
 \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
 \NewDocumentCommand\marg{m}{\arg{#1}}
@@ -1183,24 +1183,30 @@ where |#1| is the user input and the first argument to
 
 \subsection{Extended and expandable references of properties}
 
-A property is something that \LaTeX{} can track, such as a page
+A property is something that \LaTeX{} can track while processing
+the document, such as a page
 number, a heading number, other counter values, a heading title, 
-a position on the page, etc. 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 (that record/reference a fixed set of properties: 
+a position on the page, etc.
+The current value of such properties can be labeled and
+written to the \texttt{aux}-file. It can then be referenced in
+the next compilation, similar to the way the standard \cs{label}/\cs{ref}
+commands work (they record/reference a fixed set of properties: 
 label, page, title, and target).
 
 \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
+This command writes the value(s) of the \meta{list of properties}
+\texttt{aux}-file labeled by \meta{label}.  Recorded are either the
+values current when \cs{RecordProperties} is called or the value
+current when the next shipout happens---which depends on the
+declaration for each property.
+%
+The arguments \meta{label} and \meta{list of properties} can contain
+commands that 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'
+share a singe namespace. This means that you get a \texttt{Label `A'
   multiply defined} warning with the following code:
 \begin{verbatim}
 \label{A}\RecordProperties{A}{abspage}
@@ -1211,9 +1217,12 @@ share a singe namespace. That means that you get a \texttt{Label `A'
  |\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
+\meta{property} recorded in the previous run and 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.
+example---if it is a number---be used in an assignment.\footnote{For
+this to work the default value for the property would need to be a number too,
+because recorded values aren't known in the first \LaTeX{} run.}
 
 \begin{verbatim}
 \section{A section}
@@ -1232,36 +1241,42 @@ following command:
 \end{decl}
 
 \LaTeX{} predefines a set of properties, this set contains also the
-properties stored by the standard \cs{label} command:
+properties stored by the standard \cs{label} command. In the list
+below \enquote{default} indicates the value returned when the value is
+not yet known (i.e., if it wasn't recorded in the previous run and
+\enquote{at shipout} means that this property is not recorded
+immediately when \cs{RecordProperties} is used but during the next
+\cs{shipout}.
+
 \begin{description}
- \item[\texttt{abspage}] The absolute value of the current page:
+ \item[\texttt{abspage} (default: \texttt{0}, at shipout)] 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
+ \item[\texttt{page} (default: \texttt{0}, at shipout)] 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
+ \item[\texttt{pagenum} (default: \texttt{0}, at shipout)] The current page as arabic number. This is
    suitable for integer operations and comparisions.
 
- \item[\texttt{label}] The content of \cs{@currentlabel}. This is the value 
+ \item[\texttt{label} (default: \texttt{??})] 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
+ \item[\texttt{title} (default: \texttt{\cs{textbf}\{??\}})] 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 defined in the document by some sectioning command
 
- \item[\texttt{target}] The content of \cs{@currentHref}.  This
-   command is normally filled by \pkg{hyperref} and gives the name of
+ \item[\texttt{target} (default: \meta{\mdseries empty})] The content of \cs{@currentHref}.  This
+   command is normally filled by \pkg{hyperref} and holds the name of
    the last destination it created.
 
- \item[\texttt{counter}] The content of \cs{@currentcounter}.  This
+ \item[\texttt{counter} (default: \meta{\mdseries empty})] 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
+ \item[\texttt{xpos}, \texttt{ypos} (default: \texttt{0}, at shipout)] 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):
@@ -1279,14 +1294,14 @@ values they are interested in.
   |\SetProperty|\arg{name}\arg{setpoint}\arg{default}\arg{code}
 \end{decl}
 These commands declare or change a property \meta{name}\footnote{Only change 
-properties that you have declared. The standard set of properties and 
-properties of other package should never be changed!}. If a new property is 
+properties that you have declared. The declarations of standard properties of \LaTeX{} and 
+properties of other packages should never be altered!}. 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, e.g., in the first run.  
-\meta{code} is the code executed when storing the value. For example the 
+\meta{code} is the code executed when storing the value. For example, the 
 \texttt{pagenum} property is declared as 
 \begin{verbatim}
 \NewProperty{pagenum}{shipout}{0}{\the\value{page}}
@@ -1304,8 +1319,8 @@ modern packages, that use the L3 programming layer of \LaTeX{}. The
 Active links in a document need targets to which 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
+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 
 (to ensure that spacing doesn't change when hyperref is loaded), \emph{with}
@@ -1316,7 +1331,7 @@ the \pkg{hyperref} package in \texttt{hyperref-linktarget.pdf}.
 \begin{decl}
  |\MakeLinkTarget|\oarg{prefix}\arg{counter}\\
  |\MakeLinkTarget|\oarg{prefix}\{\}\\
- |\MakeLinkTarget|*\arg{target name}\\
+ |\MakeLinkTarget|*\arg{target name}
 \end{decl}
 This command prepares the creations of targets. 
 
@@ -1325,7 +1340,7 @@ This command prepares the creations of targets.
  |\LinkTargetOff|
 \end{decl}
 These commands allow to enable and disable locally the creation of
-targets. This can be useful to suppress targets created automatically
+targets. This can be useful to suppress targets otherwise created automatically
 by \cs{refstepcounter}.
 
 \begin{decl}