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.md97
1 files changed, 53 insertions, 44 deletions
diff --git a/ssp-format-specification.md b/ssp-format-specification.md
index 17974a3..ae1ecaf 100644
--- a/ssp-format-specification.md
+++ b/ssp-format-specification.md
@@ -338,6 +338,15 @@ 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
```
@@ -373,50 +382,50 @@ 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 | 353 |
-| 2 | `.part` | string | the object belongs to a part (`frontmatter`, `body`, ...) | 56,882 |
-| 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 |
-| 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 | 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 |
+| # | 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 |
+| 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 |
+| 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 |
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