summaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-09-29 20:04:55 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-10-21 19:12:17 -0400
commit4dd9b15d2210e5661f9261acf113c22d4372ffc5 (patch)
tree291dc10e1c839f084cb12ac615e1839b67807101 /README.md
parentGleam: ocda-read, byte for byte the D reader's (diff)
README: the reader in D and Gleamclaude-main-prepare
The library's reader, ocda-read: where it lives and why (src/read/, kept out of the library in D by dub configuration, in Gleam because nothing outside src/ is compiled), its modes in each language, and the two properties it holds, the same output from every form and D == Gleam byte for byte. And the one defect it found in the library, the database loader unable to say what it had not read. The module tables gain ocda.inventory and the reader, the build notes the three programs in one result. (assisted by Claude-Code)
Diffstat (limited to 'README.md')
-rw-r--r--README.md32
1 files changed, 30 insertions, 2 deletions
diff --git a/README.md b/README.md
index 6ba90e6..07fbacd 100644
--- a/README.md
+++ b/README.md
@@ -24,8 +24,36 @@ 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 `sisudoc-ssp-reader` and
+`sisudoc-ocda-db-reader` were two, each with a parser of its own. Built on
+this library, **every mode reads every form and says the same thing of a
+document's `.ssp`, `.ocda.db` and `.sisupod`**, 36 of 36 document-languages.
+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