[latex3-commits] [latex3/tagpdf] faster-ref: add user interface (b650312)

[github at latex-project.org]

Repository : https://github.com/latex3/tagpdf
On branch  : faster-ref
Link       : https://github.com/latex3/tagpdf/commit/b65031217e4ffcb3268b2a48132039d6646d8726

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

commit b65031217e4ffcb3268b2a48132039d6646d8726
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Wed Sep 11 00:50:04 2024 +0200

    add user interface


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

b65031217e4ffcb3268b2a48132039d6646d8726
 CHANGELOG.md      |  1 +
 doc/tagpdf.tex    | 15 +++++++++++++++
 tagpdf-struct.dtx | 40 +++++++++++++++++++++++++---------------
 tagpdf.dtx        |  9 ++-------
 4 files changed, 43 insertions(+), 22 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d7ac480..594be7a 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/doc/tagpdf.tex b/doc/tagpdf.tex
index 1e1516a..50d56d9 100644
--- a/doc/tagpdf.tex
+++ b/doc/tagpdf.tex
@@ -1881,6 +1881,21 @@ structure already has a parent you will get a warning.
 
 \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}
diff --git a/tagpdf-struct.dtx b/tagpdf-struct.dtx
index c3e644a..f4c7dd3 100644
--- a/tagpdf-struct.dtx
+++ b/tagpdf-struct.dtx
@@ -121,6 +121,18 @@
 % 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}
 % \begin{function}{tag (struct-key)}
@@ -1316,19 +1328,8 @@
         \tl_clear:N\l_@@_tmpa_tl
         \clist_map_inline:on {#1}
           {
-            \tl_put_right:Nn \l_@@_tmpa_tl
-              {\@@_struct_Ref_label:nN{##1},}
-          }
-        \@@_struct_gput_data_ref:no 
-         { \int_use:N \c at 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},}
+            \tl_put_right:Ne \l_@@_tmpa_tl
+              {\exp_not:N\@@_struct_Ref_label:nN{##1},}
           }
         \@@_struct_gput_data_ref:no 
          { \int_use:N \c at g_@@_struct_abs_int } {\l_@@_tmpa_tl}
@@ -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}
diff --git a/tagpdf.dtx b/tagpdf.dtx
index f03c9b2..4842bff 100644
--- a/tagpdf.dtx
+++ b/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}
           }
       }
   }