summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--ocda-model.md97
-rw-r--r--org/ocda_specification.org228
-rw-r--r--ssp-format-specification.md129
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"