From a024557f7d36047cda7bd878851911f9222b0c7c Mon Sep 17 00:00:00 2001 From: Benjamin Mako Hill Date: Thu, 13 Aug 2026 18:30:55 -0700 Subject: [PATCH] Enable tagging so the PDF/UA-2 claim is true The template declared pdfstandard=ua-2 and loaded tagpdf with \tagpdfsetup{activate-all}, which sets /Marked true and writes the conformance claim but does not turn on the kernel code that tags document structure. The result passed veraPDF's ua2 profile while its structure tree held nothing but /Document: every paragraph of the letter was marked as an artifact, so the checker had no untagged real content to complain about, and both alt= descriptions were dropped on the floor. That is a worse failure than an outright invalid file. A letter that announces itself as accessible and contains nothing readable is the one a person relying on a screen reader will trust. Adding tagging=on fixes it: the built letter now carries twenty tagged paragraphs and a Figure element holding the signature's alt text, and still passes ua2. The manual tagpdf lines are dropped since the kernel loads it. This requires TeX Live 2025 or later; on TeX Live 2024 the key is unknown and the build stops. The README gains that requirement, an Accessibility section, and a warning that a veraPDF pass is necessary but not sufficient. Co-Authored-By: Claude Opus 5 (1M context) --- README | 37 +++++++++++++++++++ ...n_letterhead_letter-matrix-deptartment.tex | 13 ++++++- 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/README b/README index 90f12ea..1c74874 100644 --- a/README +++ b/README @@ -36,10 +36,47 @@ On Debian or Ubuntu, install the following packages: On other systems, installing a full TeX Live distribution should provide everything needed. +TeX Live 2025 or later is required. The tagging code is not in TeX +Live 2024, where the build stops with "the key +'document/metadata/tagging' is unknown". Debian trixie ships TeX Live +2024. On Overleaf, set the version under Menu > Settings > TeX Live +version; it is not always high enough by default on an older project. + The two required fonts Matrix-II and OpenSans are both included in this repository, so no additional font packages are needed. +Accessibility +============= + +The letter is a tagged PDF declaring PDF/UA-2 (ISO 14289-2). Two keys +in the \DocumentMetadata block at the top of the .tex file do this, +and both are needed: tagging=on loads the kernel code that puts the +text into the PDF's structure tree, and pdfstandard=ua-2 writes the +conformance claim. The claim without the tagging produces a letter +that passes a conformance checker while containing nothing a screen +reader can read, so keep them together. + +Check a built letter with veraPDF (https://verapdf.org/, not packaged +in Debian): + + verapdf -f ua2 washington_letterhead_letter-matrix-deptartment.pdf + +Note that a PASS is necessary but not sufficient. A letter whose body +text is all marked as artifact passes too, because the standard only +requires that content which is not real be an artifact. 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 + +The signature image carries an alt= description, which is what a +screen reader announces in place of it. Keep that in place if you +swap in your own signature. The letterhead graphic in the page header +is treated as an artifact, like other running header content, so it +is skipped rather than described. + + Encrypted signature files =========================== diff --git a/washington_letterhead_letter-matrix-deptartment.tex b/washington_letterhead_letter-matrix-deptartment.tex index 5d35bee..c57002a 100644 --- a/washington_letterhead_letter-matrix-deptartment.tex +++ b/washington_letterhead_letter-matrix-deptartment.tex @@ -1,4 +1,15 @@ +% Tagged PDF (PDF/UA-2) accessibility setup. +% +% tagging=on is what actually builds the structure tree: it loads the +% kernel code that tags paragraphs, headings, and figures. Declaring +% pdfstandard=ua-2 on its own only writes the claim into the metadata. +% Without tagging=on this letter validated as PDF/UA-2 while its +% structure tree held nothing but /Document, its body text was marked +% as artifact, and the alt= descriptions below were silently dropped: +% a file that passes the checker and is unreadable to a screen reader. +% Needs TeX Live 2025 or later. \DocumentMetadata{ + tagging=on, pdfversion=2.0, pdfstandard=ua-2, lang=en-US, @@ -17,8 +28,6 @@ \usepackage[top=1.25in,left=1.25in,bottom=1.20in,right=1.25in]{geometry} \usepackage{fontspec} -\usepackage{tagpdf} -\tagpdfsetup{activate-all} \newopentypefeature{Contextuals}{NoAlternate}{-calt} \defaultfontfeatures{Kerning=Uppercase,Ligatures=TeX}