summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tagpdf/tagpdf.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tagpdf/tagpdf.tex')
-rw-r--r--macros/latex/contrib/tagpdf/tagpdf.tex116
1 files changed, 87 insertions, 29 deletions
diff --git a/macros/latex/contrib/tagpdf/tagpdf.tex b/macros/latex/contrib/tagpdf/tagpdf.tex
index fc096c338d..e36b3e9197 100644
--- a/macros/latex/contrib/tagpdf/tagpdf.tex
+++ b/macros/latex/contrib/tagpdf/tagpdf.tex
@@ -1,11 +1,22 @@
% !Mode:: "TeX:DE:UTF-8:Main"
\PassOptionsToPackage{check-declarations,enable-debug}{expl3}
-%\RequirePackage{pdfmanagement-testphase}
-\DocumentMetadata{pdfversion=2.0,lang=en-UK,testphase=phase-II,testphase=toc-tagging,testphase=sec-tagging,pdfstandard=a-2b}
+
+% Note on the compilation of the documentation:
+% The documentation uses for the tagging sometimes code
+% that is under development and/or not public yet.
+% To compile an *untagged* documentation, comment the line with
+% the testphase keys in the following \DocumentMetadata command.
+
+\DocumentMetadata
+ {
+ % comment the following line to compile an untagged documentation:
+ testphase=phase-II,testphase=toc-tagging,testphase=sec-tagging,
+ pdfversion=2.0,lang=en-UK,pdfstandard=a-2b
+ }
\makeatletter
-\def\UlrikeFischer@package@version{0.98a}
-\def\UlrikeFischer@package@date{2022-12-22}
+\def\UlrikeFischer@package@version{0.98b}
+\def\UlrikeFischer@package@date{2023-01-24}
\makeatother
\documentclass[DIV=12,parskip=half-,bibliography=totoc,a4paper]{article}
@@ -48,6 +59,10 @@
escapechar=*,
commentstyle=\color{green!50!black}\bfseries}
+% this allow to get real spaces in the code parts.
+% This should perhaps be combined in a new listings key
+\lstset{showspaces}
+\makeatletter \def\lst@visiblespace{\lst@ttfamily{\char32}{\char32}}\makeatother
\tagpdfsetup{
@@ -56,8 +71,7 @@
%show-spaces
}
-\usepackage[pdfdisplaydoctitle=true,%hyperfootnotes=false,
- ]{hyperref}
+\usepackage[pdfdisplaydoctitle=true]{hyperref}
\hypersetup{
pdftitle={The tagpdf package, v\csname UlrikeFischer@package@version\endcsname},
@@ -65,6 +79,8 @@
colorlinks}
\tcbuselibrary{documentation}
+%less space between docCommand
+\tcbset{nosep/.style={doc raster command={raster after skip=-10pt}}}
\definecolor{Definition}{rgb}{0,0.2,0.6}
\newcommand\PrintKeyName[1]{\textsf{#1}}
\newcommand\pkg[1]{\texttt{#1}}
@@ -433,8 +449,8 @@ Small bug fixes.
\item a new option \texttt{paratag} allows to change the tag name used for the
automatically tagged paragraphs.
-\item the commands |\tag_start:|, |\tag_stop:n| and |\tag_start:n| allow
- to stop and start tagging for example in trial typesetting.
+\item the commands |\tag_start:|, |\tag_stop:|, |\tag_stop:n| and |\tag_start:n| allow
+ to stop and start tagging (for example in trial typesetting).
\item Small bug fixes.
\end{itemize}
@@ -461,6 +477,14 @@ can improve the html export.
\end{itemize}
+\subsection{Changes in version 0.98a}
+Small bug fixes in code and documentation.
+
+\subsection{Changes in version 0.98b}
+The main change is from now on every structure has an ID and an IDtree is
+added. The ID of a structure can be retrieved with |\tag_get:n|
+see~\ref{sec:retrieve}.
+
\subsection{Proof of concept: the tagging of the documentation itself}
@@ -975,7 +999,7 @@ executed on the same page as the begin command. So think carefully how to
place them. For strategies how to handle paragraphs that split over pages see
subsection~\ref{sec:splitpara}.
-\begin{docCommand}{tagmcbegin}{\marg{key-val-list}}\end{docCommand}
+\begin{docCommand}[nosep]{tagmcbegin}{\marg{key-val-list}}\end{docCommand}
\begin{docCommand}{tag_mc_begin:n}{\marg{key-val-list}}\end{docCommand}
@@ -1072,7 +1096,7 @@ The key-val list understands the following keys:
\end{description}
-\begin{docCommand}{tagmcend}{}\end{docCommand}
+\begin{docCommand}[nosep]{tagmcend}{}\end{docCommand}
\begin{docCommand}{tag_mc:end}{}\end{docCommand}
These commands insert the end code of the marked content. They don't end a
@@ -1102,7 +1126,7 @@ the command, as the effect of the begin command ends with a new
%\end{tcolorbox}
-\begin{docCommand}{tagmcuse}{}\end{docCommand}
+\begin{docCommand}[nosep]{tagmcuse}{}\end{docCommand}
\begin{docCommand}{tag_mc_use:n}{}\end{docCommand}
@@ -1111,7 +1135,7 @@ into the current structure. Be aware that a marked content can be used only
once -- the command will warn you if you try to use it a second time.
-\begin{docCommand}{tag_mc_end_push:}{}\end{docCommand}
+\begin{docCommand}[nosep]{tag_mc_end_push:}{}\end{docCommand}
\begin{docCommand}{tag_mc_begin_pop:n}{\marg{key-val-list}}\end{docCommand}
If there is an open mc chunk,
@@ -1123,7 +1147,7 @@ definitions so there is only an expl3 version. Perhaps other content of the mc-d
-\begin{docCommand}{tagmcifinTF}{\marg{true code}\marg{false code}}\end{docCommand}
+\begin{docCommand}[nosep]{tagmcifinTF}{\marg{true code}\marg{false code}}\end{docCommand}
\begin{docCommand}{tag_mc_if_in:TF}{\marg{true code}\marg{false code}}\end{docCommand}
@@ -1133,10 +1157,14 @@ In \emph{generic mode}, where marked content command shouldn't be nested, it wor
In \emph{lua mode} it tests if the mc-attribute is currently unset. You can't test the nesting level with it!
+\subsubsection{Retrieving data} \label{sec:retrieve}
+With more elaborate tagging the need arise to retrieve and store current data.
\begin{docCommand}{tag_get:n}{\marg{key word}}\end{docCommand}
-This command give back some variables. Currently the only working key words are \verb+mc_tag+, \verb+struct_tag+ and \verb+struct_num+. The last returns a number and works also if only \pkg{tagpdf-base} has been loaded, but then doesn't give the same output: if \pkg{tagpdf} is loaded and tagging is active, \verb+struct_num+ gives the number of currently
+This (expandable) command give back some variables. Currently the working key words are \verb+mc_tag+, \verb+struct_tag+,
+\verb+struct_id+ and \verb+struct_num+. The ID is a string and returned including parentheses.
+\verb+struct_num+ returns a number and works also if only \pkg{tagpdf-base} has been loaded, but then doesn't give the same output: if \pkg{tagpdf} is loaded and tagging is active, \verb+struct_num+ gives the number of currently
active structure, so it reverts to the parent number if a structure is closed. If only \pkg{tagpdf-base} is loaded
nesting of structure is not tracked and so the command gives back the number of the last structure that has been created.
@@ -1230,11 +1258,11 @@ the needed code.
\tagstructbegin{tag=Figure,alt={Illustration of link annotation structure},attribute=bbox}\tagmcbegin{tag=Figure}
\ExplSyntaxOn
-\tag_stop_group_begin:
+\tag_stop:
\ExplSyntaxOff
\input{link-figure-input}
\ExplSyntaxOn
-\tag_stop_group_end:
+\tag_start:
\ExplSyntaxOff
\tagmcend\tagstructend
@@ -1408,7 +1436,7 @@ rerun.
\subsubsection{Automatic tagging of paragraphs}\label{sec:paratagging}
-\begin{docCommand}{tagpdfparaOn}{}\end{docCommand}
+\begin{docCommand}[nosep]{tagpdfparaOn}{}\end{docCommand}
\begin{docCommand}{tagpdfparaOff}{}\end{docCommand}
Another feature that emerged from the \LaTeX{} tagged PDF project are hooks at the begin and end of paragraphs.
@@ -1491,7 +1519,7 @@ The flat version is more \LaTeX-like and it is rather straightforward to patch \
The following commands can be used to define the tree structure:
-\begin{docCommand}{tagstructbegin}{\marg{key-val-list}}\end{docCommand}
+\begin{docCommand}[nosep]{tagstructbegin}{\marg{key-val-list}}\end{docCommand}
\begin{docCommand}{tag_struct_begin:n}{\marg{key-val-list}}\end{docCommand}
These commands start a new structure. They don't start a group. They set all their values globally.
@@ -1629,12 +1657,12 @@ The key-val list understands the following keys:
This key sets the |/E| key, the expanded form of an abbreviation or an acronym (I couldn't think of a better name, so I sticked to E).
\end{description}
-\begin{docCommand}{tagstructend}{}\end{docCommand}
+\begin{docCommand}[nosep]{tagstructend}{}\end{docCommand}
\begin{docCommand}{tag_struct_end:}{}\end{docCommand}
These commands end a structure. They don't end a group and it doesn't matter if they are in another group as the starting commands.
-\begin{docCommand}{tagstructuse}{\marg{label}}\end{docCommand}
+\begin{docCommand}[nosep]{tagstructuse}{\marg{label}}\end{docCommand}
\begin{docCommand}{tag_struct_use:n}{\marg{label}}\end{docCommand}
@@ -1769,22 +1797,54 @@ The following shows the marking needed for a section, a sentence and a list with
\end{document}
\end{lstlisting}
+\subsection{Interrupting the tagging}
-\subsection{Lazy and automatic tagging}\label{sec:lazy}
+Experience showed that it must be possible to interrupt tagging in some places.
+For example various packages do trial typesetting to measure text and this shouldn't create
+structures. There are therefore a number of commands for various use cases\footnote{it is
+quite possible that some of the commands will disappear again if we realize that they are not fitting!}
-A number of features of \PDF{} readers need a fully tagged \PDF{}. As an example screen readers tend to ignore alternative text (see section~\ref{sec:alt}) if the \PDF{} is not fully tagged. Also reflowing a \PDF{} only works for me (even if real space chars are in the \PDF{}) if the \PDF{} is fully tagged.
+\begin{docCommand}[nosep]{tag_stop:}{}\end{docCommand}
+\begin{docCommand}[nosep]{tag_start:}{}\end{docCommand}
+\begin{docCommand}[nosep]{tag_stop_group_begin:}{}\end{docCommand}
+\begin{docCommand}{tag_start_group_end:}{}\end{docCommand}
-This means that even if you don't care about a proper structure you should try to add at least some minimal tagging. With pdflatex this is not easy due to the page break problem. But with lualatex you can use an \texttt{Document} structure and inside it rather large mc-chunks. This minimizes the needed work.
+This commands stop and start tagging in the current group
+by switching \emph{local} booleans.
+The grouping commands also open and close a group.
-One could ask if in lua mode the code couldn't try to mark up unmarked parts e.g. as P-type chunks, like it marks them up as artifacts currently. Sadly this is not so easy, as it is quite difficult to reliably identify the structure and the place in the kids array where such chunks belongs too. I also don't think that it is really needed. It is not so difficult to define user macros which e.g. opens a structure and start an mc-chunk or which close an open mc-chunk before issuing the next \verb+\tagmcbegin+.
+\begin{docCommand}[nosep]{tag_stop:n}{\marg{label}}\end{docCommand}
+\begin{docCommand}{tag_start:n}{\marg{label}}\end{docCommand}
+This commands stop and start tagging in the current group
+by switching \emph{local} booleans, but |\tag_start:n|
+only restarts if the corresponding |tag_stop:n| actually
+stopped something. This is meant for a situation like the following,
+where you don't want that the inner |\tag_start:n| restarts tagging.
+\begin{lstlisting}
+\tag_stop:n{outer}
+ ...
+ \tag_stop:n{inner}
+ ...
+ \tag_start:n{inner}
+ ...
+\tag_start:n{outer}
+\end{lstlisting}
+
+\subsection{Lazy and automatic tagging}\label{sec:lazy}
-\subsection{Adding tagging to commands}
+
+A number of features of \PDF{} readers need a fully tagged \PDF{}. As an example screen readers tend to ignore alternative text (see section~\ref{sec:alt}) if the \PDF{} is not fully tagged. Also reflowing a \PDF{} only works for me (even if real space chars are in the \PDF{}) if the \PDF{} is fully tagged (recent versions of the adobe reader manage to
+reflow also not tagged \PDF{} but it is very slow).
+
+This means that even if you don't care about a proper structure you should try to add at least some minimal tagging. With the now available automatic tagging of paragraphs all that is needed, is to use |testphase=phase-II| in |\DocumentMetadata|. With lualatex this can work quite OK if you don't have unbalanced paragraphs in your document (pdflatex is more fragile).
+\subsection{Adding tagging to commands}
+
As mentioned above the mc-markers should not be nested. Basically you write:
@@ -1796,9 +1856,7 @@ As mentioned above the mc-markers should not be nested. Basically you write:
\end{lstlisting}
-This is quite workable as long as you mark everything manually. But how to write commands, e.g for a tabular or a graphic, that do tagging automatically without breaking the flow and the structure?
-
-
+This is quite workable as long as you mark everything manually. But when defining commands you have to ensure that they correctly push and pop the mc-chunks where needed.
\section{Alternative text, ActualText and text-to-speech software}\label{sec:alt}
@@ -2133,7 +2191,7 @@ This command takes as argument a key-val list which implements a number of show
-\printbibliography
+\printbibliography[heading=bibintoc]