explico 0.13.1 → 0.14.0

package/dist/compiler/exports/latex/explico.cls

@@ -13,85 +13,24 @@
 %% (‹part›.‹n›). LaTeX does the counting; explico checks every number against
 %% the website when it builds the PDF.
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesClass{explico}[2026/10/04 explico course book class]
+\ProvidesClass{explico}[2026/10/10 explico course book class]
 
 %% `scripts`: the document holds Greek, Cyrillic, CJK or emoji (the exporter
 %% sets it when it does), so LuaLaTeX loads the fallback fonts below.
-\newif\ifexplico@scripts
-\DeclareOption{scripts}{\explico@scriptstrue}
+\DeclareOption{scripts}{\PassOptionsToPackage{scripts}{explico-common}}
 \DeclareOption*{\PassOptionsToClass{\CurrentOption}{book}}
 \ProcessOptions\relax
 \LoadClass[11pt,oneside,openany]{book}
 
-%% --- Engine and fonts ------------------------------------------------------
-\RequirePackage{iftex}
-\RequirePackage{amsmath,amssymb,mathtools}
-%% Rule N17's engine half, as on the website (src/reference/katex-delimiters.mjs):
-%% a negative \delimitershortfall makes every \left...\right pair strictly taller
-%% than its content, so a nest grows outward at each level. TeX's default (5pt)
-%% lets nested pairs round to the same glyph.
-\delimitershortfall=-1pt
-%% Whether a text font sets Greek; if none does, a Greek letter in prose is
-%% set as its math symbol (below, with the other Unicode characters).
-\newif\ifexplico@greek
-\ifPDFTeX
-  \RequirePackage[T1]{fontenc}
-  \RequirePackage{lmodern}
-  \RequirePackage{textcomp}
-  \RequirePackage{bm}
-  %% A character no pdfTeX font sets (accented Greek, Chinese, an emoji) stays
-  %% blank instead of stopping the compile, and the log says so in LuaLaTeX's
-  %% words, which the export turns into its warning about blank characters.
-  \def\UTFviii@undefined@err#1{%
-    \typeout{Missing character: There is no
-      \expandafter\UTFviii@splitcsname\string#1\relax\space in font pdftex!}}
-\else
-  %% Latin Modern for text and math. unicode-math is also what lets a tagged
-  %% PDF carry MathML for every formula (luamml needs it); bm does not work
-  %% with it, so \bm becomes \boldsymbol.
-  \RequirePackage{unicode-math}
-  \providecommand{\bm}{\boldsymbol}
-  %% Latin Modern has no Greek, Cyrillic, Chinese, Japanese, Korean or emoji.
-  %% With `scripts`, prose in those scripts comes from fallback fonts: for each
-  %% script, the first of the fonts below this machine has (CMU Serif, from
-  %% TeX Live's cm-unicode, matches Latin Modern). A script none of them
-  %% covers stays blank, and the export warns about it.
-  \ifexplico@scripts
-  \def\explico@fallbacks{}
-  \def\explico@fallback#1#2{%
-    \let\explico@found\@empty
-    \@for\explico@candidate:=#1\do{%
-      \ifx\explico@found\@empty
-        \IfFontExistsTF{\explico@candidate}{%
-          \edef\explico@fallbacks{\explico@fallbacks"\explico@candidate:mode=harf;",}%
-          \let\explico@found\explico@candidate}{}%
-      \fi}%
-    \ifx\explico@found\@empty\else#2\fi}
-  \explico@fallback{CMU Serif,Noto Serif,DejaVu Serif,FreeSerif}{\explico@greektrue}
-  \explico@fallback{Noto Serif CJK SC,Noto Sans CJK SC,FandolSong,Source Han Serif SC}{}
-  \explico@fallback{Noto Color Emoji,Twemoji Mozilla,Symbola}{}
-  \ifx\explico@fallbacks\@empty\else
-    \directlua{luaotfload.add_fallback("explico", {\explico@fallbacks})}%
-    \setmainfont{Latin Modern Roman}[RawFeature={fallback=explico}]%
-  \fi
-  \fi
-\fi
-\RequirePackage{microtype}
+%% What the deck theme shares: engine, fonts, colours, figures, TikZ, boxes,
+%% Unicode, notation markers and cross-references (explico-common.sty).
+\RequirePackage{explico-common}
 
-%% --- Page and colour --------------------------------------------------------
+%% --- Page ---------------------------------------------------------------------
 \RequirePackage[margin=1in]{geometry}
-\RequirePackage{xcolor}
-\definecolor{explicoaccent}{HTML}{12775C}
-\definecolor{explicoframe}{HTML}{9DB8AD}
-\definecolor{explicoback}{HTML}{F3F8F6}
-\definecolor{explicoasidecaution}{HTML}{B5651D}
-\definecolor{explicoasidecautionback}{HTML}{FBF3EA}
-\definecolor{explicorule}{HTML}{8A9A93}
 
 %% --- Floats, tables and captions -------------------------------------------
-\RequirePackage{graphicx}
-\RequirePackage{array,booktabs,tabularx,longtable}
-\RequirePackage[export]{adjustbox}
+\RequirePackage{longtable}
 \RequirePackage{caption}
 \RequirePackage{newfloat}
 \DeclareFloatingEnvironment[
@@ -155,105 +94,10 @@
     \captionsetup{type=#1}%
   }{\end{minipage}\par\medskip}
 \fi
-%% explico's short caption, run in bold before the long one.
-\newcommand*{\ExplicoCaptionTitle}[1]{\textbf{#1}}
-
-%% --- Diagrams ---------------------------------------------------------------
-\RequirePackage{tikz}
-\usetikzlibrary{arrows.meta}
-\tikzset{
-  explico diagram node/.style={
-    draw=explicorule, fill=explicoback, rounded corners=3pt, line width=0.5pt,
-    align=center, inner sep=3pt, font=\small,
-  },
-  explico diagram edge/.style={
-    draw=explicorule, line width=0.6pt, -{Stealth[length=5pt,width=4pt]},
-  },
-}
 
-%% --- Boxes: memos, notes, asides, worked examples, checks ------------------
-\RequirePackage[most]{tcolorbox}
-\tcbset{
-  explico/.style={
-    enhanced, breakable, colback=explicoback, colframe=explicoframe,
-    boxrule=0.5pt, arc=2pt, left=6pt, right=6pt, top=4pt, bottom=4pt,
-    fonttitle=\bfseries\small, coltitle=black, colbacktitle=explicoback!60!white,
-    titlerule=0.4pt, before skip=10pt plus 2pt, after skip=10pt plus 2pt,
-  },
-}
 \RequirePackage{alphalph}
 \RequirePackage{enumitem}
 
-%% --- Unicode in text that the default fonts lack ---------------------------
-\RequirePackage{newunicodechar}
-\newunicodechar{°}{\ifmmode^\circ\else\textdegree\fi}
-\newunicodechar{−}{\ensuremath{-}}
-\newunicodechar{×}{\ensuremath{\times}}
-\newunicodechar{±}{\ensuremath{\pm}}
-\newunicodechar{≤}{\ensuremath{\le}}
-\newunicodechar{≥}{\ensuremath{\ge}}
-\newunicodechar{≈}{\ensuremath{\approx}}
-\newunicodechar{≠}{\ensuremath{\neq}}
-\newunicodechar{→}{\ensuremath{\rightarrow}}
-\newunicodechar{←}{\ensuremath{\leftarrow}}
-\newunicodechar{↑}{\ensuremath{\uparrow}}
-\newunicodechar{↓}{\ensuremath{\downarrow}}
-\newunicodechar{⟨}{\ensuremath{\langle}}
-\newunicodechar{⟩}{\ensuremath{\rangle}}
-\newunicodechar{⋮}{\ensuremath{\vdots}}
-\newunicodechar{√}{\ensuremath{\surd}}
-\newunicodechar{∞}{\ensuremath{\infty}}
-\newunicodechar{′}{\ensuremath{'}}
-\newunicodechar{𝒩}{\ensuremath{\mathcal{N}}}
-\newunicodechar{①}{\textcircled{\scriptsize 1}}
-\newunicodechar{②}{\textcircled{\scriptsize 2}}
-\newunicodechar{③}{\textcircled{\scriptsize 3}}
-\newunicodechar{④}{\textcircled{\scriptsize 4}}
-\newunicodechar{⑤}{\textcircled{\scriptsize 5}}
-\newunicodechar{₀}{\textsubscript{0}}
-\newunicodechar{₁}{\textsubscript{1}}
-\newunicodechar{₂}{\textsubscript{2}}
-\newunicodechar{₃}{\textsubscript{3}}
-\newunicodechar{¹}{\textsuperscript{1}}
-\newunicodechar{²}{\textsuperscript{2}}
-\newunicodechar{³}{\textsuperscript{3}}
-%% A Greek letter on its own is a symbol (the polar coordinates ρ and φ in a
-%% caption, which holds no math): it is set as its math symbol. Inside a Greek
-%% word, which the exporter marks \ExplicoGreekWord{…}, it is a letter, set
-%% from the text font's Greek where one is loaded (`scripts`).
-\newif\ifexplico@word
-\DeclareRobustCommand{\ExplicoGreekWord}[1]{{\explico@wordtrue#1}}
-%% Protected, as \ensuremath is: the text of an equation is expanded for its
-%% tagging (alt text, MathML), and an expandable body breaks it there.
-\protected\def\explico@greekletter#1#2{%
-  \ifmmode#2\else
-    \ifexplico@word
-      \ifexplico@greek\char#1\relax\else\ensuremath{#2}\fi
-    \else\ensuremath{#2}\fi
-  \fi}
-\newunicodechar{α}{\explico@greekletter{"03B1}{\alpha}}
-\newunicodechar{β}{\explico@greekletter{"03B2}{\beta}}
-\newunicodechar{γ}{\explico@greekletter{"03B3}{\gamma}}
-\newunicodechar{δ}{\explico@greekletter{"03B4}{\delta}}
-\newunicodechar{ε}{\explico@greekletter{"03B5}{\varepsilon}}
-\newunicodechar{θ}{\explico@greekletter{"03B8}{\theta}}
-\newunicodechar{λ}{\explico@greekletter{"03BB}{\lambda}}
-\newunicodechar{μ}{\explico@greekletter{"03BC}{\mu}}
-\newunicodechar{π}{\explico@greekletter{"03C0}{\pi}}
-\newunicodechar{ρ}{\explico@greekletter{"03C1}{\rho}}
-\newunicodechar{σ}{\explico@greekletter{"03C3}{\sigma}}
-\newunicodechar{τ}{\explico@greekletter{"03C4}{\tau}}
-\newunicodechar{φ}{\explico@greekletter{"03C6}{\varphi}}
-\newunicodechar{ω}{\explico@greekletter{"03C9}{\omega}}
-\newunicodechar{Γ}{\explico@greekletter{"0393}{\Gamma}}
-\newunicodechar{Δ}{\explico@greekletter{"0394}{\Delta}}
-\newunicodechar{Θ}{\explico@greekletter{"0398}{\Theta}}
-\newunicodechar{Λ}{\explico@greekletter{"039B}{\Lambda}}
-\newunicodechar{Π}{\explico@greekletter{"03A0}{\Pi}}
-\newunicodechar{Σ}{\explico@greekletter{"03A3}{\Sigma}}
-\newunicodechar{Φ}{\explico@greekletter{"03A6}{\Phi}}
-\newunicodechar{Ω}{\explico@greekletter{"03A9}{\Omega}}
-
 %% --- Links ------------------------------------------------------------------
 \RequirePackage[colorlinks,linkcolor=explicoaccent,urlcolor=explicoaccent,citecolor=explicoaccent,bookmarksnumbered]{hyperref}
 \pdfstringdefDisableCommands{\let\ExplicoGreekWord\@firstofone}
@@ -309,18 +153,20 @@
 }
 
 %% --- Chapter front line -----------------------------------------------------
-%% Under a chapter's title: where it comes from and where its live version is.
+%% Under a chapter's title: where it comes from, the version its content is at
+%% (#2, "unchanged since version 0.2.0") and where its live version is.
 \newcommand{\ExplicoSource}[3]{%
   \begingroup\small\color{black!65}%
   \noindent From \emph{#1}%
-  \if\relax\detokenize{#2}\relax\else, version~#2\fi.%
+  \if\relax\detokenize{#2}\relax\else, #2\fi.%
   \if\relax\detokenize{#3}\relax\else\ Interactive version: \url{#3}\fi
   \par\endgroup\medskip
 }
 
 %% --- Books: a part's or the course's PDF ------------------------------------
 %% The title page. #1 title, #2 what it belongs to (empty for the course),
-%% #3 content version, #4 authors, #5 website.
+%% #3 the version the content is at ("unchanged since version 0.2.0"),
+%% #4 authors, #5 website.
 \newcommand{\ExplicoTitlePage}[5]{%
   %% The title page shares page number i with the contents: no anchor of its own.
   \hypersetup{pageanchor=false}%
@@ -331,7 +177,7 @@
     \if\relax\detokenize{#2}\relax\else\vspace{0.8em}{\Large #2\par}\fi
     \if\relax\detokenize{#4}\relax\else\vspace{2.5em}{\large #4\par}\fi
     \vfill
-    {Content version~#3\par}
+    {Content #3\par}
     \if\relax\detokenize{#5}\relax\else\vspace{0.4em}{\small\url{#5}\par}\fi
   \end{titlepage}%
   \hypersetup{pageanchor=true}%
@@ -345,22 +191,6 @@
 %% A part opens on its own page, numbered as on the website.
 \newcommand{\ExplicoPart}[2]{\setcounter{part}{\numexpr#1-1\relax}\part{#2}}
 
-%% --- Notation ---------------------------------------------------------------
-%% \explain{key}{tex} and \slot{key}{tex} are explico's markers in math: the
-%% website opens a card for the key; on paper they print their content.
-\providecommand{\explain}[2]{#2}
-\providecommand{\slot}[2]{#2}
-%% \ExplicoNotation{target}{tex}: a formula's symbol that links to its notation entry
-%% (the serializer writes it only where the book has that entry).
-\providecommand{\ExplicoNotation}[2]{\hyperlink{#1}{#2}}
-%% A term in prose with a notation card on the website.
-\newcommand{\ExplicoTerm}[2]{#2}
-
-%% --- Cross-references ---------------------------------------------------------
-%% #1 label, #2 text before the number, #3 text after it.
-\newcommand{\ExplicoRef}[3]{\hyperref[#1]{#2\ref*{#1}#3}}
-\newcommand{\ExplicoEqRef}[1]{\hyperref[#1]{(\ref*{#1})}}
-
 %% --- Memos --------------------------------------------------------------------
 \newenvironment{ExplicoMemo}[1]{%
   \refstepcounter{explicomemo}%

package/dist/compiler/exports/latex/serialize.d.ts

@@ -1,5 +1,5 @@
 import { ContentSegment } from '../../../reference/mixed-content.js';
-import { NotationEntry, StaticPage, DiagramGeometry, Inline } from '../static-tree.js';
+import { StaticPage, NotationEntry, Inline, CourseTarget, FigurePicture, Block, DiagramGeometry } from '../static-tree.js';
 import '../../../reference/gate-math.js';
 import '../../../reference/types.js';
 import '../html-tree.js';
@@ -23,10 +23,13 @@ interface ChapterContext {
     readonly pictures: ReadonlyMap<string, string>;
     /** Answers of this chapter's checks, by assessment id, in authored order. */
     readonly checkItems: ReadonlyMap<string, readonly CheckItem[]>;
-    /** Course title, version and the chapter's live URL for the front line. */
+    /**
+     * The front line under the title: the course, the version the chapter's
+     * content is at (`versionPhrase`, rule C5) and its live URL.
+     */
     readonly source?: {
         readonly course: string;
-        readonly version?: string;
+        readonly since?: string;
         readonly url?: string;
     };
     /**
@@ -64,6 +67,8 @@ interface CheckItem {
 /** A LaTeX label for an anchor on a page: unique across a whole book. */
 declare function labelOf(route: string, anchor: string): string;
 declare function escapeText(text: string): string;
+/** A URL as `\url` and `\href` take it: no braces or backslashes, `%` and `#` escaped. */
+declare function escapeUrl(url: string): string;
 /**
  * Rewrites each `\explain{key}{tex}` whose key `linkTo` names as
  * `\ExplicoNotation{target}{tex}`, a link to the notation entry; any other
@@ -73,6 +78,57 @@ declare function escapeText(text: string): string;
  * inside it print their TeX.
  */
 declare function linkExplains(tex: string, linkTo: (key: string) => string | undefined): string;
+declare class ChapterWriter {
+    protected readonly context: ChapterContext;
+    private readonly route;
+    private readonly citationKeys;
+    /** Above zero inside a moving argument (a heading, a caption, a title) or a link: no link goes there. */
+    private unlinked;
+    constructor(context: ChapterContext);
+    /** A reference-list entry's citation key in this document, by its anchor. */
+    protected citeKey(anchor: string): string;
+    label(anchor: string): string;
+    /** Renders `write` with links to notation off: a link cannot nest, or sit in a moving argument. */
+    protected unlinkedWhile<T>(write: () => T): T;
+    /** Inline content with no notation links inside it. */
+    protected plain(inlines: readonly Inline[]): string;
+    /** A formula's TeX, with its notation markers linked to the appendix where the document has the entry. */
+    protected math(tex: string): string;
+    protected inDocument(target: CourseTarget): boolean;
+    protected canonicalUrl(target: CourseTarget): string | undefined;
+    /** A cross-reference: LaTeX's number inside the document, the website's outside it. */
+    protected reference(refKind: string, target: CourseTarget, children: readonly Inline[]): string;
+    inline(inline: Inline): string;
+    inlines(inlines: readonly Inline[]): string;
+    protected segments(segments: readonly ContentSegment[]): string;
+    /** A float's caption: its short caption for the lists, bold before the long one. */
+    protected caption(block: {
+        short?: string;
+        caption: readonly Inline[];
+        anchor: string;
+    }, extra?: readonly Inline[]): string;
+    /**
+     * A float. Inside a box (a memo, a worked example) a float cannot float, so
+     * it is set where it stands (`ExplicoHere`, explico.cls) and keeps its number.
+     */
+    protected float(kind: string, inPlace: boolean, content: string, caption: string, captionFirst?: boolean): string;
+    protected picture(anchor: string, picture: FigurePicture, alt: string): string;
+    protected table(block: Extract<Block, {
+        kind: 'table';
+    }>, inBox?: boolean): string;
+    /** A choice's label, its math typeset like the prompt's. */
+    protected optionLabel(option: NonNullable<CheckItem['options']>[number]): string;
+    protected check(block: Extract<Block, {
+        kind: 'check';
+    }>): string;
+    /** The chapter's answer key: every check's answers and explanations, in order. */
+    answers(checks: readonly Extract<Block, {
+        kind: 'check';
+    }>[]): string;
+    block(block: Block, inBox?: boolean): string;
+    blocks(blocks: readonly Block[], inBox?: boolean): string;
+    notation(entries: readonly NotationEntry[], remarks: readonly (readonly Inline[])[]): string;
+}
 /**
  * explico's `<Diagram>` in TikZ, from the layout Dagre gave it at build time:
  * the same boxes and edges as the website, with LaTeX setting the text and the
@@ -109,4 +165,4 @@ declare function serializeAbbreviationAppendix(abbreviations: readonly {
     readonly expansion: string;
 }[]): string;
 
-export { type AppendixNotation, type ChapterContext, type CheckItem, diagramTikz, escapeText, labelOf, linkExplains, serializeAbbreviationAppendix, serializeChapter, serializeNotationAppendix, serializePartOpener };
+export { type AppendixNotation, type ChapterContext, ChapterWriter, type CheckItem, diagramTikz, escapeText, escapeUrl, labelOf, linkExplains, serializeAbbreviationAppendix, serializeChapter, serializeNotationAppendix, serializePartOpener };

package/dist/compiler/exports/latex/serialize.js

@@ -1,4 +1,4 @@
-import { captionTitle } from "../../../components/float-name.js";
+import { captionTitle } from "../../../reference/float-name.js";
 function labelOf(route, anchor) {
   return `${route}/${anchor}`;
 }
@@ -530,7 +530,7 @@ function serializeChapter(context) {
   collect(page.blocks);
   const source = context.source;
   const sourceLine = !source ? [] : context.inBook ? source.url ? [`\\ExplicoInteractive{${escapeUrl(source.url)}}`] : [] : [
-    `\\ExplicoSource{${escapeText(source.course)}}{${escapeText(source.version ?? "")}}{${source.url ? escapeUrl(source.url) : ""}}`
+    `\\ExplicoSource{${escapeText(source.course)}}{${escapeText(source.since ?? "")}}{${source.url ? escapeUrl(source.url) : ""}}`
   ];
   return [
     `\\chapter{${escapeText(page.title)}}\\label{${labelOf(page.route, "_top")}}`,
@@ -595,8 +595,10 @@ function serializeAbbreviationAppendix(abbreviations) {
   ].join("\n");
 }
 export {
+  ChapterWriter,
   diagramTikz,
   escapeText,
+  escapeUrl,
   labelOf,
   linkExplains,
   serializeAbbreviationAppendix,

package/dist/compiler/exports/latex-export.d.ts

@@ -1,8 +1,9 @@
 import { Manifest } from '../manifest.js';
 import { ExportLogger, PreparedChapters } from './export-chapters.js';
+import { SourceFile } from './latex/document.js';
 import '../../curriculum/validation.js';
 import '../../reference/consistency.js';
-import '../../course-config-rRtME5UV.js';
+import '../../course-config-BLtIdkei.js';
 import '../../rules/catalog.js';
 import '../../rules/course-rules.js';
 import '../collections.js';
@@ -24,12 +25,33 @@ import '../../reference/mixed-content.js';
 import '../../reference/gloss.js';
 import '../../rules/waivers.js';
 import '../knowledge-version.js';
+import '../page-versions.js';
+import '../decks.js';
+import '../../reference/decks-validate.js';
+import '../../reference/deck-source.js';
 import '../lesson-derivation.js';
 import './static-tree.js';
 import './html-tree.js';
 import 'parse5';
 import './latex/capture.js';
+import 'node:http';
+import './latex/serialize.js';
 
+/**
+ * `work` over every item, at most `limit` at a time, started in `order` (the
+ * items' indices, by default their own order); results in the items' order.
+ */
+declare function mapWithLimit<T, R>(items: readonly T[], limit: number, work: (item: T) => Promise<R>, order?: readonly number[]): Promise<R[]>;
+/**
+ * The order to start documents in: the course, then the parts, then the
+ * chapters, the largest folder first within each. The course takes longest
+ * and is the one document a cache never reuses after a change; started last,
+ * it ran alone at the end while the other cores had nothing left to do.
+ */
+declare function startOrder(jobs: readonly {
+    readonly kind: 'chapter' | 'deck' | 'part' | 'course';
+    readonly files: readonly SourceFile[];
+}[]): number[];
 /**
  * Write each chapter's, each part's and the course's LaTeX source zip and PDF
  * under `downloads/`, from the chapters `prepareChapters` read and drew (read
@@ -41,4 +63,4 @@ declare function writeLatexExports(directory: URL, manifest: Manifest, options?:
     readonly prepared?: PreparedChapters;
 }): Promise<void>;
 
-export { ExportLogger, writeLatexExports };
+export { ExportLogger, mapWithLimit, startOrder, writeLatexExports };