summaryrefslogtreecommitdiffhomepage
path: root/README.md
blob: b3d5c80e30e136669dd81438c7b5fc6890f3c8f5 (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
# 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`.