Benjamin Mako Hill
56f0c1b022
It described what the paper and memo templates used to be rather than what they are. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
229 lines
7.0 KiB
Markdown
229 lines
7.0 KiB
Markdown
# CDSC LaTeX Templates
|
|
|
|
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, 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).
|
|
|
|
You can check out the latest version with:
|
|
|
|
```
|
|
git clone https://gitea.communitydata.science/collective/cdsc_tex.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]
|
|
|
|
To submit a patch, clone the repository, make your changes, and use
|
|
`git format-patch` to generate patch files to send by email:
|
|
|
|
```
|
|
git format-patch origin/master
|
|
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:
|
|
|
|
* latexmk
|
|
* texlive-luatex
|
|
* texlive-latex-recommended
|
|
* 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 python3-pypdf
|
|
```
|
|
|
|
On other systems, installing a full TeX Live distribution should provide
|
|
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. The slides template needs a newer
|
|
LaTeX than the others; see its
|
|
[README](slides_template/README.md#requirements).
|
|
|
|
|
|
## Accessibility
|
|
|
|
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
|
|
headings, paragraphs, lists, tables, and figures into the PDF's
|
|
structure tree, and `pdfstandard=ua-2` writes the conformance claim.
|
|
|
|
### Writing an accessible document
|
|
|
|
Tagging gets you the structure; the content is still up to the author.
|
|
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
|
|
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
|
|
`\includegraphics[artifact]{...}` instead.
|
|
|
|
* Mark header rows on data tables with
|
|
`\tagpdfsetup{table/header-rows={1}}` so their cells become TH rather
|
|
than TD.
|
|
|
|
### Customizing the styles
|
|
|
|
Some common packages defeat tagging, and the failure is silent: the
|
|
document compiles without complaint and the tags are simply missing.
|
|
Before adding a package, check it against the LaTeX Tagging Project's
|
|
[status list](https://latex3.github.io/tagging-project/tagging-status/).
|
|
|
|
`titlesec` and `titling` are the two to know about, because they are the
|
|
obvious tools for the job `cdsc-paper.sty` and `cdsc-memo.sty` do.
|
|
`titlesec` replaces the `\@startsection` hook the tagging code uses to
|
|
emit heading tags, so loading it produces a PDF with no headings in
|
|
the structure tree.
|
|
|
|
### Verifying
|
|
|
|
You can check a built PDF with [veraPDF](https://verapdf.org/):
|
|
|
|
```
|
|
verapdf -f ua2 text.pdf
|
|
```
|
|
|
|
It prints PASS or FAIL, and `--format text` lists the failing clauses.
|
|
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
|
|
body text is all marked as artifact passes too, because the standard
|
|
only requires that content which is not real be an artifact.
|
|
|
|
You can confirm there is something in the structure tree as well:
|
|
|
|
```
|
|
python3 -c "import pikepdf,sys; d=pikepdf.open(sys.argv[1]); \
|
|
print(d.Root.get('/StructTreeRoot') and 'tagged' or 'UNTAGGED')" file.pdf
|
|
```
|
|
|
|
## Branches
|
|
|
|
This repository has two main branches:
|
|
|
|
* `master` — Standard LaTeX templates (paper, memo, letter, slides, poster)
|
|
* `knitr` — Knitr/R template for reproducible research documents
|
|
|
|
|
|
## Scripts
|
|
|
|
### new_tex_document
|
|
|
|
Creates a new document directory from a template. Takes a document type
|
|
and destination directory as arguments:
|
|
|
|
```
|
|
new_tex_document <type> <directory>
|
|
```
|
|
|
|
Available types:
|
|
|
|
* `paper` — LaTeX paper template (master branch)
|
|
* `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:
|
|
|
|
```
|
|
new_tex_document paper my-new-paper
|
|
```
|
|
|
|
This creates `my-new-paper/` populated with the template files, with the
|
|
main source file renamed to `my-new-paper.tex` (or `.Rtex` for knitr).
|
|
|
|
### rename_tex_to_dirname
|
|
|
|
Renames the single .tex file in the current directory to match the
|
|
directory name. Useful for cleaning up a template that was set up
|
|
manually:
|
|
|
|
```
|
|
cd my-paper && rename_tex_to_dirname
|
|
```
|
|
|
|
|
|
## Shell Aliases
|
|
|
|
The file `cdsc_tex_aliases.sh` provides aliases for the old individual
|
|
script names, for convenience or backwards compatibility. Add the
|
|
following to your `.bashrc` or `.zshrc`:
|
|
|
|
```
|
|
[[ -f ~/tex/cdsc_tex/cdsc_tex_aliases.sh ]] && \
|
|
source ~/tex/cdsc_tex/cdsc_tex_aliases.sh
|
|
```
|
|
|
|
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`, `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`:
|
|
|
|
```
|
|
Old: new_knitr_document mydir
|
|
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.
|