use-math-macros — condense manuscript math onto the shared macros submodule
Rewrite the math expressions in a lab Quarto/LaTeX document so they use the shared Morrison-Lab/macros submodule (migrated from d-morrison/macros, whose URLs redirect to it) (\Ep, \Prf, \paren/\sb/\cb, \expit, \logit, \Var, \hp, \S, \h, …) instead of ad-hoc raw LaTeX. This gives every lab document the same polished, condensed notation, and centralizes the definitions in one versioned place.
When this fires
- “macroize”, “macroize the math”, “use macros”, “use the macros submodule”, “convert math to macros”, “polish the math with macros”.
- Every time you write, edit, or review LaTeX math anywhere: any project or repo, and any format (Quarto, R Markdown, LaTeX, roxygen and
.Rd, slides, Markdown docs, notebooks), a manuscript or a single equation alike — this is mandatory, not a polish pass. Use the semantic macro for each concept the library names (\Epfor a bare expectation operator,\E{x}for one subscripted byx,\Var,\Cov,\P, …) rather than writing its raw LaTeX, and when no macro names the concept, add one (step 6) rather than writing raw LaTeX (standing rule; seememories/preferences.md).
Procedure
1. Locate and check out the macros submodule
It is typically vendored at inst/analyses/macros (URL in .gitmodules):
To bring it up to date with Morrison-Lab/macros:
--remotebumps the tracked gitlink, which dirtiesgit diff HEAD. If the checkout is running SLURM/simulation jobs that stamp git provenance at completion (e.g. aconsolidate_provenance-style reproducibility guard), that poisons the run. Do the update in a separate worktree, never the running checkout:git worktree add ../<repo>-macros -b macros-update origin/main.
2. Wire the include once, at the top of the manuscript
Include the macro definitions before any math renders:
Place it near the top of the top-level .qmd (the one that assembles the {{< include >}}d children), before the first section with math.
The definitions do not blindly override existing LaTeX, and the two definition forms behave differently: \def always redefines a name, but MathJax skips \providecommand for a name that is already defined — including a LaTeX built-in like \v (caron), \b, \u, or \c. So a \providecommand whose name shadows a built-in silently no-ops: the built-in meaning survives and the render breaks with no error. The library therefore uses \def / \renewcommand (not \providecommand) for built-in-shadowing names — e.g. \renewcommand{\v}{...}, \renewcommand{\vec}{...}. See the “MathJax ignores \providecommand” note in memories/preferences.md.
3. Read the macro inventory before rewriting
macros.qmd may define macros with any of \def, \providecommand, \newcommand, or \renewcommand (the built-in-shadowing names like \v, \vec use \renewcommand), so match all four forms:
Measured 2026-09-06 on d-morrison/rme, whose copy of this same macros library is mounted at latex-macros/ rather than at the inst/analyses/macros/ path used above. It is the same d-morrison/macros repo either way — rme’s .gitmodules gives url = https://github.com/d-morrison/macros.git — so the mount path is what varies between consumers, not the library. An earlier draft of this entry said “not d-morrison/macros”, which read as a claim that these are two unrelated macro libraries. A sweep pattern-matching only \newcommand{...}/\providecommand{...} reported \vX and \vbeta as undefined; both are \def-defined. Widening the grep to all four forms above found 30 distinct v-prefixed names defined in that library — counting distinct defined names rather than uses (the definition sites number 32, since \v is defined three times), and including non-vector names such as \var and \violet that share the prefix — and exactly 2 genuinely undefined (\vL, \vl). Same class as the built-in-shadowing case this step already names — a definition-site grep is only as complete as its list of definition mechanisms, and any macros file mixing TeX primitives can use all four.
- Do: run the four-form grep above (or an equivalent covering
\def,\providecommand,\newcommand,\renewcommand) before asserting any macro is undefined, in every.qmd-based macros file, whatever path the consumer mounts it at. - Don’t: conclude a macro is undefined from a grep that only matches
\newcommand/\providecommand— confirm against\defand\renewcommandtoo.
4. Rewrite the math — using only defined macros
Delegate the heavy rewrite to the codex CLI to conserve tokens (pass the macro inventory and the target file in the prompt), then verify:
codex exec -C "$PWD" -s read-only --skip-git-repo-check -o /tmp/macroized.out - <<'EOF'
Rewrite the math in <target>.qmd to use ONLY macros defined in
inst/analyses/macros/macros.qmd plus standard LaTeX. Preserve every formula's
meaning exactly and keep all {#eq-...}/{#tbl-...} labels and @eq- refs. Output
the rewritten .qmd, then a list of the custom macro names used.
EOF(Flags per codex exec --help — the exec subcommand, -s/--sandbox read-only, --skip-git-repo-check, and -o/--output-last-message all exist; verify against your installed codex-cli version, since flag names can shift between releases.)
Never invent a macro name — an undefined command silently breaks the Quarto/MathJax render. Verify every backslash-command resolves:
# every custom command in the rewrite must be defined in macros.qmd or be standard LaTeX
comm -23 \
<(grep -oE '\\[A-Za-z]+' <target>.qmd | sort -u) \
<(grep -oE '\\(def|providecommand|newcommand|renewcommand)\{?\\[A-Za-z]+' inst/analyses/macros/macros.qmd \
| grep -oE '\\[A-Za-z]+$' | sort -u)
# review the remainder: each must be standard LaTeX (\frac, \text, \sim, \hat, …)When the math being rewritten is a definition, expand both sides before believing it. The library aliases heavily, so a definition can name a concept on the left and define it in terms of a second macro on the right, while both expand to the same glyph. \score(\lambda) \eqdef \llik'(\lambda) reads as a definition in source and renders as a symbol defined as itself, because \def\score{\ell'} and \def\llik{\ell} collapse the two sides. This is the opposite failure from inventing a macro name: every command resolves, so the comm -23 check above passes cleanly and the render emits no warning.
Two greps settle it, and both are cheap:
The library’s own canonical definitions spell the operator out rather than restating an alias, so prefer that form: \deriv{\lambda}\llik(\lambda) for a score, \dderiv for a Hessian. An alias-only definition is a deviation from house style, not a shorthand for it. Verify the result by reading the rendered page, per fact-check-prose’s “A definition can resolve, render, and still say nothing” — source cannot show this, and neither can a check that the crossref resolves.
5. Fix the vignette spellcheck leak
Custom macro command-names (paren, Ep, expit, Prf, cb, …) leak into spelling::spell_check_package() for .qmd files under vignettes/ — the spelling LaTeX filter strips common commands like \text/\frac but not custom macros. Add every custom macro name used, plus genuine terms (expit, exchangeability), to inst/WORDLIST:
Files under inst/analyses/ are not spell-checked, so this only bites for math in vignettes/.
6. Add missing macros to the submodule when helpful
If a needed concept has no macro, add it to Morrison-Lab/macros via a PR to that repo — do not define a one-off command inline in the manuscript:
Name the new macro for the concept it denotes, not for its typography, so it stays semantic. The macros repo carries a standing mwc grant, so merge the macro PR yourself once it is fully clean (see STANDING_MERGE_GRANT_REPOS in hooks/no-unauthorized-merge.py). Bump the submodule pointer in the manuscript repo once that macro PR merges.
New macros always go in Morrison-Lab/macros, never in an applied repo. The one exception is a repo that explicitly overrides one specific macro’s default meaning, in a dedicated override file. (Directive from the user, 2026-10-16: “new macros should always go into our macros repo, never into applied repos (unless you’re explicitly overriding the default macros repo for a specific semantic macro)”.) If the macros PR has to wait, say so and keep the change in a stacked PR on the macros PR; do not add a repo-local macro or an inline command. A repo-local macro file left over from the old stopgap (such as _subfiles/_macros-sds.qmd in sds) is debt: move each definition into Morrison-Lab/macros in a small PR (this is moving macro definitions, not sweeping content for a new rule). File an issue in Morrison-Lab/macros listing each leftover definition, what it means, and any existing macro it overlaps. In a remote session that has the repo attached under its old name, the issue tool accepted owner d-morrison and GitHub redirected the issue to the migrated repo (measured once, 2026-10-05: Morrison-Lab/macros#103).
- Do: add the macro to
Morrison-Lab/macros, and file the sweep issue in the same turn that you find a repo-local macro file. - Don’t: add a macro to a repo-local file, or leave one for a later upstreaming pass; Morrison-Lab/sds#54 accumulated 13 of them before anyone filed the issue.
A missing macro is never a reason to keep raw LaTeX. When a macro would make an expression shorter or clearer, and none exists, adding one is the task, not a limit on it (Ezra, 2026-10-28). This is the step that gets skipped when a reviewer asks to “use macros” and part of the expression has no macro yet: the easy answer replaces what the library already covers and reports the rest as unavoidable. That half-answer is the failure, so treat the missing macro as the first piece of work: open the macros PR, then use the macro in the stacked or follow-up change once the pin is bumped.
- Do: when a reviewer asks for macros, or a hand-written chunk such as
\eigval_{\max}repeats, check the library; if nothing names the concept, open aMorrison-Lab/macrosPR for it in the same turn. - Don’t: write “the macros list has no single macro for X, so it stays as it is”, or any rewording of that, in a reply, a PR description or a commit message. (Morrison-Lab/lds#1534, 2026-10-28: asked to condense \(\tfrac14 \eigval_{\max}\paren{\tp{X_s} X_s / \nobs}\) with macros, an agent switched to
\stprodand\designbut kept\eigval_{\max}raw “because the macros list has no single macro for the largest eigenvalue”. Ezra rejected that reasoning, and Morrison-Lab/macros#317 added\eigvalmax,\eigvalminand their call forms, for a chunk the lds notes write by hand about 30 times.) - A deterministic hook cannot enforce this rule. Whether a macro would help is a judgment about the expression, and a phrase match would catch only one wording of the excuse.
7. Verify the render and spellcheck, then ship
Run the raw-notation lint over what you changed, from the repository root:
It finds the library itself, as the macros submodule whose .gitmodules URL is the macros repository (latex-macros/, macros/ or inst/analyses/macros/, checked out or not), and extends the built-in rules with every operator macro the library defines. Pass --macros <path>/macros.qmd for a library that is not a submodule. It exits 1 and prints file:line: raw -> use macro for each hit. hooks/warn-raw-math-notation.py runs the same rules at write time, from the edited file’s repository, and warns, never blocks; with no library found, both fall back to the built-in rules alone.
Commit the rewritten .qmd, the include line, the submodule pointer, and the WORDLIST on a branch, open a PR, and drive it to clean.
Relationship to other skills
convert-repo-format— scaffolds themacros/submodule when converting a repo to a Quarto book/website (git submodule add); this skill rewrites math onto an already-present submodule. Adjacent concerns.use-preferred-style/find-ai-tells— the prose counterparts: they polish and de-slop written prose; this skill polishes math notation.memorize/remember— the paired standing rule (“always use the macros submodule for math”) lives inmemories/preferences.md; this skill is the executable how.ardi/request-pr-review— used to ship and clean the PR this skill produces.
Macros that \renewcommand a standard command take a mandatory argument
macros.qmd redefines \exp (\renewcommand{\exp}[1]{\operatorname{exp}\cb{#1}}), \vec, and \v with one mandatory argument each. A bare $\exp$ (the function name, no argument) makes the macro swallow the closing math delimiter as its argument, which leaves \cb’s \left/\right unbalanced. MathJax renders that without complaint; lualatex fails with Missing \right. inserted. So an HTML render is no evidence that the PDF builds.
Similarly, writing \exp\paren{...} or \exp(...) triggers delimiter failures in LaTeX: because \exp wraps its mandatory #1 in \cb{#1}, passing \paren makes \exp take \paren as #1, leaving unbalanced delimiters in LuaLaTeX (! Missing delimiter (. inserted)). Writing \exp(...) makes \exp consume only the opening parenthesis ( as #1, leaving the closing ) unmatched. The required form is \exp{...} or e^{...}.
Measured 2026-09-28 on Morrison-Lab/pds: Quarto Publish run 36516449603 failed on $\exp$ in _subfiles/_sec-distributions.qmd. Fixed by Morrison-Lab/pds#34, which spelled out “the exponential function”; the zero-argument \expt also works. Tracked in Morrison-Lab/pds#33. Recurred 2026-10-06 on Morrison-Lab/mds#175 with \exp\paren{-\frac{x^2}{2}} and \exp(x^8), breaking LuaLaTeX compilation with missing delimiter errors; fixed by changing to \exp{-\frac{x^2}{2}} and \exp{x^8}.
- Do: write
\exp{...}ore^{...}when applying the exponential function to an argument. - Do: name the function in prose, or use a zero-argument form (
\expt), when no argument is meant. - Do: grep for bare uses, e.g.
grep -rnE '\\(exp|vec|v)([^a-zA-Z{]|$)' --include='*.qmd', and render the PDF target when touching math. The grep is a candidate finder: it also flags valid space-separated arguments (\vec \beta) and the definitions themselves, so read each hit. - Don’t: write
\exp\paren{...}or\exp(...)—\exptakes a mandatory#1wrapped in\cb{#1}. Use\exp{...}ore^{...}instead. - Don’t: write a bare
$\exp$(or\vec,\v). - Don’t: treat a clean HTML render as evidence the PDF builds.
Common undefined shorthand and macro collisions in macros.qmd
- Undefined matrix and vector shorthands (
\mA,\vw): whilemacros.qmddefines\mX(\matr{X}),\mx,\vx(\vecf{x}),\va, etc., it does not define arbitrary shorthands like\mAor\vw. Bare\mAor\vware undefined and break LuaLaTeX during PDF compilation. Use\matr{A}for matrices and\vec{w}or\vecf{w}for vectors. - Undefined square bracket macro (
\bracket):macros.qmddoes not define\bracket{...}. Using\bracket{...}(such as for definite integral evaluation limits) fails in LaTeX as an undefined control sequence. Use\sb{...}(square bracket) instead (\sb{...}wraps in\mathopen{}\left[...\right]\mathclose{}). (Morrison-Lab/mds#175, 2026-10-06.) - Latin vector collision with
\vb:macros.qmddefines\def\b{\beta}and\def\vb{\vec \b}, which expands to Greek\vec{\beta}rather than Latin vector \(b\). When denoting a Latin vector (such as an intercept or bias vector \(b\)), do not use\vb; use\vec{b}or\vecf{b}. (Morrison-Lab/mds#48, 2026-09-29.)
No Greek letters in math source: name macros for meaning
A semantic macro is named for what a symbol means, not for the letter it prints. \vdelta, \vbeta, \hb, \bfbeta, \vth, \eps and \lam only spell a Greek letter, so they are no more semantic than the raw \delta. Outside a passage that discusses the notation itself (a symbol table, a note on which letter a field uses), write no Greek letter in a math expression, either raw or inside a letter-named macro, except a one-off symbol with no semantic category (see the Latin-letter section below). Use the macro that names the concept (\vcoef, \regcoef, \mean, \lincomp, \odds, \rate, \haz, \sigmoid), and when none exists, add one named for the concept to Morrison-Lab/macros first (step 6). For example, write the backpropagation error as \backerr^{(\ell)}, not \vdelta^{(\ell)}, and the step size as \learnrate, not \eta. Morrison-Lab/macros#113 added a concept macro for each meaning the course sites use (\sdpar, \varpar, \noise, \regpar, \param, \slack, \siglevel and the rest; interpretations.tsv lists them all), so search it before adding one. A new name must not clash with a TeX primitive or a package command: \penalty (a primitive) broke every PDF, and siunitx defines \ang. One letter often means different things on different pages (\sigma for a standard deviation and for the sigmoid; \lambda for a rate, a penalty and an eigenvalue), so choose the macro from each use’s meaning, not from the letter. (Directive from the user, 2026-10-08: “except when we’re discussing notation directly, I don’t want any hardcoded greek letters in latex expression, even in compounds like ; that’s still not a semantic macro”. Prose rule: Morrison-Lab/psw#136; detection: Morrison-Lab/ai-config#4381.)
Decorators name a role too: \est{}, not \hat
The same rule covers decorators. \hat, \tilde and \bar say how a symbol is drawn, not what it means, and a hat can mark an estimate, a fitted value or a transform. So \hat{\mean} is no more semantic than \mu: write \est{\mean} (from Morrison-Lab/macros, which prints a hat) for an estimate, and the \est-based forms where a compound exists (\ecoef{j}, \evcoef, \esdpar) rather than the hat-based \hcoef{j}, \hvcoef, \hsdpar. Pick a compound built on a concept macro: \esig and \hs also spell the Greek letter, so the section above already rules them out. When a decorated quantity has no role macro, add one to Morrison-Lab/macros first, as for Greek letters. Keep \hat only where the text discusses the notation itself. This is the target state rather than a blocker on current work: write new math this way now, and convert existing hats when you edit that math anyway (no sweep unless Ezra asks: no-sweeps-by-default).
- Do: write
\est{\mean}or\ecoef{j}for an estimate in new or edited math. - Don’t: introduce
\hat{...}or a hat-based compound (\hcoef,\hvb) in new math.
(Directive from the user, 2026-10-08: “eventually, we want to remove even non-semantic decorators like in favor of semantic macros like \est”. Prose rule: psw chapters/notation/shared-macros.qmd; sweep and detection: Morrison-Lab/ai-config#4438.)
\ell is a letter too
A bare \ell spells a letter, so it is no more semantic than a Greek letter. Choose the macro from the meaning:
\llik(or\score,\hess) for the log-likelihood and its derivatives;\obsloss{i}for the loss on observationi;\lpnorm{p}for the name of an\ell_pnorm or penalty;\lboundfor a lower bound of a set;- a Latin letter for a dummy index or a count (
j,r,m), unless it clashes with another symbol on the page.
scripts/check-raw-math.py and the write-time hook flag a bare \ell. Keep \ell only where the text discusses the notation itself. (Directive from the user, 2026-10-09: “\ell is another non-semantic macro”. Macros: Morrison-Lab/macros#118.)
Presentation commands are not notation: sizing, transposes and fonts
Three more raw forms describe how something is drawn, not what it means. The lint and the hook flag each of them, and a rewrite uses the macro that names the concept:
- Manual sizing (
\big,\Big,\bigg,\Bigg, withl,rorm): write\paren{...},\sb{...},\cb{...},\abs{...}or\norm{...}, which size themselves, and\evalAt{expression}{point}for an evaluation bar. Big operators such as\bigcupare not sizing and are not flagged. - Manual
\leftand\right: write\paren{...}for parentheses,\sb{...}for square brackets,\set{...}for a set,\cb{...}for other braces and\abs{...}for bars, instead of\left( ... \right)and its relatives. Write\evalAt{expression}{point}for an evaluation bar. Arrows such as\leftarroware not flagged. A one-sided delimiter with no matching macro, such as a half-open interval, needs a macro named for the concept. Add one when it is needed. - A raw transpose (
^\top,^{\top}): write\tp{X}, or\pt{...}for a parenthesized expression. Write the product of two vectors as\dprod{a}{b}and a matrix with itself as\stprod{X}; a matrix times a different factor stays\tp{X}followed by that factor, because it is not a dot product. - A font command used as a symbol (
\mathbb,\mathcal,\mathscr,\mathfrak): searchmacros.qmdfor the concept (\reals,\Nat,\Lik,\Ep) and add one named for the concept when none exists. The same letter means different things on different pages, so choose from the meaning.
(Directive from the user, 2026-10-09: all \mathbb, \mathscr, \mathcal and similar, manual sizing such as \big, and \top should be checked and replaced with semantic macros. Also 2026-10-09: manual left and right delimiters were still in the lds notes.)
Latin letters with a fixed role: \outvar, \predvar, \resid
A Latin letter that stands for a role in a model needs a role macro too. Write \outvar/\Outvar/\voutvar for the outcome variable, not a bare y or \vy. Write \predvar/\Predvar/\vpredvar for a predictor, not a bare x or \vx. Write \eoutvar for a predicted outcome. Write \resid/\vresid for a residual (observed minus predicted) and \prederr for a prediction error (predicted minus observed), not a bare e or \ve; for an observation used in the fit, the residual is the negative of the prediction error (sds #thm-prediction-error-residual). For a parameter estimate, write \erf{\eparam} (estimate minus truth, sds #def-estimation-error). No literal Latin or Greek letter appears in a math expression, outside a passage that discusses the notation itself, except a one-off symbol that corresponds to no semantic category. Almost every symbol has a category: the library already names outcome variables (\outvar), covariates and predictors (\predvar), generic parameters (\param, \vparam), prediction functions (\predfn), and more, so a one-off should almost never be needed. A function argument or integration variable is a generic variable of some kind, so look for its category first; add a macro to Morrison-Lab/macros (step 6) whenever a category has none. \vx and \vy remain defined; existing uses are converted in the sweep, Morrison-Lab/ai-config#4440, not as a side edit. The macros land with Morrison-Lab/macros#117; until a repo’s latex-macros pin includes it, keep the existing letters there.
- Do: write
\resid_i = \outvar_i - \eoutvar_iin new or edited math. - Don’t: write
e_i = y_i - \hat{y}_i.
(Directive from the user, 2026-10-09: “let’s use a semantic macro rather than a bare e. even y should be a macro for outcome variable, and x should be a macro for predictor variable(s)”. Macros: Morrison-Lab/macros#117; sweep: Morrison-Lab/ai-config#4440.)
Write a named quantity by its macro, not its definition
Once a quantity has a name and a macro, write the macro rather than re-expanding the expression that defines it. This is the macro-level case of math-derivation-steps’s “keep each equation simple”: every expression stays concise, and the reader sees which quantity it is about. When the quantity has no macro yet, add one to Morrison-Lab/macros first.
- Do: write the gradient of the mean squared error as
\frac{2}{n} \tp{\design} \vprederr, with the prediction errors named\vprederrand defined once in the text as\vprederr = \design\vcoef - \vy. - Don’t: write
\frac{2}{n} \tp{\design} \paren{\design\vcoef - \vy}after the prediction errors already have a name.
The pair uses prediction errors (predicted minus observed); \vy - \design\vcoef is the vector of residuals, \vresid. (Directive from the user, 2026-10-09: “remember to always decompose expressions to make each one concise; … why not use the prediction error macro instead of \vy - \design \vcoef?” Also tracked as Morrison-Lab/psw#140.)
Name a repeated or coherent chunk with a new macro
Before finishing any definition, theorem or proof, scan for a sub-expression written out two or more times, or a conceptually coherent chunk (the prediction error, the loss of one observation), and give it a macro instead of writing it out. Add the macro to Morrison-Lab/macros first, with an interpretations.tsv row, never as a local macro. The full rule is in math-derivation-steps (“Keep each equation simple”, Do and don’t). (Directive from Ezra, 2026-10-16.)
Update the notation-choices page with every macro change
Whenever you add, rename, remove or change what a macro prints in Morrison-Lab/macros, update notation-choices.qmd in the same PR. Each entry states our convention, the reasons for it, and the other conventions readers will meet in other sources. If the page is already accurate after your change, say why in the PR description and apply the no-notation-change label. Once Morrison-Lab/macros#248 lands (as of 2026-10-19 it has not), CI in Morrison-Lab/macros will fail a PR that changes macros.qmd without changing notation-choices.qmd. Until then nothing catches the omission, so check it yourself. Applied notes repos link to the entry instead of keeping their own copy. (Directive from Ezra, 2026-10-19: “make sure every time we change or add macros, we update the notation-choices page accordingly”. Tracked in Morrison-Lab/macros#248.)
Prefer command operator macros that take arguments over manual delimiter wrappers
There should be very few instances where it is necessary to write \cb (curly braces), \sb (square brackets), or \paren directly with a bare operator. Instead, use the functional command version of the operator macro that takes its operand as an argument and wraps it in delimiters automatically:
- Expectation: write
\Expf{X}or\E{X}(expands to\distop{E}\sb{X}), not bare operator\Epfollowed by manual\sb{X}(\Ep\sb{X}). - Variance / Covariance: write
\Var{X}or\Cov{X, Y}, not\Vart\paren{X}. - Probability / Quantile: write
\Prf{A}or\Qf{p}, not\Pr\paren{A}or\Q\paren{p}. - Exponential: write
\expf{x}or\exp{x}(ore^{x}), not\expt\paren{x}. - Indicator: write
\indicp{P}or\indic{A}(x). - Any function-like macro, not only operators: when a symbol macro such as
\predfnis applied to arguments, write itsfform (\predfnf{\predvar}), not the symbol followed by\paren{...}(\predfn\paren{\predvar}). The same holds for\cb{...}and every other delimiter macro, as in\expitf{x}rather than\expit\cb{x}. Before typing a macro followed by\paren,\sbor\cb, grepmacros.qmdfor<name>f. If nofform exists, propose one inMorrison-Lab/macrosfirst; notes never define it locally. (Directive from the user, 2026-10-16, review ofMorrison-Lab/sds#261; tracked in #4597.) - Operator plus any delimiter is one macro (psw’s apply a function to its argument with the macro’s f form rule): the delimiters covered are
\paren,\sb,\cb,\set,\abs,\normand\angb, and an alias of the operator counts as the operator (\Ep\sb{X}is\E{X}). A missing combined macro is created inMorrison-Lab/macrosin the same session, never worked around. Then bump the pin and use it. (Directive from the user, 2026-10-18, review ofMorrison-Lab/lds#1157. Tracked in psw#286; checked by ghacheck-fform-paren, gha#1106.)
Reserve direct \sb{...}, \cb{...}, and \paren{...} for mathematical grouping, sets (\(\cb{1, \dots, n}\)), evaluation limits, or raw algebra that does not denote an operator with a dedicated macro. (Directive from the user, 2026-10-07.)
Prefer dot products over transpose products and inner products
When two vectors multiply to give a number, write a dot product, \dprod{\vx}{\vbeta} (\(\vx \cdot \vbeta\)), not a transpose product (\vx^\top \vbeta, \vx' \vbeta, \tprod{\vx}{\vbeta}) or inner-product brackets (\langle \vx, \vbeta \rangle, \iprod{\vx}{\vbeta}). For example, write a linear model as f(\vx) = \dprod{\vx}{\vbeta}, not f(\vx) = \vx^\top \vbeta. Keep the transpose where the product is not a dot product of two vectors: a matrix product (\tp{X} X), an outer product, or a quadratic form (\tprod{\vx}{\matr{A}} \vx). Keep inner-product brackets where the text means a general inner product, such as the definition of an inner product space. The prose rule is psw’s Writing dot products. (Directive from the user, 2026-10-08, on Morrison-Lab/lds#488.)
Anti-patterns
- ❌ Inventing a macro name not defined in
macros.qmd— it silently breaks the render. Verify every command resolves (step 4). - ❌ Using bare
\mAor\vwexpecting them to expand to matrices or vectors — they are undefined inmacros.qmdand break LuaLaTeX during PDF compilation. Use\matr{A}and\vec{w}/\vecf{w}instead. - ❌ Using
\bracket{...}for square brackets —\bracketis undefined inmacros.qmd. Use\sb{...}instead. - ❌ Writing
\exp\paren{...}or\exp(...)—\expwraps its mandatory#1in\cb{#1}; passing\parenor(...)breaks delimiter balance in LuaLaTeX (! Missing delimiter (. inserted)). Use\exp{...}ore^{...}instead. - ❌ Using
\vbfor Latin vector \(b\) (e.g. bias or intercept) —macros.qmddefines\vbas\vec{\beta}(Greek beta), colliding with Latin vector \(b\). Use\vec{b}or\vecf{b}instead. - ❌ Running
git submodule update --remotein a checkout that is running provenance-stamped SLURM jobs — it dirties the tree and poisons the run. Use a worktree. - ❌ Forgetting the
inst/WORDLISTadditions for macros used invignettes/math — spellcheck fails on the leaked command-names. - ❌ Defining a one-off
\newcommandinline instead of adding it to the shared submodule. - ❌ Defining a built-in-shadowing macro (
\v,\b,\u,\c, accents, …) with\providecommand— MathJax skips it because the built-in is already defined, so the built-in survives and the render breaks silently. Use\def/\renewcommandfor those names (see step 2 andmemories/preferences.md). - ❌ Defining a macro’d concept by restating another macro (
\score \eqdef \llik') — the aliases collapse, so the rendered page shows a symbol defined as itself while the source reads as a proper definition. Spell the operator out (\deriv,\dderiv), and check the rendered output rather than the source. - ❌ Changing a formula’s meaning while “condensing” — preserve the math exactly; only re-express it.