================================ === 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 paper, memo, and letter templates need TeX Live 2025 or later. The tagging code they rely on is not in TeX Live 2024, where the build stops with "the key 'document/metadata/tagging' is unknown". Debian trixie ships TeX Live 2024, so a trixie machine needs a newer TeX Live from elsewhere in the archive. On Overleaf, choose the TeX Live version under Menu > Settings > TeX Live version; 2025 or later is required and is not always the default for an older project. ================================ === 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. Tagging is switched on by the tagging=on key in the \DocumentMetadata block at the top of each template. That key is what does the work: it loads the kernel code that puts headings, paragraphs, lists, tables, and figures into the PDF's structure tree, which is what a screen reader walks. The neighbouring pdfstandard=ua-2 key only writes the conformance claim into the file's metadata. Setting the standard without setting tagging=on yields a PDF that announces itself as accessible and contains nothing for assistive software to read, so keep the two together. 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. Three things matter most, and the paper template carries a worked example of each: * Use \section and \subsection for headings rather than setting type in bold by hand. Screen reader users navigate by the heading tree, and hand-formatted text is invisible to it. * 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, keeping it out of the reading order. * Mark header rows on data tables with \tagpdfsetup{table/header-rows ={1}} so their cells become TH rather than TD. Without it a table reads as an undifferentiated grid of values. Customizing the styles ---------------------- Some common packages defeat tagging, and the failure is usually silent: the document compiles without complaint and the tags are simply missing. Before adding a package, check its status against the LaTeX Tagging Project's list: https://latex3.github.io/tagging-project/tagging-status/ titlesec and titling are the two to know about here, because they are the obvious tools for the job cdsc-paper.sty and cdsc-memo.sty do. titlesec replaces the \@startsection hook that the tagging code uses to emit heading tags, so loading it produces a PDF with no headings in the structure tree and no error to say so. Both style files therefore build their headings and title blocks from the article class's own \@startsection and \@maketitle hooks. Verifying --------- Check a built PDF against the standard with veraPDF: verapdf -f ua2 text.pdf It prints PASS or FAIL for the file, and --format text will list the clauses that failed. All four of the tagged templates pass as shipped, so a FAIL means something in the document needs attention rather than something in the template. Run it. A document that declares PDF/UA-2 and does not meet it is worse than one that makes no claim, because the claim is what a reader relying on assistive software will trust. The declaration costs one line and validating it is the only thing that makes the line true. veraPDF is not packaged in Debian; download it from https://verapdf.org/ and put it on your PATH. For a quicker look at whether a PDF carries any structure at all, without checking conformance: 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.