forked from EduCraft/curriculum-project-hub
feat(cph): implement nested outline manifest and batch/combined export
ADR-0029 — nested outline manifest, supersedes ADR-0008's flat [[parts]]:
- cph-model: recursive loader over manifest.toml containers / element.toml
leaves; Lesson.parts (pure elements, DFS order) + Lesson.outline (elements
interleaved with section headings at their DFS-open position); rejects
ambiguous/incomplete folders and root-vs-container table misplacement
- cph-diag: new DiagCode::ManifestMalformed for carrier-document structure
errors (discharges an existing TODO)
- cph-typst: augmented manifest now serializes the outline (element/section
entries) instead of a flat parts array
- render/lib.typ: render-lesson renders section headings at their depth
- examples/TH-141 migrated to 5 nested section containers + 3 root segments,
byte-identical element order; smoke-verified via cph check/build + pdftotext
ADR-0030 — batch & combined export, extends ADR-0009/0011:
- cph build with no --target batches every declared target (repeatable
--target for an explicit subset); any target failure => non-zero exit,
per-target ledger, independent per-target execution
- cph-model: bundle.toml loader (directory + [info]/[targets.*]/ordered
lessons with per-lesson target overrides)
- cph-typst: augmented bundle manifest (path-prefixed member outlines),
Engine::{compile_check_bundle,build_bundle_pdf}
- render/lib.typ: render-bundle assembles member lessons under per-lesson
headings, depth-shifts their own section headings, resets example/lemma
counters at each lesson boundary by default
- cph-cli: `cph bundle <path> --target <name>` subcommand, same batching
contract as `cph build`
- new bundle fixtures/tests (cph-model unit + cph-typst through-template PDF
compile), smoke-verified via a real 2-lesson merged PDF
Verification: cargo fmt/clippy/test clean across the workspace (68 tests);
real cph check/build/bundle runs against TH-141 and a bundle fixture, PDF
content inspected via pdftotext.
This commit is contained in:
+110
-18
@@ -1,14 +1,14 @@
|
||||
// cph-render — curriculum lesson render package.
|
||||
//
|
||||
// PUBLIC ENTRY: `render-lesson(info, target, parts, heading-numbering)`.
|
||||
// PUBLIC ENTRY: `render-lesson(info, target, outline, heading-numbering)`.
|
||||
//
|
||||
// MODEL (ADR-0011). A build compiles a *template file* (e.g. `exports/student.typ`)
|
||||
// as the typst main, with the manifest injected via `--input manifest=<path>`.
|
||||
// The template reads the manifest, loads each part's content, and calls
|
||||
// `render-lesson` here. Presentation (heading numbering) lives in the template,
|
||||
// not the manifest, not hardcoded-unreachable in this package — we only provide
|
||||
// the DEFAULT scheme (`default-heading-numbering`) for the template to use or
|
||||
// override.
|
||||
// MODEL (ADR-0011, outline shape per ADR-0029). A build compiles a *template
|
||||
// file* (e.g. `exports/student.typ`) as the typst main, with the manifest
|
||||
// injected via `--input manifest=<path>`. The template reads the manifest,
|
||||
// loads each **element** entry's content, and calls `render-lesson` here.
|
||||
// Presentation (heading numbering) lives in the template, not the manifest,
|
||||
// not hardcoded-unreachable in this package — we only provide the DEFAULT
|
||||
// scheme (`default-heading-numbering`) for the template to use or override.
|
||||
//
|
||||
// WHY THE TEMPLATE LOADS CONTENT, NOT US (the include-resolution finding):
|
||||
// typst resolves an `include`/`import` path relative to THE PACKAGE/FILE THE
|
||||
@@ -19,11 +19,15 @@
|
||||
// Therefore the dynamic-include LOOP must live in the TEMPLATE (which lives at
|
||||
// `<root>/exports/*.typ`, so `/<part.path>/<field>.typ` resolves against
|
||||
// `--root`). `render-lesson` is content-in: it takes an ALREADY-ASSEMBLED
|
||||
// `parts` array of dicts and never includes anything itself.
|
||||
// `outline` array of entry dicts and never includes anything itself.
|
||||
//
|
||||
// A part dict the template hands us:
|
||||
// `kind` plus that kind's content/scalar fields. Content field VALUES are
|
||||
// already-evaluated typst content (the template produced them via `include`).
|
||||
// An `outline` entry the template hands us is one of:
|
||||
// - an ELEMENT: `entry-type: "element"`, `kind` plus that kind's
|
||||
// content/scalar fields. Content field VALUES are already-evaluated typst
|
||||
// content (the template produced them via `include`).
|
||||
// - a SECTION (ADR-0029): `entry-type: "section"`, `title` (heading text),
|
||||
// `depth` (1-based heading level). Contributes no element; it is a
|
||||
// heading at its depth-first-open position in the outline.
|
||||
//
|
||||
// kind -> fields (MVP) — see `part-fields` below, which the template uses to
|
||||
// know what to load:
|
||||
@@ -41,7 +45,6 @@
|
||||
// unknown : rendered conservatively == student (show only required-public
|
||||
// fields). Never crashes. The "no render rule => warning"
|
||||
// diagnostic is the Rust side's job, not ours.
|
||||
|
||||
#import "src/style.typ": base-style, default-heading-numbering, title-block, subtitle-block
|
||||
#import "src/elements/segment.typ": display-segment
|
||||
#import "src/elements/example.typ": display-example
|
||||
@@ -106,14 +109,33 @@
|
||||
}
|
||||
}
|
||||
|
||||
/// Render one section-heading outline entry (ADR-0029): `entry.title` at
|
||||
/// `entry.depth` (1-based heading level).
|
||||
#let _render-section(entry) = {
|
||||
heading(level: entry.at("depth", default: 1))[#entry.at("title", default: "")]
|
||||
}
|
||||
|
||||
/// Render one outline entry: an element dispatches on `kind` via
|
||||
/// [`_render-part`]; a section (ADR-0029) renders its heading and contributes
|
||||
/// no element.
|
||||
#let _render-entry(entry, flags) = {
|
||||
if entry.at("entry-type", default: "element") == "section" {
|
||||
_render-section(entry)
|
||||
} else {
|
||||
_render-part(entry, flags)
|
||||
}
|
||||
}
|
||||
|
||||
/// THE ENTRY POINT — called by a template (`exports/*.typ`).
|
||||
///
|
||||
/// - `info`: dict, e.g. (title: "…", author: "…"). `author` may be absent.
|
||||
/// Templates typically pass `manifest.at("info", default: (:))`.
|
||||
/// - `target`: string. MVP: "student" | "teacher". Unknown => conservative.
|
||||
/// Each template hardcodes its own target (student.typ => "student").
|
||||
/// - `parts`: ordered array of part dicts, ALREADY ASSEMBLED by the template
|
||||
/// (content fields included, scalars read). See file header.
|
||||
/// - `outline`: ordered array of outline-entry dicts (ADR-0029), ALREADY
|
||||
/// ASSEMBLED by the template (element content fields included,
|
||||
/// scalars read; section entries carry `title`/`depth`). See file
|
||||
/// header for the entry shapes.
|
||||
/// - `heading-numbering`: array of per-level numbly pattern strings, e.g.
|
||||
/// `("{1:一}、", "{1:1}.{2:1}", "{1:1}.{2:1}.{3:1}")`. Presentation
|
||||
/// lives in the template (ADR-0011); the template passes its chosen
|
||||
@@ -122,7 +144,7 @@
|
||||
#let render-lesson(
|
||||
info: (:),
|
||||
target: "student",
|
||||
parts: (),
|
||||
outline: (),
|
||||
heading-numbering: default-heading-numbering,
|
||||
) = {
|
||||
let title = info.at("title", default: [])
|
||||
@@ -146,7 +168,77 @@
|
||||
subtitle-block(flags.subtitle)
|
||||
|
||||
// Render strictly in array order.
|
||||
for part in parts {
|
||||
_render-part(part, flags)
|
||||
for entry in outline {
|
||||
_render-entry(entry, flags)
|
||||
}
|
||||
}
|
||||
|
||||
/// Shift a section entry's `depth` by `delta`; an element entry passes through
|
||||
/// unchanged (elements carry no depth). Used by [`render-bundle`] to nest each
|
||||
/// lesson's own outline one level under that lesson's title heading.
|
||||
#let _shift-depth(entry, delta) = {
|
||||
if entry.at("entry-type", default: "element") == "section" {
|
||||
entry.depth = entry.depth + delta
|
||||
}
|
||||
entry
|
||||
}
|
||||
|
||||
/// THE BUNDLE ENTRY POINT (ADR-0030) — called by a bundle target's template
|
||||
/// (`exports/<target>.typ` under a `bundle.toml` root) to assemble several
|
||||
/// already-loaded lessons into one combined document.
|
||||
///
|
||||
/// - `info`: the bundle's own `[info]` (title/author of the 合集).
|
||||
/// - `lessons`: ordered array of `(info: .., target: .., outline: ..)` dicts —
|
||||
/// one per `bundle.toml` `lessons` entry, each ALREADY ASSEMBLED exactly as
|
||||
/// a single-lesson template would assemble it for [`render-lesson`].
|
||||
/// - `heading-numbering`: shared per-level numbering scheme across the whole
|
||||
/// bundle (ADR-0011 presentation-in-template stance; same knob as
|
||||
/// `render-lesson`).
|
||||
/// - `reset-counters`: whether `example`/`lemma` auto-counters reset at each
|
||||
/// lesson boundary. **Default `true`** (ADR-0030's recommended default: a
|
||||
/// lesson's internal "例题3" means that lesson's 例题3, so cross-lesson
|
||||
/// continuation would silently break author references). Pass `false` for
|
||||
/// a genuine "全书连续编号" 合集.
|
||||
///
|
||||
/// Each lesson's own outline is rendered under a depth-1 heading naming that
|
||||
/// lesson (`lesson.info.title`); the lesson's own section headings shift one
|
||||
/// level deeper (ADR-0029's per-lesson depths are relative to that lesson, so
|
||||
/// nesting under the lesson-title heading keeps the outline↔structure
|
||||
/// correspondence meaningful in the combined document). `@label`/`@ref`
|
||||
/// cross-references stay global across the whole compiled document (typst's
|
||||
/// ordinary behavior) regardless of `reset-counters`.
|
||||
#let render-bundle(
|
||||
info: (:),
|
||||
lessons: (),
|
||||
heading-numbering: default-heading-numbering,
|
||||
reset-counters: true,
|
||||
) = {
|
||||
let title = info.at("title", default: [])
|
||||
let author = info.at("author", default: none)
|
||||
|
||||
set document(
|
||||
title: title,
|
||||
author: if author == none { () } else { author },
|
||||
)
|
||||
|
||||
show: base-style.with(heading-numbering: heading-numbering)
|
||||
|
||||
title-block()
|
||||
v(1.2em, weak: true)
|
||||
|
||||
for lesson in lessons {
|
||||
if reset-counters {
|
||||
example-counter.update(0)
|
||||
lemma-counter.update(0)
|
||||
}
|
||||
|
||||
let flags = _flags-for(lesson.at("target", default: "student"))
|
||||
let lesson-info = lesson.at("info", default: (:))
|
||||
|
||||
heading(level: 1)[#lesson-info.at("title", default: [])]
|
||||
|
||||
for entry in lesson.at("outline", default: ()) {
|
||||
_render-entry(_shift-depth(entry, 1), flags)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user