integrate ltproperties

latex3 · Sep 6, 2023 · 6a2b510 · 6a2b510
1 parent ae12fe1
commit 6a2b510
Show file tree

Hide file tree

Showing 25 changed files with 1,315 additions and 11 deletions.
diff --git a/base/changes.txt b/base/changes.txt
@@ -6,7 +6,13 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
-2023-08-19 Joseph Wright  <Joseph.Wright@latex-project.org>
+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-08-19 Joseph Wright  <Joseph.Wright@latex-project.org> 
 
 	* ltcmd.dtx, usrguide.tex
 	Remove \GetDocumentCommandArgSpec,

diff --git a/base/doc/ltnews38.tex b/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 (not 
+expandable)  commands \cs{ref} and \cs{pageref} in arbitrary places of a 
+document.  With the summer release 2023 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 \LaTeX2e camel case commands and expl3 commands.    
+
+For documentation see \texttt{texdoc ltproperties-doc}. 
 
 \section{New or improved commands}
 

diff --git a/base/doc/ltproperties-code.tex b/base/doc/ltproperties-code.tex
@@ -0,0 +1,5 @@
+% This will typeset documentation + code
+%
+
+\AtBeginDocument{\AlsoImplementation}
+\input{ltproperties.dtx}
diff --git a/base/doc/ltproperties-doc.tex b/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}
diff --git a/base/doc/source2e.tex b/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.
 

diff --git a/base/format.ins b/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}

diff --git a/base/latexrelease.ins b/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

diff --git a/base/ltmiscen.dtx b/base/ltmiscen.dtx
@@ -32,7 +32,7 @@
 %<*driver>
 % \fi
 \ProvidesFile{ltmiscen.dtx}
-             [2022/11/06 v1.2a LaTeX Kernel (Misc. Environments)]
+             [2023/09/06 v1.2b 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>

diff --git a/base/ltproperties.dtx b/base/ltproperties.dtx
@@ -31,7 +31,7 @@
 \EnableCrossrefs
 \CodelineIndex
 \begin{document}
-  \DocInput{\jobname.dtx}
+  \DocInput{ltproperties.dtx}
 \end{document}
 %</driver>
 % \fi
@@ -433,7 +433,7 @@
 %
 % \begin{implementation}
 %
-% \section{\pkg{ltproperty} implementation}
+% \section{The Implementation}
 %
 %    \begin{macrocode}
 %<*2ekernel|latexrelease>
@@ -684,17 +684,13 @@
   }  
 %    \end{macrocode}
 %
-% That is the nearest hook for the test if something has changed.
+% This command is used in \cs{enddocument} to test if some label values haved changed.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@kernel@new@label@record@testdef #1 #2
   {
     \tl_if_eq:cnF { r@#1 } {#2} 
       { \@tempswatrue }
   }
-\AddToHook { enddocument / afterlastpage }
-  {
-    \let \new@label@record \@kernel@new@label@record@testdef
-  }  
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}

diff --git a/base/testfiles/properties-001.lvt b/base/testfiles/properties-001.lvt
@@ -0,0 +1,76 @@
+\RequirePackage[enable-debug ,check-declarations]{expl3}
+\ExplSyntaxOn
+\debug_on:n { deprecation }
+\ExplSyntaxOff
+\documentclass{article}
+\input{regression-test}
+\newcounter{test}
+\begin{document}
+\START \pagenumbering{roman} \label{blub} 
+\section{Spacing}
+\showoutput 
+aaaa \RecordProperties{test1}{page,abspage,currentlabel} aaaa 
+
+\ExplSyntaxOn
+aaaa~\property_record:nn{test2}{page,abspage,currentlabel}~aaaa
+\ExplSyntaxOff 
+
+\section{Expansion}
+
+\newcommand\mylist{page,abspage,currentlabel}
+\setcounter{test}{3}
+aaaa \RecordProperties{test\arabic{test}}{\mylist} aaaa 
+
+\stepcounter{test}
+\ExplSyntaxOn
+\TEST{wrong expansion (error)}
+ {
+   aaaa~\property_record:nn{test\arabic{test}}{\mylist}~aaaa\par
+ }  
+
+\stepcounter{test}
+aaaa~\property_record:xx{test\arabic{test}}{\mylist}~aaaa\par
+
+
+aaaa~\property_record:nV{test6}\mylist~aaaa\par
+\ExplSyntaxOff 
+
+\section{References}
+
+\TEST{ LaTeX2e reference commands}
+{
+ \TYPE{page}
+ \TYPE{\RefProperty{test1}{page}} 
+ \TYPE{abspage}
+ \TYPE{\RefProperty{test1}{abspage}} 
+ \TYPE{currentlabel}
+ \TYPE{\RefProperty{test1}{currentlabel}}
+ \TYPE{unknown label}
+ \TYPE{\RefProperty{unknown}{currentlabel}}
+ \TYPE{\RefProperty[UNKNOWN]{unknown}{page}}
+} 
+
+\ExplSyntaxOn
+\TEST{expl3~reference~commands}
+ {
+   \TYPE{page}
+   \TYPE{\property_ref:nn {test1}{page}}
+   \TYPE{abspage}
+   \TYPE{\property_ref:nn {test1}{abspage}}
+   \TYPE{currentlabel}
+   \TYPE{\property_ref:nn {test1}{currentlabel}}
+   \TYPE{unknown~label}
+   \TYPE{\property_ref:nn {unknown}{currentlabel}}
+   \TYPE{\property_ref:nnn{unknown}{currentlabel}{UNKNOWN}}
+ }   
+\ExplSyntaxOff
+
+\section{Unknown property (should error)}
+
+\TEST{set unknown property (error)}
+ {\RecordProperties{test7}{unknown}}
+
+\TEST{ref unknown property (error)}
+ {\RefProperty{test1}{unknown}}
+
+\end{document}