diff --git a/README.md b/README.md index 3c68b03..94d7ed8 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,8 @@ Copyright (c) 2009-2026 Benjamin Mako Hill / This repository contains LaTeX configuration files and templates used to -format papers, memos, letters, and posters. All files are released under -the GNU GPL version 3 or later. +format papers, memos, letters, talks, and posters. All files are released +under the GNU GPL version 3 or later. The latest version can be found [in git](https://gitea.communitydata.science/collective/cdsc_tex). @@ -29,6 +29,17 @@ git send-email *.patch ``` +## Templates + +Each has its own README with build instructions and details. + +* [paper_template](paper_template/README.md) — a paper, in `article` +* [memo_template](memo_template/README.md) — a short memo +* [letter_template](letter_template/README.md) — a letter +* [slides_template](slides_template/README.md) — presentation slides, in ltx-talk +* [poster_template](poster_template/README.md) — a conference poster, in beamer + + ## Dependencies On Debian or Ubuntu, install the following packages: @@ -39,30 +50,32 @@ On Debian or Ubuntu, install the following packages: * texlive-fonts-extra * texlive-fonts-recommended * texlive-bibtex-extra +* python3-pypdf (slides template only, for the speaker-notes PDF) ``` apt install latexmk texlive-luatex texlive-latex-recommended \ texlive-fonts-extra texlive-fonts-recommended \ - texlive-bibtex-extra + texlive-bibtex-extra python3-pypdf ``` On other systems, installing a full TeX Live distribution should provide -everything needed. - -All four templates build with LuaLaTeX (via `latexmk -lualatex`). The text -fonts are Libertinus Serif and TeX Gyre Heros, both provided by -texlive-fonts-extra. +everything needed. All templates build with LuaLaTeX (via `latexmk +-lualatex`) and take their fonts from TeX Live, so nothing has to be +installed as a system font. The tagging code requires TeX Live 2025 or later. On Overleaf, set the version under Menu > Settings > TeX Live version. Debian Trixie ships TeX Live 2024; sid (unstable) has TeX Live 2026, which also works and -installs without pulling in much else. +installs without pulling in much else. The slides template needs a newer +LaTeX than the others; see its +[README](slides_template/README.md#requirements). ## Accessibility -The paper, memo, and letter templates produce tagged PDFs that declare -PDF/UA-2 (ISO 14289-2). The poster template does not; see below. +The paper, memo, letter, and slides templates produce tagged PDFs that +declare PDF/UA-2 (ISO 14289-2). The [poster +template](poster_template/README.md) does not, because beamer cannot. Two keys in the `\DocumentMetadata` block at the top of each template do this, and both are needed: `tagging=on` loads the kernel code that puts @@ -78,10 +91,11 @@ tagging. ### Writing an accessible document Tagging gets you the structure; the content is still up to the author. -The paper template carries a worked example of each of these: +The paper and slides templates carry a worked example of each of these: * Use `\section` and `\subsection` for headings rather than setting type - in bold by hand. Screen reader users navigate by the heading tree. + in bold by hand. Screen reader users navigate by the heading tree. In + the slides template, give frame titles as `\frametitle`. * Give every figure an `alt=` description on `\includegraphics`, saying what the reader is meant to take from it. A decorative image takes @@ -113,7 +127,7 @@ verapdf -f ua2 text.pdf ``` It prints PASS or FAIL, and `--format text` lists the failing clauses. -All three tagged templates pass as shipped, so a FAIL points at the +All four tagged templates pass as shipped, so a FAIL points at the document rather than the template. Note that a PASS is necessary but not sufficient. A document whose @@ -127,21 +141,11 @@ python3 -c "import pikepdf,sys; d=pikepdf.open(sys.argv[1]); \ print(d.Root.get('/StructTreeRoot') and 'tagged' or 'UNTAGGED')" file.pdf ``` -### Posters - -The poster template is not accessible and makes no accessibility -claim. The beamer class rejects `\DocumentMetadata` outright, and the -LaTeX Tagging Project lists beamer and beamerposter as no-support, -meaning incompatible and not expected to change. When a poster needs -an accessible version, build a companion document from the paper or -memo template. - - ## Branches This repository has two main branches: -* `master` — Standard LaTeX templates (paper, memo, letter, poster) +* `master` — Standard LaTeX templates (paper, memo, letter, slides, poster) * `knitr` — Knitr/R template for reproducible research documents @@ -162,6 +166,7 @@ Available types: * `memo` — LaTeX memo template (master branch) * `knitr` — Knitr/R paper template (knitr branch) * `letter` — LaTeX letter template (master branch) +* `slides` — ltx-talk presentation template (master branch) Example: @@ -199,13 +204,14 @@ This defines the following aliases (only if `new_tex_document` is in PATH): * `new_tex_memo` → `new_tex_document memo` * `new_knitr_document` → `new_tex_document knitr` * `new_tex_letter` → `new_tex_document letter` +* `new_beamer_presentation` → `new_tex_document slides` ## Migration -The individual scripts `new_knitr_document` and `new_tex_letter` have -been consolidated into `new_tex_document`. The old scripts remain in -the repository but are superseded. +The individual scripts `new_knitr_document`, `new_tex_letter`, and +`new_beamer_presentation` have been consolidated into +`new_tex_document`. To migrate, replace calls to the old scripts with `new_tex_document`: @@ -215,7 +221,14 @@ New: new_tex_document knitr mydir Old: new_tex_letter mydir New: new_tex_document letter mydir + +Old: new_beamer_presentation mydir +New: new_tex_document slides mydir ``` +The presentation template came from +[beamer-mako](https://gitlab.com/makoshark/beamer-mako), which is +superseded by `slides_template` here. + Alternatively, source `cdsc_tex_aliases.sh` (see above) to keep using the old names without changing your workflow. diff --git a/letter_template/README.md b/letter_template/README.md new file mode 100644 index 0000000..018e8c1 --- /dev/null +++ b/letter_template/README.md @@ -0,0 +1,16 @@ +# Letter Template + +A letter in the standard `letter` class. See the +[root README](../README.md) for tagging and accessibility. + +``` +make # build the PDF +make clean +``` + +Fonts are Libertinus Serif and TeX Gyre Heros, from `texlive-fonts-extra`; +`text.tex` has a commented alternative for Adobe Garamond Premier Pro. + +Replace the `\address`, `\signature`, `\location`, and `\telephone` blocks in +`text.tex`, which carry Mako's details as an example. For letterhead, see +[uw_tex_letterhead](https://gitea.communitydata.science/mako/uw_tex_letterhead). diff --git a/memo_template/README.md b/memo_template/README.md new file mode 100644 index 0000000..d940b88 --- /dev/null +++ b/memo_template/README.md @@ -0,0 +1,18 @@ +# Memo Template + +A short memo in the standard `article` class, styled by `cdsc-memo.sty`. The +title and author sit on one line above the text rather than in a title block. +See the [root README](../README.md) for tagging and accessibility. + +``` +make # build the PDF +make vc # write a vc file with the current git revision +make clean +``` + +Fonts are Libertinus Serif and TeX Gyre Heros, from `texlive-fonts-extra`; +`text.tex` has a commented alternative for Adobe Garamond Premier Pro. +Bibliography is biblatex with biber, APA style, reading `refs.bib`. + +Uncomment the `\input{vc}` and `\pagestyle{cdsc-page-memo-git}` lines in +`text.tex` to print the revision at the foot of each page. diff --git a/paper_template/README.md b/paper_template/README.md new file mode 100644 index 0000000..6e8601e --- /dev/null +++ b/paper_template/README.md @@ -0,0 +1,34 @@ +# Paper Template + +A paper in the standard `article` class, styled by `cdsc-paper.sty`. See the +[root README](../README.md) for tagging and accessibility. + +``` +make # build the PDF +make vc # write a vc file with the current git revision +make clean +``` + +`text.tex` carries worked examples of alt text on a figure and a tagged table +header row. Delete that section when you start writing. + +## Fonts + +Libertinus Serif and TeX Gyre Heros, both from `texlive-fonts-extra`. + +Mako prefers [Adobe Garamond Premier +Pro](https://fonts.adobe.com/fonts/garamond-premier-pro), which is commercial +and not redistributable. If you have it installed, swap the `\setmainfont` line +in `text.tex`. CDSC members can ask Mako for the files. + +## Bibliography + +biblatex with biber, APA style, reading `refs.bib`. `\citepos` and `\citespos` +give possessive citations. + +## Version footer + +`make vc` writes a `vc` file from the current git revision. Uncomment the +`\input{vc}` and `\pagestyle{cdsc-page-git}` lines in `text.tex` to print it at +the foot of each page. On Overleaf, use `\pagestyle{cdsc-page-overleaf}` +instead, which stamps the build time. diff --git a/poster_template/README.md b/poster_template/README.md new file mode 100644 index 0000000..1096b1e --- /dev/null +++ b/poster_template/README.md @@ -0,0 +1,20 @@ +# Poster Template + +A conference poster on beamer with beamerposter, styled by the Torino theme +and `beamercolorthememako.sty`. The source file is `main.tex`. + +``` +latexmk -f -lualatex main.tex +``` + +## Not accessible + +This is the one template that produces an untagged PDF, and it makes no +accessibility claim. The beamer class rejects `\DocumentMetadata`, and the +LaTeX Tagging Project lists beamer and beamerposter as +[no-support](https://latex3.github.io/tagging-project/tagging-status/), meaning +incompatible and not expected to change. + +When a poster needs an accessible version, build a companion document from the +[paper](../paper_template/README.md) or [memo](../memo_template/README.md) +template. diff --git a/slides_template/README b/slides_template/README deleted file mode 100644 index 894d556..0000000 --- a/slides_template/README +++ /dev/null @@ -1,109 +0,0 @@ -================================ -=== Mako's Beamer Templates ==== -================================ - -Copyright (c) 2013-2026 Benjamin Mako Hill / - -This repository contains a Beamer presentation template I use for my -own presentations. Others in the CDSC lab also use it for lab -presentations. It is released under the GNU GPL version 3 or later. - -The latest version can be found on GitLab at: -https://gitlab.com/makoshark/beamer-mako - -You can clone the repository with: - - git clone https://gitlab.com/makoshark/beamer-mako.git - -Bug reports, comments, questions, and patches can be directed to: - - Benjamin Mako Hill [work] - Benjamin Mako Hill [personal] - -Patches can be submitted as merge requests via GitLab, or by cloning -the repository and sending patches by email: - - git format-patch origin/master - git send-email *.patch - -================================ -=== Dependencies =============== -================================ - -On Debian or Ubuntu, install the following packages: - - * latexmk - * texlive-luatex - * texlive-latex-recommended - * texlive-latex-extra - - apt install latexmk texlive-luatex texlive-latex-recommended \ - texlive-latex-extra - -On other systems, installing a full TeX Live distribution should provide -everything needed. - -The template uses the Metropolis Beamer theme, bundled in the template/ -directory along with the OpenSans and RobotoMono fonts it requires. - -================================ -=== Accessibility ============== -================================ - -Slides are built as tagged PDFs that validate against PDF/UA-2 -(ISO 14289-2), which is what upload targets like Canvas check for. Check -a file with veraPDF (https://verapdf.org/): - - verapdf -f ua2 my-talk.pdf - -The pieces that do this work are: - - * \DocumentMetadata declares PDF/UA-2, PDF 2.0, and the document - language. The language tag tells a screen reader how to pronounce - the text. - * tagpdf with activate-all turns tagging on. - * The frametitle template is patched to emit H1 tags, since Beamer - does not treat frame titles as headings on its own. - * unicode-math replaces the Computer Modern math fonts, which carry no - Unicode mappings and leave formulas unreadable to assistive software. - * \hypersetup{pdfdisplaydoctitle=true} makes viewers announce the - document title instead of the filename. - * The tikz overlays behind \credit, \marktopleft, and \markbottomright - are marked as artifacts so they stay out of the reading order. - -Use a slides-only build (make slides) for anything shared. Builds that -include speaker notes do not validate, because Beamer repeats the frame -title and section headings on the notes half of each page. - -Validating is not the same as being accessible, and this template does -the first better than the second. Frame titles and links are tagged; -body text, lists, and figures are not, so a screen reader gets the -outline of a talk rather than its contents. Closing that gap needs -automatic tagging from the LaTeX kernel (\DocumentMetadata{tagging=on}), -which requires TeX Live 2025 or later and is waiting on Overleaf to -support it, and Beamer support in the LaTeX Tagging Project, which does -not exist yet. The alt={...} arguments in the template are written for -that day; they are dropped by the current toolchain. - -================================ -=== Scripts ==================== -================================ - -new_beamer_presentation ------------------------ -Creates a new presentation directory from the template. Takes a -destination directory as its argument: - - new_beamer_presentation - -Example: - - new_beamer_presentation my-talk - -This creates my-talk/ populated with the template files, with the main -source file renamed to my-talk.tex. Fonts are symlinked from the source -repository rather than copied, so the repository must remain in place. - -Symlink the script into your PATH with: - - ln -s ~/tex/beamer-mako/new_beamer_presentation ~/bin/ diff --git a/slides_template/README.ltx-talk.md b/slides_template/README.ltx-talk.md deleted file mode 100644 index 11fc10f..0000000 --- a/slides_template/README.ltx-talk.md +++ /dev/null @@ -1,97 +0,0 @@ -# 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 -``` - -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 (see -[issue #156](https://github.com/josephwright/ltx-talk/issues/156)). -`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/). - -### 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. diff --git a/slides_template/README.md b/slides_template/README.md new file mode 100644 index 0000000..fd983e1 --- /dev/null +++ b/slides_template/README.md @@ -0,0 +1,80 @@ +# Slides Template + +Presentation slides on the [ltx-talk](https://github.com/josephwright/ltx-talk) +class, which was written with tagging as a design goal. See the +[root README](../README.md) for what tagging buys and how to check it. + +## Requirements + +* LuaLaTeX +* ltx-talk, from `texlive-latex-recommended`. It needs LaTeX 2025-11-01 or + later, which is newer than TeX Live 2025 as first released; Overleaf's + TeX Live 2025 may predate it, so compile there before relying on it. +* `python3-pypdf`, for assembling the notes PDF + +``` +apt install latexmk texlive-luatex texlive-latex-recommended \ + texlive-fonts-extra python3-pypdf +``` + +Slides are set in Open Sans and Roboto Mono, both from `texlive-fonts-extra`. + +## Building + +``` +make slides # the deck +make notes # double-width slide and notes pages, for presenting +make pdfpc # build the notes PDF and open it in pdfpc +``` + +Share the slides build. The notes build is not tagged and exists to be looked +at while talking. + +## Writing slides + +Give frame titles as `\frametitle`, not as the braced argument to `frame`. The +class treats `\begin{frame}{Title}` as body text, so a title given that way is +not tagged as a heading. + +Coming 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}[<+->]` | + +## Speaker notes + +ltx-talk has no `\note` command (see +[issue #156](https://github.com/josephwright/ltx-talk/issues/156)). +`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. + +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. + +`make notes` writes `-notes.pdf`, the double-width version you present +from. Show 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/). + +To use notes in another ltx-talk document, copy `mknotes` and `talk-notes.sty` +across and load the package. `mknotes` picks up `fonts.tex` when it is present, +so the notes 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, +vendored with a licence header added and the font block left to the document. +Re-vendor from the fork rather than editing this copy.