summaryrefslogtreecommitdiffhomepage
path: root/README.md
blob: 34a2dc62040d3c8c20b4c0a076709c7b5428ef88 (plain)
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
# sisudoc-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, `sisudoc-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 **sisudoc-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**.