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,52 +1,130 @@
 ================================
-=== LaTeX Custom Scripts ======
+=== CDSC LaTeX Templates =======
 ================================
 
-Copyright (c) 2009-2018 Benjamin Mako Hill <mako@atdot.cc>
+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://projects.mako.cc/source/latex_mako/
+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 git://projects.mako.cc/latex_mako
+  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 <mako@atdot.cc>
+  Benjamin Mako Hill <makohill@uw.edu> [work]
+  Benjamin Mako Hill <mako@atdot.cc> [personal]
 
-The paper template has seen quite a lot of recent work. The letter
+To submit a patch, clone the repository, make your changes, and use
-template has seen very little and may only barely function.
+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
 
-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
 
-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

paper_template/.gitignore

@@ -13,3 +13,5 @@
 /*.ttt
 /*.bcf
 /*.run.xml
+/figures/*
+/*.tex

paper_template/Makefile

@@ -1,11 +1,9 @@
 #!/usr/bin/make
 
-all: $(patsubst %.tex,%.pdf,$(wildcard *.tex)) 
+all: $(patsubst %.Rtex,%.pdf,$(wildcard *.Rtex)) 
 
-# use the following section for Rnw/knitr documents
+%.tex: %.Rtex
-# all: $(patsubst %.Rnw,%.pdf,$(wildcard *.Rnw))
+	Rscript -e "library(knitr); knit('$<')"
-# %.tex: %.Rnw
-#	Rscript -e "library(knitr); knit('$<')"
 
 %.pdf: %.tex 
 	latexmk -f -pdf $<
@@ -15,9 +13,9 @@ clean:
 	rm -f *.tmp *.run.xml
 	rm -f vc
 	rm -f *.bbl
-	# the following lines are useful for Rnw/knitr
+	# the following lines are useful for Rtex/knitr
-	# rm -rf cache/ figure/
+	rm -rf cache/ figure/
-	# rm -f *.tex
+	rm -f *.tex
 
 viewpdf: all
 	evince *.pdf
@@ -27,4 +25,4 @@ vc:	resources/vc-git
 pdf: all
 
 .PHONY: clean all
-# .PRECIOUS: %.tex
+.PRECIOUS: %.tex

paper_template/resources/preamble.R

@@ -0,0 +1,50 @@
+bold <- function(x) {paste('{\\textbf{',x,'}}', sep ='')}
+gray <- function(x) {paste('{\\textcolor{gray}{',x,'}}', sep ='')}
+wrapify <- function (x) {paste("{", x, "}", sep="")}
+
+# load("knitr_data.RData"); now broken up into small files so we'll bring 'em all in together
+r <- do.call("c", lapply(paste("knitr_rdata/", list.files("knitr_rdata"), sep=""),
+                         function (x) {load(x); return(r)}))
+
+attach(r)
+
+f <- function (x) {formatC(x, format="d", big.mark=',')}
+
+format.percent <- function(x) {paste(f(x*100),"\\%",sep='')}
+
+format.day.ordinal <- function(x) {
+    day <- format(x,format="%d")
+    daylast <- substr(day,nchar(day),nchar(day))
+    dayfirst <- substr(day,1,1)
+    if(dayfirst == '0')
+        day = daylast
+
+    if( daylast == "1")
+        day <- paste0(day,"st")
+    else if(daylast == "2")
+        day <- paste0(day,"nd")
+    else if (daylast == "3")
+        day <- paste0(day,"rd")
+    else
+        day <- paste0(day,"th")
+        
+    return(day)
+}
+
+format.month <- function(x){
+    return( format(x,format='%B %Y'))
+}
+
+format.date <- function(x) {
+    return(paste(format(x,format = '%B'),format.day.ordinal(x),format(x,format='%Y'),sep=' '))
+}
+
+format.pvalue <- function (x, digits=3) {
+    threshold <- 1*10^(-1*digits)
+    x <- round(x, digits)
+    if (x < threshold) {
+        return(paste("p<", threshold, sep=""))
+    } else {
+        return(paste("p=", x, sep=""))
+    }
+}

paper_template/text.Rtex

@@ -9,6 +9,18 @@
 
 \usepackage[utf8]{inputenc}
 \usepackage{wrapfig}
+
+<<init, echo=FALSE>>=
+knit_hooks$set(document = function(x) {
+  x <- sub('\\usepackage[]{xcolor}',
+           '\\usepackage[dvipsnames]{xcolor}', x, fixed = TRUE)
+  x
+})
+opts_chunk$set(fig.path="figures/knitr-")
+
+source("resources/preamble.R")
+@
+
 \usepackage[T1]{fontenc}
 \usepackage{textcomp}
 \usepackage[garamond]{mathdesign}
@@ -25,9 +37,8 @@
 % \usepackage{endfloat}
 
 % import and customize urls
-\usepackage[usenames,dvipsnames]{color}
+\usepackage[dvipsnames]{xcolor}
 \usepackage[breaklinks]{hyperref}
-
 \hypersetup{colorlinks=true, linkcolor=Black, citecolor=Black, filecolor=Blue,
     urlcolor=Blue, unicode=true}
 
@@ -134,6 +145,15 @@ brown fox jumps over the lazy dog.  The quick brown fox jumps over the
 lazy dog.  The quick brown fox jumps over the lazy dog.  The quick brown
 fox jumps over the lazy dog \citep{989866}.
 
+\begin{table}
+  \centering
+<<test_table, echo=FALSE>>=
+kable(form.copy, format="latex")
+@
+\caption{This is a test table. There are \Sexpr{f(nrow(form.copy))} rows in the table.}
+\label{tab:test}
+\end{table}
+
 The quick brown fox jumps over the lazy dog.  The quick brown fox jumps
 over the lazy dog.  The quick brown fox jumps over the lazy dog.  The
 quick brown fox jumps over the lazy dog.  The quick brown fox jumps over

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
+