From 172cd5c4e5156470dc9b8355a2a1b316134324e6 Mon Sep 17 00:00:00 2001 From: Benjamin Mako Hill Date: Mon, 11 May 2026 16:07:36 -0700 Subject: [PATCH 1/6] templates: swap EB Garamond for Libertinus Serif EB Garamond's bold weight ships with only 127 cmapped glyphs --- no Latin Extended-A, no Vietnamese, no Greek, no Cyrillic, no fi/fl ligatures --- so any bold text containing accented characters (Polish, Czech, Vietnamese, etc., as well as bold author names in citations) renders as tofu boxes or font-fallback substitutions. Switch the default body font in paper_template, memo_template, and letter_template to Libertinus Serif. It ships in texlive-fonts-extra, has comprehensive Latin / Vietnamese / Greek / Cyrillic coverage in every weight, and includes all the standard f-ligatures explicitly. Each template also picks up a commented-out \\setmainfont{Garamond Premier Pro} block plus a short note: Adobe Garamond Premier Pro is Mako's preferred body font but is commercial and not redistributable, so the public templates default to Libertinus and CDSC members can swap in once they have the font installed (e.g., in ~/.fonts/). README updated to match. Co-Authored-By: Claude Sonnet 4.6 --- README | 4 ++-- letter_template/text.tex | 10 +++++++++- memo_template/text.tex | 10 +++++++++- paper_template/text.tex | 10 +++++++++- 4 files changed, 29 insertions(+), 5 deletions(-) diff --git a/README b/README index 3682b11..02b7666 100644 --- a/README +++ b/README @@ -47,8 +47,8 @@ On other systems, installing a full TeX Live distribution should provide everything needed. All four templates build with LuaLaTeX (via latexmk -lualatex). The text -fonts are EB Garamond (provided by texlive-fonts-extra) and TeX Gyre -Heros. +fonts are Libertinus Serif and TeX Gyre Heros, both provided by +texlive-fonts-extra. ================================ === Accessibility ============== diff --git a/letter_template/text.tex b/letter_template/text.tex index abb1b5f..f7d2e6d 100644 --- a/letter_template/text.tex +++ b/letter_template/text.tex @@ -10,7 +10,15 @@ % (-- => en-dash, --- => em-dash, `` and '' => curly quotes), so % re-enable them globally for every font loaded below. \defaultfontfeatures{Ligatures=TeX} -\setmainfont{EB Garamond} +\setmainfont{Libertinus Serif} +% Mako prefers Adobe Garamond Premier Pro +% (https://fonts.adobe.com/fonts/garamond-premier-pro). It is a +% commercial font and is not redistributable, so the templates default +% to the free Libertinus Serif above. If you have the font installed +% (e.g., dropped into ~/.fonts/), comment the line above and uncomment +% the next one. CDSC members can contact Mako (mako@atdot.cc) for the +% font files. +% \setmainfont{Garamond Premier Pro} \setsansfont{TeX Gyre Heros} \usepackage[letterpaper,left=1.3in,right=1.3in,top=0.8in,bottom=0.8in]{geometry} diff --git a/memo_template/text.tex b/memo_template/text.tex index 6ab2f72..a47ccbe 100644 --- a/memo_template/text.tex +++ b/memo_template/text.tex @@ -18,7 +18,15 @@ % (-- => en-dash, --- => em-dash, `` and '' => curly quotes), so % re-enable them globally for every font loaded below. \defaultfontfeatures{Ligatures=TeX} -\setmainfont{EB Garamond} +\setmainfont{Libertinus Serif} +% Mako prefers Adobe Garamond Premier Pro +% (https://fonts.adobe.com/fonts/garamond-premier-pro). It is a +% commercial font and is not redistributable, so the templates default +% to the free Libertinus Serif above. If you have the font installed +% (e.g., dropped into ~/.fonts/), comment the line above and uncomment +% the next one. CDSC members can contact Mako (mako@atdot.cc) for the +% font files. +% \setmainfont{Garamond Premier Pro} \setsansfont{TeX Gyre Heros} \usepackage[letterpaper,left=1.65in,right=1.65in,top=1.3in,bottom=1.2in]{geometry} diff --git a/paper_template/text.tex b/paper_template/text.tex index 26571b0..efc59dd 100644 --- a/paper_template/text.tex +++ b/paper_template/text.tex @@ -18,7 +18,15 @@ % (-- => en-dash, --- => em-dash, `` and '' => curly quotes), so % re-enable them globally for every font loaded below. \defaultfontfeatures{Ligatures=TeX} -\setmainfont{EB Garamond} +\setmainfont{Libertinus Serif} +% Mako prefers Adobe Garamond Premier Pro +% (https://fonts.adobe.com/fonts/garamond-premier-pro). It is a +% commercial font and is not redistributable, so the templates default +% to the free Libertinus Serif above. If you have the font installed +% (e.g., dropped into ~/.fonts/), comment the line above and uncomment +% the next one. CDSC members can contact Mako (mako@atdot.cc) for the +% font files. +% \setmainfont{Garamond Premier Pro} \setsansfont{TeX Gyre Heros} \usepackage{wrapfig} From 1a469bac1bd9cea6775d64adc903294a10f5c8e9 Mon Sep 17 00:00:00 2001 From: Benjamin Mako Hill Date: Thu, 13 Aug 2026 18:15:33 -0700 Subject: [PATCH 2/6] cdsc-paper.sty, cdsc-memo.sty: build headings without titlesec The tagging code hooks \@startsection to emit the H1/H2/H3 tags that a screen reader navigates by. titlesec replaces \section wholesale rather than going through that hook, so every heading vanished from the structure tree --- with no error to say so, which is why this went unnoticed. titling separately left an unclosed trivlist behind its \flushleft declarations, producing "the number of automatic begin and end text-unit para hooks differ" and a mis-nested tree. Both files now style headings through \@startsection and the title block through \@maketitle, using the class's own hooks. The style argument of \@startsection is applied to the whole heading, so the memo's uppercase headings append \MakeUppercase to it; the tagging code wraps the section number in \NoCaseChange so the number is left alone. Vertical spacing was matched against the previous output page by page: the memo now renders identically bar one heading a pixel off, and the paper's title block lands within two pixels. datetime is dropped from cdsc-paper.sty. Only \today was ever used from it and that is built in. Co-Authored-By: Claude Opus 5 (1M context) --- memo_template/cdsc-memo.sty | 65 ++++++++++++++++--------- paper_template/cdsc-paper.sty | 89 +++++++++++++++++++++++++---------- 2 files changed, 107 insertions(+), 47 deletions(-) diff --git a/memo_template/cdsc-memo.sty b/memo_template/cdsc-memo.sty index 3f7d704..0332b9e 100644 --- a/memo_template/cdsc-memo.sty +++ b/memo_template/cdsc-memo.sty @@ -2,12 +2,19 @@ % % Article-class equivalent of the old cdsc-memo chapterstyle that % lived in cdsc-memoir.sty. Targets the standard `article' class so -% the LaTeX tagging-project can produce tagged, accessible PDFs. +% the LaTeX tagging project can produce tagged, accessible PDFs. % % Look-and-feel: sans-serif uppercase title and author on a single % line, sans-serif uppercase section headings, no paragraph indent, % and a small-caps "page/total" footer. % +% Headings come from the article class's own \@startsection hook +% rather than from titlesec. The tagging code hooks into +% \@startsection to emit the H1, H2, and H3 tags a screen reader +% navigates by; titlesec bypasses that hook, so loading it silently +% produces a PDF with no headings in the structure tree. See the +% Accessibility section of the README. +% % Copyright 2009-2026 Benjamin Mako Hill % Copyright 2008-2009 Kieran Healy @@ -36,20 +43,35 @@ \pagestyle{cdsc-page-memo} -%%% Section headings: large sans-serif bold uppercase, with the -%%% tight before/after spacing the original memo style used. -\usepackage{titlesec} +%%% Section headings: sans-serif bold uppercase, with the tight +%%% before/after spacing the original memo style used. +%%% +%%% \@startsection takes {name}{level}{indent}{beforeskip}{afterskip} +%%% {style}. The style argument is applied to the whole heading as an +%%% argument, so \MakeUppercase can be appended to it; the tagging +%%% code wraps the section number in \NoCaseChange so the number is +%%% left alone. A negative afterskip makes a heading run in to the +%%% paragraph that follows it. -\titleformat{\section} - {\normalsize\sffamily\bfseries\MakeUppercase}{\thesection.}{0.5em}{} -\titlespacing*{\section}{0pt}{*1.5}{1pt} +\makeatletter -\titleformat{\subsection} - {\small\sffamily\bfseries\MakeUppercase}{\thesubsection.}{0.5em}{} -\titlespacing*{\subsection}{0pt}{*1}{1pt} +\renewcommand\section{\@startsection{section}{1}{\z@}% + {-1.8ex \@plus -1ex \@minus -.2ex}% + {1pt}% + {\normalsize\sffamily\bfseries\MakeUppercase}} -\titleformat{\subsubsection}[runin] - {\footnotesize\sffamily\bfseries}{\thesubsubsection.}{0.5em}{}[\hskip 0.5em] +\renewcommand\subsection{\@startsection{subsection}{2}{\z@}% + {-1.3ex \@plus -1ex \@minus -.2ex}% + {1pt}% + {\small\sffamily\bfseries\MakeUppercase}} + +\renewcommand\subsubsection{\@startsection{subsubsection}{3}{\z@}% + {-1ex \@plus -1ex \@minus -.2ex}% + {-0.5em}% + {\footnotesize\sffamily\bfseries}} + +% Period after the section number, when numbering is switched on below +\renewcommand{\@seccntformat}[1]{\csname the#1\endcsname.\hspace{0.5em}} % By default, suppress section numbering. To enable numbered sections % and subsections, comment the line below and uncomment the alternative. @@ -57,20 +79,21 @@ % \setcounter{secnumdepth}{2} %%% Title block: "TITLE [...] AUTHOR" on a single line, no date. -\usepackage{titling} - -\renewcommand{\maketitle}{% - \par\noindent\footnotesize\puB\par - {\large\sffamily\bfseries\MakeUppercase\thetitle}\hfill - {\large\sffamily\MakeUppercase\theauthor}% - \par\vskip 0.7em% -} - +%% %% \published{...}: a note about publication status, printed in small %% type at the very top of the title block. \newcommand{\puB}{} \newcommand{\published}[1]{\gdef\puB{#1}} +\renewcommand{\maketitle}{% + \par\noindent\footnotesize\puB\par + {\large\sffamily\bfseries\MakeUppercase{\@title}}\hfill + {\large\sffamily\MakeUppercase{\@author}}% + \par\vskip 0.7em% +} + +\makeatother + %%% List spacing \usepackage{enumitem} \setlist{topsep=0pt, partopsep=0pt} diff --git a/paper_template/cdsc-paper.sty b/paper_template/cdsc-paper.sty index 672ee09..ee532e0 100644 --- a/paper_template/cdsc-paper.sty +++ b/paper_template/cdsc-paper.sty @@ -1,18 +1,23 @@ % Article-class styles and page layout for CDSC paper documents. % % This file replaces the older cdsc-memoir.sty. It targets the -% standard `article' class so the LaTeX tagging-project can produce +% standard `article' class so the LaTeX tagging project can produce % tagged, accessible PDFs --- memoir is currently incompatible with % that work. The look-and-feel is kept as close to the previous % cdsc-article chapterstyle as is practical. % +% Headings and the title block are built from the article class's own +% \@startsection and \@maketitle hooks rather than from titlesec and +% titling. The tagging code hooks into \@startsection to emit the H1, +% H2, and H3 tags a screen reader navigates by; titlesec bypasses that +% hook, so loading it silently produces a PDF with no headings in the +% structure tree. See the Accessibility section of the README. +% % Copyright 2009-2026 Benjamin Mako Hill % Copyright 2008-2009 Kieran Healy % Distributed as free software under the GNU GPL v3 -\usepackage{lastpage} -\usepackage{datetime} \usepackage{xcolor} %%% Page styles (replaces memoir's \makepagestyle / \makeevenhead etc.) @@ -45,21 +50,39 @@ \pagestyle{cdsc-page} -%%% Section heading styles (replaces memoir's \setsecheadstyle etc.) -\usepackage{titlesec} +%%% Section heading styles. +%%% +%%% Each heading is declared through \@startsection, which takes: +%%% {name}{level}{indent}{beforeskip}{afterskip}{style} +%%% A negative beforeskip suppresses the paragraph indent that would +%%% otherwise follow the heading; a negative afterskip makes the +%%% heading run into the paragraph text rather than sit on its own +%%% line. The style argument receives the whole heading as its +%%% argument, so a case-changing command may be appended to it. -% Sections: large small caps; period after the number -\titleformat{\section} - {\large\scshape}{\thesection.}{0.5em}{} -\titlespacing*{\section}{0pt}{*2}{1.7ex} +\makeatletter + +% Sections: large small caps +\renewcommand\section{\@startsection{section}{1}{\z@}% + {-1.8ex \@plus -1ex \@minus -.2ex}% + {1.7ex \@plus .2ex}% + {\large\scshape}} % Subsections: italic -\titleformat{\subsection} - {\normalsize\itshape}{\thesubsection.}{0.5em}{} +\renewcommand\subsection{\@startsection{subsection}{2}{\z@}% + {-3.25ex \@plus -1ex \@minus -.2ex}% + {1.5ex \@plus .2ex}% + {\normalsize\itshape}} -% Subsubsections: small bold, runin (matches memoir's negative skip behavior) -\titleformat{\subsubsection}[runin] - {\small\bfseries}{\thesubsubsection.}{0.5em}{}[\hskip 0.5em] +% Subsubsections: small bold, run in to the following paragraph +% (the negative afterskip is what makes it run in) +\renewcommand\subsubsection{\@startsection{subsubsection}{3}{\z@}% + {-3.25ex \@plus -1ex \@minus -.2ex}% + {-0.5em}% + {\small\bfseries}} + +% Period after the section number, when numbering is switched on below +\renewcommand{\@seccntformat}[1]{\csname the#1\endcsname.\hspace{0.5em}} % By default, suppress numbering at the section level (matches the % memoir template's default of \setsecnumdepth{chapter}). To enable @@ -68,23 +91,37 @@ \setcounter{secnumdepth}{0} % \setcounter{secnumdepth}{2} -%%% Title block (titling package replaces memoir's title hooks) -\usepackage{titling} - -% Title flush left, italic, large -\pretitle{\flushleft\LARGE\itshape} -\posttitle{\par\vskip 0.5em} -\preauthor{\flushleft\large\lineskip 1em} -\postauthor{\par\lineskip 1em} -\predate{\flushleft\footnotesize\vspace{0.65em}} -\postdate{\par\vskip 1em} - +%%% Title block: flush left, italic title, author below it. +%% %% \published{...}: a note about the publication status, printed in %% small type at the very top of the title block. Use this for %% draft/working-paper notices. \newcommand{\puB}{} \newcommand{\published}[1]{\gdef\puB{#1}} -\renewcommand{\maketitlehooka}{\par\noindent\footnotesize\puB} + +% \raggedright rather than \flushleft: the flushleft environment is a +% trivlist, and starting one as a bare declaration leaves a list open +% in the structure tree. That produces "the number of automatic begin +% and end text-unit para hooks differ" and a mis-nested PDF. +% The vertical skips reproduce what titling's \pretitle/\posttitle, +% \preauthor/\postauthor, and \predate/\postdate produced. The date +% slot keeps its space even when \date{} is empty, which is what the +% previous title block did and what the template's spacing assumes. +\renewcommand{\@maketitle}{% + \null + \vskip 2em% + \par\noindent\footnotesize\puB\par + \vskip 0.79em% + {\raggedright\LARGE\itshape\@title\par}% + \vskip 1.04em% + {\raggedright\large\lineskip 1em\@author\par}% + \vskip 0.79em% + {\raggedright\footnotesize\@date\par}% + \vskip 1em% + \par\vskip 2.44em% +} + +\makeatother %%% Abstract: runin style ("**Abstract:** the quick brown fox..."), %%% indented from both margins (via the quote environment, which gives From 0a43387d2e753f8b026323cf163b26938d35caaa Mon Sep 17 00:00:00 2001 From: Benjamin Mako Hill Date: Thu, 13 Aug 2026 18:15:48 -0700 Subject: [PATCH 3/6] memo, letter: enable tagging with \DocumentMetadata{tagging=on} These templates declared pdfstandard=ua-2 and loaded tagpdf with \tagpdfsetup{activate-all}. That combination sets /Marked true and writes the PDF/UA-2 claim into the metadata, but activate-all is tagpdf's low-level switch and does not turn on the kernel code that tags document structure. The result was a file announcing itself as accessible while carrying nothing for assistive software to read: the memo's structure tree held one /Document and two /Link nodes, and the letter's held /Document alone. tagging=on loads that kernel code. The memo now tags three headings, a subsection, its paragraphs and its bibliography list; the letter tags all ten body paragraphs. The manual tagpdf lines are no longer needed since the kernel loads it. This requires TeX Live 2025 or later; on TeX Live 2024 the key is unknown and the build stops. Co-Authored-By: Claude Opus 5 (1M context) --- letter_template/text.tex | 13 ++++++++++--- memo_template/text.tex | 13 ++++++++++--- 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/letter_template/text.tex b/letter_template/text.tex index f7d2e6d..ccec5cf 100644 --- a/letter_template/text.tex +++ b/letter_template/text.tex @@ -1,4 +1,14 @@ +% 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, lists, tables, and +% floats. Declaring pdfstandard=ua-2 on its own only writes the claim +% into the metadata; without tagging=on the PDF is marked as UA-2 but +% carries no structure for a screen reader to read. This needs TeX +% Live 2025 or later --- on Overleaf, set it in Menu > Settings > +% TeX Live version. \DocumentMetadata{ + tagging=on, pdfversion=2.0, pdfstandard=ua-2, lang=en-US, @@ -23,9 +33,6 @@ \usepackage[letterpaper,left=1.3in,right=1.3in,top=0.8in,bottom=0.8in]{geometry} -\usepackage{tagpdf} -\tagpdfsetup{activate-all} - \usepackage{hyperref} \hypersetup{unicode=true, pdftitle={Letter}, diff --git a/memo_template/text.tex b/memo_template/text.tex index a47ccbe..9fbe5c7 100644 --- a/memo_template/text.tex +++ b/memo_template/text.tex @@ -1,7 +1,16 @@ % Tagged PDF (PDF/UA-2) accessibility setup. The article class works -% with the LaTeX tagging-project, so we use the full \DocumentMetadata +% with the LaTeX tagging project, so we use the full \DocumentMetadata % path here. +% +% tagging=on is what actually builds the structure tree: it loads the +% kernel code that tags paragraphs, headings, lists, tables, and +% floats. Declaring pdfstandard=ua-2 on its own only writes the claim +% into the metadata; without tagging=on the PDF is marked as UA-2 but +% carries no structure for a screen reader to read. This needs TeX +% Live 2025 or later --- on Overleaf, set it in Menu > Settings > +% TeX Live version. \DocumentMetadata{ + tagging=on, pdfversion=2.0, pdfstandard=ua-2, lang=en-US, @@ -10,8 +19,6 @@ \documentclass[12pt]{article} \usepackage{cdsc-memo} -\usepackage{tagpdf} -\tagpdfsetup{activate-all} \usepackage{fontspec} % fontspec disables the classic TeX input ligatures by default From 331b6525af2e6584b4ebac70df8e828007d60756 Mon Sep 17 00:00:00 2001 From: Benjamin Mako Hill Date: Thu, 13 Aug 2026 18:15:48 -0700 Subject: [PATCH 4/6] paper_template: enable tagging, add alt text and header row examples Switches to \DocumentMetadata{tagging=on} for the reasons described in the previous commit; the structure tree went from /Document plus eleven /Link nodes to three headings, twenty paragraphs, a tagged list and the abstract as a block quote. Adds a worked example of the two things tagging cannot do for an author. A data table carries \tagpdfsetup{table/header-rows={1}}, which makes its first row TH rather than TD so a screen reader can announce which column a value belongs to. A commented-out figure shows the alt= argument to \includegraphics, which is what gets announced in place of an image; it is left commented so the template does not have to ship a binary, and mentions [artifact] for decorative images. Co-Authored-By: Claude Opus 5 (1M context) --- paper_template/text.tex | 58 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 3 deletions(-) diff --git a/paper_template/text.tex b/paper_template/text.tex index efc59dd..5a3bc2d 100644 --- a/paper_template/text.tex +++ b/paper_template/text.tex @@ -1,7 +1,16 @@ % Tagged PDF (PDF/UA-2) accessibility setup. The article class works -% with the LaTeX tagging-project, so we use the full \DocumentMetadata +% with the LaTeX tagging project, so we use the full \DocumentMetadata % path here. +% +% tagging=on is what actually builds the structure tree: it loads the +% kernel code that tags paragraphs, headings, lists, tables, and +% floats. Declaring pdfstandard=ua-2 on its own only writes the claim +% into the metadata; without tagging=on the PDF is marked as UA-2 but +% carries no structure for a screen reader to read. This needs TeX +% Live 2025 or later --- on Overleaf, set it in Menu > Settings > +% TeX Live version. \DocumentMetadata{ + tagging=on, pdfversion=2.0, pdfstandard=ua-2, lang=en-US, @@ -10,8 +19,6 @@ \documentclass[12pt]{article} \usepackage{cdsc-paper} -\usepackage{tagpdf} -\tagpdfsetup{activate-all} \usepackage{fontspec} % fontspec disables the classic TeX input ligatures by default @@ -201,6 +208,51 @@ brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog \citep{989866}. +\section{Accessible Figures and Tables} + +Table~\ref{tab:example} shows a data table whose header row is tagged, +and the commented-out block below it shows a figure carrying alt text. +Both are here as worked examples; delete them along with this section +when you start writing. + +% ACCESSIBILITY: every figure needs an alt= description, which is what +% a screen reader announces in place of the image. Describe what the +% reader is meant to take from the figure rather than naming it: "Edit +% counts rising sharply after 2005" tells them something, "Figure 1" +% does not. The caption is read separately, so alt text that repeats +% the caption is wasted. For a purely decorative image, use +% \includegraphics[artifact]{...} instead, which keeps it out of the +% reading order entirely. +% +% \begin{figure} +% \centering +% \includegraphics[width=0.6\linewidth, +% alt={Edit counts by year, rising sharply after 2005}]{figure.pdf} +% \caption{A caption, which is read separately from the alt text.} +% \label{fig:example} +% \end{figure} + +% ACCESSIBILITY: header-rows tells the tagging code which rows are +% headers, so their cells become TH rather than TD and a screen reader +% can announce the column a value belongs to. Without it, a data table +% reads as an undifferentiated grid of numbers. Set it for each table +% that has headers; use {1,2} if two rows are headers. +\tagpdfsetup{table/header-rows={1}} +\begin{table} + \centering + \begin{tabular}{lr} + Item & Quantity \\ \hline + Widgets & 42 \\ + Gadgets & 13 + \end{tabular} + \caption{A data table whose first row is tagged as headers.} + \label{tab:example} +\end{table} + +% A table used only to position things on the page, rather than to +% present data, should be marked so assistive software skips its +% structure: \tagpdfsetup{table/tagging=presentation} + % bibliography here \setcounter{biburlnumpenalty}{9001} \printbibliography[title = {References}, heading=secbib] From 3fe02af221ce35b2dfc206eb977a836d0c5b6776 Mon Sep 17 00:00:00 2001 From: Benjamin Mako Hill Date: Thu, 13 Aug 2026 18:16:01 -0700 Subject: [PATCH 5/6] poster_template: drop the PDF/UA-2 claim beamer cannot honour The poster declared \DocumentMetadata with pdfstandard=ua-2 and patched the frametitle template to emit H1 tags. On TeX Live 2024 that produced an untagged PDF carrying an accessibility claim it did not meet. On TeX Live 2025, which is what Overleaf runs, it does not build at all: ! Class beamer Error: The beamer class is not compatible with \DocumentMetadata The LaTeX Tagging Project lists beamer and beamerposter as no-support, meaning incompatible and not expected to change, and beamerposter pulls in textpos and subfig which are incompatible in their own right. There is no fix available, so the template now makes no claim and says why. Removing the block also gets the poster building again. Co-Authored-By: Claude Opus 5 (1M context) --- poster_template/main.tex | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/poster_template/main.tex b/poster_template/main.tex index d6190fa..6c549f6 100644 --- a/poster_template/main.tex +++ b/poster_template/main.tex @@ -1,24 +1,19 @@ -\DocumentMetadata{ - pdfversion=2.0, - pdfstandard=ua-2, - lang=en-US, -} +% ACCESSIBILITY: this poster is not a tagged PDF. The beamer class +% rejects \DocumentMetadata outright ("Class beamer Error: The beamer +% class is not compatible with \DocumentMetadata"), and the LaTeX +% Tagging Project lists both beamer and beamerposter as no-support, +% meaning incompatible and not expected to change. beamerposter also +% pulls in textpos and subfig, which are incompatible in their own +% right. +% +% There is no way to make this template produce an accessible PDF +% today. Rather than declare PDF/UA-2 and ship an untagged file, it +% makes no claim at all. If a poster has to be accessible, supply a +% tagged companion document built from the paper or memo template. \documentclass[xcolor=dvipsnames, 12pt]{beamer} \usepackage[size=custom, width=114, height=80, scale=1.5]{beamerposter} -\usepackage{tagpdf} -\tagpdfsetup{activate-all} - -% Tag frame titles as H1 headings for PDF accessibility -\addtobeamertemplate{frametitle}{% - \tagstructbegin{tag=H1}% - \tagmcbegin{tag=H1}% -}{% - \tagmcend% - \tagstructend% -} - \usepackage[absolute,overlay]{textpos} % set up the file to create notes in the output PDFs From b94d69f6a3eb35b1f0c13630526e27851e4b6e8a Mon Sep 17 00:00:00 2001 From: Benjamin Mako Hill Date: Thu, 13 Aug 2026 18:16:01 -0700 Subject: [PATCH 6/6] README: document what makes the tagging work, and what defeats it Records that tagging=on is the key doing the work and pdfstandard=ua-2 only writes the claim, since setting the second without the first is the failure this series fixes and is easy to reintroduce. Adds the TeX Live 2025 requirement to Dependencies, including that Debian trixie ships 2024 and that Overleaf projects choose their TeX Live version in the settings menu and do not always default high enough. Adds sections on writing an accessible document (headings, alt text, table header rows), on customizing the styles, and on verifying that a PDF really carries structure. The customizing section names titlesec and titling specifically: they are the obvious tools for the job the two style files do, and they break tagging silently. Notes that the poster is not accessible and makes no claim. Co-Authored-By: Claude Opus 5 (1M context) --- README | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 81 insertions(+), 3 deletions(-) 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 =================== ================================