================================
=== 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, assignments, and letters. 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 EB Garamond (provided by texlive-fonts-extra) and TeX Gyre
Heros.

================================
=== Accessibility ==============
================================

The letter and poster templates produce PDF/UA-2 compliant tagged PDFs
via the LaTeX tagging project (\DocumentMetadata + tagpdf). You can
verify compliance with verapdf: https://verapdf.org/

The paper and assignment templates are based on the memoir class, which
is not yet compatible with the LaTeX tagged-PDF code. They load the
pdfmanagement-testphase layer for PDF metadata only. When memoir gains
tagging support upstream, the commented-out \DocumentMetadata and tagpdf
lines in each template can be re-enabled. See:

  https://github.com/latex3/tagging-project/issues/910

================================
=== Branches ===================
================================

This repository has two main branches:

  master  Standard LaTeX templates (paper, assignment, letter)
  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)
  assignment  LaTeX assignment 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_assignment   →  new_tex_document assignment
  new_knitr_document   →  new_tex_document knitr
  new_tex_letter       →  new_tex_document letter

================================
=== Migration ==================
================================

The individual scripts new_knitr_document, new_tex_assignment, 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_assignment mydir
  New: new_tex_document assignment 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.