summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tagpdf/tagpdf-user.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-12-19 03:00:50 +0000
committerNorbert Preining <norbert@preining.info>2023-12-19 03:00:50 +0000
commit60e9a31bad8271499f6b5f9280174e76bd62814f (patch)
treec33ee4a5f7e5fb95bab9a06c6a5121e1f4728db1 /macros/latex/contrib/tagpdf/tagpdf-user.dtx
parente7154d152b4c047832de9bd4cf0d2bc3efe4125a (diff)
CTAN sync 202312190300
Diffstat (limited to 'macros/latex/contrib/tagpdf/tagpdf-user.dtx')
-rw-r--r--macros/latex/contrib/tagpdf/tagpdf-user.dtx131
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}
{