diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-13 16:54:02 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-13 16:54:02 -0400 |
| commit | 79a7a0cf09c9d6b5d9974376dcb7a98bd5bdbcba (patch) | |
| tree | 0a83345133c51ff0144c33364077603570a47f45 /README.md | |
| parent | format 2.1: ocda-read, the readers folded in (diff) | |
release 2.1.0: versions, a nix-gleam build, READMEHEADmainclaude-spec-matchup-redo-fixing-3
The library's version follows the format's: 2.1.0 in dub.json,
gleam.toml and both flakes. A release is numbered major.minor.patch,
major.minor being the format and shared with the specification and the
writer, the patch the library's own.
dlang/flake.lock and gleam/flake.lock: nixpkgs forward to
26.11pre1097770, the same revision in both, as the two have been at
every commit.
README:
- the two earlier readers, sisudoc-ssp-reader and
sisudoc-ocda-db-reader, are named as what they now are: published
frozen, the record of readers written from the specification
alone, their work done by ocda-read;
- the documents the checks run over are the markup document samples,
named with their repository and the spine flags that build the
artefacts; the claims say "every document-language of the markup
document samples" rather than a count, which changes as the samples
do; the same in gleam/README.md, which also describes the nix-gleam
build and names the specification's documents as .md, as they are;
- "one implementation per language", where it said "one reader";
- the reader's modes that describe the document say the same of every
form; --languages and --files describe the file, and say so;
- a short section on building, a link to the specification, the
format as 2.1, and the license.
Checked: D and Gleam build; with the writer at the same point, over
the markup document samples: the four dumps (D and Gleam, .ssp and
.ocda.db) identical for every document-language of the markup document
samples, ocda-read the same from every form and in both languages, and
D == Gleam in all five formats.
(assisted by Claude-Code)
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 86 |
1 files changed, 53 insertions, 33 deletions
@@ -1,25 +1,25 @@ # 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 implementation per language, in a directory named for the language.** Written by Claude (Anthropic), working in Claude Code from the specification, at the direction of and reviewed by Ralph Amissah. -**One reader per language, in a directory named for the language.** - | | | |--------------------|---------| | [`dlang/`](dlang/) | D | | [`gleam/`](gleam/) | Gleam | -| `ruby/` | to come | ## What it is for 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. +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 ─┐ @@ -45,13 +45,14 @@ ocda-read [--tree|--html|--llm-text|--llm-jsonl|--images|--verify --image-dir=<d 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. +and `.sisupod`**, for every document-language of the markup document +samples. 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 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; @@ -66,6 +67,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: @@ -78,14 +84,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. @@ -96,15 +102,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 the `.ssp` reader, which carried the same code. +Fixed here and in the `.ssp` reader, `sisudoc-ssp-reader`, which carried the +same code. ### the whole-model dump: four more @@ -124,8 +130,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 @@ -151,8 +157,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. @@ -172,11 +178,25 @@ 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. + +## License -At format **2.x**. +AGPL-3.0-or-later: the license text is in [`LICENSE`](LICENSE), the notice in +[`COPYRIGHT`](COPYRIGHT). |
