summaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md42
1 files changed, 37 insertions, 5 deletions
diff --git a/README.md b/README.md
index 5e328c0..ad3a9a9 100644
--- a/README.md
+++ b/README.md
@@ -16,8 +16,10 @@ at the direction of and reviewed by Ralph Amissah.
## What it is for
-The readers in `sisudoc-ssp-reader` and `sisudoc-ocda-db-reader` each read
-one serialisation and print. A **writer** needs neither: it needs the document.
+The first programs written from the specification were two readers,
+`sisudoc-ssp-reader` and `sisudoc-ocda-db-reader`, each reading one
+serialisation and printing. A **writer** needs neither: it needs the
+document.
```
.ssp ─┐
@@ -29,8 +31,38 @@ 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.
+That is the whole of the idea. The writers are functions from the model to
+bytes, and the reader is a program over the model.
+
+## The reader
+
+```sh
+ocda-read [--tree|--html|--llm-text|--llm-jsonl|--images|--verify --image-dir=<d>|
+ --languages|--files|--report-unknown|--validate]
+ <file>.ssp | <file>.ocda.db | <file>.sisupod [lang]
+```
+
+One reader, in each language, where the two earlier readers had a parser
+each. Built on this library, **every mode reads every form, and every mode
+that describes the document says the same thing of its `.ssp`, `.ocda.db`
+and `.sisupod`**, 36 of 36 document-languages. Two modes describe the file
+instead, and differ as the files do: `--languages` lists the one language a
+`.ssp` holds and every language of the other two, and `--files` finds
+carried files only in a `.ocda.db`. The D reader has every mode of both
+old readers; the Gleam one the modes the Gleam readers had (the summary,
+`--tree`, `--languages`, `--files`, `--report-unknown`), and in those **its
+output is the D one's, byte for byte**, 36 of 36.
+
+It is in each language's `src/read/`, and not part of the library: a
+program using the library does not build it (in D, by dub configuration;
+in Gleam a dependant compiles it and does not use it, Gleam building
+everything in `src/`).
+
+Writing it found one defect in the library: **the database loader could
+not say what it had not understood**. It asks for columns by name, and so
+never saw the ones it did not ask for, and reported that it had understood
+everything. It now counts them on the conditions under which the `.ssp`
+writes the same property, and the report is the same from either form.
## The checks that matter
@@ -72,7 +104,7 @@ Nothing else had caught it. The two `.ssp` readers had been compared on
*section counts*, which this does not change. It took loading the same
document two ways and comparing the objects.
-Fixed here and in `sisudoc-ssp-reader/dlang`, which carried the same code.
+Fixed here and in the `.ssp` reader, which carried the same code.
### the whole-model dump: four more