From 0e2c9fa40ed98ceb7a26c2af69807cf577b6e32a Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Fri, 25 Sep 2026 16:34:44 -0400 Subject: the abstraction as a library, and a defect it found at once The readers each read one serialisation and print. A writer needs neither: it needs the document. So the model and both loaders live here, and a writer cannot tell which serialisation it was handed, exactly as spine own writers cannot. ocda.model imports nothing, which is the property that makes writers possible: they depend on the model and on neither loader. The model and the .ssp loader are the ssp-reader code, moved and renamed to the level they belong to: the model is neither the .ssp nor the .ocda.db. ocda.load_db is new, and returns the same value from sqlite that load_ssp returns from text. ocda.load is the one place that decides what a path is. The claim is only true if the two loaders agree, so test/agree.d asks: load a document both ways and compare the models object by object. It found a real defect on its first run. Eight of thirty-six disagreed, and the cause was the .ssp loader, not the formats: an object whose first text line is blank lost it, the loader having decided whether to start a new line by asking whether the accumulated text was empty, which is a different question from whether a line has been seen. Seven documents of the sample set have verse opening on a blank line and every one of them was wrong. Nothing else had caught it: the two .ssp readers were compared on section counts, which the bug does not disturb. It took loading one document two ways and comparing the objects. Fixed here, and in ssp-reader/dlang which carried the same code. 36 of 36 now agree. (assisted by Claude-Code) Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..de115f1 --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +# ocda-lib + +The **object-centric document abstraction as a library**: the model, and +loaders for both of the forms it is written in. + +**One reader per language, in a directory named for the language.** + +| | | +|---|---| +| [`dlang/`](dlang/) | D | +| `gleam/` | to come | +| `ruby/` | to come | + +## What it is for + +The readers in `ssp-reader` and `ocda-db-reader` each read one +serialisation and print. A **writer** needs neither: it needs the document. + +``` + .ssp ─┐ + ├─> the model ─> a writer + .ocda.db ─┘ +``` + +So this library holds the model and both loaders, and **a writer cannot +tell which serialisation it was handed** — exactly as spine's own writers +cannot, since spine 0.25.0. + +That is the whole of the idea. The readers become thin programs over this, +and the writers are functions from the model to bytes. + +## The check that matters + +The claim above is only true if the two loaders agree, so the library asks: + +```sh +nix build && ./result/bin/ocda-agree .ssp .ocda.db [lang] +``` + +It compares the two models object by object: citation number, kind, type, +part, parent, heading level, digest, text, ancestors and image count. + +**Over the reference collection the two loaders agree on 36 of 36 +document-languages.** They did not at first: see below. + +## What the check found, first time it was run + +Eight of thirty-six disagreed, and the cause was a defect in the `.ssp` +loader rather than a difference between the formats. + +An object whose **first text line is blank** lost it. The loader decided +whether to start a new line by asking whether the accumulated text was +empty, which is not the same question as whether a line has been seen. Of +the sample collection **seven documents have verse opening on a blank +line**, and in every one of them the blank was dropped. + +Nothing else had caught it. The two `.ssp` readers were compared on +*section counts*, which this does not change; spine's own output was never +diffed against the reader's. It took loading the same document two ways and +comparing the objects. + +Fixed here and in `ssp-reader/dlang`, which carried the same code. + +## What it reads, and what it does not + +| | | +|---|---| +| `.ssp` | yes | +| `.ocda.db` | yes, any language of it | +| `.sisupod` | not yet: unwrap the archive and read the `.ssp` inside it | +| `.sst`, `.ssm` markup | **no, and not planned**: that is a parser, which is spine's work | +| a url | no | + +`ocda/load.d` is the one place that decides what a path is, so a new input +type is added once and every reader and writer gains it. + +## The format + +Specified in **sisudoc-abstraction-format**: `ocda-model.md` for the model +this library implements, and the two format specifications for the loaders. +Section 4 of `ocda-db-format-specification.md` gives the column by column +correspondence that `load_db.d` follows. + +At format **2.x**. -- cgit v1.2.3