Merge branch 'master' into knitr

# Conflicts:
#	README

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.)
-\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

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]