1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
|
# 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**.
|