summaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md84
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**.