explico 0.13.0 → 0.14.0

package/src/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/src/compiler/exports/latex/serialize.ts

@@ -1,4 +1,4 @@
-import { captionTitle } from '../../../components/float-name';
+import { captionTitle } from '../../../reference/float-name';
 import type { ContentSegment } from '../../../reference/mixed-content';
 import type {
   Block,
@@ -30,8 +30,11 @@ export 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. */
-  readonly source?: { readonly course: string; readonly version?: string; readonly url?: string };
+  /**
+   * 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 since?: string; readonly url?: string };
   /**
    * A chapter of a part's or the course's book: its citation keys gain the
    * chapter (`projectiles/projectile-range/openstax`), since each chapter
@@ -95,7 +98,8 @@ export function escapeText(text: string): string {
     .replace(GREEK_WORD, (word) => `\\ExplicoGreekWord{${word}}`);
 }
 
-function escapeUrl(url: string): string {
+/** A URL as `\url` and `\href` take it: no braces or backslashes, `%` and `#` escaped. */
+export function escapeUrl(url: string): string {
   return url.replace(/[\\{}]/gu, '').replace(/[%#]/gu, (char) => `\\${char}`);
 }
 
@@ -237,19 +241,19 @@ export function linkExplains(tex: string, linkTo: (key: string) => string | unde
   }
 }
 
-class ChapterWriter {
+export class ChapterWriter {
   private readonly route: string;
   private readonly citationKeys: Map<string, string>;
   /** Above zero inside a moving argument (a heading, a caption, a title) or a link: no link goes there. */
   private unlinked = 0;
 
-  constructor(private readonly context: ChapterContext) {
+  constructor(protected readonly context: ChapterContext) {
     this.route = context.page.route;
     this.citationKeys = entryKeys(citationKeys(context.page.blocks));
   }
 
   /** A reference-list entry's citation key in this document, by its anchor. */
-  private citeKey(anchor: string): string {
+  protected citeKey(anchor: string): string {
     const key = this.citationKeys.get(anchor) ?? anchor;
     return this.context.inBook ? `${this.route}/${key}` : key;
   }
@@ -259,7 +263,7 @@ class ChapterWriter {
   }
 
   /** Renders `write` with links to notation off: a link cannot nest, or sit in a moving argument. */
-  private unlinkedWhile<T>(write: () => T): T {
+  protected unlinkedWhile<T>(write: () => T): T {
     this.unlinked++;
     try {
       return write();
@@ -269,22 +273,22 @@ class ChapterWriter {
   }
 
   /** Inline content with no notation links inside it. */
-  private plain(inlines: readonly Inline[]): string {
+  protected plain(inlines: readonly Inline[]): string {
     return this.unlinkedWhile(() => this.inlines(inlines));
   }
 
   /** A formula's TeX, with its notation markers linked to the appendix where the document has the entry. */
-  private math(tex: string): string {
+  protected math(tex: string): string {
     const targets = this.context.notationTargets;
     if (this.unlinked > 0 || !targets || targets.size === 0) return tex;
     return linkExplains(tex, (key) => (targets.has(key) ? labelOf('notation', key) : undefined));
   }
 
-  private inDocument(target: CourseTarget): boolean {
+  protected inDocument(target: CourseTarget): boolean {
     return this.context.documentRoutes.has(target.route);
   }
 
-  private canonicalUrl(target: CourseTarget): string | undefined {
+  protected canonicalUrl(target: CourseTarget): string | undefined {
     const base = this.context.canonicalBaseUrl;
     if (!base) return undefined;
     const path = target.route ? `${target.route}/` : '';
@@ -292,7 +296,7 @@ class ChapterWriter {
   }
 
   /** A cross-reference: LaTeX's number inside the document, the website's outside it. */
-  private reference(refKind: string, target: CourseTarget, children: readonly Inline[]): string {
+  protected reference(refKind: string, target: CourseTarget, children: readonly Inline[]): string {
     const text = plainText(children);
     if (this.inDocument(target) && target.anchor) {
       const label = labelOf(target.route, target.anchor);
@@ -352,14 +356,14 @@ class ChapterWriter {
     return inlines.map((inline) => this.inline(inline)).join('');
   }
 
-  private segments(segments: readonly ContentSegment[]): string {
+  protected segments(segments: readonly ContentSegment[]): string {
     return segments
       .map((segment) => (segment.type === 'math' ? `$${this.math(segment.latex)}$` : escapeText(segment.value)))
       .join('');
   }
 
   /** A float's caption: its short caption for the lists, bold before the long one. */
-  private caption(block: { short?: string; caption: readonly Inline[]; anchor: string }, extra: readonly Inline[] = []): string {
+  protected caption(block: { short?: string; caption: readonly Inline[]; anchor: string }, extra: readonly Inline[] = []): string {
     const short = block.short?.trim();
     const long = [this.plain(block.caption), this.plain(extra)].filter(Boolean).join(' ');
     const title = short ? `\\ExplicoCaptionTitle{${escapeText(captionTitle(short))}} ` : '';
@@ -371,13 +375,13 @@ class ChapterWriter {
    * 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.
    */
-  private float(kind: string, inPlace: boolean, content: string, caption: string, captionFirst = false): string {
+  protected float(kind: string, inPlace: boolean, content: string, caption: string, captionFirst = false): string {
     const parts = captionFirst ? [caption, content] : [content, caption];
     if (inPlace) return [`\\begin{ExplicoHere}{${kind}}`, ...parts, '\\end{ExplicoHere}'].join('\n');
     return [`\\begin{${kind}}[htbp]`, '\\centering', ...parts, `\\end{${kind}}`].join('\n');
   }
 
-  private picture(anchor: string, picture: FigurePicture, alt: string): string {
+  protected picture(anchor: string, picture: FigurePicture, alt: string): string {
     if (picture.kind === 'diagram') return diagramTikz(picture.geometry, this);
     const file = this.context.pictures.get(anchor);
     if (file) {
@@ -392,7 +396,7 @@ class ChapterWriter {
     )}: see the interactive version on the course website.}}`;
   }
 
-  private table(block: Extract<Block, { kind: 'table' }>, inBox = false): string {
+  protected table(block: Extract<Block, { kind: 'table' }>, inBox = false): string {
     const rows = [...block.head, ...block.body];
     const columns = Math.max(0, ...rows.map((row) => row.reduce((sum, cell) => sum + cell.colspan, 0)));
     if (columns === 0) return '';
@@ -454,11 +458,11 @@ class ChapterWriter {
   }
 
   /** A choice's label, its math typeset like the prompt's. */
-  private optionLabel(option: NonNullable<CheckItem['options']>[number]): string {
+  protected optionLabel(option: NonNullable<CheckItem['options']>[number]): string {
     return option.labelSegments ? this.segments(option.labelSegments) : escapeText(option.label);
   }
 
-  private check(block: Extract<Block, { kind: 'check' }>): string {
+  protected check(block: Extract<Block, { kind: 'check' }>): string {
     const items = this.context.checkItems.get(block.assessmentId) ?? [];
     const questions = items.map((item) => {
       const options =
@@ -688,7 +692,7 @@ export function serializeChapter(context: ChapterContext): string {
         ? [`\\ExplicoInteractive{${escapeUrl(source.url)}}`]
         : []
       : [
-          `\\ExplicoSource{${escapeText(source.course)}}{${escapeText(source.version ?? '')}}{${
+          `\\ExplicoSource{${escapeText(source.course)}}{${escapeText(source.since ?? '')}}{${
             source.url ? escapeUrl(source.url) : ''
           }}`,
         ];

package/src/compiler/exports/latex/texlive-packages.txt

@@ -1,7 +1,7 @@
 # TeX Live 2026 packages for explico's LaTeX export, for the package_file of
 # zauguin/install-texlive; tlmgr adds each one's dependencies. This is what a
-# chapter reads under LuaLaTeX and pdfLaTeX (latexmk -recorder), less what
-# latex-bin brings. Package names change between TeX Live years: check the
+# chapter and a deck read under LuaLaTeX and pdfLaTeX (latexmk -recorder),
+# less what latex-bin brings. Package names change between TeX Live years: check the
 # list again when moving texlive_version.
 
 # Engines, formats, build tool
@@ -41,6 +41,10 @@ tcolorbox
 unicode-math
 xcolor
 
+# beamerthemeexplico.sty: a deck's slides and handout
+beamer
+translator
+
 # What those load
 amscls
 bigintcalc