Merge branch 'ltproperties' into develop

base/changes.txt

@@ -6,6 +6,11 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
+2023-09-05 Ulrike Fischer <Ulrike.Fischer@latex-project.org>
+	* ltproperties.dtx: 
+      First implementation of properties module
+    * ltmiscen.dtx:
+      add test to \enddocument for changes in property values.   
 2023-09-01  Joseph Wright  <Joseph.Wright@latex-project.org>
 
 	* ltcmd.dtx
@@ -27,6 +32,8 @@ are not part of the distribution.
 
 2023-08-19 Joseph Wright  <Joseph.Wright@latex-project.org>
 
+2023-08-19 Joseph Wright  <Joseph.Wright@latex-project.org> 
+
 	* ltcmd.dtx, usrguide.tex
 	Remove \GetDocumentCommandArgSpec,
 	  \GetDocumentEnvironmentArgSpec,

base/doc/ltnews38.tex

@@ -148,6 +148,62 @@ \section{Sockets and plugs}
 
 For documentation see \texttt{texdoc ltsockets-doc} for now.
 
+\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: 
+\begin{verbatim}
+\NewProperty{chapter}{now}{?}{\thechapter}
+\end{verbatim}
+The second argument means that the property is recorded immediately 
+(\enquote{now}) and not at 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}: 
+\begin{verbatim}
+\RecordProperties{mylabel}{chapter,page,currentlabel}
+\end{verbatim}
+To reference the value the \cs{RefProperty} command is provided which takes 
+two arguments, the label and the property: 
+\begin{verbatim}
+\RefProperty{mylabel}{chapter}
+\end{verbatim}
+
+The new module predeclares a set of generally useful properties: 
+\texttt{currentlabel} (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{pagenum} (the page as an arabic number), 
+\texttt{abspage} (the absolute page number), \texttt{counter} (the name of 
+the current counter), \texttt{xpos} and \texttt{ypos} the position on the 
+page as set by a previous \cs{pdfsavepos}. 
+
+The module provides both \LaTeXe{} camel case commands and expl3 commands.    
+
+For documentation see \texttt{texdoc ltproperties-doc}. 
 
 \section{New or improved commands}
 

base/doc/ltproperties-code.tex

@@ -0,0 +1,5 @@
+% This will typeset documentation + code
+%
+
+\AtBeginDocument{\AlsoImplementation}
+\input{ltproperties.dtx}

base/doc/ltproperties-doc.tex

@@ -0,0 +1,8 @@
+% This will typeset only documentation but not the code
+%
+
+\AtBeginDocument{\OnlyDescription
+%                 \let\tableofcontents\relax
+                  \RenewCommandCopy\MaybeStop\StopEventually
+                 }
+\input{ltproperties.dtx}

base/doc/source2e.tex

@@ -303,6 +303,8 @@
  \DocInclude{ltpageno} % Page numbering
 
  \DocInclude{ltxref}   % Cross referencing
+
+ \DocInclude{ltproperties}   % Extended Cross referencing
 
  \DocInclude{ltmiscen} % Miscellaneous environment definitions.
 

base/format.ins

@@ -192,6 +192,7 @@ the system are in the document `cfgguide.tex'.
           \from{lttextcomp.dtx}{2ekernel}
           \from{ltpageno.dtx}{2ekernel}
           \from{ltxref.dtx}{2ekernel}
+          \from{ltproperties.dtx}{2ekernel}
           \from{ltmiscen.dtx}{2ekernel}
           \from{ltmath.dtx}{2ekernel}
           \from{ltlists.dtx}{2ekernel}

base/latexrelease.ins

@@ -119,6 +119,7 @@ extension .ins) which are part of the distribution.
   \from{lttextcomp.dtx}  {latexrelease}%
   \from{ltpageno.dtx}    {latexrelease}% empty
   \from{ltxref.dtx}      {latexrelease}% empty
+  \from{ltproperties.dtx}{latexrelease}%
   \from{ltmiscen.dtx}    {latexrelease}%
   \from{ltmath.dtx}      {latexrelease}%
   \from{ltlists.dtx}     {latexrelease}% empty

base/ltmiscen.dtx

@@ -32,7 +32,7 @@
 %<*driver>
 % \fi
 \ProvidesFile{ltmiscen.dtx}
-             [2023/09/01 v1.2c LaTeX Kernel (Misc. Environments)]
+             [2023/09/06 v1.2c LaTeX Kernel (Misc. Environments)]
 % \iffalse
 \documentclass{ltxdoc}
 \GetFileInfo{ltmiscen.dtx}
@@ -194,8 +194,8 @@
 %    \begin{macrocode}
 %</2ekernel>
 %<*2ekernel|latexrelease>
-%<latexrelease>\IncludeInRelease{2020/10/01}%
-%<latexrelease>                 {\enddocument}{Use Hooks}%
+%<latexrelease>\IncludeInRelease{2023/11/01}%
+%<latexrelease>                 {\enddocument}{check property labels}%
 \def\enddocument{%
 %    \end{macrocode}
 %    The |\end{document}| hook is executed first. If necessary it can
@@ -230,6 +230,10 @@
        \let\@setckpt\@gobbletwo
        \let\@newl@bel\@testdef
 %    \end{macrocode}
+% \changes{v1.2b}{2023/09/06}{Test changes of values in \cs{new@label@record}}
+%    \begin{macrocode}
+       \let\new@label@record\@kernel@new@label@record@testdef
+%    \end{macrocode}
 % \changes{v1.0z}{1995/07/13}{Shorten redefinition of \cs{bibcite} and
 %          \cs{newlabel}}
 %    The previous line is equiv to setting
@@ -357,6 +361,67 @@
 %    \begin{macrocode}
 %</2ekernel|latexrelease>
 %<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}%
+%<latexrelease>                 {\enddocument}{Use Hooks}%
+%<latexrelease>\def\enddocument{%
+%<latexrelease>   \@kernel@before@enddocument
+%<latexrelease>   \UseOneTimeHook{enddocument}%
+%<latexrelease>   \@kernel@after@enddocument
+%<latexrelease>   \@checkend{document}%
+%<latexrelease>   \clearpage
+%<latexrelease>   \UseOneTimeHook{enddocument/afterlastpage}%
+%<latexrelease>   \@kernel@after@enddocument@afterlastpage
+%<latexrelease>   \begingroup
+%<latexrelease>     \if@filesw
+%<latexrelease>       \immediate\closeout\@mainaux
+%<latexrelease>       \let\@setckpt\@gobbletwo
+%<latexrelease>       \let\@newl@bel\@testdef
+%<latexrelease>       \@tempswafalse
+%<latexrelease>       \makeatletter \@@input\jobname.aux
+%<latexrelease>     \fi
+%<latexrelease>     \UseOneTimeHook{enddocument/afteraux}%
+%<latexrelease>     \UseOneTimeHook{enddocument/info}%
+%<latexrelease>   \endgroup
+%<latexrelease>   \UseOneTimeHook{enddocument/end}%
+%<latexrelease>   \deadcycles\z@\@@end}
+%<latexrelease>\NewHook{enddocument}
+%<latexrelease>\NewHook{enddocument/afterlastpage}
+%<latexrelease>\NewHook{enddocument/afteraux}
+%<latexrelease>\NewHook{enddocument/info}
+%<latexrelease>\NewHook{enddocument/end}
+%<latexrelease>\AddToHook{enddocument/info}[kernel/filelist]{\@dofilelist}
+%<latexrelease>\AddToHook{enddocument/info}[kernel/warnings]{\@enddocument@kernel@warnings}
+%<latexrelease>\AddToHook{enddocument/info}[kernel/release]{%
+%<latexrelease>   \let\show@release@info\wlog
+%<latexrelease>   \show@release@info{ ***********}%
+%<latexrelease>   \the\LaTeXReleaseInfo
+%<latexrelease>   \show@release@info{ ***********}}
+%<latexrelease>
+%<latexrelease>\DeclareHookRule{enddocument/info}{kernel/release}{before}{kernel/filelist}
+%<latexrelease>\DeclareHookRule{enddocument/info}{kernel/filelist}{before}{kernel/warnings}
+%<latexrelease>\def\@enddocument@kernel@warnings{%
+%<latexrelease>   \ifdim \font@submax >\fontsubfuzz\relax
+%<latexrelease>     \@font@warning{Size substitutions with differences\MessageBreak
+%<latexrelease>                up to \font@submax\space have occurred.\@gobbletwo}%
+%<latexrelease>   \fi
+%<latexrelease>   \@defaultsubs
+%<latexrelease>   \@refundefined
+%<latexrelease>   \if@filesw
+%<latexrelease>     \ifx \@multiplelabels \relax
+%<latexrelease>       \if@tempswa
+%<latexrelease>         \@latex@warning@no@line{Label(s) may have changed.
+%<latexrelease>             Rerun to get cross-references right}%
+%<latexrelease>       \fi
+%<latexrelease>     \else
+%<latexrelease>       \@multiplelabels
+%<latexrelease>     \fi
+%<latexrelease>     \ifx \@extra@page@added \relax
+%<latexrelease>         \@latex@warning@no@line{Temporary extra page added at the end.
+%<latexrelease>             Rerun to get it removed}%
+%<latexrelease>     \fi
+%<latexrelease>   \fi
+%<latexrelease>}
+%<latexrelease>\EndIncludeInRelease
 %<latexrelease>\IncludeInRelease{0000/00/00}%
 %<latexrelease>                 {\enddocument}{Use Hooks}%
 %<latexrelease>