Merge branch 'master' into knitr

Replace the individual new_knitr_document, new_tex_assignment, and
new_tex_letter scripts with a single new_tex_document script that takes
a document type as its first argument. Fix bugs present in all scripts:
unquoted variables, TMPDIR name collision, missing existence checks, and
mktemp running unconditionally. Add cdsc_tex_aliases.sh for backwards
compatibility with old script names. Add rename_tex_to_dirname script
(moved from ~/bin). Update README and wiki page to reflect new setup.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README

@@ -1,50 +1,130 @@
 ================================
-=== LaTeX Custom Scripts ======
+=== CDSC LaTeX Templates =======
 ================================
 
-Copyright (c) 2009-2025 Benjamin Mako Hill <mako@atdot.cc> / <makohill@uw.edu>
+Copyright (c) 2009-2026 Benjamin Mako Hill <mako@atdot.cc> / <makohill@uw.edu>
 
-This repository contains LaTeX configuration files that I use to format
+This repository contains LaTeX configuration files and templates used to
-my papers. They are all released under the GNU GPL version 3 or later.
+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
 
-As scripts and configuration files, I do not "release" these files. You
+You can check out the latest version with:
-can always check out the latest version with Git with the following
-command:
 
   git clone https://gitea.communitydata.science/collective/cdsc_tex.git
 
-Bug reports, comments, questions, and patches can all be directed to:
+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 ===============
 ================================
 
-If you are running Debian or Ubuntu, you will first need to install the
+On Debian or Ubuntu, install the following packages:
-following packages:
 
-  * rubber
+  * latexmk
   * texlive-latex-recommended
   * texlive-fonts-extra
   * texlive-fonts-recommended
-  * texlive-bibtex-extra 
+  * texlive-bibtex-extra
 
-You can do so with the following command:
+  apt install latexmk texlive-latex-recommended \
-
-  apt-get install rubber texlive-latex-recommended \
   texlive-fonts-extra texlive-fonts-recommended \
-  texlive-bibtex-extra 
+  texlive-bibtex-extra
 
-I don't know the details of setting up these LaTeX files to work with on
+On other systems, installing a full TeX Live distribution should provide
-systems other than Debian or Ubuntu but imagine it will involve
+everything needed.
-installing a full TeX Live distribution.
 
-In my templates, I make extensive use of the following Garamond font:
+The templates make extensive use of the URW Garamond font, available from
+CTAN: https://ctan.org/pkg/urw-garamond
 
-  http://www.ctan.org/tex-archive/fonts/urw/garamond/
+================================
+=== 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.

cdsc_tex_aliases.sh

@@ -0,0 +1,9 @@
+# Aliases for cdsc_tex document creation scripts.
+# Source this file from ~/.bashrc or ~/.zshrc:
+#   source ~/tex/cdsc_tex/cdsc_tex_aliases.sh
+
+if command -v new_tex_document > /dev/null 2>&1; then
+    alias new_tex_assignment='new_tex_document assignment'
+    alias new_knitr_document='new_tex_document knitr'
+    alias new_tex_letter='new_tex_document letter'
+fi

new_knitr_document

@@ -1,22 +0,0 @@
-#!/bin/sh
-
-# Helper script to export LaTeX templates for new documents
-# Copyright (c) 2009-2016 Benjamin Mako Hill <mako@atdot.cc>
-# Released under the GPLv3 or later.
-
-CURDIR=$(pwd)
-TMPDIR=$(mktemp -d)
-
-if test $1
-then
-    cd "$HOME/tex/cdsc_tex"
-    git archive --format=tar knitr paper_template|tar x --strip=1 -C "$TMPDIR"
-    cd "$CURDIR"
-
-    # get rid of paper_template subdir
-    mv "$TMPDIR" "$1"
-    cd "$1";
-    mv "text.Rtex" "$1.Rtex"
-else
-    echo "specifiy a directory where the template should go";
-fi

new_tex_assignment

@@ -1,22 +0,0 @@
-#!/bin/sh
-
-# Helper script to export LaTeX templates for new documents
-# Copyright (c) 2009-2018 Benjamin Mako Hill <mako@atdot.cc>
-# Released under the GPLv3 or later.
-
-CURDIR=$(pwd)
-TMPDIR=$(mktemp -d)
-
-if test $1
-then
-    cd "$HOME/tex/cdsc_tex"
-    git archive --format=tar master assignment_template|tar x --strip=1 -C "$TMPDIR"
-    cd "$CURDIR"
-
-    # get rid of paper_template subdir
-    mv "$TMPDIR" "$1"
-    cd "$1";
-    mv "text.tex" "$1.tex"
-else
-    echo "specifiy a directory where the template should go";
-fi

new_tex_document

@@ -1,22 +1,64 @@
 #!/bin/sh
 
-# Helper script to export LaTeX templates for new documents
+# Helper script to export LaTeX/knitr templates for new documents
-# Copyright (c) 2009-2016 Benjamin Mako Hill <mako@atdot.cc>
+# Copyright (c) 2009-2026 Benjamin Mako Hill <mako@atdot.cc>
 # Released under the GPLv3 or later.
 
+set -e
+
 CURDIR=$(pwd)
-TMPDIR=$(mktemp -d)
 
-if test $1
+usage() {
-then
+    echo "Usage: $(basename "$0") <type> <directory>"
-    cd "$HOME/tex/cdsc_tex"
+    echo "Types: paper, assignment, knitr, letter"
-    git archive --format=tar master paper_template|tar x --strip=1 -C "$TMPDIR"
+    exit 1
-    cd "$CURDIR"
+}
 
-    # get rid of paper_template subdir
+[ -n "$1" ] && [ -n "$2" ] || usage
-    mv "$TMPDIR" "$1"
+
-    cd "$1";
+TYPE="$1"
-    mv "text.tex" "$1.tex"
+DEST="$2"
-else
+
-    echo "specifiy a directory where the template should go";
+case "$TYPE" in
+    paper)
+        REPO="$HOME/tex/cdsc_tex"
+        BRANCH="master"
+        TEMPLATE="paper_template"
+        EXT="tex"
+        ;;
+    assignment)
+        REPO="$HOME/tex/cdsc_tex"
+        BRANCH="master"
+        TEMPLATE="assignment_template"
+        EXT="tex"
+        ;;
+    knitr)
+        REPO="$HOME/tex/cdsc_tex"
+        BRANCH="knitr"
+        TEMPLATE="paper_template"
+        EXT="Rtex"
+        ;;
+    letter)
+        REPO="$HOME/tex/cdsc_tex"
+        BRANCH="master"
+        TEMPLATE="letter_template"
+        EXT="tex"
+        ;;
+    *)
+        echo "error: unknown type '$TYPE'"
+        usage
+        ;;
+esac
+
+if [ -e "$DEST" ]; then
+    echo "error: '$DEST' already exists"
+    exit 1
 fi
+
+WORK_DIR=$(mktemp -d)
+cd "$REPO"
+git archive --format=tar "$BRANCH" "$TEMPLATE" | tar x --strip=1 -C "$WORK_DIR"
+cd "$CURDIR"
+mv "$WORK_DIR" "$DEST"
+cd "$DEST"
+mv "text.$EXT" "$(basename "$DEST").$EXT"

new_tex_letter

@@ -1,21 +0,0 @@
-#!/bin/sh
-# Helper script to export LaTeX templates for new letters
-# Copyright (c) 2009-2016 Benjamin Mako Hill <mako@atdot.cc>
-# Released under the GPLv3 or later.
-
-CURDIR=$(pwd)
-TMPDIR=$(mktemp -d)
-
-if test $1
-then
-    cd "$HOME/tex/latex_mako"
-    git archive --format=tar HEAD letter_template|tar x --strip=1 -C "$TMPDIR"
-    cd "$CURDIR"
-
-    # get rid of paper_template subdir
-    mv "$TMPDIR" "$1"
-    cd "$1";
-    mv "text.tex" "$1.tex"
-else
-    echo "specifiy a directory where the template should go";
-fi

rename_tex_to_dirname

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+set -e
+
+TARGET="$(basename "$(pwd)").tex"
+
+if [ -e "$TARGET" ]; then
+    echo "error: '$TARGET' already exists"
+    exit 1
+fi
+
+files=(*.tex)
+if [ "${files[0]}" = "*.tex" ]; then
+    echo "error: no .tex files found"
+    exit 1
+fi
+if [ "${#files[@]}" -gt 1 ]; then
+    echo "error: multiple .tex files found: ${files[*]}"
+    exit 1
+fi
+
+mv "${files[0]}" "$TARGET"

wiki_page.wiki

@@ -0,0 +1,108 @@
+In order to write LaTeX documents, there are two main options. The first is to do everything in Overleaf. The second option, which is explained below in this document under [[#Installing TeX on your computer]], is to install software on your local machine which will compile LaTeX documents.
+
+This document explains how to use our lab-created templates. Using other templates may require other steps.
+
+== Getting/Installing Templates ==
+
+You can find the latest version of the templates [https://gitea.communitydata.science/collective/cdsc_tex here].
+
+To clone the public repository, you can do:
+
+ git clone https://gitea.communitydata.science/collective/cdsc_tex.git
+
+If you can clone them into the directory <code>~/tex/</code> (e.g., by doing <code>mkdir ~/tex; cd ~/tex</code> before running the clone command above) it will make things a bit easier.
+
+This repository includes scripts for quickly creating a new project from a template. Symlink them into your PATH with:
+
+ ln -s ~/tex/cdsc_tex/new_tex_document ~/bin/
+ ln -s ~/tex/cdsc_tex/rename_tex_to_dirname ~/bin/
+
+The main script is <code>new_tex_document</code>, which takes a document type and destination directory:
+
+ new_tex_document <type> <directory>
+
+Available types are <code>paper</code>, <code>assignment</code>, <code>knitr</code>, and <code>letter</code>. For example:
+
+ new_tex_document paper my-new-paper
+ new_tex_document knitr my-knitr-paper
+
+The repository also includes <code>cdsc_tex_aliases.sh</code>, which defines aliases for the old individual script names (<code>new_knitr_document</code>, <code>new_tex_assignment</code>, <code>new_tex_letter</code>) in case you prefer those. Add the following to your <code>.bashrc</code> or <code>.zshrc</code> to load them:
+
+ [[ -f ~/tex/cdsc_tex/cdsc_tex_aliases.sh ]] && source ~/tex/cdsc_tex/cdsc_tex_aliases.sh
+
+== Using the paper templates ==
+
+There are quite a number of useful instructions sprinkled throughout the TeX source file in comments. You should pay particular attention to the comments that begin with:
+
+ % LATEX NOTE:
+
+There are two styles that come with the package with two basic layouts that are defined. To switch between them, you just edit the following line:
+
+ \chapterstyle{cdsc-article}
+
+The first style <code>cdsc-article</code> is great for papers ([https://mako.cc/academic/shaw_hill-laboratories_of_oligarchy-DRAFT.pdf a perhaps dated example]). 
+
+The second style <code>cdsc-memo</code> is more for shorter pieces and memos ([https://mako.cc/academic/bmh-research_statement.pdf a perhaps dated example]). 
+
+If you want to use the style, you might want to consider switching the <code>\chapterstyle</code> line mentioned above <code>cdsc-article</code> to <code>cdsc-memo</code> by editing the following line.
+
+If you want to include git commit IDs and datestamp on each page of the paper, you can uncomment the following lines which will import version control information after running <code>make vc</code> 
+
+ \input{vc}
+ \pagestyle{cdsc-page-git}
+
+One problem is that this can be tricky to get to work on Overleaf. This alternative line will just input a timestamp at the build process:
+
+ \pagestyle{cdsc-page-overleaf}
+
+Either approach can be useful for keeping track of which version of a document somebody has.
+
+The templates themselves use the [https://texdoc.org/serve/memoir/0 LaTeX Memoir Class] (warning that link is a ~1000 page PDF and the documentation).
+
+== Using the Beamer templates ==
+
+The beamer templates are described in [[CommunityData:Beamer]].
+
+== Using the poster template ==
+
+The poster template is in a subdirectory called <code>poster_template</code> within the <code>cdsc_tex</code> repository above. The template is actually just a single Beamer slide. You can simply upload all the files in this directory to Overleaf and/or build them following instructions over on [[CommunityData:Beamer]].
+
+== Sending Patches to the templates ==
+
+If you want to send patches, clone the repository, make your changes, and use <code>git format-patch</code> to generate patch files to email directly to mako at <code>mako@atdot.cc</code>. For example:
+
+ git format-patch origin/master
+ git send-email *.patch
+
+== Installing TeX on your computer ==
+=== Debian/Ubuntu Installation Instructions ===
+
+First, you'll want to install the following packages:
+
+* latexmk
+* texlive-latex-recommended
+* texlive-latex-extra
+* texlive-fonts-extra
+* texlive-fonts-recommended
+* texlive-bibtex-extra
+* moreutils
+* gawk
+
+Also, to install Garamond grab and install the font from [https://ctan.org/pkg/urw-garamond here] through the following complicated process:
+
+* Download the file
+* Create ''~/texmf'' if it does not exist yet
+* Unzip the file ugm.zip from the garamond.zip file into that ~/texmf/
+* Copy the other font files in the root directory of garamond.zip into ~/texmf/fonts/type1/
+* Run "texhash ~/texmf
+
+Alternatively, if you want to install them system wide and have root credentials, you can also place them in ''/usr/local/share/texmf'' instead.
+
+=== Using MacTeX on macOS ===
+
+To install with MacTeX, you need to install the font:
+
+ wget https://tug.org/fonts/getnonfreefonts/install-getnonfreefonts
+ texlua install-getnonfreefonts
+ sudo getnonfreefonts-sys garamond
+