diff options
| -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`. |
