summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tagpdf/tagpdf-user.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-01-14 03:01:14 +0000
committerNorbert Preining <norbert@preining.info>2022-01-14 03:01:14 +0000
commit45623da68203ac8d7aa04b779a6ed65c92c3f866 (patch)
tree151ca3ede3ee826360d4b32c0029cfc106346ec9 /macros/latex/contrib/tagpdf/tagpdf-user.dtx
parentee3f9ca89b21a2174f7e427d9d48247b1912e130 (diff)
CTAN sync 202201140301
Diffstat (limited to 'macros/latex/contrib/tagpdf/tagpdf-user.dtx')
-rw-r--r--macros/latex/contrib/tagpdf/tagpdf-user.dtx152
1 files changed, 122 insertions, 30 deletions
diff --git a/macros/latex/contrib/tagpdf/tagpdf-user.dtx b/macros/latex/contrib/tagpdf/tagpdf-user.dtx
index 23737dfc29..2b58d81659 100644
--- a/macros/latex/contrib/tagpdf/tagpdf-user.dtx
+++ b/macros/latex/contrib/tagpdf/tagpdf-user.dtx
@@ -2,7 +2,7 @@
%
%% File: tagpdf-user.dtx
%
-% Copyright (C) 2019-2021 Ulrike Fischer
+% Copyright (C) 2019-2022 Ulrike Fischer
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -50,7 +50,7 @@
% }^^A
% }
%
-% \date{Version 0.92, released 2021-08-27}
+% \date{Version 0.93, released 2022-01-13}
% \maketitle
% \begin{documentation}
% \section{Setup commands}
@@ -60,7 +60,18 @@
% \end{syntax}
% This is the main setup command to adapt the behaviour of tagpdf.
% It can be used in the preamble and in the document (but not all keys make sense there).
+% \end{function}
%
+% \begin{function}{activate (setup-key)}
+% And additional setup key which combine the other activate keys
+% |activate-mc|, |activate-tree|, |activate-struct| and additionally
+% add a document structure.
+% \end{function}
+%
+%
+% \begin{function}{\tagpdfifluatexTF,\tagpdfifluatexT,\tagpdfifpdftexT}
+% small wrappers around engine tests. This functions should not be used and will be removed
+% in one of the next versions.
% \end{function}
%
% \section{Commands related to mc-chunks}
@@ -76,7 +87,7 @@
% and \cs{tagmcend} will issue in horizontal mode an \cs{unskip}.
% \end{function}
%
-% \begin{function}{\tagmcifin}
+% \begin{function}{\tagmcifinTF}
% \begin{syntax}
% \cs{tagmcifin} \Arg{true code}\Arg{false code}
% \end{syntax}
@@ -112,7 +123,7 @@
% necessarly stops the compilation. The keys and their function are described below.
% \end{function}
%
-% \begin{function}{mc-data}
+% \begin{function}{mc-data (show-key)}
% \begin{syntax}
% |mc-data| = \meta{number}
% \end{syntax}
@@ -123,7 +134,7 @@
% newpage. The value is a positive integer and sets the first mc-shown. If no value
% is given, 1 is used and so all mc-chunks created so far are shown.
% \end{function}
-% \begin{function}{mc-current}
+% \begin{function}{mc-current (show-key)}
% \begin{syntax}
% |mc-current|
% \end{syntax}
@@ -131,7 +142,14 @@
% chunk is open it shows only the state of the abs count. It works in all mode,
% but the output in luamode looks different.
% \end{function}
-% \begin{function}{struct-stack}
+% \begin{function}{mc-marks (show-key)}
+% \begin{syntax}
+% |mc-marks| = |show|\verb+|+|use|
+% \end{syntax}
+% This key helps to debug the page marks. It should only be used at shipout in
+% header or footer.
+% \end{function}
+% \begin{function}{struct-stack (show-key)}
% \begin{syntax}
% |struct-stack| = |log|\verb+|+|show|
% \end{syntax}
@@ -163,7 +181,7 @@
% faulty code, e.g. a missing |\par| at the end of a low-level vbox can highly
% confuse the tagging. The tags should be carefully checked if this is used.
%
-% \begin{function}{paratagging,paratagging-show}
+% \begin{function}{paratagging (setup-key),paratagging-show (setup-key)}
% \begin{syntax}
% |paratagging| = |true|\verb+|+|false|\\
% |paratagging-show| = |true|\verb+|+|false|\\
@@ -179,15 +197,34 @@
% faster then |\tagpdfsetup|. But I'm not sure if the names are good.
% \end{function}
%
+% \begin{function}{\tagpdfsuppressmarks}
+% This command allows to suppress the creation of the marks. It takes an argument
+% which should normally be one of the mc-commands, puts a group around it and
+% suppress the marks creation in this group. This command should be used if
+% the begin and end command are at different boxing levels. E.g.
+% \begin{verbatim}
+% \@hangfrom
+% {
+% \tagstructbegin{tag=H1}%
+% \tagmcbegin {tag=H1}%
+% #2
+% }
+% {#3\tagpdfsuppressmarks{\tagmcend}\tagstructend}%
+% \end{verbatim}
+% \end{function}
+%
% \subsection{Header and footer}
-% Header and footer are automatically excluded from tagging. This can for
-% now to allow debugging be disabled with the following key, but probably
-% this key will disappear again. If some real content is in the header and
+% Header and footer are automatically excluded from tagging. This can
+% be disabled with the following key.
+% If some real content is in the header and
% footer, tagging must be restarted there explicitly.
+% The key accepts the values |true| which surrounds the header with an artifact
+% mc-chunk, |false| which disables the automatic tagging, and |pagination| which
+% additionally adds an artifact structure with an pagination attribute.
%
-% \begin{function}{exclude-header-footer}
+% \begin{function}{exclude-header-footer (setup-key)}
% \begin{syntax}
-% |exclude-header-footer| = |true|\verb+|+|false|
+% |exclude-header-footer| = |true|\verb+|+|false|\verb+|+pagination
% \end{syntax}%
% \end{function}
@@ -213,7 +250,7 @@
% \begin{macrocode}
%<@@=tag>
%<*header>
-\ProvidesExplPackage {tagpdf-user} {2021-08-27} {0.92}
+\ProvidesExplPackage {tagpdf-user} {2022-01-13} {0.93}
{tagpdf - user commands}
%</header>
% \end{macrocode}
@@ -288,14 +325,6 @@
% \end{macro}
%
%
-% \begin{macro}{\tagpdfifluatexTF,\tagpdfifluatexT,\tagpdfifpdftexTF}
-% I should deprecate them ...
-% \begin{macrocode}
-\cs_set_eq:NN\tagpdfifluatexTF \sys_if_engine_luatex:TF
-\cs_set_eq:NN\tagpdfifluatexT \sys_if_engine_luatex:T
-\cs_set_eq:NN\tagpdfifpdftexT \sys_if_engine_pdftex:T
-% \end{macrocode}
-% \end{macro}
%
% \section{Debugging}
% \begin{macro}{\ShowTagging}
@@ -310,7 +339,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{mc-data}
+% \begin{macro}{mc-data (show-key)}
% This key is (currently?) relevant for lua mode only.
% It shows the data of all mc-chunks created so far.
% It is accurate only after shipout, so typically should be issued after a
@@ -330,7 +359,7 @@
% \end{macrocode}
% \end{macro}
-% \begin{macro}{mc-current}
+% \begin{macro}{mc-current (show-key)}
% This shows some info about the current mc-chunk. It works in generic and lua-mode.
% \begin{macrocode}
\keys_define:nn { @@ / show }
@@ -397,7 +426,7 @@
}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{mc-marks}
+% \begin{macro}{mc-marks (show-key)}
% It maps the mc-marks into the sequences and then shows them.
% This allows to inspect the first and last mc-Mark on a page.
% It should only be used in the shipout (header/footer).
@@ -447,7 +476,7 @@
}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{struct-stack}
+% \begin{macro}{struct-stack (show-key)}
% \begin{macrocode}
\keys_define:nn { @@ / show }
{
@@ -466,7 +495,7 @@
% This part should be regularly revisited to check if the code should go to a
% better place or can be improved.
% \subsection{Document structure}
-% \begin{macro}{\@@_add_document_structure:n,activate}
+% \begin{macro}{\@@_add_document_structure:n,activate (setup-key)}
% \begin{macrocode}
\cs_new_protected:Npn \@@_add_document_structure:n #1
{
@@ -485,6 +514,28 @@
}
% \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: The pdf version should be 2.0, structures should be activated,
+% the code in the pdfmanagement must be there.
+% \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: }
+ { ! \pdf_version_compare_p:Nn < {2.0} }
+ }
+ {
+ \tl_set:Nn \l_pdf_current_structure_destination_tl { __tag/struct/\g__tag_struct_stack_current_tl }
+ \pdf_activate_structure_destination:
+ }
+ }
+% \end{macrocode}
+
% \subsection{Fake space}
% \begin{macro}{\pdffakespace}
% We need a luatex variant for |\pdffakespace|. This should probably go into
@@ -518,8 +569,8 @@
%
%\begin{macro}
% {
-% paratagging,
-% paratagging-show,
+% paratagging (setup-key),
+% paratagging-show (setup-key),
% }
% These keys enable/disable locally paratagging, and the debug modus.
% It can affect the typesetting if |paratagging-show| is used. The small numbers
@@ -593,7 +644,7 @@
\tl_put_right:Nn \@mult@ptagging@hook
{
\@@_check_typeout_v:n {====>~In~\string\page@sofar}
- \process@cols\mult@gfirstbox
+ \process@cols\mult@firstbox
{
\@@_add_missing_mcs_to_stream:Nn \count@ {multicol}
}
@@ -686,7 +737,41 @@
\bool_gset_eq:NN \g_@@_in_mc_bool\g_@@_saved_in_mc_bool
}
}
+% \end{macrocode}
+% This version allows to use an Artifact structure
+% \begin{macrocode}
+\@@_attr_new_entry:nn {@@/attr/pagination}{/O/Artifact/Type/Pagination}
+\cs_new_protected:Npn \@@_exclude_struct_headfoot_begin:n #1
+ {
+ \bool_set_false:N \l_@@_para_bool
+ \bool_if:NTF \g_@@_mode_lua_bool
+ {
+ \tag_mc_end_push:
+ }
+ {
+ \bool_gset_eq:NN \g_@@_saved_in_mc_bool \g_@@_in_mc_bool
+ \bool_gset_false:N \g_@@_in_mc_bool
+ }
+ \tag_struct_begin:n{tag=Artifact,attribute-class=@@/attr/#1}
+ \tag_mc_begin:n {artifact=#1}
+ }
+\cs_new_protected:Npn \@@_exclude_struct_headfoot_end:
+ {
+ \tag_mc_end:
+ \tag_struct_end:
+ \bool_if:NTF \g_@@_mode_lua_bool
+ {
+ \tag_mc_begin_pop:n{}
+ }
+ {
+ \bool_gset_eq:NN \g_@@_in_mc_bool\g_@@_saved_in_mc_bool
+ }
+ }
+% \end{macrocode}
+% And now the keys
+% \begin{macro}{exclude-header-footer (setup-key)}
+% \begin{macrocode}
\keys_define:nn { @@ / setup }
{
exclude-header-footer .choice:,
@@ -697,6 +782,13 @@
\cs_set_eq:NN \@@_hook_kernel_after_head: \@@_exclude_headfoot_end:
\cs_set_eq:NN \@@_hook_kernel_after_foot: \@@_exclude_headfoot_end:
},
+ exclude-header-footer / pagination .code:n =
+ {
+ \cs_set:Nn \@@_hook_kernel_before_head: { \@@_exclude_struct_headfoot_begin:n {pagination} }
+ \cs_set:Nn \@@_hook_kernel_before_foot: { \@@_exclude_struct_headfoot_begin:n {pagination} }
+ \cs_set_eq:NN \@@_hook_kernel_after_head: \@@_exclude_struct_headfoot_end:
+ \cs_set_eq:NN \@@_hook_kernel_after_foot: \@@_exclude_struct_headfoot_end:
+ },
exclude-header-footer / false .code:n =
{
\cs_set_eq:NN \@@_hook_kernel_before_head: \prg_do_nothing:
@@ -708,7 +800,7 @@
exclude-header-footer .initial:n = true
}
% \end{macrocode}
-
+% \end{macro}
% \subsection{Links}
% We need to close and reopen mc-chunks around links.
% Currently we handle URI and GoTo (internal) links.