summaryrefslogtreecommitdiffhomepage
path: root/ocda-db-format-specification.md
diff options
context:
space:
mode:
Diffstat (limited to 'ocda-db-format-specification.md')
-rw-r--r--ocda-db-format-specification.md94
1 files changed, 48 insertions, 46 deletions
diff --git a/ocda-db-format-specification.md b/ocda-db-format-specification.md
index f99868e..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
@@ -181,37 +181,39 @@ declaration line, or a database key.
Where the names differ they differ for a reason, the `.ssp` preferring the
short form and the database the explicit one:
-| `.ssp` property | database |
-|-----------------|----------|
-| `.parent` | `parent_ocn` |
+| `.ssp` property | database |
+|--------------------|-----------------------|
+| `.parent` | `parent_ocn` |
| `.last_descendant` | `last_descendant_ocn` |
-| `.dummy` | `dummy_heading` |
-| `.ocn_off` | `object_number_off` |
-| `.part` | `is_of_part` |
-| `.section` | `is_of_section` |
+| `.dummy` | `dummy_heading` |
+| `.ocn_off` | `object_number_off` |
+| `.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:
-| `.ssp` property | database |
-|-----------------|----------|
-| `.image` | `object_images` |
-| `.stow_link` | `object_links` |
-| `.anchor_tag` | `object_anchors` |
-| `.lev4_subtoc` | `object_subtoc` |
+| `.ssp` property | database |
+|-----------------|------------------|
+| `.image` | `object_images` |
+| `.stow_link` | `object_links` |
+| `.anchor_tag` | `object_anchors` |
+| `.lev4_subtoc` | `object_subtoc` |
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
@@ -244,13 +246,13 @@ there.
## 5. The `files` table: what it carries, and how
-| role | named by | `compression` | `data` holds |
-|------|----------|---------------|--------------|
-| `image` | its bare filename | `none` | the file as read |
-| `source` | `media/text/<lang>/<file>` | `zstd` | a zstd frame |
-| `conf` | `conf/document_make` | `zstd` | a zstd frame |
-| `manifest` | `pod.manifest` | `zstd` | a zstd frame |
-| `tools` | `tools/po4a/...` | `zstd` | a zstd frame |
+| role | named by | `compression` | `data` holds |
+|------------|----------------------------|---------------|------------------|
+| `image` | its bare filename | `none` | the file as read |
+| `source` | `media/text/<lang>/<file>` | `zstd` | a zstd frame |
+| `conf` | `conf/document_make` | `zstd` | a zstd frame |
+| `manifest` | `pod.manifest` | `zstd` | a zstd frame |
+| `tools` | `tools/po4a/...` | `zstd` | a zstd frame |
The `compression` column carries the literal `none` or `zstd`, so a reader
need not infer it from the role.
@@ -289,11 +291,11 @@ SELECT role, count(*), sum(bytes) FROM files GROUP BY role;
### 6.2 The views
-| view | gives |
-|------|-------|
-| `outline` | the headings: lang, section, seq, ocn, both levels, `last_descendant_ocn`, identifier, text |
-| `citable` | every object with an ocn, ordered by ocn, language named |
-| `document_files` | what the file carries: role, name, bytes, sha256, pixel size |
+| view | gives |
+|------------------|---------------------------------------------------------------------------------------------|
+| `outline` | the headings: lang, section, seq, ocn, both levels, `last_descendant_ocn`, identifier, text |
+| `citable` | every object with an ocn, ordered by ocn, language named |
+| `document_files` | what the file carries: role, name, bytes, sha256, pixel size |
**`outline` and `citable` name the language and order by it first.** A view
over a file that may hold ten languages and does not say which would read as