Skip to content

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.

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).

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" } [ … ]
]
  • annotations/, enrichment/, and vocabulary/ are not content streams. They do not appear as .vyasa-block-* columns.
  • Large graphs: vyasac pack warns when annotation edges exceed the viewer budget (see performance guards in the toolchain repo).
  • A second publisher cannot yet attach an overlay .vyview with its own catalog id. [dependencies] merges extra content streams; it does not replace spine HTML. See Dependencies and localization.