convert README to markdown
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
221
README.md
Normal file
221
README.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user