explico 0.13.1 → 0.14.0

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

@@ -0,0 +1,419 @@
+/**
+ * A lesson's deck as beamer (docs/authoring/deck.md): the frames its page
+ * shows, read off the built page (`readStaticDeck`), in explico's theme
+ * (`beamerthemeexplico.sty`, over `explico-common.sty`). The folder holds
+ * `main.tex` (the slides) and `handout.tex` (each slide followed by its
+ * notes), both reading `deck.tex`. Each frame carries `\label{frame:N}`, and
+ * the build checks that LaTeX numbers every frame as the page does.
+ *
+ * On paper a step is beamer's overlay (`uncoverenv`, `\item<k->`); a step
+ * that drives a figure or lights a symbol shows nothing new, so it takes no
+ * slide. After the last frame, an appendix lists the symbols the frames use,
+ * and each symbol on a frame links to its entry (rule D5's paper half).
+ * Beamer cannot write a tagged PDF (it refuses `\DocumentMetadata`):
+ * the deck's PDFs are untagged, and the chapter's PDF is the accessible
+ * paper edition.
+ */
+import { readFileSync } from 'node:fs';
+
+import type { Manifest, ManifestDeck } from '../../manifest';
+import type { Block, DeckFrame, Inline, NotationEntry, StaticDeck, StaticPage } from '../static-tree';
+import { escapeText, ChapterWriter, labelOf, linkExplains, type ChapterContext } from './serialize';
+import { versionPhrase } from '../../page-versions';
+import { explicoCommon, needsScripts, trailerId, type SourceFile } from './document';
+
+/** `beamerthemeexplico.sty`, read next to this module. */
+export function deckTheme(): string {
+  return readFileSync(new URL('./beamerthemeexplico.sty', import.meta.url), 'utf8');
+}
+
+const ASPECT: Readonly<Record<string, string>> = { '16:9': '169', '16:10': '1610', '4:3': '43' };
+
+/** The frames of a deck as the static tree reads them, flattened for the citation keys. */
+function deckPage(deck: StaticDeck): StaticPage {
+  return {
+    slug: deck.slug,
+    route: deck.route,
+    title: deck.title,
+    blocks: deck.frames.flatMap((frame) => [...frame.segments.flatMap((segment) => segment.blocks), ...frame.notes]),
+    notation: [],
+    notationRemarks: [],
+  };
+}
+
+class DeckWriter extends ChapterWriter {
+  inline(inline: Inline): string {
+    // A deck has no bibliography of its own: a citation is its number, and the
+    // references frame lists the entries.
+    if (inline.kind === 'cite') return `[${escapeText(inline.number)}]`;
+    return super.inline(inline);
+  }
+
+  /** A float's caption on a frame: its number (the chapter's, when recalled), its short and long caption. */
+  private deckCaption(kind: string, block: { number: string; short?: string; caption: readonly Inline[] }, extra: readonly Inline[] = []): string {
+    const number = block.number ? `${kind}~${escapeText(block.number)}` : '';
+    const short = block.short?.trim() ? escapeText(block.short.trim().replace(/\.$/u, '')) : '';
+    const long = [this.plain(block.caption), this.plain(extra)].filter(Boolean).join(' ');
+    return `\\ExplicoDeckCaption{${number}}{${short}}{${long}}`;
+  }
+
+  block(block: Block, inBox = false): string {
+    switch (block.kind) {
+      case 'heading':
+        return `\\par\\textbf{${this.plain(block.children)}}\\par`;
+      case 'equation':
+        return `\\begin{equation*}\n${this.math(block.tex)}\n\\tag{${escapeText(block.number)}}\n\\end{equation*}`;
+      case 'list': {
+        const environment = block.ordered ? 'enumerate' : 'itemize';
+        const items = block.items.map((item, index) => {
+          const step = block.itemSteps?.[index] ?? 1;
+          return `\\item${step > 1 ? `<${step}->` : ''} ${this.blocks(item, inBox)}`;
+        });
+        return `\\begin{${environment}}\n${items.join('\n')}\n\\end{${environment}}`;
+      }
+      case 'figure': {
+        const alt = block.alt ?? [block.short, ...block.caption.map((inline) => ('value' in inline ? inline.value : ''))].filter(Boolean).join(' ');
+        const picture = this.picture(block.anchor, block.picture, alt).replace('max height=0.6\\textheight', 'max height=0.62\\textheight');
+        return `\\begin{center}\n${picture}\n${this.deckCaption('Figure', block, block.live)}\n\\end{center}`;
+      }
+      case 'diagram':
+        return [
+          '\\begin{center}',
+          '\\begin{adjustbox}{max width=\\linewidth,max height=0.62\\textheight}',
+          this.unlinkedWhile(() => this.picture(block.anchor, { kind: 'diagram', geometry: block.geometry }, '')),
+          '\\end{adjustbox}',
+          this.deckCaption('Diagram', block),
+          '\\end{center}',
+        ].join('\n');
+      case 'table': {
+        const tabular = this.table({ ...block, number: '' }, true);
+        return `\\begin{center}\n${this.deckCaption('Table', block)}\n\\smallskip\n${tabular}\n\\end{center}`;
+      }
+      case 'memo':
+        return [`\\begin{block}{${this.plain(block.title)}}`, this.blocks(block.children, true), '\\end{block}'].join('\n');
+      case 'note':
+        return [`\\begin{block}{${escapeText(block.title)}}`, this.blocks(block.children, true), '\\end{block}'].join('\n');
+      case 'aside': {
+        const environment = block.variant === 'caution' || block.variant === 'danger' ? 'alertblock' : 'block';
+        return [`\\begin{${environment}}{${this.plain(block.title)}}`, this.blocks(block.children, true), `\\end{${environment}}`].join('\n');
+      }
+      case 'examples':
+        return block.items
+          .map((item) => [`\\begin{block}{${this.plain(item.title)}}`, this.blocks(item.children, true), '\\end{block}'].join('\n'))
+          .join('\n');
+      case 'check': {
+        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
+              ? `\n\\begin{enumerate}\n${item.options.map((option) => `\\item[(${String.fromCharCode(97 + item.options!.indexOf(option))})] ${this.optionLabel(option)}`).join('\n')}\n\\end{enumerate}`
+              : '';
+          return `\\item ${this.segments(item.promptSegments)}${options}`;
+        });
+        return [
+          `\\par{\\usebeamercolor[fg]{structure}\\textbf{Knowledge check ${escapeText(block.number)}}}\\enspace ${this.plain(block.title)}\\par`,
+          ...(questions.length > 0 ? ['\\begin{enumerate}', ...questions, '\\end{enumerate}'] : []),
+        ].join('\n');
+      }
+      default:
+        return super.block(block, inBox);
+    }
+  }
+
+  /** A check's answers, for the frame's notes. */
+  checkAnswers(block: Extract<Block, { kind: 'check' }>): string {
+    const items = this.context.checkItems.get(block.assessmentId) ?? [];
+    return items
+      .map((item) => {
+        if (item.type === 'single-choice' && item.options) {
+          const index = item.options.findIndex((option) => option.id === item.correctOptionId);
+          const answer = index === -1 ? '' : `(${String.fromCharCode(97 + index)}) ${this.optionLabel(item.options[index]!)}. `;
+          return `Answer: ${answer}${this.segments(item.explanationSegments)}`;
+        }
+        if (item.type === 'numeric' && item.answer) {
+          return `Answer: $${item.answer.value}$ (within $\\pm${item.answer.tolerance}$). ${this.segments(item.explanationSegments)}`;
+        }
+        return this.segments(item.explanationSegments);
+      })
+      .join('\\par ');
+  }
+
+  frameTitle(frame: DeckFrame): string {
+    return this.plain(frame.title);
+  }
+
+  /** A legend line's symbol, linked to its appendix entry. */
+  legendSymbol(tex: string): string {
+    return this.math(tex);
+  }
+
+  /**
+   * The notation appendix: each symbol the deck uses, by first use, with its
+   * name, what it is, its units and its defining formula, as the chapter's
+   * notation lists it. It breaks over as many frames as it needs.
+   */
+  notationFrames(entries: readonly NotationEntry[]): string {
+    if (entries.length === 0) return '';
+    const targets = new Set(entries.map((entry) => entry.key));
+    const items = entries.map((entry) => {
+      const formula = entry.formulaTex
+        ? linkExplains(entry.formulaTex, (named) => (named !== entry.key && targets.has(named) ? labelOf('notation', named) : undefined))
+        : undefined;
+      const parts = [
+        `\\textbf{${this.inlines(entry.label)}}.`,
+        this.inlines(entry.summary),
+        ...(entry.units ? [`\\emph{Units:} ${this.inlines(entry.units)}.`] : []),
+        ...(formula ? [`$${formula}$`] : []),
+      ];
+      return `\\item[{${entry.symbolTex ? `$${entry.symbolTex}$` : ''}}]\\hypertarget{${labelOf('notation', entry.key)}}{}${parts.join(' ')}`;
+    });
+    return [
+      '\\appendix',
+      '\\section{Notation}',
+      '\\begin{frame}[allowframebreaks,t]{Notation}',
+      '\\small',
+      '\\begin{description}',
+      ...items,
+      '\\end{description}',
+      '\\end{frame}',
+    ].join('\n');
+  }
+}
+
+/**
+ * The notation keys a deck's LaTeX names, in order of first use: in a
+ * formula (`\explain{key}{…}`) or in prose (`\ExplicoTerm{key}{…}`).
+ */
+export function deckNotationKeys(tex: string): string[] {
+  const keys = new Set<string>();
+  for (const match of tex.matchAll(/\\(?:explain|ExplicoTerm)\{([^{}]+)\}\{/gu)) keys.add(match[1]!);
+  return [...keys];
+}
+
+/**
+ * The symbols a deck's frames use, in order of first use, from its page's
+ * notation list: its appendix in every download.
+ */
+export function deckSymbols(
+  context: Omit<ChapterContext, 'page'> & { readonly deck: StaticDeck },
+): NotationEntry[] {
+  const byKey = new Map(context.deck.notation.map((entry) => [entry.key, entry]));
+  return deckNotationKeys(serializeDeck(context).tex).flatMap((key) => {
+    const entry = byKey.get(key);
+    return entry ? [entry] : [];
+  });
+}
+
+/** Every check a frame shows, at any depth. */
+function checksOf(blocks: readonly Block[]): Extract<Block, { kind: 'check' }>[] {
+  const out: Extract<Block, { kind: 'check' }>[] = [];
+  for (const block of blocks) {
+    if (block.kind === 'check') out.push(block);
+    if ('children' in block && Array.isArray(block.children) && block.kind !== 'paragraph' && block.kind !== 'heading') {
+      out.push(...checksOf(block.children as readonly Block[]));
+    }
+  }
+  return out;
+}
+
+function hasCode(blocks: readonly Block[]): boolean {
+  return blocks.some(
+    (block) =>
+      block.kind === 'code' ||
+      ('children' in block && Array.isArray(block.children) && block.kind !== 'paragraph' && block.kind !== 'heading' && hasCode(block.children as readonly Block[])),
+  );
+}
+
+export interface DeckSerialization {
+  /** `deck.tex`: every frame, in order. */
+  readonly tex: string;
+  /** The line of `deck.tex` each frame ends on, by frame number: a paper overflow names its frame by it. */
+  readonly frameEnds: ReadonlyMap<number, number>;
+}
+
+/**
+ * The frames of a deck in beamer, then the notation appendix of the symbols
+ * they use (`appendix`, each linked from its uses through `notationTargets`).
+ */
+export function serializeDeck(
+  context: Omit<ChapterContext, 'page'> & { readonly deck: StaticDeck; readonly appendix?: readonly NotationEntry[] },
+): DeckSerialization {
+  const writer = new DeckWriter({ ...context, page: deckPage(context.deck) });
+  const lines: string[] = [];
+  const frameEnds = new Map<number, number>();
+  const push = (text: string) => lines.push(...text.split('\n'));
+  // The progress bar runs over the deck's own frames, not the appendix's.
+  push(`\\ExplicoDeckFrames{${context.deck.frames.length}}`);
+  lines.push('');
+  for (const frame of context.deck.frames) {
+    const label = `\\label{frame:${frame.number}}`;
+    if (frame.kind === 'title') {
+      push(`\\begin{frame}[plain]${label}\n\\titlepage\n\\end{frame}`);
+    } else if (frame.kind === 'section') {
+      push(`\\section{${writer.frameTitle(frame)}}\n\\begin{frame}${label}\n\\ExplicoSectionPage\n\\end{frame}`);
+    } else {
+      const blocks = frame.segments.flatMap((segment) => segment.blocks);
+      const options = hasCode(blocks) ? '[fragile]' : '';
+      const body = frame.segments.map((segment) => {
+        const content = writer.blocks(segment.blocks);
+        return segment.step > 1 ? `\\begin{uncoverenv}<${segment.step}->\n${content}\n\\end{uncoverenv}` : content;
+      });
+      const legend = frame.legend.filter((item) => item.tex);
+      const answers = checksOf(blocks).map((check) => writer.checkAnswers(check)).filter(Boolean);
+      const notes = [writer.blocks(frame.notes), ...answers].filter((text) => text.trim().length > 0);
+      push(
+        [
+          `\\begin{frame}${options}{${writer.frameTitle(frame)}}${label}`,
+          ...body,
+          ...(legend.length > 0
+            ? [`\\ExplicoLegend{${legend.map((item) => `$${writer.legendSymbol(item.tex)}$~${escapeText(item.label.map((inline) => ('value' in inline ? inline.value : '')).join(''))}`).join('\\quad ')}}`]
+            : []),
+          ...(notes.length > 0 ? [`\\note{${notes.join('\n\n')}}`] : []),
+          '\\end{frame}',
+        ].join('\n'),
+      );
+    }
+    frameEnds.set(frame.number, lines.length);
+    lines.push('');
+  }
+  const appendix = writer.notationFrames(context.appendix ?? []);
+  if (appendix) push(`${appendix}\n`);
+  return { tex: `${lines.join('\n')}\n`, frameEnds };
+}
+
+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');
+
+/** `main.tex` or `handout.tex` of a deck. */
+function deckMain(manifest: Manifest, deck: ManifestDeck, handout: boolean, scripts: boolean): string {
+  const ratio = ASPECT[manifest.deck?.aspectRatio ?? '16:9'] ?? '169';
+  const course = manifest.about.material.name;
+  const authors = (manifest.about.authors ?? []).map((author) => author.name).filter(Boolean).join(', ');
+  // The version the deck's content is at (rule C5): an unchanged deck's PDF
+  // stays the same bytes from release to release.
+  const version = versionPhrase(deck.since, manifest.about.knowledge.version);
+  const document = `${deck.slug}${handout ? '#handout' : ''}`;
+  const trailer = trailerId(manifest, document, deck.since);
+  return [
+    `% The deck's ${handout ? 'handout: each slide followed by its notes' : 'slides'}. Compile with \`latexmk${handout ? ' handout.tex' : ''}\` (LuaLaTeX, see latexmkrc).`,
+    '% A fixed seed for TeX\'s random numbers: the same source gives the same PDF.',
+    '\\ExplSyntaxOn \\sys_gset_rand_seed:n { 1 } \\ExplSyntaxOff',
+    // usepdftitle=false: the title below is the PDF's, not beamer's "title - subtitle".
+    `\\documentclass[aspectratio=${ratio},11pt,usepdftitle=false${handout ? ',handout' : ''}]{beamer}`,
+    `\\usetheme${scripts ? '[scripts]' : ''}{explico}`,
+    ...(handout ? ['\\setbeameroption{show notes}'] : []),
+    `\\ifdefined\\directlua\\pdfvariable trailerid {[<${trailer}><${trailer}>]}\\else\\pdftrailerid{${trailer}}\\fi`,
+    `\\title{${escapeText(deck.title)}}`,
+    `\\subtitle{${escapeText(course)}}`,
+    `\\author{${escapeText(authors || course)}}`,
+    `\\date{Content ${escapeText(version)}}`,
+    `\\hypersetup{pdftitle={${escapeText(deck.title)}},pdfauthor={${escapeText(authors || course)}},pdfsubject={${escapeText(course)}}}`,
+    '\\begin{document}',
+    '\\input{deck}',
+    '\\end{document}',
+    '',
+  ].join('\n');
+}
+
+function deckReadme(manifest: Manifest, deck: ManifestDeck, url: string | undefined): string {
+  const course = manifest.about.material.name;
+  return [
+    `# ${deck.title} — slides`,
+    '',
+    `The LaTeX source of a deck of *${course}*, ${versionPhrase(deck.since, manifest.about.knowledge.version)}.` +
+      (url ? ` Its interactive version: ${url}` : ''),
+    '',
+    '- `main.tex` — the slides: `latexmk` builds `main.pdf`.',
+    '- `handout.tex` — each slide followed by its speaker notes: `latexmk handout.tex`.',
+    '- `deck.tex` — the frames, which both read.',
+    '- `beamerthemeexplico.sty` — explico\'s beamer theme: the legend line, the frame number, the progress bar.',
+    '- `explico-common.sty` — what the theme shares with explico\'s book class: fonts, colours, figures,',
+    '  diagrams and the notation markers.',
+    '- `figures/` — the deck\'s figures, as vector PDF where the website draws them.',
+    '- `latexmkrc` — LuaLaTeX by default; `latexmk -pdf` uses pdfLaTeX.',
+    '',
+    'Beamer cannot write a tagged PDF: these PDFs are not accessible to a screen reader. The deck\'s',
+    'web page and its chapter\'s PDF are.',
+    '',
+  ].join('\n');
+}
+
+export interface DeckSourceInput {
+  readonly manifest: Manifest;
+  readonly deck: ManifestDeck;
+  readonly page: StaticDeck;
+  readonly checkItems: ChapterContext['checkItems'];
+  readonly pictures: ReadonlyMap<string, { readonly path: string; readonly content: Uint8Array }>;
+  readonly scripts?: boolean;
+}
+
+/** A deck's LaTeX folder, and where each of its frames ends in `deck.tex`. */
+export function deckSource(input: DeckSourceInput): { files: SourceFile[]; frameEnds: ReadonlyMap<number, number> } {
+  const { manifest, deck, page } = input;
+  const base = manifest.lessonExports.canonicalBaseUrl;
+  const url = base ? `${base}${deck.slug}/` : undefined;
+  const context = {
+    deck: page,
+    documentRoutes: new Set([page.route]),
+    ...(base ? { canonicalBaseUrl: base } : {}),
+    pictures: new Map([...input.pictures].map(([anchor, picture]) => [anchor, picture.path])),
+    checkItems: input.checkItems,
+  };
+  // The appendix lists the symbols the frames name, in order of first use;
+  // a second pass links each use to its entry.
+  const appendix = deckSymbols(context);
+  const serialized = serializeDeck({
+    ...context,
+    appendix,
+    notationTargets: new Set(appendix.map((entry) => entry.key)),
+  });
+  const scripts = input.scripts ?? needsScripts(serialized.tex);
+  const files: SourceFile[] = [
+    { path: 'main.tex', content: deckMain(manifest, deck, false, scripts) },
+    { path: 'handout.tex', content: deckMain(manifest, deck, true, scripts) },
+    { path: 'deck.tex', content: serialized.tex },
+    { path: 'beamerthemeexplico.sty', content: deckTheme() },
+    { path: 'explico-common.sty', content: explicoCommon() },
+    { path: 'latexmkrc', content: LATEXMKRC },
+    { path: 'README.md', content: deckReadme(manifest, deck, url) },
+    ...[...input.pictures.values()].map((picture) => ({ path: picture.path, content: picture.content })),
+  ];
+  return { files, frameEnds: serialized.frameEnds };
+}
+
+/**
+ * The frames LaTeX numbered differently from the deck page: each frame's
+ * `\label{frame:N}` must carry frame number N.
+ */
+export function deckNumberingProblems(aux: string, frames: number): string[] {
+  const numbers = new Map<number, number>();
+  for (const match of aux.matchAll(/\\newlabel\{frame:(\d+)\}\{\{(\d+)\}/gu)) {
+    numbers.set(Number(match[1]), Number(match[2]));
+  }
+  const problems: string[] = [];
+  for (let frame = 1; frame <= frames; frame += 1) {
+    const printed = numbers.get(frame);
+    if (printed === undefined) problems.push(`slide ${frame} has no frame in the PDF`);
+    else if (printed !== frame) problems.push(`slide ${frame} is frame ${printed} in the PDF`);
+  }
+  return problems;
+}
+
+/** The frames a beamer log says run over their slide, by `deck.tex` line: `{ frame, points }`. */
+export function deckOverflows(log: string, frameEnds: ReadonlyMap<number, number>): { frame: number; points: number }[] {
+  const ends = [...frameEnds].sort((a, b) => a[1] - b[1]);
+  const found = new Map<number, number>();
+  for (const match of log.matchAll(/Overfull \\vbox \(([\d.]+)pt too high\) detected at line (\d+)/gu)) {
+    const line = Number(match[2]);
+    const frame = ends.find(([, end]) => line <= end + 1)?.[0];
+    if (frame !== undefined) found.set(frame, Math.max(found.get(frame) ?? 0, Number(match[1])));
+  }
+  return [...found].map(([frame, points]) => ({ frame, points: Math.round(points) })).sort((a, b) => a.frame - b.frame);
+}