diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-05-11 20:41:31 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-05-11 20:41:31 -0400 |
| commit | c17ca174c4aca4ed6cf47682f5f49389502b8ae5 (patch) | |
| tree | 773db069aacf475cab30d8f0581138004bce8b1a | |
| parent | rename .sda references and files to .ssp (diff) | |
docs: add README under git.sisudoc.org/tools/ namespaceold-main-abandoned
Add a top-level README.md identifying the repository as a
specification (not a program), summarising what .ssp is (a
human-readable, PEG-parsable serialisation of spine's in-memory
document abstraction), listing the line-type grammar at a glance,
and pointing readers at format-specification.md for the full
reference and at the two example .ssp files shipped alongside.
Canonical URLs use the new git.sisudoc.org/tools/ namespace,
matching the parallel moves in tree-sitter-sisu and ssp-reader
and the local rename of sisudoc-spine-utils/ to
sisudoc-spine-tools/. Cross-references to ssp-reader and
tree-sitter-sisu follow the same convention.
(assisted by Claude-Code)
| -rw-r--r-- | README.md | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..865de1b --- /dev/null +++ b/README.md @@ -0,0 +1,109 @@ +# 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), + [`example-wealth-of-networks.ssp`](example-wealth-of-networks.ssp) - + worked examples spine itself produced from real source documents. + +## 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/tools/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 --ssp --output=/tmp/out path/to/doc.sst +ls /tmp/out/**/*.ssp +``` + +(See sisudoc-spine's CLI help for the current flag name if `--ssp` +changes.) + +## 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/tools/doc-abstraction-format +- **Clone:** `git clone --depth=1 git://git.sisudoc.org/tools/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/tools/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/tools/tree-sitter-sisu) - + tree-sitter grammar for the upstream `.sst` / `.ssm` markup that + spine consumes before producing `.ssp`. |
