summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--README.md32
-rw-r--r--dlang/README.md43
-rw-r--r--gleam/README.md38
3 files changed, 93 insertions, 20 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
diff --git a/dlang/README.md b/dlang/README.md
index 302f874..96df8f4 100644
--- a/dlang/README.md
+++ b/dlang/README.md
@@ -4,14 +4,16 @@ The abstraction's model and both its loaders, as a dub library.
## Modules
-|-----------------|---------------------------------------------------------------|
-| `ocda.model` | the document, the object, the eight sections. Imports nothing |
-| `ocda.load_ssp` | text -> model |
-| `ocda.load_db` | sqlite -> model |
-| `ocda.load` | what a path is, and loading it |
-| `ocda.dump` | the model written out canonically, as an oracle |
-| `ocda.sqlite` | the sqlite3 C API, declared rather than depended upon |
->>>>>>> 3ad58ce (ocda-lib in Gleam, and four agreements of 36 of 36)
+|------------------|------------------------------------------------------------------------------------------------------------|
+| `ocda.model` | the document, the object, the eight sections. Imports nothing |
+| `ocda.load_ssp` | text -> model |
+| `ocda.load_db` | sqlite -> model |
+| `ocda.load` | what a path is, and loading it |
+| `ocda.inventory` | what a file holds beyond the one document: its languages (every form alike), and what a `.ocda.db` carries |
+| `ocda.dump` | the model written out canonically, as an oracle |
+| `ocda.sqlite` | the sqlite3 C API, declared rather than depended upon |
+| `read.*` | `ocda-read`, the reader: in `src/read/`, and *not* part of the library (below) |
+
`ocda.model` importing nothing is the property that matters: a writer
depends on the model and on neither loader.
@@ -31,6 +33,26 @@ foreach (obj; doc.body) { ... }
Link `sqlite3`; the library declares the dozen functions it needs rather
than taking a binding from the registry, so there is nothing to fetch.
+## The reader
+
+```sh
+nix build .#ocda-read && ./result/bin/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]
+```
+
+The library's reader, one program where `sisudoc-ssp-reader` and
+`sisudoc-ocda-db-reader` were two. Its output modules are the `.ssp`
+reader's, moved onto the library's model, so every mode reads every form
+and **says the same thing of a document's `.ssp`, `.ocda.db` and
+`.sisupod`**. `--files` answers for a `.ocda.db`, the one form that carries
+files; `--validate` checks a `.ssp` as text and refuses anything else.
+
+It lives in `src/read/` beside the library, and dub keeps it out of the
+library: the configuration `library` excludes `src/read/*`, the
+configuration `ocda-read` builds it. A program using the library by dub, or
+by naming `src/ocda/*.d` as the writer's flake does, never compiles it.
+
## The two checks
```sh
@@ -55,8 +77,11 @@ repository README and in the history.
## Build
```sh
+nix build # all three programs, in one result/bin
+nix build .#ocda-read # the reader
nix build .#ocda-agree # the agreement check
nix build .#ocda-dump # the canonical dump
-nix develop # ldc, dub, dtools, sqlite
+nix develop # ldc, dub, dtools, sqlite, zstd
dub build # the library
+dub build --config=ocda-read # the reader
```
diff --git a/gleam/README.md b/gleam/README.md
index a43fe2d..1da1648 100644
--- a/gleam/README.md
+++ b/gleam/README.md
@@ -1,14 +1,17 @@
# ocda-lib, in Gleam
-The abstraction's model and both its loaders, as a Gleam library, and the
-two programs that put it to the question.
-
-|-----------------|----------------------------------------------------------------------------------|
-| `ocda/model` | the document, the object, the image. Depends on nothing but the standard library |
-| `ocda/load_ssp` | text -> model |
-| `ocda/load_db` | sqlite -> model |
-| `ocda/load` | what a path is, and loading it |
-| `ocda/dump` | the model written out canonically, as an oracle |
+The abstraction's model and both its loaders, as a Gleam library, with its
+reader and the two programs that put it to the question.
+
+|------------------|-----------------------------------------------------------------------------------------|
+| `ocda/model` | the document, the object, the image. Depends on nothing but the standard library |
+| `ocda/load_ssp` | text -> model |
+| `ocda/load_db` | sqlite -> model |
+| `ocda/load` | what a path is, and loading it |
+| `ocda/inventory` | what a file holds beyond the one document: its languages, and what a `.ocda.db` carries |
+| `ocda/dump` | the model written out canonically, as an oracle |
+| `read/main` | `ocda-read`, the reader |
+| `ocda_ffi.erl` | a sha256, from OTP's crypto, which the standard library lacks |
## Use
@@ -26,6 +29,23 @@ case load.load(path, "en", False) {
}
```
+## The reader
+
+```sh
+nix build
+./result/bin/ocda-read [--tree|--outline|--languages|--files|--report-unknown]
+ <file>.ssp|<file>.ocda.db|<file>.zip [lang]
+```
+
+`ocda-lib read`, installed also as `ocda-read`. The modes the Gleam readers
+had, over the library, so each reads every form this library reads; the
+others are the D reader's. **Its output is the D `ocda-read`'s, byte for
+byte**, in every mode both have. In `src/read/`, because Gleam compiles
+nothing outside `src/`; a program depending on the library compiles it too,
+and does not use it.
+
+A `.sisupod` it refuses, saying why: the zstd frame, below.
+
## The two programs
```sh