diff options
Diffstat (limited to 'ocda-model.md')
| -rw-r--r-- | ocda-model.md | 92 |
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 |
