summaryrefslogtreecommitdiffhomepage
path: root/README.org
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-10-01 19:06:40 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-10-01 19:06:40 -0400
commit9b9391327424febd5bd774d2ce35ecc137c79a58 (patch)
treea4b4467693d64dd3b55ff3a1b893cba2ffd59c0a /README.org
parentthe specification in org: links to the section, not "see section 3" (diff)
the specification uses org, rather than being markdown in orgclaude-convert-md-to-org
The first conversion carried markdown's forms across. This one uses the structures org has for what the specification holds: - each .ssp property is a heading of its own under section 6.3, its order, value, condition and count in a property drawer, with an id (prop-parent) that the database specification's column tables link to. The table at the head of 6.3 is a column view of those headings, regenerated from them, so it cannot drift from them; - the @meta keys are a checklist, checked where the reference collection uses them, and the counts (28 of 43, and each group's) are org's own count of the checks rather than a number in the prose; - tables whose cells were prose are definition lists: the version history, with org dates, the note marks, the @source and @make keys, the model's three terms and two serialisations; - what is formal is a named source block: the grammar (ssp-grammar, tangled to ssp.peg), the database queries (sqlite, tangled to ocda-db-queries.sql, runnable in place given :db), and .ssp lines as ssp blocks. Tangled files are generated and not tracked; - inline code is ~code~ rather than =verbatim=: org reads a table cell that begins with "=" as a formula once the table is edited, and two tables had been rewritten to #ERROR that way; - README: a section on reading it in org, and the pandoc filter that makes a markdown copy for a forge, an export rather than a second source, with every link between the documents and to a section kept. Fixed in passing, both from the first conversion: the @meta table's "exercised" marks had been read by pandoc as emphasis and lost, and a code span after ".." had not rendered. Checked: each document exports with org's broken-link check on; every link into another document names an id it has; every table row has its table's number of cells; every word of the markdown is in the org bar table headings, titles and the rewording named above; the tangled queries run against a format 2.1 database; every link in the markdown copy resolves. (assisted by Claude-Code) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Diffstat (limited to 'README.org')
-rw-r--r--README.org109
1 files changed, 83 insertions, 26 deletions
diff --git a/README.org b/README.org
index 6ce8575..bf8f1eb 100644
--- a/README.org
+++ b/README.org
@@ -7,8 +7,8 @@
Specification of the *object-centric document abstraction* that
[[https://git.sisudoc.org/projects/sisudoc-spine][sisudoc-spine]] builds from
-SiSU markup, and of the two forms it is written in: *=.ssp=*, text and
-PEG-parsable, and *=.ocda.db=*, sqlite.
+SiSU markup, and of the two forms it is written in: *~.ssp~*, text and
+PEG-parsable, and *~.ocda.db~*, sqlite.
The two carry one version number between them, because neither may express
what the other cannot.
@@ -19,19 +19,19 @@ what the other cannot.
:END:
A specification, not a program. The repository ships:
-- [[file:ocda-model.org][=ocda-model.org=]] - *the model*: what an object is,
+- [[file:ocda-model.org][~ocda-model.org~]] - *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.
-- [[file:ssp-format-specification.org][=ssp-format-specification.org=]] - *the
- =.ssp=*: the model written as text.
-- [[file:ocda-db-format-specification.org][=ocda-db-format-specification.org=]] -
- *the =.ocda.db=*: the model written as sqlite.
-- [[file:example-autonomous-contract.ssp][=example-autonomous-contract.ssp=]] -
+ /abstraction/ and ~.ssp~ are told apart.
+- [[file:ssp-format-specification.org][~ssp-format-specification.org~]] - *the
+ ~.ssp~*: the model written as text.
+- [[file:ocda-db-format-specification.org][~ocda-db-format-specification.org~]] -
+ *the ~.ocda.db~*: the model written as sqlite.
+- [[file:example-autonomous-contract.ssp][~example-autonomous-contract.ssp~]] -
spine's output for that sample document, complete and unedited.
-- [[file:example-wealth-of-networks.ssp][=example-wealth-of-networks.ssp=]] -
+- [[file: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
+ 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.
@@ -47,16 +47,16 @@ poem, so from 2.0 to 2.1 each changed by its version line alone).
The format is at *2.1*, and says so on the first line of every
file:
-#+begin_example
+#+begin_src ssp
% SiSU Document Abstraction v2.1
-#+end_example
+#+end_src
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=?
+* What is ~.ssp~?
:PROPERTIES:
:CUSTOM_ID: what-is-ssp
:END:
@@ -64,22 +64,22 @@ 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
+("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-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
+- 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
-[[file:ssp-format-specification.org][=ssp-format-specification.org=]]):
+[[file:ssp-format-specification.org][~ssp-format-specification.org~]]):
#+begin_example
@name { section / block open
@@ -104,7 +104,7 @@ Line types (full grammar in
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
+~.sst~ / ~.ssm~ markup, which spine then turns into ~.ssp~ along
the way to the final output formats.
* Quickstart
@@ -123,7 +123,7 @@ Look at a real example:
$EDITOR example-wealth-of-networks.ssp
#+end_src
-Generate your own =.ssp= from a sample document via spine:
+Generate your own ~.ssp~ from a sample document via spine:
#+begin_src sh
# inside sisudoc-spine/
@@ -131,9 +131,66 @@ result/bin/spine --source --pod2 --output=/tmp/ssp path/to/pod
ls /tmp/ssp/*/abstraction/*.ssp
#+end_src
-=--pod2= writes the abstraction as =.ssp= and bundles it into the
+~--pod2~ writes the abstraction as ~.ssp~ and bundles it into the
source pod. (See sisudoc-spine's CLI help for the current flags.)
+* Reading it in org
+:PROPERTIES:
+:CUSTOM_ID: reading-it-in-org
+:END:
+The specification is written in org, and uses it for more than markup:
+
+- *Each numbered section has an id* (~sec-6-3~), and every "section 6.3" in
+ the text is a link to it, in its own document or another.
+- *Each ~.ssp~ property is a heading* of its own under
+ [[file:ssp-format-specification.org::#sec-6-3][section 6.3]] of the ~.ssp~
+ specification, with its order, value, condition and count in a property
+ drawer and an id (~prop-parent~) that the database specification links to.
+ The table at the head of the section is a /column view/ of those headings:
+ ~C-c C-c~ on its ~#+BEGIN~ line regenerates it, so the table and the
+ properties cannot disagree for longer than it takes to press it.
+- *The ~@meta~ keys are a checklist*, a key checked where the reference
+ collection uses it, and the counts on the heading and on each group are
+ org's own count of the checks: ~C-c #~ on a heading updates them.
+- *What is formal is a named source block*: the grammar (~ssp-grammar~,
+ tangled to ~ssp.peg~), the database queries (~ocda-db-query-1~ to ~5~, as
+ ~sqlite~ blocks tangled to ~ocda-db-queries.sql~), and ~.ssp~ lines as
+ ~ssp~ blocks. ~C-c C-v t~ tangles a document's blocks to their files, which
+ are generated and not kept in the repository. A query block runs in place
+ with ~C-c C-c~ given a database, by adding ~:db <file>.ocda.db~ to its
+ header.
+
+A markdown copy, for a forge that renders markdown and not org, is an export
+rather than a second source. The filter below keeps the links between the
+documents and to their sections working in the copy:
+
+#+begin_src sh
+for f in README ocda-model ssp-format-specification ocda-db-format-specification; do
+ pandoc -f org -t gfm -s --wrap=preserve --lua-filter org-to-md.lua "$f.org" -o "$f.md"
+done
+#+end_src
+
+#+NAME: org-to-md
+#+begin_src lua :tangle org-to-md.lua
+-- links between the documents go to the .md, and every section keeps the
+-- id the org gave it, so that a link to a section still lands on it
+function Link(el)
+ el.target = el.target:gsub("^([%w%-]+)%.org::#", "%1.md#"):gsub("^([%w%-]+)%.org$", "%1.md")
+ return el
+end
+function Header(el)
+ if el.identifier ~= "" then
+ table.insert(el.content, 1, pandoc.RawInline("html", '<a id="' .. el.identifier .. '"></a>'))
+ end
+ return el
+end
+function Code(el)
+ el.text = el.text:gsub("^(README)%.org$", "%1.md"):gsub("^(ocda%-model)%.org$", "%1.md")
+ :gsub("^([%w%-]+%-format%-specification)%.org$", "%1.md")
+ return el
+end
+#+end_src
+
* License
:PROPERTIES:
:CUSTOM_ID: license
@@ -147,17 +204,17 @@ project.
:CUSTOM_ID: repository
:END:
- *Canonical URL:* [[https://git.sisudoc.org/projects/sisudoc-abstraction-format]]
-- *Clone:* =git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format=
+- *Clone:* ~git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format~
* Related projects
:PROPERTIES:
:CUSTOM_ID: related-projects
:END:
- [[https://git.sisudoc.org/projects/sisudoc-spine][sisudoc-spine]] -
- the document engine that produces =.ssp= files.
+ the document engine that produces ~.ssp~ files.
- [[https://git.sisudoc.org/projects/ssp-reader][ssp-reader]] -
- reference reader; renders =.ssp= to tree outline, HTML, plain
+ reference reader; renders ~.ssp~ to tree outline, HTML, plain
text with breadcrumbs, or LLM-ready JSONL.
- [[https://git.sisudoc.org/projects/tree-sitter-sisu][tree-sitter-sisu]] -
- tree-sitter grammar for the upstream =.sst= / =.ssm= markup that
- spine consumes before producing =.ssp=.
+ tree-sitter grammar for the upstream ~.sst~ / ~.ssm~ markup that
+ spine consumes before producing ~.ssp~.