Skip to content

Edition identity and gaps

A .vyview must name itself. Title, license, and source live on the pack (manifest.edition), not only in catalog.json. When a member of the work is expected but has no file, declare the extent and address the hole with `note. Do not put that sentence in the spine HTML. Rust does not emit notice HTML into the stream; the Viewer places it.

The platform Viewer reads these packed keys. It does not invent "Untitled" or verse lists under a hole.

SurfaceWhat the reader sees
Title rowCatalog / pack title. An info control opens description, license, source, source_root, snapshot, and each work_notes sentence (href is a link). Incomplete edition objects are omitted, not filled in.
ContentsAbsent containers stay in id order (Matsya: 276, 277, 278) with meta Missing and no verse children. Opening the row weaves the container, not the next chapter.
GapThe kind="gap" sentence sits on that container row (edition-gap). It is not copied onto verses and does not appear as a verse gutter badge.
UncertainA gutter mark uncertain whose tooltip is the note body. Verse HTML is unchanged. Untyped `note stays the existing note badge.

App walkthrough: Viewer.

vyasac pack with target view (the default) or vyir fails unless every field below is set and non-blank. There is no "Untitled" fallback for the HTML <title> or the catalog fragment.

Packed edition keySource in vyasac.toml
title[workspace] title
description[workspace] description
license[catalog] license
source[catalog] source
source_root[catalog] source_root
snapshot[catalog] snapshot (YYYY-MM-DD)
[workspace]
id = "matsya"
name = "matsya"
title = "Matsya Purāṇa"
description = "Sanskrit Wikisource impression of the Matsya Purāṇa."
[catalog]
type = "work"
language = "sa"
license = "CC-BY-SA-4.0"
source = "Sanskrit Wikisource"
source_root = "मत्स्यपुराणम्"
snapshot = "2026-09-29"

zip and sqlite pack targets do not require edition. Reader apps load .vyview.

catalog.json (library listing) still copies workspace title/description and [catalog] type / language / license. That row can drift from a file someone downloaded last month. edition is the file’s own identity — open from OPFS, a shared .vyview, or vyasav inspect without fetching the catalog.

Check it:

Terminal window
vyasav inspect build/matsya.vyview
vyasav inspect --table manifest build/matsya.vyview

Bare inspect JSON includes publication.edition (and work_notes when present).

Without [urn.extent], the contents list is the set of files that compiled. A missing chapter number simply does not appear.

Optional [urn.extent] says which ids were expected. A missing member becomes the same kind of container row the packer already uses for a present parent: pad :0 until the URN has hierarchy.len() components (2:0 on ["adhyaya","verse"]). That row has empty HTML, block attribute absent = true, and a catalog_tree entry with no verse leaves. The packer does not invent verses under a hole.

Extent applies to the primary stream only. Overlay streams do not get empty rows for the same hole. A translation file for an id that has no spine block remains a URN orphan (existing rule).

Top-level range (the first hierarchy name, directly under the work):

[urn]
hierarchy = ["adhyaya", "verse"]
[urn.extent]
adhyaya = "1..291"

Parent-keyed range (the second hierarchy name only — three-or-more-level works):

[urn]
hierarchy = ["book", "chapter", "verse"]
[urn.extent.chapter]
"1" = "1..240"
"2" = "1..49"

Rules:

  • The key is a non-leaf name in hierarchy. An extent on the leaf (verse) is a pack error.
  • start..end is inclusive integers, start <= end, span < 10000.
  • An id in the extent with no primary content becomes an absent container. No virtual leaves.
  • An id in the extent that has a file is a present container (no absent attribute).
  • A content file whose id is outside the extent is a pack error.
  • Omit [urn.extent] to keep today’s behavior (no synthetic holes).
  • Sequence layout only. Do not combine extent with layout = "document" unless a later release says so.
  • You declare the extent. The compiler does not infer it from filenames or Wikisource.

A sparse extent (1..291 with fourteen files) adds many empty output rows and no matching source bytes. The bloat gate (Size(.vyview) / source bytes, 2.0× for view; --strict errors) will refuse a declaration that is mostly holes. That is intended.

Inspect a hole:

Terminal window
vyasav inspect --table html_blocks --urn 2:0 build/work.vyview
vyasav inspect --table block_attributes --urn 2:0 build/work.vyview

Expect empty content, stream_name = the packed primary folder, and absent. In catalog_tree, that id looks like "2": { "slots": [0], "leaves": [] }.

Keep the command. Add kind when the sentence is a reader-facing notice. Body text is the command’s text (content on the Note, or on a work_notes entry). Optional attributes: detail, href.

kindAddressMeaning
gapan absent container (277:0)This member was expected and has no text.
omissionthe work (scope="work"), or a present container (1:0)Something in the source was left out of this edition on purpose.
uncertaina verse (1:1), not a :0 containerThis reading is doubtful. Verse HTML stays as packed.
sourcethe work (scope="work" only)Where this impression came from. One sentence; fields live on edition.
`note { scope="work" kind="source" } [
Sanskrit Wikisource snapshot 2026-09-29. Adhyāya 277 is a stub and is absent here.
]
`note "277:0" { kind="gap" href="https://sa.wikisource.org/wiki/…" } [
This adhyāya is a stub on Sanskrit Wikisource and is not in this edition.
]
`note "291:4" { kind="uncertain" } [
The source prints this number without a separating dot, so the pādas stay in one verse.
]

Pack rules:

  • kind must be one of the four values. Any other value fails the pack. A `note with no kind is still a Note node and HAS_NOTE edge (no reader class).
  • scope="work" writes { kind, content, detail?, href? } into manifest work_notes. It must not quote a URN. It does not create HAS_NOTE. kind="gap" and kind="uncertain" cannot use work scope. kind="source" requires work scope.
  • A targeted note uses HAS_NOTE as today. Quote the full relative path (see below). `note "1..3" { kind="gap" } is not a chapter range; write each container ("2:0").
  • kind="gap" only on an absent container (last component 0 and absent=true). Present 1:0 + gap fails. gap on a verse fails.
  • Do not paste the notice into mula (or any stream) HTML.

Quoted targets are not padded. After range expand, every target must have exactly hierarchy.len() colon-separated components.

On hierarchy = ["adhyaya", "verse"]:

QuoteMeaning
"277:0"adhyāya container (present header or a hole)
"277:1"verse 1 of adhyāya 277
"277"pack error — would have encoded as a verse of adhyāya 0

The encoder still right-aligns anything that slips through; pack fails first so "277" cannot mean the chapter on notes and a verse on annotate.

One-level hierarchy = ["verse"] may still quote "1". Nested `annotate that inherits targets is checked the same way. `note / `annotate / `frame are standard-library commands; do not command-def them in context.vy.

Details and frame: Annotations. Field list: Workspace configuration. Inspect flags: CLI reference. Hosts that are not the platform Viewer: Embedding viewers.