diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-09-25 22:28:50 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-03 12:09:16 -0400 |
| commit | f7f4063b351b98e372412d2b364b88ecbe0912c7 (patch) | |
| tree | e42a925cc84acaa4d46b8848960cf6a5beb1e812 /ocda-model.md | |
| parent | .ocda.db specified & the two serialisations agree (diff) | |
derived values, that the model left unstated
The model says nothing about an object's identifier or its anchor, and
both are derived: the identifier is the ocn where there is one, the
anchor is the segment name. The .ssp omits each where it can be worked
out; the .ocda.db states both on every row.
This is existing behaviour, not a new rule. Spine's own .ssp reader has
always filled both in, which is why the database carries them: the
database is written from the .ssp read straight back. It should have
been written down first. Two readers written independently from these
documents disagreed for want of it, on nearly every object, and nothing
short of comparing whole models showed it.
ocda-model.md gains 3.1 the identifier, 7.1 the anchor and 9 derived
values, with the loading rule in a table; "what the model does not hold"
becomes 10.
The two format specifications gain what a reader needs and did not have:
- the .ssp's property table now says what the absent value is, not only
when it is written;
- the .ocda.db gains 3.2.1, the metadata key prefix that carries what
the .ssp puts in four blocks, which a reader must strip to give one
model from either file, and the note that a value here may carry
whitespace the text form cannot represent;
- 3.3 gains the element types of each JSON column and a warning to
parse rather than scan: the encoder writes "/" as "\/" and every
document in the reference collection has a heading containing one;
- 4.1 names the three places the two files are not symmetric,
including translation.ocn_aligned, which a .ssp cannot hold because
it is one language, and which a reader should keep out of the
document model so that nothing built on the model can tell which
file it was given.
(assisted by Claude-Code)
Diffstat (limited to 'ocda-model.md')
| -rw-r--r-- | ocda-model.md | 80 |
1 files changed, 79 insertions, 1 deletions
diff --git a/ocda-model.md b/ocda-model.md index 8c24958..0984e78 100644 --- a/ocda-model.md +++ b/ocda-model.md @@ -39,9 +39,12 @@ the document is made of and the unit it is cited by. Every object carries: - an **object citation number** (OCN), section 3; +- an **identifier**, section 3.1; - 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, section 4; +- the **segment** it is in, and for a heading an **anchor**, sections 7 + and 7.1; - its **text**, in spine's internal representation; - a **digest** of that text. @@ -108,6 +111,24 @@ otherwise: its verses share one; `through_the_looking_glass` has 21 such cases. Key on position within a section when one row is wanted. +### 3.1 The identifier + +Every object also carries an **identifier**: the name by which an output +refers to it. An HTML anchor, a LaTeX `\hypertarget`, a link from a book +index entry to the object it indexes, are all written from the identifier. + +**The identifier of an object with a non-zero OCN is its OCN**, written as +text. That is the ordinary case and it is the reason a citation to object +42 can be turned into a link without consulting anything. + +An object with OCN `0` has no OCN to take an identifier from, so one is +assigned: `a1`, `a2`, `a3`, ... in document order over the objects that +need one. There are few of them, eleven in a book, and they are the +generated furniture of section 3. + +**A reader must arrive at the identifier whether or not the serialisation +wrote it down**; see section 9. + ## 4. Levels A document has **eight heading levels**, in two groups of four: @@ -188,6 +209,21 @@ both separately because the answers differ: Without the second, a reader cannot say where a paragraph belongs. The search database reads the second. +### 7.1 The anchor + +A heading carries an **anchor**: the name an output links to in order to +arrive at that heading. It is what a table of contents entry and a +cross reference point at. + +**An object's anchor is its segment name**, in the ordinary case, because a +heading that opens a segment is arrived at by arriving at the segment. It +differs only where a heading is not the opening of the segment it sits in: +69 of the 72 anchors in one reference document equal their segment and 3 do +not. + +**A reader must arrive at the anchor whether or not the serialisation wrote +it down**; see section 9. + ## 8. Digests The model is checkable at four levels, and the chain is what lets an @@ -203,7 +239,49 @@ 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. -## 9. What the model does not hold +## 9. Derived values, and why a reader must derive them + +Two of the values above are **derived**: the identifier from the OCN +(section 3.1), and the anchor from the segment name (section 7.1). The +model holds them; a serialisation need not, and the text form does not. + +**A serialisation may omit a value it can compute.** The `.ssp` writes a +property only when it carries information, so it omits `.identifier` where +the identifier is the OCN and `.anchor` where the anchor is the segment +name. The `.ocda.db` is columns rather than lines and writes both +unconditionally. + +Both are conforming. What is **not** conforming is a reader that takes the +text form literally and hands on a model with those fields empty, because +that model is not the same model the database gives, and a writer over it +will produce different output from the two serialisations of one document. + +The size of the difference is easy to underestimate. In +`free_culture.lawrence_lessig` the `.ssp` omits **1,314 identifiers and 69 +anchors** that the `.ocda.db` states, which is nearly every object in the +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 | + +**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 +here *because* two readers written independently from these documents +disagreed for want of it: the rule was implied by the `.ssp`'s emission +conditions and nowhere asserted. + +It is also what **spine's own reader** does, and always did, which is why +the `.ocda.db` carries the derived values: the database is written from the +`.ssp` read straight back, and the reading fills both in. So this section +documents existing behaviour rather than prescribing new. It should have +been written down first. + +## 10. 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 |
