262

TUGboat, Volume 44 (2023), No. 2

Automated tagging of LATEX documents —what is possible today, in 2023?
Ulrike Fischer, Frank Mittelbach
Abstract
The LATEX Tagged PDF project was started in spring2020 and announced to the TEX community by theLATEX Team at the Online TUG Conference 2020 [9].
This short report describes the progress and statusof this multi-year project achieved with the LATEX
summer release 2023.
Contents
1 Introduction262

2 Goals of the Tagged PDF project263

3 Some problems we faced
3.1 Tags are not visible . . . . . . . . . .
3.2 Missing PDF 2.0 support . . . . . . .
3.3 Parent-Child rules . . . . . . . . . .

263
263
263
263

4 What is possible today:
Tagging of “Leslie Lamport Documents”
4.1 Links . . . . . . . . . . . . . . . . . .
4.2 Paragraphs . . . . . . . . . . . . . .
4.3 Footnotes . . . . . . . . . . . . . . .
4.4 Sectioning . . . . . . . . . . . . . . .
4.5 Tables of contents and similar lists .
4.6 Display environments and lists . . .
4.7 Citations and bibliographies . . . . .
4.8 Graphics . . . . . . . . . . . . . . . .
4.9 Floats . . . . . . . . . . . . . . . . .
4.10 minipage and \parbox . . . . . . . .
4.11 Text commands . . . . . . . . . . . .
4.12 Math . . . . . . . . . . . . . . . . . .
4.13 Firstaid . . . . . . . . . . . . . . . .

263
264
264
264
264
264
264
265
265
265
265
265
265
265

5 What is missing

265

6 Summary266

1Introduction

A tagged PDF is a PDF with an additional semanticstructure. The purpose of tagging and the technicalbackground have been described in earlier articles [3,4] and in the documentation of the tagpdf package[2] and won’t be repeated here.
As a short motivation for how tagging improves
the accessibility and the reuse of data, let’s look atbank statements as an example. For a few months
Ulrike gets them as tagged PDF1 and can comparethem with earlier untagged versions. The tagging ofthe PDF is quite basic: apart from a few tags aroundparagraphs it contains only a large table with three
1 Their tagging is not done with LAT X.

EUlrike Fischer, Frank Mittelbach
doi.org/10.47397/tb/44-2/tb137fischer-tagging23

Figure 1: A tagged bank statement

Figure 2: Copy & paste of a tagged table into aspreadsheet

columns (the date, a multiline description and theamount). As shown in figure 1, the tagging adds TR(Table Row) tags around rows and TD (Table Data)around the cells.
If such a bank statement is read with a screen
reader, then with an untagged PDF the reading orderis messy: the amount is read somewhere in the middleof the multiline description, text surrounding thetable can leak into the reading, and there are no
options to navigate in the table. With a tagged PDF
the experience is quite different: the reading order iscorrect, the screen reader announces row and column
numbers and it is possible to navigate by rows andcells. Copy & paste from a tagging aware PDF reader
improves too: while with an untagged PDF the table
content is dumped into one column of a spreadsheet,the content of a tagged PDF is correctly split into
single cells, as can be seen in figure 2.

TUGboat, Volume 44 (2023), No. 22263

Goals of the Tagged PDF project

The example hopefully shows why tagging is generally important and the LATEX team embarked on
the task to support tagging. To address a common
misunderstanding: The main goal of the Tagged
PDF project is not to make tagging possible — thisis already the case today: if you want to produce
a tagged PDF with LATEX you can do it. The main
goal is to make tagging automated and easy to use.
It should be possible for the average user to create
a tagged PDF with only minimal changes to theirsources.

Figure 3: Part of the Parent-Child rules for the P tag

files attached to a structure through its accessibility
API. PAC3 crashes if a PDF 2.0 files is loaded.

The Tagged PDF project has to redefine many LATEX
commands but this is in some sense an expected task.
Before we describe the current state of the project
we want to discuss some problems, outside of theProject Team’s control, that we identified in the lastyear.

We have here a clear chicken-and-egg problem:
As there are only few tagged PDF 2.0 files in thewild, no viewer correctly processes them, and because no viewer handles tagged PDF 2.0 files properly there is no incentive for applications to produce
tagged PDF 2.0 files. However, there is some hopefor changes: The PDF 2.0 reference is now available
at no cost; ISO 32005, which handles the combined
PDF 1.7 and PDF 2.0 tag set, has been released [6]and PDF/UA-2 will be released shortly too.

3.1

3.3

3Some problems we faced

Tags are not visible

The screenshot in Figure 1 was made with Acrobat Pro, and that costs money. Free viewers andbrowser plug-ins normally don’t show tags even if (aswith Adobe Reader) they use them to improve, forexample, the copy & paste heuristic. This missing
visibility makes it difficult to convince users that tags
are important. It also makes development in LATEX
difficult as package maintainers can’t easily checkthe tagging. Fortunately, the situation is starting tochange and some free PDF viewers like PDF-XChangeand PDFix Desktop Lite now can be used to checkthe tags.
3.2

Missing PDF 2.0 support

The ISO spec for PDF 2.0 [5] is more than 6 years
old. PDF 2.0 added various new features that are
crucial for tagging. For example, it extends the tag
set with tags like Title, Aside and FEnote. It also
adds two new features, both needed for the tagging
of math: 1) it declares the MathML namespace, and2) it supports attaching embedded files to structure
objects; then they are called “associated files”. Such
associated files can contain the source code or theMathML representation. With PDF 2.0 it is also
possible to link to a structure instead of to a location
on a page. LATEX is able to produce PDF 2.0 andcan make use of the new features.
But sadly PDF 2.0 also has a problem: it is notwell supported by PDF viewers and consumers. EvenAcrobat Pro is, at the time of writing, not able tohandle tag namespaces and doesn’t pass associatedParent-Child rules

Structure elements defined by the PDF spec can’t
be used freely: The PDF format defines containment
rules and describes which standard tag is allowed asa child or parent of other elements. If you declare
your own tag names you have to also declare a role
mapping to the standard tags and your tags thenhave to obey the containment rules of the standard
tags they map to. In PDF 1.7 the rules were only
described in a rather vague way. PDF 2.0 introduceda large matrix for the PDF 2.0 tags and the new
ISO 32005 [6] extends this matrix to combine thePDF 1.7 and 2.0 tags. Figure 3 shows an excerpt ofthe rules.
Until last year the tagpdf package didn’t checksuch rules, so authors had to look up the lists manually to decide if a tagging structure is valid or not.
With more automated tagging, this became problematic: it became too easy to create a structurethat violates the rules, so a data structure to store
and automatically check the parent-child relation hasbeen implemented. This isn’t trivial, as the checks
have to take role mapping and slight differences between PDF 1.7 and PDF 2.0 into account, and handle
special tags (Part, Div and NonStruct) that don’t
have their own rules but inherit the containment rulefrom their parent in the structures.
4

What is possible today:
Tagging of “Leslie Lamport Documents”

The next milestone in the project is to enable theautomated tagging of what we call “Leslie Lamport

Automated tagging of LATEX documents — what is possible today, in 2023?

264

TUGboat, Volume 44 (2023), No. 2Documents”. These are documents which use environments and commands as described in the LATEX
manual [7]. They are based on the standard classes
article, report and book and load only a restricted
set of compatible packages.
The code is being developed in various modules
in the latex-lab bundle, and can be loaded in the\DocumentMetadata command with the testphasekey. The supported values for the key are describedin documentmetadata-support-doc.pdf. In LATEX
2023-06-01, phase-III is the most comprehensive
value that loads almost all available modules, andalso activates tagging.
\DocumentMetadata{testphase=phase-III}\documentclass{article}
Please refer to the documentation for details of thedifferent modules.
The following sections describe what is taggedin this phase. For engines, pdfLATEX or LuaLATEX
are recommended; other engines may work but are
not much tested and do not offer support for real
space characters and so give less accessible PDFs.
4.1

Links

The hyperref package is fully supported and links(both internal and external) are automatically tagged.
4.2

Paragraphs

Paragraphs are tagged with the help of the para
hooks. Page breaks in paragraphs are handled automatically [8] through patches of the output routine.
This mechanism usually works well, but there
can be problems if paragraphs are directly nested(the parent-child rules do not allow that), if the para
hooks are not balanced (e.g., if a low-level \vbox
is not properly ended with a \par), or if a package
operates with low-level paragraph commands suchas \everypar in an unexpected way.
4.3

like \@startsection and \@sect are redefined. The
tagging not only surrounds the titles with a structure but also adds a Sect structure around heading
and body of every section (see figure 4). Classes
like memoir or KOMA and packages like titlesec areincompatible.
This implementation will not stay; the long-termplan is to reimplement the sectioning commands tooffer more configuration options.
4.5

Tables of contents and similar lists

The implementation of the tagging support is rather
lightweight and redefines, for example, \@starttoc,\addcontentsline, \@dottedtocline, \l@part, etc.
Classes and packages like memoir, KOMA, titletoc
and etoc are incompatible. Classes and documentsthat (re)define \l@part, \l@chapter or \l@section
must adapt these definitions to add the hooks needed
for tagging. An example of such a redefinition canbe found in ltugboat.cls.

Footnotes

The latex-lab module for footnotes is a full reimplementation of the footnote code and adds hooks
and configuration points needed both for tagging andfor the configuration of footnote layouts.
This code is not compatible with classes likememoir or KOMA, or with packages such as bigfoot,manyfoot or footnote that redefine internals related
to footnotes. A replacement for the footmisc package has been written, so this package is alreadysupported.
4.4

Figure 4: Tagging of sectioning commands

Sectioning

The changes to sectioning commands are currently
rather lightweight; only a few internal commands
Ulrike Fischer, Frank Mittelbach

4.6

Display environments and lists

The list implementation in standard LATEX servesa dual purpose: it implements true lists such as
itemize and enumerate, and is also used as the basis
for vertical blocks such as center, quote, verbatim,
and for the theorem environments. These are all
implemented as “trivial” lists with a single (hidden)
item.
While this was convenient to get a consistent layout, it is not adequate when it comes to interpretingthe structure of a document, because environments
based on trivlist should not advertise themselves
as being a “list” — after all, from a semantic point ofview they aren’t lists.

TUGboat, Volume 44 (2023), No. 2

265

These environments have therefore been fully
reimplemented and extended based on templates(from the xtemplate package). The code is currently
incompatible with important packages like enumitem,enumerate, fancyvrb, listings, and also with theorem packages. Replacements or adaptations will beprovided at a later stage.
4.7

Citations and bibliographies

Bibliographies are typically lists and so tagged by thelist code of the previous section. Citations are tagged
as Reference and point to the relevant bibliography
entry. The natbib package is supported. biblatex
is supported if hyperref is used.

Figure 5: Example structure tree with figure

4.11
4.8

Graphics

Graphics cannot be tagged automatically: For accessibility the author has to provide an alternative text. As an interface the new code adds2 to\includegraphics and the picture environmentan alt key that an author can use for this purpose.
TikZ is not yet supported, but should follow soon.
\includegraphics[alt={This shows a duck}]{duck}\begin{picture}[alt={This shows a duck too}](100,100)...
\end{picture}
4.9

FloatsFloats (currently only figure and table) are tagged
as “endfloats”. That means the structures are moved
to the end of the structure tree.3 An example tree
is shown in figure 5. The code also changes theplacement of the hyperref anchor: it is now moved
to the beginning of the float. If a float contains twocaptions, the author has to manually mark how thefloat should be split into two float structures.
Also missing, at the moment, is support for thefloat package, [H] (“here”) floats (they will need adifferent structure), subcaptions and \marginpar.
4.10

minipage and \parbox

Initial support for minipage and \parbox has been
added. But the content of such boxes can be arbitrarily complex, and it is unclear if the current codeworks as desired in all cases.
2 The alt key was added to \includegraphics in LAT X

E2021-11-15 but does nothing if tagging is not used.
3 Only the structures in the structure tree! This does notaffect the typesetting!

Text commands

The LATEX logo and \emph are tagged. To the logo
an alternative text is added, and \emph is tagged
as EM. \textbf is not tagged by default as it is too
often used without a semantic meaning.
4.12

Math

There is also an early prototype for tagging formulas.
It is not yet included in phase-III but can be loaded
as an additional module:\DocumentMetadata{testphase={phase-III,math}}
The code grabs the content of the math and reprocesses it. The code is compatible with amsmath (thatpackage is explicitly loaded) but not compatible withpackages defining their own math environments. Because of the missing PDF 2.0 support it is currently
not possible to test if the provided tagging is in factadequate.
The module can have side-effects on “fake math”,
for example urls from the url package, which internally use math mode for technical reasons, and aretagged as Formula at the time of this writing. Suchplaces must be found and handled separately.
4.13

Firstaid

latex-lab contains also a small module firstaid
which contains small temporary corrections to external packages to improve their compatibility withthe tagging code. Like the math module it must beloaded explicitly:\DocumentMetadata{testphase={phase-III,firstaid}}
5

What is missing

We are not yet at the point where we can state that
all elements described in Leslie Lamport’s manual on
LATEX are supported. One open point is \savebox
and \usebox (and the TEX counterparts). Reusing

Automated tagging of LATEX documents — what is possible today, in 2023?

266

TUGboat, Volume 44 (2023), No. 2

boxes still needs some research to decide how tohandle boxes with and without internal structure.
Indexes, glossaries and similar lists are currently
not properly handled either. They will not generate errors, but an index created with the standard theindex environment will tag every item andsubitem and subsubitem as a paragraph of its own,
so important semantic information about the nestingis lost.
And last, there is the structure with which thisarticle started: tables. It is not very difficult to surround table rows and cells with TR and TD structures.
But a properly tagged table should surround header
cells with TH and complex tables need to reference
the header from the data cells. The standard LATEX
input doesn’t mark up the headers of the table andit is not yet clear how the syntax can be extended
to detect headers reliably.
This was one of the three topics in the “tagging workshop” we ran a day before the 2023 TUG
conference in Bonn, Germany. A report from thisworkshop is given elsewhere in this issue [1].
6SummaryStarting with LATEX 2023-06-01, quite a large set ofstandard documents can be tagged in an automatedway — as an example this (TUGboat) article itself
has been tagged with the code.
There is still much to do. We are grateful foreveryone who tests the code and gives feedback. For
this we have opened a dedicated Github repository
for the tagging project where issues can be reported
and discussions can be opened:
https://github.com/latex3/tagging-project

References[1] D. Carlisle, U. Fischer, F. Mittelbach.
Report on the LATEX Tagged PDF Workshop,
TUG 2023. TUGboat 44(2):267–269,
2023. doi.org/10.47397/tb/44-2/
carlisle-taggedpdfworkshop23[2] U. Fischer. The tagpdf package.
ctan.org/pkg/tagpdf[3] U. Fischer. Creating accessible pdfs with LATEX.
TUGboat 41(1):26–28, 2020. tug.org/TUGboat/
tb41-1/tb127fischer-accessible.pdf[4] U. Fischer. On the road to Tagged PDF:
About StructElem, marked content, PDF/Aand squeezed bärs. TUGboat 42(2):170–173,
2021. doi.org/10.47397/tb/42-2/
tb131fischer-tagpdf[5] ISO. ISO 32000-2:2020(en), 2nd ed., 2020.
PDF 2.0. iso.org/en/contents/data/standard/07/58/75839.html[6] ISO. ISO/TS 32005:2023 , 1st ed., 2023.
PDF 1.7 and 2.0 structure namespace inclusion.
iso.org/en/contents/data/standard/04/58/45878.html[7] L. Lamport. LATEX: A Document Preparation
System: User’s Guide and Reference Manual .
Addison Wesley, 2nd ed., 1994.
[8] F. Mittelbach. Taming the beast — advancesin paragraph tagging with pdfTEX and XETEX(2021): Automatic paragraph tagging with thepdfTEX and XETEX engine[s] now possible.
latex-project.org/news/2022/09/06/
TUG-online-talks-21-22/[9] F. Mittelbach, the LATEX Project Team.
Quo vadis LATEX(3) Team — a look backand at the upcoming years. TUGboat
41(2):201–207, 2020. tug.org/TUGboat/
tb41-2/tb128mitt-quovadis.pdf⋄ Ulrike Fischer
LATEX project team
Bonn
Germany
ulrike.fischer (at) latex-project.org⋄ Frank Mittelbach
LATEX project team
Mainz
Germany
frank.mittelbach (at) latex-project.org
ORCID 0000-0001-6318-1230

Ulrike Fischer, Frank Mittelbach