222 lines
6.6 KiB
Markdown
222 lines
6.6 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, 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
|
|
```
|
|
|
|
|
|
## Dependencies
|
|
|
|
On Debian or Ubuntu, install the following packages:
|
|
|
|
* latexmk
|
|
* texlive-luatex
|
|
* texlive-latex-recommended
|
|
* texlive-fonts-extra
|
|
* texlive-fonts-recommended
|
|
* texlive-bibtex-extra
|
|
|
|
```
|
|
apt install latexmk texlive-luatex texlive-latex-recommended \
|
|
texlive-fonts-extra texlive-fonts-recommended \
|
|
texlive-bibtex-extra
|
|
```
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
The paper and memo templates were originally built on the memoir
|
|
class, which is incompatible with the LaTeX tagged-PDF code. They now
|
|
use the standard article class with custom styling (`cdsc-paper.sty`
|
|
and `cdsc-memo.sty`) to keep their previous look while supporting full
|
|
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:
|
|
|
|
* Use `\section` and `\subsection` for headings rather than setting type
|
|
in bold by hand. Screen reader users navigate by the heading tree.
|
|
|
|
* 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 three 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
|
|
```
|
|
|
|
### 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)
|
|
* `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)
|
|
|
|
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`
|
|
|
|
|
|
## 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.
|
|
|
|
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
|
|
```
|
|
|
|
Alternatively, source `cdsc_tex_aliases.sh` (see above) to keep using the
|
|
old names without changing your workflow.
|