diff options
Diffstat (limited to 'ssp-format-specification.md')
| -rw-r--r-- | ssp-format-specification.md | 113 |
1 files changed, 65 insertions, 48 deletions
diff --git a/ssp-format-specification.md b/ssp-format-specification.md index ae1ecaf..a401947 100644 --- a/ssp-format-specification.md +++ b/ssp-format-specification.md @@ -1,7 +1,7 @@ # The `.ssp` format **The object-centric document abstraction, written as text. Format version -2.0**, as spine 0.25.0 emits and reads it. +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 @@ -63,7 +63,7 @@ by reading a `.ssp` back, so it can hold nothing this format cannot express. The version is declared **in band**, on the first line of every file: ``` -% SiSU Document Abstraction v2.0 +% SiSU Document Abstraction v2.1 ``` and by the sibling sqlite serialisation in its `schema.version` metadata @@ -80,11 +80,12 @@ row, so that one bump moves both. ### 2.2 History -| version | date | what moved | -|---------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 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. | +| 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. | ## 3. Lexical structure @@ -146,7 +147,7 @@ it may not. | `⑆` | a page number of the source edition follows | 19,099 | | | `┨` `┣` | that page number, open and close | 19,099 | | | `■` | monospace | 10,688 | | -| `【` `】` | an inline note | 2,159 | | +| `【` `】` | 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 | | @@ -163,6 +164,21 @@ it may 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. @@ -193,7 +209,7 @@ are part of the format. In order, and this order is fixed: ``` -% SiSU Document Abstraction v2.0 +% SiSU Document Abstraction v2.1 % Source: <markup filename> @source { ... } @@ -385,47 +401,48 @@ 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`, ...) | 56,882 | +| 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,631 | +| 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 | `.children` | ints | the heading has child headings | 827 | -| 7 | `.ancestors` | 8 ints | any is non-zero | 53,595 | -| 8 | `.ancestors_collapsed` | 8 ints | any is non-zero | 53,595 | -| 9 | `.dom_status` | 8 ints | any is non-zero | 3,319 | -| 10 | `.dom_status_collapsed` | 8 ints | any is non-zero | 3,319 | -| 11 | `.heading_lev_collapsed` | int | it is below 9 | 3,503 | -| 12 | `.parent_lev` | int | non-zero | 52,848 | -| 13 | `.dummy` | `true` | the heading was introduced to segment an output | 183 | -| 14 | `.ocn_off` | `true` | the object has no citation number | 7,543 | -| 15 | `.is_of_type` | string | always, in practice | 56,882 | -| 16 | `.attrib` | string | set | 1 | -| 17 | `.meta_lang` | string | the object carries its own language | 0 | -| 18 | `.meta_syntax` | string | the object carries its own markup syntax | 0 | -| 19 | `.sha256` | hex | the object's text digest is non-zero | 51,253 | -| 20 | `.image` | record | once **per image**, in order of appearance | 63 | -| 21 | `.indent` | 2 ints | either indent is non-zero: `base hang` | 7,583 | -| 22 | `.bullet` | `true` | the object is a bullet item | 1,903 | -| 23 | `.lang` | string | the text attributes carry a language | 0 | -| 24 | `.has` | flags | any is set | 11,143 | -| 25 | `.table_cols` | int | the object is a table with columns | 32 | -| 26 | `.table_widths` | ints | the table has column widths | 32 | -| 27 | `.table_aligns` | letters | the table has alignments (`l` `c` `r`) | 32 | -| 28 | `.table_header` | `true` | the table has a header row | 29 | -| 29 | `.code_linenumbers` | `true` | the code block is numbered | 1 | -| 30 | `.stow_link` | url | once **per extracted link** | 1,013 | -| 31 | `.segment` | string | the heading opens a segment | 3,355 | -| 32 | `.anchor` | string | the anchor differs from the segment name (**otherwise it is the segment name**: model section 9) | 68 | -| 33 | `.segment_prev` | string | there is a previous segment | 1,022 | -| 34 | `.segment_next` | string | there is a next segment | 1,022 | -| 35 | `.heading_lev_anchor` | string | the heading has a level anchor tag | 1,854 | -| 36 | `.segment_epub` | string | the heading opens an epub segment | 3,355 | -| 37 | `.segment_html_is` | string | the object is inside an html segment | 47,024 | -| 38 | `.segment_epub_is` | string | the object is inside an epub segment | 47,024 | -| 39 | `.segment_lv4_is` | string | **and** it differs from `.segment_html_is` | 342 | -| 40 | `.heading_ancestors_text` | 8 slots, `\|` joined, escaped | any slot is non-empty | 3,319 | -| 41 | `.lev4_subtoc` | string | once **per sub-table-of-contents entry** | 1,887 | -| 42 | `.anchor_tag` | string | once **per anchor tag** | 7,883 | +| 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 |
