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.