Expand description
Portable document model — what engines produce. Portable document model — what engines produce.
This module defines the universal semantic shape every engine renders into. The model carries:
- Structure:
Block/InlineSpan(headings, paragraphs, lists, links, etc.) — what content there is. - Semantic intent:
FeedHeader,FeedEntry,MetadataRow,Badge— when a source format has block-level meaning beyond “this is a paragraph”, the engine can name it. Intelligence layers downstream (search, summarise, recommend, recall) match on these intents, not just text. - Provenance: where the content came from (canonical URI, source engine, fetch time, source label).
- Trust state: how authenticated the source is (Trusted / Tofu / Insecure / Broken / Unknown).
- Diagnostics: parser / render warnings the engine wants to surface (unsupported construct, degraded rendering, parse warnings).
§Spec faithfulness
Protocol engines (gemini, gopher, RSS/Atom, finger) populate semantic
variants only when the source spec actually says them — RSS <item>
becomes FeedEntry, finger Login: alice becomes MetadataRow. The
engines do not invent semantics the spec doesn’t say. File-format
engines (markdown, the knot note format) can be richer because the
format owns its own semantics.
§Round-trip
EngineDocument::to_markdown and EngineDocument::to_gemini live
in the render submodule and let clips / notes export back into native
CommonMark / gemtext.
Structs§
- Block
Evaluators - The host’s eval menu: the
BlockEvaluators it ships, keyed by language. Routing a fence’s tag to a backend is the polyglot seam — register the languages you trust on this build, and an unknown tag simply isn’t found (the evaluate pass denies it). - Block
Provenance - Provenance for a single block within an
crate::EngineDocument. - Block
Provenance Map - Sparse map from
crate::EngineDocument::blocksindex to a per-block provenance override. - Document
Provenance - Where the document came from.
- Engine
Document - A rendered document.
- Eval
Outcome - What happened: counts, reasons, and the provenance of every spliced block.
- Eval
Output - What an evaluator returns: a format tag and the text it produced.
plain(or empty) renders as a text block;gemtext/markdown/djotare nested-rendered through the registry. - Evaluation
Policy - What the evaluate pass may do, as plain data. The host builds one per
document from its standing and the user’s settings;
deny_allis the floor and the right default for any received document. - Fetched
- What a fetch closure returns: the body plus the content type the
transport reported (
Nonelets the renderer sniff). - Gophermap
Context - Server context a gophermap is written against: the host/port columns RFC 1436 requires on every menu line.
- Resolved
Provenance - Result of resolving provenance for a single block.
- Transclude
Outcome - What happened, faithfully: counts and reasons, plus the provenance of every spliced block (top-level index → source), for the host to carry the way clips carry theirs.
- Transclusion
Policy - What the resolve pass may do, as plain data. The host builds one per
document from the document’s standing (own note vs received) and the
user’s settings;
TransclusionPolicy::deny_allis the safe floor.
Enums§
- Block
- A block-level region of an
EngineDocument. - Document
Diagnostic - A note the engine attaches to the document about parse / render quality.
- Document
Trust State - How authenticated the document’s source is.
- Inline
Span - An inline-level span inside a
Block. - Table
Alignment - A table column’s text alignment (djot / markdown
:---,:---:,---:).
Traits§
- Block
Evaluator - A pluggable knot-block evaluator: one scripting language behind the eval fence lane.
Functions§
- evaluate_
blocks - Run the document’s top-level
<lang> evalfences in place. See the module docs for the contract; the outcome reports everything that happened. - inline_
text - Flatten a span list into a plain-text string suitable for accessible
names and snippet extraction.
Codecontributes its inner text; styling containers (Emphasis/Strong) andLinkcontribute their inner span text recursively.SoftBreakbecomes a space,LineBreakbecomes a newline. - parse_
eval - Parse an eval fence’s info string:
<lang> eval(theevalopt-in). Returns the language;Nonefor a plain<lang>sample or anything else. - parse_
include - Parse an include fence’s info string:
include <url>(anything after the URL is reserved). Returns the URL. - resolve_
transclusions - Resolve the document’s top-level
includefences in place. See the module docs for the contract; the outcome reports everything that happened (and didn’t).