From 7a3e5f4f831be7e298e590297a670919d74b81b8 Mon Sep 17 00:00:00 2001
From: Benjamin Mako Hill <mako@atdot.cc>
Date: Thu, 13 Aug 2026 18:18:37 -0700
Subject: [PATCH] paper_template (knitr): tag the kable table, show fig.alt for
 chunks

The merge from master brought in a static demo table and a LaTeX-only
figure example, neither of which suits this branch. This adapts them to
knitr.

\tagpdfsetup{table/header-rows={1}} now sits above the existing kable
table rather than above a hand-written duplicate, which is the case a
reader of this branch actually has: kable emits the column names as a
single header row, so those cells become TH and a screen reader can
announce which column a value belongs to. Verified in the built PDF,
which now carries two TH cells alongside its twelve TD.

The figure example gains the knitr form. A chunk passes its
description through the fig.alt option, which knitr writes into the
\includegraphics call it generates; the file-inclusion form is kept
alongside it for figures that do not come from a chunk. Both are
commented out, so knitr does not try to evaluate a plot of data the
template does not ship.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 paper_template/text.Rtex | 54 +++++++++++++++++++---------------------
 1 file changed, 25 insertions(+), 29 deletions(-)

diff --git a/paper_template/text.Rtex b/paper_template/text.Rtex
index 23eb40e..8335334 100644
--- a/paper_template/text.Rtex
+++ b/paper_template/text.Rtex
@@ -163,6 +163,14 @@ 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.
+\tagpdfsetup{table/header-rows={1}}
 \begin{table}
   \centering
 <<test_table, echo=FALSE>>=
@@ -190,19 +198,24 @@ 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.
+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.
 
-% 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.
+% For a figure generated by a chunk, knitr passes the fig.alt option
+% through to the \includegraphics call it writes:
+%
+% <<edits_plot, echo=FALSE, fig.cap="A caption, read separately from the alt text.", 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:
 %
 % \begin{figure}
 %   \centering
@@ -212,23 +225,6 @@ when you start writing.
 %   \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}