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}