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.tex152
1 files changed, 85 insertions, 67 deletions
diff --git a/macros/latex/contrib/tagpdf/tagpdf.tex b/macros/latex/contrib/tagpdf/tagpdf.tex
index cc3295488e..27cd1d128d 100644
--- a/macros/latex/contrib/tagpdf/tagpdf.tex
+++ b/macros/latex/contrib/tagpdf/tagpdf.tex
@@ -10,35 +10,33 @@
\DocumentMetadata
{
% comment the following line to compile an untagged documentation:
- testphase=phase-III,testphase=graphics,
+ testphase=phase-III,
pdfversion=2.0,lang=en-UK,pdfstandard=a-4,
+ %uncompress
}
\DebugBlocksOff
\makeatletter
-\def\UlrikeFischer@package@version{0.98g}
-\def\UlrikeFischer@package@date{2023-05-16}
+\def\UlrikeFischer@package@version{0.98h}
+\def\UlrikeFischer@package@date{2023-06-06}
\makeatother
-\documentclass[DIV=12,parskip=half-,bibliography=totoc,a4paper]{article}
+\documentclass[bibliography=totoc,a4paper]{article}
\usepackage{geometry}
\usepackage[english]{babel}
\usepackage{unicode-math}
\setmainfont{Heuristica}
\usepackage[nopatch]{microtype}
-\makeatletter
-% see https://github.com/schlcht/microtype/issues/8
-%\patchcmd{\MT@get@prot}{\noindent}{\RawNoindent}{}{\fail}
-\makeatother
-%\usepackage{scrlayer-scrpage}
\usepackage[autostyle]{csquotes}
-\usepackage[style=numeric,hyperref=false]{biblatex}
+\usepackage[style=numeric]{biblatex}
\addbibresource{tagpdf.bib}
\usepackage[noparboxrestore]{marginnote}
-\makeatletter \renewcommand*{\mn@parboxrestore}{\tagpdfparaOff}%
+\makeatletter
+\renewcommand*{\mn@parboxrestore}{\tagpdfparaOff}%
+\makeatother
\reversemarginpar
\usepackage{tcolorbox}
@@ -89,11 +87,6 @@
\usepackage{tagpdfdocu-patches}
-
-%\cfoot*{\pagemark}
-
-%
-
\newcommand\PDF{PDF}
\title{The \pkg{tagpdf} package, v\csname UlrikeFischer@package@version\endcsname}
@@ -128,12 +121,12 @@ This package is not meant for normal document production. It is mainly a tool to
tagging.
You need a very current \LaTeX{} format.
- You need a very current L3 programming layer.
- You need the new \LaTeX{} PDF management bundle.
+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. 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.
+At some time it will disappear when the code has been integrated into the \LaTeX{} format.
This package can change in an incompatible way.
@@ -160,45 +153,47 @@ Issues, comments, suggestions should be added as issues to the github tracker:
\section{Introduction}
-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.
+Since many years the creation of accessible, tagged \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 web page \parencite{tugaccess} dedicated to this theme.
+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, means to try out how core \LaTeX\ commands behave if tagging is used. Without such experiments it is in my opinion
+quite difficult to get a feeling about what has to be done, which kernel changes are needed, how packages should be adapted.
-This package were developped to close this gap by offering \emph{core} commands to tag a \PDF{}%
+This package was developed 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 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.
-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.
-
+The code has been written so that it can be added as module to the \LaTeX{} kernel itself if it turns out to be usable.
+It therefore avoid to 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
+these changes should 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 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.
+now structure destinations. More changes are in the latex-lab bundle and can be loaded through testphase keys.
-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}.
+I'm sure that tagpdf 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.
+Please also check the github site and latex-lab for new examples and improvements.
\subsection{Tagging and accessibility}
-While the package is named \texttt{tagpdf} the goal is actually \emph{accessible} \PDF{}-files. Tagging is \emph{one} requirement for accessibility but there are others. I will mention some later on in this documentation, and -- if sensible -- I will also try to add code, keys or tips for them.
+While the package is named \texttt{tagpdf} the goal is also \emph{accessible} \PDF{}-files. Tagging is \emph{one} (the most difficult) requirement for accessibility but there are others. I will mention some later on in this documentation, and -- if sensible -- I will also try to add code, keys or tips for them.
So the name of the package is a bit wrong. As excuse I can only say that it is shorter and easier to pronounce.
\subsection{Engines and modes}
-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 works theoretically with all engines,
+but the xelatex and the latex-dvips-route are basically untested tested and they also don't support
+real space glyphs so I don't recommend them.
+lualatex is the most powerful and safe modus and should be used for new documents, it is slower than pdflatex but requires less compilations to get tagging. pdflatex works ok and can be used for legacy documents; it needs more compilations to resolve all cross references needed for the tagging.
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.
-I implemented the generic mode first. Mostly because my tex skills are much better than my lua skills and I wanted to get the tex side right before starting to fight with attributes and node traversing.
+I implemented the generic mode first. Mostly because my \TeX\ skills are much better than my lua skills and I wanted to get the \TeX\ side right before starting to fight with attributes and node traversing.
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.
@@ -208,18 +203,37 @@ at best at least once or twice more often then normal.
\subsection{References and target PDF version}
-My main reference for the first versions of this package
-was the free reference for \PDF{} 1.7. \parencite{pdfreference} and so the package also targetted this version.
+My main reference for the first versions of this package was the free
+reference for \PDF{} 1.7. \parencite{pdfreference} and so the first versions
+of the package implemented only \PDF{} 1.7.
+
+In 2018 \PDF{} 2.0. has been released. The reference can be bought at no cost
+through the PDF association.
+
+\PDF{} 2.0 has a number of features that are really needed for good tagging:
+it knows more structure types, it allows to add associated files to
+structures---these are small, embedded files which can for example contain
+the mathML or source code of an equation---, it knows structure destinations
+which allows to link to a structure.
+
-In 2018 \PDF{} 2.0. has been released, and since 2020 all engines can set the version to 2.0. So the package will
-now target \PDF{} 2.0. This doesn't mean that 2.0 will be required, but that the code and the options will be extended to
-support \PDF{} 2.0. One example is the support for associated files, another the support for name spaces in version 0.82.
+\PDF{}~2.0 features are currently (mid 2023) not well supported by
+\PDF~consumer. No PDF viewer (including Acrobat) for example can handle name
+spaces and associated files. PAC~3 even crashes if one tries to load a \PDF{}
+2.0 file, and pdftk will create a \PDF{}~1.0 from it.
-The package doesn't try to suppress all 2.0 features if an older \PDF{} version is produced. It normally doesn't harm if a \PDF{} contains keys unknown in its version and it makes the code faster and easier to maintain if there aren't too many tests and code pathes; so for example associated files will always be added. But tests could be added in case this leads to incompabilities.
+Nevertheless \LaTeX{} targets \PDF{} 2.0, tagpdf has added support for
+associated files, for name spaces and other \PDF{} 2.0 features tagpdf and we
+recommend to use \PDF{} 2.0 if possible and then to complain to the PDF{}
+consumer if something doesn't work.
+
+The package doesn't try to suppress all 2.0 features if an older \PDF{}
+version is produced. It normally doesn't harm if a \PDF{} contains keys
+unknown in its version and it makes the code faster and easier to maintain if
+there aren't too many tests and code pathes; so for example associated files
+will always be added. But tests could be added in case this leads to
+incompabilities.
-It should be noted that some tools don't like \PDF{}~2.0. PAC~3 for example
-simply crashes, and pdftk will create a \PDF{}~1.0 from it. This makes
-testing \PDF{}~2.0 files a bit of a challenge.
\subsection{Validation}
@@ -228,11 +242,14 @@ testing \PDF{}~2.0 files a bit of a challenge.
\begin{itemize}
\item
- One must check that the \PDF{} is \emph{syntactically} correct. It is rather easy to create broken \PDF{}:
- e.g. if a chunk is opened on one page but closed on the next page or if the document isn't compiled often enough.
+ One must check that the \PDF{} is \emph{syntactically} correct.
+ It is rather easy to create broken \PDF{}:
+ e.g. if a chunk is opened on one page but closed
+ on the next page or if the document isn't compiled often enough.
-\item
-One must check how good the requirements of the PDF/UA standard are followed \emph{formally}.
+\item One must check how good the requirements of the PDF/UA standard are
+ followed \emph{formally}\footnote{The PDF/UA-2 standard for \PDF~2.0
+ will hopefully be released in 2023}.
\item
One must check how good the accessibility is \emph{practically}.
@@ -241,26 +258,33 @@ One must check how good the accessibility is \emph{practically}.
Syntax validation and formal standard validation can be done with preflight
of the (non-free) adobe acrobat. It can also be done also with the free
-\PDF{} Accessibility Checker (PAC~3) \parencite{pac3}. There is also the
+\PDF{} Accessibility Checker (PAC~2021) \parencite{pac3}. There is also the
validator veraPDF \parencite{verapdf}. A rather new and quite useful tool is
\enquote{Next Generation PDF} \parencite{ngpdf}, a browser application which
converts a tagged PDF to html, allows to inspect its structure and also to
edit the structure.
-Practical validation is naturally the more complicated part. It needs screen reader, users which actually knows how to handle them, can test documents and can report where a \PDF{} has real accessibility problems.
+Practical validation is naturally the more complicated part.
+It needs screen reader, users which actually knows how to handle them,
+can test documents and can report where a \PDF{} has real accessibility problems.
\minisec{Preflight woes}
-Sadly validators can not be always trusted. As an example for an reason that I don't understand the adobe preflight don't like the list structure \texttt{L}.
-It is also possible that validators contradict: that the one says everything is okay, while the other complains.
+Sadly validators can not be always trusted.
+As an example for an reason that I don't understand the adobe preflight
+don't like the list structure \texttt{L}.
+It is also possible that validators contradict: that the one says everything is okay,
+while the other complains.
\subsection{Examples wanted!}
-To make the package usable examples are needed: examples that demonstrate how various structures can be tagged and which patches are needed, examples for the test suite, examples that demonstrates problems.
+To make the package usable examples are needed:
+examples that demonstrate how various structures can be tagged and which patches are needed,
+examples for the test suite, examples that demonstrates problems.
\begin{tcolorbox}
@@ -269,7 +293,8 @@ Feedback, contribuations and corrections are welcome!
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.%
+so that uncompressed \PDF{} are created and the internal objects and
+structures can be inspected and be compared by the l3build checks.%
\section{Changes}
@@ -1232,19 +1257,14 @@ This solves the \enquote{interruption} problem, but has its price: Material inse
must be properly guarded. For example
\begin{taglstlisting}
-\RequirePackage{pdfmanagement-testphase}
-\DeclareDocumentMetadata{uncompress}
+\DocumentMetadata{uncompress}
\documentclass{article}
-\usepackage{tagpdf}
-\tagpdfsetup{activate,interwordspace=true}
\pagestyle{headings}
\begin{document}
-\tagstructbegin{tag=Document}
\sectionmark{HEADER}
\AddToHook{shipout/background}{\put(5cm,-5cm){BACKGROUND}}
\tagmcbegin{tag=P}Page 1\newpage Page 2\tagmcend
-\tagstructend
\end{document}
\end{taglstlisting}
@@ -1255,13 +1275,11 @@ like.
\includegraphics[alt=Show tags of examples]{global-ex}
-It is therefore from now on important to correctly markup such code. Header and footer typically should be
-artifacts. The LaTeX kernel hasn't yet suitable hooks around header and footer to allow to automate
-this, but a first draft has been added with \pkg{pdfmanagement-testphase}. Starting with version 0.92
-header and footer are marked as (simple) artifacts.
-If they contain code which needs a different markup it still must be added explicitly.
-With packages like \pkg{fancyhdr} or \pkg{scrlayer-scrpage} it is quite easy to add
-the needed code.
+It is therefore from now on important to correctly markup such code. Header
+and footer are now marked as artifacts (see below). If they contain code
+which needs a different markup it still must be added explicitly. With
+packages like \pkg{fancyhdr} or \pkg{scrlayer-scrpage} it is quite easy to
+add the needed code.
\subsubsection{Tips}