20
0

removed extra extraneous comments

Cuts the multi-line rationale blocks down to what a reader of the file
needs. The reasoning behind the tagging setup belongs in the commit
messages that introduced it, not repeated above every \DocumentMetadata
block.

Also trims the README: drops the consequence clause explaining what
happens when the standard is declared without the tagging, drops the
quoted TeX Live 2024 error message, and notes that sid has a new enough
TeX Live for anyone not on Overleaf. Adds the caveat that a veraPDF
PASS is necessary but not sufficient, since a document whose body text
is all artifact passes too.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-15 10:24:15 +09:00
parent 4ae0bddb40
commit f7e16a221c
7 changed files with 54 additions and 146 deletions

78
README
View File

@@ -50,13 +50,10 @@ All four templates build with LuaLaTeX (via latexmk -lualatex). The text
fonts are Libertinus Serif and TeX Gyre Heros, both provided by
texlive-fonts-extra.
The paper, memo, and letter templates need TeX Live 2025 or later. The
tagging code they rely on is not in TeX Live 2024, where the build
stops with "the key 'document/metadata/tagging' is unknown". Debian
trixie ships TeX Live 2024, so a trixie machine needs a newer TeX Live
from elsewhere in the archive. On Overleaf, choose the TeX Live
version under Menu > Settings > TeX Live version; 2025 or later is
required and is not always the default for an older project.
The tagging code requires TeX Live 2025 or later. On Overleaf, set the
version under Menu > Settings > TeX Live version. Debian Trixie ships
TeX Live 2024; sid (unstable) has TeX Live 2026, which also works and
installs without pulling in much else.
================================
=== Accessibility ==============
@@ -65,15 +62,10 @@ required and is not always the default for an older project.
The paper, memo, and letter templates produce tagged PDFs that declare
PDF/UA-2 (ISO 14289-2). The poster template does not; see below.
Tagging is switched on by the tagging=on key in the \DocumentMetadata
block at the top of each template. That key is what does the work: it
loads the kernel code that puts headings, paragraphs, lists, tables,
and figures into the PDF's structure tree, which is what a screen
reader walks. The neighbouring pdfstandard=ua-2 key only writes the
conformance claim into the file's metadata. Setting the standard
without setting tagging=on yields a PDF that announces itself as
accessible and contains nothing for assistive software to read, so
keep the two together.
Two keys in the \DocumentMetadata block at the top of each template do
this, and both are needed: tagging=on loads the kernel code that puts
headings, paragraphs, lists, tables, and figures into the PDF's
structure tree, and pdfstandard=ua-2 writes the conformance claim.
The paper and memo templates were originally built on the memoir
class, which is incompatible with the LaTeX tagged-PDF code. They now
@@ -85,62 +77,50 @@ Writing an accessible document
------------------------------
Tagging gets you the structure; the content is still up to the author.
Three things matter most, and the paper template carries a worked
example of each:
The paper template carries a worked example of each of these:
* Use \section and \subsection for headings rather than setting type
in bold by hand. Screen reader users navigate by the heading tree,
and hand-formatted text is invisible to it.
in bold by hand. Screen reader users navigate by the heading tree.
* Give every figure an alt= description on \includegraphics, saying
what the reader is meant to take from it. A decorative image takes
\includegraphics[artifact]{...} instead, keeping it out of the
reading order.
\includegraphics[artifact]{...} instead.
* Mark header rows on data tables with \tagpdfsetup{table/header-rows
={1}} so their cells become TH rather than TD. Without it a table
reads as an undifferentiated grid of values.
={1}} so their cells become TH rather than TD.
Customizing the styles
----------------------
Some common packages defeat tagging, and the failure is usually
silent: the document compiles without complaint and the tags are
simply missing. Before adding a package, check its status against the
LaTeX Tagging Project's list:
Some common packages defeat tagging, and the failure is silent: the
document compiles without complaint and the tags are simply missing.
Before adding a package, check it against the LaTeX Tagging Project's
list:
https://latex3.github.io/tagging-project/tagging-status/
titlesec and titling are the two to know about here, because they are
the obvious tools for the job cdsc-paper.sty and cdsc-memo.sty do.
titlesec replaces the \@startsection hook that the tagging code uses
to emit heading tags, so loading it produces a PDF with no headings in
the structure tree and no error to say so. Both style files therefore
build their headings and title blocks from the article class's own
\@startsection and \@maketitle hooks.
titlesec and titling are the two to know about, because they are the
obvious tools for the job cdsc-paper.sty and cdsc-memo.sty do.
titlesec replaces the \@startsection hook the tagging code uses to
emit heading tags, so loading it produces a PDF with no headings in
the structure tree.
Verifying
---------
Check a built PDF against the standard with veraPDF:
You can check a built PDF with veraPDF (https://verapdf.org/):
verapdf -f ua2 text.pdf
It prints PASS or FAIL for the file, and --format text will list the
clauses that failed. All four of the tagged templates pass as shipped,
so a FAIL means something in the document needs attention rather than
something in the template.
It prints PASS or FAIL, and --format text lists the failing clauses.
All three tagged templates pass as shipped, so a FAIL points at the
document rather than the template.
Run it. A document that declares PDF/UA-2 and does not meet it is
worse than one that makes no claim, because the claim is what a reader
relying on assistive software will trust. The declaration costs one
line and validating it is the only thing that makes the line true.
Note that a PASS is necessary but not sufficient. A document whose
body text is all marked as artifact passes too, because the standard
only requires that content which is not real be an artifact.
veraPDF is not packaged in Debian; download it from
https://verapdf.org/ and put it on your PATH.
For a quicker look at whether a PDF carries any structure at all,
without checking conformance:
You can confirm there is something in the structure tree as well:
python3 -c "import pikepdf,sys; d=pikepdf.open(sys.argv[1]); \
print(d.Root.get('/StructTreeRoot') and 'tagged' or 'UNTAGGED')" file.pdf