Merge branch 'master' into knitr

# Conflicts:
#	paper_template/text.Rtex

paper_template/cdsc-paper.sty

@@ -6,12 +6,9 @@
 % 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.
+% Headings and the title block use the class's own \@startsection and
+% \@maketitle hooks, not titlesec and titling, which break tagging.
+% See the Customizing section of the README.
 %
 % Copyright 2009-2026 Benjamin Mako Hill <mako@atdot.cc>
 % Copyright 2008-2009 Kieran Healy <kjhealy@soc.duke.edu>
@@ -50,15 +47,9 @@
 
 \pagestyle{cdsc-page}
 
-%%% 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.
+%%% Section headings. \@startsection takes {name}{level}{indent}
+%%% {beforeskip}{afterskip}{style}; a negative afterskip runs the
+%%% heading in to the following paragraph.
 
 \makeatletter
 
@@ -75,7 +66,6 @@
   {\normalsize\itshape}}
 
 % 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}%
@@ -99,14 +89,9 @@
 \newcommand{\puB}{}
 \newcommand{\published}[1]{\gdef\puB{#1}}
 
-% \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.
+% \raggedright, not \flushleft: flushleft is a trivlist and would leave
+% a list open in the structure tree. The skips match titling's output;
+% the date slot keeps its space even when \date{} is empty.
 \renewcommand{\@maketitle}{%
   \null
   \vskip 2em%

paper_template/text.Rtex

@@ -1,14 +1,4 @@
-% Tagged PDF (PDF/UA-2) accessibility setup. The article class works
-% 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.
+% Tagged PDF (PDF/UA-2) accessibility setup.
 \DocumentMetadata{
   tagging=on,
   pdfversion=2.0,
@@ -163,13 +153,8 @@ 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}.
 
-% 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 which column a value belongs to. Without it, a table
-% reads as an undifferentiated grid of numbers. kable puts the column
-% names in a single header row, so {1} is right for the table below;
-% use {1,2} where two rows are headers. Set it for each table, since
-% it applies to the tables that follow it.
+% header-rows makes the first row TH rather than TD. kable emits the
+% column names as a single header row, so {1} is right here.
 \tagpdfsetup{table/header-rows={1}}
 \begin{table}
   \centering
@@ -198,24 +183,23 @@ fox jumps over the lazy dog \citep{989866}.
 
 \section{Accessible Figures and Tables}
 
-Table~\ref{tab:test} above is tagged with a header row. Figures need
-alt text, 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 it is wasted. These are worked examples;
-delete this section when you start writing.
+Table~\ref{tab:test} above is tagged with a header row, and the
+commented-out block below shows a figure carrying alt text. Both are
+here as worked examples; delete them along with this section when you
+start writing.
 
-% For a figure generated by a chunk, knitr passes the fig.alt option
-% through to the \includegraphics call it writes:
+% alt= is what a screen reader announces in place of the image. Say what
+% the reader should take from it, not what it is called. A decorative
+% image takes [artifact] instead, keeping it out of the reading order.
 %
-% <<edits_plot, echo=FALSE, fig.cap="A caption, read separately from the alt text.", fig.alt="Edit counts by year, rising sharply after 2005">>=
+% For a chunk-generated figure, knitr passes fig.alt through to the
+% \includegraphics call it writes:
+%
+% <<edits_plot, echo=FALSE, fig.cap="A caption.", fig.alt="Edit counts by year, rising sharply after 2005">>=
 % plot(year, edits)
 % @
 %
-% For a figure included from a file, put alt= on \includegraphics
-% directly. A purely decorative image takes [artifact] instead, which
-% keeps it out of the reading order entirely:
+% For a figure included from a file, put alt= on \includegraphics:
 %
 % \begin{figure}
 %   \centering
@@ -225,9 +209,8 @@ delete this section when you start writing.
 %   \label{fig:example}
 % \end{figure}
 
-% 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}
+% A layout table, used to position rather than present, takes
+% \tagpdfsetup{table/tagging=presentation}
 
 % bibliography here
 \setcounter{biburlnumpenalty}{9001}