Annotations
Annotations
Section titled “Annotations”Use a top-level annotations/ directory (peer of content/ and templates/) to attach metadata to relative URNs. Pack does not store those files as HTML streams. They become rows in graph_nodes / graph_edges that the viewer uses for Explore facets and named spans.
This is the in-pack model: the same workspace that owns the text also owns the graph. Who else may contribute overlays (an external SME, a second publication that overrides a URN) is under review and may need an RFC — see the toolchain note notes/task-annotations-feature-review.md in the vyasa repo. Do not treat RFC 019’s annotate-range examples as shipped syntax.
Workspace layout
Section titled “Workspace layout”my_work/├── vyasac.toml├── context.vy # aliases, entities; annotate / note / frame are stdlib├── content/…├── annotations/│ ├── context.vy # optional│ └── overlay.vy└── templates/…`annotate, `note, and `frame are in the standard library (category="metadata"). Do not re-declare them in context.vy (that prints Redefining command).
annotate
Section titled “annotate”Argument (or target / urn attribute) is a relative URN, a last-component range, or a comma list. Pack expands "1:1..1:20" to each leaf in that span (cap 10 000). Attributes other than target / urn / id become value nodes plus an edge typed as the uppercase key.
`annotate "1:24:2" { rishi=vamadeva, devata=agni, chandas=gayatri }
`annotate "4:5:0:0" { featured=sri_rudram }The viewer treats each key as a facet (attr:featured, attr:rishi, …). There is no hardcoded featured or Taittirīya vocabulary in the compiler.
Use packed relative paths with every hierarchy component (1:1, 4:5:1:1), not urn:vyasa:… prefixes and not a short id that the encoder would right-align. On ["chapter","verse"], `annotate "1" is a pack error; use "1:1" (verse) or "1:0" (chapter container). One-level hierarchy = ["verse"] may still quote "1". Nested commands inherit the expanded list and are checked the same way.
Editorial gloss (variant reading, damage) or a typed notice (kind). Packed as a Note node and HAS_NOTE edge, except scope="work" which writes manifest.work_notes only.
Quoted URNs must be full-width, same rule as `annotate. Optional fragment after # is stripped for sequence id encoding.
`note "4:1:12#phrase-2" { type="variant" source="Ms-B" } [ Alternative reading on folio 4b.]
`note "277:0" { kind="gap" } [ This adhyāya is a stub at the source and is not in this edition.]Reader-facing kind values are closed: gap, omission, uncertain, source. How they address work vs hole vs verse: Edition identity and gaps. A `note with no kind stays an unclassed gloss.
Groups nested annotate/note under a named context (IN_FRAME edges). Useful for a ritual day or a commentary campaign.
`frame { id="yv-agnicayana-day-1" type="ritual-context" name="Agnicayana" } [ `annotate "1:1..1:2" { role="invocation" } [ … ]]What pack does not do
Section titled “What pack does not do”annotations/,enrichment/, andvocabulary/are not content streams. They do not appear as.vyasa-block-*columns.- Large graphs:
vyasac packwarns when annotation edges exceed the viewer budget (see performance guards in the toolchain repo). - A second publisher cannot yet attach an overlay
.vyviewwith its own catalog id.[dependencies]merges extra content streams; it does not replace spine HTML. See Dependencies and localization.
Related
Section titled “Related”- Edition identity and gaps —
edition, absent containers, note kinds, and how the Viewer shows them - Command reference —
annotate,note,frame - Streams and the URN spine — relative URNs and packed names
- RFC notes 008 / 010 / 019 — design history; some proposed forms did not ship