# 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; unmaintained and not accessible


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