diff options
author | Norbert Preining <norbert@preining.info> | 2023-12-19 03:00:50 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-12-19 03:00:50 +0000 |
commit | 60e9a31bad8271499f6b5f9280174e76bd62814f (patch) | |
tree | c33ee4a5f7e5fb95bab9a06c6a5121e1f4728db1 /macros/latex/contrib/tagpdf/tagpdf-user.dtx | |
parent | e7154d152b4c047832de9bd4cf0d2bc3efe4125a (diff) |
CTAN sync 202312190300
Diffstat (limited to 'macros/latex/contrib/tagpdf/tagpdf-user.dtx')
-rw-r--r-- | macros/latex/contrib/tagpdf/tagpdf-user.dtx | 131 |
1 files changed, 104 insertions, 27 deletions
diff --git a/macros/latex/contrib/tagpdf/tagpdf-user.dtx b/macros/latex/contrib/tagpdf/tagpdf-user.dtx index 704a2f769d..5f1a72a3e8 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-user.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-user.dtx @@ -18,7 +18,7 @@ % % The development version of the bundle can be found at % -% https://github.com/u-fischer/tagpdf +% https://github.com/latex3/tagpdf % % for those people who are interested. %<*driver> @@ -46,7 +46,7 @@ % }^^A % } % -% \date{Version 0.98q, released 2023-11-19} +% \date{Version 0.98r, released 2023-12-18} % \maketitle % \begin{documentation} % \section{Setup commands} @@ -159,7 +159,7 @@ % \end{function} % % \section{Extension commands} -% The following commands and code parts are not core command of tagpdf. +% The following commands and code parts are not core commands of tagpdf. % They either provide work-arounds for missing functionality elsewhere, % or do a first step to apply tagpdf commands to document commands. % @@ -250,7 +250,7 @@ % \begin{macrocode} %<@@=tag> %<*header> -\ProvidesExplPackage {tagpdf-user} {2023-11-19} {0.98q} +\ProvidesExplPackage {tagpdf-user} {2023-12-18} {0.98r} {tagpdf - user commands} %</header> % \end{macrocode} @@ -346,7 +346,91 @@ % \end{macrocode} % \end{macro} % +% \section{Socket support} +% The next \LaTeX{} will use special sockets for the tagging. +% +% These sockets will use names starting +% with \texttt{tagsupport/}. Usually, these sockets have exactly two +% plugs defined: \texttt{noop} (when no tagging is requested or +% tagging is not wanted for some reason) and +% a second plug that enables the tagging. There +% may be more, e.g., tagging with special debugging, etc., but right +% now it is usually just on or off. +% +% Given that we sometimes have to suspend tagging, it would be fairly +% inefficient to put different plugs into these sockets whenever that +% happens. We therefore offer \cs{UseTaggingSocket} which is like +% \cs{UseSocket} except that the socket name is specified without +% \texttt{tagsupport/}, i.e., +% \begin{quote} +% \verb=\UseTaggingSocket{foo}= $\to$ +% \verb=\UseSocket{tagsupport/foo}= +% \end{quote} +% Beside being slightly shorter, the big advantage is that this way +% we can change \cs{UseTaggingSocket} to do nothing by switching a boolean +% instead of changing the plugs of the tagging support sockets back and forth. +% +% It is possible to use the tagging support sockets with +% \cs{UseSocket} directly, but in this case the socket remains active +% if e.g. \cs{SuspendTagging} is in force. There may be reasons for doing +% that but in general we expect to always use \cs{UseTaggingSocket}. +% +% The L3 programming layer versions \cs{tag_socket_use:n} and +% \cs{tag_socket_use:nn} are slightly more efficient than +% \cs{UseTaggingSocket} because they do not have to determine how +% many arguments the socket takes when disabling it. +% +% Until we can be sure that the kernel defines the commands we provide them before +% redefining them: +% \begin{macrocode} +%<*base> +\providecommand\tag_socket_use:n[1]{} +\providecommand\tag_socket_use:nn[2]{} +\providecommand\UseTaggingSocket[1]{} +%</base> +% \end{macrocode} % +% \begin{macro}{\tag_socket_use:n,\tag_socket_use:nn,\UseTaggingSocket} +% \begin{macrocode} +%<*package> +\cs_set_protected:Npn \tag_socket_use:n #1 + { + \bool_if:NT \l_@@_active_socket_bool + { \UseSocket {tagsupport/#1} } + } +% \end{macrocode} +% +% \begin{macrocode} +\cs_set_protected:Npn \tag_socket_use:nn #1#2 + { + \bool_if:NT \l_@@_active_socket_bool + { \UseSocket {tagsupport/#1} {#2} } + } +% \end{macrocode} +% +% \begin{macrocode} +\cs_set_protected:Npn \UseTaggingSocket #1 + { + \bool_if:NTF \l_@@_active_socket_bool + { \UseSocket{tagsupport/#1} } + { + \int_case:nnF + { \int_use:c { c__socket_tagsupport/#1_args_int } } + { + 0 \prg_do_nothing: + 1 \use_none:n + 2 \use_none:nn +% \end{macrocode} +% We do not expect tagging sockets with more than one or two +% arguments, so for now we only provide those. +% \begin{macrocode} + } + \ERRORusetaggingsocket + } + } +%</package> +% \end{macrocode} +% \end{macro} % % \section{Debugging} % \begin{macro}{\ShowTagging} @@ -550,22 +634,17 @@ % \end{macro} % % \section{Commands to extend document commands} -% The following commands and code parts are not core command of tagpdf. +% The following commands and code parts are not core commands of tagpdf. % They either provide work-arounds for missing functionality elsewhere, % or do a first step to apply tagpdf commands to document commands. % This part should be regularly revisited to check if the code should go to a % better place or can be improved. % -% \subsection{new ref system} -% Until l3ref is in the kernel, we provide a definition for \cs{newlabeldata} in -% the aux-file to avoid errors if a document switches between tagging and non-tagging. % \begin{macrocode} -%<base>\AddToHook{begindocument} -%<base> {\immediate\write\@mainaux{\string\providecommand\string\newlabeldata[2]{}}} %<*package> % \end{macrocode} % \subsection{Document structure} -% \begin{macro}{\g_@@_root_default_tl,activate (setup-key)} +% \begin{macro}{\g_@@_root_default_tl,activate (setup-key),activate-socket (setup-key)} % \begin{macrocode} \tl_new:N\g_@@_root_default_tl \tl_gset:Nn\g_@@_root_default_tl {Document} @@ -574,11 +653,12 @@ \hook_gput_code:nnn{tagpdf/finish/before}{tagpdf}{\tagstructend} \keys_define:nn { @@ / setup} - { + { + activate-socket .bool_set:N = \l_@@_active_socket_bool, activate .code:n = { \keys_set:nn { @@ / setup } - { activate-mc,activate-tree,activate-struct } + { activate-mc,activate-tree,activate-struct,activate-socket } \tl_gset:Nn\g_@@_root_default_tl {#1} }, activate .default:n = Document @@ -586,24 +666,22 @@ % \end{macrocode} % \end{macro} +% % \subsection{Structure destinations} -% In TeXlive 2022 pdftex and luatex will offer support for structure destinations. -% The pdfmanagement has already backend support. We activate them if the -% prerequisites are there: structures should be activated, -% the code in the pdfmanagement must be there. +% Since TeXlive 2022 pdftex and luatex offer support for structure destinations +% and the pdfmanagement has backend support for. We activate them if +% structures are actually created. % Structure destinations are actually PDF 2.0 only but they don't harm in % older PDF and can improve html export. % \begin{macrocode} \AddToHook{begindocument/before} { - \bool_lazy_all:nT - { - { \g_@@_active_struct_dest_bool } - { \g_@@_active_struct_bool } - { \cs_if_exist_p:N \pdf_activate_structure_destination: } - } + \bool_lazy_and:nnT + { \g_@@_active_struct_dest_bool } + { \g_@@_active_struct_bool } { - \tl_set:Nn \l_pdf_current_structure_destination_tl { _@@/struct/\g_@@_struct_stack_current_tl } + \tl_set:Nn \l_pdf_current_structure_destination_tl + { _@@/struct/\g_@@_struct_stack_current_tl } \pdf_activate_structure_destination: } } @@ -643,11 +721,10 @@ % \l_@@_para_main_tag_tl} % At first some variables. % \begin{macrocode} -\bool_new:N \l_@@_para_bool %</package> %<base>\bool_new:N \l_@@_para_flattened_bool +%<base>\bool_new:N \l_@@_para_bool %<*package> -\bool_new:N \l_@@_para_show_bool \int_new:N \g_@@_para_begin_int \int_new:N \g_@@_para_end_int \int_new:N \g_@@_para_main_begin_int @@ -721,7 +798,7 @@ % \end{macrocode} % \end{macro} % -% TEMPORARLY FIX (2023-11-17). Until latex-lab is update we must adapt a sec command: +% TEMPORARLY FIX (2023-11-17). Until latex-lab is updated we must adapt a sec command: % \begin{macrocode} \AddToHook{package/latex-lab-testphase-sec/after} { |