forked from EduCraft/curriculum-project-hub
feat(render): export templates + render-lesson entry; template owns include loop (WU-C', ADR-0011)
Replace the display(parts) entry (which a generated driver called) with the
template model: real editable templates (render/templates/{student,teacher}.typ,
the framework defaults copied into an engineering file's exports/) read the
manifest via toml(sys.inputs.manifest) and assemble parts themselves.
Key finding (drives the engine): a dynamic `include` inside a package resolves
against the PACKAGE root, never --root — so the include loop must live in the
TEMPLATE (which sits under --root): `include "/" + part.path + "/" + field +
".typ"` (root-relative absolute, runtime-computed — legal per ADR-0011's verified
fact). cph-render exposes render-lesson(info, target, parts, heading-numbering)
(content-in, never includes) + part-fields (kind→fields) + default-heading-numbering.
Numbering (numbly per-level) is set in the template, editable per engineering file.
Surfaced OPEN point closed by the engine (WU-D'): typst has no file-exists
primitive, so optional content (lemma proof) presence comes from a per-part
`fields` array the engine computes from disk. Manifest injected as root-relative
absolute (--input manifest=/...). numbly stays vendored/offline. display removed.
local-packages symlink (test-only @local resolution) gitignored — regenerable,
self-referential; the embedded engine mounts cph-render directly.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,63 @@
|
||||
# Default export templates (ADR-0011)
|
||||
|
||||
`student.typ` / `teacher.typ` are the **framework default templates**. In a real
|
||||
engineering file they live at `exports/student.typ` / `exports/teacher.typ`; the
|
||||
project-creation flow seeds copies there (out of scope here — see ADR-0011 Open
|
||||
Questions). They are kept here as the canonical, copyable defaults and for the
|
||||
offline smoke test below.
|
||||
|
||||
Each template:
|
||||
|
||||
1. reads the injected manifest: `toml(sys.inputs.manifest)`;
|
||||
2. loops `manifest.parts`, `include`-ing each content field via a computed
|
||||
**root-relative absolute** path `/<part.path>/<field>.typ`, and reading scalar
|
||||
fields (example `source`) from `/<part.path>/element.toml`;
|
||||
3. assembles a `parts` array and calls `cph-render`'s `render-lesson(...)`,
|
||||
passing the per-level heading numbering (presentation lives in the template).
|
||||
|
||||
## Why the include loop is in the template, not in cph-render
|
||||
|
||||
typst resolves a dynamic `include`/`toml` path relative to **the file the call
|
||||
lexically appears in**, and a package (`@local/cph-render`) has its **own virtual
|
||||
root**. A dynamic `include` written inside the package resolves against the
|
||||
*package* dir — even an absolute `/segments/x.typ` — never the engineering
|
||||
`--root`. Verified empirically. The template lives under `--root`, so its
|
||||
`/<part.path>/<field>.typ` resolves against `--root`. Hence the template loads
|
||||
content and hands `render-lesson` an already-assembled `parts` array;
|
||||
`render-lesson` never includes anything.
|
||||
|
||||
## Key path facts for the engine
|
||||
|
||||
- **Template is the typst main file.** Compile it directly.
|
||||
- **`--root` = engineering-file root.** Content `include`s use absolute
|
||||
root-relative paths.
|
||||
- **Manifest is injected as a root-relative ABSOLUTE path**:
|
||||
`--input manifest=/manifest.toml`. `toml(sys.inputs.manifest)` resolves
|
||||
relative to the *template's* location (`exports/`), so a bare
|
||||
`manifest=manifest.toml` would look in `exports/`. Pass the leading `/`.
|
||||
- **Optional content presence** (lemma `proof`): typst has no file-exists
|
||||
primitive, so the template cannot probe disk. It reads a per-part `fields`
|
||||
array from the manifest listing the content fields present on disk. *(OPEN: the
|
||||
exact manifest shape for this is for the Rust/manifest contract to pin.)*
|
||||
|
||||
## Offline smoke test
|
||||
|
||||
`@local/cph-render` is resolved from a local-packages dir (a symlink to the
|
||||
render package root — regenerable, test-only):
|
||||
|
||||
```sh
|
||||
cd render
|
||||
# one-time: make @local/cph-render resolvable offline
|
||||
mkdir -p vendor/local-packages/local/cph-render
|
||||
ln -sfn "$(pwd)" vendor/local-packages/local/cph-render/0.1.0
|
||||
|
||||
# compile a template against the smoke engineering file
|
||||
typst compile --root examples/smoke-eng \
|
||||
--package-path ./vendor/local-packages \
|
||||
--package-cache-path ./vendor/typst-packages \
|
||||
--input manifest=/manifest.toml \
|
||||
examples/smoke-eng/exports/student.typ /tmp/cph-tmpl-student.pdf
|
||||
```
|
||||
|
||||
(`examples/smoke-eng/exports/{student,teacher}.typ` are copies of the defaults
|
||||
here, mirroring how a real engineering file carries its own templates.)
|
||||
Reference in New Issue
Block a user