diff options
Diffstat (limited to 'ocda-model.org')
| -rw-r--r-- | ocda-model.org | 158 |
1 files changed, 80 insertions, 78 deletions
diff --git a/ocda-model.org b/ocda-model.org index 17e8132..ad869fc 100644 --- a/ocda-model.org +++ b/ocda-model.org @@ -11,8 +11,8 @@ 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: -| [[file:ssp-format-specification.org][=ssp-format-specification.org=]] | the OCDA as text, =.ssp= | -| [[file:ocda-db-format-specification.org][=ocda-db-format-specification.org=]] | the OCDA as sqlite, =.ocda.db= | +- [[file:ssp-format-specification.org][~ssp-format-specification.org~]] :: the OCDA as text, ~.ssp~ +- [[file:ocda-db-format-specification.org][~ocda-db-format-specification.org~]] :: the OCDA as sqlite, ~.ocda.db~ This document is what they share. It describes objects; they describe writing objects down. @@ -24,11 +24,13 @@ 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 | +- 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 @@ -61,39 +63,39 @@ Every object carries: :END: 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* (~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 | +| 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 ([[#sec-5][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 +| ~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 ([[#sec-5][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= | +| ~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 +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 does not need to know all sixteen kinds* to decide whether it may reflow the text, which is what the second axis is for. @@ -114,15 +116,15 @@ Three properties follow, and each is a trap for a reader that assumes otherwise: - *Not every object has one.* Generated furniture, and objects the markup - has suppressed, carry =0=. There are many of them: 7,543 across the 36 + has suppressed, carry ~0~. There are many of them: 7,543 across the 36 document reference collection. -- *=0= is therefore not an identity.* Objects sharing =0= are not the - same object, and =0= must never be used as a key. +- *~0~ is therefore not an identity.* Objects sharing ~0~ are not the + same object, and ~0~ must never be used as a key. - *A non-zero OCN is unique within a document*, from format 2.1: checked over the reference collection, no non-zero OCN occurs twice in any of the 36 document-languages. *Before 2.1 it was not*: a poem carried the OCN of its last verse, so the same number named two objects (48 such pairs in the - collection, 21 in =through_the_looking_glass=). A reader of an older + collection, 21 in ~through_the_looking_glass~). A reader of an older artefact keys on position within a section when one row is wanted. ** 3.1 The identifier @@ -130,15 +132,15 @@ otherwise: :CUSTOM_ID: sec-3-1 :END: Every object also carries an *identifier*: the name by which an output -refers to it. An HTML anchor, a LaTeX =\hypertarget=, a link from a book +refers to it. An HTML anchor, a LaTeX ~\hypertarget~, a link from a book index entry to the object it indexes, are all written from the identifier. *The identifier of an object with a non-zero OCN is its OCN*, written as text. That is the ordinary case and it is the reason a citation to object 42 can be turned into a link without consulting anything. -An object with OCN =0= has no OCN to take an identifier from, so one is -assigned: =a1=, =a2=, =a3=, ... in document order over the objects that +An object with OCN ~0~ has no OCN to take an identifier from, so one is +assigned: ~a1~, ~a2~, ~a3~, ... in document order over the objects that need one. There are few of them, eleven in a book, and they are the generated furniture of [[#sec-3][section 3]]. @@ -153,22 +155,22 @@ 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 | | - -=A= to =D= are the title levels, =1= to =4= the body levels, and the index +| ~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 [[#sec-5][section 5]] are indexed by. A heading that claims no level has 9, which is the "not a heading level" value and is why -=.heading_lev_collapsed= is emitted only when it is below 9. +~.heading_lev_collapsed~ is emitted only when it is below 9. -*Collapsed levels.* A document that uses =A= and then =1=, skipping =B=, -=C= and =D=, has a gap in its levels that is an artefact of the markup +*Collapsed levels.* A document that uses ~A~ and then ~1~, skipping ~B~, +~C~ and ~D~, has a gap in its levels that is an artefact of the markup rather than of the document. Every level-indexed array therefore comes in two forms: as marked up, and *collapsed*, with the unused levels removed so that the remaining ones are contiguous. Outputs that care about nesting @@ -183,31 +185,31 @@ Structure is carried by number, not by nesting: an object names its parent rather than containing its children. This is what lets the serialisations be flat and the model be walked in either direction. -- *=parent=* - the OCN of the object this one hangs from. - *A parent of =0= is not "no parent"*: it is a parent heading the author +- *~parent~* - the OCN of the object this one hangs from. + *A parent of ~0~ is not "no parent"*: it is a parent heading the author has made non-substantive, its OCN suppressed or a dummy heading introduced to segment an output. The distinction is preserved - deliberately, and a reader walking upward must stop at =0= rather than + deliberately, and a reader walking upward must stop at ~0~ rather than treat it as missing, or the walk will not terminate. -- *=ancestors=* - *eight slots, indexed by level* ([[#sec-4][section 4]]): the OCN - of the heading at each level above this object, =0= where there is none, +- *~ancestors~* - *eight slots, indexed by level* ([[#sec-4][section 4]]): the OCN + of the heading at each level above this object, ~0~ where there is none, so the path to the root is available without walking it. *A heading's own OCN sits in its own level's slot*: checked over the reference collection, 3,432 headings of 3,432. So for a heading the array is its path including itself, and for any other object it is the path to the heading above it. -- *=ancestors_collapsed=* - the same, in collapsed levels. -- *=children=* - a heading's child headings. -- *=last_descendant=* - the last OCN under a heading, which makes a +- *~ancestors_collapsed~* - the same, in collapsed levels. +- *~children~* - a heading's child headings. +- *~last_descendant~* - the last OCN under a heading, which makes a subtree a *range* rather than a traversal: everything from the heading's OCN to its last descendant is inside it. -- *=ocn_range=* - for a *container*, the first and last OCN of what it +- *~ocn_range~* - for a *container*, the first and last OCN of what it holds (2.1). A poem is the one container: its verses are the citable - units, one object each, and the poem is not; it carries OCN =0= and no + units, one object each, and the poem is not; it carries OCN ~0~ and no identifier, *comes immediately before its first verse*, and is cited as - the range of them (=173-180=). So a writer that meets a poem knows what + the range of them (~173-180~). So a writer that meets a poem knows what follows and where it ends, and can wrap the verses in one pass. The poem - has no text of its own. =0 0=, or absent, where the object is not a + has no text of its own. ~0 0~, or absent, where the object is not a container. *Before 2.1* the poem came /after/ its last verse, carried that verse's OCN and identifier, and stated no range. @@ -222,8 +224,8 @@ Objects are grouped into nine sections, in this order: head toc body endnotes glossary bibliography bookindex blurb tail #+end_example -=head= is the document's title matter, =body= the document proper, and the -rest are generated or gathered. =tail= is the end of document some output +~head~ is the document's title matter, ~body~ the document proper, and the +rest are generated or gathered. ~tail~ is the end of document some output writers use. A section with no objects is not carried. * 7. Segments @@ -285,10 +287,10 @@ Two of the values above are *derived*: the identifier from the OCN ([[#sec-3-1][section 3.1]]), and the anchor from the segment name ([[#sec-7-1][section 7.1]]). The model holds them; a serialisation need not, and the text form does not. -*A serialisation may omit a value it can compute.* The =.ssp= writes a -property only when it carries information, so it omits =.identifier= where -the identifier is the OCN and =.anchor= where the anchor is the segment -name. The =.ocda.db= is columns rather than lines and writes both +*A serialisation may omit a value it can compute.* The ~.ssp~ writes a +property only when it carries information, so it omits ~.identifier~ where +the identifier is the OCN and ~.anchor~ where the anchor is the segment +name. The ~.ocda.db~ is columns rather than lines and writes both unconditionally. Both are conforming. What is *not* conforming is a reader that takes the @@ -297,8 +299,8 @@ that model is not the same model the database gives, and a writer over it will produce different output from the two serialisations of one document. The size of the difference is easy to underestimate. In -=free_culture.lawrence_lessig= the =.ssp= omits *1,314 identifiers and 69 -anchors* that the =.ocda.db= states, which is nearly every object in the +~free_culture.lawrence_lessig~ the ~.ssp~ omits *1,314 identifiers and 69 +anchors* that the ~.ocda.db~ states, which is nearly every object in the document. So, on loading: @@ -306,18 +308,18 @@ 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 | +| 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 here /because/ two readers written independently from these documents -disagreed for want of it: the rule was implied by the =.ssp='s emission +disagreed for want of it: the rule was implied by the ~.ssp~'s emission conditions and nowhere asserted. It is also what *spine's own reader* does, and always did, which is why -the =.ocda.db= carries the derived values: the database is written from the -=.ssp= read straight back, and the reading fills both in. So this section +the ~.ocda.db~ carries the derived values: the database is written from the +~.ssp~ read straight back, and the reading fills both in. So this section documents existing behaviour rather than prescribing new. It should have been written down first. @@ -326,7 +328,7 @@ been written down first. :CUSTOM_ID: sec-10 :END: - *The markup.* The model is what the markup produced, not the markup - itself. An artefact that carries both is the =.ocda.db=, which carries + itself. An artefact that carries both is the ~.ocda.db~, which carries the markup alongside the model rather than within it. - *The images.* The model /names/ them, with digest, byte size and pixel size, and they must be found beside the file for a document to be |
