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
|
# doc-abstraction-format
Specification for the **`.ssp`** text format - a human-readable,
PEG-parsable serialisation of the in-memory document abstraction
produced by [sisudoc-spine](https://git.sisudoc.org/projects/sisudoc-spine).
## What this is
A specification, not a program. The repository ships:
- [`format-specification.md`](format-specification.md) - the format
reference.
- [`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 some 19,500 lines.
Both carry, in their opening comment lines, the command that
regenerates them and the spine version they came from, so they can
be diffed against a run rather than taken on trust.
## 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
[`format-specification.md`](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
(the reference implementation is
[ssp-reader](https://git.sisudoc.org/projects/ssp-reader)).
- 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 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/*/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/projects/sisudoc-spine)
project.
## Repository
- **Canonical URL:** https://git.sisudoc.org/projects/doc-abstraction-format
- **Clone:** `git clone --depth=1 git://git.sisudoc.org/specs/doc-abstraction-format`
## Related projects
- [sisudoc-spine](https://git.sisudoc.org/projects/sisudoc-spine) -
the document engine that produces `.ssp` files.
- [ssp-reader](https://git.sisudoc.org/projects/ssp-reader) -
reference reader; renders `.ssp` to tree outline, HTML, plain
text with breadcrumbs, or LLM-ready JSONL.
- [tree-sitter-sisu](https://git.sisudoc.org/projects/tree-sitter-sisu) -
tree-sitter grammar for the upstream `.sst` / `.ssm` markup that
spine consumes before producing `.ssp`.
|