diff --git a/README b/README index 02b7666..eca5413 100644 --- a/README +++ b/README @@ -50,13 +50,30 @@ 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. + ================================ === Accessibility ============== ================================ -All four templates produce PDF/UA-2 compliant tagged PDFs via the -LaTeX tagging project (\DocumentMetadata + tagpdf). You can verify -compliance with verapdf: https://verapdf.org/ +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. The paper and memo templates were originally built on the memoir class, which is incompatible with the LaTeX tagged-PDF code. They now @@ -64,6 +81,67 @@ use the standard article class with custom styling (cdsc-paper.sty and cdsc-memo.sty) to keep their previous look while supporting full tagging. +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: + + * 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. + + * 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. + + * 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. + +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: + + 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. + +Verifying +--------- + +To see whether a PDF really carries structure, open the tag tree in a +PDF reader that shows one, or check for the tags directly: + + python3 -c "import pikepdf,sys; d=pikepdf.open(sys.argv[1]); \ + print(d.Root.get('/StructTreeRoot') and 'tagged' or 'UNTAGGED')" file.pdf + +That confirms structure exists but not that the file conforms to +PDF/UA-2. Full conformance checking needs veraPDF +(https://verapdf.org/), which is not packaged in Debian. + +Posters +------- + +The poster template is not accessible and makes no accessibility +claim. The beamer class rejects \DocumentMetadata outright, and the +LaTeX Tagging Project lists beamer and beamerposter as no-support, +meaning incompatible and not expected to change. When a poster needs +an accessible version, build a companion document from the paper or +memo template. + ================================ === Branches =================== ================================