explico 0.13.1 → 0.15.0

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

@@ -1,7 +1,10 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { newestSince, versionPhrase } from "../../page-versions.js";
 import {
   escapeText,
+  escapeUrl,
+  labelOf,
   serializeAbbreviationAppendix,
   serializeChapter,
   serializeNotationAppendix,
@@ -10,6 +13,9 @@ import {
 function explicoClass() {
   return readFileSync(new URL("./explico.cls", import.meta.url), "utf8");
 }
+function explicoCommon() {
+  return readFileSync(new URL("./explico-common.sty", import.meta.url), "utf8");
+}
 function twoDigits(value) {
   return String(value).padStart(2, "0");
 }
@@ -32,6 +38,16 @@ function checkItems(manifest, lesson) {
   }
   return items;
 }
+function deckCheckItems(manifest, deck) {
+  const lessonIds = deck.lessonId !== void 0 ? [deck.lessonId] : deck.covers.map((cover) => cover.chapter.replace(/\//g, "."));
+  const items = /* @__PURE__ */ new Map();
+  for (const id of lessonIds) {
+    for (const [assessment, list] of checkItems(manifest, { id })) {
+      if (!items.has(assessment)) items.set(assessment, list);
+    }
+  }
+  return items;
+}
 const DOCUMENT_METADATA = [
   "% A fixed seed for TeX's random numbers, before tagging loads: tagpdf names",
   "% one of its structure namespaces with random digits, and the same source",
@@ -45,11 +61,19 @@ const DOCUMENT_METADATA = [
   "  \\DocumentMetadata{lang=en,pdfversion=2.0,tagging=on}",
   "\\fi"
 ];
-function trailerId(manifest, document) {
+function trailerId(manifest, document, since) {
   return createHash("md5").update(`${manifest.about.material.name}
-${manifest.about.knowledge.version}
+${versionPhrase(since, manifest.about.knowledge.version)}
 ${document}`).digest("hex").toUpperCase();
 }
+function bookSince(parts) {
+  return newestSince(
+    parts.flatMap(({ part, chapters }) => [
+      ...part.overview ? [part.overview.since] : [],
+      ...chapters.map(({ lesson }) => lesson.since)
+    ])
+  );
+}
 function trailerIdLine(id) {
   return `\\ifdefined\\directlua\\pdfvariable trailerid {[<${id}><${id}>]}\\else\\pdftrailerid{${id}}\\fi`;
 }
@@ -64,7 +88,7 @@ function mainTex(manifest, lesson, chapterFile) {
     ...DOCUMENT_METADATA,
     `\\documentclass[${paper}]{explico}`,
     "% The same identifier for every compile of this source.",
-    trailerIdLine(trailerId(manifest, lesson.slug)),
+    trailerIdLine(trailerId(manifest, lesson.slug, lesson.since)),
     ...numbering.floats === "part" ? ["\\ExplicoFloatsByPart"] : [],
     `\\ExplicoSectionDepth{${numbering.sections.show ? numbering.sections.depth : 1}}`,
     `\\hypersetup{pdftitle={${escapeText(lesson.title)}},pdfauthor={${escapeText(
@@ -91,7 +115,7 @@ function readme(manifest, lesson, url) {
   return [
     `# ${lesson.title}`,
     "",
-    `The LaTeX source of a chapter of *${course}* (content version ${manifest.about.knowledge.version}).` + (url ? ` Interactive version: ${url}` : ""),
+    `The LaTeX source of a chapter of *${course}* (${versionPhrase(lesson.since, manifest.about.knowledge.version)}).` + (url ? ` Interactive version: ${url}` : ""),
     "",
     "## Build",
     "",
@@ -110,6 +134,8 @@ function readme(manifest, lesson, url) {
     "- `main.tex` \u2014 the document: class options, then the chapter.",
     "- `explico.cls` \u2014 explico's book class: layout, numbering, and the",
     "  environments the chapter uses (memos, notes, worked examples, checks).",
+    "- `explico-common.sty` \u2014 what the class shares with explico's slides: fonts,",
+    "  colours, figures, diagrams and the notation markers.",
     `- \`${chapterPath(manifest, lesson)}\` \u2014 the chapter.`,
     "- `figures/` \u2014 the chapter's figures, as vector PDF where the website draws them.",
     "",
@@ -131,7 +157,7 @@ function chapterSource(input) {
     checkItems: checkItems(manifest, lesson),
     source: {
       course: manifest.about.material.name,
-      version: manifest.about.knowledge.version,
+      since: versionPhrase(lesson.since, manifest.about.knowledge.version),
       ...url ? { url } : {}
     }
   });
@@ -140,21 +166,36 @@ function chapterSource(input) {
     { path: "latexmkrc", content: LATEXMKRC },
     { path: "main.tex", content: mainTex(manifest, lesson, file) },
     { path: "explico.cls", content: explicoClass() },
+    { path: "explico-common.sty", content: explicoCommon() },
     { path: file, content: chapter },
     ...[...input.pictures.values()].map((picture) => ({ path: picture.path, content: picture.content }))
   ]);
 }
 const OTHER_SCRIPTS = /[\u0370-\u03FF\u0400-\u04FF\u1F00-\u1FFF\u2E80-\u9FFF\uAC00-\uD7AF\uF900-\uFAFF\uFF00-\uFFEF\u2600-\u27BF\u{1F000}-\u{1FAFF}]/u;
 const MATH_GREEK = /[αβγδεθλμπρστφωΓΔΘΛΠΣΦΩ]/gu;
+function needsScripts(tex) {
+  return tex.includes("\\ExplicoGreekWord{") || OTHER_SCRIPTS.test(tex.replace(MATH_GREEK, ""));
+}
 function withScripts(files) {
   const needed = files.some(
-    (file) => file.path.endsWith(".tex") && typeof file.content === "string" && (file.content.includes("\\ExplicoGreekWord{") || OTHER_SCRIPTS.test(file.content.replace(MATH_GREEK, "")))
+    (file) => file.path.endsWith(".tex") && typeof file.content === "string" && needsScripts(file.content)
   );
   if (!needed) return files;
   return files.map(
     (file) => file.path === "main.tex" && typeof file.content === "string" ? { ...file, content: file.content.replace(/\\documentclass\[([^\]]*)\]\{explico\}/u, "\\documentclass[$1,scripts]{explico}") } : file
   );
 }
+function slidesChapter(entry) {
+  const checks = entry.lesson.assessments.length;
+  return [
+    `\\chapter{${escapeText(entry.lesson.title)}}\\label{${labelOf(entry.lesson.slug, "_top")}}`,
+    `This lesson is taught as slides${entry.slidesUrl ? `: \\url{${escapeUrl(entry.slidesUrl)}}` : ""}.` + (checks > 0 ? ` Its knowledge check${checks === 1 ? " is" : "s are"} on its slides.` : ""),
+    ...entry.outcomes.length > 0 ? ["", "After it, you can:", "\\begin{itemize}", ...entry.outcomes.map((outcome) => `\\item ${escapeText(outcome)}`), "\\end{itemize}"] : [],
+    // Its checks keep their numbers, so the chapters after it keep theirs.
+    ...checks > 0 ? [`\\addtocounter{explicocheck}{${checks}}`] : [],
+    ""
+  ].join("\n");
+}
 function countNumbered(parts, kind) {
   let count = 0;
   const visit = (blocks) => {
@@ -210,7 +251,7 @@ function bookMainTex(input, inputs, appendices) {
     ...DOCUMENT_METADATA,
     `\\documentclass[${paper}]{explico}`,
     "% The same identifier for every compile of this source.",
-    trailerIdLine(trailerId(manifest, input.document)),
+    trailerIdLine(trailerId(manifest, input.document, bookSince(input.parts))),
     ...numbering.floats === "part" ? ["\\ExplicoFloatsByPart"] : [],
     `\\ExplicoSectionDepth{${numbering.sections.show ? numbering.sections.depth : 1}}`,
     "% The contents list parts, chapters and sections.",
@@ -221,7 +262,7 @@ function bookMainTex(input, inputs, appendices) {
     "\\begin{document}",
     "\\frontmatter",
     `\\ExplicoTitlePage{${escapeText(input.title)}}{${escapeText(input.subtitle ?? "")}}{${escapeText(
-      manifest.about.knowledge.version
+      versionPhrase(bookSince(input.parts), manifest.about.knowledge.version)
     )}}{${escapeText(authors.join(", "))}}{${url ? url.replace(/[\\{}]/gu, "").replace(/[%#]/gu, (char) => `\\${char}`) : ""}}`,
     "% The contents and lists in black, as a book sets them; links in the text keep their colour.",
     "\\begingroup\\hypersetup{linkcolor=black}",
@@ -241,7 +282,7 @@ function bookReadme(input) {
   return [
     `# ${input.title}`,
     "",
-    `The LaTeX source of ${input.subtitle ? `${input.subtitle.replace(/^Part/u, "part")}` : `*${manifest.about.material.name}*`} (content version ${manifest.about.knowledge.version}).` + (url ? ` Interactive version: ${url}` : ""),
+    `The LaTeX source of ${input.subtitle ? `${input.subtitle.replace(/^Part/u, "part")}` : `*${manifest.about.material.name}*`} (${versionPhrase(bookSince(input.parts), manifest.about.knowledge.version)}).` + (url ? ` Interactive version: ${url}` : ""),
     "",
     "## Build",
     "",
@@ -261,6 +302,8 @@ function bookReadme(input) {
     "  diagrams, then each part and its chapters, then the appendices.",
     "- `explico.cls` \u2014 explico's book class: layout, numbering, and the",
     "  environments the chapters use (memos, notes, worked examples, checks).",
+    "- `explico-common.sty` \u2014 what the class shares with explico's slides: fonts,",
+    "  colours, figures, diagrams and the notation markers.",
     "- `parts/NN-<part>.tex` \u2014 a part's opening page and text;",
     "  `parts/NN-<part>/MM-<chapter>.tex` \u2014 its chapters.",
     "- `backmatter/` \u2014 the notation and abbreviation appendices.",
@@ -275,7 +318,6 @@ function bookSource(input) {
   const { manifest, parts } = input;
   const canonicalBaseUrl = manifest.lessonExports.canonicalBaseUrl;
   const course = manifest.about.material.name;
-  const version = manifest.about.knowledge.version;
   const documentRoutes = new Set(
     parts.flatMap(({ overview, chapters }) => [
       ...overview ? [overview.route] : [],
@@ -286,7 +328,7 @@ function bookSource(input) {
   const common = { documentRoutes, canonicalBaseUrl, inBook: true, notationTargets };
   const files = [];
   const inputs = [];
-  for (const { part, overview, chapters } of parts) {
+  for (const { part, overview, chapters, slides = [] } of parts) {
     const partFile = `parts/${twoDigits(part.ordinal)}-${part.dir}.tex`;
     files.push({
       path: partFile,
@@ -294,7 +336,17 @@ function bookSource(input) {
 `
     });
     inputs.push(partFile);
+    const pending = [...slides].sort((a, b) => a.lesson.chapter - b.lesson.chapter);
+    const writeSlides = (before) => {
+      while (pending.length > 0 && pending[0].lesson.chapter < before) {
+        const entry = pending.shift();
+        const file = chapterPath(manifest, entry.lesson);
+        files.push({ path: file, content: slidesChapter(entry) });
+        inputs.push(file);
+      }
+    };
     for (const { lesson, page, pictures } of chapters) {
+      writeSlides(lesson.chapter);
       const file = chapterPath(manifest, lesson);
       const url = canonicalBaseUrl ? `${canonicalBaseUrl}${lesson.slug}/` : void 0;
       files.push({
@@ -304,12 +356,14 @@ function bookSource(input) {
           page,
           pictures: new Map([...pictures].map(([anchor, picture]) => [anchor, picture.path])),
           checkItems: checkItems(manifest, lesson),
-          source: { course, version, ...url ? { url } : {} }
+          // In a book the line is the URL alone; the title page carries the version.
+          source: { course, ...url ? { url } : {} }
         })
       });
       inputs.push(file);
       files.push(...[...pictures.values()].map((picture) => ({ path: picture.path, content: picture.content })));
     }
+    writeSlides(Number.POSITIVE_INFINITY);
   }
   const appendices = [];
   const notation = serializeNotationAppendix(appendixNotation(manifest, parts), {
@@ -335,15 +389,20 @@ function bookSource(input) {
     { path: "latexmkrc", content: LATEXMKRC },
     { path: "main.tex", content: bookMainTex(input, inputs, appendices) },
     { path: "explico.cls", content: explicoClass() },
+    { path: "explico-common.sty", content: explicoCommon() },
     ...files
   ]);
 }
 export {
+  bookSince,
   bookSource,
   chapterFolderName,
   chapterPath,
   chapterSource,
   checkItems,
+  deckCheckItems,
   explicoClass,
+  explicoCommon,
+  needsScripts,
   trailerId
 };

package/dist/compiler/exports/latex/explico-common.sty

@@ -0,0 +1,198 @@
+%% explico-common.sty — what every LaTeX document explico writes shares: its
+%% book class (`explico.cls`) and its deck theme (`beamerthemeexplico.sty`).
+%%
+%% The engine, the fonts and the Unicode characters, the colours, the
+%% figures and tables, the TikZ styles of a diagram, the box style, the
+%% notation markers (\explain, \slot) and the cross-references. Edit it
+%% freely in a download.
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{explico-common}[2026/10/10 explico shared definitions]
+
+%% `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}
+\ProcessOptions\relax
+
+%% --- 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}
+
+%% --- Page and colour --------------------------------------------------------
+\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}
+\RequirePackage[export]{adjustbox}
+%% 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,
+  },
+}
+
+%% --- 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}}
+
+%% --- 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})}}
+
+\endinput