diff options
Diffstat (limited to 'macros/latex/contrib/tagpdf/tagpdf-struct.dtx')
-rw-r--r-- | macros/latex/contrib/tagpdf/tagpdf-struct.dtx | 181 |
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} |