add user interface

CHANGELOG.md

@@ -9,6 +9,7 @@ this project uses date-based 'snapshot' version identifiers.
 
 ### Changed
  - \tag_stop:n and \tag_start:n no longer expand key in debug mode.
+ - speeding up the creation of Ref keys
 
 ## [2024-08-02]
 Version 0.99d

doc/tagpdf.tex

@@ -1881,6 +1881,21 @@ \subsubsection{Commands to define the structure}
 
 \subsubsection{Handling the \texttt{Ref} key in structures}\label{sec:Refkey}
 
+Structures that cross reference other structures, e.g. citation commands, table of 
+content entries, footnote require often a \texttt{Ref} key. \texttt{Ref}
+can be added with the |ref| key if \cs{tagstructbegin} described above
+but as it is a task that often has to be done automatically in code
+there exist also a command. The target structure of a \texttt{Ref} key
+can be identified with three methods: through a label name set with the |label| key,
+through a destination name if a \cs{MakeLinkTarget} has been used in 
+the target structure---this also works if hyperref has not been loaded---and through
+the structure number, which has been stored e.g. in a label.    
+
+\begin{docCommands}
+ {  
+  {doc name=\tag_struct_gput_ref:nnn,doc parameter=\marg{structure number}\marg{keyword}\marg{value}},
+ }\end{docCommands}
+
 
 
 \subsubsection{Root structure}

tagpdf-struct.dtx

@@ -120,6 +120,18 @@
 % the third the value. Currently the only keyword is \texttt{ref} which updates
 % the Ref key (an array)
 % \end{function}
+%
+% \begin{function}{\tag_struct_gput_ref:nnn}
+% \begin{syntax}
+%  \cs{tag_struct_gput_ref:nnn}\Arg{structure number}\Arg{keyword}\Arg{value}
+%  \end{syntax}
+% This is an user interface to add a Ref key to an
+% existing structure. The target structure doesn't have to exist yet
+% but can be addressed by label, destname or even num.
+% \meta{keyword} is currently either \texttt{label}, \texttt{dest}
+% or \texttt{num}. The value is then either a label name, the name of a destination
+% or a structure number.
+% \end{function}
 % 
 % \section{Public keys}
 % \subsection{Keys for the structure commands}
@@ -1316,23 +1328,12 @@
         \tl_clear:N\l_@@_tmpa_tl
         \clist_map_inline:on {#1}
           {
-            \tl_put_right:Nn \l_@@_tmpa_tl
-              {\@@_struct_Ref_label:nN{##1},}
+            \tl_put_right:Ne \l_@@_tmpa_tl
+              {\exp_not:N\@@_struct_Ref_label:nN{##1},}
           }
         \@@_struct_gput_data_ref:no 
          { \int_use:N \c@g_@@_struct_abs_int } {\l_@@_tmpa_tl}
       },
-    refdest .code:n        = % ref property
-      {
-        \tl_clear:N\l_@@_tmpa_tl
-        \clist_map_inline:on {#1}
-          {
-            \tl_put_right:Nn \l_@@_tmpa_tl
-              {\@@_struct_Ref_dest:nN{##1},}
-          }
-        \@@_struct_gput_data_ref:no 
-         { \int_use:N \c@g_@@_struct_abs_int } {\l_@@_tmpa_tl}
-      },     
     E .code:n        = % E property
       {
         \str_set_convert:Nnon
@@ -1959,10 +1960,19 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\tag_struct_add_ref:nnn}
+% \begin{macro}{\tag_struct_gput_ref:nnn}
+% This is an user interface to add a Ref key to an
+% existing structure. The target structure doesn't have to exist yet
+% but can be addressed by label, destname or even num.
 %    \begin{macrocode}
+%<base>\cs_new_protected:Npn \tag_struct_gput_ref:nnn #1 #2 #3{}
 %<*package>
-
+\cs_set_protected:Npn \tag_struct_gput_ref:nnn #1 #2 #3 
+%#1 structnum, #2 label, dest or num, #3 value 
+  {
+    \@@_struct_gput_data_ref:no 
+         { #1 } {\cs:w @@_struct_Ref_#2:nN \cs_end: { #3 } , }
+  }
 %</package>
 %    \end{macrocode}
 % \end{macro}

tagpdf.dtx

@@ -200,10 +200,7 @@
   {
     \cs_set_protected:Npn \__fnote_gput_ref:nn #1 #2 %#1 the structure number receiving the ref #2
       {
-        \tag_if_active:T
-          {
-            \tag_struct_gput:nnn {#1}{ref}{\@@_struct_Ref_num:nN { #2 }}
-          }
+        \tag_struct_gput_ref:nnn {#1}{num}{#2}
       }
   }
 \AddToHook{package/latex-lab-testphase-toc/after}
@@ -212,9 +209,7 @@
       {
         \prop_map_inline:Nn\g_@@_struct_ref_by_dest_prop
           {
-            \@@_struct_gput_data_ref:nn
-              { ##1 }
-              { \@@_struct_Ref_dest:nN{ ##2 }}
+            \tag_struct_gput_ref:nnn {##1}{dest}{##2}
           }
       }
   }