summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--README.md109
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`.