diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-04-18 20:28:29 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-03 12:07:15 -0400 |
| commit | 0bf25dac62f2f8351367bc55ff9b373e380f7cf0 (patch) | |
| tree | 6de0d5805ce835a3ceedb64afec0d609add0ad34 /README.md | |
sisudoc-abstraction-format 2.0: ocda-model & .ssp
In the age of maleable, replacable, improvable, text, we here continue
to seek to being able to represent set text in a fixed, determinate way.
this is an effort using an LLM to extract the document abstraction
specifications for the program spine (Anthropic's Claude Code is used):
- within the program spine the document abstraction can be captured in
a .ssp document abstraction serialization file, which is a peg
parsable serialisation (from which other document abstractions can be
derived, such as the sqlite ocda-db abstraction)
https://git.sisudoc.org/sisudoc-spine/
git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine
- here in the specification: capturing, describing, stating the
specification of the abstraction as captured by the .ssp document
serialization, with enough detail and precision to enable the
independent reading and writing of the abstraction.
https://git.sisudoc.org/sisudoc-abstraction-format/
git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format
- in the tools/ namespace attempts are made to successfuly, perfectly
re-read and write from the abstraction using the specification alone
(without use of any other prior or outside knowledge of the .ssp
serialization format)
sisudoc-abstraction-format is derived from the spine emitter,
sisudoc/ocda/abstraction/ssp.d, whose sspObjectRecord is the single
definition of what an object looks like, and checked against the
document markup sample set.
Should there be a difference the emitter is normative and the
specification is wrong; and it states so.
Three documents, so the model is described once rather than in each
format specification:
ocda-model.md the model: what an object is, the
citation number, structure,
sections, segments, digests. The
part both serialisations share
ssp-format-specification.md the model written as text
ocda-db-format-specification.md the model written as sqlite, to
come
The naming follows the three levels: ocda names the model,
abstraction names the pipeline stage, and .ssp and .ocda.db name the
two serialisations. A thing is named for the level it belongs to,
which is why this file is ssp-format-specification.md and not
ocda-format-specification.md: it specifies one serialisation, not the
model.
The specification states the version and the policy that governs it,
and separates conformance into what a reader must do, should do, and
what a writer must do. The single "should" is that a reader should
report what it ignored: without it, silence cannot be told from
understanding.
Both worked examples regenerated from spine 0.25.0. The excerpt
carries one complete object embedding an image, so the .image record
and the image marker in the object text can be read against each
other.
The name .ssp is recorded: it belongs to the .sst, .ssm, .ssi family
and stands loosely for sisu peg or sisu parsable, .ssa for sisu
abstraction having been thought taken by other projects.
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)
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..3b2b329 --- /dev/null +++ b/README.md @@ -0,0 +1,138 @@ +# sisudoc-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/sisudoc-spine). + +## What this is + +A specification, not a program. The repository ships: + +- [`ocda-model.md`](ocda-model.md) - **the model**: what an object is, + the citation number, structure, sections, segments, digests. The part + both serialisations share, and the place the three terms *ocda*, + *abstraction* and `.ssp` are told apart. +- [`ssp-format-specification.md`](ssp-format-specification.md) - **the + `.ssp`**: the model written as text. +- `ocda-db-format-specification.md` - **the `.ocda.db`**: the model written + as sqlite. To come. +- [`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 27,769 lines. + +Both carry, in their opening comment lines, the command that +regenerates them, so they can be diffed against a run rather than +taken on trust. Both are output of **spine 0.25.0, format 2.0**. + +## Version + +The format is at **2.0**, and says so on the first line of every +file: + +``` +% SiSU Document Abstraction v2.0 +``` + +The minor part is raised when a property is added, the major part +when one changes meaning or goes away, and a reader checks the major +part and refuses what it does not know. The history is in the +specification. + +## 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/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/sisudoc-spine) +project. + +## Repository + +- **Canonical URL:** https://git.sisudoc.org/sisudoc-abstraction-format +- **Clone:** `git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format` + +## Related projects + +- [sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) - + the document engine that produces `.ssp` files. +- [ssp-reader](https://git.sisudoc.org/sisudoc-ocda-lib) - +- [ssp-writer](https://git.sisudoc.org/sisudoc-ocda-writer) - + reference reader; renders `.ssp` to tree outline, HTML, plain + text with breadcrumbs, or LLM-ready JSONL. +- [tree-sitter-sisu](https://git.sisudoc.org/tree-sitter-sisu) - + tree-sitter grammar for the upstream `.sst` / `.ssm` markup that + spine consumes before producing `.ssp`. |
