collective/cdsc_tex
20
0
Fork 0
Code Activity

Give each template its own README

Browse Source 
The root README keeps what is shared — dependencies, accessibility, the
scripts — and links to a per-template README for how to build and what is
in it. The Posters section moves to poster_template/README.md with a
pointer left behind, since it is that template's caveat.

slides_template/README.md replaces the two READMEs that came with
beamer-mako.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Benjamin Mako Hill
2026-08-19 16:01:15 +09:00
parent 5c9f965fc7
commit 591d089fa0
8 changed files with 209 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
README.md
View File

@@ -3,8 +3,8 @@
Copyright (c) 2009-2026 Benjamin Mako Hill <mako@atdot.cc> / <makohill@uw.edu>
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.

16
letter_template/README.md Normal file
View File

@@ -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).

18
memo_template/README.md Normal file
View File

@@ -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.

34
paper_template/README.md Normal file
View File

@@ -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.

20
poster_template/README.md Normal file
View File

@@ -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.

109
slides_template/README
View File

@@ -1,109 +0,0 @@
================================
=== Mako's Beamer Templates ====
================================
Copyright (c) 2013-2026 Benjamin Mako Hill <mako@atdot.cc> / <makohill@uw.edu>
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 <makohill@uw.edu> [work]
Benjamin Mako Hill <mako@atdot.cc> [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 <directory>
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/

97
slides_template/README.ltx-talk.md
View File

@@ -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.

80
slides_template/README.md Normal file
View File

@@ -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 `<jobname>-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.