explico 0.12.0 → 0.13.0

package/dist/compiler/exports/latex/document.d.ts

@@ -0,0 +1,102 @@
+import { ManifestLesson, ManifestPart, Manifest } from '../../manifest.js';
+import { StaticPage } from '../static-tree.js';
+import { CheckItem } from './serialize.js';
+import '../../../curriculum/validation.js';
+import '../../../reference/consistency.js';
+import '../../../course-config-rRtME5UV.js';
+import '../../../rules/catalog.js';
+import '../../../rules/course-rules.js';
+import '../../collections.js';
+import '../../../reference/types.js';
+import '../../../reference/gate-retired-keys.js';
+import '../../../reference/lint-ignore.js';
+import '../../../reference/equations-validate.js';
+import '../../../reference/tables-validate.js';
+import '../../../reference/keyed-float-validate.js';
+import '../../../reference/figures-validate.js';
+import '../../../reference/diagrams-validate.js';
+import '../../../reference/examples-validate.js';
+import '../../../reference/folds-validate.js';
+import '../../../reference/knowledge-checks-validate.js';
+import '../../../reference/raw-floats-validate.js';
+import '../../../reference/lab-katex-validate.js';
+import '../../../reference/gate-math.js';
+import '../../../reference/mixed-content.js';
+import '../../../reference/gloss.js';
+import '../../../rules/waivers.js';
+import '../../knowledge-version.js';
+import '../../lesson-derivation.js';
+import '../html-tree.js';
+import 'parse5';
+
+/**
+ * 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.
+ */
+interface SourceFile {
+    readonly path: string;
+    readonly content: string | Uint8Array;
+}
+/** explico's class, shipped next to this module (copied into `dist/` by `copy-assets`). */
+declare function explicoClass(): string;
+/** `parts/02-projectiles/02-optimal-launch-angle.tex` for chapter 2.2. */
+declare function chapterPath(manifest: Pick<Manifest, 'parts'>, lesson: ManifestLesson): string;
+/** The folder name a chapter's download unzips to. */
+declare function chapterFolderName(lesson: ManifestLesson): string;
+/** A chapter's check answers, by assessment id, in authored order. */
+declare function checkItems(manifest: Pick<Manifest, 'assessmentContent'>, lesson: Pick<ManifestLesson, 'id'>): Map<string, CheckItem[]>;
+/**
+ * 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.
+ */
+declare function trailerId(manifest: Pick<Manifest, 'about'>, document: string): string;
+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. */
+declare function chapterSource(input: ChapterSourceInput): SourceFile[];
+/** A chapter of a book, with its figure files. */
+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. */
+interface BookPart {
+    readonly part: ManifestPart;
+    readonly overview?: StaticPage;
+    readonly chapters: readonly BookChapter[];
+}
+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 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.
+ */
+declare function bookSource(input: BookSourceInput): SourceFile[];
+
+export { type BookChapter, type BookPart, type BookSourceInput, type ChapterSourceInput, type SourceFile, bookSource, chapterFolderName, chapterPath, chapterSource, checkItems, explicoClass, trailerId };

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

@@ -0,0 +1,349 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import {
+  escapeText,
+  serializeAbbreviationAppendix,
+  serializeChapter,
+  serializeNotationAppendix,
+  serializePartOpener
+} from "./serialize.js";
+function explicoClass() {
+  return readFileSync(new URL("./explico.cls", import.meta.url), "utf8");
+}
+function twoDigits(value) {
+  return String(value).padStart(2, "0");
+}
+function chapterPath(manifest, lesson) {
+  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`;
+}
+function chapterFolderName(lesson) {
+  return `${lesson.slug.split("/").at(-1) ?? lesson.slug}-latex`;
+}
+function checkItems(manifest, lesson) {
+  const items = /* @__PURE__ */ new Map();
+  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;
+}
+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"
+];
+function trailerId(manifest, document) {
+  return createHash("md5").update(`${manifest.about.material.name}
+${manifest.about.knowledge.version}
+${document}`).digest("hex").toUpperCase();
+}
+function trailerIdLine(id) {
+  return `\\ifdefined\\directlua\\pdfvariable trailerid {[<${id}><${id}>]}\\else\\pdftrailerid{${id}}\\fi`;
+}
+function mainTex(manifest, lesson, chapterFile) {
+  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.authors?.map((author) => author.name).filter((name) => !!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, lesson, url) {
+  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` \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).",
+    `- \`${chapterPath(manifest, lesson)}\` \u2014 the chapter.`,
+    "- `figures/` \u2014 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");
+}
+function chapterSource(input) {
+  const { manifest, lesson, page } = input;
+  const file = chapterPath(manifest, lesson);
+  const base = manifest.lessonExports.canonicalBaseUrl;
+  const url = base ? `${base}${lesson.slug}/` : void 0;
+  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 }))
+  ]);
+}
+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 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, "")))
+  );
+  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 countNumbered(parts, kind) {
+  let count = 0;
+  const visit = (blocks) => {
+    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);
+      }
+    }
+  };
+  for (const { chapters } of parts) for (const { page } of chapters) visit(page.blocks);
+  return count;
+}
+function appendixNotation(manifest, parts) {
+  const local = /* @__PURE__ */ new Map();
+  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 = /* @__PURE__ */ new Set();
+  const entries = [];
+  const add = (page) => {
+    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, inputs, appendices) {
+  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.authors?.map((author) => author.name).filter((name) => !!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) {
+  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` \u2014 the book: title page, contents, lists of figures, tables and",
+    "  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).",
+    "- `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.",
+    "- `figures/` \u2014 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");
+}
+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] : [],
+      ...chapters.map(({ page }) => page.route)
+    ])
+  );
+  const notationTargets = new Set(appendixNotation(manifest, parts).map(({ entry }) => entry.key));
+  const common = { documentRoutes, canonicalBaseUrl, inBook: true, notationTargets };
+  const files = [];
+  const inputs = [];
+  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: /* @__PURE__ */ new Map(), checkItems: /* @__PURE__ */ new Map() }, part) : `\\ExplicoPart{${part.ordinal}}{${escapeText(part.label)}}
+`
+    });
+    inputs.push(partFile);
+    for (const { lesson, page, pictures } of chapters) {
+      const file = chapterPath(manifest, lesson);
+      const url = canonicalBaseUrl ? `${canonicalBaseUrl}${lesson.slug}/` : void 0;
+      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 = [];
+  const notation = serializeNotationAppendix(appendixNotation(manifest, parts), {
+    ...common,
+    pictures: /* @__PURE__ */ new Map(),
+    checkItems: /* @__PURE__ */ 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
+  ]);
+}
+export {
+  bookSource,
+  chapterFolderName,
+  chapterPath,
+  chapterSource,
+  checkItems,
+  explicoClass,
+  trailerId
+};