| Age | Commit message (Collapse) | Author | Files | Lines |
|
- editor's notes:
Updated here, spine now apart from author's notes recognises existing
markup's editor's notes, ~[* ]~ and ~[+ ]~, and writes them as notes
of their own numbered series: *1, *2 ... and +1, +2 ... document.
- a poem is a container of its verse:
.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. A 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)
|
|
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)
|
|
Writing a validator from this document alone, as the test of whether
it suffices, turned up two rules that a reader needs and that were
implied rather than stated.
- Repeated occurrences of a property are consecutive: the four
repeatable properties share one position in the order and nothing is
written between them. Without that said, a validator checking order
cannot tell a legitimate repeat from a property out of place.
- And no property follows the text: the record is declaration, then
properties, then text lines, and once a text line has been written no
further property appears.
Both hold over the reference collection, and both are now stated with
the check that establishes them.
The third document, derived from the writer and checked against the
sample set's published databases: eight tables, one virtual table, three
views, fifty columns on objects.
The claim worth making and checked: nothing is lost in either direction
between the two serialisations. Every .ssp property is a column or a
child table, every column is a property, a value from the object
declaration line, or a database key. The mapping is given in full. Six
properties are renamed, the text form preferring the short name and
the database the explicit one; two are expanded, .indent into base and
hang and .has into five columns; and the four repeatable properties
become the four child tables. That is all that is different.
Which follows from how the database is made: the document is emitted
as .ssp, read straight back, and what comes back is written. So the
database cannot carry an object property the .ssp cannot express, and
the two cannot drift. It is also why they share one version number.
The compression column carries the literal none or zstd, so a reader
need not infer it from the role; images are the role that is stored
as read, png and jpeg being compressed already.
(assisted by Claude-Code)
|