diff options
| -rw-r--r-- | ocda-model.md | 97 | ||||
| -rw-r--r-- | org/ocda_specification.org | 228 | ||||
| -rw-r--r-- | ssp-format-specification.md | 129 |
3 files changed, 377 insertions, 77 deletions
diff --git a/ocda-model.md b/ocda-model.md index b3e82cc..1c916ca 100644 --- a/ocda-model.md +++ b/ocda-model.md @@ -14,7 +14,7 @@ between them**, because neither may express what the other cannot: This document is what they share. It describes objects; they describe writing objects down. -## 1. Three words, three levels +## 1. Three words, and what each names The terms are used precisely in this repository and in spine, and the distinction is worth holding: @@ -39,14 +39,52 @@ the document is made of and the unit it is cited by. Every object carries: - an **object citation number** (OCN), section 3; -- a **kind**, one of sixteen: `para`, `heading`, `toc`, `bookindex`, - `endnote`, `code`, `bibliography`, `comment`, `verse`, `glossary`, - `quote`, `poem`, `block`, `table`, `blurb`, `group`; +- 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; + children and its last descendant, section 4; - 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,158 | +| `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, holding verses | 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. @@ -70,7 +108,35 @@ otherwise: its verses share one; `through_the_looking_glass` has 21 such cases. Key on position within a section when one row is wanted. -## 4. Structure +## 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 @@ -82,15 +148,20 @@ be flat and the model be walked in either direction. 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, the OCN at each level above this object, - so the path to the root is available without walking. -- **`ancestors_collapsed`** - the same with the empty levels removed. +- **`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. -## 5. Sections +## 6. Sections Objects are grouped into nine sections, in this order: @@ -102,7 +173,7 @@ head toc body endnotes glossary bibliography bookindex blurb tail rest are generated or gathered. `tail` is the end of document some output writers use. A section with no objects is not carried. -## 6. Segments +## 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 @@ -117,7 +188,7 @@ both separately because the answers differ: Without the second, a reader cannot say where a paragraph belongs. The search database reads the second. -## 7. Digests +## 8. Digests The model is checkable at four levels, and the chain is what lets an artefact be verified rather than trusted: @@ -132,7 +203,7 @@ 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. -## 8. What the model does not hold +## 9. 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 diff --git a/org/ocda_specification.org b/org/ocda_specification.org index 120fa88..bcb4b0b 100644 --- a/org/ocda_specification.org +++ b/org/ocda_specification.org @@ -194,7 +194,7 @@ between them**, because neither may express what the other cannot: This document is what they share. It describes objects; they describe writing objects down. -## 1. Three words, three levels +## 1. Three words, and what each names The terms are used precisely in this repository and in spine, and the distinction is worth holding: @@ -219,14 +219,52 @@ the document is made of and the unit it is cited by. Every object carries: - an **object citation number** (OCN), section 3; -- a **kind**, one of sixteen: `para`, `heading`, `toc`, `bookindex`, - `endnote`, `code`, `bibliography`, `comment`, `verse`, `glossary`, - `quote`, `poem`, `block`, `table`, `blurb`, `group`; +- 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; + children and its last descendant, section 4; - 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,158 | +| `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, holding verses | 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. @@ -250,27 +288,60 @@ otherwise: its verses share one; `through_the_looking_glass` has 21 such cases. Key on position within a section when one row is wanted. -## 4. Structure +## 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 + **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, the OCN at each level above this object, - so the path to the root is available without walking. -- **`ancestors_collapsed`** - the same with the empty levels removed. +- **`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. -## 5. Sections +## 6. Sections Objects are grouped into nine sections, in this order: @@ -282,7 +353,7 @@ head toc body endnotes glossary bibliography bookindex blurb tail rest are generated or gathered. `tail` is the end of document some output writers use. A section with no objects is not carried. -## 6. Segments +## 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 @@ -297,7 +368,7 @@ both separately because the answers differ: Without the second, a reader cannot say where a paragraph belongs. The search database reads the second. -## 7. Digests +## 8. Digests The model is checkable at four levels, and the chain is what lets an artefact be verified rather than trusted: @@ -312,7 +383,7 @@ 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. -## 8. What the model does not hold +## 9. 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 @@ -462,16 +533,60 @@ 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: -| marker | means | -|-----------------|---------------------------| -| `【` `】` | an inline note | -| `┥` `┝` `┤` `├` | link text and link target | -| `░` | non-breaking space | -| `┘` | line break | -| `☼` | image | - -A reader that renders text must decode these; a reader that only searches -or counts need not. They are stable and are part of the format. +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 | 2,159 | | +| `¤` | 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. + +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 @@ -552,15 +667,33 @@ by `;`, levels within a topic by `:`, and alternatives at a level by `|`. ### 5.3 `@make` - how the document is to be built -| key | meaning | -|-------------------------|-----------------------------------------------------| -| `doc_type` | `article`, `book`, ... | -| `auto_num_top_at_level` | the level automatic numbering starts at | -| `auto_num_top_lv` | | -| `auto_num_depth` | how many levels are numbered | -| `breaks` | page break instructions | -| `footer` | footer text, slots joined with `\|` | -| `home_button_text` | markup for the home link, carrying internal markers | +| 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 @@ -676,8 +809,8 @@ set, as a guide to which parts of the format are load bearing. | 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 4 -and 6), the third because it is a property of this table rather than of the +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, @@ -717,10 +850,20 @@ links notes_reg notes_star images images_no_dim ## 7. Grammar -A PEG sketch. It is deliberately loose about property *names*, which the -table in section 6.3 fixes, and about the order, which section 6.3 fixes: -a grammar that enumerated 42 alternatives in sequence would be unreadable -and would need editing for every minor version. +,**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 @@ -748,6 +891,13 @@ 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" diff --git a/ssp-format-specification.md b/ssp-format-specification.md index 1fb5c3c..1f54aab 100644 --- a/ssp-format-specification.md +++ b/ssp-format-specification.md @@ -133,16 +133,60 @@ 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: -| marker | means | -|-----------------|---------------------------| -| `【` `】` | an inline note | -| `┥` `┝` `┤` `├` | link text and link target | -| `░` | non-breaking space | -| `┘` | line break | -| `☼` | image | - -A reader that renders text must decode these; a reader that only searches -or counts need not. They are stable and are part of the format. +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 | 2,159 | | +| `¤` | 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. + +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 @@ -223,15 +267,33 @@ by `;`, levels within a topic by `:`, and alternatives at a level by `|`. ### 5.3 `@make` - how the document is to be built -| key | meaning | -|-------------------------|-----------------------------------------------------| -| `doc_type` | `article`, `book`, ... | -| `auto_num_top_at_level` | the level automatic numbering starts at | -| `auto_num_top_lv` | | -| `auto_num_depth` | how many levels are numbered | -| `breaks` | page break instructions | -| `footer` | footer text, slots joined with `\|` | -| `home_button_text` | markup for the home link, carrying internal markers | +| 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 @@ -347,8 +409,8 @@ set, as a guide to which parts of the format are load bearing. | 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 4 -and 6), the third because it is a property of this table rather than of the +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, @@ -388,10 +450,20 @@ links notes_reg notes_star images images_no_dim ## 7. Grammar -A PEG sketch. It is deliberately loose about property *names*, which the -table in section 6.3 fixes, and about the order, which section 6.3 fixes: -a grammar that enumerated 42 alternatives in sequence would be unreadable -and would need editing for every minor version. +**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 @@ -419,6 +491,13 @@ 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" |
