collective/cdsc_tex
20
0
Fork 0
Code Activity

Rewrite the port's README as Markdown

Browse Source 
Converts it and fills in what was missing: install instructions, links to
ltx-talk, trantor, veraPDF and the presenter viewers, the upstream issues
behind the speaker-notes workaround and the overlay tagging bug, and how to
use the notes machinery in another document.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Benjamin Mako Hill
2026-08-14 07:22:15 -07:00
parent 9495928ff5
commit 288d571df2
2 changed files with 103 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
slides_template/README.ltx-talk
View File

@@ -1,125 +0,0 @@
================================
=== ltx-talk port ==============
================================
This branch is the presentation template ported from beamer to the
ltx-talk class. It is experimental and kept apart from master, where the
beamer template is still the one in daily use.
The reason to move is accessibility. Beamer cannot produce a genuinely
tagged PDF: the master template validates as PDF/UA-2 only because
tagpdf marks everything it was not told about as decorative, so a screen
reader gets the frame titles and nothing else. Beamer 3.77 has since made
this worse by refusing \DocumentMetadata outright, which breaks tagging
on TeX Live 2025 entirely.
ltx-talk was written by the LaTeX Project with tagging as a design goal,
and the difference in the output is not subtle. Slides built here carry
real paragraphs, lists as L/LI/Lbl/LBody, sections as headings, formulas
as MathML, and alt text that actually reaches the PDF. veraPDF passes on
the strength of that structure rather than in spite of its absence.
================================
=== Requirements ===============
================================
* TeX Live 2025 or newer (ltx-talk needs LaTeX 2025-11-01 or later)
* LuaLaTeX; XeTeX is not supported
* Python 3 with pypdf, for assembling the notes PDF
* veraPDF, to check conformance
Fonts and figures are the same ones the beamer template used and sit
beside the source. They have to: LuaTeX fails to resolve a
parent-relative Path= for fonts and dies with an unhelpful
empty-filename error.
================================
=== Building ===================
================================
make slides the deck; this is what gets uploaded
make notes double-width slide + notes pages for presenting
make validate check the deck against PDF/UA-2
make pdfpc build the notes PDF and open it in pdfpc
Only the slides build is expected to validate. The notes PDF is
assembled by hand from two PDFs, which destroys the tag tree, and that is
fine: it exists to be read while talking and is never shared.
================================
=== Speaker notes ==============
================================
ltx-talk has no \note command. Its README and website describe speaker
notes as part of what the class is for, but the feature has not been
written: the request is open upstream as issue #156, where the maintainer
has said notes are wanted but that the interface needs thought first. As
of v0.5.3 nothing has landed.
Notes here are therefore captured rather than typeset. talk-notes.sty
defines \note so that it contributes nothing to the slides and instead
records its text to a side file, and mknotes reads that file afterwards
to build the presenter PDF.
The awkward part is that a frame is not a page. Overlays expand one frame
into several slides, and how many is not knowable from the source. So
talk-notes.sty writes a record for every page from the shipout hook,
which is the first moment at which the frame and slide identity of a page
is settled:
PAGE 3|FRAME 3|SLIDE 1
PAGE 4|FRAME 3|SLIDE 2
PAGE 5|FRAME 3|SLIDE 3
Notes take the same overlay specifications as everything else, so
\note<1>{...} appears only beside the first slide of its frame and
\note<3->{...} only from the third on. A note without a specification
runs alongside the whole frame.
The assembled page puts the slide on the left and, on the right, a grey
band carrying the section and the 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 dspdfviewer and pdfpc, which show them
already.
================================
=== Theme ======================
================================
trantor.sty is Marco Pompili's Metropolis-like theme for ltx-talk,
vendored here under its MIT license (see LICENSE.trantor) and modified in
two places: font selection has been moved out to the document, since this
template ships OpenSans and RobotoMono, and the Euler maths font it
loaded by default is not packaged in Debian's TeX Live.
Upstream: https://github.com/mrc-pop/trantor
================================
=== 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; the
argument form produces a frame with no heading at all, silently. This
looks like an upstream oversight rather than a decision, so it may change.
ltx-talk tags frame titles at H4, deliberately well below sections and
subsections, and the manual describes the relationship between frame
titles and sectioning as "still very much open". That default is left
alone here. It can be changed with
\tagpdfsetup{role/new-tag = frametitle/H1}
but H1 would put frame titles at the same level as the section headings
that contain them, so it is worth deciding what an accessibility checker
should see before reaching for it.
Overlay tagging has an open upstream bug, issue #33, where \only<1> and
\only<2> produce output that fails validation. The \pause and <+-> forms
used here are the well-supported case.
ltx-talk is version 0.5.x and warns that almost all interfaces may still
change. talk-notes.sty reads two of its private internals,
\g__talk_frame_int and \g__talk_slide_int, which is the price of getting
an exact page mapping and the first thing to check if a future release
breaks the notes build.

103
slides_template/README.ltx-talk.md Normal file
View File

@@ -0,0 +1,103 @@
# ltx-talk port
This branch is the presentation template ported from beamer to the
[ltx-talk](https://github.com/josephwright/ltx-talk) class. ltx-talk was
written with tagging as a design goal.
## Requirements
* LuaLaTeX
* TeX Live 2025 or newer (ltx-talk needs LaTeX 2025-11-01 or later);
`texlive-latex-recommended` ships the class
* `python3-pypdf`, for assembling the notes PDF
You can install all three on Debian with:
```
apt install texlive-latex-recommended python3-pypdf
```
## Building
```
make slides # the deck; this is what gets uploaded
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/).
## 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
[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),
[pdfpc](https://pdfpc.github.io/), or the web viewers
[Beamer Viewer](https://beamerviewer.euxane.eu/) and
[backstage](https://bckstg.xyz/).
### Installing speaker notes
To use speaker notes in another ltx-talk document, copy two files out of this
repository:
- `mknotes`
- `talk-notes.sty`
Load the package in the preamble:
```latex
\usepackage{talk-notes}
```
Write notes with `\note{...}`, or `\note<2->{...}` to bind one to particular
slides of a frame. As in beamer, plain notes run together as text, each
starting a new paragraph, and `\note[item]{...}` adds an entry to a numbered
list printed after them.
Build the deck, then assemble the presenter PDF:
```
./mknotes example
```
That reads `example.pdf` and `example.notes` and writes `example-notes.pdf`,
the double-width version you present from. The slides in `example.pdf` are
untouched.
If `fonts.tex` is present it is used for the notes pages, so they match the
deck. `--preamble FILE` names a different fragment.
## Theme
`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.