collective/cdsc_tex
20
0
Fork 0
Code Activity

convert README to markdown

Browse Source 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Benjamin Mako Hill
2026-08-15 10:24:24 +09:00
parent f7e16a221c
commit aaa67b6d54
2 changed files with 221 additions and 214 deletions
Download Patch File Download Diff File Expand all files Collapse all files

214
README
View File

@@ -1,214 +0,0 @@
================================
=== 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 at:
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
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.

221
README.md Normal file
View 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.