summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tagpdf/tagpdf-struct.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tagpdf/tagpdf-struct.dtx')
-rw-r--r--macros/latex/contrib/tagpdf/tagpdf-struct.dtx181
1 files changed, 154 insertions, 27 deletions
diff --git a/macros/latex/contrib/tagpdf/tagpdf-struct.dtx b/macros/latex/contrib/tagpdf/tagpdf-struct.dtx
index 103e337e9d..a476e3cf86 100644
--- a/macros/latex/contrib/tagpdf/tagpdf-struct.dtx
+++ b/macros/latex/contrib/tagpdf/tagpdf-struct.dtx
@@ -46,7 +46,7 @@
% }^^A
% }
%
-% \date{Version 0.95, released 2022-05-29}
+% \date{Version 0.96, released 2022-08-06}
% \maketitle
% \begin{documentation}
% \section{Public Commands}
@@ -67,6 +67,18 @@
% A structure should be used only once,
% if the structure already has a parent a warning is issued.
% \end{function}
+% \begin{function}{\tag_struct_object_ref:n,\tag_struct_object_ref:e}
+% \begin{syntax}
+% \cs{tag_struct_object_ref:n}\Arg{struct number}
+% \end{syntax}
+% This is a small wrapper around |\pdf_object_ref:n| to retrieve the
+% object reference of the structure with the number \meta{struct number}.
+% This number can be retrieved and stored for the current structure
+% for example with \cs{tag_get:n}\Arg{struct_num}. Be aware that it can only
+% be used if the structure has already been created and that it doesn't check
+% if the object actually exists!
+% \end{function}
+%
% The following two functions are used to add annotations. They must be used
% together and with care to get the same numbers. Perhaps some improvements are needed
% here.
@@ -109,8 +121,21 @@
% \end{function}
% \begin{function}{label (struct-key)}
% This key sets a label by which
-% one can use the structure later in another structure.
-% Internally the label name will start with \texttt{tagpdfstruct-}.
+% one can refer to the structure. It is e.g.
+% used by \cs{tag_struct_use:n} (where a real label is actually not
+% needed as you can only use structures already defined), and by the
+% |ref| key (which can refer to future structures).
+% Internally the label name will start with \texttt{tagpdfstruct-} and it stores
+% the two attributs |tagstruct| (the structure number) and |tagstructobj| (the
+% object reference).
+% \end{function}
+% \begin{function}{parent (struct-key)}
+% By default a structure is added as kid to the currently active structure.
+% With the parent key one can choose another parent. The value is a structure number which
+% must refer to an already existing, previously created structure. Such a structure
+% number can for example be have been stored with \cs{tag_get:n}, but one can also use
+% a label on the parent structure and then use
+% \cs{ref_value:nn}|{tagpdfstruct-label}{tagstruct}| to retrieve it.
% \end{function}
% \begin{function}{title (struct-key),title-o (struct-key)}
% This keys allows to set the dictionary entry
@@ -119,7 +144,7 @@
% Commands are not expanded. |title-o| will expand the value once.
% \end{function}
%
-% \begin{function}{alttext (struct-key)}
+% \begin{function}{alt (struct-key)}
% This key inserts an \texttt{/Alt} value in the dictionary of structure object.
% The value is handled as verbatim string and hex encoded.
% The value will be expanded first once.
@@ -217,7 +242,7 @@
% \begin{macrocode}
%<@@=tag>
%<*header>
-\ProvidesExplPackage {tagpdf-struct-code} {2022-05-29} {0.95}
+\ProvidesExplPackage {tagpdf-struct-code} {2022-08-06} {0.96}
{part of tagpdf - code related to storing structure}
%</header>
% \end{macrocode}
@@ -274,10 +299,14 @@
% \end{variable}
%
% \begin{variable}{\g_@@_struct_stack_current_tl,\l_@@_struct_stack_parent_tmpa_tl}
-% The global variable will hold the current structure number.
+% The global variable will hold the current structure number. It is already
+% defined in \texttt{tagpdf-base}.
% The local temporary variable will hold the parent when we fetch it from the stack.
% \begin{macrocode}
-\tl_new:N \g_@@_struct_stack_current_tl
+%</package>
+%<base>\tl_new:N \g_@@_struct_stack_current_tl
+%<base>\tl_gset:Nn \g_@@_struct_stack_current_tl {\int_use:N\c@g_@@_struct_abs_int}
+%<*package>
\tl_new:N \l_@@_struct_stack_parent_tmpa_tl
% \end{macrocode}
% \end{variable}
@@ -617,6 +646,7 @@
% \end{macrocode}
% \end{macro}
+% \subsection{Output of the object}
% \begin{macro}{\@@_struct_get_dict_content:nN}
% This maps the dictionary content of a structure into a tl-var.
% Basically it does what |\pdfdict_use:n| does.
@@ -639,13 +669,32 @@
{ g_@@_struct_#1_prop }
{ ##1 }
{
- \c_space_tl/##1~\prop_item:cn{ g_@@_struct_#1_prop } { ##1 }
+ \c_space_tl/##1~
+% \end{macrocode}
+% Some keys needs the option to format the key, e.g. add brackets for an
+% array
+% \begin{macrocode}
+ \cs_if_exist_use:cTF {@@_struct_format_##1:e}
+ {
+ { \prop_item:cn{ g_@@_struct_#1_prop } { ##1 } }
+ }
+ {
+ \prop_item:cn{ g_@@_struct_#1_prop } { ##1 }
+ }
}
}
}
}
% \end{macrocode}
% \end{macro}
+% \begin{macro}{\@@_struct_format_Ref:n}
+% Ref is an array, we store only the content to be able to extend it
+% so the formatting command adds the brackets:
+% \begin{macrocode}
+\cs_new:Nn\__tag_struct_format_Ref:n{[#1]}
+\cs_generate_variant:Nn\__tag_struct_format_Ref:n{e}
+% \end{macrocode}
+% \end{macro}
% \begin{macro}{\@@_struct_write_obj:n}
% This writes out the structure object.
% This is done in the finish code, in the tree module and
@@ -658,7 +707,7 @@
\@@_struct_fill_kid_key:n { #1 }
\@@_struct_get_dict_content:nN { #1 } \l_@@_tmpa_tl
\exp_args:Nx
- \pdf_object_write:nx
+ \pdf_object_write_dict:nx
{ @@/struct/#1 }
{
\l_@@_tmpa_tl
@@ -744,7 +793,7 @@
\exp_args:Ne
\tl_tail:n
{
- \prop_item:cn {g_@@_struct_\g__tag_struct_stack_current_tl _prop}{S}
+ \prop_item:cn {g_@@_struct_\g_@@_struct_stack_current_tl _prop}{S}
}
}
%</package>
@@ -758,7 +807,7 @@
%<*base>
\cs_new:Npn \@@_get_data_struct_num:
{
- \int_use:N\c@g_@@_struct_abs_int
+ \g_@@_struct_stack_current_tl
}
%</base>
% \end{macrocode}
@@ -772,10 +821,11 @@
% {
% label (struct-key),
% stash (struct-key),
+% parent (struct-key),
% tag (struct-key),
% title (struct-key),
% title-o (struct-key),
-% alttext (struct-key),
+% alt (struct-key),
% actualtext (struct-key),
% lang (struct-key),
% ref (struct-key),
@@ -787,9 +837,26 @@
{
label .tl_set:N = \l_@@_struct_key_label_tl,
stash .bool_set:N = \l_@@_struct_elem_stash_bool,
+ parent .code:n =
+ {
+ \bool_lazy_and:nnTF
+ {
+ \prop_if_exist_p:c { g_@@_struct_\int_eval:n {#1}_prop }
+ }
+ {
+ \int_compare_p:nNn {#1}<{\c@g_@@_struct_abs_int}
+ }
+ { \tl_set:Nx \l_@@_struct_stack_parent_tmpa_tl { \int_eval:n {#1} } }
+ {
+ \msg_warning:nnxx { tag } { struct-unknown }
+ { \int_eval:n {#1} }
+ { parent~key~ignored }
+ }
+ },
+ parent .default:n = {-1},
tag .code:n = % S property
{
- \seq_set_split:Nne \l_@@_tmpa_seq { / } {#1/\prop_item:Nn\g__tag_role_tags_NS_prop{#1}}
+ \seq_set_split:Nne \l_@@_tmpa_seq { / } {#1/\prop_item:No\g__tag_role_tags_NS_prop{#1}}
\tl_gset:Nx \g_@@_struct_tag_tl { \seq_item:Nn\l_@@_tmpa_seq {1} }
\tl_gset:Nx \g_@@_struct_tag_NS_tl { \seq_item:Nn\l_@@_tmpa_seq {2} }
\@@_check_structure_tag:N \g_@@_struct_tag_tl
@@ -829,7 +896,7 @@
{ T }
{ <\l_@@_tmpa_str> }
},
- alttext .code:n = % Alt property
+ alt .code:n = % Alt property
{
\str_set_convert:Noon
\l_@@_tmpa_str
@@ -841,6 +908,7 @@
{ Alt }
{ <\l_@@_tmpa_str> }
},
+ alttext .meta:n = {alt=#1},
actualtext .code:n = % ActualText property
{
\str_set_convert:Noon
@@ -860,18 +928,18 @@
{ Lang }
{ (#1) }
},
- ref .code:n = % Lang property
+% \end{macrocode}
+% Ref is an array, the brackets are added through the formatting command.
+% \begin{macrocode}
+ ref .code:n = % ref property
{
\tl_clear:N\l_@@_tmpa_tl
- \clist_map_inline:nn {#1}
+ \clist_map_inline:on {#1}
{
\tl_put_right:Nx \l_@@_tmpa_tl
{~\ref_value:nn{tagpdfstruct-##1}{tagstructobj} }
}
- \@@_prop_gput:cnx
- { g_@@_struct_\int_eval:n {\c@g_@@_struct_abs_int}_prop }
- { Ref }
- { [\l_@@_tmpa_tl] }
+ \@@_struct_gput_data_ref:ee { \int_eval:n {\c@g_@@_struct_abs_int} } {\l_@@_tmpa_tl}
},
E .code:n = % E property
{
@@ -1044,6 +1112,7 @@
{ g_@@_struct_\int_eval:n { \c@g_@@_struct_abs_int }_prop }
{ Type }
{ /StructElem }
+ \tl_set:Nn \l_@@_struct_stack_parent_tmpa_tl {-1}
\keys_set:nn { @@ / struct} { #1 }
\@@_check_structure_has_tag:n { \int_eval:n {\c@g_@@_struct_abs_int} }
\tl_if_empty:NF
@@ -1051,13 +1120,19 @@
{
\@@_ref_label:en{tagpdfstruct-\l_@@_struct_key_label_tl}{struct}
}
- %get the potential parent from the stack:
- \seq_get:NNF
- \g_@@_struct_stack_seq
- \l_@@_struct_stack_parent_tmpa_tl
+% \end{macrocode}
+% The structure number of the parent is either taken from the stack or
+% has been set with the parent key.
+% \begin{macrocode}
+ \int_compare:nNnT { \l_@@_struct_stack_parent_tmpa_tl } = { -1 }
{
- \msg_error:nn { tag } { struct-faulty-nesting }
- }
+ \seq_get:NNF
+ \g_@@_struct_stack_seq
+ \l_@@_struct_stack_parent_tmpa_tl
+ {
+ \msg_error:nn { tag } { struct-faulty-nesting }
+ }
+ }
\seq_gpush:NV \g_@@_struct_stack_seq \c@g_@@_struct_abs_int
\seq_gpush:NV \g_@@_struct_tag_stack_seq \g_@@_struct_tag_tl
\tl_gset:NV \g_@@_struct_stack_current_tl \c@g_@@_struct_abs_int
@@ -1151,9 +1226,61 @@
}
}
}
+%</package>
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\tag_struct_object_ref:n}
+% This is a command that allows to reference a structure. The argument is the
+% number which can be get for the current structure with |\tag_get:n{struct_num}|
+% TODO check if it should be in base too.
+% \begin{macrocode}
+%<*package>
+\cs_new:Npn \tag_struct_object_ref:n #1
+ {
+ \pdf_object_ref:n {@@/struct/#1}
+ }
+\cs_generate_variant:Nn \tag_struct_object_ref:n {e}
% \end{macrocode}
+%
% \end{macro}
%
+% \begin{macro}{\tag_struct_gput:nnn}
+% This is a command that allows to update the data of a structure.
+% The first argument is the
+% number of the structure, the second a keyword referring to a function,
+% the third the value. Currently the only keyword is \texttt{ref}
+% \begin{macrocode}
+\cs_new_protected:Npn \tag_struct_gput:nnn #1 #2 #3
+ {
+ \cs_if_exist_use:cF {@@_struct_gput_data_#2:nn}
+ { %warning??
+ \use_none:nn
+ }
+ {#1}{#3}
+ }
+\cs_generate_variant:Nn \tag_struct_gput:nnn {ene,nne}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_struct_gput_data_ref:nn}
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_struct_gput_data_ref:nn #1 #2
+ % #1 receiving struct num, #2 list of object ref
+ {
+ \prop_get:cnN
+ { g_@@_struct_#1_prop }
+ {Ref}
+ \l_@@_tmpb_tl
+ \@@_prop_gput:cnx
+ { g_@@_struct_#1_prop }
+ { Ref }
+ { \quark_if_no_value:NF\l_@@_tmpb_tl { \l_@@_tmpb_tl\c_space_tl }#2 }
+ }
+\cs_generate_variant:Nn \@@_struct_gput_data_ref:nn {ee}
+% \end{macrocode}
+% \end{macro}
+
% \begin{macro}
% {
% \tag_struct_insert_annot:nn,
@@ -1192,7 +1319,7 @@
% \section{Attributes and attribute classes}
% \begin{macrocode}
%<*header>
-\ProvidesExplPackage {tagpdf-attr-code} {2022-05-29} {0.95}
+\ProvidesExplPackage {tagpdf-attr-code} {2022-08-06} {0.96}
{part of tagpdf - code related to attributes and attribute classes}
%</header>
% \end{macrocode}