explico 0.11.1 → 0.13.0

package/dist/compiler/exports/latex-export.js

@@ -0,0 +1,169 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { availableParallelism } from "node:os";
+import { dirname, extname, join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
+import { zip } from "./zip.js";
+import {
+  consoleLogger,
+  epochOf,
+  figuresOf,
+  imageFile,
+  needsCapture,
+  prepareChapters,
+  readBuiltPage,
+  strictMode
+} from "./export-chapters.js";
+import { compileLatex, missingCharacters, findLatexEngine } from "./latex/compile.js";
+import { bookSource, chapterFolderName, chapterSource } from "./latex/document.js";
+import { courseFileStem } from "./export-pages.js";
+import { auxLabels, numberingMismatches, websiteNumbers } from "./latex/numbering.js";
+async function pagePictures(outputRoot, base, page, captured) {
+  const pictures = /* @__PURE__ */ new Map();
+  for (const figure of figuresOf(page.blocks)) {
+    const capturedFigure = captured?.get(figure.anchor);
+    if (capturedFigure) {
+      pictures.set(figure.anchor, {
+        path: `figures/${page.route}/${figure.anchor}.pdf`,
+        content: capturedFigure.pdf
+      });
+      continue;
+    }
+    if (figure.picture.kind !== "image" || needsCapture(figure)) continue;
+    const file = imageFile(outputRoot, base, page.route, figure.picture.src);
+    pictures.set(figure.anchor, {
+      path: `figures/${page.route}/${figure.anchor}${extname(file).toLowerCase()}`,
+      content: await readFile(file)
+    });
+  }
+  return pictures;
+}
+async function mapWithLimit(items, limit, work) {
+  const results = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await work(items[index]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+  return results;
+}
+async function writeLatexExports(directory, manifest, options = {}) {
+  if (!manifest.lessonExports.latex) return;
+  const logger = options.logger ?? consoleLogger;
+  const strict = strictMode();
+  const outputRoot = fileURLToPath(directory);
+  const { base, chapters, captures } = options.prepared ?? await prepareChapters(outputRoot, manifest, { logger, projectRoot: options.projectRoot });
+  const engine = await findLatexEngine();
+  if ("missing" in engine) {
+    if (strict) throw new Error(`LaTeX export cannot build PDFs: ${engine.missing}`);
+    logger.warn(`LaTeX export: writing the source zips only. ${engine.missing}`);
+  }
+  const jobs = [];
+  const pictures = /* @__PURE__ */ new Map();
+  for (const { lesson, page } of chapters) {
+    const chapterPictures = await pagePictures(outputRoot, base, page, captures.get(page.route));
+    pictures.set(lesson.id, chapterPictures);
+    jobs.push({
+      kind: "chapter",
+      name: lesson.slug,
+      files: chapterSource({ manifest, lesson, page, documentRoutes: /* @__PURE__ */ new Set([page.route]), pictures: chapterPictures }),
+      target: lesson.slug,
+      folder: chapterFolderName(lesson),
+      website: websiteNumbers(page, `${lesson.part}.${lesson.chapter}`)
+    });
+  }
+  const byId = new Map(chapters.map((chapter) => [chapter.lesson.id, chapter]));
+  const pageSlugs = new Set(manifest.pages.map((page) => page.slug));
+  const parts = [];
+  for (const part of manifest.parts) {
+    const partChapters = part.lessons.flatMap((id) => {
+      const chapter = byId.get(id);
+      return chapter ? [{ ...chapter, pictures: pictures.get(id) }] : [];
+    });
+    if (partChapters.length === 0) continue;
+    const overview = pageSlugs.has(`${part.dir}/index`) ? (await readBuiltPage(outputRoot, `${part.dir}/index`)).page : void 0;
+    parts.push({ part, ...overview ? { overview } : {}, chapters: partChapters });
+  }
+  const bookNumbers = (bookParts) => new Map(
+    bookParts.flatMap(
+      ({ chapters: partChapters }) => partChapters.flatMap(({ lesson, page }) => [...websiteNumbers(page, `${lesson.part}.${lesson.chapter}`)])
+    )
+  );
+  const course = manifest.about.material.name;
+  for (const entry of parts) {
+    jobs.push({
+      kind: "part",
+      name: `part/${entry.part.dir}`,
+      files: bookSource({
+        manifest,
+        parts: [entry],
+        document: `part/${entry.part.dir}`,
+        title: entry.part.label,
+        subtitle: `Part ${entry.part.ordinal} of ${course}`
+      }),
+      target: `part/${entry.part.dir}`,
+      folder: `${entry.part.dir}-latex`,
+      website: bookNumbers([entry])
+    });
+  }
+  if (parts.length > 0) {
+    jobs.push({
+      kind: "course",
+      name: "course",
+      files: bookSource({ manifest, parts, document: "course", title: course }),
+      target: "course",
+      folder: `${courseFileStem(manifest)}-latex`,
+      website: bookNumbers(parts)
+    });
+  }
+  const pending = jobs.map((job) => ({
+    target: join(outputRoot, "downloads", `${job.target}-latex.zip`),
+    content: zip(job.files.map((file) => ({ path: `${job.folder}/${file.path}`, content: file.content })))
+  }));
+  const durations = [];
+  const started = performance.now();
+  if (!("missing" in engine)) {
+    const compiled = await mapWithLimit(jobs, availableParallelism(), async (job) => {
+      const jobStarted = performance.now();
+      const result = await compileLatex(job.files, engine, { epoch: epochOf(manifest), name: job.name });
+      durations.push({ kind: job.kind, seconds: (performance.now() - jobStarted) / 1e3 });
+      const problems = numberingMismatches(job.website, auxLabels(result.aux));
+      if (problems.length > 0) {
+        throw new Error(`LaTeX numbers ${job.name} differently from the website:
+  ${problems.join("\n  ")}`);
+      }
+      const missing = job.kind === "chapter" ? missingCharacters(result.log) : [];
+      if (missing.length > 0) {
+        logger.warn(
+          `LaTeX export: the PDF of ${job.name} leaves ${missing.length} character(s) blank, which its fonts cannot draw: ${missing.slice(0, 12).join(", ")}${missing.length > 12 ? ", \u2026" : ""}. The web page shows them, the PDF does not. Under LuaLaTeX, install a font that covers them on the build machine (explico.cls looks for CMU Serif, Noto Serif or DejaVu Serif for Greek, Noto CJK or Fandol for Chinese, Japanese and Korean, and Noto Color Emoji for emoji); pdfLaTeX sets none of them. Or write the word in Latin script, or a symbol as math ($\\alpha$).`
+        );
+      }
+      return result.pdf;
+    });
+    jobs.forEach((job, index) => {
+      pending.push({ target: join(outputRoot, "downloads", `${job.target}.pdf`), content: compiled[index] });
+    });
+  }
+  const wall = (performance.now() - started) / 1e3;
+  const temporary = pending.map((file) => ({ ...file, temporary: `${file.target}.tmp-${process.pid}` }));
+  try {
+    for (const file of temporary) {
+      await mkdir(dirname(file.target), { recursive: true });
+      await writeFile(file.temporary, file.content);
+    }
+    for (const file of temporary) await rename(file.temporary, file.target);
+  } finally {
+    await Promise.all(temporary.map((file) => rm(file.temporary, { force: true })));
+  }
+  const pdfs = pending.filter((file) => file.target.endsWith(".pdf")).length;
+  const seconds = (kind) => durations.filter((entry) => entry.kind === kind).reduce((sum, entry) => sum + entry.seconds, 0);
+  logger.info(
+    `LaTeX export: ${chapters.length} chapter(s), ${parts.length} part(s)${parts.length > 0 ? " and the course" : ""}: ${jobs.length} source zip(s)` + (pdfs > 0 ? `, ${pdfs} PDF(s) with ${"name" in engine ? engine.name : ""} in ${wall.toFixed(1)} s on up to ${availableParallelism()} core(s) (compile time: chapters ${seconds("chapter").toFixed(1)} s, parts ${seconds("part").toFixed(1)} s, course ${seconds("course").toFixed(1)} s)` : "") + (captures.size > 0 ? `, figures from ${captures.size} page(s) drawn as vector PDF` : "") + "."
+  );
+}
+export {
+  writeLatexExports
+};

package/dist/compiler/exports/markdown/serialize.d.ts

@@ -0,0 +1,51 @@
+import { RootContent } from 'mdast';
+import { CheckItem } from '../latex/serialize.js';
+import { StaticPage, DiagramGeometry } from '../static-tree.js';
+import '../../../reference/mixed-content.js';
+import '../../../reference/gate-math.js';
+import '../../../reference/types.js';
+import '../html-tree.js';
+import 'parse5';
+
+/**
+ * Serialize explico's static reading tree to Markdown: GitHub's flavour, with
+ * `$…$` and `$$…$$` math for remark-math, KaTeX or MathJax (decisions D2, D3).
+ * It builds an mdast tree and lets `mdast-util-to-markdown` write it, so every
+ * character that means something to Markdown is escaped where it must be.
+ *
+ * What a reader of the file needs from the website comes along as text: each
+ * heading and float keeps its number, a display equation its `\tag{…}`, and
+ * every anchor an `<a id>` the links in the file land on. A reference into a
+ * page of the same download is a link into its file; any other goes to the
+ * website. The author's `\explain{key}{…}` markers are stripped from the
+ * math. Memos, notes, examples and checks are titled quotes, always open;
+ * Starlight's asides are GitHub alerts; each chapter ends with its
+ * references, its notation and the answers to its checks.
+ */
+interface MarkdownChapterContext {
+    readonly page: StaticPage;
+    /** Every page of this download by route, with its file relative to this one (`''` for this file). */
+    readonly documentFiles: ReadonlyMap<string, string>;
+    /** Published course root, for links that leave the download. */
+    readonly canonicalBaseUrl?: string;
+    /** Picture files written for this page, by float anchor or image `src`, relative to this file. */
+    readonly pictures: ReadonlyMap<string, string>;
+    /** Answers of this page's checks, by assessment id, in authored order. */
+    readonly checkItems: ReadonlyMap<string, readonly CheckItem[]>;
+    /** Course title, version and the page's live URL, for the line under its title. */
+    readonly source?: {
+        readonly course: string;
+        readonly version?: string;
+        readonly url?: string;
+    };
+}
+/** Each edge of a diagram as the boxes it joins: the nearest box to each end. */
+declare function diagramEdges(geometry: DiagramGeometry): [number, number][];
+/** The Markdown of one page: its title, its body, references, notation and answers. */
+declare function serializeMarkdownPage(context: MarkdownChapterContext, options?: {
+    readonly number?: string;
+}): string;
+/** Markdown of a few blocks of mdast, written the same way (for a download's `index.md`). */
+declare function serializeMarkdownNodes(children: RootContent[]): string;
+
+export { type MarkdownChapterContext, diagramEdges, serializeMarkdownNodes, serializeMarkdownPage };