explico 0.12.0 → 0.13.1

package/src/compiler/exports/latex/compile.ts

@@ -0,0 +1,168 @@
+import { spawn } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import type { SourceFile } from './document';
+
+/**
+ * Compile a LaTeX folder to PDF with `latexmk`. LuaLaTeX is the engine: it
+ * is the one the LaTeX Project recommends for new documents and the only one
+ * that writes MathML into a tagged PDF. `EXPLICO_LATEX_ENGINE=pdflatex`
+ * switches to pdfLaTeX, for a machine whose TeX Live lacks LuaLaTeX's font
+ * loader.
+ */
+
+export interface LatexEngine {
+  readonly name: 'lualatex' | 'pdflatex';
+  readonly latexmkOption: '-lualatex' | '-pdf';
+}
+
+export interface CompiledLatex {
+  readonly pdf: Buffer;
+  readonly aux: string;
+  readonly log: string;
+}
+
+interface RunResult {
+  readonly code: number | null;
+  readonly output: string;
+}
+
+function run(command: string, args: readonly string[], options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}): Promise<RunResult> {
+  return new Promise((resolveRun) => {
+    let output = '';
+    let child;
+    try {
+      child = spawn(command, args, { cwd: options.cwd, env: options.env ?? process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch {
+      resolveRun({ code: null, output: '' });
+      return;
+    }
+    const capture = (chunk: Buffer) => {
+      if (output.length < 200_000) output += chunk.toString('utf8');
+    };
+    child.stdout.on('data', capture);
+    child.stderr.on('data', capture);
+    child.once('error', () => resolveRun({ code: null, output }));
+    child.once('close', (code) => resolveRun({ code, output }));
+  });
+}
+
+/**
+ * The engine to compile with, or the reason there is none. LuaLaTeX also
+ * needs `luaotfload` (Debian ships it separately, in `texlive-luatex`).
+ */
+export async function findLatexEngine(): Promise<LatexEngine | { readonly missing: string }> {
+  const requested = process.env.EXPLICO_LATEX_ENGINE ?? 'lualatex';
+  if (requested !== 'lualatex' && requested !== 'pdflatex') {
+    return { missing: `EXPLICO_LATEX_ENGINE must be "lualatex" or "pdflatex", not ${JSON.stringify(requested)}.` };
+  }
+  if ((await run('latexmk', ['-v'])).code !== 0) {
+    return { missing: 'latexmk is not installed (TeX Live 2025 or later provides it).' };
+  }
+  if ((await run(requested, ['--version'])).code !== 0) {
+    return { missing: `${requested} is not installed.` };
+  }
+  if (requested === 'lualatex') {
+    const loader = await run('kpsewhich', ['luaotfload.sty']);
+    if (loader.code !== 0 || !loader.output.trim()) {
+      return {
+        missing:
+          'LuaLaTeX cannot load fonts: luaotfload is missing (on Debian or Ubuntu, install texlive-luatex). ' +
+          'Set EXPLICO_LATEX_ENGINE=pdflatex to compile with pdfLaTeX instead.',
+      };
+    }
+  }
+  return requested === 'lualatex'
+    ? { name: 'lualatex', latexmkOption: '-lualatex' }
+    : { name: 'pdflatex', latexmkOption: '-pdf' };
+}
+
+/**
+ * The last LaTeX errors of a log, with their file and line. A Lua error
+ * (`[\directlua]:1: …`, `….lua:12: …`) carries no TeX file and line.
+ */
+function latexErrors(log: string): string {
+  const lines = log.split('\n');
+  const found: string[] = [];
+  lines.forEach((line, index) => {
+    if (/^(?:\.\/[^:]+:\d+: |! |\[\\directlua\]:\d+: |\S+\.lua:\d+: )/u.test(line)) {
+      found.push([line, lines[index + 1] ?? ''].join(' ').trim());
+    }
+  });
+  return found.slice(0, 6).join('\n  ');
+}
+
+/**
+ * The characters a compile could not draw, in first-seen order: LuaLaTeX
+ * leaves a blank where the font has no glyph and only logs `Missing
+ * character: There is no 中 (U+4E2D) in font …` — Greek, CJK or emoji in
+ * prose against Latin Modern. Each comes back once, as `中 (U+4E2D)`.
+ */
+export function missingCharacters(log: string): string[] {
+  const found = new Set<string>();
+  for (const match of log.matchAll(/Missing character: There is no (\S+) \((U\+[0-9A-F]+)\)/gu)) {
+    found.add(`${match[1]} (${match[2]})`);
+  }
+  return [...found];
+}
+
+/**
+ * Compile `files` (a folder with `main.tex`) and return the PDF with the
+ * `.aux` LaTeX wrote, for the numbering check. `epoch` fixes the PDF's dates
+ * so the same source gives the same file.
+ */
+export async function compileLatex(
+  files: readonly SourceFile[],
+  engine: LatexEngine,
+  options: { readonly epoch?: number; readonly name?: string } = {},
+): Promise<CompiledLatex> {
+  const root = await mkdtemp(join(tmpdir(), 'explico-latex-'));
+  try {
+    for (const file of files) {
+      const path = join(root, file.path);
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, file.content);
+    }
+    const result = await run(
+      'latexmk',
+      [
+        engine.latexmkOption,
+        '-interaction=nonstopmode',
+        '-halt-on-error',
+        '-file-line-error',
+        '-norc',
+        // luaotfload's caches are inputs latexmk tracks; the build's other
+        // compiles rewrite them meanwhile, and a compile that sees its inputs
+        // change on every run never settles ("needed too many passes").
+        '-e',
+        "$hash_calc_ignore_pattern{'luc'} = '^';",
+        'main.tex',
+      ],
+      {
+        cwd: root,
+        env: {
+          ...process.env,
+          SOURCE_DATE_EPOCH: String(options.epoch ?? 0),
+          FORCE_SOURCE_DATE: '1',
+        },
+      },
+    );
+    const log = await readFile(join(root, 'main.log'), 'utf8').catch(() => result.output);
+    if (result.code !== 0) {
+      // A failure latexmk reports itself (runs that never settle, a missing
+      // tool) leaves no error in the LaTeX log: say what latexmk said.
+      const errors = latexErrors(log);
+      const said = errors === '' ? `\n  latexmk: ${result.output.trim().split('\n').slice(-12).join('\n  ')}` : '';
+      throw new Error(`LaTeX could not compile ${options.name ?? 'the document'}:\n  ${errors || log.slice(-1500)}${said}`);
+    }
+    return {
+      pdf: await readFile(join(root, 'main.pdf')),
+      aux: await readFile(join(root, 'main.aux'), 'utf8'),
+      log,
+    };
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}

package/src/compiler/exports/latex/document.ts

@@ -0,0 +1,479 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+import type { Manifest, ManifestLesson, ManifestPart } from '../../manifest';
+import type { Block, StaticPage } from '../static-tree';
+import {
+  escapeText,
+  serializeAbbreviationAppendix,
+  serializeChapter,
+  serializeNotationAppendix,
+  serializePartOpener,
+  type AppendixNotation,
+  type CheckItem,
+} from './serialize';
+
+/**
+ * The LaTeX source of one chapter as a folder: what a reader unzips and what
+ * explico compiles to make the PDF it offers. Files are returned in memory,
+ * keyed by their path inside the folder, so the same tree feeds the zip and
+ * the compile.
+ */
+
+export interface SourceFile {
+  readonly path: string;
+  readonly content: string | Uint8Array;
+}
+
+/** explico's class, shipped next to this module (copied into `dist/` by `copy-assets`). */
+export function explicoClass(): string {
+  return readFileSync(new URL('./explico.cls', import.meta.url), 'utf8');
+}
+
+function twoDigits(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+/** `parts/02-projectiles/02-optimal-launch-angle.tex` for chapter 2.2. */
+export function chapterPath(manifest: Pick<Manifest, 'parts'>, lesson: ManifestLesson): string {
+  const part = manifest.parts.find((entry) => entry.ordinal === lesson.part);
+  const partDir = part?.dir ?? lesson.slug.split('/')[0] ?? 'part';
+  const name = lesson.slug.split('/').at(-1) ?? lesson.slug;
+  return `parts/${twoDigits(lesson.part)}-${partDir}/${twoDigits(lesson.chapter)}-${name}.tex`;
+}
+
+/** The folder name a chapter's download unzips to. */
+export function chapterFolderName(lesson: ManifestLesson): string {
+  return `${lesson.slug.split('/').at(-1) ?? lesson.slug}-latex`;
+}
+
+/** A chapter's check answers, by assessment id, in authored order. */
+export function checkItems(manifest: Pick<Manifest, 'assessmentContent'>, lesson: Pick<ManifestLesson, 'id'>): Map<string, CheckItem[]> {
+  const items = new Map<string, CheckItem[]>();
+  for (const item of manifest.assessmentContent) {
+    if (item.lessonId !== lesson.id) continue;
+    const list = items.get(item.assessmentId) ?? [];
+    list.push(item);
+    items.set(item.assessmentId, list);
+  }
+  return items;
+}
+
+/**
+ * The seed comes first: tagpdf names its "user" structure namespace with
+ * `\int_rand:n` digits as it loads, and TeX seeds its random numbers from
+ * the clock, so without it no two compiles of a source agree.
+ *
+ * LuaLaTeX writes a tagged PDF/UA-2 with MathML for every formula. pdfLaTeX
+ * tags less: no MathML, booktabs rules left untagged, and a box that breaks
+ * across pages opens its marked content on one page and closes it on the
+ * next (poppler: "Mismatched EMC operator"). So its PDF claims no standard.
+ */
+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',
+  '% should give the same PDF.',
+  '\\ExplSyntaxOn \\sys_gset_rand_seed:n { 1 } \\ExplSyntaxOff',
+  '% LuaLaTeX: a tagged, accessible PDF (PDF/UA-2) with MathML for every formula.',
+  '% pdfLaTeX tags it less completely, so it claims no standard.',
+  '\\ifdefined\\directlua',
+  '  \\DocumentMetadata{lang=en,pdfversion=2.0,pdfstandard=ua-2,tagging=on}',
+  '\\else',
+  '  \\DocumentMetadata{lang=en,pdfversion=2.0,tagging=on}',
+  '\\fi',
+];
+
+/**
+ * The PDF's file identifier (its trailer `/ID`), which the engines derive
+ * from the output file's path unless told: fixed from the course, its
+ * content version and the document, so every compile of a source agrees.
+ */
+export function trailerId(manifest: Pick<Manifest, 'about'>, document: string): string {
+  return createHash('md5')
+    .update(`${manifest.about.material.name}\n${manifest.about.knowledge.version}\n${document}`)
+    .digest('hex')
+    .toUpperCase();
+}
+
+function trailerIdLine(id: string): string {
+  return `\\ifdefined\\directlua\\pdfvariable trailerid {[<${id}><${id}>]}\\else\\pdftrailerid{${id}}\\fi`;
+}
+
+function mainTex(
+  manifest: Manifest,
+  lesson: ManifestLesson,
+  chapterFile: string,
+): string {
+  const paper = manifest.lessonExports.latexPaper === 'a4' ? 'a4paper' : 'letterpaper';
+  const { numbering } = manifest;
+  const offsets = lesson.numbering;
+  const course = manifest.about.material.name;
+  const authors = (manifest.about as { authors?: readonly { name?: string }[] }).authors
+    ?.map((author) => author.name)
+    .filter((name): name is string => !!name);
+  return [
+    '% Compile with `latexmk` (LuaLaTeX, see latexmkrc) or `latexmk -pdf` (pdfLaTeX).',
+    ...DOCUMENT_METADATA,
+    `\\documentclass[${paper}]{explico}`,
+    '% The same identifier for every compile of this source.',
+    trailerIdLine(trailerId(manifest, lesson.slug)),
+    ...(numbering.floats === 'part' ? ['\\ExplicoFloatsByPart'] : []),
+    `\\ExplicoSectionDepth{${numbering.sections.show ? numbering.sections.depth : 1}}`,
+    `\\hypersetup{pdftitle={${escapeText(lesson.title)}},pdfauthor={${escapeText(
+      authors && authors.length > 0 ? authors.join(', ') : course,
+    )}},pdfsubject={${escapeText(course)}}}`,
+    '\\begin{document}',
+    `\\ExplicoStartChapterAt{${lesson.part}}{${lesson.chapter}}{${offsets.equations}}{${offsets.tables}}{${offsets.figures}}{${offsets.diagrams}}{${offsets.checks}}{${offsets.examples}}`,
+    `\\input{${chapterFile.replace(/\.tex$/u, '')}}`,
+    '\\end{document}',
+    '',
+  ].join('\n');
+}
+
+const LATEXMKRC = [
+  '# LuaLaTeX by default; `latexmk -pdf` uses pdfLaTeX instead.',
+  '$pdf_mode = 4;',
+  '$postscript_mode = $dvi_mode = 0;',
+  "# luaotfload rewrites its font caches as fonts are looked up; they are not",
+  "# this document's sources, so a rewrite is no reason to run again.",
+  "$hash_calc_ignore_pattern{'luc'} = '^';",
+  '',
+].join('\n');
+
+function readme(manifest: Manifest, lesson: ManifestLesson, url: string | undefined): string {
+  const course = manifest.about.material.name;
+  return [
+    `# ${lesson.title}`,
+    '',
+    `The LaTeX source of a chapter of *${course}*` +
+      ` (content version ${manifest.about.knowledge.version}).` +
+      (url ? ` Interactive version: ${url}` : ''),
+    '',
+    '## Build',
+    '',
+    'Needs TeX Live 2025 or later.',
+    '',
+    '```sh',
+    'latexmk          # LuaLaTeX (preferred)',
+    'latexmk -pdf     # pdfLaTeX',
+    '```',
+    '',
+    'LuaLaTeX writes a tagged, accessible PDF (PDF/UA-2) with MathML for every',
+    'formula. pdfLaTeX tags it less completely and claims no standard.',
+    '',
+    '## Files',
+    '',
+    '- `main.tex` — the document: class options, then the chapter.',
+    '- `explico.cls` — explico\'s book class: layout, numbering, and the',
+    '  environments the chapter uses (memos, notes, worked examples, checks).',
+    `- \`${chapterPath(manifest, lesson)}\` — the chapter.`,
+    '- `figures/` — the chapter\'s figures, as vector PDF where the website draws them.',
+    '',
+    'Numbers are LaTeX\'s own and match the website when the source is built',
+    'unchanged; edit freely and they follow.',
+    '',
+  ].join('\n');
+}
+
+export interface ChapterSourceInput {
+  readonly manifest: Manifest;
+  readonly lesson: ManifestLesson;
+  readonly page: StaticPage;
+  /** Routes of every chapter in the document (just this one for a chapter download). */
+  readonly documentRoutes: ReadonlySet<string>;
+  /** Figure files already produced for this chapter, by float anchor, with their bytes. */
+  readonly pictures: ReadonlyMap<string, { readonly path: string; readonly content: Uint8Array }>;
+}
+
+/** Every file of one chapter's LaTeX folder. */
+export function chapterSource(input: ChapterSourceInput): SourceFile[] {
+  const { manifest, lesson, page } = input;
+  const file = chapterPath(manifest, lesson);
+  const base = manifest.lessonExports.canonicalBaseUrl;
+  const url = base ? `${base}${lesson.slug}/` : undefined;
+  const chapter = serializeChapter({
+    page,
+    documentRoutes: input.documentRoutes,
+    canonicalBaseUrl: base,
+    pictures: new Map([...input.pictures].map(([anchor, picture]) => [anchor, picture.path])),
+    checkItems: checkItems(manifest, lesson),
+    source: {
+      course: manifest.about.material.name,
+      version: manifest.about.knowledge.version,
+      ...(url ? { url } : {}),
+    },
+  });
+  return withScripts([
+    { path: 'README.md', content: readme(manifest, lesson, url) },
+    { path: 'latexmkrc', content: LATEXMKRC },
+    { path: 'main.tex', content: mainTex(manifest, lesson, file) },
+    { path: 'explico.cls', content: explicoClass() },
+    { path: file, content: chapter },
+    ...[...input.pictures.values()].map((picture) => ({ path: picture.path, content: picture.content })),
+  ]);
+}
+
+/**
+ * Greek, Cyrillic, Chinese, Japanese and Korean letters, and emoji: the
+ * characters Latin Modern lacks and the class's fallback fonts set.
+ */
+const OTHER_SCRIPTS =
+  /[\u0370-\u03FF\u0400-\u04FF\u1F00-\u1FFF\u2E80-\u9FFF\uAC00-\uD7AF\uF900-\uFAFF\uFF00-\uFFEF\u2600-\u27BF\u{1F000}-\u{1FAFF}]/u;
+
+/** The Greek letters explico.cls sets as math symbols when they stand alone. */
+const MATH_GREEK = /[αβγδεθλμπρστφωΓΔΘΛΠΣΦΩ]/gu;
+
+/**
+ * The document's files, with the class option `scripts` on `main.tex` when a
+ * `.tex` file holds a character of another script: the class then loads its
+ * fallback fonts under LuaLaTeX, which costs every compile that does not
+ * need them about two seconds.
+ */
+function withScripts(files: SourceFile[]): SourceFile[] {
+  // A Greek letter on its own is a symbol the class sets as math; a Greek
+  // word (`\ExplicoGreekWord`), an accented letter or another script needs a
+  // text font.
+  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, ''))),
+  );
+  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,
+  );
+}
+
+/** A chapter of a book, with its figure files. */
+export interface BookChapter {
+  readonly lesson: ManifestLesson;
+  readonly page: StaticPage;
+  readonly pictures: ReadonlyMap<string, { readonly path: string; readonly content: Uint8Array }>;
+}
+
+/** A part of a book: its own page, when it has one, and its chapters in order. */
+export interface BookPart {
+  readonly part: ManifestPart;
+  readonly overview?: StaticPage;
+  readonly chapters: readonly BookChapter[];
+}
+
+export interface BookSourceInput {
+  readonly manifest: Manifest;
+  readonly parts: readonly BookPart[];
+  /** What the book is (`part/projectiles`, `course`): it names the PDF's identifier. */
+  readonly document: string;
+  readonly title: string;
+  /** What the book belongs to, on its title page: `Part 2 of …` for a part. */
+  readonly subtitle?: string;
+}
+
+/** Every numbered block of a kind in a book, at any depth. */
+function countNumbered(parts: readonly BookPart[], kind: 'figure' | 'table' | 'diagram'): number {
+  let count = 0;
+  const visit = (blocks: readonly Block[]) => {
+    for (const block of blocks) {
+      if (block.kind === kind && 'number' in block && block.number) count += 1;
+      if (block.kind === 'list') block.items.forEach(visit);
+      if (block.kind === 'examples') block.items.forEach((item) => visit(item.children));
+      if ('children' in block && Array.isArray(block.children) && block.kind !== 'paragraph' && block.kind !== 'heading') {
+        visit(block.children as readonly Block[]);
+      }
+    }
+  };
+  for (const { chapters } of parts) for (const { page } of chapters) visit(page.blocks);
+  return count;
+}
+
+/**
+ * The book's symbols in the order they first appear, each once. A symbol
+ * only one chapter defines names that chapter.
+ */
+function appendixNotation(manifest: Manifest, parts: readonly BookPart[]): AppendixNotation[] {
+  const local = new Map<string, string>();
+  for (const lesson of manifest.lessons) {
+    for (const definition of lesson.notation.definitions) {
+      if (definition.scope === 'local') local.set(definition.key, `${lesson.part}.${lesson.chapter}`);
+    }
+  }
+  const seen = new Set<string>();
+  const entries: AppendixNotation[] = [];
+  const add = (page: StaticPage) => {
+    for (const entry of page.notation) {
+      if (seen.has(entry.key)) continue;
+      seen.add(entry.key);
+      const chapter = local.get(entry.key);
+      entries.push({ entry, page, ...(chapter ? { chapter } : {}) });
+    }
+  };
+  for (const { overview, chapters } of parts) {
+    if (overview) add(overview);
+    for (const { page } of chapters) add(page);
+  }
+  return entries;
+}
+
+function bookMainTex(input: BookSourceInput, inputs: readonly string[], appendices: readonly string[]): string {
+  const { manifest, parts } = input;
+  const paper = manifest.lessonExports.latexPaper === 'a4' ? 'a4paper' : 'letterpaper';
+  const { numbering } = manifest;
+  const course = manifest.about.material.name;
+  const authors = (manifest.about as { authors?: readonly { name?: string }[] }).authors
+    ?.map((author) => author.name)
+    .filter((name): name is string => !!name) ?? [];
+  const url = manifest.lessonExports.canonicalBaseUrl;
+  const lists = [
+    ...(countNumbered(parts, 'figure') > 0 ? ['\\listoffigures'] : []),
+    ...(countNumbered(parts, 'table') > 0 ? ['\\listoftables'] : []),
+    ...(countNumbered(parts, 'diagram') > 0 ? ['\\listofdiagrams'] : []),
+  ];
+  return [
+    '% Compile with `latexmk` (LuaLaTeX, see latexmkrc) or `latexmk -pdf` (pdfLaTeX).',
+    ...DOCUMENT_METADATA,
+    `\\documentclass[${paper}]{explico}`,
+    '% The same identifier for every compile of this source.',
+    trailerIdLine(trailerId(manifest, input.document)),
+    ...(numbering.floats === 'part' ? ['\\ExplicoFloatsByPart'] : []),
+    `\\ExplicoSectionDepth{${numbering.sections.show ? numbering.sections.depth : 1}}`,
+    '% The contents list parts, chapters and sections.',
+    '\\setcounter{tocdepth}{1}',
+    `\\hypersetup{pdftitle={${escapeText(input.title)}},pdfauthor={${escapeText(
+      authors.length > 0 ? authors.join(', ') : course,
+    )}},pdfsubject={${escapeText(course)}}}`,
+    '\\begin{document}',
+    '\\frontmatter',
+    `\\ExplicoTitlePage{${escapeText(input.title)}}{${escapeText(input.subtitle ?? '')}}{${escapeText(
+      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}',
+    '\\tableofcontents',
+    ...lists,
+    '\\endgroup',
+    '\\mainmatter',
+    ...inputs.map((file) => `\\input{${file.replace(/\.tex$/u, '')}}`),
+    ...(appendices.length > 0 ? ['\\appendix', ...appendices.map((file) => `\\input{${file.replace(/\.tex$/u, '')}}`)] : []),
+    '\\end{document}',
+    '',
+  ].join('\n');
+}
+
+function bookReadme(input: BookSourceInput): string {
+  const { manifest } = input;
+  const url = manifest.lessonExports.canonicalBaseUrl;
+  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}` : ''),
+    '',
+    '## Build',
+    '',
+    'Needs TeX Live 2025 or later.',
+    '',
+    '```sh',
+    'latexmk          # LuaLaTeX (preferred)',
+    'latexmk -pdf     # pdfLaTeX',
+    '```',
+    '',
+    'LuaLaTeX writes a tagged, accessible PDF (PDF/UA-2) with MathML for every',
+    'formula. pdfLaTeX tags it less completely and claims no standard.',
+    '',
+    '## Files',
+    '',
+    '- `main.tex` — the book: title page, contents, lists of figures, tables and',
+    '  diagrams, then each part and its chapters, then the appendices.',
+    "- `explico.cls` — explico's book class: layout, numbering, and the",
+    '  environments the chapters use (memos, notes, worked examples, checks).',
+    "- `parts/NN-<part>.tex` — a part's opening page and text;",
+    '  `parts/NN-<part>/MM-<chapter>.tex` — its chapters.',
+    '- `backmatter/` — the notation and abbreviation appendices.',
+    "- `figures/` — the chapters' figures, as vector PDF where the website draws them.",
+    '',
+    "Numbers are LaTeX's own and match the website when the source is built",
+    'unchanged; edit freely and they follow.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Every file of a part's or the course's LaTeX folder: a book with a title
+ * page, contents and lists, each part opening with its own page's text,
+ * every chapter in order with references between them as `\ref`s, and the
+ * notation and abbreviation appendices.
+ */
+export function bookSource(input: BookSourceInput): SourceFile[] {
+  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] : []),
+      ...chapters.map(({ page }) => page.route),
+    ]),
+  );
+  // The keys the book's notation appendix defines: a formula links to these.
+  const notationTargets = new Set(appendixNotation(manifest, parts).map(({ entry }) => entry.key));
+  const common = { documentRoutes, canonicalBaseUrl, inBook: true, notationTargets } as const;
+  const files: SourceFile[] = [];
+  const inputs: string[] = [];
+  for (const { part, overview, chapters } of parts) {
+    const partFile = `parts/${twoDigits(part.ordinal)}-${part.dir}.tex`;
+    files.push({
+      path: partFile,
+      content: overview
+        ? serializePartOpener({ ...common, page: overview, pictures: new Map(), checkItems: new Map() }, part)
+        : `\\ExplicoPart{${part.ordinal}}{${escapeText(part.label)}}\n`,
+    });
+    inputs.push(partFile);
+    for (const { lesson, page, pictures } of chapters) {
+      const file = chapterPath(manifest, lesson);
+      const url = canonicalBaseUrl ? `${canonicalBaseUrl}${lesson.slug}/` : undefined;
+      files.push({
+        path: file,
+        content: serializeChapter({
+          ...common,
+          page,
+          pictures: new Map([...pictures].map(([anchor, picture]) => [anchor, picture.path])),
+          checkItems: checkItems(manifest, lesson),
+          source: { course, version, ...(url ? { url } : {}) },
+        }),
+      });
+      inputs.push(file);
+      files.push(...[...pictures.values()].map((picture) => ({ path: picture.path, content: picture.content })));
+    }
+  }
+  const appendices: string[] = [];
+  const notation = serializeNotationAppendix(appendixNotation(manifest, parts), {
+    ...common,
+    pictures: new Map(),
+    checkItems: new Map(),
+  });
+  if (notation) {
+    files.push({ path: 'backmatter/notation.tex', content: notation });
+    appendices.push('backmatter/notation.tex');
+  }
+  const abbreviations = serializeAbbreviationAppendix(
+    manifest.abbreviations.flatMap((entry) =>
+      typeof entry.abbr === 'string' && typeof entry.expansion === 'string'
+        ? [{ abbr: entry.abbr, expansion: entry.expansion }]
+        : [],
+    ),
+  );
+  if (abbreviations) {
+    files.push({ path: 'backmatter/abbreviations.tex', content: abbreviations });
+    appendices.push('backmatter/abbreviations.tex');
+  }
+  return withScripts([
+    { path: 'README.md', content: bookReadme(input) },
+    { path: 'latexmkrc', content: LATEXMKRC },
+    { path: 'main.tex', content: bookMainTex(input, inputs, appendices) },
+    { path: 'explico.cls', content: explicoClass() },
+    ...files,
+  ]);
+}