summaryrefslogtreecommitdiffhomepage
path: root/org
AgeCommit message (Collapse)AuthorFilesLines
2026-10-12format 2.1: on poems and editor's notesHEADmainclaude-check-mainRalph Amissah3-100/+545
- 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)
2026-10-03derived values that the model left unstatedRalph Amissah1-45/+215
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)
2026-10-03.ocda.db specified & the two serialisations agreeRalph Amissah1-9/+346
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)
2026-10-03gaps: kinds, types, levels, make block, markersRalph Amissah1-39/+189
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)
2026-10-03sisudoc-abstraction-format 2.0: ocda-model & .sspRalph Amissah1-0/+810
In an age of malleable, replaceable, improvable text, we continue to seek to represent set text in a fixed, determinate way. This is an effort, using an LLM (Anthropic's Claude Code), to extract and state the specification of the document abstraction of the program spine: - spine can write its document abstraction as a .ssp file, a PEG-parsable serialisation from which other forms of it, such as the sqlite .ocda.db, can be derived https://git.sisudoc.org/sisudoc-spine git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine - this repository states the specification of that abstraction, as the .ssp writes it, in enough detail and with enough precision for the abstraction to be read and written independently git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format - the claim is tested separately: with readers and writers built from the specification alone, with no other knowledge of the format, that read and write the abstraction exactly The specification is derived from the spine emitter, sisudoc/ocda/abstraction/ssp.d, whose sspObjectRecord is the single definition of what an object looks like, and checked against the document markup sample set. Where the two differ the emitter is normative and the specification is wrong; the specification says so. Three documents, so the model is described once rather than in each format specification: ocda-model.md the model: what an object is, the citation number, structure, sections, segments, digests. The part both serialisations share ssp-format-specification.md the model written as text ocda-db-format-specification.md the model written as sqlite, to come The naming follows the three levels: ocda names the model, abstraction names the pipeline stage, and .ssp and .ocda.db name the two serialisations. A thing is named for the level it belongs to, which is why this file is ssp-format-specification.md and not ocda-format-specification.md: it specifies one serialisation, not the model. The specification states the version and the policy that governs it, and separates conformance into what a reader must do, should do, and what a writer must do. The single "should" is that a reader should report what it ignored: without it, silence cannot be told from understanding. Both worked examples regenerated from spine 0.25.0. The excerpt carries one complete object embedding an image, so the .image record and the image marker in the object text can be read against each other. The name .ssp is recorded: it belongs to the .sst, .ssm, .ssi family and stands loosely for sisu peg or sisu parsable, .ssa for sisu abstraction having been thought taken by other projects. README.md identifies the repository as a specification, not a program, summarises what a .ssp is, gives its line types at a glance, and points to ssp-format-specification.md and the two examples. org/ocda_specification.org is the literate source the documents are tangled from. 2026-09-22 (assisted by Claude-Code)