[latex3-commits] [latex3/latex2e] update-clsguide: changes from review (50eb0d4a)

[github at latex-project.org]

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

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

commit 50eb0d4a503703fd8a395c120a8abcbf45345179
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Thu Oct 12 00:09:28 2023 +0200

    changes from review


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

50eb0d4a503703fd8a395c120a8abcbf45345179
 base/doc/clsguide.tex | 50 ++++++++++++++++++++++++++------------------------
 1 file changed, 26 insertions(+), 24 deletions(-)

diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex
index acad2703..c3de1d28 100644
--- a/base/doc/clsguide.tex
+++ b/base/doc/clsguide.tex
@@ -1184,10 +1184,12 @@ 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
-number, a section number or a name. Such properties can be labeled,
+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.
+commands (that record/reference a fixed set of properties: 
+label, page, title, and target).
 
 \begin{decl}
   |\RecordProperties|\arg{label}\arg{list of properties} 
@@ -1201,7 +1203,7 @@ 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'
   multiply defined} warning with the following code:
 \begin{verbatim}
-\label{A}\RecordProperties{A}{page}
+\label{A}\RecordProperties{A}{abspage}
 \end{verbatim}
 
 
@@ -1243,14 +1245,13 @@ properties stored by the standard \cs{label} command:
  \item[\texttt{pagenum}] The current page as arabic number. This is
    suitable for integer operations and comparisions.
 
- \item[\texttt{currentlabel}] The content of \cs{@currentlabel}. This
-   is the value that you get also with the standard
-   \cs{label}/\cs{ref}.
+ \item[\texttt{label}] 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
    command is filled beside others by the \pkg{nameref} package and
-   some classes (e.g.~\pkg{memoir}) and typically gives the title of
-   some sectioning command.
+   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
@@ -1266,7 +1267,7 @@ properties stored by the standard \cs{label} command:
    be necessary to save the position before and after the label):
    \begin{verbatim}
      \pdfsavepos 
-     \RefProperty{myposition}{xpos,ypos}%
+     \RecordProperties{myposition}{xpos,ypos}%
      \pdfsavepos
    \end{verbatim}  
 \end{description} 
@@ -1277,16 +1278,16 @@ values they are interested in.
   |\NewProperty|\arg{name}\arg{setpoint}\arg{default}\arg{code}\\
   |\SetProperty|\arg{name}\arg{setpoint}\arg{default}\arg{code}
 \end{decl}
-These commands declare or change a property \meta{name}\footnote{The
-standard set of properties and properties of other package should not
-be changed!}. 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.  \meta{code} is the code executed when
-storing the value. For example the \texttt{pagenum} property is
-declare as
+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 
+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 
+\texttt{pagenum} property is declared as 
 \begin{verbatim}
 \NewProperty{pagenum}{shipout}{0}{\the\value{page}}
 \end{verbatim}
@@ -1295,18 +1296,19 @@ The commands related to properties are offered as a set of CamelCase
 commands for traditional \LaTeXe{} packages (and for use in the
 document preamble if needed) as well as \texttt{expl3} commands for
 modern packages, that use the L3 programming layer of \LaTeX{}. The
-\texttt{expl3} commands and more details can by found in
+\texttt{expl3} commands and more details can be found in
 \texttt{ltproperties-doc.pdf}.
 
 \subsection{Preparing link targets}
 
-Active links in a document need targets where they can jump to. Such
+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
 \LaTeX{} provides the following commands. \emph{Without}
-\pkg{hyperref} they do nothing or insert only a whatsits, \emph{with}
+\pkg{hyperref} they do nothing or insert only a whatsits 
+(to ensure that spacing doesn't change when hyperref is loaded), \emph{with}
 \pkg{hyperref} they add the necessary targets. Details about the
 behaviour and the arguments of the following commands can by found in
 the \pkg{hyperref} package in \texttt{hyperref-linktarget.pdf}.
@@ -1314,7 +1316,7 @@ the \pkg{hyperref} package in \texttt{hyperref-linktarget.pdf}.
 \begin{decl}
  |\MakeLinkTarget|\oarg{prefix}\arg{counter}\\
  |\MakeLinkTarget|\oarg{prefix}\{\}\\
- |\MakeLinkTarget|*\arg{manual target}\\
+ |\MakeLinkTarget|*\arg{target name}\\
 \end{decl}
 This command prepares the creations of targets. 
 
@@ -1327,7 +1329,7 @@ targets. This can be useful to suppress targets created automatically
 by \cs{refstepcounter}.
 
 \begin{decl}
- |\NextLinkTarget|\arg{manual target}
+ |\NextLinkTarget|\arg{target name}
 \end{decl}
 This changes the name of the next target that will be created.