diff options
Diffstat (limited to 'ssp-format-specification.md')
| -rw-r--r-- | ssp-format-specification.md | 212 |
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 |
