forked from EduCraft/curriculum-project-hub
白
76 lines
3.7 KiB
Markdown
76 lines
3.7 KiB
Markdown
# Default export templates (ADR-0011, outline shape ADR-0036)
|
|
|
|
`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.outline` (ADR-0036's depth-first rendering order — elements
|
|
interleaved with section headings at their DFS-open position). For an
|
|
`type = "element"` entry: `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`. For a
|
|
`type = "section"` entry: passing its `title`/`depth` straight through — no
|
|
content to load, it is a heading;
|
|
3. assembles an `outline` array of entry dicts 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 `outline` 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-element
|
|
`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.)*
|
|
- **Sections carry no content fields.** A `type = "section"` outline entry
|
|
(ADR-0036) has only `kind`/`title`/`depth`/`path`; the template passes it
|
|
through untouched — no `include`, no `element.toml` read.
|
|
|
|
## 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. The
|
|
`examples/smoke-eng/manifest.toml` is hand-authored directly in the augmented
|
|
`[[outline]]` shape that `cph_typst::build_augmented_manifest` would otherwise
|
|
produce, since this smoke test bypasses the Rust engine entirely.)
|