diff options
| -rw-r--r-- | README.md | 9 | ||||
| -rw-r--r-- | claude-org/ocda_specification.org | 1630 | ||||
| -rw-r--r-- | claude-org/sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org | 252 | ||||
| -rw-r--r-- | ssp-format-specification.md | 17 |
4 files changed, 1908 insertions, 0 deletions
@@ -47,6 +47,11 @@ 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. +A release is numbered `major.minor.patch`. `major.minor` is the format, and +is shared by the specification and the programs that implement it; the patch +is each one's own, and changes nothing a file can contain, so it is not +written in a file. + ## What is `.ssp`? Spine's processing pipeline goes @@ -141,5 +146,9 @@ project. - [sisudoc-ocda-writer](https://git.sisudoc.org/sisudoc-ocda-writer) - sample writers over that library (text, markdown, html, epub, typst), each checked against spine. To be published. +- [sisudoc-ssp-reader](https://git.sisudoc.org/sisudoc-ssp-reader) and + [sisudoc-ocda-db-reader](https://git.sisudoc.org/sisudoc-ocda-db-reader) - + the first readers, written from this specification alone, in D and in + Gleam; frozen, their work now done by `ocda-read` in sisudoc-ocda-lib. - [tree-sitter-sisu](https://git.sisudoc.org/tree-sitter-sisu) - grammar for the .sst / .ssm markup spine reads before writing a .ssp. diff --git a/claude-org/ocda_specification.org b/claude-org/ocda_specification.org new file mode 100644 index 0000000..6bb169d --- /dev/null +++ b/claude-org/ocda_specification.org @@ -0,0 +1,1630 @@ +-*- mode: org -*- +#+TITLE: configuration git +#+DESCRIPTION: documents - structuring, various output representations & search +#+FILETAGS: :spine:hub: +#+AUTHOR: Ralph Amissah +#+EMAIL: [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]] +#+COPYRIGHT: Copyright (C) 2015 (continuously updated, current 2026) Ralph Amissah +#+LANGUAGE: en +#+STARTUP: content hideblocks hidestars noindent entitiespretty +#+PROPERTY: header-args+ :eval never-export :exports code +#+PROPERTY: header-args+ :noweb yes :padline no +#+PROPERTY: header-args+ :results silent :cache no +#+PROPERTY: header-args+ :mkdirp yes +#+OPTIONS: H:3 num:nil toc:t \n:t ::t |:t ^:nil -:t f:t *:t + +* ./ +** README.md + +#+HEADER: :tangle ../README.md +#+HEADER: :noweb yes +#+BEGIN_SRC md +# sisudoc-abstraction-format + +Specification of the **object-centric document abstraction** that +[sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) builds from +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. + +## 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`](ocda-db-format-specification.md) - + **the `.ocda.db`**: the model written as sqlite. +- [`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, format 2.1** (neither holds a +poem, so from 2.0 to 2.1 each changed by its version line alone). + +## Version + +The format is at **2.1**, and says so on the first line of every +file: + +``` +% SiSU Document Abstraction v2.1 +``` + +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. + +A release is numbered `major.minor.patch`. `major.minor` is the format, and +is shared by the specification and the programs that implement it; the patch +is each one's own, and changes nothing a file can contain, so it is not +written in a file. + +## 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 +[`ssp-format-specification.md`](ssp-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 + (readers written from this specification alone: + sisudoc-ssp-reader, sisudoc-ocda-db-reader, now frozen with current readers + offered and maintained within sisudoc-ocda-lib). +- 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 ssp-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/pod/*/media/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 writes `.ssp` and `.ocda.db` files. +- [sisudoc-ocda-lib](https://git.sisudoc.org/sisudoc-ocda-lib) - the + abstraction read as a library, from a .ssp, a .ocda.db or a + .sisupod (D and Gleam). To be published. +- [sisudoc-ocda-writer](https://git.sisudoc.org/sisudoc-ocda-writer) - + sample writers over that library (text, markdown, html, epub, typst), + each checked against spine. To be published. +- [sisudoc-ssp-reader](https://git.sisudoc.org/sisudoc-ssp-reader) and + [sisudoc-ocda-db-reader](https://git.sisudoc.org/sisudoc-ocda-db-reader) - + the first readers, written from this specification alone, in D and in + Gleam; frozen, their work now done by `ocda-read` in sisudoc-ocda-lib. +- [tree-sitter-sisu](https://git.sisudoc.org/tree-sitter-sisu) - grammar + for the .sst / .ssm markup spine reads before writing a .ssp. +#+END_SRC + +** git .gitignore :gitignore: + +#+HEADER: :tangle "../.gitignore" +#+BEGIN_SRC gitignore +,* +!.gitignore +!*.nix +!flake.lock +!*.md +!*.ssp +!org/ +!**/*.org +!**/COPYRIGHT +#+END_SRC + +** ocda-model.md + +#+HEADER: :tangle ../ocda-model.md +#+BEGIN_SRC md +# The object-centric document abstraction (OCDA) + +,**The model.** What a document *is* once spine has parsed it, independent +of any file it is written to. + +Two serialisations carry this model, and they carry **one version number +between them**, because neither may express what the other cannot: + +| | | +|----------------------------------------------------------------------|--------------------------------| +| [`ssp-format-specification.md`](ssp-format-specification.md) | the OCDA as text, `.ssp` | +| [`ocda-db-format-specification.md`](ocda-db-format-specification.md) | the OCDA as sqlite, `.ocda.db` | + +This document is what they share. It describes objects; they describe +writing objects down. + +## 1. Three words, and what each names + +The terms are used precisely in this repository and in spine, and the +distinction is worth holding: + +| level | term | names | +|--------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| the model | **OCDA** | what a document is once parsed: numbered objects with structure, identity and digests. Independent of any file, any stage, any tool | +| the stage | **abstraction** | the middle of spine's **markup -> abstraction -> output**: the act of building the model, and the point at which a document may now enter the pipeline | +| the serialisations | **`.ssp`**, **`.ocda.db`** | the model written down, as text and as sqlite | + +A thing is named for the level it belongs to. Something true of the model +whatever file it is in takes *ocda*; something about the pipeline stage +takes *abstraction*; something that reads or writes one file form takes +that form's name. + +## 2. The object + +A document is a sequence of **objects**, grouped into sections. An object +is a paragraph, a heading, a table, an endnote, a line of verse: the unit +the document is made of and the unit it is cited by. + +Every object carries: + +- an **object citation number** (OCN), section 3; +- an **identifier**, section 3.1; +- a **kind** and a **type**, section 2.1; +- its **place in the structure**: parent, ancestors, and for a heading its + children and its last descendant, section 4; +- the **segment** it is in, and for a heading an **anchor**, sections 7 + and 7.1; +- its **text**, in spine's internal representation; +- a **digest** of that text. + +### 2.1 Kind and type: two axes, not one + +An object is classified twice, and the two answer different questions. + +,**Kind** (`is_a`) says *what the object is*, one of sixteen. Each kind +belongs to one section, except `heading`, which appears in all nine: + +| kind | section | what it is | count | +|----------------|--------------|--------------------------------------------------------------------------------|--------| +| `para` | body | a paragraph, the ordinary unit of a document | 41,885 | +| `heading` | *all nine* | a heading at one of the eight levels | 3,503 | +| `toc` | toc | an entry in the generated table of contents | 3,215 | +| `bookindex` | bookindex | an entry in the generated book index | 3,034 | +| `endnote` | endnotes | a note, gathered from where it was called | 2,294 | +| `code` | body | a code block | 1,623 | +| `bibliography` | bibliography | a bibliography entry | 585 | +| `comment` | body | markup comment, carried and not rendered | 450 | +| `verse` | body | one verse of a poem | 151 | +| `glossary` | glossary | a glossary entry | 56 | +| `quote` | body | a block quotation | 53 | +| `poem` | body | a poem: the container of its verses, OCN `0`, cited as their range (section 5) | 48 | +| `block` | body | a block of grouped text | 45 | +| `table` | body | a table, with its columns described | 32 | +| `blurb` | blurb | a blurb entry | 28 | +| `group` | body | a group block | 16 | + +,**Type** (`is_of_type`) says *how the object's text behaves*, and takes +only three values: + +| type | means | kinds | +|-----------|---------------------------------------------------------|---------------------------------------------------------------------------------------| +| `para` | flowing text, wrapped as the output sees fit | `para`, `heading`, `toc`, `bookindex`, `endnote`, `bibliography`, `glossary`, `blurb` | +| `block` | text whose line breaks are significant and must be kept | `code`, `verse`, `quote`, `poem`, `block`, `table`, `group` | +| `comment` | not rendered | `comment` | + +The mapping from kind to type is fixed: every `code` object is of type +`block`, every `para` object of type `para`. **A renderer that has the type +does not need to know all sixteen kinds** to decide whether it may reflow +the text, which is what the second axis is for. + +## 3. The object citation number + +The OCN is the heart of the model and the reason for it. + +,**An object's OCN is the same in every format spine writes.** A paragraph +that is object 42 in the HTML is object 42 in the EPUB, in the PDF, in the +plain text, in the search database and in both serialisations of the +abstraction. A citation to object 42 of a document is therefore a citation +to a fixed piece of text, not to a page in one edition or a scroll position +in one rendering. + +Three properties follow, and each is a trap for a reader that assumes +otherwise: + +- **Not every object has one.** Generated furniture, and objects the markup + has suppressed, carry `0`. There are many of them: 7,543 across the 36 + document reference collection. +- **`0` is therefore not an identity.** Objects sharing `0` are not the + same object, and `0` must never be used as a key. +- **A non-zero OCN is unique within a document**, from format 2.1: checked + over the reference collection, no non-zero OCN occurs twice in any of the + 36 document-languages. **Before 2.1 it was not**: a poem carried the OCN of + its last verse, so the same number named two objects (48 such pairs in the + collection, 21 in `through_the_looking_glass`). A reader of an older + artefact keys on position within a section when one row is wanted. + +### 3.1 The identifier + +Every object also carries an **identifier**: the name by which an output +refers to it. An HTML anchor, a LaTeX `\hypertarget`, a link from a book +index entry to the object it indexes, are all written from the identifier. + +,**The identifier of an object with a non-zero OCN is its OCN**, written as +text. That is the ordinary case and it is the reason a citation to object +42 can be turned into a link without consulting anything. + +An object with OCN `0` has no OCN to take an identifier from, so one is +assigned: `a1`, `a2`, `a3`, ... in document order over the objects that +need one. There are few of them, eleven in a book, and they are the +generated furniture of section 3. + +,**A reader must arrive at the identifier whether or not the serialisation +wrote it down**; see section 9. + +## 4. Levels + +A document has **eight heading levels**, in two groups of four: + +| level | index | what it is | +|-------|-------|----------------------------------------------| +| `A` | 0 | the document title. Exactly one per document | +| `B` | 1 | | +| `C` | 2 | the title matter below it | +| `D` | 3 | | +| `1` | 4 | the top level of the document body | +| `2` | 5 | | +| `3` | 6 | below that | +| `4` | 7 | | + +`A` to `D` are the title levels, `1` to `4` the body levels, and the index +is what the eight-slot arrays of section 5 are indexed by. A heading that +claims no level has 9, which is the "not a heading level" value and is why +`.heading_lev_collapsed` is emitted only when it is below 9. + +,**Collapsed levels.** A document that uses `A` and then `1`, skipping `B`, +`C` and `D`, has a gap in its levels that is an artefact of the markup +rather than of the document. Every level-indexed array therefore comes in +two forms: as marked up, and **collapsed**, with the unused levels removed +so that the remaining ones are contiguous. Outputs that care about nesting +depth use the collapsed form; anything tracing back to the markup uses the +other. + +## 5. Structure + +Structure is carried by number, not by nesting: an object names its parent +rather than containing its children. This is what lets the serialisations +be flat and the model be walked in either direction. + +- **`parent`** - the OCN of the object this one hangs from. + **A parent of `0` is not "no parent"**: it is a parent heading the author + has made non-substantive, its OCN suppressed or a dummy heading + introduced to segment an output. The distinction is preserved + deliberately, and a reader walking upward must stop at `0` rather than + treat it as missing, or the walk will not terminate. +- **`ancestors`** - **eight slots, indexed by level** (section 4): the OCN + of the heading at each level above this object, `0` where there is none, + so the path to the root is available without walking it. + **A heading's own OCN sits in its own level's slot**: checked over the + reference collection, 3,432 headings of 3,432. So for a heading the array + is its path including itself, and for any other object it is the path to + the heading above it. +- **`ancestors_collapsed`** - the same, in collapsed levels. +- **`children`** - a heading's child headings. +- **`last_descendant`** - the last OCN under a heading, which makes a + subtree a **range** rather than a traversal: everything from the + heading's OCN to its last descendant is inside it. +- **`ocn_range`** - for a **container**, the first and last OCN of what it + holds (2.1). A poem is the one container: its verses are the citable + units, one object each, and the poem is not; it carries OCN `0` and no + identifier, **comes immediately before its first verse**, and is cited as + the range of them (`173-180`). So a writer that meets a poem knows what + follows and where it ends, and can wrap the verses in one pass. The poem + has no text of its own. `0 0`, or absent, where the object is not a + container. + **Before 2.1** the poem came *after* its last verse, carried that verse's + OCN and identifier, and stated no range. + +## 6. Sections + +Objects are grouped into nine sections, in this order: + +``` +head toc body endnotes glossary bibliography bookindex blurb tail +``` + +`head` is the document's title matter, `body` the document proper, and the +rest are generated or gathered. `tail` is the end of document some output +writers use. A section with no objects is not carried. + +## 7. Segments + +An output may be one file or many. A **segment** is one of the many: a +chapter-sized piece of HTML or EPUB with its own name and its own +navigation. + +Two different questions are asked about segments, and the model answers +both separately because the answers differ: + +- **which segment does this heading open?** Set on headings only. +- **which segment is this object in?** Set on nearly every object. + +Without the second, a reader cannot say where a paragraph belongs. The +search database reads the second. + +### 7.1 The anchor + +A heading carries an **anchor**: the name an output links to in order to +arrive at that heading. It is what a table of contents entry and a +cross reference point at. + +,**An object's anchor is its segment name**, in the ordinary case, because a +heading that opens a segment is arrived at by arriving at the segment. It +differs only where a heading is not the opening of the segment it sits in: +69 of the 72 anchors in one reference document equal their segment and 3 do +not. + +,**A reader must arrive at the anchor whether or not the serialisation wrote +it down**; see section 9. + +## 8. Digests + +The model is checkable at four levels, and the chain is what lets an +artefact be verified rather than trusted: + +``` +the markup files ──> a digest over every markup file of that language +the serialisation ──> a digest of the .ssp a database was built from +each object ──> a digest of the object's text +each image ──> a digest of the image file, with its size in bytes and pixels +``` + +An object's digest is over its text alone, so a change to one paragraph +moves one digest and no other. + +## 9. Derived values, and why a reader must derive them + +Two of the values above are **derived**: the identifier from the OCN +(section 3.1), and the anchor from the segment name (section 7.1). The +model holds them; a serialisation need not, and the text form does not. + +,**A serialisation may omit a value it can compute.** The `.ssp` writes a +property only when it carries information, so it omits `.identifier` where +the identifier is the OCN and `.anchor` where the anchor is the segment +name. The `.ocda.db` is columns rather than lines and writes both +unconditionally. + +Both are conforming. What is **not** conforming is a reader that takes the +text form literally and hands on a model with those fields empty, because +that model is not the same model the database gives, and a writer over it +will produce different output from the two serialisations of one document. + +The size of the difference is easy to underestimate. In +`free_culture.lawrence_lessig` the `.ssp` omits **1,314 identifiers and 69 +anchors** that the `.ocda.db` states, which is nearly every object in the +document. + +So, on loading: + +| field | when absent | take | +|------------|--------------------------|------------------------------------------------------------------| +| identifier | OCN is non-zero | the OCN as text | +| identifier | OCN is `0` | whatever the serialisation gave; there is nothing to derive from | +| anchor | the object has a segment | the segment name | + +,**This is a property of the model, not of either format**, which is why it +is stated here and not only in the two format specifications. It is stated +here *because* two readers written independently from these documents +disagreed for want of it: the rule was implied by the `.ssp`'s emission +conditions and nowhere asserted. + +It is also what **spine's own reader** does, and always did, which is why +the `.ocda.db` carries the derived values: the database is written from the +`.ssp` read straight back, and the reading fills both in. So this section +documents existing behaviour rather than prescribing new. It should have +been written down first. + +## 10. What the model does not hold + +- **The markup.** The model is what the markup produced, not the markup + itself. An artefact that carries both is the `.ocda.db`, which carries + the markup alongside the model rather than within it. +- **The images.** The model *names* them, with digest, byte size and pixel + size, and they must be found beside the file for a document to be + complete. +- **Any output format.** No HTML, no page numbers, no typesetting. +#+END_SRC + +** ssp-format-specification.md + +#+HEADER: :tangle ../ssp-format-specification.md +#+BEGIN_SRC md +# The `.ssp` format + +,**The object-centric document abstraction, written as text. Format version +2.1**, as spine emits and reads it after 0.25.1. + +This document specifies *one serialisation*. The model it serialises is +specified in [`ocda-model.md`](ocda-model.md), which the sqlite +serialisation shares; read that first if the question is what an object +,*is* rather than how it is written down. + +## The name + +`.ssp` belongs to the family of SiSU markup extensions, `.sst` (sisu text), +`.ssm` (sisu master) and `.ssi` (sisu insert), and a short extension was +wanted that sat with them. It stands loosely for **sisu peg**, or **sisu +parsable**. `.ssa`, for sisu abstraction, was thought to be taken by other +projects. + +So the extension names the *file family and its parsability*, where +`.ocda.db` names the *model and its container*. The two are not parallel in +construction and are not meant to be. + +## Status + +This specification is derived from the emitter +(`sisudoc/ocda/abstraction/ssp.d` in sisudoc-spine, whose `sspObjectRecord` +is "the single definition of what an object looks like in a `.ssp` file"), +and every claim in it is checked against the project's 36 document +reference set. Where the two could differ, the emitter is normative and +this document is wrong. + +## 1. What a `.ssp` is + +A `.ssp` file is the serialisation, as text, of one language of one +document after spine has parsed it: the object model, not the markup and +not any output format. + +Spine's pipeline is **markup -> abstraction -> output**. A `.ssp` is the +middle stage written down. Since spine 0.25.0 it is also read back, so a +document may enter the pipeline at the abstraction stage instead of being +parsed, and the output writers cannot tell which happened. + +The format is: + +- **line oriented.** Every construct is a whole line. No line continuations. +- **order significant.** Sections appear in a fixed order, objects in + document order, and an object's properties in a fixed order (section 6.3). +- **UTF-8**, without a byte order mark. +- **lossless for the abstraction**, not for the markup: a `.ssp` read back + and re-emitted is byte identical, which the project's test suite asserts + over the whole reference set. + +### 1.1 What it is not + +It does not carry the markup it was made from, and it does not carry its +images: it *names* them, with their digests and pixel sizes, and they must +be found beside it (`../image/` within a pod) for the document to be +complete. An artefact that carries both is the `.ocda.db`, which is built +by reading a `.ssp` back, so it can hold nothing this format cannot express. + +## 2. Version and compatibility + +The version is declared **in band**, on the first line of every file: + +``` +% SiSU Document Abstraction v2.1 +``` + +and by the sibling sqlite serialisation in its `schema.version` metadata +row, so that one bump moves both. + +### 2.1 The rule + +- The **minor** part is raised when a property is **added**. A reader of the + newer format still reads the older one. +- The **major** part is raised when a property **changes meaning or goes + away**. +- A reader **checks the major part and refuses what it does not know**, + rather than loading an unfamiliar artefact half populated in silence. +- A **patch** part, the third, numbers *releases* and not the format: a + correction or clarification of this text, or a fix in a program that + implements it, changes nothing a file can contain. So a file declares + `major.minor` only, and a release is `major.minor.patch`. The + specification and the programs that implement it share `major.minor`, + which is the format, and each numbers its own patches. + +### 2.2 History + +| version | date | what moved | +|---------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 2.1 | 2026-09-29 | `.ocn_range`, the first and last ocn of what a container holds. A poem is a container of verses and is cited as their range: it now comes before its first verse, carries ocn `0` and no identifier, and states the range, where it had come after its last verse carrying that verse's ocn and identifier, so that one number named two objects. A minor bump: the property is an addition, the poem was never rendered and has no text, the verses are unchanged, and a 2.0 reader reads a 2.1 file. The same run gathers a note in a poem's last verse into the endnotes, which it had not been: one more endnote in the reference collection. And the editor's notes, `~[* ]~` and `~[+ ]~`, which spine had not recognised and passed through as text, are notes: a third form of note mark, a symbol and a number (`*1`, `+1`), each series numbered through the document; 135 more endnotes, 2,294 in all (section 3.2, "A note begins with its mark"). | +| 2.0 | 2026-09-18 | `source.digest` changes meaning: it covers every markup file the document is made of, where it had been the digest of the master file alone. A change of meaning, so the major part. | +| 1.1 | 2026-09-10 | The `@source` block; the document metadata the output writers read, carried in full (14 `@meta` and 3 `@make` properties added); `.segment_lv4_is`. | +| 0.1 | | The first form. | + +### 2.3 Releases of this specification + +| release | format | what | +|---------|--------|---------------------------------------------------------------------| +| 2.0.0 | 2.0 | the model and the `.ssp` | +| 2.0.1 | 2.0 | the object kinds and types, the levels, the make block, the markers | +| 2.0.2 | 2.0 | the `.ocda.db`; two rules a validator found unstated | +| 2.0.3 | 2.0 | the derived values: the identifier and the anchor | +| 2.1.0 | 2.1 | `.ocn_range`, and the editor's notes | +| 2.1.1 | 2.1 | the patch part of a release number, and this table | + +## 3. Lexical structure + +Six line types, distinguished by their first character. Nothing else is a +valid line. + +| line | form | meaning | +|--------------------|-----------------|-----------------------------------------------| +| comment | `% ...` | file header only (section 4) | +| block open | `@name {` | opens a preamble block or a section | +| block close | `}` | closes it | +| key | ` key: value` | inside a preamble block, two spaces of indent | +| object declaration | `[ocn] kind...` | opens an object record (section 6.1) | +| property | `.name: value` | a property of the object just declared | +| text | `\| text` | a line of the object's text | +| blank | | separates records; carries no meaning | + +A value runs to the **end of the line**. It is not quoted, and it is not +trimmed beyond the single space after the colon. A value may therefore +contain `:`, spaces, and any UTF-8 character except a line break. + +### 3.1 Escaping + +Only one value is escaped, because only one value is a **joined list**: +`.heading_ancestors_text` joins eight slots with `|`. A slot that itself +contains `|`, a backslash, or a line break would otherwise be unreadable. + +| in the value | written as | +|-----------------|------------| +| `\` | `\\` | +| `\|` | `\\|` | +| newline | `\n` | +| carriage return | `\r` | + +Unescaping reads left to right: a backslash escapes the next character, +`\n` and `\r` become the control characters, any other escaped character +stands for itself, and an unescaped `|` ends the slot. + +,**No other value is escaped**, and text lines are not escaped at all: a +text line is the object's text verbatim after the two-character `| ` +prefix. + +### 3.2 Object text is internal markup + +The text on `|` lines is spine's **internal** representation, neither the +author's markup nor any output. It carries the markers spine uses to hold +inline structure: + +The full set is defined in spine's `InlineMarkup` (`ocda/meta/defaults.d`). +Counts are occurrences in object text across the 36 document reference +collection, which distinguishes what a reader will certainly meet from what +it may not. + +| marker | means | count | where | +|-------------|---------------------------------------------|--------|----------------------| +| `░` | non-breaking space | 23,048 | | +| `┥` `┝` | link text, open and close | 20,290 | | +| `┤` `├` | link target, open and close | 20,290 | | +| `⑆` | a page number of the source edition follows | 19,099 | | +| `┨` `┣` | that page number, open and close | 19,099 | | +| `■` | monospace | 10,688 | | +| `【` `】` | an inline note, its mark first (below) | 2,294 | | +| `¤` | an internal site link | 2,157 | | +| `┊` | table cell separator | 695 | `table` objects only | +| `┙` | line break, inline | 184 | | +| `☼` | an image, in a link's text slot | 63 | | +| `┚` | line break, spaced | 50 | `group` objects only | +| `〖` `〗` | a starred note | 0 | | +| `‖` | a citation | 0 | | +| `┘` | line break, plain | 0 | | +| `┼` `┿` `╂` | page break: line, page, new page | 0 | | +| `┏` `┆` | table open, table paragraph | 0 | | +| `␣` | separator | 0 | | + +,**A count of 0 means the reference collection does not exercise it, not +that it cannot appear.** All of these are defined by the emitter and a +reader must be prepared for them. + +,**A note begins with its mark**, then whitespace, then the note: `【12 text】`. +The mark is one of three forms, and a reader must take all three: + +| mark | what | example | +|-------------------------|-------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| digits | the author's notes, numbered through the document | `【12 ...】` | +| `*` or `+`, repeated | a special note, marked by the symbols alone | `【** ...】` | +| `*` or `+`, then digits | an editor's note (2.1): the markup's `~[* ]~` and `~[+ ]~`, each series numbered through the document apart from the author's | `【*3 ...】`, `【+1 ...】` | + +So the pattern is `【(\d+|[*+]+[0-9]*)\s`. Before 2.1 the third form did not +occur: spine did not recognise the editor's-note markup, and it came through +as text, `~[* ...]~` and all. Each note of every form is gathered into the +`endnotes` section, where its `.anchor_tag` is `note_` and the mark +(`note_12`, `note_*3`). + +Two traps in this table, both found by counting rather than by reading: + +,**`┚` is defined twice**, as the spaced line break and as the table close. +In object text it occurs only in `group` objects, never in a `table`, so +the object's kind resolves it. A reader should decide by kind rather than +by character. + +,**`「` and `」` are not markers here.** They are defined in `InlineMarkup` +as the wrapper spine's ODT writer puts around an object number, but that +happens at output, after the abstraction. Their 67 occurrences in the +reference collection are **Japanese corner brackets in the document's own +text**, being quotation marks in Japanese. In a `.ssp` they are always +content. + +Some markers are the ASCII characters `*`, `!`, `/`, `_`, `^` and `,` for +emphasis, bold, italic, underscore, superscript and subscript. These are +,**not distinguishable from ordinary text by inspection**, and a reader that +needs them must follow spine's rules for where they apply rather than +searching for the characters. + +A reader that renders text must decode all of this; a reader that only +searches or counts need not, and one that wants plain text may strip the +non-ASCII markers and take the ASCII ones as text. They are stable and they +are part of the format. + +## 4. File shape + +In order, and this order is fixed: + +``` +% SiSU Document Abstraction v2.1 +% Source: <markup filename> + +@source { ... } + +@meta { ... } + +@make { ... } + +@doc_has { ... } + +@head { ... } +@toc { ... } +@body { ... } +@endnotes { ... } +@glossary { ... } +@bibliography { ... } +@bookindex { ... } +@blurb { ... } +@tail { ... } +``` + +The two `%` lines are the only comments in the file and appear only here. +The four preamble blocks are always present and always in that order. The +nine section blocks appear in that order. **A section is omitted entirely +when the document has no objects for it**, though in practice that is rare: +all 36 documents of the reference collection carry all nine, several of +them holding a single generated object. + +## 5. The preamble blocks + +Inside a block, every line is ` key: value` with exactly two spaces of +indent. Keys are unique within a block. **A key whose value is empty is +omitted**, so the set of keys present varies by document; the exceptions +are noted below. + +### 5.1 `@source` - what this abstraction was made from + +| key | always? | meaning | +|-------------|----------------------------|-----------------------------------------------------------------------------| +| `language` | yes | the language of *this* file | +| `languages` | when the pod declares them | every language of the document, space separated | +| `digest` | yes | sha256 over **every markup file the document is made of**, in a fixed order | + +The source *filename* is not repeated here; it is on the `% Source:` line. + +`digest` is what changed in 2.0. It had been the digest of the master file +alone, which for a single file document was right and for a multi-file one +was close to meaningless: any chapter could be edited without the digest +moving. + +### 5.2 `@meta` - the document's own metadata + +Dublin-Core shaped, `group.name`. **43 keys are defined**; a given document +carries only those it has. The 28 the reference collection exercises are +marked; the remainder are defined and simply unused by these documents. + +| group | keys | +|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `title.` | `main`*, `subtitle`*, `full`*, `language`*, `edition`* | +| `creator.` | `author`*, `author_surname`*, `author_surname_fn`*, `author_email`*, `illustrator`*, `translator`* | +| `date.` | `published`*, `created`*, `issued`*, `available`*, `modified`*, `valid`*, `added_to_site`* | +| `rights.` | `copyright`*, `license`*, `copyright_text`, `copyright_translation`, `copyright_illustrations`, `copyright_photographs`, `copyright_cover`, `copyright_audio`, `copyright_video` | +| `classify.` | `topic_register`*, `subject`, `keywords`, `loc`*, `dewey`* | +| `identifier.` | `isbn`, `oclc` | +| `notes.` | `summary`*, `abstract`*, `description`* | +| `original.` | `source`*, `title`, `language`, `language_char` | +| `language.` | `document_char`*, `document` | + +`classify.topic_register` is structured within its value: topics separated +by `;`, levels within a topic by `:`, and alternatives at a level by `|`. + +### 5.3 `@make` - how the document is to be built + +| key | value | meaning | +|-------------------------|--------------------------|--------------------------------------------------------------------------------------------------------| +| `doc_type` | `article`, `book` | what kind of document this is | +| `auto_num_top_at_level` | a level, e.g. `1` | the heading level automatic numbering starts at, **as written in the markup** | +| `auto_num_top_lv` | that level's index, 0..8 | the same level as a number (section 4 of [`ocda-model.md`](ocda-model.md)); `9` where numbering is off | +| `auto_num_depth` | e.g. `2` | how many levels down numbering continues | +| `breaks` | see below | where the output starts a new page, and where it breaks one | +| `footer` | slots joined with `\|` | the footer, each slot carrying link markup | +| `home_button_text` | link markup | the home link, as internal markup | + +`auto_num_top_at_level` and `auto_num_top_lv` are **the same value twice**, +as the markup wrote it and as an index: `1` and `4`, since the body levels +begin at index 4. + +`breaks` is a small language of its own, `new=` for a new page and +`break=` for a page break, each taking a comma separated list of levels, +the two separated by `;`: + +``` +breaks: new=:A,:B; break=:C,1 +breaks: new=:B; break=1 +breaks: break=1 +``` + +The level names here are written as they are in the markup, so with or +without the leading colon as the document wrote them; a reader should not +assume either form. + +### 5.4 `@doc_has` - what the document contains, by count + +Ten keys, **all ten always emitted**, zero included. This block is a +summary a reader can use without walking the objects. + +``` +inline_links inline_notes_reg inline_notes_star tables codeblocks +images poems groups blocks quotes +``` + +## 6. Objects + +The nine section blocks hold object records, in document order. An object +record is an object declaration line, then its properties, then its text +lines, then a blank line. + +### 6.1 The declaration line + +``` +[<ocn>] <kind> +[<ocn>] heading :<level> +[<ocn>] heading :<level> <identifier> +``` + +`<ocn>` is the **object citation number** (see +[`ocda-model.md`](ocda-model.md) section 3). `[0]` means the object has +none, is shared by many objects, and must never be used as a key; key on +position within a section instead. + +`<kind>` is one of sixteen: + +``` +para heading toc bookindex endnote code bibliography comment +verse glossary quote poem block table blurb group +``` + +A **heading** is the one kind whose declaration line carries more: its +markup level after a colon (`:A` `:B` `:C` `:D` for the title levels, +`:1`..`:4` for the body levels; `:D` is defined and unexercised by the +reference collection), and then its identifier, when it has one +that is not simply the ocn. Every other kind carries an identifier, on the +same condition, as the `.identifier` property. + +> **A reader must derive the identifier where it is absent, and the anchor +> likewise.** "when it has one that is not simply the ocn" means the +> identifier *is* the ocn in every other case, and a reader that leaves the +> field empty gives a different model from the one the `.ocda.db` gives, on +> nearly every object. Section 9 of [`ocda-model.md`](ocda-model.md) states +> both derivations and why they belong to the model rather than to either +> format. Two readers written independently from these documents disagreed +> for want of it. + +### 6.2 Text lines + +``` +| <text> +``` + +One line per line of the object's text, in order, each prefixed with +`| ` (pipe, space). An object with no text has no text lines. The text is +internal markup (section 3.2) and is not escaped. + +### 6.3 Properties + +,**Properties appear in a fixed order**, the order of the table below, and a +reader may rely on it: checked over the reference set, no object among +56,882 emits a property out of this order. + +,**A property is omitted when it holds its default**, so absence is +meaningful and is defined per property in the table. Four properties +repeat, appearing once per value rather than carrying a list: `.image`, +`.stow_link`, `.lev4_subtoc` and `.anchor_tag`. + +Two consequences of the order, which a validator needs stated and which +hold over the whole reference collection: + +- **a repeated property's occurrences are consecutive.** They share one + position in the order, and nothing is written between them. Checked: no + repeat in the collection is separated by another property. +- **no property follows the text.** The record is declaration, then + properties, then text lines, and once a `|` line has been written no + further property appears. Checked: 0 occurrences in the collection. + +In the table, "emitted when" is the condition under which the property +appears at all. Counts are occurrences across the 36 document reference +set, as a guide to which parts of the format are load bearing. + +| # | property | value | emitted when | count | +|----|---------------------------|-------------------------------|----------------------------------------------------------------------------------------------------|--------| +| 1 | `.identifier` | string | a non-heading has an identifier that is not its ocn (**otherwise it is the ocn**: model section 9) | 353 | +| 2 | `.part` | string | the object belongs to a part (`frontmatter`, `body`, ...) | 57,018 | +| 3 | `.section` | string | the object's own section differs from the block it sits in | 605 | +| 4 | `.parent` | int | **every object except** the document root and `toc` entries | 53,767 | +| 5 | `.last_descendant` | int | non-zero: the last ocn under this heading | 3,202 | +| 6 | `.ocn_range` | 2 ints | the object is a container: the first and last ocn of what it holds (2.1; a poem, model section 5) | 48 | +| 7 | `.children` | ints | the heading has child headings | 827 | +| 8 | `.ancestors` | 8 ints | any is non-zero | 53,731 | +| 9 | `.ancestors_collapsed` | 8 ints | any is non-zero | 53,731 | +| 10 | `.dom_status` | 8 ints | any is non-zero | 3,319 | +| 11 | `.dom_status_collapsed` | 8 ints | any is non-zero | 3,319 | +| 12 | `.heading_lev_collapsed` | int | it is below 9 | 3,503 | +| 13 | `.parent_lev` | int | non-zero | 52,984 | +| 14 | `.dummy` | `true` | the heading was introduced to segment an output | 183 | +| 15 | `.ocn_off` | `true` | the object has no citation number | 7,543 | +| 16 | `.is_of_type` | string | always, in practice | 57,018 | +| 17 | `.attrib` | string | set | 1 | +| 18 | `.meta_lang` | string | the object carries its own language | 0 | +| 19 | `.meta_syntax` | string | the object carries its own markup syntax | 0 | +| 20 | `.sha256` | hex | the object's text digest is non-zero | 51,253 | +| 21 | `.image` | record | once **per image**, in order of appearance | 63 | +| 22 | `.indent` | 2 ints | either indent is non-zero: `base hang` | 7,583 | +| 23 | `.bullet` | `true` | the object is a bullet item | 1,903 | +| 24 | `.lang` | string | the text attributes carry a language | 0 | +| 25 | `.has` | flags | any is set | 11,384 | +| 26 | `.table_cols` | int | the object is a table with columns | 32 | +| 27 | `.table_widths` | ints | the table has column widths | 32 | +| 28 | `.table_aligns` | letters | the table has alignments (`l` `c` `r`) | 32 | +| 29 | `.table_header` | `true` | the table has a header row | 29 | +| 30 | `.code_linenumbers` | `true` | the code block is numbered | 1 | +| 31 | `.stow_link` | url | once **per extracted link** | 1,014 | +| 32 | `.segment` | string | the heading opens a segment | 3,355 | +| 33 | `.anchor` | string | the anchor differs from the segment name (**otherwise it is the segment name**: model section 9) | 68 | +| 34 | `.segment_prev` | string | there is a previous segment | 1,022 | +| 35 | `.segment_next` | string | there is a next segment | 1,022 | +| 36 | `.heading_lev_anchor` | string | the heading has a level anchor tag | 1,854 | +| 37 | `.segment_epub` | string | the heading opens an epub segment | 3,355 | +| 38 | `.segment_html_is` | string | the object is inside an html segment | 47,072 | +| 39 | `.segment_epub_is` | string | the object is inside an epub segment | 47,072 | +| 40 | `.segment_lv4_is` | string | **and** it differs from `.segment_html_is` | 342 | +| 41 | `.heading_ancestors_text` | 8 slots, `\|` joined, escaped | any slot is non-empty | 3,319 | +| 42 | `.lev4_subtoc` | string | once **per sub-table-of-contents entry** | 1,887 | +| 43 | `.anchor_tag` | string | once **per anchor tag** | 8,019 | + +Three of these need a word here, the first two because the model behind +them is easy to misread (see [`ocda-model.md`](ocda-model.md) sections 5 +and 7), the third because it is a property of this table rather than of the +format. + +,**`.parent: 0` is emitted, not omitted.** A parent of 0 is a real, +non-substantive parent and not a missing value, so the property is written +out rather than defaulted away: omitting it would make the two cases +indistinguishable in the file. A reader walking upward stops at 0. + +,**`.segment` and `.segment_html_is` are different questions**, and both are +carried: what a heading opens, and what an object sits in. A reader wanting +to know where a paragraph belongs needs the second. + +,**Count 0 does not mean "not in the format".** `.meta_lang`, `.meta_syntax` +and `.lang` are emitted by spine under the conditions given, and no +document in the reference collection meets them. A reader must handle them; +a test corpus does not exercise them. + +### 6.4 The `.image` record + +``` +.image: <filename> sha256:<HEX> bytes:<n> px:<width>x<height> +.image: <filename> missing:true +``` + +Filename first, as the object's handle on the image. The remaining fields +are self describing `key:value` tokens, **so that further fields may be +added without invalidating existing readers**; `px:` is omitted when the +pixel size is unknown. `px:` is the file's own size, not the display size, +which the object's text already carries. + +### 6.5 The `.has` flags + +Space separated, in this order, each present only when set: + +``` +links notes_reg notes_star images images_no_dim +``` + +## 7. Grammar + +,**This grammar is complete for the file shape and deliberately incomplete +for one thing: the order of properties.** A grammar that fixed the order +would have to enumerate 42 optional terms in sequence, would be unreadable, +and would need editing at every minor version, which is exactly when a +property is added. The order is a guarantee of the format (section 6.3) and +is stated there, where it can be read; a parser that wants to check it can +do so against the table. + +So: **a file that this grammar accepts and section 6.3 rejects is a +malformed file, not an ambiguity in the format.** The grammar is the shape; +the table is the contract. + +,**Checked**: every line of the 36 document reference collection matches one +of the eight line shapes below, 721,363 lines with none left over. + +```peg +Document <- Header Source Meta Make DocHas Section* EOF +Header <- "% SiSU Document Abstraction v" Version EOL + "% Source: " Value EOL Blank +Version <- Digit+ "." Digit+ + +Source <- "@source {" EOL Pair+ "}" EOL Blank +Meta <- "@meta {" EOL Pair* "}" EOL Blank +Make <- "@make {" EOL Pair* "}" EOL Blank +DocHas <- "@doc_has {" EOL Pair+ "}" EOL Blank +Pair <- " " Key ": " Value EOL +Key <- [a-z_]+ ("." [a-z_]+)? + +Section <- "@" SectionName " {" EOL Blank Object* "}" EOL Blank +SectionName <- "head" / "toc" / "body" / "endnotes" / "glossary" + / "bibliography" / "bookindex" / "blurb" / "tail" + +Object <- Decl Property* TextLine* Blank +Decl <- "[" Digit+ "] " (Heading / Kind) EOL +Heading <- "heading :" Level (" " Identifier)? +Level <- [A-D] / [1-4] +Kind <- [a-z]+ +Property <- "." Name ": " Value EOL +Name <- [a-z_0-9]+ +TextLine <- "| " Value EOL + +# a repeatable property appears once per value rather than carrying a list: +# .image .stow_link .lev4_subtoc .anchor_tag +# and .image has an inner shape of its own: +Image <- ".image: " FileName (" " Field)* EOL +Field <- Key ":" Value +FileName <- (!" " !EOL .)+ + +Value <- (!EOL .)* +Blank <- EOL +EOL <- "\n" +Digit <- [0-9] +``` + +## 8. Conformance + +### 8.1 A reader must + +- **Check the major version** on the first line and refuse a major it does + not know. Loading an unknown major half populated, in silence, is the + failure this rule exists to prevent. +- **Tolerate unknown properties** within a known major version, since the + minor part is raised precisely by adding them. Ignoring them is + conforming behaviour. +- **Treat `[0]` as not an identity.** Objects with no citation number are + numerous and share the number. +- **Stop at `.parent: 0`** when walking upward. + +### 8.2 A reader should + +- **Report what it ignored**, at least on request. A reader that silently + drops what it does not understand cannot tell its user whether it + understood the document, and cannot be used to check this specification + against an implementation. + +### 8.3 A writer must + +- Emit the blocks and sections in the order of section 4, an object's + properties in the order of section 6.3, and objects in document order. +- Omit a property holding its default, per section 6.3. +- Escape only what section 3.1 requires, and only where it requires it. + +## 9. Relationship to the model, and to the sqlite serialisation + +The model this format writes down is specified in +[`ocda-model.md`](ocda-model.md): objects, citation numbers, structure, +sections, segments and digests. This document adds nothing to the model and +subtracts nothing from it; it says how the model is written as text. + +The `.ocda.db` is the same abstraction as sqlite, and is **built by reading +a `.ssp` back**: the document is emitted as `.ssp`, read straight in, and +what comes back is written. So the database cannot carry an object property +this format cannot express, and the two cannot drift. They share the +version, which is why a bump moves both. + +The database is not a competitor to this format. It carries every language +of a document in one file, and the markup, images and configuration as +well, which this format does not. + +## 10. Worked examples + +- `example-autonomous-contract.ssp` - one document, complete and unedited. +- `example-wealth-of-networks.ssp` - an excerpt of a large one: verbatim + lines with marked elisions, keeping the preamble, the `@head` section, + and a run of body objects including one that embeds an image. + +Each carries, in its opening comments, the command that regenerates it. +#+END_SRC + +** ocda-db-format-specification.md + +#+HEADER: :tangle ../ocda-db-format-specification.md +#+BEGIN_SRC md +# The `.ocda.db` format + +,**The object-centric document abstraction, written as sqlite. Format +version 2.1**, as spine emits and reads it after 0.25.1. + +This document specifies *one serialisation*. The model it serialises is +specified in [`ocda-model.md`](ocda-model.md), which the text serialisation +shares; read that first if the question is what an object *is* rather than +how it is stored. + +## Status + +Derived from the writer, `sisudoc/outputs/io_out/sqlite_ocda_db.d`, and +checked against the 27 published databases of the project's reference +collection. Where the two could differ the writer is normative and this +document is wrong. + +## 1. What it is, and what makes it different + +One file per **document**, holding **every language of it**: a ten language +document is one database with ten rows in `documents`, written one language +at a time into the one file. + +Two things distinguish it from the `.ssp`: + +- **It carries its own source.** The markup, the images, `conf/document_make`, + `pod.manifest` and the `tools/po4a` catalogues are all inside it, in the + `files` table. A pod can be written back out of it, and spine does exactly + that when asked for an artefact that needs markup. The `.ssp` names its + images and carries none of them. +- **It is queryable without being parsed.** A question about the document is + a SELECT, answered from the file with no spine and no reader. + +### 1.1 It is built from the `.ssp` + +The document is emitted as `.ssp`, **read straight back**, and what comes +back is what is written. So **the database cannot carry an object property +the `.ssp` cannot express**, and the two cannot drift. That is also why they +share one version number: a bump moves both. + +The carried *files* are the deliberate exception. They come from the pod +rather than from the abstraction, each with its digest. + +## 2. Version + +Declared in band, in the `metadata` table: + +```sql +SELECT key, value FROM metadata WHERE doc_id IS NULL; +-- build.spine_version | 0.25.0 +-- schema.name | sisu-abstraction-db +-- schema.version | 2.1 +``` + +The rule is the model's, and identical to the `.ssp`: the minor part is +raised when a property is added, the major when one changes meaning or goes +away, and **a reader checks the major part and refuses what it does not +know**. See [`ssp-format-specification.md`](ssp-format-specification.md) +section 2 for the history, which is shared. + +## 3. The schema + +Eight tables, one virtual table, three views. + +``` + documents id, lang, source_filename, ssp_digest UNIQUE(lang) + │ doc_id + ├─ metadata doc_id, key, value UNIQUE(doc_id, key) + │ + └─ objects id, doc_id, section, seq, ocn, ... 50 columns + UNIQUE(doc_id, section, seq) + ├─ object_images object_id, seq, name, bytes, sha256, + │ width, height, missing + ├─ object_links object_id, seq, url + ├─ object_anchors object_id, seq, anchor + └─ object_subtoc object_id, seq, entry + + files id, role, name, bytes, sha256, width, height, + compression, data UNIQUE(role, name) + + objects_fts fts5 over objects.text, external content over objects.id +``` + +### 3.1 `doc_id` is the language key + +`documents.id`, referred to as `doc_id` everywhere else, is **what tells one +language's rows from another's**. It is the key to reach for in every query. + +`objects.lang` and `objects.meta_lang` are **properties of the object** and +are not it. They are almost always empty (section 6). + +### 3.2 The file-level metadata rows + +`metadata` is keyed `UNIQUE(doc_id, key)` and not on key alone, because +every language has a title and a creator and a key-only key would refuse the +second. + +Three rows describe **the file** rather than a document in it, and are +written with `doc_id` null: `schema.name`, `schema.version` and +`build.spine_version`. In SQL no null equals another null, so +`UNIQUE(doc_id, key)` does not constrain them, and a partial unique index +over `key` alone `WHERE doc_id IS NULL` is what makes them singular. + +#### 3.2.1 The key prefix carries what the `.ssp` puts in blocks + +The `.ssp` has four preamble blocks, `@source`, `@meta`, `@make` and +`@doc_has`. The database has **one** `metadata` table, and tells them apart +by a **prefix on the key**: + +| `.ssp` block | database key | +|--------------|-----------------------------------------------------------| +| `@meta` | the key as it stands: `title.main`, `creator.author`, ... | +| `@make` | `make.` + the key: `make.footer`, `make.doc_type` | +| `@doc_has` | `doc_has.` + the key: `doc_has.images`, `doc_has.tables` | +| `@source` | `source.` + the key: `source.language`, `source.digest` | + +,**A reader must strip the prefix and restore the grouping**, or a writer +over it has to ask `metadata["make.footer"]` from a database and +`make["footer"]` from a `.ssp`, which is exactly the difference the two +serialisations exist not to make. + +`source.` also carries two keys with no `@source` counterpart, +`source.filename` and `source.ssp_digest`; the `.ssp` puts the first in its +`% Source:` comment and cannot hold the second, which is a digest *of* it. + +Values may carry leading or trailing whitespace here where the `.ssp` +cannot represent it, its `key: value` line being unable to distinguish a +value that begins with a space from the separator. **Strip on load**, as a +reader of the text form necessarily does. + +### 3.3 Fixed-width arrays are JSON + +`children`, `ancestors`, `ancestors_collapsed`, `dom_status`, +`dom_status_collapsed`, `heading_ancestors_text`, `table_widths` and +`table_aligns` are stored as **JSON arrays**, with validity checks, so that +`json_extract`, `json_each` and `json_array_length` reach inside them. + +> **Parse them as JSON.** A scan that strips `[`, `]`, `,` and `"` looks +> adequate and is wrong on the first escape: the encoder writes `/` as +> `\/`, so `FREE/OPEN-SOURCE SOFTWARE` comes back as +> `FREE\/OPEN-SOURCE SOFTWARE`. All 36 document-languages of the reference +> collection contain at least one, and the defect is invisible to any check +> that does not compare the field itself. +> +> Note also that `table_widths` is an array of **integers except where the +> columns divide evenly**, when it is `[33.3333,33.3333,33.3333]`. A decoder +> that accepts strings and integers and then falls back to a default turns +> a value it could not read into one that looks read. + +The **element types**, so that a decoder can be written to accept exactly +what occurs: + +| column | elements | +|--------------------------------------------------------------------------------------|-------------------------------------------------------------------| +| `children`, `ancestors`, `ancestors_collapsed`, `dom_status`, `dom_status_collapsed` | integers | +| `table_widths` | integers, or floats where the columns divide evenly | +| `table_aligns` | strings, one of `l` `c` `r` | +| `heading_ancestors_text` | strings, eight of them, empty where that level is not an ancestor | + +The `.ssp` writes the first three groups **space separated** and +`heading_ancestors_text` **`|` separated**. The empty slots of the last are +significant: they say which levels a heading sits under, so the separators +carry as much as the text does. + +The open-ended lists are **rows in the four child tables** instead of +columns: images, links, anchor tags and sub-table-of-contents entries. Each +child table carries `seq`, which preserves the order they appeared in. + +### 3.4 Indexes + +`objects(doc_id, section)`, `objects(ocn)`, `objects(parent_ocn)`, +`objects(is_a)`, `objects(heading_level)` where it is a heading, and +`files(role)`, `object_images(name)`. + +## 4. The relationship to the `.ssp`, column by column + +,**Nothing is lost in either direction.** Every `.ssp` property is a column +or a child table; every column is a property, a value from the object +declaration line, or a database key. + +Where the names differ they differ for a reason, the `.ssp` preferring the +short form and the database the explicit one: + +| `.ssp` property | database | +|--------------------|-----------------------| +| `.parent` | `parent_ocn` | +| `.last_descendant` | `last_descendant_ocn` | +| `.dummy` | `dummy_heading` | +| `.ocn_off` | `object_number_off` | +| `.part` | `is_of_part` | +| `.section` | `is_of_section` | + +Three are **expanded**, the `.ssp` folding what the database spreads: + +| `.ssp` property | database | +|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `.indent: <base> <hang>` | `indent_base`, `indent_hang` | +| `.ocn_range: <first> <last>` | `ocn_range_first`, `ocn_range_last` (2.1: `0` where the object is not a container; a 2.0 database has neither column, and reads as no range) | +| `.has: links notes_reg notes_star images images_no_dim` | `has_links`, `has_notes_reg`, `has_notes_star`, `has_images`, `has_images_no_dim` | + +The four **repeatable** properties become the four child tables: + +| `.ssp` property | database | +|-----------------|------------------| +| `.image` | `object_images` | +| `.stow_link` | `object_links` | +| `.anchor_tag` | `object_anchors` | +| `.lev4_subtoc` | `object_subtoc` | + +And four columns come from outside the property list: `ocn`, `is_a` and +`heading_level` from the object declaration line, and `text` from its `|` +lines. `id`, `doc_id` and `seq` are the database's own keys; `seq` is the +object's position within its section, and `(doc_id, section, seq)` is what +identifies an object when `ocn` will not: `0`, or, before 2.1, a poem +sharing its last verse's number (see [`ocda-model.md`](ocda-model.md) +section 3). + +### 4.1 Where the two are not symmetric + +"Nothing is lost in either direction" is true of the model, and there are +three places where the *files* nonetheless differ. A reader must know all +three, because each of them made two independently written readers disagree. + +,**1. The database states what the `.ssp` derives.** `identifier` and +`anchor` are written on every row. The `.ssp` omits each where it can be +worked out, the identifier being the ocn and the anchor the segment name +(sections 6.1 and 6.3 of +[`ssp-format-specification.md`](ssp-format-specification.md), section 9 of +[`ocda-model.md`](ocda-model.md)). In `free_culture.lawrence_lessig` that is +,**1,314 identifiers and 69 anchors** stated here and absent there. Neither +file is the poorer; a reader that does not derive is. + +,**2. `translation.ocn_aligned` is here and cannot be in a `.ssp`.** It says +whether the languages of a document share one numbering, and a `.ssp` is one +language. It is therefore a fact about **the file**, not about the document +in it, and it is the one such fact either serialisation carries. + +A reader should **keep it out of the document model**, for the same reason +the `schema.*` and `build.*` rows are kept out: a writer over the model must +not be able to tell which serialisation it was handed, and a field that +exists only when the input was a database is exactly that tell. The model +has no place for collection-wide facts yet; when it grows one, this belongs +there. + +,**3. Whitespace and grouping**, as section 3.2.1 gives them. + +## 5. The `files` table: what it carries, and how + +| role | named by | `compression` | `data` holds | +|------------|----------------------------|---------------|------------------| +| `image` | its bare filename | `none` | the file as read | +| `source` | `media/text/<lang>/<file>` | `zstd` | a zstd frame | +| `conf` | `conf/document_make` | `zstd` | a zstd frame | +| `manifest` | `pod.manifest` | `zstd` | a zstd frame | +| `tools` | `tools/po4a/...` | `zstd` | a zstd frame | + +The `compression` column carries the literal `none` or `zstd`, so a reader +need not infer it from the role. + +Three rules make the file predictable: + +1. **Compression is decided by role, never by size.** The same kind of file + always stores the same way, so nobody need measure a document to know + what its database will look like. A very small file can come out a few + bytes larger inside a zstd frame; that is accepted rather than fixed with + a threshold, which would make two documents of the same kind store + differently for no reason a reader could see. +2. **Images are not compressed.** png and jpeg are compressed already; zstd + gains nothing and costs a decompression on every read. +3. **`objects.text` is never compressed.** The full text index reads that + column directly, and compressing it would stop search working completely + rather than subtly. + +,**`bytes` and `sha256` are always those of the original file**, whatever +`compression` says. So a digest check, a `digests.txt` line and a rebuilt +`source.digest` all keep working, and a reader that does not decompress can +still say what it is looking at. + +## 6. Querying it + +`sqlite3` is all that is needed. The recipes below were run against the +published databases. + +### 6.1 What is this file + +```sql +SELECT key, value FROM metadata WHERE doc_id IS NULL; +SELECT id, lang, source_filename FROM documents ORDER BY id; +SELECT role, count(*), sum(bytes) FROM files GROUP BY role; +``` + +### 6.2 The views + +| view | gives | +|------------------|---------------------------------------------------------------------------------------------| +| `outline` | the headings: lang, section, seq, ocn, both levels, `last_descendant_ocn`, identifier, text | +| `citable` | every object with an ocn, ordered by ocn, language named | +| `document_files` | what the file carries: role, name, bytes, sha256, pixel size | + +,**`outline` and `citable` name the language and order by it first.** A view +over a file that may hold ten languages and does not say which would read as +one document and be several. + +,**A trap in `citable`:** it is `SELECT d.lang AS lang, o.*`, and `objects` +has a `lang` column of its own, so sqlite renames the second one. The view +has **`lang`, the document's language, and `lang:1`, the object's own**. +Quote the second if you want it: `SELECT "lang:1" FROM citable`. + +### 6.3 Structure + +A heading's subtree is a **range**, not a traversal, because every heading +carries `last_descendant_ocn`: + +```sql +SELECT count(*) FROM objects o, + (SELECT doc_id, ocn, last_descendant_ocn FROM objects + WHERE is_a='heading' AND ocn=66) h + WHERE o.doc_id = h.doc_id + AND o.ocn BETWEEN h.ocn AND h.last_descendant_ocn; +``` + +And the path back up, on `parent_ocn`: + +```sql +WITH RECURSIVE up(ocn, parent_ocn, text) AS ( + SELECT ocn, parent_ocn, text FROM objects WHERE doc_id=1 AND ocn=345 + UNION ALL + SELECT o.ocn, o.parent_ocn, o.text FROM objects o + JOIN up ON o.ocn = up.parent_ocn AND o.doc_id=1 AND o.is_a='heading' + WHERE up.parent_ocn > 0) +SELECT ocn, substr(text,1,44) FROM up; +``` + +,**Keep the `parent_ocn > 0` guard.** A parent of 0 is a real, +non-substantive parent and not a missing value, and without the guard the +recursion does not terminate. + +### 6.4 Full text + +```sql +SELECT o.ocn, substr(o.text,1,44) FROM objects_fts f + JOIN objects o ON o.id = f.rowid + JOIN documents d ON d.id = o.doc_id + WHERE f.text MATCH 'commons' AND d.lang='en' AND o.ocn > 0 + ORDER BY rank LIMIT 3; +``` + +fts5 syntax is available in full: `MATCH 'peer AND production'`, +`MATCH '"peer production"'`, `MATCH 'peer NEAR production'`. + +The index is **external content** over `objects.id`: the text is indexed, +not stored twice. + +### 6.5 Three things to know before trusting a query + +1. **An ocn is not unique within a document**, and `0` is shared by many + objects. Key on `objects.id`, or on `(doc_id, section, seq)`. +2. **`objects.text` is internal markup**, neither the author's markup nor + any output. Fine for search and for reading structure, not for display + without decoding. The markers are in + [`ssp-format-specification.md`](ssp-format-specification.md) section 3.2. +3. **A multi-language file answers an unfiltered query with every language + at once.** A single-language document has one `documents` row, so plain + queries read naturally there; anything else wants `WHERE lang='..'` or a + join to `documents`. + +## 7. Digests, and verifying a file + +``` +the markup files ──> metadata source.digest sha256 over every markup file + of that language +the .ssp ──> documents.ssp_digest of the .ssp it was built from +each object ──> objects.sha256 over the object's text +each carried file──> files.sha256 over the original bytes +the spine used ──> metadata build.spine_version +``` + +So `.sst -> .ssp -> .ocda.db` is checkable end to end, and +`spine --ocda-verify=<file>` closes the loop by writing the carried markup +back out and re-parsing it: **does this spine still make this abstraction +from the markup this file carries?** It writes nothing and the exit status +is the answer. + +,**Only this artefact can answer that from itself alone**, which is the +strongest sense in which it is the one to work with. + +The database's own digest is taken once, when the last language has been +written, and appears in `digests.txt`. The metadata page links the database +and claims no hash for it, deliberately: the page is written per language +while the database is added to per language, so a digest taken there would +be of a file that no longer exists by the end of the run. + +## 8. Conformance + +A reader **must** check `schema.version`'s major part and refuse a major it +does not know; **must** treat `ocn` as not an identity; **must** stop at +`parent_ocn = 0` when walking upward; and **should** say what it did not +understand, for the reason given in +[`ssp-format-specification.md`](ssp-format-specification.md) section 8.2. + +A writer **must** keep `bytes` and `sha256` those of the original file +whatever `compression` says, and **must not** compress `objects.text`. +#+END_SRC + +* COPYRIGHT & LICENSE +** notices +*** project (project root) ./ + +#+HEADER: :tangle "../COPYRIGHT" +#+HEADER: :noweb yes +#+BEGIN_SRC org +- Name: spine - SiSU Spine, Doc Reform + <<sisudoc_spine_copyright>> + + <<sisudoc_spine_license_agpl3>> + + <<sisudoc_spine_summary>> + +<<sisudoc_spine_markup_samples>> +#+END_SRC + +*** code org ./org + +- .org literate programming: + - copyright asserted + - omitted + - license + - dependency information + +#+HEADER: :tangle "../org/COPYRIGHT" +#+HEADER: :noweb yes +#+BEGIN_SRC text +- Name: spine - SiSU Spine, Doc Reform + <<sisudoc_spine_copyright>> + + <<sisudoc_spine_license_agpl3>> + + <<sisudoc_spine_summary>> + +<<sisudoc_spine_markup_samples>> +#+END_SRC + +** incorporate +*** copyright + +#+NAME: sisudoc_spine_copyright +#+BEGIN_SRC emacs-lisp +<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_copyright()>> +#+END_SRC + +*** agpl3 + +#+NAME: sisudoc_spine_license_agpl3 +#+BEGIN_SRC emacs-lisp +<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_license_agpl3()>> +#+END_SRC + +*** spine_summary + +#+NAME: sisudoc_spine_summary +#+BEGIN_SRC emacs-lisp +<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_summary()>> +#+END_SRC + +*** markup_samples + +#+NAME: sisudoc_spine_markup_samples +#+BEGIN_SRC emacs-lisp +<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_markup_samples()>> +#+END_SRC + +* org includes +** project version + +#+NAME: spine_version +#+HEADER: :noweb yes +#+BEGIN_SRC emacs-lisp +<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:spine_project_version()>> +#+END_SRC + +** year + +#+NAME: year +#+HEADER: :noweb yes +#+BEGIN_SRC emacs-lisp +<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:year()>> +#+END_SRC + +** document header including copyright & license + +#+NAME: doc_header_including_copyright_and_license +#+HEADER: :noweb yes +#+BEGIN_SRC emacs-lisp +<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:spine_doc_header_including_copyright_and_license()>> +#+END_SRC + +* nixpkgs source + +#+NAME: nixpkgs_unstable +#+HEADER: :noweb yes +#+BEGIN_SRC emacs-lisp +<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:nixpkgs_unstable()>> +#+END_SRC + +* __END__ diff --git a/claude-org/sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org b/claude-org/sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org new file mode 100644 index 0000000..5ec2d52 --- /dev/null +++ b/claude-org/sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org @@ -0,0 +1,252 @@ +-*- mode: org -*- +#+TITLE: sisudoc spine (doc_reform) object-centric document abstraction +#+DESCRIPTION: documents - structuring, publishing in multiple formats & search +#+FILETAGS: :spine:abstraction: +#+AUTHOR: Ralph Amissah +#+EMAIL: [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]] +#+COPYRIGHT: Copyright (C) 2015 (continuously updated, current 2026) Ralph Amissah +#+LANGUAGE: en +#+STARTUP: content hideblocks hidestars noindent entitiespretty +#+PROPERTY: header-args+ :eval never-export :exports code +#+PROPERTY: header-args+ :noweb yes :padline no +#+PROPERTY: header-args+ :results silent :cache no +#+PROPERTY: header-args+ :mkdirp yes +#+OPTIONS: H:3 num:nil toc:t \n:t ::t |:t ^:nil -:t f:t *:t + +- [[./doc-reform.org][doc-reform.org]] [[./][org/]] + +* spine doc header including copyright & license + +#+NAME: spine_doc_header_including_copyright_and_license +#+BEGIN_SRC org +/+ +- Name: SisuDoc Spine, Doc Reform [a part of] + - Description: documents, structuring, processing, publishing, search + - static content generator + + - Author: Ralph Amissah + [ralph.amissah@gmail.com] + + - Copyright: (C) 2015 (continuously updated, current 2026) Ralph Amissah, All Rights Reserved. + + - License: AGPL 3 or later: + + Spine (SiSU), a framework for document structuring, publishing and + search + + Copyright (C) Ralph Amissah + + This program is free software: you can redistribute it and/or modify it + under the terms of the GNU AFERO General Public License as published by the + Free Software Foundation, either version 3 of the License, or (at your + option) any later version. + + This program is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + more details. + + You should have received a copy of the GNU General Public License along with + this program. If not, see [https://www.gnu.org/licenses/]. + + If you have Internet connection, the latest version of the AGPL should be + available at these locations: + [https://www.fsf.org/licensing/licenses/agpl.html] + [https://www.gnu.org/licenses/agpl.html] + + - Spine (by Doc Reform, related to SiSU) uses standard: + - docReform markup syntax + - standard SiSU markup syntax with modified headers and minor modifications + - docReform object numbering + - standard SiSU object citation numbering & system + + - Homepages: + [https://www.sisudoc.org] + [https://www.doc-reform.org] + + - Git + [https://git.sisudoc.org/] + ++/ +#+END_SRC + +** incorporate +*** copyright + +#+NAME: sisudoc_spine_copyright +#+BEGIN_SRC org +- Description: documents, structuring, processing, publishing, search + - static content generator + +- Author: Ralph Amissah + [ralph.amissah@gmail.com] + +- Copyright: (C) 2015 - 2026 Ralph Amissah +#+END_SRC + +*** license +**** AGPLv3 + +#+NAME: sisudoc_spine_license_agpl3 +#+BEGIN_SRC org +- code under src/* src/sisudoc/* + - License: AGPL 3 or later: + + Spine, Doc Reform (SiSU), a framework for document structuring, publishing and + search + + Copyright (C) Ralph Amissah + + This program is free software: you can redistribute it and/or modify it + under the terms of the GNU AFERO General Public License as published by + the Free Software Foundation, either version 3 of the License, or (at your + option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + for more details. + + You should have received a copy of the GNU General Public License along + with this program. If not, see [https://www.gnu.org/licenses/]. + + If you have Internet connection, the latest version of the AGPL should be + available at these locations: + [https://www.fsf.org/licensing/licenses/agpl.html] + [https://www.gnu.org/licenses/agpl.html] +#+END_SRC + +*** spine_summary + +#+NAME: sisudoc_spine_summary +#+BEGIN_SRC org +- Spine, Doc Reform (related to SiSU) uses standard: + - docReform markup syntax (based on SiSU markup) + - standard SiSU markup syntax with modified headers and minor + modifications + - docReform object numbering (based on SiSU object citation numbering) + - standard SiSU document object numbering + +- Homepages: + [https://www.sisudoc.org] +#+END_SRC + +#+BEGIN_SRC org + - Homepages: + [https://www.sisudoc.org] + [https://www.sisudoc.org] + + - Git + [] +#+END_SRC + +*** markup_samples + +#+NAME: sisudoc_spine_markup_samples +#+BEGIN_SRC org +- Spine, Doc Reform (SiSU) markup samples + Individual document content Copyright (Author) [as stated in document header] + Individual document content License (Author) [as stated in document header] +#+END_SRC + +* spine version info SET VERSION +** version in full + +#+NAME: spine_project_version +#+BEGIN_SRC org +<<spine_project_version_part_major>>.<<spine_project_version_part_minor>>.<<spine_project_version_part_patch>> +#+END_SRC + +** version parts (major, minor, patch) + +#+NAME: spine_project_version_major_minor_patch +#+BEGIN_SRC org +<<spine_project_version_part_major>>, <<spine_project_version_part_minor>>, <<spine_project_version_part_patch>> +#+END_SRC + +*** major + +#+NAME: spine_project_version_part_major +#+BEGIN_SRC org +0 +#+END_SRC + +*** minor + +#+NAME: spine_project_version_part_minor +#+BEGIN_SRC org +25 +#+END_SRC + +*** patch + +#+NAME: spine_project_version_part_patch +#+BEGIN_SRC org +2 +#+END_SRC + +* year + +#+NAME: year +#+BEGIN_SRC org +2026 +#+END_SRC + +* sisudoc spine git source SET +** sisudoc-spine src + +#+NAME: sisudoc_spine_nix_src +#+BEGIN_SRC org +git://git.sisudoc.org/software/sisudoc-spine +#+END_SRC + +** dlang overlay src + +#+NAME: sisudoc_dlang_nix_overlay_src +#+BEGIN_SRC org +git://git.sisudoc.org/package/dlang-nix-overlays-and-flake +#+END_SRC + +* ocda ssp version format SET +** ocda ssp version in full + +#+NAME: ocda_ssp_format_version +#+BEGIN_SRC org +<<ocda_ssp_format_version_part_major>>.<<ocda_ssp_format_version_part_minor>> +#+END_SRC + +** parts +*** major + +#+NAME: ocda_ssp_format_version_part_major +#+BEGIN_SRC org +2 +#+END_SRC + +*** minor + +#+NAME: ocda_ssp_format_version_part_minor +#+BEGIN_SRC org +1 +#+END_SRC + +* sqlite collection search db schema version + +#+NAME: sqlite_collection_search_db_schema_version +#+BEGIN_SRC org +1 +#+END_SRC + +* nipkgs source + +- github:NixOS/nixpkgs/nixpkgs-unstable +- https://channels.nixos.org/nixpkgs-unstable/nixexprs.tar.zst + +#+NAME: nixpkgs_unstable +#+BEGIN_SRC org +https://channels.nixos.org/nixpkgs-unstable/nixexprs.tar.zst +#+END_SRC + +#+BEGIN_SRC org +github:NixOS/nixpkgs/nixpkgs-unstable +#+END_SRC diff --git a/ssp-format-specification.md b/ssp-format-specification.md index a401947..6ac0030 100644 --- a/ssp-format-specification.md +++ b/ssp-format-specification.md @@ -77,6 +77,12 @@ row, so that one bump moves both. away**. - A reader **checks the major part and refuses what it does not know**, rather than loading an unfamiliar artefact half populated in silence. +- A **patch** part, the third, numbers *releases* and not the format: a + correction or clarification of this text, or a fix in a program that + implements it, changes nothing a file can contain. So a file declares + `major.minor` only, and a release is `major.minor.patch`. The + specification and the programs that implement it share `major.minor`, + which is the format, and each numbers its own patches. ### 2.2 History @@ -87,6 +93,17 @@ row, so that one bump moves both. | 1.1 | 2026-09-10 | The `@source` block; the document metadata the output writers read, carried in full (14 `@meta` and 3 `@make` properties added); `.segment_lv4_is`. | | 0.1 | | The first form. | +### 2.3 Releases of this specification + +| release | format | what | +|---------|--------|---------------------------------------------------------------------| +| 2.0.0 | 2.0 | the model and the `.ssp` | +| 2.0.1 | 2.0 | the object kinds and types, the levels, the make block, the markers | +| 2.0.2 | 2.0 | the `.ocda.db`; two rules a validator found unstated | +| 2.0.3 | 2.0 | the derived values: the identifier and the anchor | +| 2.1.0 | 2.1 | `.ocn_range`, and the editor's notes | +| 2.1.1 | 2.1 | the patch part of a release number, and this table | + ## 3. Lexical structure Six line types, distinguished by their first character. Nothing else is a |
