diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-09-24 11:36:25 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-03 13:59:51 -0400 |
| commit | 3d82583f31a9f0464e0b1fda7dbf7bdf0e9f9256 (patch) | |
| tree | 0424d5f178ec7af391c868d71d34454c88672a9c /ocda-model.md | |
| parent | sisudoc-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.md | 97 |
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 |
