From e2c99a0ef9dc9c3803d4aa1b74ac3a9b6dbf14bc Mon Sep 17 00:00:00 2001
From: Benjamin Mako Hill <mako@atdot.cc>
Date: Sat, 15 Aug 2026 11:28:31 +0900
Subject: [PATCH] Rewrite the port's README around using the template

Adds a table mapping beamer constructs to their equivalents here, which
is what someone arriving with a deck needs.

Cuts the parts that recorded what the port turned up rather than how to
use the result: the known-gaps section, the description of how the notes
page is laid out, and the asides about which upstream issues are open.
Those now live in the issues filed against ltx-talk.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 slides_template/README.ltx-talk.md | 56 +++++++++++++-----------------
 1 file changed, 25 insertions(+), 31 deletions(-)

diff --git a/slides_template/README.ltx-talk.md b/slides_template/README.ltx-talk.md
index 532f94d..11fc10f 100644
--- a/slides_template/README.ltx-talk.md
+++ b/slides_template/README.ltx-talk.md
@@ -25,24 +25,35 @@ make notes       # double-width slide + notes pages for presenting
 make pdfpc       # build the notes PDF and open it in pdfpc
 ```
 
-The notes are a kludge. They exist to be read while talking and not shared.
-Only the slides build is expected to validate with tools like
-[veraPDF](https://verapdf.org/).
+Share the slides build, not the notes build: only the slides are tagged and
+expected to validate with tools like [veraPDF](https://verapdf.org/).
+
+## Migrating from beamer
+
+| beamer | here |
+|---|---|
+| `\begin{frame}{Title}` | `\frametitle{Title}` inside the frame |
+| `\begin{frame}[standout]{}` | `\standout{...}` |
+| `\sectionpage` from the theme | `\section{...}` then `\sectionpage` |
+| `\subsectionpage` | `\subsection{...}` then `\subsectionpage` |
+| `\note{...}`, `\note[item]{...}` | same, after `\usepackage{talk-notes}` |
+| `\appendix` | same |
+| `\alert{...}`, `\item<2->`, `\pause` | same |
+| `\only<1>{...}` | avoid; use `\pause` or `\begin{itemize}[<+->]` |
+
+Use `\frametitle`, not the braced argument: by default the class treats
+`\begin{frame}{Title}` as body text, so the title is not tagged as a heading.
+Give every `\includegraphics` an `alt={...}` description, and declare table
+header rows with `\tagpdfsetup{table/header-rows={1}}` before the tabular.
 
 ## Speaker notes
 
-ltx-talk has no `\note` command. Its README and website list speaker notes
-among what the class is for, but the feature is unwritten (see
+ltx-talk has no `\note` command (see
 [issue #156](https://github.com/josephwright/ltx-talk/issues/156)).
-
-`talk-notes.sty` defines `\note` so that it records its text to a side file and
-contributes nothing to the slides. `mknotes` reads that file afterwards and
-builds the presenter PDF.
-
-The assembled page puts the slide on the left and, on the right, a grey band
-carrying the section and position in the talk, a thumbnail of the current
-slide flush into the corner, and the notes below. Previous and next slides are
-left to the viewer: [dspdfviewer](https://github.com/dannyedel/dspdfviewer),
+`talk-notes.sty` defines one that records its text to a side file and
+contributes nothing to the slides; `mknotes` reads that file afterwards and
+builds the presenter PDF. Present it with
+[dspdfviewer](https://github.com/dannyedel/dspdfviewer),
 [pdfpc](https://pdfpc.github.io/), or the web viewers
 [Beamer Viewer](https://beamerviewer.euxane.eu/) and
 [backstage](https://bckstg.xyz/).
@@ -84,20 +95,3 @@ deck. `--preamble FILE` names a different fragment.
 `trantor.sty` is [Marco Pompili's](https://github.com/mrc-pop)
 [Metropolis-like theme](https://github.com/mrc-pop/trantor) for
 ltx-talk.
-
-## Known gaps
-
-Frame titles must be given as `\frametitle{...}` inside the frame, not as the
-argument to `\begin{frame}{...}`. Only the command form is tagged.
-
-ltx-talk tags frame titles at H4, well below sections, and its manual calls the
-relationship between frame titles and sectioning "still very much open".
-
-[Issue #33](https://github.com/josephwright/ltx-talk/issues/33): `\only<1>` and
-`\only<2>` produce output that fails validation. The `\pause` and `<+->` forms
-used here are unaffected.
-
-ltx-talk is version 0.5.x and warns that almost all interfaces may change.
-`talk-notes.sty` reads two internals, `\g__talk_frame_int` and
-`\g__talk_slide_int` — the first thing to check if a release breaks the notes
-build.