Merge branch 'master' into knitr

# Conflicts:
#	README

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
+The paper, memo, and letter templates produce tagged PDFs that declare
-LaTeX tagging project (\DocumentMetadata + tagpdf). You can verify
+PDF/UA-2 (ISO 14289-2). The poster template does not; see below.
-compliance with verapdf: https://verapdf.org/
+
+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 ===================
 ================================

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},

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 <mako@atdot.cc>
 % Copyright 2008-2009 Kieran Healy <kjhealy@soc.duke.edu>
 
@@ -36,20 +43,35 @@
 
 \pagestyle{cdsc-page-memo}
 
-%%% Section headings: large sans-serif bold uppercase, with the
+%%% Section headings: sans-serif bold uppercase, with the tight
-%%% tight before/after spacing the original memo style used.
+%%% before/after spacing the original memo style used.
-\usepackage{titlesec}
+%%%
+%%% \@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}
+\makeatletter
-  {\normalsize\sffamily\bfseries\MakeUppercase}{\thesection.}{0.5em}{}
-\titlespacing*{\section}{0pt}{*1.5}{1pt}
 
-\titleformat{\subsection}
+\renewcommand\section{\@startsection{section}{1}{\z@}%
-  {\small\sffamily\bfseries\MakeUppercase}{\thesubsection.}{0.5em}{}
+  {-1.8ex \@plus -1ex \@minus -.2ex}%
-\titlespacing*{\subsection}{0pt}{*1}{1pt}
+  {1pt}%
+  {\normalsize\sffamily\bfseries\MakeUppercase}}
 
-\titleformat{\subsubsection}[runin]
+\renewcommand\subsection{\@startsection{subsection}{2}{\z@}%
-  {\footnotesize\sffamily\bfseries}{\thesubsubsection.}{0.5em}{}[\hskip 0.5em]
+  {-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}

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

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 <mako@atdot.cc>
 % Copyright 2008-2009 Kieran Healy <kjhealy@soc.duke.edu>
 
 % 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.)
+%%% Section heading styles.
-\usepackage{titlesec}
+%%%
+%%% 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
+\makeatletter
-\titleformat{\section}
+
-  {\large\scshape}{\thesection.}{0.5em}{}
+% Sections: large small caps
-\titlespacing*{\section}{0pt}{*2}{1.7ex}
+\renewcommand\section{\@startsection{section}{1}{\z@}%
+  {-1.8ex \@plus -1ex \@minus -.2ex}%
+  {1.7ex \@plus .2ex}%
+  {\large\scshape}}
 
 % Subsections: italic
-\titleformat{\subsection}
+\renewcommand\subsection{\@startsection{subsection}{2}{\z@}%
-  {\normalsize\itshape}{\thesubsection.}{0.5em}{}
+  {-3.25ex \@plus -1ex \@minus -.2ex}%
+  {1.5ex \@plus .2ex}%
+  {\normalsize\itshape}}
 
-% Subsubsections: small bold, runin (matches memoir's negative skip behavior)
+% Subsubsections: small bold, run in to the following paragraph
-\titleformat{\subsubsection}[runin]
+% (the negative afterskip is what makes it run in)
-  {\small\bfseries}{\thesubsubsection.}{0.5em}{}[\hskip 0.5em]
+\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)
+%%% Title block: flush left, italic title, author below it.
-\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}
-
 %% \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

paper_template/text.Rtex

@@ -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}
 
 <<init, echo=FALSE>>=
 knit_hooks$set(document = function(x) {
@@ -181,6 +188,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]

poster_template/main.tex

@@ -1,24 +1,19 @@
-\DocumentMetadata{
+% ACCESSIBILITY: this poster is not a tagged PDF. The beamer class
-  pdfversion=2.0,
+% rejects \DocumentMetadata outright ("Class beamer Error: The beamer
-  pdfstandard=ua-2,
+% class is not compatible with \DocumentMetadata"), and the LaTeX
-  lang=en-US,
+% 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