summaryrefslogtreecommitdiffhomepage
path: root/README.md
blob: 400bced2c52d472cd4f796d72103ea7f4d1db7be (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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
# sisudoc-abstraction-format

Specification of the **object-centric document abstraction** that
[sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) builds from
SiSU markup, and of the two forms it is written in: **`.ssp`**, text and
PEG-parsable, and **`.ocda.db`**, sqlite.

The two carry one version number between them, because neither may express
what the other cannot.

## What this is

A specification, not a program. The repository ships:

- [`ocda-model.md`](ocda-model.md) - **the model**: what an object is,
  the citation number, structure, sections, segments, digests. The part
  both serialisations share, and the place the three terms *ocda*,
  *abstraction* and `.ssp` are told apart.
- [`ssp-format-specification.md`](ssp-format-specification.md) - **the
  `.ssp`**: the model written as text.
- [`ocda-db-format-specification.md`](ocda-db-format-specification.md) -
  **the `.ocda.db`**: the model written as sqlite.
- [`example-autonomous-contract.ssp`](example-autonomous-contract.ssp) -
  spine's output for that sample document, complete and unedited.
- [`example-wealth-of-networks.ssp`](example-wealth-of-networks.ssp) -
  an excerpt of spine's output for that sample document: verbatim
  lines, marked elisions, keeping the preamble, the `@head` section
  and a run of body objects that includes an object embedding an
  image. The whole file runs to 27,769 lines.

Both carry, in their opening comment lines, the command that
regenerates them, so they can be diffed against a run rather than
taken on trust. Both are output of **spine, format 2.1** (neither holds a
poem, so from 2.0 to 2.1 each changed by its version line alone).

## Version

The format is at **2.1**, and says so on the first line of every
file:

```
% SiSU Document Abstraction v2.1
```

The minor part is raised when a property is added, the major part
when one changes meaning or goes away, and a reader checks the major
part and refuses what it does not know. The history is in the
specification.

## What is `.ssp`?

Spine's processing pipeline goes
**markup -> abstraction -> output**. The abstraction stage builds an
in-memory object model: every paragraph, heading, table, footnote
etc. is a numbered object with parent / sibling / type metadata
("OCN" - Object Citation Numbering). `.ssp` is a faithful text
serialisation of that object model.

It is designed for:

- Inspecting and debugging spine's abstraction stage.
- Diff-friendly version control of document structure (a `.ssp`
  diff between two markup edits shows exactly which objects
  changed).
- Round-trip experiments: markup -> spine -> `.ssp` -> alternative
  renderers (HTML, LLM-ready chunks, ...) without rerunning spine.
- A stable contract between spine and downstream consumers that do
  not want to link against spine's internal D types.

Line types (full grammar in
[`ssp-format-specification.md`](ssp-format-specification.md)):

```
@name {           section / block open
}                  section / block close
[N] type ...       object declaration (N = OCN, 0 if unnumbered)
.name: value       property of the preceding object
| text content     text line of the preceding object
                   blank line (object separator)
% comment          comment (ignored by parser)
```

## Audience

- Developers writing readers / converters for spine's abstraction
  (readers written from this specification alone:
  sisudoc-ssp-reader, sisudoc-ocda-db-reader, now frozen with current readers
  offered and maintained within sisudoc-ocda-lib).
- Anyone studying spine's internal document model without reading
  the D source.
- LLM / search / indexing tooling that consumes structured
  document data downstream of spine.

End-user document authors do not need to read this; they write
`.sst` / `.ssm` markup, which spine then turns into `.ssp` along
the way to the final output formats.

## Quickstart

Read the spec:

```sh
$EDITOR ssp-format-specification.md
```

Look at a real example:

```sh
$EDITOR example-wealth-of-networks.ssp
```

Generate your own `.ssp` from a sample document via spine:

```sh
# inside sisudoc-spine/
result/bin/spine --source --pod2 --output=/tmp/ssp path/to/pod
ls /tmp/ssp/pod/*/media/abstraction/*.ssp
```

`--pod2` writes the abstraction as `.ssp` and bundles it into the
source pod. (See sisudoc-spine's CLI help for the current flags.)

## License

AGPL-3.0-or-later, matching the parent
[sisudoc-spine](https://git.sisudoc.org/sisudoc-spine)
project.

## Repository

- **Canonical URL:** https://git.sisudoc.org/sisudoc-abstraction-format
- **Clone:** `git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format`

## Related projects

- [sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) - the document
  engine that writes `.ssp` and `.ocda.db` files.
- [sisudoc-ocda-lib](https://git.sisudoc.org/sisudoc-ocda-lib) - the
  abstraction read as a library, from a .ssp, a .ocda.db or a
  .sisupod (D and Gleam). To be published.
- [sisudoc-ocda-writer](https://git.sisudoc.org/sisudoc-ocda-writer) -
  sample writers over that library (text, markdown, html, epub, typst),
  each checked against spine. To be published.
- [tree-sitter-sisu](https://git.sisudoc.org/tree-sitter-sisu) - grammar
  for the .sst / .ssm markup spine reads before writing a .ssp.