summaryrefslogtreecommitdiffhomepage
path: root/ocda-model.md
diff options
context:
space:
mode:
Diffstat (limited to 'ocda-model.md')
-rw-r--r--ocda-model.md92
1 files changed, 46 insertions, 46 deletions
diff --git a/ocda-model.md b/ocda-model.md
index 84e521a..1c173b1 100644
--- a/ocda-model.md
+++ b/ocda-model.md
@@ -6,9 +6,9 @@ of any file it is written to.
Two serialisations carry this model, and they carry **one version number
between them**, because neither may express what the other cannot:
-| | |
-|---|---|
-| [`ssp-format-specification.md`](ssp-format-specification.md) | the OCDA as text, `.ssp` |
+| | |
+|----------------------------------------------------------------------|--------------------------------|
+| [`ssp-format-specification.md`](ssp-format-specification.md) | the OCDA as text, `.ssp` |
| [`ocda-db-format-specification.md`](ocda-db-format-specification.md) | the OCDA as sqlite, `.ocda.db` |
This document is what they share. It describes objects; they describe
@@ -19,11 +19,11 @@ writing objects down.
The terms are used precisely in this repository and in spine, and the
distinction is worth holding:
-| level | term | names |
-|-------|------|-------|
-| the model | **OCDA** | what a document is once parsed: numbered objects with structure, identity and digests. Independent of any file, any stage, any tool |
-| the stage | **abstraction** | the middle of spine's **markup -> abstraction -> output**: the act of building the model, and the point at which a document may now enter the pipeline |
-| the serialisations | **`.ssp`**, **`.ocda.db`** | the model written down, as text and as sqlite |
+| level | term | names |
+|--------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| the model | **OCDA** | what a document is once parsed: numbered objects with structure, identity and digests. Independent of any file, any stage, any tool |
+| the stage | **abstraction** | the middle of spine's **markup -> abstraction -> output**: the act of building the model, and the point at which a document may now enter the pipeline |
+| the serialisations | **`.ssp`**, **`.ocda.db`** | the model written down, as text and as sqlite |
A thing is named for the level it belongs to. Something true of the model
whatever file it is in takes *ocda*; something about the pipeline stage
@@ -55,33 +55,33 @@ 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,159 |
-| `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: the container of its verses, OCN `0`, cited as their range (section 5) | 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 |
+| 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,294 |
+| `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: the container of its verses, OCN `0`, cited as their range (section 5) | 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` |
+| 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
@@ -136,16 +136,16 @@ wrote it down**; see section 9.
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 | |
+| 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
@@ -276,11 +276,11 @@ document.
So, on loading:
-| field | when absent | take |
-|-------|-------------|------|
-| identifier | OCN is non-zero | the OCN as text |
-| identifier | OCN is `0` | whatever the serialisation gave; there is nothing to derive from |
-| anchor | the object has a segment | the segment name |
+| field | when absent | take |
+|------------|--------------------------|------------------------------------------------------------------|
+| identifier | OCN is non-zero | the OCN as text |
+| identifier | OCN is `0` | whatever the serialisation gave; there is nothing to derive from |
+| anchor | the object has a segment | the segment name |
**This is a property of the model, not of either format**, which is why it
is stated here and not only in the two format specifications. It is stated