summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-09-29 14:02:30 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-10-03 19:42:56 -0400
commit9e6fb20c0ccb18f1eec25478a2c12ad124c7d033 (patch)
tree98adeae3a5968171777c415169a8ca5faecf62d7
parentderived values that the model left unstated (diff)
format 2.1: a poem is a container of its versesmain-2
.ocn_range, the first and last ocn of what a container holds, as one .ssp property and two .ocda.db columns. A poem is the one container: its verses are the citable units rather than the poem. Poem now comes before its first verse, carries ocn 0 and no identifier, and states the range, where it came after its last verse carrying that verse's ocn and identifier. So the model can now say that a non-zero ocn is unique within a document, and does, keeping the older rule for artefacts written before 2.1. A minor bump: an addition, a poem was never rendered and has no text, the verses are unchanged, and a 2.0 reader reads a 2.1 file. The property-count table is recounted over the regenerated reference set, the method first checked against the old set, which it reproduces. The one new endnote, a note in a poem's last verse now gathered, accounts for the other moved counts; the poems' segment names account for .segment_html_is and .segment_epub_is. (assisted by Claude-Code)
-rw-r--r--README.md7
-rw-r--r--example-autonomous-contract.ssp2
-rw-r--r--example-wealth-of-networks.ssp2
-rw-r--r--ocda-db-format-specification.md94
-rw-r--r--ocda-model.md65
-rw-r--r--org/ocda_specification.org279
-rw-r--r--ssp-format-specification.md113
7 files changed, 314 insertions, 248 deletions
diff --git a/README.md b/README.md
index ae17930..7c6a76c 100644
--- a/README.md
+++ b/README.md
@@ -30,15 +30,16 @@ A specification, not a program. The repository ships:
Both carry, in their opening comment lines, the command that
regenerates them, so they can be diffed against a run rather than
-taken on trust. Both are output of **spine 0.25.0, format 2.0**.
+taken on trust. Both are output of **spine, format 2.1** (neither holds a
+poem, so from 2.0 to 2.1 each changed by its version line alone).
## Version
-The format is at **2.0**, and says so on the first line of every
+The format is at **2.1**, and says so on the first line of every
file:
```
-% SiSU Document Abstraction v2.0
+% SiSU Document Abstraction v2.1
```
The minor part is raised when a property is added, the major part
diff --git a/example-autonomous-contract.ssp b/example-autonomous-contract.ssp
index da458a9..ca0424e 100644
--- a/example-autonomous-contract.ssp
+++ b/example-autonomous-contract.ssp
@@ -3,7 +3,7 @@
% <pod-samples>/pod/the_autonomous_contract.ralph_amissah
% <out>/pod/the_autonomous_contract.ralph_amissah/media/abstraction/the_autonomous_contract.ralph_amissah.en.ssp
% Real spine output, complete and unedited but for these four comment lines.
-% SiSU Document Abstraction v2.0
+% SiSU Document Abstraction v2.1
% Source: the_autonomous_contract.ralph_amissah.sst
@source {
diff --git a/example-wealth-of-networks.ssp b/example-wealth-of-networks.ssp
index 54827d1..efbe8f0 100644
--- a/example-wealth-of-networks.ssp
+++ b/example-wealth-of-networks.ssp
@@ -7,7 +7,7 @@
% An EXCERPT of real spine output: every line below is verbatim, and
% each elision is marked. The whole file is 27,769 lines.
%
-% SiSU Document Abstraction v2.0
+% SiSU Document Abstraction v2.1
% Source: the_wealth_of_networks.yochai_benkler.sst
@source {
diff --git a/ocda-db-format-specification.md b/ocda-db-format-specification.md
index f99868e..fe4ad3a 100644
--- a/ocda-db-format-specification.md
+++ b/ocda-db-format-specification.md
@@ -1,7 +1,7 @@
# The `.ocda.db` format
**The object-centric document abstraction, written as sqlite. Format
-version 2.0**, as spine 0.25.0 emits and reads it.
+version 2.1**, as spine emits and reads it after 0.25.1.
This document specifies *one serialisation*. The model it serialises is
specified in [`ocda-model.md`](ocda-model.md), which the text serialisation
@@ -49,7 +49,7 @@ Declared in band, in the `metadata` table:
SELECT key, value FROM metadata WHERE doc_id IS NULL;
-- build.spine_version | 0.25.0
-- schema.name | sisu-abstraction-db
--- schema.version | 2.0
+-- schema.version | 2.1
```
The rule is the model's, and identical to the `.ssp`: the minor part is
@@ -107,12 +107,12 @@ The `.ssp` has four preamble blocks, `@source`, `@meta`, `@make` and
`@doc_has`. The database has **one** `metadata` table, and tells them apart
by a **prefix on the key**:
-| `.ssp` block | database key |
-|--------------|--------------|
-| `@meta` | the key as it stands: `title.main`, `creator.author`, ... |
-| `@make` | `make.` + the key: `make.footer`, `make.doc_type` |
-| `@doc_has` | `doc_has.` + the key: `doc_has.images`, `doc_has.tables` |
-| `@source` | `source.` + the key: `source.language`, `source.digest` |
+| `.ssp` block | database key |
+|--------------|-----------------------------------------------------------|
+| `@meta` | the key as it stands: `title.main`, `creator.author`, ... |
+| `@make` | `make.` + the key: `make.footer`, `make.doc_type` |
+| `@doc_has` | `doc_has.` + the key: `doc_has.images`, `doc_has.tables` |
+| `@source` | `source.` + the key: `source.language`, `source.digest` |
**A reader must strip the prefix and restore the grouping**, or a writer
over it has to ask `metadata["make.footer"]` from a database and
@@ -150,12 +150,12 @@ reader of the text form necessarily does.
The **element types**, so that a decoder can be written to accept exactly
what occurs:
-| column | elements |
-|--------|----------|
-| `children`, `ancestors`, `ancestors_collapsed`, `dom_status`, `dom_status_collapsed` | integers |
-| `table_widths` | integers, or floats where the columns divide evenly |
-| `table_aligns` | strings, one of `l` `c` `r` |
-| `heading_ancestors_text` | strings, eight of them, empty where that level is not an ancestor |
+| column | elements |
+|--------------------------------------------------------------------------------------|-------------------------------------------------------------------|
+| `children`, `ancestors`, `ancestors_collapsed`, `dom_status`, `dom_status_collapsed` | integers |
+| `table_widths` | integers, or floats where the columns divide evenly |
+| `table_aligns` | strings, one of `l` `c` `r` |
+| `heading_ancestors_text` | strings, eight of them, empty where that level is not an ancestor |
The `.ssp` writes the first three groups **space separated** and
`heading_ancestors_text` **`|` separated**. The empty slots of the last are
@@ -181,37 +181,39 @@ declaration line, or a database key.
Where the names differ they differ for a reason, the `.ssp` preferring the
short form and the database the explicit one:
-| `.ssp` property | database |
-|-----------------|----------|
-| `.parent` | `parent_ocn` |
+| `.ssp` property | database |
+|--------------------|-----------------------|
+| `.parent` | `parent_ocn` |
| `.last_descendant` | `last_descendant_ocn` |
-| `.dummy` | `dummy_heading` |
-| `.ocn_off` | `object_number_off` |
-| `.part` | `is_of_part` |
-| `.section` | `is_of_section` |
+| `.dummy` | `dummy_heading` |
+| `.ocn_off` | `object_number_off` |
+| `.part` | `is_of_part` |
+| `.section` | `is_of_section` |
-Two are **expanded**, the `.ssp` folding what the database spreads:
+Three are **expanded**, the `.ssp` folding what the database spreads:
-| `.ssp` property | database |
-|-----------------|----------|
-| `.indent: <base> <hang>` | `indent_base`, `indent_hang` |
-| `.has: links notes_reg notes_star images images_no_dim` | `has_links`, `has_notes_reg`, `has_notes_star`, `has_images`, `has_images_no_dim` |
+| `.ssp` property | database |
+|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| `.indent: <base> <hang>` | `indent_base`, `indent_hang` |
+| `.ocn_range: <first> <last>` | `ocn_range_first`, `ocn_range_last` (2.1: `0` where the object is not a container; a 2.0 database has neither column, and reads as no range) |
+| `.has: links notes_reg notes_star images images_no_dim` | `has_links`, `has_notes_reg`, `has_notes_star`, `has_images`, `has_images_no_dim` |
The four **repeatable** properties become the four child tables:
-| `.ssp` property | database |
-|-----------------|----------|
-| `.image` | `object_images` |
-| `.stow_link` | `object_links` |
-| `.anchor_tag` | `object_anchors` |
-| `.lev4_subtoc` | `object_subtoc` |
+| `.ssp` property | database |
+|-----------------|------------------|
+| `.image` | `object_images` |
+| `.stow_link` | `object_links` |
+| `.anchor_tag` | `object_anchors` |
+| `.lev4_subtoc` | `object_subtoc` |
And four columns come from outside the property list: `ocn`, `is_a` and
`heading_level` from the object declaration line, and `text` from its `|`
lines. `id`, `doc_id` and `seq` are the database's own keys; `seq` is the
object's position within its section, and `(doc_id, section, seq)` is what
-identifies an object when `ocn` will not (see
-[`ocda-model.md`](ocda-model.md) section 3).
+identifies an object when `ocn` will not: `0`, or, before 2.1, a poem
+sharing its last verse's number (see [`ocda-model.md`](ocda-model.md)
+section 3).
### 4.1 Where the two are not symmetric
@@ -244,13 +246,13 @@ there.
## 5. The `files` table: what it carries, and how
-| role | named by | `compression` | `data` holds |
-|------|----------|---------------|--------------|
-| `image` | its bare filename | `none` | the file as read |
-| `source` | `media/text/<lang>/<file>` | `zstd` | a zstd frame |
-| `conf` | `conf/document_make` | `zstd` | a zstd frame |
-| `manifest` | `pod.manifest` | `zstd` | a zstd frame |
-| `tools` | `tools/po4a/...` | `zstd` | a zstd frame |
+| role | named by | `compression` | `data` holds |
+|------------|----------------------------|---------------|------------------|
+| `image` | its bare filename | `none` | the file as read |
+| `source` | `media/text/<lang>/<file>` | `zstd` | a zstd frame |
+| `conf` | `conf/document_make` | `zstd` | a zstd frame |
+| `manifest` | `pod.manifest` | `zstd` | a zstd frame |
+| `tools` | `tools/po4a/...` | `zstd` | a zstd frame |
The `compression` column carries the literal `none` or `zstd`, so a reader
need not infer it from the role.
@@ -289,11 +291,11 @@ SELECT role, count(*), sum(bytes) FROM files GROUP BY role;
### 6.2 The views
-| view | gives |
-|------|-------|
-| `outline` | the headings: lang, section, seq, ocn, both levels, `last_descendant_ocn`, identifier, text |
-| `citable` | every object with an ocn, ordered by ocn, language named |
-| `document_files` | what the file carries: role, name, bytes, sha256, pixel size |
+| view | gives |
+|------------------|---------------------------------------------------------------------------------------------|
+| `outline` | the headings: lang, section, seq, ocn, both levels, `last_descendant_ocn`, identifier, text |
+| `citable` | every object with an ocn, ordered by ocn, language named |
+| `document_files` | what the file carries: role, name, bytes, sha256, pixel size |
**`outline` and `citable` name the language and order by it first.** A view
over a file that may hold ten languages and does not say which would read as
diff --git a/ocda-model.md b/ocda-model.md
index 065677a..1c173b1 100644
--- a/ocda-model.md
+++ b/ocda-model.md
@@ -55,24 +55,24 @@ An object is classified twice, and the two answer different questions.
**Kind** (`is_a`) says *what the object is*, one of sixteen. Each kind
belongs to one section, except `heading`, which appears in all nine:
-| kind | section | what it is | count |
-|----------------|--------------|----------------------------------------------|--------|
-| `para` | body | a paragraph, the ordinary unit of a document | 41,885 |
-| `heading` | *all nine* | a heading at one of the eight levels | 3,503 |
-| `toc` | toc | an entry in the generated table of contents | 3,215 |
-| `bookindex` | bookindex | an entry in the generated book index | 3,034 |
-| `endnote` | endnotes | a note, gathered from where it was called | 2,158 |
-| `code` | body | a code block | 1,623 |
-| `bibliography` | bibliography | a bibliography entry | 585 |
-| `comment` | body | markup comment, carried and not rendered | 450 |
-| `verse` | body | one verse of a poem | 151 |
-| `glossary` | glossary | a glossary entry | 56 |
-| `quote` | body | a block quotation | 53 |
-| `poem` | body | a poem, holding verses | 48 |
-| `block` | body | a block of grouped text | 45 |
-| `table` | body | a table, with its columns described | 32 |
-| `blurb` | blurb | a blurb entry | 28 |
-| `group` | body | a group block | 16 |
+| kind | section | what it is | count |
+|----------------|--------------|--------------------------------------------------------------------------------|--------|
+| `para` | body | a paragraph, the ordinary unit of a document | 41,885 |
+| `heading` | *all nine* | a heading at one of the eight levels | 3,503 |
+| `toc` | toc | an entry in the generated table of contents | 3,215 |
+| `bookindex` | bookindex | an entry in the generated book index | 3,034 |
+| `endnote` | endnotes | a note, gathered from where it was called | 2,294 |
+| `code` | body | a code block | 1,623 |
+| `bibliography` | bibliography | a bibliography entry | 585 |
+| `comment` | body | markup comment, carried and not rendered | 450 |
+| `verse` | body | one verse of a poem | 151 |
+| `glossary` | glossary | a glossary entry | 56 |
+| `quote` | body | a block quotation | 53 |
+| `poem` | body | a poem: the container of its verses, OCN `0`, cited as their range (section 5) | 48 |
+| `block` | body | a block of grouped text | 45 |
+| `table` | body | a table, with its columns described | 32 |
+| `blurb` | blurb | a blurb entry | 28 |
+| `group` | body | a group block | 16 |
**Type** (`is_of_type`) says *how the object's text behaves*, and takes
only three values:
@@ -107,9 +107,12 @@ otherwise:
document reference collection.
- **`0` is therefore not an identity.** Objects sharing `0` are not the
same object, and `0` must never be used as a key.
-- **An OCN is not unique within a document even when non-zero.** A poem and
- its verses share one; `through_the_looking_glass` has 21 such cases. Key
- on position within a section when one row is wanted.
+- **A non-zero OCN is unique within a document**, from format 2.1: checked
+ over the reference collection, no non-zero OCN occurs twice in any of the
+ 36 document-languages. **Before 2.1 it was not**: a poem carried the OCN of
+ its last verse, so the same number named two objects (48 such pairs in the
+ collection, 21 in `through_the_looking_glass`). A reader of an older
+ artefact keys on position within a section when one row is wanted.
### 3.1 The identifier
@@ -181,6 +184,16 @@ be flat and the model be walked in either direction.
- **`last_descendant`** - the last OCN under a heading, which makes a
subtree a **range** rather than a traversal: everything from the
heading's OCN to its last descendant is inside it.
+- **`ocn_range`** - for a **container**, the first and last OCN of what it
+ holds (2.1). A poem is the one container: its verses are the citable
+ units, one object each, and the poem is not; it carries OCN `0` and no
+ identifier, **comes immediately before its first verse**, and is cited as
+ the range of them (`173-180`). So a writer that meets a poem knows what
+ follows and where it ends, and can wrap the verses in one pass. The poem
+ has no text of its own. `0 0`, or absent, where the object is not a
+ container.
+ **Before 2.1** the poem came *after* its last verse, carried that verse's
+ OCN and identifier, and stated no range.
## 6. Sections
@@ -263,11 +276,11 @@ document.
So, on loading:
-| field | when absent | take |
-|-------|-------------|------|
-| identifier | OCN is non-zero | the OCN as text |
-| identifier | OCN is `0` | whatever the serialisation gave; there is nothing to derive from |
-| anchor | the object has a segment | the segment name |
+| field | when absent | take |
+|------------|--------------------------|------------------------------------------------------------------|
+| identifier | OCN is non-zero | the OCN as text |
+| identifier | OCN is `0` | whatever the serialisation gave; there is nothing to derive from |
+| anchor | the object has a segment | the segment name |
**This is a property of the model, not of either format**, which is why it
is stated here and not only in the two format specifications. It is stated
diff --git a/org/ocda_specification.org b/org/ocda_specification.org
index fae845d..a3f5303 100644
--- a/org/ocda_specification.org
+++ b/org/ocda_specification.org
@@ -53,15 +53,16 @@ A specification, not a program. The repository ships:
Both carry, in their opening comment lines, the command that
regenerates them, so they can be diffed against a run rather than
-taken on trust. Both are output of **spine 0.25.0, format 2.0**.
+taken on trust. Both are output of **spine, format 2.1** (neither holds a
+poem, so from 2.0 to 2.1 each changed by its version line alone).
## Version
-The format is at **2.0**, and says so on the first line of every
+The format is at **2.1**, and says so on the first line of every
file:
```
-% SiSU Document Abstraction v2.0
+% SiSU Document Abstraction v2.1
```
The minor part is raised when a property is added, the major part
@@ -250,24 +251,24 @@ An object is classified twice, and the two answer different questions.
,**Kind** (`is_a`) says *what the object is*, one of sixteen. Each kind
belongs to one section, except `heading`, which appears in all nine:
-| kind | section | what it is | count |
-|----------------|--------------|----------------------------------------------|--------|
-| `para` | body | a paragraph, the ordinary unit of a document | 41,885 |
-| `heading` | *all nine* | a heading at one of the eight levels | 3,503 |
-| `toc` | toc | an entry in the generated table of contents | 3,215 |
-| `bookindex` | bookindex | an entry in the generated book index | 3,034 |
-| `endnote` | endnotes | a note, gathered from where it was called | 2,158 |
-| `code` | body | a code block | 1,623 |
-| `bibliography` | bibliography | a bibliography entry | 585 |
-| `comment` | body | markup comment, carried and not rendered | 450 |
-| `verse` | body | one verse of a poem | 151 |
-| `glossary` | glossary | a glossary entry | 56 |
-| `quote` | body | a block quotation | 53 |
-| `poem` | body | a poem, holding verses | 48 |
-| `block` | body | a block of grouped text | 45 |
-| `table` | body | a table, with its columns described | 32 |
-| `blurb` | blurb | a blurb entry | 28 |
-| `group` | body | a group block | 16 |
+| kind | section | what it is | count |
+|----------------|--------------|--------------------------------------------------------------------------------|--------|
+| `para` | body | a paragraph, the ordinary unit of a document | 41,885 |
+| `heading` | *all nine* | a heading at one of the eight levels | 3,503 |
+| `toc` | toc | an entry in the generated table of contents | 3,215 |
+| `bookindex` | bookindex | an entry in the generated book index | 3,034 |
+| `endnote` | endnotes | a note, gathered from where it was called | 2,294 |
+| `code` | body | a code block | 1,623 |
+| `bibliography` | bibliography | a bibliography entry | 585 |
+| `comment` | body | markup comment, carried and not rendered | 450 |
+| `verse` | body | one verse of a poem | 151 |
+| `glossary` | glossary | a glossary entry | 56 |
+| `quote` | body | a block quotation | 53 |
+| `poem` | body | a poem: the container of its verses, OCN `0`, cited as their range (section 5) | 48 |
+| `block` | body | a block of grouped text | 45 |
+| `table` | body | a table, with its columns described | 32 |
+| `blurb` | blurb | a blurb entry | 28 |
+| `group` | body | a group block | 16 |
,**Type** (`is_of_type`) says *how the object's text behaves*, and takes
only three values:
@@ -302,9 +303,12 @@ otherwise:
document reference collection.
- **`0` is therefore not an identity.** Objects sharing `0` are not the
same object, and `0` must never be used as a key.
-- **An OCN is not unique within a document even when non-zero.** A poem and
- its verses share one; `through_the_looking_glass` has 21 such cases. Key
- on position within a section when one row is wanted.
+- **A non-zero OCN is unique within a document**, from format 2.1: checked
+ over the reference collection, no non-zero OCN occurs twice in any of the
+ 36 document-languages. **Before 2.1 it was not**: a poem carried the OCN of
+ its last verse, so the same number named two objects (48 such pairs in the
+ collection, 21 in `through_the_looking_glass`). A reader of an older
+ artefact keys on position within a section when one row is wanted.
### 3.1 The identifier
@@ -376,6 +380,16 @@ be flat and the model be walked in either direction.
- **`last_descendant`** - the last OCN under a heading, which makes a
subtree a **range** rather than a traversal: everything from the
heading's OCN to its last descendant is inside it.
+- **`ocn_range`** - for a **container**, the first and last OCN of what it
+ holds (2.1). A poem is the one container: its verses are the citable
+ units, one object each, and the poem is not; it carries OCN `0` and no
+ identifier, **comes immediately before its first verse**, and is cited as
+ the range of them (`173-180`). So a writer that meets a poem knows what
+ follows and where it ends, and can wrap the verses in one pass. The poem
+ has no text of its own. `0 0`, or absent, where the object is not a
+ container.
+ **Before 2.1** the poem came *after* its last verse, carried that verse's
+ OCN and identifier, and stated no range.
## 6. Sections
@@ -458,11 +472,11 @@ document.
So, on loading:
-| field | when absent | take |
-|-------|-------------|------|
-| identifier | OCN is non-zero | the OCN as text |
-| identifier | OCN is `0` | whatever the serialisation gave; there is nothing to derive from |
-| anchor | the object has a segment | the segment name |
+| field | when absent | take |
+|------------|--------------------------|------------------------------------------------------------------|
+| identifier | OCN is non-zero | the OCN as text |
+| identifier | OCN is `0` | whatever the serialisation gave; there is nothing to derive from |
+| anchor | the object has a segment | the segment name |
,**This is a property of the model, not of either format**, which is why it
is stated here and not only in the two format specifications. It is stated
@@ -494,7 +508,7 @@ been written down first.
# The `.ssp` format
,**The object-centric document abstraction, written as text. Format version
-2.0**, as spine 0.25.0 emits and reads it.
+2.1**, as spine emits and reads it after 0.25.1.
This document specifies *one serialisation*. The model it serialises is
specified in [`ocda-model.md`](ocda-model.md), which the sqlite
@@ -556,7 +570,7 @@ by reading a `.ssp` back, so it can hold nothing this format cannot express.
The version is declared **in band**, on the first line of every file:
```
-% SiSU Document Abstraction v2.0
+% SiSU Document Abstraction v2.1
```
and by the sibling sqlite serialisation in its `schema.version` metadata
@@ -573,11 +587,12 @@ row, so that one bump moves both.
### 2.2 History
-| version | date | what moved |
-|---------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 2.0 | 2026-09-18 | `source.digest` changes meaning: it covers every markup file the document is made of, where it had been the digest of the master file alone. A change of meaning, so the major part. |
-| 1.1 | 2026-09-10 | The `@source` block; the document metadata the output writers read, carried in full (14 `@meta` and 3 `@make` properties added); `.segment_lv4_is`. |
-| 0.1 | | The first form. |
+| version | date | what moved |
+|---------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 2.1 | 2026-09-29 | `.ocn_range`, the first and last ocn of what a container holds. A poem is a container of verses and is cited as their range: it now comes before its first verse, carries ocn `0` and no identifier, and states the range, where it had come after its last verse carrying that verse's ocn and identifier, so that one number named two objects. A minor bump: the property is an addition, the poem was never rendered and has no text, the verses are unchanged, and a 2.0 reader reads a 2.1 file. The same run gathers a note in a poem's last verse into the endnotes, which it had not been: one more endnote in the reference collection. And the editor's notes, `~[* ]~` and `~[+ ]~`, which spine had not recognised and passed through as text, are notes: a third form of note mark, a symbol and a number (`*1`, `+1`), each series numbered through the document; 135 more endnotes, 2,294 in all (section 3.2, "A note begins with its mark"). |
+| 2.0 | 2026-09-18 | `source.digest` changes meaning: it covers every markup file the document is made of, where it had been the digest of the master file alone. A change of meaning, so the major part. |
+| 1.1 | 2026-09-10 | The `@source` block; the document metadata the output writers read, carried in full (14 `@meta` and 3 `@make` properties added); `.segment_lv4_is`. |
+| 0.1 | | The first form. |
## 3. Lexical structure
@@ -639,7 +654,7 @@ it may not.
| `⑆` | a page number of the source edition follows | 19,099 | |
| `┨` `┣` | that page number, open and close | 19,099 | |
| `■` | monospace | 10,688 | |
-| `【` `】` | an inline note | 2,159 | |
+| `【` `】` | an inline note, its mark first (below) | 2,294 | |
| `¤` | an internal site link | 2,157 | |
| `┊` | table cell separator | 695 | `table` objects only |
| `┙` | line break, inline | 184 | |
@@ -656,6 +671,21 @@ it may not.
that it cannot appear.** All of these are defined by the emitter and a
reader must be prepared for them.
+,**A note begins with its mark**, then whitespace, then the note: `【12 text】`.
+The mark is one of three forms, and a reader must take all three:
+
+| mark | what | example |
+|-------------------------|-------------------------------------------------------------------------------------------------------------------------------|----------------------------|
+| digits | the author's notes, numbered through the document | `【12 ...】` |
+| `*` or `+`, repeated | a special note, marked by the symbols alone | `【** ...】` |
+| `*` or `+`, then digits | an editor's note (2.1): the markup's `~[* ]~` and `~[+ ]~`, each series numbered through the document apart from the author's | `【*3 ...】`, `【+1 ...】` |
+
+So the pattern is `【(\d+|[*+]+[0-9]*)\s`. Before 2.1 the third form did not
+occur: spine did not recognise the editor's-note markup, and it came through
+as text, `~[* ...]~` and all. Each note of every form is gathered into the
+`endnotes` section, where its `.anchor_tag` is `note_` and the mark
+(`note_12`, `note_*3`).
+
Two traps in this table, both found by counting rather than by reading:
,**`┚` is defined twice**, as the spaced line break and as the table close.
@@ -686,7 +716,7 @@ are part of the format.
In order, and this order is fixed:
```
-% SiSU Document Abstraction v2.0
+% SiSU Document Abstraction v2.1
% Source: <markup filename>
@source { ... }
@@ -878,47 +908,48 @@ set, as a guide to which parts of the format are load bearing.
| # | property | value | emitted when | count |
|----|---------------------------|-------------------------------|----------------------------------------------------------------------------------------------------|--------|
| 1 | `.identifier` | string | a non-heading has an identifier that is not its ocn (**otherwise it is the ocn**: model section 9) | 353 |
-| 2 | `.part` | string | the object belongs to a part (`frontmatter`, `body`, ...) | 56,882 |
+| 2 | `.part` | string | the object belongs to a part (`frontmatter`, `body`, ...) | 57,018 |
| 3 | `.section` | string | the object's own section differs from the block it sits in | 605 |
-| 4 | `.parent` | int | **every object except** the document root and `toc` entries | 53,631 |
+| 4 | `.parent` | int | **every object except** the document root and `toc` entries | 53,767 |
| 5 | `.last_descendant` | int | non-zero: the last ocn under this heading | 3,202 |
-| 6 | `.children` | ints | the heading has child headings | 827 |
-| 7 | `.ancestors` | 8 ints | any is non-zero | 53,595 |
-| 8 | `.ancestors_collapsed` | 8 ints | any is non-zero | 53,595 |
-| 9 | `.dom_status` | 8 ints | any is non-zero | 3,319 |
-| 10 | `.dom_status_collapsed` | 8 ints | any is non-zero | 3,319 |
-| 11 | `.heading_lev_collapsed` | int | it is below 9 | 3,503 |
-| 12 | `.parent_lev` | int | non-zero | 52,848 |
-| 13 | `.dummy` | `true` | the heading was introduced to segment an output | 183 |
-| 14 | `.ocn_off` | `true` | the object has no citation number | 7,543 |
-| 15 | `.is_of_type` | string | always, in practice | 56,882 |
-| 16 | `.attrib` | string | set | 1 |
-| 17 | `.meta_lang` | string | the object carries its own language | 0 |
-| 18 | `.meta_syntax` | string | the object carries its own markup syntax | 0 |
-| 19 | `.sha256` | hex | the object's text digest is non-zero | 51,253 |
-| 20 | `.image` | record | once **per image**, in order of appearance | 63 |
-| 21 | `.indent` | 2 ints | either indent is non-zero: `base hang` | 7,583 |
-| 22 | `.bullet` | `true` | the object is a bullet item | 1,903 |
-| 23 | `.lang` | string | the text attributes carry a language | 0 |
-| 24 | `.has` | flags | any is set | 11,143 |
-| 25 | `.table_cols` | int | the object is a table with columns | 32 |
-| 26 | `.table_widths` | ints | the table has column widths | 32 |
-| 27 | `.table_aligns` | letters | the table has alignments (`l` `c` `r`) | 32 |
-| 28 | `.table_header` | `true` | the table has a header row | 29 |
-| 29 | `.code_linenumbers` | `true` | the code block is numbered | 1 |
-| 30 | `.stow_link` | url | once **per extracted link** | 1,013 |
-| 31 | `.segment` | string | the heading opens a segment | 3,355 |
-| 32 | `.anchor` | string | the anchor differs from the segment name (**otherwise it is the segment name**: model section 9) | 68 |
-| 33 | `.segment_prev` | string | there is a previous segment | 1,022 |
-| 34 | `.segment_next` | string | there is a next segment | 1,022 |
-| 35 | `.heading_lev_anchor` | string | the heading has a level anchor tag | 1,854 |
-| 36 | `.segment_epub` | string | the heading opens an epub segment | 3,355 |
-| 37 | `.segment_html_is` | string | the object is inside an html segment | 47,024 |
-| 38 | `.segment_epub_is` | string | the object is inside an epub segment | 47,024 |
-| 39 | `.segment_lv4_is` | string | **and** it differs from `.segment_html_is` | 342 |
-| 40 | `.heading_ancestors_text` | 8 slots, `\|` joined, escaped | any slot is non-empty | 3,319 |
-| 41 | `.lev4_subtoc` | string | once **per sub-table-of-contents entry** | 1,887 |
-| 42 | `.anchor_tag` | string | once **per anchor tag** | 7,883 |
+| 6 | `.ocn_range` | 2 ints | the object is a container: the first and last ocn of what it holds (2.1; a poem, model section 5) | 48 |
+| 7 | `.children` | ints | the heading has child headings | 827 |
+| 8 | `.ancestors` | 8 ints | any is non-zero | 53,731 |
+| 9 | `.ancestors_collapsed` | 8 ints | any is non-zero | 53,731 |
+| 10 | `.dom_status` | 8 ints | any is non-zero | 3,319 |
+| 11 | `.dom_status_collapsed` | 8 ints | any is non-zero | 3,319 |
+| 12 | `.heading_lev_collapsed` | int | it is below 9 | 3,503 |
+| 13 | `.parent_lev` | int | non-zero | 52,984 |
+| 14 | `.dummy` | `true` | the heading was introduced to segment an output | 183 |
+| 15 | `.ocn_off` | `true` | the object has no citation number | 7,543 |
+| 16 | `.is_of_type` | string | always, in practice | 57,018 |
+| 17 | `.attrib` | string | set | 1 |
+| 18 | `.meta_lang` | string | the object carries its own language | 0 |
+| 19 | `.meta_syntax` | string | the object carries its own markup syntax | 0 |
+| 20 | `.sha256` | hex | the object's text digest is non-zero | 51,253 |
+| 21 | `.image` | record | once **per image**, in order of appearance | 63 |
+| 22 | `.indent` | 2 ints | either indent is non-zero: `base hang` | 7,583 |
+| 23 | `.bullet` | `true` | the object is a bullet item | 1,903 |
+| 24 | `.lang` | string | the text attributes carry a language | 0 |
+| 25 | `.has` | flags | any is set | 11,384 |
+| 26 | `.table_cols` | int | the object is a table with columns | 32 |
+| 27 | `.table_widths` | ints | the table has column widths | 32 |
+| 28 | `.table_aligns` | letters | the table has alignments (`l` `c` `r`) | 32 |
+| 29 | `.table_header` | `true` | the table has a header row | 29 |
+| 30 | `.code_linenumbers` | `true` | the code block is numbered | 1 |
+| 31 | `.stow_link` | url | once **per extracted link** | 1,014 |
+| 32 | `.segment` | string | the heading opens a segment | 3,355 |
+| 33 | `.anchor` | string | the anchor differs from the segment name (**otherwise it is the segment name**: model section 9) | 68 |
+| 34 | `.segment_prev` | string | there is a previous segment | 1,022 |
+| 35 | `.segment_next` | string | there is a next segment | 1,022 |
+| 36 | `.heading_lev_anchor` | string | the heading has a level anchor tag | 1,854 |
+| 37 | `.segment_epub` | string | the heading opens an epub segment | 3,355 |
+| 38 | `.segment_html_is` | string | the object is inside an html segment | 47,072 |
+| 39 | `.segment_epub_is` | string | the object is inside an epub segment | 47,072 |
+| 40 | `.segment_lv4_is` | string | **and** it differs from `.segment_html_is` | 342 |
+| 41 | `.heading_ancestors_text` | 8 slots, `\|` joined, escaped | any slot is non-empty | 3,319 |
+| 42 | `.lev4_subtoc` | string | once **per sub-table-of-contents entry** | 1,887 |
+| 43 | `.anchor_tag` | string | once **per anchor tag** | 8,019 |
Three of these need a word here, the first two because the model behind
them is easy to misread (see [`ocda-model.md`](ocda-model.md) sections 5
@@ -1078,7 +1109,7 @@ Each carries, in its opening comments, the command that regenerates it.
# The `.ocda.db` format
,**The object-centric document abstraction, written as sqlite. Format
-version 2.0**, as spine 0.25.0 emits and reads it.
+version 2.1**, as spine emits and reads it after 0.25.1.
This document specifies *one serialisation*. The model it serialises is
specified in [`ocda-model.md`](ocda-model.md), which the text serialisation
@@ -1126,7 +1157,7 @@ Declared in band, in the `metadata` table:
SELECT key, value FROM metadata WHERE doc_id IS NULL;
-- build.spine_version | 0.25.0
-- schema.name | sisu-abstraction-db
--- schema.version | 2.0
+-- schema.version | 2.1
```
The rule is the model's, and identical to the `.ssp`: the minor part is
@@ -1184,12 +1215,12 @@ The `.ssp` has four preamble blocks, `@source`, `@meta`, `@make` and
`@doc_has`. The database has **one** `metadata` table, and tells them apart
by a **prefix on the key**:
-| `.ssp` block | database key |
-|--------------|--------------|
-| `@meta` | the key as it stands: `title.main`, `creator.author`, ... |
-| `@make` | `make.` + the key: `make.footer`, `make.doc_type` |
-| `@doc_has` | `doc_has.` + the key: `doc_has.images`, `doc_has.tables` |
-| `@source` | `source.` + the key: `source.language`, `source.digest` |
+| `.ssp` block | database key |
+|--------------|-----------------------------------------------------------|
+| `@meta` | the key as it stands: `title.main`, `creator.author`, ... |
+| `@make` | `make.` + the key: `make.footer`, `make.doc_type` |
+| `@doc_has` | `doc_has.` + the key: `doc_has.images`, `doc_has.tables` |
+| `@source` | `source.` + the key: `source.language`, `source.digest` |
,**A reader must strip the prefix and restore the grouping**, or a writer
over it has to ask `metadata["make.footer"]` from a database and
@@ -1227,12 +1258,12 @@ reader of the text form necessarily does.
The **element types**, so that a decoder can be written to accept exactly
what occurs:
-| column | elements |
-|--------|----------|
-| `children`, `ancestors`, `ancestors_collapsed`, `dom_status`, `dom_status_collapsed` | integers |
-| `table_widths` | integers, or floats where the columns divide evenly |
-| `table_aligns` | strings, one of `l` `c` `r` |
-| `heading_ancestors_text` | strings, eight of them, empty where that level is not an ancestor |
+| column | elements |
+|--------------------------------------------------------------------------------------|-------------------------------------------------------------------|
+| `children`, `ancestors`, `ancestors_collapsed`, `dom_status`, `dom_status_collapsed` | integers |
+| `table_widths` | integers, or floats where the columns divide evenly |
+| `table_aligns` | strings, one of `l` `c` `r` |
+| `heading_ancestors_text` | strings, eight of them, empty where that level is not an ancestor |
The `.ssp` writes the first three groups **space separated** and
`heading_ancestors_text` **`|` separated**. The empty slots of the last are
@@ -1258,37 +1289,39 @@ declaration line, or a database key.
Where the names differ they differ for a reason, the `.ssp` preferring the
short form and the database the explicit one:
-| `.ssp` property | database |
-|-----------------|----------|
-| `.parent` | `parent_ocn` |
+| `.ssp` property | database |
+|--------------------|-----------------------|
+| `.parent` | `parent_ocn` |
| `.last_descendant` | `last_descendant_ocn` |
-| `.dummy` | `dummy_heading` |
-| `.ocn_off` | `object_number_off` |
-| `.part` | `is_of_part` |
-| `.section` | `is_of_section` |
+| `.dummy` | `dummy_heading` |
+| `.ocn_off` | `object_number_off` |
+| `.part` | `is_of_part` |
+| `.section` | `is_of_section` |
-Two are **expanded**, the `.ssp` folding what the database spreads:
+Three are **expanded**, the `.ssp` folding what the database spreads:
-| `.ssp` property | database |
-|-----------------|----------|
-| `.indent: <base> <hang>` | `indent_base`, `indent_hang` |
-| `.has: links notes_reg notes_star images images_no_dim` | `has_links`, `has_notes_reg`, `has_notes_star`, `has_images`, `has_images_no_dim` |
+| `.ssp` property | database |
+|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| `.indent: <base> <hang>` | `indent_base`, `indent_hang` |
+| `.ocn_range: <first> <last>` | `ocn_range_first`, `ocn_range_last` (2.1: `0` where the object is not a container; a 2.0 database has neither column, and reads as no range) |
+| `.has: links notes_reg notes_star images images_no_dim` | `has_links`, `has_notes_reg`, `has_notes_star`, `has_images`, `has_images_no_dim` |
The four **repeatable** properties become the four child tables:
-| `.ssp` property | database |
-|-----------------|----------|
-| `.image` | `object_images` |
-| `.stow_link` | `object_links` |
-| `.anchor_tag` | `object_anchors` |
-| `.lev4_subtoc` | `object_subtoc` |
+| `.ssp` property | database |
+|-----------------|------------------|
+| `.image` | `object_images` |
+| `.stow_link` | `object_links` |
+| `.anchor_tag` | `object_anchors` |
+| `.lev4_subtoc` | `object_subtoc` |
And four columns come from outside the property list: `ocn`, `is_a` and
`heading_level` from the object declaration line, and `text` from its `|`
lines. `id`, `doc_id` and `seq` are the database's own keys; `seq` is the
object's position within its section, and `(doc_id, section, seq)` is what
-identifies an object when `ocn` will not (see
-[`ocda-model.md`](ocda-model.md) section 3).
+identifies an object when `ocn` will not: `0`, or, before 2.1, a poem
+sharing its last verse's number (see [`ocda-model.md`](ocda-model.md)
+section 3).
### 4.1 Where the two are not symmetric
@@ -1321,13 +1354,13 @@ there.
## 5. The `files` table: what it carries, and how
-| role | named by | `compression` | `data` holds |
-|------|----------|---------------|--------------|
-| `image` | its bare filename | `none` | the file as read |
-| `source` | `media/text/<lang>/<file>` | `zstd` | a zstd frame |
-| `conf` | `conf/document_make` | `zstd` | a zstd frame |
-| `manifest` | `pod.manifest` | `zstd` | a zstd frame |
-| `tools` | `tools/po4a/...` | `zstd` | a zstd frame |
+| role | named by | `compression` | `data` holds |
+|------------|----------------------------|---------------|------------------|
+| `image` | its bare filename | `none` | the file as read |
+| `source` | `media/text/<lang>/<file>` | `zstd` | a zstd frame |
+| `conf` | `conf/document_make` | `zstd` | a zstd frame |
+| `manifest` | `pod.manifest` | `zstd` | a zstd frame |
+| `tools` | `tools/po4a/...` | `zstd` | a zstd frame |
The `compression` column carries the literal `none` or `zstd`, so a reader
need not infer it from the role.
@@ -1366,11 +1399,11 @@ SELECT role, count(*), sum(bytes) FROM files GROUP BY role;
### 6.2 The views
-| view | gives |
-|------|-------|
-| `outline` | the headings: lang, section, seq, ocn, both levels, `last_descendant_ocn`, identifier, text |
-| `citable` | every object with an ocn, ordered by ocn, language named |
-| `document_files` | what the file carries: role, name, bytes, sha256, pixel size |
+| view | gives |
+|------------------|---------------------------------------------------------------------------------------------|
+| `outline` | the headings: lang, section, seq, ocn, both levels, `last_descendant_ocn`, identifier, text |
+| `citable` | every object with an ocn, ordered by ocn, language named |
+| `document_files` | what the file carries: role, name, bytes, sha256, pixel size |
,**`outline` and `citable` name the language and order by it first.** A view
over a file that may hold ten languages and does not say which would read as
diff --git a/ssp-format-specification.md b/ssp-format-specification.md
index ae1ecaf..a401947 100644
--- a/ssp-format-specification.md
+++ b/ssp-format-specification.md
@@ -1,7 +1,7 @@
# The `.ssp` format
**The object-centric document abstraction, written as text. Format version
-2.0**, as spine 0.25.0 emits and reads it.
+2.1**, as spine emits and reads it after 0.25.1.
This document specifies *one serialisation*. The model it serialises is
specified in [`ocda-model.md`](ocda-model.md), which the sqlite
@@ -63,7 +63,7 @@ by reading a `.ssp` back, so it can hold nothing this format cannot express.
The version is declared **in band**, on the first line of every file:
```
-% SiSU Document Abstraction v2.0
+% SiSU Document Abstraction v2.1
```
and by the sibling sqlite serialisation in its `schema.version` metadata
@@ -80,11 +80,12 @@ row, so that one bump moves both.
### 2.2 History
-| version | date | what moved |
-|---------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 2.0 | 2026-09-18 | `source.digest` changes meaning: it covers every markup file the document is made of, where it had been the digest of the master file alone. A change of meaning, so the major part. |
-| 1.1 | 2026-09-10 | The `@source` block; the document metadata the output writers read, carried in full (14 `@meta` and 3 `@make` properties added); `.segment_lv4_is`. |
-| 0.1 | | The first form. |
+| version | date | what moved |
+|---------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 2.1 | 2026-09-29 | `.ocn_range`, the first and last ocn of what a container holds. A poem is a container of verses and is cited as their range: it now comes before its first verse, carries ocn `0` and no identifier, and states the range, where it had come after its last verse carrying that verse's ocn and identifier, so that one number named two objects. A minor bump: the property is an addition, the poem was never rendered and has no text, the verses are unchanged, and a 2.0 reader reads a 2.1 file. The same run gathers a note in a poem's last verse into the endnotes, which it had not been: one more endnote in the reference collection. And the editor's notes, `~[* ]~` and `~[+ ]~`, which spine had not recognised and passed through as text, are notes: a third form of note mark, a symbol and a number (`*1`, `+1`), each series numbered through the document; 135 more endnotes, 2,294 in all (section 3.2, "A note begins with its mark"). |
+| 2.0 | 2026-09-18 | `source.digest` changes meaning: it covers every markup file the document is made of, where it had been the digest of the master file alone. A change of meaning, so the major part. |
+| 1.1 | 2026-09-10 | The `@source` block; the document metadata the output writers read, carried in full (14 `@meta` and 3 `@make` properties added); `.segment_lv4_is`. |
+| 0.1 | | The first form. |
## 3. Lexical structure
@@ -146,7 +147,7 @@ it may not.
| `⑆` | a page number of the source edition follows | 19,099 | |
| `┨` `┣` | that page number, open and close | 19,099 | |
| `■` | monospace | 10,688 | |
-| `【` `】` | an inline note | 2,159 | |
+| `【` `】` | an inline note, its mark first (below) | 2,294 | |
| `¤` | an internal site link | 2,157 | |
| `┊` | table cell separator | 695 | `table` objects only |
| `┙` | line break, inline | 184 | |
@@ -163,6 +164,21 @@ it may not.
that it cannot appear.** All of these are defined by the emitter and a
reader must be prepared for them.
+**A note begins with its mark**, then whitespace, then the note: `【12 text】`.
+The mark is one of three forms, and a reader must take all three:
+
+| mark | what | example |
+|-------------------------|-------------------------------------------------------------------------------------------------------------------------------|----------------------------|
+| digits | the author's notes, numbered through the document | `【12 ...】` |
+| `*` or `+`, repeated | a special note, marked by the symbols alone | `【** ...】` |
+| `*` or `+`, then digits | an editor's note (2.1): the markup's `~[* ]~` and `~[+ ]~`, each series numbered through the document apart from the author's | `【*3 ...】`, `【+1 ...】` |
+
+So the pattern is `【(\d+|[*+]+[0-9]*)\s`. Before 2.1 the third form did not
+occur: spine did not recognise the editor's-note markup, and it came through
+as text, `~[* ...]~` and all. Each note of every form is gathered into the
+`endnotes` section, where its `.anchor_tag` is `note_` and the mark
+(`note_12`, `note_*3`).
+
Two traps in this table, both found by counting rather than by reading:
**`┚` is defined twice**, as the spaced line break and as the table close.
@@ -193,7 +209,7 @@ are part of the format.
In order, and this order is fixed:
```
-% SiSU Document Abstraction v2.0
+% SiSU Document Abstraction v2.1
% Source: <markup filename>
@source { ... }
@@ -385,47 +401,48 @@ set, as a guide to which parts of the format are load bearing.
| # | property | value | emitted when | count |
|----|---------------------------|-------------------------------|----------------------------------------------------------------------------------------------------|--------|
| 1 | `.identifier` | string | a non-heading has an identifier that is not its ocn (**otherwise it is the ocn**: model section 9) | 353 |
-| 2 | `.part` | string | the object belongs to a part (`frontmatter`, `body`, ...) | 56,882 |
+| 2 | `.part` | string | the object belongs to a part (`frontmatter`, `body`, ...) | 57,018 |
| 3 | `.section` | string | the object's own section differs from the block it sits in | 605 |
-| 4 | `.parent` | int | **every object except** the document root and `toc` entries | 53,631 |
+| 4 | `.parent` | int | **every object except** the document root and `toc` entries | 53,767 |
| 5 | `.last_descendant` | int | non-zero: the last ocn under this heading | 3,202 |
-| 6 | `.children` | ints | the heading has child headings | 827 |
-| 7 | `.ancestors` | 8 ints | any is non-zero | 53,595 |
-| 8 | `.ancestors_collapsed` | 8 ints | any is non-zero | 53,595 |
-| 9 | `.dom_status` | 8 ints | any is non-zero | 3,319 |
-| 10 | `.dom_status_collapsed` | 8 ints | any is non-zero | 3,319 |
-| 11 | `.heading_lev_collapsed` | int | it is below 9 | 3,503 |
-| 12 | `.parent_lev` | int | non-zero | 52,848 |
-| 13 | `.dummy` | `true` | the heading was introduced to segment an output | 183 |
-| 14 | `.ocn_off` | `true` | the object has no citation number | 7,543 |
-| 15 | `.is_of_type` | string | always, in practice | 56,882 |
-| 16 | `.attrib` | string | set | 1 |
-| 17 | `.meta_lang` | string | the object carries its own language | 0 |
-| 18 | `.meta_syntax` | string | the object carries its own markup syntax | 0 |
-| 19 | `.sha256` | hex | the object's text digest is non-zero | 51,253 |
-| 20 | `.image` | record | once **per image**, in order of appearance | 63 |
-| 21 | `.indent` | 2 ints | either indent is non-zero: `base hang` | 7,583 |
-| 22 | `.bullet` | `true` | the object is a bullet item | 1,903 |
-| 23 | `.lang` | string | the text attributes carry a language | 0 |
-| 24 | `.has` | flags | any is set | 11,143 |
-| 25 | `.table_cols` | int | the object is a table with columns | 32 |
-| 26 | `.table_widths` | ints | the table has column widths | 32 |
-| 27 | `.table_aligns` | letters | the table has alignments (`l` `c` `r`) | 32 |
-| 28 | `.table_header` | `true` | the table has a header row | 29 |
-| 29 | `.code_linenumbers` | `true` | the code block is numbered | 1 |
-| 30 | `.stow_link` | url | once **per extracted link** | 1,013 |
-| 31 | `.segment` | string | the heading opens a segment | 3,355 |
-| 32 | `.anchor` | string | the anchor differs from the segment name (**otherwise it is the segment name**: model section 9) | 68 |
-| 33 | `.segment_prev` | string | there is a previous segment | 1,022 |
-| 34 | `.segment_next` | string | there is a next segment | 1,022 |
-| 35 | `.heading_lev_anchor` | string | the heading has a level anchor tag | 1,854 |
-| 36 | `.segment_epub` | string | the heading opens an epub segment | 3,355 |
-| 37 | `.segment_html_is` | string | the object is inside an html segment | 47,024 |
-| 38 | `.segment_epub_is` | string | the object is inside an epub segment | 47,024 |
-| 39 | `.segment_lv4_is` | string | **and** it differs from `.segment_html_is` | 342 |
-| 40 | `.heading_ancestors_text` | 8 slots, `\|` joined, escaped | any slot is non-empty | 3,319 |
-| 41 | `.lev4_subtoc` | string | once **per sub-table-of-contents entry** | 1,887 |
-| 42 | `.anchor_tag` | string | once **per anchor tag** | 7,883 |
+| 6 | `.ocn_range` | 2 ints | the object is a container: the first and last ocn of what it holds (2.1; a poem, model section 5) | 48 |
+| 7 | `.children` | ints | the heading has child headings | 827 |
+| 8 | `.ancestors` | 8 ints | any is non-zero | 53,731 |
+| 9 | `.ancestors_collapsed` | 8 ints | any is non-zero | 53,731 |
+| 10 | `.dom_status` | 8 ints | any is non-zero | 3,319 |
+| 11 | `.dom_status_collapsed` | 8 ints | any is non-zero | 3,319 |
+| 12 | `.heading_lev_collapsed` | int | it is below 9 | 3,503 |
+| 13 | `.parent_lev` | int | non-zero | 52,984 |
+| 14 | `.dummy` | `true` | the heading was introduced to segment an output | 183 |
+| 15 | `.ocn_off` | `true` | the object has no citation number | 7,543 |
+| 16 | `.is_of_type` | string | always, in practice | 57,018 |
+| 17 | `.attrib` | string | set | 1 |
+| 18 | `.meta_lang` | string | the object carries its own language | 0 |
+| 19 | `.meta_syntax` | string | the object carries its own markup syntax | 0 |
+| 20 | `.sha256` | hex | the object's text digest is non-zero | 51,253 |
+| 21 | `.image` | record | once **per image**, in order of appearance | 63 |
+| 22 | `.indent` | 2 ints | either indent is non-zero: `base hang` | 7,583 |
+| 23 | `.bullet` | `true` | the object is a bullet item | 1,903 |
+| 24 | `.lang` | string | the text attributes carry a language | 0 |
+| 25 | `.has` | flags | any is set | 11,384 |
+| 26 | `.table_cols` | int | the object is a table with columns | 32 |
+| 27 | `.table_widths` | ints | the table has column widths | 32 |
+| 28 | `.table_aligns` | letters | the table has alignments (`l` `c` `r`) | 32 |
+| 29 | `.table_header` | `true` | the table has a header row | 29 |
+| 30 | `.code_linenumbers` | `true` | the code block is numbered | 1 |
+| 31 | `.stow_link` | url | once **per extracted link** | 1,014 |
+| 32 | `.segment` | string | the heading opens a segment | 3,355 |
+| 33 | `.anchor` | string | the anchor differs from the segment name (**otherwise it is the segment name**: model section 9) | 68 |
+| 34 | `.segment_prev` | string | there is a previous segment | 1,022 |
+| 35 | `.segment_next` | string | there is a next segment | 1,022 |
+| 36 | `.heading_lev_anchor` | string | the heading has a level anchor tag | 1,854 |
+| 37 | `.segment_epub` | string | the heading opens an epub segment | 3,355 |
+| 38 | `.segment_html_is` | string | the object is inside an html segment | 47,072 |
+| 39 | `.segment_epub_is` | string | the object is inside an epub segment | 47,072 |
+| 40 | `.segment_lv4_is` | string | **and** it differs from `.segment_html_is` | 342 |
+| 41 | `.heading_ancestors_text` | 8 slots, `\|` joined, escaped | any slot is non-empty | 3,319 |
+| 42 | `.lev4_subtoc` | string | once **per sub-table-of-contents entry** | 1,887 |
+| 43 | `.anchor_tag` | string | once **per anchor tag** | 8,019 |
Three of these need a word here, the first two because the model behind
them is easy to misread (see [`ocda-model.md`](ocda-model.md) sections 5