diff --git a/slides_template/README.ltx-talk b/slides_template/README.ltx-talk deleted file mode 100644 index 203afa4..0000000 --- a/slides_template/README.ltx-talk +++ /dev/null @@ -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. diff --git a/slides_template/README.ltx-talk.md b/slides_template/README.ltx-talk.md new file mode 100644 index 0000000..532f94d --- /dev/null +++ b/slides_template/README.ltx-talk.md @@ -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.