diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-09-29 14:02:30 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-12 21:48:46 -0400 |
| commit | 7532a04beb6f51665011cf3117d2b29c651a3442 (patch) | |
| tree | 0c7a9fb53724ed3648399c5994156a71df915a9a /ocda-db-format-specification.md | |
| parent | derived values that the model left unstated (diff) | |
format 2.1: on poems and editor's notesHEADmainclaude-check-main
- editor's notes:
Updated here, spine now apart from author's notes recognises existing
markup's editor's notes, ~[* ]~ and ~[+ ]~, and writes them as notes
of their own numbered series: *1, *2 ... and +1, +2 ... document.
- a poem is a container of its verse:
.ocn_range, the first and last ocn of what a container holds, as one
.ssp property and two .ocda.db columns. A poem is the one container:
its verses are the citable units rather than the poem. A poem now
comes before its first verse, carries ocn 0 and no identifier, and
states the range, where it came after its last verse carrying that
verse's ocn and identifier.
So the model can now say that a non-zero ocn is unique within a
document, and does, keeping the older rule for artefacts written
before 2.1. A minor bump: an addition, a poem was never rendered and
has no text, the verses are unchanged, and a 2.0 reader reads a 2.1
file.
The property-count table is recounted over the regenerated reference
set, the method first checked against the old set, which it reproduces.
The one new endnote, a note in a poem's last verse now gathered,
accounts for the other moved counts; the poems' segment names account
for .segment_html_is and .segment_epub_is.
(assisted by Claude-Code)
Diffstat (limited to 'ocda-db-format-specification.md')
| -rw-r--r-- | ocda-db-format-specification.md | 44 |
1 files changed, 23 insertions, 21 deletions
diff --git a/ocda-db-format-specification.md b/ocda-db-format-specification.md index eacc618..fe4ad3a 100644 --- a/ocda-db-format-specification.md +++ b/ocda-db-format-specification.md @@ -1,7 +1,7 @@ # The `.ocda.db` format **The object-centric document abstraction, written as sqlite. Format -version 2.0**, as spine 0.25.0 emits and reads it. +version 2.1**, as spine emits and reads it after 0.25.1. This document specifies *one serialisation*. The model it serialises is specified in [`ocda-model.md`](ocda-model.md), which the text serialisation @@ -49,7 +49,7 @@ Declared in band, in the `metadata` table: SELECT key, value FROM metadata WHERE doc_id IS NULL; -- build.spine_version | 0.25.0 -- schema.name | sisu-abstraction-db --- schema.version | 2.0 +-- schema.version | 2.1 ``` The rule is the model's, and identical to the `.ssp`: the minor part is @@ -107,12 +107,12 @@ The `.ssp` has four preamble blocks, `@source`, `@meta`, `@make` and `@doc_has`. The database has **one** `metadata` table, and tells them apart by a **prefix on the key**: -| `.ssp` block | database key | -|--------------|--------------| -| `@meta` | the key as it stands: `title.main`, `creator.author`, ... | -| `@make` | `make.` + the key: `make.footer`, `make.doc_type` | -| `@doc_has` | `doc_has.` + the key: `doc_has.images`, `doc_has.tables` | -| `@source` | `source.` + the key: `source.language`, `source.digest` | +| `.ssp` block | database key | +|--------------|-----------------------------------------------------------| +| `@meta` | the key as it stands: `title.main`, `creator.author`, ... | +| `@make` | `make.` + the key: `make.footer`, `make.doc_type` | +| `@doc_has` | `doc_has.` + the key: `doc_has.images`, `doc_has.tables` | +| `@source` | `source.` + the key: `source.language`, `source.digest` | **A reader must strip the prefix and restore the grouping**, or a writer over it has to ask `metadata["make.footer"]` from a database and @@ -150,12 +150,12 @@ reader of the text form necessarily does. The **element types**, so that a decoder can be written to accept exactly what occurs: -| column | elements | -|--------|----------| -| `children`, `ancestors`, `ancestors_collapsed`, `dom_status`, `dom_status_collapsed` | integers | -| `table_widths` | integers, or floats where the columns divide evenly | -| `table_aligns` | strings, one of `l` `c` `r` | -| `heading_ancestors_text` | strings, eight of them, empty where that level is not an ancestor | +| column | elements | +|--------------------------------------------------------------------------------------|-------------------------------------------------------------------| +| `children`, `ancestors`, `ancestors_collapsed`, `dom_status`, `dom_status_collapsed` | integers | +| `table_widths` | integers, or floats where the columns divide evenly | +| `table_aligns` | strings, one of `l` `c` `r` | +| `heading_ancestors_text` | strings, eight of them, empty where that level is not an ancestor | The `.ssp` writes the first three groups **space separated** and `heading_ancestors_text` **`|` separated**. The empty slots of the last are @@ -190,12 +190,13 @@ short form and the database the explicit one: | `.part` | `is_of_part` | | `.section` | `is_of_section` | -Two are **expanded**, the `.ssp` folding what the database spreads: +Three are **expanded**, the `.ssp` folding what the database spreads: -| `.ssp` property | database | -|---------------------------------------------------------|-----------------------------------------------------------------------------------| -| `.indent: <base> <hang>` | `indent_base`, `indent_hang` | -| `.has: links notes_reg notes_star images images_no_dim` | `has_links`, `has_notes_reg`, `has_notes_star`, `has_images`, `has_images_no_dim` | +| `.ssp` property | database | +|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `.indent: <base> <hang>` | `indent_base`, `indent_hang` | +| `.ocn_range: <first> <last>` | `ocn_range_first`, `ocn_range_last` (2.1: `0` where the object is not a container; a 2.0 database has neither column, and reads as no range) | +| `.has: links notes_reg notes_star images images_no_dim` | `has_links`, `has_notes_reg`, `has_notes_star`, `has_images`, `has_images_no_dim` | The four **repeatable** properties become the four child tables: @@ -210,8 +211,9 @@ And four columns come from outside the property list: `ocn`, `is_a` and `heading_level` from the object declaration line, and `text` from its `|` lines. `id`, `doc_id` and `seq` are the database's own keys; `seq` is the object's position within its section, and `(doc_id, section, seq)` is what -identifies an object when `ocn` will not (see -[`ocda-model.md`](ocda-model.md) section 3). +identifies an object when `ocn` will not: `0`, or, before 2.1, a poem +sharing its last verse's number (see [`ocda-model.md`](ocda-model.md) +section 3). ### 4.1 Where the two are not symmetric |
