forked from bai/curriculum-project-hub
docs(adr): add ADR-0011 (export builds = typed steps over templates), correct ADR-0008
Refines ADR-0009 by fixing the shape of an artifact and a build; corrects a
false premise that propagated into the implementation.
ADR-0011:
- Artifact is an ADT WITH fields: SingleFile{filepath} / FileTree{root,
outputs:glob} — the product semantics (one file where, vs a tree of what) are
pinned, not erased behind a bare tag.
- A target = artifact + ordered typed steps: typstCompile{template} (typed
because the framework wires the manifest in — not a raw shell line) | shell{run}
(the hatch where ADR-0005 category-b medium-only builds land).
- Presentation (numbly numbering, styling) lives in the template file
(exports/<target>.typ), NOT the manifest; manifest [targets.*.numbering] removed.
- Correction (verified against typst source: typst-eval/src/import.rs:22,174;
tests/suite/scripting/include.typ): include/import paths MAY be runtime-computed
(only a bare `import expr` without `as` is restricted). So the framework does
NOT generate a static-include driver — a template toml()-reads the manifest and
includes each part via a computed path. Removes a whole generated layer.
- RenderRule-as-payload retired; coverage downgraded to a declaration (which
kinds a target renders) feeding the unchanged renderIgnored warning.
ADR-0008: corrected the two clauses (the "generated driver / static #import"
wording) that were residue of the false premise, pointing them at the
template-injection model and citing ADR-0011.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -87,7 +87,9 @@ MVP kind set: `segment` ⇒ `textbook.typ`; `example` ⇒ `problem.typ`,
|
||||
`solution.typ`; `lemma` ⇒ `stmt.typ`, `proof.typ`; `sop` ⇒ `sop.typ`. This
|
||||
**drops the samples' per-element `main.typ`** (`#let textbook = include …`):
|
||||
that field-to-file wiring is now implied by the schema + naming convention and
|
||||
materialized by the generated driver, not hand-authored.
|
||||
materialized at build time by the export template, not hand-authored. (Originally
|
||||
this said "the generated driver"; ADR-0011 supersedes that — there is no generated
|
||||
driver, an export template reads the manifest and includes each part's content.)
|
||||
|
||||
A `content` field's denotation remains ADR-0006's: the **module body content**
|
||||
of `F.typ`, not its `#let` exports. The file sits at a real relative path
|
||||
@@ -99,9 +101,12 @@ of `F.typ`, not its `#let` exports. The file sits at a real relative path
|
||||
- The checker recovers the full ordered lesson from `manifest.toml` + each
|
||||
`element.toml` without evaluating any typst — order and membership are plain
|
||||
data, diffable and greppable.
|
||||
- A typst driver entrypoint (static `#import`s + the render call) becomes a
|
||||
*generated artifact* the renderer produces from the manifest per target; it is
|
||||
never the canonical lesson and is not hand-edited.
|
||||
- A per-target **export template** (a real, editable `.typ` file, e.g.
|
||||
`exports/student.typ`) reads the manifest and renders the lesson; it is the
|
||||
build entrypoint, not the canonical lesson. (This clause originally described a
|
||||
*generated* driver with static `#import`s, on a since-corrected belief that
|
||||
typst forbids runtime-computed include paths — see ADR-0011's *Correction*.
|
||||
Include/import paths may be computed, so no driver is generated.)
|
||||
- Element folders lose their per-element `main.typ`; `element.toml` + the schema's
|
||||
content-file convention replace it. Migrating the samples is a mechanical
|
||||
rewrite (the migration is part of the MVP).
|
||||
|
||||
Reference in New Issue
Block a user