diff options
| -rw-r--r-- | README.md | 89 | ||||
| -rw-r--r-- | dlang/dub.json | 2 | ||||
| -rw-r--r-- | dlang/flake.nix | 2 | ||||
| -rw-r--r-- | gleam/README.md | 23 | ||||
| -rw-r--r-- | gleam/flake.lock | 17 | ||||
| -rw-r--r-- | gleam/gleam.toml | 2 |
6 files changed, 76 insertions, 59 deletions
@@ -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"] |
