diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-01 19:06:40 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-01 19:06:40 -0400 |
| commit | 9b9391327424febd5bd774d2ce35ecc137c79a58 (patch) | |
| tree | a4b4467693d64dd3b55ff3a1b893cba2ffd59c0a /README.org | |
| parent | the 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.org | 109 |
1 files changed, 83 insertions, 26 deletions
@@ -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~. |
