summaryrefslogtreecommitdiffhomepage
path: root/ssp-format-specification.md
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-09-24 11:36:25 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-10-03 21:50:59 -0400
commit8387d81b7f39002e046ea835dd9e4b147410c1ab (patch)
treeb021e465fad8466a9845a9f3b5e1b9d4ef88ae92 /ssp-format-specification.md
parentsisudoc-abstraction-format 2.0: ocda-model & .ssp (diff)
gaps: kinds, types, levels, make block, markers
close gaps left in the first pass, measured against the document markup sample set, (which caught four wrong counts and two traps). ocda-model.md The sixteen object kinds are now defined rather than listed, each with the section it belongs to and its weight in the collection. Only heading appears in all nine sections. Kind and type are two axes rather than one, and type is the useful one for a renderer: is_of_type takes just three values, para, block and comment, saying whether the text may be reflowed. The mapping from kind to type is fixed, so a reader that has the type need not know all sixteen kinds to lay text out. A section on levels, which the first pass assumed: eight of them, A to D for the title matter and 1 to 4 for the body, index 0 to 7, and that index is what the eight-slot arrays are indexed by. A heading's own OCN sits in its own level's slot. Collapsed levels explained as what they are, an artefact of the markup removed. ssp-format-specification.md The @make keys are described rather than named. auto_num_top_at_level and auto_num_top_lv are the same value twice, as the markup wrote it and as an index. breaks is a small language of its own, new= and break= over comma separated levels, and the levels are written there as the markup wrote them. The marker table is now the full set from InlineMarkup with counts from the collection, and the counting corrected four markers the first pass had at zero. Two traps found by counting. The spaced line break and the table close are the same character, and the object kind is what resolves them: it occurs in group objects and never in a table. And the corner brackets are not markers in a .ssp at all: they wrap an object number in ODT output, which happens after the abstraction, so their occurrences here are Japanese quotation marks in the document's own text. The grammar says what it does and does not fix, and why the order of properties is left to the table rather than enumerated as 42 optional terms that would need editing at every minor version. Every line of the collection matches one of its eight line shapes. (assisted by Claude-Code)
Diffstat (limited to 'ssp-format-specification.md')
-rw-r--r--ssp-format-specification.md129
1 files changed, 104 insertions, 25 deletions
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"