convert README to markdown
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
214
README
214
README
@@ -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
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