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:
78
README
78
README
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user