From 3f34ec6afde21801eff0b655949a6d219e47943c Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Tue, 13 Oct 2026 16:54:02 -0400 Subject: release 2.1.0: versions, the library locked, the pipeline The writer's version follows the format's: 2.1.0 in dub.json, gleam.toml and both flakes (it was 2.0.0), and manifest.toml locks the library at 2.1.0 to match. A release is numbered major.minor.patch, major.minor being the format and shared with the specification and the library, the patch the writer's own. flake.lock, in dlang/ and gleam/, pins the library at its 2.1.0 release and nixpkgs as that release locks it, so the writer builds with what the library was built and checked with. The READMEs say plain nix build, and how to build against a working copy of the library instead. The pipeline no longer builds or runs sisudoc-ssp-reader and sisudoc-ocda-db-reader, which are frozen: ocda-read, the library's reader, covers both, and read.sh already ran it from both forms and in both languages. Gone from build.sh, config.sh, one.sh and read.sh, and from pipeline/README.md, which with config.sh now names spine's --show-abstraction as the README does. build.sh still gives the writer the library beside it, so that the library run and the library built in are the same one. README, to what was decided for these writers: the outputs must be identical from every form and the D and Gleam writers must agree byte for byte, but they are not held to spine's bytes; each format has its own judge, and a difference from spine is there to read better. The introduction said "identical to each other and to spine's", and the example compared --text with spine's text file, which fails by design; the example now compares the .ssp and the .ocda.db. The documents the checks run over are the markup document samples, named with their repository and the spine flags that build the artefacts, and the counts read "all" or "every document" rather than a number, here and in dlang/, gleam/ and pipeline/README.md. The format is 2.1, and the license is stated. Checked: D and Gleam build from the lock; over the markup document samples, D == Gleam in text, markdown, html, epub and typst for every document-language, and the .ssp and the .ocda.db give the same output. (assisted by Claude-Code) --- pipeline/README.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) (limited to 'pipeline/README.md') diff --git a/pipeline/README.md b/pipeline/README.md index c5920f7..b5adc84 100644 --- a/pipeline/README.md +++ b/pipeline/README.md @@ -1,13 +1,13 @@ -# The pipeline: how to run the readers, the library and the writers +# The pipeline: how to run the library, its reader and the writers Fixed scripts rather than a test suite. They produce output that is meant to be **looked at**, and they double as the answer to "what do I type?". ``` config.sh where everything is, and where the output goes -build.sh build every reader, library and writer, in both languages +build.sh build the library and the writer, in both languages one.sh one tool, one document - the answer to "how do I run this?" -read.sh every reader and both libraries, over every document +read.sh the library and its reader, over every document write.sh every writer, in both languages, over every document pdf.sh compile the .typ files that write.sh produced run.sh all of the above, in order @@ -20,7 +20,7 @@ document-language and a `.ocda.db` for each document, and, where there is one, a `.sisupod` beside it. That is what spine writes: ```sh -spine --abstraction --ocda-db --pod2 --output= ... +spine --show-abstraction --ocda-db --pod2 --output= ... ``` Everything downstream reads those files and nothing else. **No tool here @@ -44,8 +44,6 @@ at something. ## Where the output goes ``` -$OUT/read/ssp-d/ ssp-g/ the .ssp readers' summaries -$OUT/read/db-d/ db-g/ the .ocda.db readers' summaries $OUT/read/dump-d/ dump-g/ the library's dump, from each serialisation $OUT/write/text/{d,g}/ .txt $OUT/write/md/{d,g}/ .md @@ -70,8 +68,8 @@ sh pipeline/one.sh read-d .sisupod en --tree The tool names are `-`: `text`, `md`, `html`, `epub`, `typst` for the writers, `read` for the library's reader (ocda-read, which -reads every form and takes its modes after the file), and `ssp`, `db`, `dump`, -`agree` for the older readers and the library; `-d` for D and `-g` for Gleam. +reads every form and takes its modes after the file), and `dump`, `agree` for +the library; `-d` for D and `-g` for Gleam. Output goes to stdout, so a comparison is a pipeline. The epub and the typst name a file instead, because an epub is a zip and a `.typ` names its images by @@ -86,7 +84,7 @@ typst compile --root d d/x.typ d/x.pdf ## What the counts at the end mean Each stage prints a few numbers. They are not a pass, they are a way to see a -regression without reading 36 documents. +regression without reading every document. | `all four dumps identical` | the library's whole claim: two serialisations, two languages, one model | |---|---| -- cgit v1.2.3