summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-10-13 16:54:02 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-10-22 21:35:49 -0400
commitfb1abe780c644df1b0593fa5dbc1ef8d28688693 (patch)
tree6b62395fa1e81808aa1d38f8f2bdb3394bfd8f12
parentformat 2.1: ocda-read, the readers folded in (diff)
release 2.1.0: versions, a nix-gleam build, READMEclaude-spec-matchup-redo
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. gleam/flake.lock: flake.nix names the nixpkgs channel url, but the lock still recorded the github pin it replaced, so every build rewrote it. The lock as nix rewrote it is the one built and checked; it moves nixpkgs forward to 26.11pre1088030. 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 document markup 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"; - a short section on building, a link to the specification, the format as 2.1, and the licence. 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)
-rw-r--r--README.md89
-rw-r--r--dlang/dub.json2
-rw-r--r--dlang/flake.nix2
-rw-r--r--gleam/README.md23
-rw-r--r--gleam/flake.lock17
-rw-r--r--gleam/gleam.toml2
6 files changed, 76 insertions, 59 deletions
diff --git a/README.md b/README.md
index e58ecac..16b08ed 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +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 (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 ─┐
@@ -40,14 +42,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;
@@ -62,6 +63,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:
@@ -74,14 +80,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.
@@ -92,15 +98,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
@@ -120,8 +126,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
@@ -147,8 +153,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.
@@ -168,11 +174,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).
diff --git a/dlang/dub.json b/dlang/dub.json
index 861c2cc..6b77a17 100644
--- a/dlang/dub.json
+++ b/dlang/dub.json
@@ -2,7 +2,7 @@
"authors": [ "Ralph Amissah" ],
"copyright": "Copyright (C) 2026 Ralph Amissah",
"name": "ocda-lib",
- "version": "2.0.0",
+ "version": "2.1.0",
"description": "the object-centric document abstraction as a library: the model, and loaders for its two serialisations",
"homepage": "https://sisudoc.org",
"license": "AGPL-3.0+",
diff --git a/dlang/flake.nix b/dlang/flake.nix
index 2241af6..240f9af 100644
--- a/dlang/flake.nix
+++ b/dlang/flake.nix
@@ -20,7 +20,7 @@
mkTool = { tool, binary, what, mains, compiler, compilerBin }:
pkgs.stdenv.mkDerivation {
pname = "ocda-lib-${tool}";
- version = "2.0.0";
+ version = "2.1.0";
src = self;
nativeBuildInputs = [ compiler ];
buildInputs = [ pkgs.sqlite pkgs.zstd ];
diff --git a/gleam/README.md b/gleam/README.md
index 482db38..8135005 100644
--- a/gleam/README.md
+++ b/gleam/README.md
@@ -60,12 +60,12 @@ the whole model out canonically, and is the stronger check of the two,
because it is **byte for byte what the D library's `ocda-dump` writes**.
So the four questions can all be asked with `diff`:
-| | |
-|-----------------------------|-----------------------------|
-| 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 document-language |
+| Gleam: `.ssp` == `.ocda.db` | every document-language |
+| `.ssp`: D == Gleam | every document-language |
+| `.ocda.db`: D == Gleam | every document-language |
## Deliberately a mirror of the D library
@@ -112,11 +112,12 @@ nix develop -c gleam test
Shipped as an Erlang shipment rather than an escript, because sqlite on the
BEAM is a NIF and a NIF cannot be loaded from inside an escript archive.
-The dependency hash in `flake.nix` pins what `manifest.toml` pins; change
-one and the other must change with it.
+The build is nix-gleam's, kept in `nix-gleam/` (see its README): each Hex
+dependency is fetched on its own, with the checksum gleam wrote into
+`manifest.toml`, so there is no hash in `flake.nix` to keep up to date.
## Format
-Specified in **sisudoc-abstraction-format**: `ocda-model.org` for the model,
-`ssp-format-specification.org` and `ocda-db-format-specification.org` for the
-two serialisations. At format **2.x**.
+Specified in **sisudoc-abstraction-format**: `ocda-model.md` for the model,
+`ssp-format-specification.md` and `ocda-db-format-specification.md` for the
+two serialisations. At format **2.1**.
diff --git a/gleam/flake.lock b/gleam/flake.lock
index 5f236ab..0ccb16f 100644
--- a/gleam/flake.lock
+++ b/gleam/flake.lock
@@ -2,18 +2,15 @@
"nodes": {
"nixpkgs": {
"locked": {
- "lastModified": 1790185690,
- "narHash": "sha256-xJ+X4hBtOcAFGBOe5nAMyMUeF9foJBmIOu3NjBqBycU=",
- "owner": "NixOS",
- "repo": "nixpkgs",
- "rev": "4975466d324710c576dc11ad614684e6bd8cad8e",
- "type": "github"
+ "lastModified": 1791487292,
+ "narHash": "sha256-6BIvCXtdLW4HQwsOGkgH444aB3vCbHypE9TA78ireh8=",
+ "rev": "8edc0c72e3a38faf5434e40d1f19431125fe4b30",
+ "type": "tarball",
+ "url": "https://releases.nixos.org/nixpkgs/nixpkgs-26.11pre1088030.8edc0c72e3a3/nixexprs.tar.zst"
},
"original": {
- "owner": "NixOS",
- "ref": "nixos-unstable",
- "repo": "nixpkgs",
- "type": "github"
+ "type": "tarball",
+ "url": "https://channels.nixos.org/nixpkgs-unstable/nixexprs.tar.zst"
}
},
"root": {
diff --git a/gleam/gleam.toml b/gleam/gleam.toml
index 7b474eb..66d3280 100644
--- a/gleam/gleam.toml
+++ b/gleam/gleam.toml
@@ -1,5 +1,5 @@
name = "ocda_lib"
-version = "2.0.0"
+version = "2.1.0"
description = "the object-centric document abstraction as a library: the model, and loaders for its two serialisations"
licences = ["AGPL-3.0-or-later"]