explico 0.12.0 → 0.13.1

package/src/compiler/exports/latex/texlive-packages.txt

@@ -0,0 +1,76 @@
+# TeX Live 2026 packages for explico's LaTeX export, for the package_file of
+# zauguin/install-texlive; tlmgr adds each one's dependencies. This is what a
+# chapter reads under LuaLaTeX and pdfLaTeX (latexmk -recorder), less what
+# latex-bin brings. Package names change between TeX Live years: check the
+# list again when moving texlive_version.
+
+# Engines, formats, build tool
+latex-bin
+latexmk
+
+# Latin Modern text and math
+lm
+lm-math
+cm-unicode  # optional: Greek and Cyrillic prose in Latin Modern's design (CMU Serif)
+
+# Tagged PDF 2.0 with MathML
+latex-lab
+luamml
+pdfmanagement
+tagpdf
+
+# explico.cls
+adjustbox
+alphalph
+amsfonts
+booktabs
+caption
+ec
+enumitem
+float  # optional in the class, but without it an in-box float loses its tagged caption
+geometry
+hyperref
+iftex
+lualatex-math
+mathtools
+microtype
+newfloat
+newunicodechar
+pgf
+tcolorbox
+unicode-math
+xcolor
+
+# What those load
+amscls
+bigintcalc
+bitset
+bookmark
+collectbox
+environ
+etoolbox
+fontspec
+footmisc
+gettitlestring
+hycolor
+ifoddpage
+infwarerr
+intcalc
+kvdefinekeys
+kvoptions
+kvsetkeys
+l3packages
+listings
+listingsutf8
+ltxcmds
+mptopdf
+pdfcol
+pdfescape
+pdftexcmds
+refcount
+stringenc
+tikzfill
+trimspaces
+url
+varwidth
+xkeyval

package/src/compiler/exports/latex-export.ts

@@ -0,0 +1,255 @@
+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 type { Manifest } from '../manifest';
+import type { StaticPage } from './static-tree';
+import { zip } from './zip';
+import {
+  consoleLogger,
+  epochOf,
+  figuresOf,
+  imageFile,
+  needsCapture,
+  prepareChapters,
+  readBuiltPage,
+  strictMode,
+  type ExportLogger,
+  type PreparedChapters,
+} from './export-chapters';
+import { compileLatex, missingCharacters, findLatexEngine } from './latex/compile';
+import { bookSource, chapterFolderName, chapterSource, type BookPart, type SourceFile } from './latex/document';
+import { courseFileStem } from './export-pages';
+import { auxLabels, numberingMismatches, websiteNumbers } from './latex/numbering';
+
+export type { ExportLogger } from './export-chapters';
+
+/**
+ * The LaTeX export (`lessonExports.latex`): after Astro's static build, each
+ * chapter's source folder — `main.tex`, `explico.cls`, the chapter and its
+ * figures — is zipped to `downloads/<slug>-latex.zip`, and the same folder is
+ * compiled to `downloads/<slug>.pdf`. Each part and the course are books
+ * (`bookSource`): `downloads/part/<dir>-latex.zip` and `.pdf`,
+ * `downloads/course-latex.zip` and `.pdf`. Every document compiles at once,
+ * up to one per core.
+ *
+ * The build fails when a compiled number differs from the website's, when
+ * LaTeX reports an error, and — in CI (`CI` set) or with
+ * `EXPLICO_LATEX_STRICT=1` — when the TeX engine or the browser for figures
+ * is missing. On a developer's machine without them it warns and still
+ * writes the source zips.
+ */
+
+async function pagePictures(
+  outputRoot: string,
+  base: string,
+  page: StaticPage,
+  captured: ReadonlyMap<string, { pdf: Uint8Array }> | undefined,
+): Promise<Map<string, { path: string; content: Uint8Array }>> {
+  const pictures = new Map<string, { path: string; content: Uint8Array }>();
+  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;
+}
+
+interface PendingFile {
+  readonly target: string;
+  readonly content: Uint8Array;
+}
+
+/** `work` over every item, at most `limit` at a time; results in the items' order. */
+async function mapWithLimit<T, R>(items: readonly T[], limit: number, work: (item: T) => Promise<R>): Promise<R[]> {
+  const results: R[] = 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;
+}
+
+/**
+ * Write each chapter's, each part's and the course's LaTeX source zip and PDF
+ * under `downloads/`, from the chapters `prepareChapters` read and drew (read
+ * here when not given).
+ */
+export async function writeLatexExports(
+  directory: URL,
+  manifest: Manifest,
+  options: {
+    readonly logger?: ExportLogger;
+    readonly projectRoot?: string;
+    readonly prepared?: PreparedChapters;
+  } = {},
+): Promise<void> {
+  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}`);
+  }
+
+  /** One LaTeX document: its folder, where its zip and PDF go, and the numbers it must print. */
+  interface Job {
+    readonly kind: 'chapter' | 'part' | 'course';
+    readonly name: string;
+    readonly files: SourceFile[];
+    readonly target: string;
+    readonly folder: string;
+    readonly website: Map<string, string>;
+  }
+  const jobs: Job[] = [];
+  const pictures = new Map<string, Awaited<ReturnType<typeof pagePictures>>>();
+  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: new Set([page.route]), pictures: chapterPictures }),
+      target: lesson.slug,
+      folder: chapterFolderName(lesson),
+      website: websiteNumbers(page, `${lesson.part}.${lesson.chapter}`),
+    });
+  }
+
+  // Each part, and the course, as a book (plan step 6).
+  const byId = new Map(chapters.map((chapter) => [chapter.lesson.id, chapter]));
+  const pageSlugs = new Set(manifest.pages.map((page) => page.slug));
+  const parts: BookPart[] = [];
+  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
+      : undefined;
+    parts.push({ part, ...(overview ? { overview } : {}), chapters: partChapters });
+  }
+  const bookNumbers = (bookParts: readonly BookPart[]) =>
+    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: PendingFile[] = 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 }))),
+  }));
+
+  // Compile every document at once, up to one per core; a book numbers
+  // every chapter, so each is checked against the website whole.
+  const durations: { kind: Job['kind']; seconds: number }[] = [];
+  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) / 1000 });
+      const problems = numberingMismatches(job.website, auxLabels(result.aux));
+      if (problems.length > 0) {
+        throw new Error(`LaTeX numbers ${job.name} differently from the website:\n  ${problems.join('\n  ')}`);
+      }
+      // A part's and the course's PDFs repeat their chapters' text, so each
+      // character is reported once, by the chapter that has it.
+      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 ? ', …' : ''}. 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) / 1000;
+
+  // Nothing is published until every document has compiled and matched.
+  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: Job['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` : '') +
+      '.',
+  );
+}