explico 0.12.0 → 0.13.0

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

@@ -0,0 +1,787 @@
+import { captionTitle } from '../../../components/float-name';
+import type { ContentSegment } from '../../../reference/mixed-content';
+import type {
+  Block,
+  CourseTarget,
+  DiagramGeometry,
+  FigurePicture,
+  Inline,
+  NotationEntry,
+  StaticPage,
+  TableCell,
+} from '../static-tree';
+
+/**
+ * Serialize explico's static reading tree to the LaTeX of one chapter, written
+ * against `explico.cls`. The output is source a person can read and edit:
+ * explico's blocks are named environments, cross-references are `\ref`s to
+ * labels, and numbers are LaTeX's own (checked against the website after
+ * compiling, see `numbering.ts`).
+ */
+
+/** What the serializer needs to know beyond the page itself. */
+export interface ChapterContext {
+  readonly page: StaticPage;
+  /** Routes of every page in this document; a reference to one becomes a `\ref`. */
+  readonly documentRoutes: ReadonlySet<string>;
+  /** Published course root, for links that leave the document. */
+  readonly canonicalBaseUrl?: string;
+  /** Picture files written for this chapter, by float anchor (`fig-…`), relative to the document. */
+  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 };
+  /**
+   * A chapter of a part's or the course's book: its citation keys gain the
+   * chapter (`projectiles/projectile-range/openstax`), since each chapter
+   * keeps its own reference list numbered as on its page; its notation is in
+   * the book's appendix, not after the chapter; and under its title is only
+   * the link to its live version, the title page naming the course.
+   */
+  readonly inBook?: boolean;
+  /**
+   * Keys with an entry in the document's notation appendix, so a formula's
+   * `\explain{key}{…}` can link to it. Absent for a chapter's own document,
+   * which has no appendix: its markers print their TeX, as the class does.
+   */
+  readonly notationTargets?: ReadonlySet<string>;
+}
+
+export interface CheckItem {
+  readonly itemId: string;
+  readonly type: 'single-choice' | 'numeric';
+  readonly promptSegments: readonly ContentSegment[];
+  readonly explanationSegments: readonly ContentSegment[];
+  readonly options?: readonly {
+    readonly id: string;
+    readonly label: string;
+    /** The label as text and math (manifest v30); without it, the label is text. */
+    readonly labelSegments?: readonly ContentSegment[];
+  }[];
+  readonly correctOptionId?: string;
+  readonly answer?: { readonly value: number; readonly tolerance: number };
+}
+
+/** A LaTeX label for an anchor on a page: unique across a whole book. */
+export function labelOf(route: string, anchor: string): string {
+  return `${route}/${anchor}`;
+}
+
+const TEXT_ESCAPES: Readonly<Record<string, string>> = {
+  '\\': '\\textbackslash{}',
+  '{': '\\{',
+  '}': '\\}',
+  $: '\\$',
+  '&': '\\&',
+  '#': '\\#',
+  '^': '\\textasciicircum{}',
+  _: '\\_',
+  '%': '\\%',
+  '~': '\\textasciitilde{}',
+  '<': '\\textless{}',
+  '>': '\\textgreater{}',
+  '|': '\\textbar{}',
+  ' ': '~',
+  '​': '',
+};
+
+/** Two or more Greek letters in a row: a word, set as text, not as symbols. */
+const GREEK_WORD = /[\u0370-\u03FF\u1F00-\u1FFF]{2,}/gu;
+
+export function escapeText(text: string): string {
+  return text
+    .replace(/[\\{}$&#^_%~<>| ​]/gu, (char) => TEXT_ESCAPES[char] ?? char)
+    .replace(GREEK_WORD, (word) => `\\ExplicoGreekWord{${word}}`);
+}
+
+function escapeUrl(url: string): string {
+  return url.replace(/[\\{}]/gu, '').replace(/[%#]/gu, (char) => `\\${char}`);
+}
+
+/** Roughly how many glyphs a formula prints: commands count as one, markers' keys as none. */
+function texVisibleLength(tex: string): number {
+  return tex
+    .replace(/\\(?:explain|slot)\{[^{}]*\}/gu, '')
+    .replace(/\\(?:left|right|[bB]igg?[lr]?|quad|qquad)(?![a-zA-Z])/gu, '')
+    .replace(/\\[,;:!]/gu, '')
+    .replace(/\\[a-zA-Z]+/gu, 'x')
+    .replace(/[{}^_\s]/gu, '').length;
+}
+
+/** Roughly how many glyphs some inline content prints. */
+function visibleLength(inlines: readonly Inline[]): number {
+  let length = 0;
+  for (const inline of inlines) {
+    if (inline.kind === 'text' || inline.kind === 'code') length += inline.value.length;
+    else if (inline.kind === 'math') length += texVisibleLength(inline.tex);
+    else if (inline.kind === 'cite') length += inline.number.length + 2;
+    else if ('children' in inline) length += visibleLength(inline.children);
+  }
+  return length;
+}
+
+function isMathOnly(inlines: readonly Inline[]): boolean {
+  const content = inlines.filter((inline) => !(inline.kind === 'text' && !inline.value.trim()));
+  return content.length > 0 && content.every((inline) => inline.kind === 'math');
+}
+
+function plainText(inlines: readonly Inline[]): string {
+  return inlines
+    .map((inline) => {
+      switch (inline.kind) {
+        case 'text':
+        case 'code':
+          return inline.value;
+        case 'math':
+          return inline.tex;
+        case 'break':
+          return ' ';
+        case 'cite':
+          return `[${inline.number}]`;
+        case 'memoMark':
+          return inline.label;
+        default:
+          return 'children' in inline ? plainText(inline.children) : '';
+      }
+    })
+    .join('');
+}
+
+/** Every citation's source id, by the anchor of its reference-list item. */
+function citationKeys(blocks: readonly Block[]): Map<string, string> {
+  const keys = new Map<string, string>();
+  const visitInlines = (inlines: readonly Inline[]) => {
+    for (const inline of inlines) {
+      if (inline.kind === 'cite' && inline.sourceId) keys.set(inline.anchor, inline.sourceId);
+      if ('children' in inline) visitInlines(inline.children);
+    }
+  };
+  const visitBlocks = (list: readonly Block[]) => {
+    for (const block of list) {
+      if ('children' in block && Array.isArray(block.children)) {
+        if (block.kind === 'paragraph' || block.kind === 'heading') visitInlines(block.children);
+        else visitBlocks(block.children as readonly Block[]);
+      }
+      if (block.kind === 'list') block.items.forEach(visitBlocks);
+      if (block.kind === 'examples') block.items.forEach((item) => visitBlocks(item.children));
+      if (block.kind === 'table') [...block.head, ...block.body].flat().forEach((cell) => visitInlines(cell.children));
+      if ('caption' in block) visitInlines(block.caption);
+    }
+  };
+  visitBlocks(blocks);
+  return keys;
+}
+
+/**
+ * Each reference-list entry's `\bibitem` key, by its anchor. The page lists a
+ * source once per locator it is cited with (`[@s; ch. 3]` and `[@s; ch. 4]`
+ * are two entries, two numbers), so a source cited with one locator keeps its
+ * id as the key and one cited with several gets one key per entry
+ * (`s/cite-4`): a repeated key would be multiply defined, and every `\cite`
+ * of it would print the last entry's number.
+ */
+function entryKeys(sourceByAnchor: ReadonlyMap<string, string>): Map<string, string> {
+  const anchorsBySource = new Map<string, string[]>();
+  for (const [anchor, sourceId] of sourceByAnchor) {
+    const anchors = anchorsBySource.get(sourceId) ?? [];
+    anchors.push(anchor);
+    anchorsBySource.set(sourceId, anchors);
+  }
+  const keys = new Map<string, string>();
+  for (const [sourceId, anchors] of anchorsBySource) {
+    for (const anchor of anchors) {
+      keys.set(anchor, anchors.length === 1 ? sourceId : `${sourceId}/${anchor}`);
+    }
+  }
+  return keys;
+}
+
+/**
+ * Rewrites each `\explain{key}{tex}` whose key `linkTo` names as
+ * `\ExplicoNotation{target}{tex}`, a link to the notation entry; any other
+ * marker stays, and the class prints its TeX. Brace-aware, so a body with
+ * nested groups is kept whole. A link cannot hold another, so the outermost
+ * linked marker wins: `\dot{x}` links to the time derivative, and the markers
+ * inside it print their TeX.
+ */
+export function linkExplains(tex: string, linkTo: (key: string) => string | undefined): string {
+  const marker = '\\explain{';
+  let out = '';
+  let index = 0;
+  for (;;) {
+    const start = tex.indexOf(marker, index);
+    if (start < 0) return out + tex.slice(index);
+    const keyEnd = tex.indexOf('}', start + marker.length);
+    if (keyEnd < 0 || tex[keyEnd + 1] !== '{') {
+      out += tex.slice(index, start + marker.length);
+      index = start + marker.length;
+      continue;
+    }
+    let depth = 0;
+    let close = keyEnd + 1;
+    for (; close < tex.length; close++) {
+      const char = tex[close];
+      if (char === '\\') close++;
+      else if (char === '{') depth++;
+      else if (char === '}' && --depth === 0) break;
+    }
+    if (close >= tex.length) return out + tex.slice(index);
+    const key = tex.slice(start + marker.length, keyEnd);
+    const target = linkTo(key);
+    const inner = tex.slice(keyEnd + 2, close);
+    const body = target ? inner : linkExplains(inner, linkTo);
+    out += tex.slice(index, start);
+    out += target ? `\\ExplicoNotation{${target}}{${body}}` : `\\explain{${key}}{${body}}`;
+    index = close + 1;
+  }
+}
+
+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) {
+    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 {
+    const key = this.citationKeys.get(anchor) ?? anchor;
+    return this.context.inBook ? `${this.route}/${key}` : key;
+  }
+
+  label(anchor: string): string {
+    return labelOf(this.route, anchor);
+  }
+
+  /** Renders `write` with links to notation off: a link cannot nest, or sit in a moving argument. */
+  private unlinkedWhile<T>(write: () => T): T {
+    this.unlinked++;
+    try {
+      return write();
+    } finally {
+      this.unlinked--;
+    }
+  }
+
+  /** Inline content with no notation links inside it. */
+  private 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 {
+    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 {
+    return this.context.documentRoutes.has(target.route);
+  }
+
+  private canonicalUrl(target: CourseTarget): string | undefined {
+    const base = this.context.canonicalBaseUrl;
+    if (!base) return undefined;
+    const path = target.route ? `${target.route}/` : '';
+    return `${base}${path}${target.anchor ? `#${target.anchor}` : ''}`;
+  }
+
+  /** A cross-reference: LaTeX's number inside the document, the website's outside it. */
+  private 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);
+      if (refKind === 'equation' && /^\(\s*[\d.]+\s*\)$/u.test(text.trim())) {
+        return `\\ExplicoEqRef{${label}}`;
+      }
+      const number = /\d+(?:\.\d+)*/u.exec(text);
+      if (number && ['equation', 'figure', 'table', 'diagram', 'section', 'example', 'check'].includes(refKind)) {
+        const before = text.slice(0, number.index);
+        const after = text.slice(number.index + number[0].length);
+        return `\\ExplicoRef{${label}}{${escapeText(before)}}{${escapeText(after)}}`;
+      }
+      return `\\hyperref[${label}]{${this.plain(children)}}`;
+    }
+    const url = this.canonicalUrl(target);
+    return url ? `\\href{${escapeUrl(url)}}{${this.plain(children)}}` : this.inlines(children);
+  }
+
+  inline(inline: Inline): string {
+    switch (inline.kind) {
+      case 'text':
+        return escapeText(inline.value);
+      case 'emphasis':
+        return `\\emph{${this.inlines(inline.children)}}`;
+      case 'strong':
+        return `\\textbf{${this.inlines(inline.children)}}`;
+      case 'superscript':
+        return `\\textsuperscript{${this.inlines(inline.children)}}`;
+      case 'subscript':
+        return `\\textsubscript{${this.inlines(inline.children)}}`;
+      case 'code':
+        return `\\texttt{${escapeText(inline.value)}}`;
+      case 'math':
+        return `$${this.math(inline.tex)}$`;
+      case 'break':
+        return '\\newline ';
+      case 'link':
+        return `\\href{${escapeUrl(inline.href)}}{${this.plain(inline.children)}}`;
+      case 'ref':
+        return this.reference(inline.refKind, inline.target, inline.children);
+      case 'term':
+        return `\\ExplicoTerm{${inline.key}}{${this.inlines(inline.children)}}`;
+      case 'cite':
+        // The locator is part of the entry it points at, as on the page,
+        // so the marker is the entry's number alone.
+        return inline.sourceId
+          ? `\\cite{${this.citeKey(inline.anchor)}}`
+          : `[${escapeText(inline.number)}]`;
+      case 'memoMark':
+        return `\\ExplicoMemoMark{${this.label(inline.anchor)}}`;
+      case 'noteMark':
+        return `\\ExplicoNoteMark{${this.label(inline.anchor)}}{${this.plain(inline.children)}}`;
+    }
+  }
+
+  inlines(inlines: readonly Inline[]): string {
+    return inlines.map((inline) => this.inline(inline)).join('');
+  }
+
+  private 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 {
+    const short = block.short?.trim();
+    const long = [this.plain(block.caption), this.plain(extra)].filter(Boolean).join(' ');
+    const title = short ? `\\ExplicoCaptionTitle{${escapeText(captionTitle(short))}} ` : '';
+    const list = short ? `[${escapeText(short)}]` : '';
+    return `\\caption${list}{${title}${long}}\\label{${this.label(block.anchor)}}`;
+  }
+
+  /**
+   * 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 {
+    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 {
+    if (picture.kind === 'diagram') return diagramTikz(picture.geometry, this);
+    const file = this.context.pictures.get(anchor);
+    if (file) {
+      // The tagged PDF reads `alt` to a screen reader in place of the picture.
+      // Its braces keep a comma, an equals sign or a bracket from ending the
+      // key or the option list, so the text keeps its punctuation.
+      const text = escapeText(alt || 'Figure');
+      return `\\includegraphics[alt={${text}},max width=\\linewidth,max height=0.6\\textheight]{${file}}`;
+    }
+    return `\\fbox{\\parbox{0.9\\linewidth}{\\centering\\small\\itshape ${escapeText(
+      alt || 'Interactive figure',
+    )}: see the interactive version on the course website.}}`;
+  }
+
+  private 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 '';
+    const cellAt = (row: readonly TableCell[], column: number): TableCell | undefined => {
+      let position = 0;
+      for (const cell of row) {
+        if (position === column && cell.colspan === 1) return cell;
+        position += cell.colspan;
+      }
+      return undefined;
+    };
+    const widths = Array.from({ length: columns }, (_, column) =>
+      Math.max(0, ...rows.map((row) => visibleLength(cellAt(row, column)?.children ?? []))),
+    );
+    // A column that is mostly prose may wrap; math and numbers never break.
+    const prose = Array.from({ length: columns }, (_, column) =>
+      block.body.some((row) => {
+        const cell = cellAt(row, column);
+        return !!cell && !isMathOnly(cell.children) && /[a-z]{3}/iu.test(plainText(cell.children));
+      }),
+    );
+    const total = widths.reduce((sum, width) => sum + width + 2, 0);
+    const wraps = total > 75 && prose.some((isProse, column) => isProse && widths[column]! > 18);
+    const alignOf = (column: number): string => {
+      if (wraps && prose[column] && widths[column]! > 18) return '>{\\raggedright\\arraybackslash}X';
+      const align = (block.body[0] && cellAt(block.body[0], column)?.align) ?? cellAt(block.head[0] ?? [], column)?.align;
+      return align === 'right' ? 'r' : align === 'center' ? 'c' : 'l';
+    };
+    const spec = Array.from({ length: columns }, (_, column) => alignOf(column)).join('');
+    const dense = columns >= 8;
+    const row = (cells: readonly TableCell[]) =>
+      `${cells
+        .map((cell) => {
+          const content = this.inlines(cell.children);
+          return cell.colspan > 1 ? `\\multicolumn{${cell.colspan}}{l}{${content}}` : content;
+        })
+        .join(' & ')} \\\\`;
+    const body = [
+      '\\toprule',
+      ...block.head.map(row),
+      ...(block.head.length > 0 ? ['\\midrule'] : []),
+      ...block.body.map(row),
+      '\\bottomrule',
+    ];
+    // A table of data (many columns, nothing to wrap) shrinks to the measure
+    // only when it would overflow it; a table of prose wraps its long columns.
+    const tabular = wraps
+      ? ['\\small', `\\begin{tabularx}{\\linewidth}{@{}${spec}@{}}`, ...body, '\\end{tabularx}'].join('\n')
+      : [
+          dense ? '\\footnotesize\\setlength{\\tabcolsep}{4pt}' : '\\small',
+          '\\begin{adjustbox}{max width=\\linewidth}',
+          `\\begin{tabular}{@{}${spec}@{}}`,
+          ...body,
+          '\\end{tabular}',
+          '\\end{adjustbox}',
+        ].join('\n');
+    if (!block.number) return `\\begin{center}\n${tabular}\n\\end{center}`;
+    return this.float('table', inBox, tabular, this.caption(block), true);
+  }
+
+  /** A choice's label, its math typeset like the prompt's. */
+  private 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 {
+    const items = this.context.checkItems.get(block.assessmentId) ?? [];
+    const questions = items.map((item) => {
+      const options =
+        item.type === 'single-choice' && item.options && item.options.length > 0
+          ? [
+              '\\begin{enumerate}[label=(\\alph*)]',
+              ...item.options.map((option) => `\\item ${this.optionLabel(option)}`),
+              '\\end{enumerate}',
+            ].join('\n')
+          : '';
+      return `\\item ${this.segments(item.promptSegments)}${options ? `\n${options}` : ''}`;
+    });
+    return [
+      `\\begin{ExplicoCheck}{${this.plain(block.title)}}\\label{${this.label(block.anchor)}}`,
+      ...(questions.length > 0 ? ['\\begin{enumerate}', ...questions, '\\end{enumerate}'] : []),
+      `\\ExplicoCheckAnswerNote{${this.label('answers')}}`,
+      '\\end{ExplicoCheck}',
+    ].join('\n');
+  }
+
+  /** The chapter's answer key: every check's answers and explanations, in order. */
+  answers(checks: readonly Extract<Block, { kind: 'check' }>[]): string {
+    if (checks.length === 0) return '';
+    const parts = [`\\section*{Answers to the knowledge checks}\\hypertarget{${this.label('answers')}}{}`];
+    for (const check of checks) {
+      const items = this.context.checkItems.get(check.assessmentId) ?? [];
+      parts.push(
+        `\\paragraph*{\\ExplicoRef{${this.label(check.anchor)}}{Knowledge check~}{}: ${this.plain(check.title)}}`,
+      );
+      parts.push('\\begin{enumerate}');
+      for (const item of items) {
+        let answer = '';
+        if (item.type === 'single-choice' && item.options) {
+          const index = item.options.findIndex((option) => option.id === item.correctOptionId);
+          if (index !== -1) {
+            answer = `\\textbf{(${String.fromCharCode(97 + index)})} ${this.optionLabel(item.options[index]!)}. `;
+          }
+        } else if (item.type === 'numeric' && item.answer) {
+          answer = `\\textbf{$${item.answer.value}$} (accepted within $\\pm${item.answer.tolerance}$). `;
+        }
+        parts.push(`\\item ${answer}${this.segments(item.explanationSegments)}`);
+      }
+      parts.push('\\end{enumerate}');
+    }
+    return parts.join('\n');
+  }
+
+  block(block: Block, inBox = false): string {
+    switch (block.kind) {
+      case 'heading': {
+        const text = this.plain(block.children);
+        const label = block.anchor ? `\\label{${this.label(block.anchor)}}` : '';
+        if (inBox) return `\\par\\smallskip\\noindent\\textbf{${text}}${label}\\par`;
+        const command =
+          ['section', 'subsection', 'subsubsection', 'paragraph', 'subparagraph'][
+            Math.min(Math.max(block.level - 2, 0), 4)
+          ] ?? 'paragraph';
+        const star = block.number ? '' : '*';
+        return `\\${command}${star}{${text}}${label}`;
+      }
+      case 'paragraph':
+        return this.inlines(block.children);
+      case 'list': {
+        const environment = block.ordered ? 'enumerate' : 'itemize';
+        const start =
+          block.ordered && block.start && block.start !== 1
+            ? `\\setcounter{enumi}{${block.start - 1}}\n`
+            : '';
+        const items = block.items.map((item) => `\\item ${this.blocks(item, inBox)}`);
+        return `\\begin{${environment}}\n${start}${items.join('\n')}\n\\end{${environment}}`;
+      }
+      case 'equation':
+        return `\\begin{equation}\\label{${this.label(block.anchor)}}\n${this.math(block.tex)}\n\\end{equation}`;
+      case 'displayMath':
+        return `\\[\n${this.math(block.tex)}\n\\]`;
+      case 'figure':
+        return this.float(
+          'figure',
+          inBox,
+          this.picture(
+            block.anchor,
+            block.picture,
+            block.alt ?? [block.short && captionTitle(block.short), plainText(block.caption)].filter(Boolean).join(' '),
+          ),
+          this.caption(block, block.live),
+        );
+      case 'diagram':
+        return this.float(
+          'diagram',
+          inBox,
+          this.unlinkedWhile(() => diagramTikz(block.geometry, this)),
+          this.caption(block),
+        );
+      case 'table':
+        return this.table(block, inBox);
+      case 'memo':
+        return [
+          `\\begin{ExplicoMemo}{${this.plain(block.title)}}\\label{${this.label(block.anchor)}}`,
+          this.blocks(block.children, true),
+          '\\end{ExplicoMemo}',
+        ].join('\n');
+      case 'note':
+        return [
+          `\\begin{ExplicoNote}{${this.label(block.anchor)}}{${escapeText(block.title)}}`,
+          this.blocks(block.children, true),
+          '\\end{ExplicoNote}',
+        ].join('\n');
+      case 'aside':
+        return [
+          `\\begin{ExplicoAside}{${block.variant}}{${this.plain(block.title)}}`,
+          this.blocks(block.children, true),
+          '\\end{ExplicoAside}',
+        ].join('\n');
+      case 'fold':
+        return [
+          ...(block.title ? [`\\paragraph*{${this.plain(block.title)}}`] : []),
+          this.blocks(block.children, inBox),
+        ].join('\n');
+      case 'examples':
+        return [
+          `\\begin{ExplicoExamples}{${this.plain(block.title)}}\\label{${this.label(block.anchor)}}`,
+          ...block.items.flatMap((item) => [
+            `\\ExplicoExample{${this.plain(item.title)}}`,
+            this.blocks(item.children, true),
+          ]),
+          '\\end{ExplicoExamples}',
+        ].join('\n');
+      case 'check':
+        return this.check(block);
+      case 'quote':
+        return `\\begin{quote}\n${this.blocks(block.children, inBox)}\n\\end{quote}`;
+      case 'image': {
+        const file = this.context.pictures.get(block.src);
+        return file
+          ? `\\begin{center}\\includegraphics[max width=\\linewidth]{${file}}\\end{center}`
+          : '';
+      }
+      case 'code':
+        return `\\begin{verbatim}\n${block.value}\n\\end{verbatim}`;
+      case 'rule':
+        return '\\par\\noindent\\rule{\\linewidth}{0.4pt}\\par';
+      case 'references':
+        return [
+          `\\begin{ExplicoReferences}{${block.items.length}}`,
+          ...block.items.map(
+            (item) =>
+              `\\bibitem{${this.citeKey(item.anchor)}} ${this.plain(item.children)}`,
+          ),
+          '\\end{ExplicoReferences}',
+        ].join('\n');
+    }
+  }
+
+  blocks(blocks: readonly Block[], inBox = false): string {
+    return blocks
+      .map((block) => this.block(block, inBox))
+      .filter((text) => text.trim().length > 0)
+      .join('\n\n');
+  }
+
+  notation(entries: readonly NotationEntry[], remarks: readonly (readonly Inline[])[]): string {
+    if (entries.length === 0) return '';
+    const items = entries.map((entry) => {
+      const symbol = entry.symbolTex ? `$${entry.symbolTex}$` : '';
+      const parts = [
+        `\\textbf{${this.inlines(entry.label)}}.`,
+        this.inlines(entry.summary),
+        ...(entry.units ? [`\\emph{Units:} ${this.inlines(entry.units)}.`] : []),
+        ...(entry.formulaTex ? [`\\[${entry.formulaTex}\\]`] : []),
+      ];
+      return `\\item[${symbol}]\\hypertarget{${this.label(entry.anchor)}}{}${parts.join(' ')}`;
+    });
+    return [
+      '\\section*{Notation}',
+      ...remarks.map((remark) => `\\noindent\\emph{${this.inlines(remark)}}\\par\\medskip`),
+      '\\begin{description}',
+      ...items,
+      '\\end{description}',
+    ].join('\n');
+  }
+}
+
+/**
+ * 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
+ * math. Coordinates are scaled to the text width; type keeps its size.
+ */
+export function diagramTikz(geometry: DiagramGeometry, writer: { inlines(inlines: readonly Inline[]): string }): string {
+  if (geometry.nodes.length === 0) return '';
+  // CSS pixels to points, shrunk to fit a 450 pt measure (the text width of
+  // both letter and A4 pages with one-inch margins is wider).
+  const scale = 0.75 * Math.min(1, 450 / Math.max(1, geometry.width * 0.75));
+  const pt = (value: number) => `${(value * scale).toFixed(1)}pt`;
+  const point = (x: number, y: number) => `(${pt(x)},${pt(-y)})`;
+  const nodes = geometry.nodes.map((node) => {
+    const text = node.text ? writer.inlines([{ kind: 'text', value: node.text }]) : '';
+    const math = node.tex ? `$${node.tex}$` : '';
+    const content = [text, math].filter(Boolean).join('\\\\ ');
+    const textWidth = Math.max(10, node.width * scale - 8).toFixed(1);
+    return `\\node[explico diagram node,minimum width=${pt(node.width)},minimum height=${pt(node.height)},text width=${textWidth}pt] at ${point(node.x + node.width / 2, node.y + node.height / 2)} {${content}};`;
+  });
+  const edges = geometry.edges.map(
+    (edge) => `\\draw[explico diagram edge] ${edge.map(([x, y]) => point(x, y)).join(' -- ')};`,
+  );
+  return ['\\begin{tikzpicture}', ...edges, ...nodes, '\\end{tikzpicture}'].join('\n');
+}
+
+/** The LaTeX of one chapter: `\chapter`, its body, references, notation and answers. */
+export function serializeChapter(context: ChapterContext): string {
+  const writer = new ChapterWriter(context);
+  const { page } = context;
+  const checks: Extract<Block, { kind: 'check' }>[] = [];
+  const collect = (blocks: readonly Block[]) => {
+    for (const block of blocks) {
+      if (block.kind === 'check') checks.push(block);
+      if ('children' in block && Array.isArray(block.children) && block.kind !== 'paragraph' && block.kind !== 'heading') {
+        collect(block.children as readonly Block[]);
+      }
+    }
+  };
+  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) : ''
+          }}`,
+        ];
+  return [
+    `\\chapter{${escapeText(page.title)}}\\label{${labelOf(page.route, '_top')}}`,
+    '\\ExplicoApplyOffsets',
+    ...sourceLine,
+    writer.blocks(page.blocks),
+    ...(context.inBook ? [] : [writer.notation(page.notation, page.notationRemarks)]),
+    writer.answers(checks),
+    '',
+  ]
+    .filter((part) => part !== undefined)
+    .join('\n\n');
+}
+
+/**
+ * A part's opener in a book: `\ExplicoPart`, numbered as on the website, then
+ * the text of the part's own page (its introduction, scope and objectives).
+ */
+export function serializePartOpener(context: ChapterContext, part: { readonly ordinal: number; readonly label: string }): string {
+  const writer = new ChapterWriter({ ...context, inBook: true });
+  return [
+    `\\ExplicoPart{${part.ordinal}}{${escapeText(part.label)}}\\label{${labelOf(context.page.route, '_top')}}`,
+    writer.blocks(context.page.blocks),
+    '',
+  ].join('\n\n');
+}
+
+/** A symbol in a book's notation appendix: its entry, the page that defines it, and the chapter it is local to. */
+export interface AppendixNotation {
+  readonly entry: NotationEntry;
+  readonly page: StaticPage;
+  /** `2.2` for a symbol only one chapter defines; none for a shared one. */
+  readonly chapter?: string;
+}
+
+/**
+ * The book's notation appendix: every symbol its chapters use, in the order
+ * they first appear, each with its meaning, units and defining formula.
+ */
+export function serializeNotationAppendix(
+  entries: readonly AppendixNotation[],
+  context: Omit<ChapterContext, 'page'>,
+): string {
+  if (entries.length === 0) return '';
+  const writers = new Map<string, ChapterWriter>();
+  const writerFor = (page: StaticPage) => {
+    let writer = writers.get(page.route);
+    if (!writer) {
+      writer = new ChapterWriter({ ...context, page, inBook: true });
+      writers.set(page.route, writer);
+    }
+    return writer;
+  };
+  const targets = context.notationTargets;
+  /** A defining formula, each other entry it names linked; its own symbol is the entry the reader is on. */
+  const formula = (key: string, tex: string) =>
+    targets ? linkExplains(tex, (named) => (named !== key && targets.has(named) ? labelOf('notation', named) : undefined)) : tex;
+  const items = entries.map(({ entry, page, chapter }) => {
+    const writer = writerFor(page);
+    const parts = [
+      `\\textbf{${writer.inlines(entry.label)}}.`,
+      writer.inlines(entry.summary),
+      ...(entry.units ? [`\\emph{Units:} ${writer.inlines(entry.units)}.`] : []),
+      ...(chapter ? [`\\emph{In Chapter~${chapter} only.}`] : []),
+      ...(entry.formulaTex ? [`\\[${formula(entry.key, entry.formulaTex)}\\]`] : []),
+    ];
+    const symbol = entry.symbolTex ? `$${entry.symbolTex}$` : '';
+    return `\\item[{${symbol}}]\\hypertarget{${labelOf('notation', entry.key)}}{}${parts.join(' ')}`;
+  });
+  return [
+    '\\chapter{Notation}\\label{appendix/notation}',
+    'The symbols of this book, in the order they first appear.',
+    '\\begin{description}',
+    ...items,
+    '\\end{description}',
+    '',
+  ].join('\n');
+}
+
+/** The book's abbreviation appendix: each abbreviation and what it stands for. */
+export function serializeAbbreviationAppendix(
+  abbreviations: readonly { readonly abbr: string; readonly expansion: string }[],
+): string {
+  if (abbreviations.length === 0) return '';
+  return [
+    '\\chapter{Abbreviations}\\label{appendix/abbreviations}',
+    '\\begin{description}',
+    ...[...abbreviations]
+      .sort((a, b) => a.abbr.localeCompare(b.abbr))
+      .map((entry) => `\\item[{${escapeText(entry.abbr)}}] ${escapeText(entry.expansion)}`),
+    '\\end{description}',
+    '',
+  ].join('\n');
+}