# 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`.