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.tex248
1 files changed, 139 insertions, 109 deletions
diff --git a/macros/latex/contrib/tagpdf/tagpdf.tex b/macros/latex/contrib/tagpdf/tagpdf.tex
index 70a771de2b..977e32cf32 100644
--- a/macros/latex/contrib/tagpdf/tagpdf.tex
+++ b/macros/latex/contrib/tagpdf/tagpdf.tex
@@ -4,8 +4,8 @@
\DocumentMetadata{pdfversion=2.0,lang=en-UK,testphase=phase-II}
\makeatletter
-\def\UlrikeFischer@package@version{0.95}
-\def\UlrikeFischer@package@date{2022-05-29}
+\def\UlrikeFischer@package@version{0.96}
+\def\UlrikeFischer@package@date{2022-08-06}
\makeatother
\documentclass[DIV=12,parskip=half-,bibliography=totoc]{scrartcl}
@@ -14,10 +14,10 @@
\usepackage{unicode-math}
\setmainfont{Heuristica}
-\usepackage{microtype}
+\usepackage[nopatch]{microtype}
\makeatletter
% see https://github.com/schlcht/microtype/issues/8
-\patchcmd{\MT@get@prot}{\noindent}{\RawNoindent}{}{\fail}
+%\patchcmd{\MT@get@prot}{\noindent}{\RawNoindent}{}{\fail}
\makeatother
\usepackage{scrlayer-scrpage}
@@ -99,7 +99,7 @@
\tagstructbegin{tag=Title}
\tagmcbegin{tag=Title}
-\begin{center}\let\thanks\par
+\begin{center}%\let\thanks\par
\makeatletter
\usekomafont{title}{\huge \@title \par}
@@ -127,7 +127,8 @@ You need a very current \LaTeX{} format.
You need a very current L3 programming layer.
You need the new \LaTeX{} PDF management bundle.
-This package is incomplete, experimental and quite probably contains bugs.
+This package is incomplete, experimental and quite probably contains bugs. It is in parts
+quite slow as the code prefers readability over speed.
At some time it will disappear when the code has been integrated into the \LaTeX{} format.
This package can change in an incompatible way.
@@ -147,62 +148,30 @@ Issues, comments, suggestions should be added as issues to the github tracker:
\tableofcontents
-\section{Preface to version 0.94}
-
-In this version a small package, \pkg{tagpdf-base} has been added. It provides
-no-op versions of the main expl3 user commands for packages that want to support
-tagging but can't be sure if the \pkg{tagpdf} package has been loaded.
-
-
-
-\section{Preface to version 0.93}
-The main change in the package itself in this version is the support for structure destinations.
-This is a new type of destinations in \PDF~2.0.
-For pdftex and luatex this requires new binaries. They will be included
-in texlive 2022, miktex already has the new pdftex, the new luatex will probably follow soon.
-
-Beside this mostly some clean up and bug fixes has been done.
-
-A more important step will be done in \LaTeX{} itself in the next dev-release: The command \cs{DocumentMetadata} will be
-added to the format and will take over the role of \cs{DeclareDocumentMetadata} from \pkg{pdfmanagement-testphase} and additionally
-will also load the pdf management code. This will simplify the documents as it will no longer be needed to load
-a package.
-
-
-
-\section{Preface to version 0.92}
-
-In this version support for page breaks in pdftex has been added. As described in section~\ref{sec:splitpara},
-tagging markers must be added by \emph{page}. That means that a paragraph that goes over two pages must get an end
-marker at the end on the first page and a new begin marker on the next page.
-
-With lualatex that is rather easy to ensure, with pdflatex it requires quite sophisticated code.
-The method is described in Frank Mittelbach's talk at TUG~2021
-\enquote{Taming the beast — Advances in paragraph tagging with pdfTeX and XeTeX}
-\url{https://youtu.be/SZHIeevyo3U?t=19551}. The new code requires a new version of the pdfmanagement-testphase package.
-
-Please check also section~\ref{sec:splitpara} for possible pitfalls.
-
-Also new in this version is the handling of header and footer: they will now be tagged as artifacts automatically.
-See section~\ref{sec:header-footer}.
\section{Introduction}
-Since many year the creation of accessible \PDF{}-files with \LaTeX\ which conform to the PDF/UA standard has been on the agenda of \TeX-meetings. Many people agree that this is important and Ross Moore has done quite some work on it. There is also a TUG-mailing list and a webpage \parencite{tugaccess} dedicated to this theme.
+Since many years the creation of accessible \PDF{}-files with \LaTeX\ which conform to the PDF/UA standard has been on the agenda of \TeX-meetings. Many people agree that this is important and Ross Moore has done quite some work on it. There is also a TUG-mailing list and a webpage \parencite{tugaccess} dedicated to this theme.
+
+But in my opinion missing were means to \emph{experiment} with tagging and accessibility. Means to try out, how difficult it is to tag some structures, means to try out, how much tagging is really needed (standards and validators don't need to be right \ldots), means to test what else is needed so that a \PDF{} works e.g. with a screen reader. Without such experiments it is imho quite difficult to get a feeling about what has to be done, which kernel changes are needed, how packages should be adapted.
-But in my opinion missing are means to \emph{experiment} with tagging and accessibility. Means to try out, how difficult it is to tag some structures, means to try out, how much tagging is really needed (standards and validators don't need to be right \ldots), means to test what else is needed so that a \PDF{} works e.g. with a screen reader. Without such experiments it is imho quite difficult to get a feeling about what has to be done, which kernel changes are needed, how packages should be adapted.
-This package tries to close this gap by offering \emph{core} commands to tag a \PDF{}%
+This package were developped to close this gap by offering \emph{core} commands to tag a \PDF{}%
\footnote{In case you don't know what this means: there will be some explanations later on.}.
+My hope was that the knowledge gained by the use of this package will at the end allow to decide if and how code to do tagging should be part of the \LaTeX\ kernel.
-My hope is that the knowledge gained by the use of this package will at the end allow to decide if and how code to do tagging should be part of the \LaTeX\ kernel.
-The package does not patch commands from other packages. It is also not an aim of the package to develop such patches. While at the end changes to various commands in many classes and packages will be needed to get tagged \PDF{} files -- and the examples accompanying the package try (or will try) to show various strategies -- these changes should in my opinion be done by the class, package and document writers themselves using a sensible API provided by the kernel and not by some external package that adds patches everywhere and would need constant maintenance -- one only need to look at packages like tex4ht or bidi or hyperref to see how difficult and sometimes fragile this is.
+The code has been written with the goal to extend \LaTeX{} itself.
+It therefore quite does not patch commands from other packages and is also not an aim of the package to develop such patches. While at the end changes to various commands in many classes and packages will be needed to get tagged \PDF{} files -- and the examples accompanying the package try (or will try) to show various strategies -- these changes should in my opinion be done by the class, package and document writers themselves using a sensible API provided by the kernel and not by some external package that adds patches everywhere and would need constant maintenance -- one only need to look at packages like tex4ht or bidi or hyperref to see how difficult and sometimes fragile this is.
-So this package deliberately concentrates on the basics -- and this already quite a lot, there are much more details involved as I expected when I started.
-I'm sure that it has bugs. Bugs reports, suggestions and comments can be added to the issue tracker on github. \url{https://github.com/u-fischer/tagpdf}.
+The package is now a part of the Tagged PDF project and triggered already various changes in the LaTeX kernel and the engines: There is a new PDF management,
+the new para hooks allows to automatically tag paragraphs, after changes in the output routine
+page breaks and header and footer are handled correctly, the engines support
+now structure destinations.
+
+I'm sure that it still has bugs. Bugs reports, suggestions and comments can be added to the issue tracker on github. \url{https://github.com/u-fischer/tagpdf}.
Please also check the github site for new examples and improvements.
@@ -215,7 +184,9 @@ So the name of the package is a bit wrong. As excuse I can only say that it is s
\subsection{Engines and modes}
-The package works currently with pdflatex and lualatex. First steps have been done to also enable support for xelatex and the latex-dvips-route; but this isn't yet much tested.
+The package theoretically with all engines,
+But the xelatex and the latex-dvips-route are not much tested and they also don't support
+real space glyphs. lualatex is the most powerful and safe modus, but pdflatex works ok too.
The package has two modes: the \emph{generic mode} which should work in theory with every engine and the \emph{lua mode} which works only with lualatex.
@@ -223,7 +194,8 @@ I implemented the generic mode first. Mostly because my tex skills are much bett
While the generic mode is not bad and I spent quite some time to get it working I nevertheless think that the lua mode is the future and the only one that will be usable for larger documents. \PDF{} is a page orientated format and so the ability of luatex to manipulate pages and nodes after the \TeX-processing is really useful here. Also with luatex characters are normally already given as unicode.
-The package uses quite a lot labels (in generic mode more than with luamode). At the begin it relied on the \pkg{zref} package, but switched now to a new experimental implementation for labels. The drawback of the new method is that they don't give yet good rerun messages if they have changed. I advise to use the \pkg{rerunfilecheck} package as a intermediate work-around.
+The package uses quite a lot labels (in generic mode more than with luamode). At the begin it relied on the \pkg{zref} package, but switched now to a new experimental implementation for labels. The drawback of the new method is that they don't give yet good rerun messages if they have changed. I advise to use the \pkg{rerunfilecheck} package as a intermediate work-around and when using pdflatex compile
+at best at least once or twice more often then normal.
\subsection{References and target PDF version}
@@ -283,14 +255,15 @@ Feedback, contribuations and corrections are welcome!
\end{tcolorbox}
-All examples should use the \cs{tagpdfsetup} key \PrintKeyName{uncompress} described in the next section so that uncompressed \PDF{} are created and the internal objects and structures can be inspected and -- hopefully soon -- be compared by the l3build checks.%
+All examples should use the \cs{DocumentMetadata} key \PrintKeyName{uncompress}
+so that uncompressed \PDF{} are created and the internal objects and structures can be inspected and -- hopefully soon -- be compared by the l3build checks.%
\section{Changes}
\subsection{Changes in 0.3}
-In this version I improved the handling of alternative and actual text. See section~\ref{sec:alttext}. This change meant that the package relied on the module \texttt{l3str-convert}.
+In this version I improved the handling of alternative and actual text. See section~\ref{sec:alt}. This change meant that the package relies on the module \texttt{l3str-convert}.
I no longer try to (pdf-)escape the tag names: it is a bit unclear how to do it at best with luatex. This will perhaps later change again.
@@ -307,7 +280,7 @@ I added code to add \enquote{real} space glyphs to the \PDF{}, see section \ref{
\subsection{Changes in 0.6}
-\textbf{Breaking change!} The attributes used in luamode to mark the MC-chunks are no longer set globally. I thought that global attribute would make it easier to tag, but it only leads to problem when e.g. header and footer are inserted. So from this version on the attributes are set locally and the effect of a \verb+\tagmcbegin+ ends with the current group. This means that in some cases more \verb+\tagmcbegin+ are needed and this affected some of the examples, e.g. the patching commands for sections with KOMA. On the other side it means that quite often one can omit the \verb+\tagmcend+ command.
+\textbf{Breaking change!} The attributes used in luamode to mark the MC-chunks are no longer set globally. I thought that global attributes would make it easier to tag, but it only leads to problem when e.g. header and footer are inserted. So from this version on the attributes are set locally and the effect of a \verb+\tagmcbegin+ ends with the current group. This means that in some cases more \verb+\tagmcbegin+ are needed and this affected some of the examples, e.g. the patching commands for sections with KOMA. On the other side it means that quite often one can omit the \verb+\tagmcend+ command.
\subsection{Changes in version 0.61}
@@ -401,7 +374,7 @@ works also if tagging is not active.
\begin{itemize}
\item support for page breaks in pdftex has been added, see section~\ref{sec:splitpara},
-This requires a new version of the pdfmanagement-testphase package.
+
\item header and footer are tagged as artifacts automatically, see section~\ref{sec:header-footer}.
@@ -410,6 +383,9 @@ will now expand once.
\end{itemize}
+
+
+
\subsection{Changes in version 0.93}
\begin{itemize}
@@ -417,8 +393,12 @@ will now expand once.
has been added. This allow e.g. to add a css-file which is be used if the \PDF\ is converted to
html.
-\item First steps have been done to adapt the package to planed changes in \LaTeX{}: The command \cs{DocumentMetadata} will be
-added to the format and will take over the role of \cs{DeclareDocumentMetadata} from \pkg{pdfmanagement-testphase}.
+\item First steps have been done to adapt the package to planed changes in \LaTeX{}:
+The command \cs{DocumentMetadata} will be
+added to the format and will take over the role of \cs{DeclareDocumentMetadata}
+from \pkg{pdfmanagement-testphase} and additionally
+will also load the pdf management code. This will simplify the documents
+as it will no longer be needed to load the package.
\item The package has now support for \enquote{structure destinations}.
This is a new type of destinations in \PDF~2.0.
@@ -429,6 +409,36 @@ in texlive 2022, miktex already has the new pdftex, the new luatex will probably
\end{itemize}
+\subsection{Changes in version 0.94}
+
+In this version a small package, \pkg{tagpdf-base} has been added. It provides
+no-op versions of the main expl3 user commands for packages that want to support
+tagging but can't be sure if the \pkg{tagpdf} package has been loaded.
+
+\subsection{Changes in version 0.95}
+
+Small bug fixes.
+
+\subsection{Changes in version 0.96}
+
+\begin{itemize}
+\item The \texttt{alttext} key has been renamed to \texttt{alt}, the other key name exists as alias.
+
+\item The new command |\tag_struct_object_ref:n| allows to
+ create the object reference of a structure.
+
+\item a new key \texttt{parent} has been added
+ to allow structures to choose their parent structure.
+
+\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 Small bug fixes.
+\end{itemize}
+
\subsection{Proof of concept: the tagging of the documentation itself}
Starting with version 0.6 the documentation itself has been tagged. The tagging wasn't (and isn't) in no way perfect. The validator from Adobe didn't complain, but PAX3 wanted alternative text for all links (no idea why) and so I put everywhere simple text like \enquote{link} and \enquote{ref}. The links to footnotes gave warnings, so I disabled them. I used types from the \PDF{} version 1.7, mostly as I have no idea what should be used for code in 2.0. Margin notes were simply wrong \ldots
@@ -443,36 +453,25 @@ Be aware that to create the tagged version a current lualatex-dev and a current
\tagpdfparaOff
-\tagstructbegin{tag=Figure,alttext=PAC3 report,attribute=bbox}\tagmcbegin{tag=Figure}
+\tagstructbegin{tag=Figure,alt=PAC3 report,attribute=bbox}\tagmcbegin{tag=Figure}
\includegraphics{pac3}
\tagmcend\tagstructend
\tagpdfparaOn
-\section{Setup}
-
-The package requires the new PDF management. With a current version of \pkg{pdfmanagement-testphase} it can be loaded and
-activated like this:
-
-\begin{lstlisting}
-\RequirePackage{pdfmanagement-testphase}
-\DeclareDocumentMetadata
- {
- testphase = tagpdf, % load
- activate = tagging % activate and create the document structure
- }
-\documentclass{article}
-\begin{document}
-some text
-\end{document}
-\end{lstlisting}
+\section{Loading}
-With \LaTeX{} 2022-06-01 (or a current \LaTeX-dev) the call will be simpler
+The package requires the new PDF management. With a current \LaTeX{} (2022-06-01 or newer)
+the PDF management is loaded if you use the \cs{DocumentMetadata} command before \cs{documentclass}.
+The \texttt{tagpdf} package can then be loaded and activated by using the \texttt{testphase} key. The exact behaviour of
+the \texttt{testphase} key is documented in \texttt{documentmetadata-support-doc.pdf} which
+is part of the \texttt{latex-lab} bundle.
\begin{lstlisting}
\DocumentMetadata
{
- testphase = tagpdf, % load + activate
+ % testphase = phase-I, % tagging without paragraph tagging
+ testphase = phase-II % tagging with paragraph tagging and other new stuff.
}
\documentclass{article}
\begin{document}
@@ -482,14 +481,18 @@ some text
\minisec{Activation needed!}
+The package can also be loaded normally with |\usepackage| (but it is
+still required to use \cs{DocumentMetadata} to load the pdfmanagement) but
+it will then -- apart from loading more packages and defining a lot of things -- not do much. You will have to \emph{activate} it with \verb+\tagpdfsetup+.
-When the package is loaded it will -- apart from loading more packages and defining a lot of things -- not do much. You will have to activate it with \verb+\tagpdfsetup+ or as shown above in \verb+\DeclareDocumentMetadata+/\verb+\DocumentMetadata+.
+The pdfmanagement loaded with \cs{DocumentMetadata} will in any case load \texttt{tagpdf-base} a
+small package that provides no-op versions of the main tagging commands.
Most commands do nothing if tagging is not activated, but in case a test is needed a command (with the usual p,T,F variants) is provided:
\begin{docCommand}{tag_if_active:TF}{}\end{docCommand}
-The check is true only if \emph{everything} is activated. In all other cases (also if tagging has been stopped locally) it will be false.
+The check is true only if \emph{everything} is activated. In all other cases (including if tagging has been stopped locally) it will be false.
\subsection{Modes and package options}
@@ -555,6 +558,8 @@ That's a debug option, it helps in lua mode to see where space glyph will be ins
\item[\PrintKeyName{paratagging-show}] Boolean. This activate/deactivates small red numbers in the places where the paratagging hook code is used.
+\item[\PrintKeyName{paratag}] String. This key changes the tag used by the paratagging code. The default tag is \texttt{P}. A useful local setting here can be \texttt{NonStruct}, which creates a structure \enquote{without meaning}.
+
\item[\PrintKeyName{tabsorder}]
Choice key, possible values are \PrintKeyName{row}, \PrintKeyName{column}, \PrintKeyName{structure}, \PrintKeyName{none}. This decides if a \verb+/Tabs+ value is written to the dictionary of the page objects. Not really needed for tagging itself, but one of the things you probably need for accessibility checks. So I added it. Currently the tabsorder is the same for all pages. Perhaps this should be changed \ldots.
@@ -625,7 +630,7 @@ To tag a \PDF{} three tasks must be carried out:
\tagpdfparaOff
-\tagstructbegin{tag=Figure,alttext={Illustration of page stream with marked content},attribute=bbox}%
+\tagstructbegin{tag=Figure,alt={Illustration of page stream with marked content},attribute=bbox}%
\tagmcbegin{tag=Figure}%
\begin{tikzpicture}[baseline=(a.north),node distance=2pt,remember picture]
\node(start){\ldots~\ldots~\ldots};
@@ -645,7 +650,7 @@ To tag a \PDF{} three tasks must be carried out:
\tagpdfparaOff
\newlength\ydistance\setlength\ydistance{-0.8cm}
-\tagstructbegin{tag=Figure,alttext={Illustration of structure},attribute=bbox}%
+\tagstructbegin{tag=Figure,alt={Illustration of structure},attribute=bbox}%
\tagmcbegin{tag=Figure}%
\begin{tikzpicture}[remember picture,baseline=(root.north)]
@@ -847,21 +852,21 @@ The key-val list understands the following keys:
\item[\PrintKeyName{label}]
This key sets a label by which you can call the marked content later in another structure (if it has been stashed with the previous key). Internally the label name will start with \texttt{tagpdf-}.
- \item[\PrintKeyName{alttext}]
- This key inserts an \texttt{/Alt} value in the property dictionary of the BDC operator. See section~\ref{sec:alttext}. The value is handled as verbatim string, commands are not expanded but the value will be expanded first once (so works like the key \texttt{alttext-o} in previous versions which has been removed).
+ \item[\PrintKeyName{alt}]
+ This key inserts an \texttt{/Alt} value in the property dictionary of the BDC operator. See section~\ref{sec:alt}. The value is handled as verbatim string, commands are not expanded but the value will be expanded first once (so works like the key \texttt{alttext-o} in previous versions which has been removed).
That means that you can do something like in the following listing
and it will insert \verb+\frac{a}{b}+ (hex encoded) in the \PDF{}.
\begin{lstlisting}
\newcommand\myalttext{\frac{a}{b}}
- \tagmcbegin{tag=P,alttext=\myalttext}
+ \tagmcbegin{tag=P,alt=\myalttext}
\end{lstlisting}
\item[\PrintKeyName{actualtext}]
- This key inserts an \texttt{/ActualText} value in the property dictionary of the BDC operator. See section~\ref{sec:alttext}. The value is handled as verbatim string, commands are not expanded but the value will be expanded first once (so works like the key \texttt{actualtext-o} in previous versions which has been removed).
+ This key inserts an \texttt{/ActualText} value in the property dictionary of the BDC operator. See section~\ref{sec:alt}. The value is handled as verbatim string, commands are not expanded but the value will be expanded first once (so works like the key \texttt{actualtext-o} in previous versions which has been removed).
That means that you can do something like in the following listing and and it will insert \verb+X+ (hex encoded) in the \PDF{}.
@@ -936,7 +941,10 @@ In \emph{lua mode} it tests if the mc-attribute is currently unset. You can't te
\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 works also if only \pkg{tagpdf-base} has been loaded.
+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
+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.
+
\subsubsection{Luamode: global or not global -- that is the question}\label{sec:global-local}
@@ -994,7 +1002,7 @@ the \emph{second} page will be marked as artifact. The following figure shows ho
like.
\tagpdfparaOff
-\tagstructbegin{tag=Figure,alttext=Show tags of examples,attribute=bbox}\tagmcbegin{tag=Figure}
+\tagstructbegin{tag=Figure,alt=Show tags of examples,attribute=bbox}\tagmcbegin{tag=Figure}
\includegraphics{global-ex}
\tagmcend\tagstructend
@@ -1025,7 +1033,7 @@ the needed code.
\begin{figure}
\tagpdfparaOff
-\tagstructbegin{tag=Figure,alttext={Illustration of link annotation structure},attribute=bbox}\tagmcbegin{tag=Figure}
+\tagstructbegin{tag=Figure,alt={Illustration of link annotation structure},attribute=bbox}\tagmcbegin{tag=Figure}
\ExplSyntaxOn
\tag_stop_group_begin:
\ExplSyntaxOff
@@ -1161,7 +1169,7 @@ If this is really the way to go one would need some script to add the mark-up as
But I'm not sure that this is the best way to do math. It looks rather odd that a document should have to tell a screen reader in such detail how to read an equation. It would be much more efficient, sensible and flexible if a complete representation of the equation in mathML could be stored in the \PDF{} and the task how to read this aloud delegated to the screen reader. As \PDF{}~2.0 introduced associated files it is probable that this will be the way to go but more investigations are needed here.
-See also section~\ref{sec:alttext} for some more remarks and tests.
+See also section~\ref{sec:alt} for some more remarks and tests.
\subsubsection{Split paragraphs}\label{sec:splitpara}
@@ -1186,14 +1194,18 @@ Pellentesque scelerisque
sit amet, lacus.\tagmcend
\end{lstlisting}
-Starting with version 0.91 there is code which tries to resolve this problem. Basically it works like this: every mc-command
+Starting with version 0.92 there is code which tries to resolve this problem. Basically it works like this: every mc-command
issues a mark command (actually two slightly different). When the page is built in the output routine this mark commands are inspected
and from them \LaTeX{} can deduce if there is a mc-chunk which must be closed or reopened.
+The method is described in Frank Mittelbach's talk at TUG~2021
+\enquote{Taming the beast — Advances in paragraph tagging with pdfTeX and XeTeX}
+\url{https://youtu.be/SZHIeevyo3U?t=19551}.
+
Please note
\begin{itemize}
-\item The code requires the pdfmanagement-testphase version v0.95i.
+\item The code requires a pdfmanagement-testphase version v0.95i or newer.
\item Typically you will need more compilations than previously, don't rely on the rerun messages, but if something looks wrong
rerun.
\item The code relies on that related |\tagmcbegin| and |\tagmcend| are in the same boxing level. If one is in a box (which hides the marks) and the other in the main galley, things will go wrong.
@@ -1206,12 +1218,16 @@ rerun.
Another feature that emerged from the \LaTeX{} tagged PDF project are hooks at the begin and end of paragraphs.
\pkg{tagpdf} makes use of these hooks to tag paragraphs. This can be activated/deactivated (also locally) with
-options of \cs{tagpdfsetup} or with the two commands above. \emph{This is very experimental and it requires a new \LaTeX!}
+options of \cs{tagpdfsetup} or with the two commands above.
The automatic tagging require that for every begin of a paragraph with the begin hook code
there a corresponding end with the closing hook code. This can fail, e.g if a |vbox| doesn't correctly issue a |\par| at the end.
-If this happens the tagging structure can get every confused. It is therefore needed to check the structure carefully as currently
-no checks are implemented to check this automatically.
+If this happens the tagging structure can get every confused. At the end of the document \pkg{tagpdf} checks if
+the number of start and end paragraph structures created here are equal and it will error if not.
+
+Nesting the activation and deactivation of the tagging of paragraphs can be quite difficult. For example if it is unclear if the inner code issues a |\par| or not it is not trivial to exclude an end hook for every excluded begin hook.
+In such cases it can be easier to use the new |paratag| key with the value |NonStruct| to convert some |P|-structures
+into |NonStruct|-structures without real meaning.
\subsection{Task 2: Marking the structure}
@@ -1296,16 +1312,29 @@ The key-val list understands the following keys:
Normally a new structure inserts itself as a kid into the currently active structure. This key prohibits this. The structure is nevertheless from now on \enquote{the current active structure} and parent for following marked content and structures.
\item[\PrintKeyName{label}]
- This key sets a label by which you can use the structure later in another structure. Internally the label name will start with \texttt{tagpdfstruct-}.
-
-
- \item[\PrintKeyName{alttext}]
- This key inserts an \texttt{/Alt} value in the dictionary of structure object, see section~\ref{sec:alttext}. The value is handled as verbatim string and hex encoded. The value will be expanded first once (so works like the key \texttt{alttext-o} in previous versions which has been removed). That means that you can do something like this:
+ This key sets a label by which 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 attributes \texttt{tagstruct} (the structure number) and \texttt{tagstructobj} (the
+ object reference).
+
+ \item[\PrintKeyName{parent}]
+ % 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}\verb+{tagpdfstruct-label}{tagstruct}+ to retrieve it.
+
+ \item[\PrintKeyName{alt}]
+ This key inserts an \texttt{/Alt} value in the dictionary of structure object, see section~\ref{sec:alt}. The value is handled as verbatim string and hex encoded. The value will be expanded first once (so works like the key \texttt{alttext-o} in previous versions which has been removed). That means that you can do something like this:
\begin{lstlisting}
\newcommand\myalttext{\frac{a}{b}}
- \tagstructbegin{tag=P,alttext=\myalttext}
+ \tagstructbegin{tag=P,alt=\myalttext}
\end{lstlisting}
@@ -1315,7 +1344,7 @@ The key-val list understands the following keys:
\item[\PrintKeyName{actualtext}]
- This key inserts an \texttt{/ActualText} value in the dictionary of structure object, see section~\ref{sec:alttext}. The value is handled as verbatim string, The value will be expanded first once (so works like the key \texttt{alttext-o} in previous versions which has been removed). That means that you can do something like this:
+ This key inserts an \texttt{/ActualText} value in the dictionary of structure object, see section~\ref{sec:alt}. The value is handled as verbatim string, The value will be expanded first once (so works like the key \texttt{alttext-o} in previous versions which has been removed). That means that you can do something like this:
\begin{lstlisting}
\newcommand\myactualtext{X}
@@ -1398,7 +1427,8 @@ The key-val list understands the following keys:
\item[\PrintKeyName{ref}]
This key allows to add references to other structure elements, it adds the |/Ref| array to the structure.
The value should be a comma separated list of structure labels set with the |label| key.
- e.g. |ref={label1,label2}|.
+ e.g. |ref={label1,label2}|. It can be used more than once in the key/value argument and combines the
+ references.
\item[\PrintKeyName{E}]
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).
@@ -1548,7 +1578,7 @@ The following shows the marking needed for a section, a sentence and a list with
\subsection{Lazy and automatic tagging}\label{sec:lazy}
-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:alttext}) 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.
+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.
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.
@@ -1576,7 +1606,7 @@ This is quite workable as long as you mark everything manually. But how to write
-\section{Alternative text, ActualText and text-to-speech software}\label{sec:alttext}
+\section{Alternative text, ActualText and text-to-speech software}\label{sec:alt}
@@ -1586,7 +1616,7 @@ Both can be added either to the marked content in the page stream or to the obje
The value of \PrintKeyName{/ActualText} (inserted by \texttt{tagpdf} with \PrintKeyName{actualtext}) is meant to replace single characters or rather small pieces of text. It can be used also without any tagging (e.g. with the package accsupp). If the \PDF{} reader support this (adobe reader does, sumatra not) one can change with it how a piece of text is copied and pasted e.g. to split up a ligature.
-\PrintKeyName{/Alt} (inserted by \texttt{tagpdf} with \PrintKeyName{alttext}) is a key to improve accessibility: with it one can add to a picture or something else an alternative text.
+\PrintKeyName{/Alt} (inserted by \texttt{tagpdf} with \PrintKeyName{alt}) is a key to improve accessibility: with it one can add to a picture or something else an alternative text.
The file \texttt{ex-alt-actualtext.tex} shows some experiments I made with with both keys and text-to-speech software (the in-built of adobe and nvda).
To sum them up:
@@ -1839,7 +1869,7 @@ This is not meant as a full reference only as a background to make the examples
\tagpdfparaOff
-\tagstructbegin{tag=Figure,alttext={Illustration of postfix notation},attribute=bbox}\tagmcbegin{tag=Figure}
+\tagstructbegin{tag=Figure,alt={Illustration of postfix notation},attribute=bbox}\tagmcbegin{tag=Figure}
\begin{tikzpicture}[baseline=(c.base)]
\node[arg](a1) {18};
\node[arg,right=of a1.east](a2) {0};
@@ -1912,7 +1942,7 @@ This is not meant as a full reference only as a background to make the examples
\tagpdfparaOff
- \tagstructbegin{tag=Figure,alttext={Illustration of array},attribute=bbox}\tagmcbegin{tag=Figure}
+ \tagstructbegin{tag=Figure,alt={Illustration of array},attribute=bbox}\tagmcbegin{tag=Figure}
\begin{tikzpicture}[baseline=(c.base)]
\node[arg](a1) {0};
\node[arg,right = of a1.east](a2) {15 0 R};