diff --git a/README b/README deleted file mode 100644 index 319b2a5..0000000 --- a/README +++ /dev/null @@ -1,214 +0,0 @@ -================================ -=== CDSC LaTeX Templates ======= -================================ - -Copyright (c) 2009-2026 Benjamin Mako Hill / - -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 [work] - Benjamin Mako Hill [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 - -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..3c68b03 --- /dev/null +++ b/README.md @@ -0,0 +1,221 @@ +# CDSC LaTeX Templates + +Copyright (c) 2009-2026 Benjamin Mako Hill / + +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 [work] +* Benjamin Mako Hill [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 +``` + +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.