summaryrefslogtreecommitdiffhomepage
path: root/ssp-format-specification.md
diff options
context:
space:
mode:
Diffstat (limited to 'ssp-format-specification.md')
-rw-r--r--ssp-format-specification.md212
1 files changed, 106 insertions, 106 deletions
diff --git a/ssp-format-specification.md b/ssp-format-specification.md
index f6351e4..5b8abc3 100644
--- a/ssp-format-specification.md
+++ b/ssp-format-specification.md
@@ -80,28 +80,28 @@ row, so that one bump moves both.
### 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. |
+| 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
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 |
+| 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
@@ -139,26 +139,26 @@ 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 | |
+| 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
@@ -247,11 +247,11 @@ 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 |
+| 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.
@@ -266,32 +266,32 @@ 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` |
+| 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 |
+| 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
@@ -398,51 +398,51 @@ 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 |
+| # | 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