summaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md86
1 files changed, 53 insertions, 33 deletions
diff --git a/README.md b/README.md
index 487b2cd..e1581b4 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
# sisudoc-ocda-lib
The **object-centric document abstraction as a library**: the model, and
-loaders for both of the forms it is written in.
+loaders for each of the forms it is written in.
-**One reader per language, in a directory named for the language.**
+**One implementation per language, in a directory named for the language.**
| | |
|--------------------|---------|
@@ -11,10 +11,13 @@ loaders for both of the forms it is written in.
| [`gleam/`](gleam/) | Gleam |
| `ruby/` | to come |
-## What it is for (NO LONGER RELEASED, NOW USED DIRECTLY BY WRITER) FIX
+## What it is for
-The readers in `sisudoc-ssp-reader` (NO LONGER RELEASED, NOW USED DIRECTLY BY WRITER) FIX and `sisudoc-ocda-db-reader` (NO LONGER RELEASED, NOW USED DIRECTLY BY WRITER) FIX 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. They are published frozen, as the record of
+readers written from the specification alone, and their work is now done by
+`ocda-read`, below. A **writer** needs neither: it needs the document.
```
.ssp ─┐
@@ -37,14 +40,13 @@ ocda-read [--tree|--html|--llm-text|--llm-jsonl|--images|--verify --image-dir=<d
<file>.ssp | <file>.ocda.db | <file>.sisupod [lang]
```
-One reader, in each language, where `sisudoc-ssp-reader` (NO LONGER RELEASED, NOW USED DIRECTLY BY WRITER) FIX and
-`sisudoc-ocda-db-reader` (NO LONGER RELEASED, NOW USED DIRECTLY BY WRITER) FIX 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.
+One reader, in each language, where the two earlier readers had a parser
+each. Built on this library, **every mode reads every form and says the same
+thing of a document's `.ssp`, `.ocda.db` and `.sisupod`**, for every
+document-language of the markup document samples. The D reader has every
+mode of both earlier 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**.
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;
@@ -59,6 +61,11 @@ writes the same property, and the report is the same from either form.
## The checks that matter
+The checks are run over the markup document samples
+([sisudoc-spine-samples](https://git.sisudoc.org/sisudoc-spine-samples)),
+built by spine with `--show-abstraction --ocda-db --pod2`, which writes each
+document's `.ssp`, its `.ocda.db` and its pod.
+
The claim above is only true if the loaders agree, so the library asks. Two
programs, in each language:
@@ -71,14 +78,14 @@ ocda-dump <file>.ssp|<file>.ocda.db [lang] # the whole model, canonically
of the two**, and the reason it exists: it writes the entire loaded model
out in a fully determined form, and the D and the Gleam library write it
*byte for byte alike*. So four questions can be asked, all of them with
-`diff`:
+`diff`, and each holds for every document-language:
-| | |
-|-----------------------------|---------------------------------|
-| D: `.ssp` == `.ocda.db` | **36 of 36** document-languages |
-| Gleam: `.ssp` == `.ocda.db` | **36 of 36** |
-| `.ssp`: D == Gleam | **36 of 36** |
-| `.ocda.db`: D == Gleam | **36 of 36** |
+| | |
+|-----------------------------|---------------|
+| D: `.ssp` == `.ocda.db` | **every one** |
+| Gleam: `.ssp` == `.ocda.db` | **every one** |
+| `.ssp`: D == Gleam | **every one** |
+| `.ocda.db`: D == Gleam | **every one** |
None of those held at first.
@@ -89,15 +96,15 @@ None of those held at first.
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. Eight of
-thirty-six documents disagreed.
+the markup document samples **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 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. (NO LONGER RELEASED, NOW USED DIRECTLY BY WRITER) FIX
+Fixed here and in the `.ssp` reader, `sisudoc-ssp-reader`, which carried the
+same code.
### the whole-model dump: four more
@@ -117,8 +124,8 @@ the two loaders:
serialisation it was handed.
3. **The JSON columns were scanned rather than parsed.** Phobos writes `/`
as `\/`, so every heading containing a slash came back with a backslash
- in it: **all 36 document-languages** differed on
- `heading_ancestors_text` and nothing else had shown it.
+ in it: **every document-language** differed on `heading_ancestors_text`
+ and nothing else had shown it.
4. **`translation.ocn_aligned`** is in the database and cannot be in a
`.ssp`, which is one language and cannot know whether the languages
share a numbering. It is a fact about the *file*, so the loaders leave
@@ -144,8 +151,8 @@ puts it in, `--source` does not. A pod without one is refused with a message
saying which flag makes a pod this library can read, because that is a fact
about the pod rather than about the library.
-**Over the reference collection, a `.sisupod` gives the same model as the
-`.ssp` beside it: 36 of 36 document-languages, byte identical dumps.** A
+**Over the markup document samples, a `.sisupod` gives the same model as the
+`.ssp` beside it, for every document-language: byte identical dumps.** A
writer over the library therefore gained a third input form without being
touched, which is the point of the dispatch being in one place.
@@ -165,11 +172,24 @@ the only place the two libraries differ in what they accept.
`ocda/load` is the one place in each language that decides what a path is,
so a new input form is added once and every reader and writer gains it.
+## Building and use
+
+`nix build` in `dlang/` or `gleam/`. See [`dlang/README.md`](dlang/README.md)
+and [`gleam/README.md`](gleam/README.md) for the modules, the programs and
+using the library from another program.
+
## 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 the `load_db` of each language follows.
+Specified in
+[**sisudoc-abstraction-format**](https://git.sisudoc.org/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
+the `load_db` of each language follows.
+
+At format **2.1**; the library's version follows the format's major and
+minor parts.
+
+## Licence
-At format **2.x**.
+AGPL-3.0-or-later. See [`COPYRIGHT`](COPYRIGHT).