# ssp-reader Readers for the **`.ssp`** document abstraction, the object-centric document abstraction written as text, which `sisudoc-spine` emits and reads. **One reader per language, in a directory named for the language.** | | | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | [`dlang/`](dlang/) | D. Outline, HTML scroll, breadcrumbed text, JSONL chunks for embedding pipelines, an image manifest, image verification, and `--validate` | | [`gleam/`](gleam/) | Gleam. Summary, outline, and what it did not understand | | `ruby/` | to come | ## Why more than one These are not three tools that happen to share a name. They are **the same specification implemented more than once**, and the interesting thing about them is that they agree. Each was written from the format specification, `doc-abstraction-format`, rather than from spine's emitter or from each other. Run over the 36 document reference collection, **the D and Gleam readers agree on the section counts of all 36**. That is the point of the exercise. A specification that one implementation follows is a description of that implementation; a specification that two independent implementations follow, in languages with nothing in common, is a description of the format. ## What a reader must do From the specification's conformance section, and both readers do it: - **check the major version** declared on the first line and refuse a major it does not know, rather than loading an unfamiliar artefact half populated in silence; - **tolerate unknown properties** within a major version, since the minor part is raised precisely by adding them; - **say what it ignored**, on request. A reader that drops what it does not know is conforming; one that cannot say what it dropped cannot show a specification to be complete, silence and understanding being alike from outside. The last is why both carry `--report-unknown`, and it has earned its place: it found that the D reader was rendering markup comments into its HTML, text and JSONL output, because it was ignoring the property that says an object is commentary. ## Building Each language directory builds in its own way and says how in its own README. Neither depends on the other. ## The format Specified in **doc-abstraction-format**: `ocda-model.md` for the model both serialisations share, `ssp-format-specification.md` for this one, and `ocda-db-format-specification.md` for the sqlite form. The readers here are at format **2.x**.