Edition identity and gaps
Edition identity and gaps
Section titled “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.
In the Viewer
Section titled “In the Viewer”The platform Viewer reads these packed keys. It does not invent "Untitled" or verse lists under a hole.
| Surface | What the reader sees |
|---|---|
| Title row | Catalog / 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. |
| Contents | Absent 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. |
| Gap | The 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. |
| Uncertain | A gutter mark uncertain whose tooltip is the note body. Verse HTML is unchanged. Untyped `note stays the existing note badge. |
App walkthrough: Viewer.
1. Required edition fields (view pack)
Section titled “1. Required edition fields (view pack)”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 key | Source 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:
vyasav inspect build/matsya.vyviewvyasav inspect --table manifest build/matsya.vyviewBare inspect JSON includes publication.edition (and work_notes when present).
2. Declared extent and absent containers
Section titled “2. Declared extent and absent containers”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..endis 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
absentattribute). - 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:
vyasav inspect --table html_blocks --urn 2:0 build/work.vyviewvyasav inspect --table block_attributes --urn 2:0 build/work.vyviewExpect empty content, stream_name = the packed primary folder, and absent. In catalog_tree, that id looks like "2": { "slots": [0], "leaves": [] }.
3. Notices via note
Section titled “3. Notices via note”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.
kind | Address | Meaning |
|---|---|---|
gap | an absent container (277:0) | This member was expected and has no text. |
omission | the work (scope="work"), or a present container (1:0) | Something in the source was left out of this edition on purpose. |
uncertain | a verse (1:1), not a :0 container | This reading is doubtful. Verse HTML stays as packed. |
source | the 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:
kindmust be one of the four values. Any other value fails the pack. A`notewith nokindis still aNotenode andHAS_NOTEedge (no reader class).scope="work"writes{ kind, content, detail?, href? }into manifestwork_notes. It must not quote a URN. It does not createHAS_NOTE.kind="gap"andkind="uncertain"cannot use work scope.kind="source"requires work scope.- A targeted note uses
HAS_NOTEas 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 component0andabsent=true). Present1:0+gapfails.gapon a verse fails.- Do not paste the notice into
mula(or any stream) HTML.
4. Full-width quoted URNs
Section titled “4. Full-width quoted URNs”Quoted targets are not padded. After range expand, every target must have exactly hierarchy.len() colon-separated components.
On hierarchy = ["adhyaya", "verse"]:
| Quote | Meaning |
|---|---|
"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.