summaryrefslogtreecommitdiffhomepage
path: root/ocda-model.md
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-09-24 11:36:25 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-10-03 13:59:51 -0400
commit3d82583f31a9f0464e0b1fda7dbf7bdf0e9f9256 (patch)
tree0424d5f178ec7af391c868d71d34454c88672a9c /ocda-model.md
parentsisudoc-abstraction-format 2.0: ocda-model & .ssp (diff)
gaps: kinds, types, levels, make block, markers
close gaps left in the first pass, measured against the document markup sample set, (which caught four wrong counts and two traps). ocda-model.md The sixteen object kinds are now defined rather than listed, each with the section it belongs to and its weight in the collection. Only heading appears in all nine sections. Kind and type are two axes rather than one, and type is the useful one for a renderer: is_of_type takes just three values, para, block and comment, saying whether the text may be reflowed. The mapping from kind to type is fixed, so a reader that has the type need not know all sixteen kinds to lay text out. A section on levels, which the first pass assumed: eight of them, A to D for the title matter and 1 to 4 for the body, index 0 to 7, and that index is what the eight-slot arrays are indexed by. A heading's own OCN sits in its own level's slot. Collapsed levels explained as what they are, an artefact of the markup removed. ssp-format-specification.md The @make keys are described rather than named. auto_num_top_at_level and auto_num_top_lv are the same value twice, as the markup wrote it and as an index. breaks is a small language of its own, new= and break= over comma separated levels, and the levels are written there as the markup wrote them. The marker table is now the full set from InlineMarkup with counts from the collection, and the counting corrected four markers the first pass had at zero. Two traps found by counting. The spaced line break and the table close are the same character, and the object kind is what resolves them: it occurs in group objects and never in a table. And the corner brackets are not markers in a .ssp at all: they wrap an object number in ODT output, which happens after the abstraction, so their occurrences here are Japanese quotation marks in the document's own text. The grammar says what it does and does not fix, and why the order of properties is left to the table rather than enumerated as 42 optional terms that would need editing at every minor version. Every line of the collection matches one of its eight line shapes. (assisted by Claude-Code)
Diffstat (limited to 'ocda-model.md')
-rw-r--r--ocda-model.md97
1 files changed, 84 insertions, 13 deletions
diff --git a/ocda-model.md b/ocda-model.md
index b97cf09..f2d73f5 100644
--- a/ocda-model.md
+++ b/ocda-model.md
@@ -14,7 +14,7 @@ between them**, because neither may express what the other cannot:
This document is what they share. It describes objects; they describe
writing objects down.
-## 1. Three words, three levels
+## 1. Three words, and what each names
The terms are used precisely in this repository and in spine, and the
distinction is worth holding:
@@ -39,14 +39,52 @@ the document is made of and the unit it is cited by.
Every object carries:
- an **object citation number** (OCN), section 3;
-- a **kind**, one of sixteen: `para`, `heading`, `toc`, `bookindex`,
- `endnote`, `code`, `bibliography`, `comment`, `verse`, `glossary`,
- `quote`, `poem`, `block`, `table`, `blurb`, `group`;
+- a **kind** and a **type**, section 2.1;
- its **place in the structure**: parent, ancestors, and for a heading its
- children and its last descendant;
+ children and its last descendant, section 4;
- its **text**, in spine's internal representation;
- a **digest** of that text.
+### 2.1 Kind and type: two axes, not one
+
+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 |
+
+**Type** (`is_of_type`) says *how the object's text behaves*, and takes
+only three values:
+
+| type | means | kinds |
+|------|-------|-------|
+| `para` | flowing text, wrapped as the output sees fit | `para`, `heading`, `toc`, `bookindex`, `endnote`, `bibliography`, `glossary`, `blurb` |
+| `block` | text whose line breaks are significant and must be kept | `code`, `verse`, `quote`, `poem`, `block`, `table`, `group` |
+| `comment` | not rendered | `comment` |
+
+The mapping from kind to type is fixed: every `code` object is of type
+`block`, every `para` object of type `para`. **A renderer that has the type
+does not need to know all sixteen kinds** to decide whether it may reflow
+the text, which is what the second axis is for.
+
## 3. The object citation number
The OCN is the heart of the model and the reason for it.
@@ -70,7 +108,35 @@ otherwise:
its verses share one; `through_the_looking_glass` has 21 such cases. Key
on position within a section when one row is wanted.
-## 4. Structure
+## 4. Levels
+
+A document has **eight heading levels**, in two groups of four:
+
+| level | index | what it is |
+|-------|-------|------------|
+| `A` | 0 | the document title. Exactly one per document |
+| `B` | 1 | |
+| `C` | 2 | the title matter below it |
+| `D` | 3 | |
+| `1` | 4 | the top level of the document body |
+| `2` | 5 | |
+| `3` | 6 | below that |
+| `4` | 7 | |
+
+`A` to `D` are the title levels, `1` to `4` the body levels, and the index
+is what the eight-slot arrays of section 5 are indexed by. A heading that
+claims no level has 9, which is the "not a heading level" value and is why
+`.heading_lev_collapsed` is emitted only when it is below 9.
+
+**Collapsed levels.** A document that uses `A` and then `1`, skipping `B`,
+`C` and `D`, has a gap in its levels that is an artefact of the markup
+rather than of the document. Every level-indexed array therefore comes in
+two forms: as marked up, and **collapsed**, with the unused levels removed
+so that the remaining ones are contiguous. Outputs that care about nesting
+depth use the collapsed form; anything tracing back to the markup uses the
+other.
+
+## 5. Structure
Structure is carried by number, not by nesting: an object names its parent
rather than containing its children. This is what lets the serialisations
@@ -82,15 +148,20 @@ be flat and the model be walked in either direction.
introduced to segment an output. The distinction is preserved
deliberately, and a reader walking upward must stop at `0` rather than
treat it as missing, or the walk will not terminate.
-- **`ancestors`** - eight slots, the OCN at each level above this object,
- so the path to the root is available without walking.
-- **`ancestors_collapsed`** - the same with the empty levels removed.
+- **`ancestors`** - **eight slots, indexed by level** (section 4): the OCN
+ of the heading at each level above this object, `0` where there is none,
+ so the path to the root is available without walking it.
+ **A heading's own OCN sits in its own level's slot**: checked over the
+ reference collection, 3,432 headings of 3,432. So for a heading the array
+ is its path including itself, and for any other object it is the path to
+ the heading above it.
+- **`ancestors_collapsed`** - the same, in collapsed levels.
- **`children`** - a heading's child headings.
- **`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.
-## 5. Sections
+## 6. Sections
Objects are grouped into nine sections, in this order:
@@ -102,7 +173,7 @@ head toc body endnotes glossary bibliography bookindex blurb tail
rest are generated or gathered. `tail` is the end of document some output
writers use. A section with no objects is not carried.
-## 6. Segments
+## 7. Segments
An output may be one file or many. A **segment** is one of the many: a
chapter-sized piece of HTML or EPUB with its own name and its own
@@ -117,7 +188,7 @@ both separately because the answers differ:
Without the second, a reader cannot say where a paragraph belongs. The
search database reads the second.
-## 7. Digests
+## 8. Digests
The model is checkable at four levels, and the chain is what lets an
artefact be verified rather than trusted:
@@ -132,7 +203,7 @@ each image ──> a digest of the image file, with its size in bytes and pixels
An object's digest is over its text alone, so a change to one paragraph
moves one digest and no other.
-## 8. What the model does not hold
+## 9. What the model does not hold
- **The markup.** The model is what the markup produced, not the markup
itself. An artefact that carries both is the `.ocda.db`, which carries