diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 84 |
1 files changed, 84 insertions, 0 deletions
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 <doc>.ssp <doc>.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**. |
