summaryrefslogtreecommitdiffhomepage
path: root/ssp-format-specification.org
diff options
context:
space:
mode:
Diffstat (limited to 'ssp-format-specification.org')
-rw-r--r--ssp-format-specification.org877
1 files changed, 664 insertions, 213 deletions
diff --git a/ssp-format-specification.org b/ssp-format-specification.org
index 7258862..d0846de 100644
--- a/ssp-format-specification.org
+++ b/ssp-format-specification.org
@@ -9,7 +9,7 @@
2.1*, as spine emits and reads it after 0.25.1.
This document specifies /one serialisation/. The model it serialises is
-specified in [[file:ocda-model.org][=ocda-model.org=]], which the sqlite
+specified in [[file:ocda-model.org][~ocda-model.org~]], which the sqlite
serialisation shares; read that first if the question is what an object
/is/ rather than how it is written down.
@@ -17,14 +17,14 @@ serialisation shares; read that first if the question is what an object
:PROPERTIES:
:CUSTOM_ID: the-name
:END:
-=.ssp= belongs to the family of SiSU markup extensions, =.sst= (sisu text),
-=.ssm= (sisu master) and =.ssi= (sisu insert), and a short extension was
+~.ssp~ belongs to the family of SiSU markup extensions, ~.sst~ (sisu text),
+~.ssm~ (sisu master) and ~.ssi~ (sisu insert), and a short extension was
wanted that sat with them. It stands loosely for *sisu peg*, or *sisu
-parsable*. =.ssa=, for sisu abstraction, was thought to be taken by other
+parsable*. ~.ssa~, for sisu abstraction, was thought to be taken by other
projects.
So the extension names the /file family and its parsability/, where
-=.ocda.db= names the /model and its container/. The two are not parallel in
+~.ocda.db~ names the /model and its container/. The two are not parallel in
construction and are not meant to be.
* Status
@@ -32,21 +32,21 @@ construction and are not meant to be.
:CUSTOM_ID: status
:END:
This specification is derived from the emitter
-(=sisudoc/ocda/abstraction/ssp.d= in sisudoc-spine, whose =sspObjectRecord=
-is "the single definition of what an object looks like in a =.ssp= file"),
+(~sisudoc/ocda/abstraction/ssp.d~ in sisudoc-spine, whose ~sspObjectRecord~
+is "the single definition of what an object looks like in a ~.ssp~ file"),
and every claim in it is checked against the project's 36 document
reference set. Where the two could differ, the emitter is normative and
this document is wrong.
-* 1. What a =.ssp= is
+* 1. What a ~.ssp~ is
:PROPERTIES:
:CUSTOM_ID: sec-1
:END:
-A =.ssp= file is the serialisation, as text, of one language of one
+A ~.ssp~ file is the serialisation, as text, of one language of one
document after spine has parsed it: the object model, not the markup and
not any output format.
-Spine's pipeline is *markup -> abstraction -> output*. A =.ssp= is the
+Spine's pipeline is *markup -> abstraction -> output*. A ~.ssp~ is the
middle stage written down. Since spine 0.25.0 it is also read back, so a
document may enter the pipeline at the abstraction stage instead of being
parsed, and the output writers cannot tell which happened.
@@ -57,7 +57,7 @@ The format is:
- *order significant.* Sections appear in a fixed order, objects in
document order, and an object's properties in a fixed order ([[#sec-6-3][section 6.3]]).
- *UTF-8*, without a byte order mark.
-- *lossless for the abstraction*, not for the markup: a =.ssp= read back
+- *lossless for the abstraction*, not for the markup: a ~.ssp~ read back
and re-emitted is byte identical, which the project's test suite asserts
over the whole reference set.
@@ -67,9 +67,9 @@ The format is:
:END:
It does not carry the markup it was made from, and it does not carry its
images: it /names/ them, with their digests and pixel sizes, and they must
-be found beside it (=../image/= within a pod) for the document to be
-complete. An artefact that carries both is the =.ocda.db=, which is built
-by reading a =.ssp= back, so it can hold nothing this format cannot express.
+be found beside it (~../image/~ within a pod) for the document to be
+complete. An artefact that carries both is the ~.ocda.db~, which is built
+by reading a ~.ssp~ back, so it can hold nothing this format cannot express.
* 2. Version and compatibility
:PROPERTIES:
@@ -77,11 +77,11 @@ by reading a =.ssp= back, so it can hold nothing this format cannot express.
:END:
The version is declared *in band*, on the first line of every file:
-#+begin_example
+#+begin_src ssp
% SiSU Document Abstraction v2.1
-#+end_example
+#+end_src
-and by the sibling sqlite serialisation in its =schema.version= metadata
+and by the sibling sqlite serialisation in its ~schema.version~ metadata
row, so that one bump moves both.
** 2.1 The rule
@@ -99,12 +99,21 @@ row, so that one bump moves both.
:PROPERTIES:
:CUSTOM_ID: sec-2-2
:END:
-| version | date | what moved |
-|---------+------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 2.1 | 2026-09-29 | =.ocn_range=, the first and last ocn of what a container holds. A poem is a container of verses and is cited as their range: it now comes before its first verse, carries ocn =0= and no identifier, and states the range, where it had come after its last verse carrying that verse's ocn and identifier, so that one number named two objects. A minor bump: the property is an addition, the poem was never rendered and has no text, the verses are unchanged, and a 2.0 reader reads a 2.1 file. The same run gathers a note in a poem's last verse into the endnotes, which it had not been: one more endnote in the reference collection. And the editor's notes, =~[* ]~= and =~[+ ]~=, which spine had not recognised and passed through as text, are notes: a third form of note mark, a symbol and a number (=*1=, =+1=), each series numbered through the document; 135 more endnotes, 2,294 in all ([[#sec-3-2][section 3.2]], "A note begins with its mark"). |
-| 2.0 | 2026-09-18 | =source.digest= changes meaning: it covers every markup file the document is made of, where it had been the digest of the master file alone. A change of meaning, so the major part. |
-| 1.1 | 2026-09-10 | The =@source= block; the document metadata the output writers read, carried in full (14 =@meta= and 3 =@make= properties added); =.segment_lv4_is=. |
-| 0.1 | | The first form. |
+- 2.1 [2026-09-29 Tue] :: ~.ocn_range~, the first and last ocn of what a
+ container holds. A poem is a container of verses and is cited as their range:
+ it now comes before its first verse, carries ocn
+ ~0~ and no identifier, and states the range, where it had come after its last verse carrying that verse's ocn and identifier, so that one number named two objects. A minor bump: the property is an addition, the poem was never rendered and has no text, the verses are unchanged, and a 2.0 reader reads a 2.1 file. The same run gathers a note in a poem's last verse into the endnotes, which it had not been: one more endnote in the reference collection. And the editor's notes, =~[*
+ ]~= and =~[+
+ ]~=, which spine had not recognised and passed through as text, are notes: a third form of note mark, a symbol and a number (~*1~, ~+1~),
+ each series numbered through the document; 135 more endnotes, 2,294 in all
+ ([[#sec-3-2][section 3.2]], "A note begins with its mark").
+- 2.0 [2026-09-18 Fri] :: ~source.digest~ changes meaning: it covers every
+ markup file the document is made of, where it had been the digest of the
+ master file alone. A change of meaning, so the major part.
+- 1.1 [2026-09-10 Thu] :: The ~@source~ block; the document metadata the output
+ writers read, carried in full (14 ~@meta~ and 3 ~@make~ properties added);
+ ~.segment_lv4_is~.
+- 0.1 :: The first form.
* 3. Lexical structure
:PROPERTIES:
@@ -113,29 +122,30 @@ row, so that one bump moves both.
Six line types, distinguished by their first character. Nothing else is a
valid line.
-| line | form | meaning |
-|--------------------+-----------------+-----------------------------------------------|
-| comment | =% ...= | file header only ([[#sec-4][section 4]]) |
-| block open | =@name {= | opens a preamble block or a section |
-| block close | =}= | closes it |
-| key | =key: value=, indented two spaces | inside a preamble block |
-| object declaration | =[ocn] kind...= | opens an object record ([[#sec-6-1][section 6.1]]) |
-| property | =.name: value= | a property of the object just declared |
-| text | \vert{} then the text | a line of the object's text |
-| blank | | separates records; carries no meaning |
+| line | form | meaning |
+|--------------------+-----------------------------------+----------------------------------------|
+| comment | ~% ...~ | file header only ([[#sec-4][section 4]]) |
+| block open | ~@name {~ | opens a preamble block or a section |
+| block close | ~}~ | closes it |
+| key | ~key: value~, indented two spaces | inside a preamble block |
+| object declaration | ~[ocn] kind...~ | opens an object record ([[#sec-6-1][section 6.1]]) |
+| property | ~.name: value~ | a property of the object just declared |
+| text | \vert{} then the text | a line of the object's text |
+| blank | | separates records; carries no meaning |
A value runs to the *end of the line*. It is not quoted, and it is not
trimmed beyond the single space after the colon. A value may therefore
-contain =:=, spaces, and any UTF-8 character except a line break.
+contain ~:~, spaces, and any UTF-8 character except a line break.
** 3.1 Escaping
:PROPERTIES:
:CUSTOM_ID: sec-3-1
:END:
Only one value is escaped, because only one value is a *joined list*:
-=.heading_ancestors_text= joins eight slots with =|=. A slot that itself
-contains =|=, a backslash, or a line break would otherwise be unreadable.
+~.heading_ancestors_text~ joins eight slots with ~|~. A slot that itself
+contains ~|~, a backslash, or a line break would otherwise be unreadable.
+#+NAME: ssp-escapes
#+begin_example
in the value written as
\ \\
@@ -145,81 +155,82 @@ carriage return \r
#+end_example
Unescaping reads left to right: a backslash escapes the next character,
-=\n= and =\r= become the control characters, any other escaped character
-stands for itself, and an unescaped =|= ends the slot.
+~\n~ and ~\r~ become the control characters, any other escaped character
+stands for itself, and an unescaped ~|~ ends the slot.
*No other value is escaped*, and text lines are not escaped at all: a
text line is the object's text verbatim after its two-character prefix,
-=|= and a space.
+~|~ and a space.
** 3.2 Object text is internal markup
:PROPERTIES:
:CUSTOM_ID: sec-3-2
:END:
-The text on =|= lines is spine's *internal* representation, neither the
+The text on ~|~ lines is spine's *internal* representation, neither the
author's markup nor any output. It carries the markers spine uses to hold
inline structure:
-The full set is defined in spine's =InlineMarkup= (=ocda/meta/defaults.d=).
+The full set is defined in spine's ~InlineMarkup~ (~ocda/meta/defaults.d~).
Counts are occurrences in object text across the 36 document reference
collection, which distinguishes what a reader will certainly meet from what
it may not.
-| marker | means | count | where |
+| marker | means | count | where |
|-------------+---------------------------------------------+--------+----------------------|
-| =░= | non-breaking space | 23,048 | |
-| =┥= =┝= | link text, open and close | 20,290 | |
-| =┤= =├= | link target, open and close | 20,290 | |
-| =⑆= | a page number of the source edition follows | 19,099 | |
-| =┨= =┣= | that page number, open and close | 19,099 | |
-| =■= | monospace | 10,688 | |
-| =【= =】= | an inline note, its mark first (below) | 2,294 | |
-| =¤= | an internal site link | 2,157 | |
-| =┊= | table cell separator | 695 | =table= objects only |
-| =┙= | line break, inline | 184 | |
-| =☼= | an image, in a link's text slot | 63 | |
-| =┚= | line break, spaced | 50 | =group= objects only |
-| =〖= =〗= | a starred note | 0 | |
-| =‖= | a citation | 0 | |
-| =┘= | line break, plain | 0 | |
-| =┼= =┿= =╂= | page break: line, page, new page | 0 | |
-| =┏= =┆= | table open, table paragraph | 0 | |
-| =␣= | separator | 0 | |
+| ~░~ | non-breaking space | 23,048 | |
+| ~┥~ ~┝~ | link text, open and close | 20,290 | |
+| ~┤~ ~├~ | link target, open and close | 20,290 | |
+| ~⑆~ | a page number of the source edition follows | 19,099 | |
+| ~┨~ ~┣~ | that page number, open and close | 19,099 | |
+| ~■~ | monospace | 10,688 | |
+| ~【~ ~】~ | an inline note, its mark first (below) | 2,294 | |
+| ~¤~ | an internal site link | 2,157 | |
+| ~┊~ | table cell separator | 695 | ~table~ objects only |
+| ~┙~ | line break, inline | 184 | |
+| ~☼~ | an image, in a link's text slot | 63 | |
+| ~┚~ | line break, spaced | 50 | ~group~ objects only |
+| ~〖~ ~〗~ | a starred note | 0 | |
+| ~‖~ | a citation | 0 | |
+| ~┘~ | line break, plain | 0 | |
+| ~┼~ ~┿~ ~╂~ | page break: line, page, new page | 0 | |
+| ~┏~ ~┆~ | table open, table paragraph | 0 | |
+| ~␣~ | separator | 0 | |
*A count of 0 means the reference collection does not exercise it, not
that it cannot appear.* All of these are defined by the emitter and a
reader must be prepared for them.
-*A note begins with its mark*, then whitespace, then the note: =【12 text】=.
+*A note begins with its mark*, then whitespace, then the note: ~【12 text】~.
The mark is one of three forms, and a reader must take all three:
-| mark | what | example |
-|-------------------------+-------------------------------------------------------------------------------------------------------------------------------+----------------------------|
-| digits | the author's notes, numbered through the document | =【12 ...】= |
-| =*= or =+=, repeated | a special note, marked by the symbols alone | =【** ...】= |
-| =*= or =+=, then digits | an editor's note (2.1): the markup's =~[* ]~= and =~[+ ]~=, each series numbered through the document apart from the author's | =【*3 ...】=, =【+1 ...】= |
+- digits :: the author's notes, numbered through the document: ~【12 ...】~
+- ~*~ or ~+~, repeated :: a special note, marked by the symbols alone:
+ ~【** ...】~
+- ~*~ or ~+~, then digits :: an editor's note (2.1): the markup's =~[* ]~= and
+ =~[+ ]~=, each series numbered through the document apart from the author's:
+ ~【*3 ...】~, ~【+1 ...】~
-So the pattern is =【(\d+|[*+]+[0-9]*)\s=. Before 2.1 the third form did not
+So the pattern is ~【(\d+|[*+]+[0-9]*)\s~. Before 2.1 the third form did not
occur: spine did not recognise the editor's-note markup, and it came through
as text, =~[* ...]~= and all. Each note of every form is gathered into the
-=endnotes= section, where its =.anchor_tag= is =note_= and the mark
-(=note_12=, =note_*3=).
+~endnotes~ section, where its ~.anchor_tag~ is ~note_~ and the mark
+(~note_12~, ~note_*3~).
Two traps in this table, both found by counting rather than by reading:
-*=┚= is defined twice*, as the spaced line break and as the table close.
-In object text it occurs only in =group= objects, never in a =table=, so
+*~┚~ is defined twice*, as the spaced line break and as the table close.
+In object text it occurs only in ~group~ objects, never in a ~table~, so
the object's kind resolves it. A reader should decide by kind rather than
by character.
-*=「= and =」= are not markers here.* They are defined in =InlineMarkup=
+*~「~ and ~」~ are not markers here.* They are defined in ~InlineMarkup~
as the wrapper spine's ODT writer puts around an object number, but that
happens at output, after the abstraction. Their 67 occurrences in the
reference collection are *Japanese corner brackets in the document's own
-text*, being quotation marks in Japanese. In a =.ssp= they are always
+text*, being quotation marks in Japanese. In a ~.ssp~ they are always
content.
-Some markers are the ASCII characters =*=, =!=, =/=, =_=, =^= and =,= for
+Some markers are the ASCII characters ~*~, ~!~, ~/~, ~_~, ~^~ and ~,~ for
emphasis, bold, italic, underscore, superscript and subscript. These are
*not distinguishable from ordinary text by inspection*, and a reader that
needs them must follow spine's rules for where they apply rather than
@@ -236,7 +247,8 @@ are part of the format.
:END:
In order, and this order is fixed:
-#+begin_example
+#+NAME: ssp-file-shape
+#+begin_src ssp
% SiSU Document Abstraction v2.1
% Source: <markup filename>
@@ -257,9 +269,9 @@ In order, and this order is fixed:
@bookindex { ... }
@blurb { ... }
@tail { ... }
-#+end_example
+#+end_src
-The two =%= lines are the only comments in the file and appear only here.
+The two ~%~ lines are the only comments in the file and appear only here.
The four preamble blocks are always present and always in that order. The
nine section blocks appear in that order. *A section is omitted entirely
when the document has no objects for it*, though in practice that is rare:
@@ -270,84 +282,129 @@ them holding a single generated object.
:PROPERTIES:
:CUSTOM_ID: sec-5
:END:
-Inside a block, every line is =key: value= with exactly two spaces of
+Inside a block, every line is ~key: value~ with exactly two spaces of
indent. Keys are unique within a block. *A key whose value is empty is
omitted*, so the set of keys present varies by document; the exceptions
are noted below.
-** 5.1 =@source= - what this abstraction was made from
+** 5.1 ~@source~ - what this abstraction was made from
:PROPERTIES:
:CUSTOM_ID: sec-5-1
:END:
-| key | always? | meaning |
-|-------------+----------------------------+---------------------------------------------------------------------------|
-| =language= | yes | the language of /this/ file |
-| =languages= | when the pod declares them | every language of the document, space separated |
-| =digest= | yes | sha256 over *every markup file the document is made of*, in a fixed order |
+- ~language~, always :: the language of /this/ file
+- ~languages~, when the pod declares them :: every language of the document,
+ space separated
+- ~digest~, always :: sha256 over *every markup file the document is made of*,
+ in a fixed order
-The source /filename/ is not repeated here; it is on the =% Source:= line.
+The source /filename/ is not repeated here; it is on the ~% Source:~ line.
-=digest= is what changed in 2.0. It had been the digest of the master file
+~digest~ is what changed in 2.0. It had been the digest of the master file
alone, which for a single file document was right and for a multi-file one
was close to meaningless: any chapter could be edited without the digest
moving.
-** 5.2 =@meta= - the document's own metadata
+** 5.2 ~@meta~ - the document's own metadata [28/43]
:PROPERTIES:
:CUSTOM_ID: sec-5-2
+:COOKIE_DATA: checkbox recursive
:END:
-Dublin-Core shaped, =group.name=. *43 keys are defined*; a given document
+Dublin-Core shaped, ~group.name~. *43 keys are defined*; a given document
carries only those it has. The 28 the reference collection exercises are
-marked; the remainder are defined and simply unused by these documents.
-
-| group | keys |
-|---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| =title.= | =main=/, =subtitle=/, =full=/, =language=/, =edition=* |
-| =creator.= | =author=/, =author_surname=/, =author_surname_fn=/, =author_email=/, =illustrator=/, =translator=/ |
-| =date.= | =published=/, =created=/, =issued=/, =available=/, =modified=/, =valid=/, =added_to_site=* |
-| =rights.= | =copyright=/, =license=/, =copyright_text=, =copyright_translation=, =copyright_illustrations=, =copyright_photographs=, =copyright_cover=, =copyright_audio=, =copyright_video= |
-| =classify.= | =topic_register=/, =subject=, =keywords=, =loc=/, =dewey=* |
-| =identifier.= | =isbn=, =oclc= |
-| =notes.= | =summary=/, =abstract=/, =description=* |
-| =original.= | =source=*, =title=, =language=, =language_char= |
-| =language.= | =document_char=*, =document= |
-
-=classify.topic_register= is structured within its value: topics separated
-by =;=, levels within a topic by =:=, and alternatives at a level by =|=.
-
-** 5.3 =@make= - how the document is to be built
+checked; the remainder are defined and simply unused by these documents.
+The counts, on the heading and on each group, are of the checks.
+
+- ~title.~ [5/5]
+ - [X] ~main~
+ - [X] ~subtitle~
+ - [X] ~full~
+ - [X] ~language~
+ - [X] ~edition~
+- ~creator.~ [6/6]
+ - [X] ~author~
+ - [X] ~author_surname~
+ - [X] ~author_surname_fn~
+ - [X] ~author_email~
+ - [X] ~illustrator~
+ - [X] ~translator~
+- ~date.~ [7/7]
+ - [X] ~published~
+ - [X] ~created~
+ - [X] ~issued~
+ - [X] ~available~
+ - [X] ~modified~
+ - [X] ~valid~
+ - [X] ~added_to_site~
+- ~rights.~ [2/9]
+ - [X] ~copyright~
+ - [X] ~license~
+ - [ ] ~copyright_text~
+ - [ ] ~copyright_translation~
+ - [ ] ~copyright_illustrations~
+ - [ ] ~copyright_photographs~
+ - [ ] ~copyright_cover~
+ - [ ] ~copyright_audio~
+ - [ ] ~copyright_video~
+- ~classify.~ [3/5]
+ - [X] ~topic_register~
+ - [ ] ~subject~
+ - [ ] ~keywords~
+ - [X] ~loc~
+ - [X] ~dewey~
+- ~identifier.~ [0/2]
+ - [ ] ~isbn~
+ - [ ] ~oclc~
+- ~notes.~ [3/3]
+ - [X] ~summary~
+ - [X] ~abstract~
+ - [X] ~description~
+- ~original.~ [1/4]
+ - [X] ~source~
+ - [ ] ~title~
+ - [ ] ~language~
+ - [ ] ~language_char~
+- ~language.~ [1/2]
+ - [X] ~document_char~
+ - [ ] ~document~
+
+~classify.topic_register~ is structured within its value: topics separated
+by ~;~, levels within a topic by ~:~, and alternatives at a level by ~|~.
+
+** 5.3 ~@make~ - how the document is to be built
:PROPERTIES:
:CUSTOM_ID: sec-5-3
:END:
-| key | value | meaning |
-|-------------------------+--------------------------+---------------------------------------------------------------------------------------------------------------|
-| =doc_type= | =article=, =book= | what kind of document this is |
-| =auto_num_top_at_level= | a level, e.g. =1= | the heading level automatic numbering starts at, *as written in the markup* |
-| =auto_num_top_lv= | that level's index, 0..8 | the same level as a number ([[file:ocda-model.org::#sec-4][section 4]] of [[file:ocda-model.org][=ocda-model.org=]]); =9= where numbering is off |
-| =auto_num_depth= | e.g. =2= | how many levels down numbering continues |
-| =breaks= | see below | where the output starts a new page, and where it breaks one |
-| =footer= | slots joined with \vert{} | the footer, each slot carrying link markup |
-| =home_button_text= | link markup | the home link, as internal markup |
-
-=auto_num_top_at_level= and =auto_num_top_lv= are *the same value twice*,
-as the markup wrote it and as an index: =1= and =4=, since the body levels
+- ~doc_type~ (~article~, ~book~) :: what kind of document this is
+- ~auto_num_top_at_level~ (a level, e.g. ~1~) :: the heading level automatic
+ numbering starts at, *as written in the markup*
+- ~auto_num_top_lv~ (that level's index, 0..8) :: the same level as a number
+ ([[file:ocda-model.org::#sec-4][section 4]] of
+ [[file:ocda-model.org][~ocda-model.org~]]); ~9~ where numbering is off
+- ~auto_num_depth~ (e.g. ~2~) :: how many levels down numbering continues
+- ~breaks~ (see below) :: where the output starts a new page, and where it
+ breaks one
+- ~footer~ (slots joined with ~|~) :: the footer, each slot carrying link markup
+- ~home_button_text~ (link markup) :: the home link, as internal markup
+
+~auto_num_top_at_level~ and ~auto_num_top_lv~ are *the same value twice*,
+as the markup wrote it and as an index: ~1~ and ~4~, since the body levels
begin at index 4.
-=breaks= is a small language of its own, =new== for a new page and
-=break== for a page break, each taking a comma separated list of levels,
-the two separated by =;=:
+~breaks~ is a small language of its own, ~new=~ for a new page and
+~break=~ for a page break, each taking a comma separated list of levels,
+the two separated by ~;~:
-#+begin_example
+#+begin_src ssp
breaks: new=:A,:B; break=:C,1
breaks: new=:B; break=1
breaks: break=1
-#+end_example
+#+end_src
The level names here are written as they are in the markup, so with or
without the leading colon as the document wrote them; a reader should not
assume either form.
-** 5.4 =@doc_has= - what the document contains, by count
+** 5.4 ~@doc_has~ - what the document contains, by count
:PROPERTIES:
:CUSTOM_ID: sec-5-4
:END:
@@ -371,18 +428,18 @@ lines, then a blank line.
:PROPERTIES:
:CUSTOM_ID: sec-6-1
:END:
-#+begin_example
+#+begin_src ssp
[<ocn>] <kind>
[<ocn>] heading :<level>
[<ocn>] heading :<level> <identifier>
-#+end_example
+#+end_src
-=<ocn>= is the *object citation number* (see
-[[file:ocda-model.org][=ocda-model.org=]] [[file:ocda-model.org::#sec-3][section 3]]). =[0]= means the object has
+~<ocn>~ is the *object citation number* (see
+[[file:ocda-model.org][~ocda-model.org~]] [[file:ocda-model.org::#sec-3][section 3]]). ~[0]~ means the object has
none, is shared by many objects, and must never be used as a key; key on
position within a section instead.
-=<kind>= is one of sixteen:
+~<kind>~ is one of sixteen:
#+begin_example
para heading toc bookindex endnote code bibliography comment
@@ -390,18 +447,18 @@ verse glossary quote poem block table blurb group
#+end_example
A *heading* is the one kind whose declaration line carries more: its
-markup level after a colon (=:A= =:B= =:C= =:D= for the title levels,
-=:1=..=:4= for the body levels; =:D= is defined and unexercised by the
+markup level after a colon (~:A~ ~:B~ ~:C~ ~:D~ for the title levels,
+~:1~..~:4~ for the body levels; ~:D~ is defined and unexercised by the
reference collection), and then its identifier, when it has one
that is not simply the ocn. Every other kind carries an identifier, on the
-same condition, as the =.identifier= property.
+same condition, as the ~.identifier~ property.
#+begin_quote
*A reader must derive the identifier where it is absent, and the anchor
likewise.* "when it has one that is not simply the ocn" means the
identifier /is/ the ocn in every other case, and a reader that leaves the
-field empty gives a different model from the one the =.ocda.db= gives, on
-nearly every object. [[file:ocda-model.org::#sec-9][Section 9]] of [[file:ocda-model.org][=ocda-model.org=]] states
+field empty gives a different model from the one the ~.ocda.db~ gives, on
+nearly every object. [[file:ocda-model.org::#sec-9][Section 9]] of [[file:ocda-model.org][~ocda-model.org~]] states
both derivations and why they belong to the model rather than to either
format. Two readers written independently from these documents disagreed
for want of it.
@@ -411,17 +468,18 @@ for want of it.
:PROPERTIES:
:CUSTOM_ID: sec-6-2
:END:
-#+begin_example
+#+begin_src ssp
| <text>
-#+end_example
+#+end_src
One line per line of the object's text, in order, each prefixed with
-=|= and a space. An object with no text has no text lines. The text is
+~|~ and a space. An object with no text has no text lines. The text is
internal markup ([[#sec-3-2][section 3.2]]) and is not escaped.
** 6.3 Properties
:PROPERTIES:
:CUSTOM_ID: sec-6-3
+:COLUMNS: %ORDER(#) %ITEM(property) %VALUE(value) %EMITTED(emitted when) %COUNT(count)
:END:
*Properties appear in a fixed order*, the order of the table below, and a
reader may rely on it: checked over the reference set, no object among
@@ -429,8 +487,8 @@ reader may rely on it: checked over the reference set, no object among
*A property is omitted when it holds its default*, so absence is
meaningful and is defined per property in the table. Four properties
-repeat, appearing once per value rather than carrying a list: =.image=,
-=.stow_link=, =.lev4_subtoc= and =.anchor_tag=.
+repeat, appearing once per value rather than carrying a list: ~.image~,
+~.stow_link~, ~.lev4_subtoc~ and ~.anchor_tag~.
Two consequences of the order, which a validator needs stated and which
hold over the whole reference collection:
@@ -439,94 +497,486 @@ hold over the whole reference collection:
position in the order, and nothing is written between them. Checked: no
repeat in the collection is separated by another property.
- *no property follows the text.* The record is declaration, then
- properties, then text lines, and once a =|= line has been written no
+ properties, then text lines, and once a ~|~ line has been written no
further property appears. Checked: 0 occurrences in the collection.
In the table, "emitted when" is the condition under which the property
appears at all. Counts are occurrences across the 36 document reference
set, as a guide to which parts of the format are load bearing.
-| ​# | property | value | emitted when | count |
-|----+---------------------------+------------------------------+---------------------------------------------------------------------------------------------------+--------|
-| 1 | =.identifier= | string | a non-heading has an identifier that is not its ocn (*otherwise it is the ocn*: [[file:ocda-model.org::#sec-9][model section 9]]) | 353 |
-| 2 | =.part= | string | the object belongs to a part (=frontmatter=, =body=, ...) | 57,018 |
-| 3 | =.section= | string | the object's own section differs from the block it sits in | 605 |
-| 4 | =.parent= | int | *every object except* the document root and =toc= entries | 53,767 |
-| 5 | =.last_descendant= | int | non-zero: the last ocn under this heading | 3,202 |
-| 6 | =.ocn_range= | 2 ints | the object is a container: the first and last ocn of what it holds (2.1; a poem, [[file:ocda-model.org::#sec-5][model section 5]]) | 48 |
-| 7 | =.children= | ints | the heading has child headings | 827 |
-| 8 | =.ancestors= | 8 ints | any is non-zero | 53,731 |
-| 9 | =.ancestors_collapsed= | 8 ints | any is non-zero | 53,731 |
-| 10 | =.dom_status= | 8 ints | any is non-zero | 3,319 |
-| 11 | =.dom_status_collapsed= | 8 ints | any is non-zero | 3,319 |
-| 12 | =.heading_lev_collapsed= | int | it is below 9 | 3,503 |
-| 13 | =.parent_lev= | int | non-zero | 52,984 |
-| 14 | =.dummy= | =true= | the heading was introduced to segment an output | 183 |
-| 15 | =.ocn_off= | =true= | the object has no citation number | 7,543 |
-| 16 | =.is_of_type= | string | always, in practice | 57,018 |
-| 17 | =.attrib= | string | set | 1 |
-| 18 | =.meta_lang= | string | the object carries its own language | 0 |
-| 19 | =.meta_syntax= | string | the object carries its own markup syntax | 0 |
-| 20 | =.sha256= | hex | the object's text digest is non-zero | 51,253 |
-| 21 | =.image= | record | once *per image*, in order of appearance | 63 |
-| 22 | =.indent= | 2 ints | either indent is non-zero: =base hang= | 7,583 |
-| 23 | =.bullet= | =true= | the object is a bullet item | 1,903 |
-| 24 | =.lang= | string | the text attributes carry a language | 0 |
-| 25 | =.has= | flags | any is set | 11,384 |
-| 26 | =.table_cols= | int | the object is a table with columns | 32 |
-| 27 | =.table_widths= | ints | the table has column widths | 32 |
-| 28 | =.table_aligns= | letters | the table has alignments (=l= =c= =r=) | 32 |
-| 29 | =.table_header= | =true= | the table has a header row | 29 |
-| 30 | =.code_linenumbers= | =true= | the code block is numbered | 1 |
-| 31 | =.stow_link= | url | once *per extracted link* | 1,014 |
-| 32 | =.segment= | string | the heading opens a segment | 3,355 |
-| 33 | =.anchor= | string | the anchor differs from the segment name (*otherwise it is the segment name*: [[file:ocda-model.org::#sec-9][model section 9]]) | 68 |
-| 34 | =.segment_prev= | string | there is a previous segment | 1,022 |
-| 35 | =.segment_next= | string | there is a next segment | 1,022 |
-| 36 | =.heading_lev_anchor= | string | the heading has a level anchor tag | 1,854 |
-| 37 | =.segment_epub= | string | the heading opens an epub segment | 3,355 |
-| 38 | =.segment_html_is= | string | the object is inside an html segment | 47,072 |
-| 39 | =.segment_epub_is= | string | the object is inside an epub segment | 47,072 |
-| 40 | =.segment_lv4_is= | string | *and* it differs from =.segment_html_is= | 342 |
-| 41 | =.heading_ancestors_text= | 8 slots, \vert{} joined, escaped | any slot is non-empty | 3,319 |
-| 42 | =.lev4_subtoc= | string | once *per sub-table-of-contents entry* | 1,887 |
-| 43 | =.anchor_tag= | string | once *per anchor tag* | 8,019 |
-
-Three of these need a word here, the first two because the model behind
-them is easy to misread (see [[file:ocda-model.org][=ocda-model.org=]] [[file:ocda-model.org::#sec-5][sections 5]]
-and [[file:ocda-model.org::#sec-7][7]]), the third because it is a property of this table rather than of the
-format.
-
-*=.parent: 0= is emitted, not omitted.* A parent of 0 is a real,
+# A column view of the headings below, one per property: C-c C-c on
+# the #+BEGIN line regenerates it from their drawers.
+#+BEGIN: columnview :id local :skip-empty-rows t :maxlevel 3
+| # | property | value | emitted when | count |
+|----+---------------------------+----------------------------------+---------------------------------------------------------------------------------------------------+--------|
+| 1 | ~.identifier~ | string | a non-heading has an identifier that is not its ocn (*otherwise it is the ocn*: [[file:ocda-model.org::#sec-9][model section 9]]) | 353 |
+| 2 | ~.part~ | string | the object belongs to a part (~frontmatter~, ~body~, ...) | 57,018 |
+| 3 | ~.section~ | string | the object's own section differs from the block it sits in | 605 |
+| 4 | ~.parent~ | int | *every object except* the document root and ~toc~ entries | 53,767 |
+| 5 | ~.last_descendant~ | int | non-zero: the last ocn under this heading | 3,202 |
+| 6 | ~.ocn_range~ | 2 ints | the object is a container: the first and last ocn of what it holds (2.1; a poem, [[file:ocda-model.org::#sec-5][model section 5]]) | 48 |
+| 7 | ~.children~ | ints | the heading has child headings | 827 |
+| 8 | ~.ancestors~ | 8 ints | any is non-zero | 53,731 |
+| 9 | ~.ancestors_collapsed~ | 8 ints | any is non-zero | 53,731 |
+| 10 | ~.dom_status~ | 8 ints | any is non-zero | 3,319 |
+| 11 | ~.dom_status_collapsed~ | 8 ints | any is non-zero | 3,319 |
+| 12 | ~.heading_lev_collapsed~ | int | it is below 9 | 3,503 |
+| 13 | ~.parent_lev~ | int | non-zero | 52,984 |
+| 14 | ~.dummy~ | ~true~ | the heading was introduced to segment an output | 183 |
+| 15 | ~.ocn_off~ | ~true~ | the object has no citation number | 7,543 |
+| 16 | ~.is_of_type~ | string | always, in practice | 57,018 |
+| 17 | ~.attrib~ | string | set | 1 |
+| 18 | ~.meta_lang~ | string | the object carries its own language | 0 |
+| 19 | ~.meta_syntax~ | string | the object carries its own markup syntax | 0 |
+| 20 | ~.sha256~ | hex | the object's text digest is non-zero | 51,253 |
+| 21 | ~.image~ | record | once *per image*, in order of appearance | 63 |
+| 22 | ~.indent~ | 2 ints | either indent is non-zero: ~base hang~ | 7,583 |
+| 23 | ~.bullet~ | ~true~ | the object is a bullet item | 1,903 |
+| 24 | ~.lang~ | string | the text attributes carry a language | 0 |
+| 25 | ~.has~ | flags | any is set | 11,384 |
+| 26 | ~.table_cols~ | int | the object is a table with columns | 32 |
+| 27 | ~.table_widths~ | ints | the table has column widths | 32 |
+| 28 | ~.table_aligns~ | letters | the table has alignments (~l~ ~c~ ~r~) | 32 |
+| 29 | ~.table_header~ | ~true~ | the table has a header row | 29 |
+| 30 | ~.code_linenumbers~ | ~true~ | the code block is numbered | 1 |
+| 31 | ~.stow_link~ | url | once *per extracted link* | 1,014 |
+| 32 | ~.segment~ | string | the heading opens a segment | 3,355 |
+| 33 | ~.anchor~ | string | the anchor differs from the segment name (*otherwise it is the segment name*: [[file:ocda-model.org::#sec-9][model section 9]]) | 68 |
+| 34 | ~.segment_prev~ | string | there is a previous segment | 1,022 |
+| 35 | ~.segment_next~ | string | there is a next segment | 1,022 |
+| 36 | ~.heading_lev_anchor~ | string | the heading has a level anchor tag | 1,854 |
+| 37 | ~.segment_epub~ | string | the heading opens an epub segment | 3,355 |
+| 38 | ~.segment_html_is~ | string | the object is inside an html segment | 47,072 |
+| 39 | ~.segment_epub_is~ | string | the object is inside an epub segment | 47,072 |
+| 40 | ~.segment_lv4_is~ | string | *and* it differs from ~.segment_html_is~ | 342 |
+| 41 | ~.heading_ancestors_text~ | 8 slots, \vert{} joined, escaped | any slot is non-empty | 3,319 |
+| 42 | ~.lev4_subtoc~ | string | once *per sub-table-of-contents entry* | 1,887 |
+| 43 | ~.anchor_tag~ | string | once *per anchor tag* | 8,019 |
+#+END:
+
+Two of these carry a note under their own heading, ~.parent~ and ~.segment~,
+because the model behind them is easy to misread (see
+[[file:ocda-model.org][~ocda-model.org~]] [[file:ocda-model.org::#sec-5][sections 5]] and [[file:ocda-model.org::#sec-7][7]]).
+A third thing needs a word here, because it is a property of this table
+rather than of the format:
+
+*Count 0 does not mean "not in the format".* ~.meta_lang~, ~.meta_syntax~
+and ~.lang~ are emitted by spine under the conditions given, and no
+document in the reference collection meets them. A reader must handle them;
+a test corpus does not exercise them.
+
+*** ~.identifier~
+:PROPERTIES:
+:CUSTOM_ID: prop-identifier
+:ORDER: 1
+:VALUE: string
+:EMITTED: a non-heading has an identifier that is not its ocn (*otherwise it is the ocn*: [[file:ocda-model.org::#sec-9][model section 9]])
+:COUNT: 353
+:END:
+
+*** ~.part~
+:PROPERTIES:
+:CUSTOM_ID: prop-part
+:ORDER: 2
+:VALUE: string
+:EMITTED: the object belongs to a part (~frontmatter~, ~body~, ...)
+:COUNT: 57,018
+:END:
+
+*** ~.section~
+:PROPERTIES:
+:CUSTOM_ID: prop-section
+:ORDER: 3
+:VALUE: string
+:EMITTED: the object's own section differs from the block it sits in
+:COUNT: 605
+:END:
+
+*** ~.parent~
+:PROPERTIES:
+:CUSTOM_ID: prop-parent
+:ORDER: 4
+:VALUE: int
+:EMITTED: *every object except* the document root and ~toc~ entries
+:COUNT: 53,767
+:END:
+*~.parent: 0~ is emitted, not omitted.* A parent of 0 is a real,
non-substantive parent and not a missing value, so the property is written
out rather than defaulted away: omitting it would make the two cases
indistinguishable in the file. A reader walking upward stops at 0.
-*=.segment= and =.segment_html_is= are different questions*, and both are
+*** ~.last_descendant~
+:PROPERTIES:
+:CUSTOM_ID: prop-last-descendant
+:ORDER: 5
+:VALUE: int
+:EMITTED: non-zero: the last ocn under this heading
+:COUNT: 3,202
+:END:
+
+*** ~.ocn_range~
+:PROPERTIES:
+:CUSTOM_ID: prop-ocn-range
+:ORDER: 6
+:VALUE: 2 ints
+:EMITTED: the object is a container: the first and last ocn of what it holds (2.1; a poem, [[file:ocda-model.org::#sec-5][model section 5]])
+:COUNT: 48
+:END:
+
+*** ~.children~
+:PROPERTIES:
+:CUSTOM_ID: prop-children
+:ORDER: 7
+:VALUE: ints
+:EMITTED: the heading has child headings
+:COUNT: 827
+:END:
+
+*** ~.ancestors~
+:PROPERTIES:
+:CUSTOM_ID: prop-ancestors
+:ORDER: 8
+:VALUE: 8 ints
+:EMITTED: any is non-zero
+:COUNT: 53,731
+:END:
+
+*** ~.ancestors_collapsed~
+:PROPERTIES:
+:CUSTOM_ID: prop-ancestors-collapsed
+:ORDER: 9
+:VALUE: 8 ints
+:EMITTED: any is non-zero
+:COUNT: 53,731
+:END:
+
+*** ~.dom_status~
+:PROPERTIES:
+:CUSTOM_ID: prop-dom-status
+:ORDER: 10
+:VALUE: 8 ints
+:EMITTED: any is non-zero
+:COUNT: 3,319
+:END:
+
+*** ~.dom_status_collapsed~
+:PROPERTIES:
+:CUSTOM_ID: prop-dom-status-collapsed
+:ORDER: 11
+:VALUE: 8 ints
+:EMITTED: any is non-zero
+:COUNT: 3,319
+:END:
+
+*** ~.heading_lev_collapsed~
+:PROPERTIES:
+:CUSTOM_ID: prop-heading-lev-collapsed
+:ORDER: 12
+:VALUE: int
+:EMITTED: it is below 9
+:COUNT: 3,503
+:END:
+
+*** ~.parent_lev~
+:PROPERTIES:
+:CUSTOM_ID: prop-parent-lev
+:ORDER: 13
+:VALUE: int
+:EMITTED: non-zero
+:COUNT: 52,984
+:END:
+
+*** ~.dummy~
+:PROPERTIES:
+:CUSTOM_ID: prop-dummy
+:ORDER: 14
+:VALUE: ~true~
+:EMITTED: the heading was introduced to segment an output
+:COUNT: 183
+:END:
+
+*** ~.ocn_off~
+:PROPERTIES:
+:CUSTOM_ID: prop-ocn-off
+:ORDER: 15
+:VALUE: ~true~
+:EMITTED: the object has no citation number
+:COUNT: 7,543
+:END:
+
+*** ~.is_of_type~
+:PROPERTIES:
+:CUSTOM_ID: prop-is-of-type
+:ORDER: 16
+:VALUE: string
+:EMITTED: always, in practice
+:COUNT: 57,018
+:END:
+
+*** ~.attrib~
+:PROPERTIES:
+:CUSTOM_ID: prop-attrib
+:ORDER: 17
+:VALUE: string
+:EMITTED: set
+:COUNT: 1
+:END:
+
+*** ~.meta_lang~
+:PROPERTIES:
+:CUSTOM_ID: prop-meta-lang
+:ORDER: 18
+:VALUE: string
+:EMITTED: the object carries its own language
+:COUNT: 0
+:END:
+
+*** ~.meta_syntax~
+:PROPERTIES:
+:CUSTOM_ID: prop-meta-syntax
+:ORDER: 19
+:VALUE: string
+:EMITTED: the object carries its own markup syntax
+:COUNT: 0
+:END:
+
+*** ~.sha256~
+:PROPERTIES:
+:CUSTOM_ID: prop-sha256
+:ORDER: 20
+:VALUE: hex
+:EMITTED: the object's text digest is non-zero
+:COUNT: 51,253
+:END:
+
+*** ~.image~
+:PROPERTIES:
+:CUSTOM_ID: prop-image
+:ORDER: 21
+:VALUE: record
+:EMITTED: once *per image*, in order of appearance
+:COUNT: 63
+:END:
+Its inner form is [[#sec-6-4][section 6.4]].
+
+*** ~.indent~
+:PROPERTIES:
+:CUSTOM_ID: prop-indent
+:ORDER: 22
+:VALUE: 2 ints
+:EMITTED: either indent is non-zero: ~base hang~
+:COUNT: 7,583
+:END:
+
+*** ~.bullet~
+:PROPERTIES:
+:CUSTOM_ID: prop-bullet
+:ORDER: 23
+:VALUE: ~true~
+:EMITTED: the object is a bullet item
+:COUNT: 1,903
+:END:
+
+*** ~.lang~
+:PROPERTIES:
+:CUSTOM_ID: prop-lang
+:ORDER: 24
+:VALUE: string
+:EMITTED: the text attributes carry a language
+:COUNT: 0
+:END:
+
+*** ~.has~
+:PROPERTIES:
+:CUSTOM_ID: prop-has
+:ORDER: 25
+:VALUE: flags
+:EMITTED: any is set
+:COUNT: 11,384
+:END:
+The flags are [[#sec-6-5][section 6.5]].
+
+*** ~.table_cols~
+:PROPERTIES:
+:CUSTOM_ID: prop-table-cols
+:ORDER: 26
+:VALUE: int
+:EMITTED: the object is a table with columns
+:COUNT: 32
+:END:
+
+*** ~.table_widths~
+:PROPERTIES:
+:CUSTOM_ID: prop-table-widths
+:ORDER: 27
+:VALUE: ints
+:EMITTED: the table has column widths
+:COUNT: 32
+:END:
+
+*** ~.table_aligns~
+:PROPERTIES:
+:CUSTOM_ID: prop-table-aligns
+:ORDER: 28
+:VALUE: letters
+:EMITTED: the table has alignments (~l~ ~c~ ~r~)
+:COUNT: 32
+:END:
+
+*** ~.table_header~
+:PROPERTIES:
+:CUSTOM_ID: prop-table-header
+:ORDER: 29
+:VALUE: ~true~
+:EMITTED: the table has a header row
+:COUNT: 29
+:END:
+
+*** ~.code_linenumbers~
+:PROPERTIES:
+:CUSTOM_ID: prop-code-linenumbers
+:ORDER: 30
+:VALUE: ~true~
+:EMITTED: the code block is numbered
+:COUNT: 1
+:END:
+
+*** ~.stow_link~
+:PROPERTIES:
+:CUSTOM_ID: prop-stow-link
+:ORDER: 31
+:VALUE: url
+:EMITTED: once *per extracted link*
+:COUNT: 1,014
+:END:
+
+*** ~.segment~
+:PROPERTIES:
+:CUSTOM_ID: prop-segment
+:ORDER: 32
+:VALUE: string
+:EMITTED: the heading opens a segment
+:COUNT: 3,355
+:END:
+*~.segment~ and ~.segment_html_is~ are different questions*, and both are
carried: what a heading opens, and what an object sits in. A reader wanting
to know where a paragraph belongs needs the second.
-*Count 0 does not mean "not in the format".* =.meta_lang=, =.meta_syntax=
-and =.lang= are emitted by spine under the conditions given, and no
-document in the reference collection meets them. A reader must handle them;
-a test corpus does not exercise them.
+*** ~.anchor~
+:PROPERTIES:
+:CUSTOM_ID: prop-anchor
+:ORDER: 33
+:VALUE: string
+:EMITTED: the anchor differs from the segment name (*otherwise it is the segment name*: [[file:ocda-model.org::#sec-9][model section 9]])
+:COUNT: 68
+:END:
+
+*** ~.segment_prev~
+:PROPERTIES:
+:CUSTOM_ID: prop-segment-prev
+:ORDER: 34
+:VALUE: string
+:EMITTED: there is a previous segment
+:COUNT: 1,022
+:END:
+
+*** ~.segment_next~
+:PROPERTIES:
+:CUSTOM_ID: prop-segment-next
+:ORDER: 35
+:VALUE: string
+:EMITTED: there is a next segment
+:COUNT: 1,022
+:END:
+
+*** ~.heading_lev_anchor~
+:PROPERTIES:
+:CUSTOM_ID: prop-heading-lev-anchor
+:ORDER: 36
+:VALUE: string
+:EMITTED: the heading has a level anchor tag
+:COUNT: 1,854
+:END:
+
+*** ~.segment_epub~
+:PROPERTIES:
+:CUSTOM_ID: prop-segment-epub
+:ORDER: 37
+:VALUE: string
+:EMITTED: the heading opens an epub segment
+:COUNT: 3,355
+:END:
+
+*** ~.segment_html_is~
+:PROPERTIES:
+:CUSTOM_ID: prop-segment-html-is
+:ORDER: 38
+:VALUE: string
+:EMITTED: the object is inside an html segment
+:COUNT: 47,072
+:END:
+
+*** ~.segment_epub_is~
+:PROPERTIES:
+:CUSTOM_ID: prop-segment-epub-is
+:ORDER: 39
+:VALUE: string
+:EMITTED: the object is inside an epub segment
+:COUNT: 47,072
+:END:
+
+*** ~.segment_lv4_is~
+:PROPERTIES:
+:CUSTOM_ID: prop-segment-lv4-is
+:ORDER: 40
+:VALUE: string
+:EMITTED: *and* it differs from ~.segment_html_is~
+:COUNT: 342
+:END:
+
+*** ~.heading_ancestors_text~
+:PROPERTIES:
+:CUSTOM_ID: prop-heading-ancestors-text
+:ORDER: 41
+:VALUE: 8 slots, \vert{} joined, escaped
+:EMITTED: any slot is non-empty
+:COUNT: 3,319
+:END:
-** 6.4 The =.image= record
+*** ~.lev4_subtoc~
+:PROPERTIES:
+:CUSTOM_ID: prop-lev4-subtoc
+:ORDER: 42
+:VALUE: string
+:EMITTED: once *per sub-table-of-contents entry*
+:COUNT: 1,887
+:END:
+
+*** ~.anchor_tag~
+:PROPERTIES:
+:CUSTOM_ID: prop-anchor-tag
+:ORDER: 43
+:VALUE: string
+:EMITTED: once *per anchor tag*
+:COUNT: 8,019
+:END:
+
+** 6.4 The ~.image~ record
:PROPERTIES:
:CUSTOM_ID: sec-6-4
:END:
-#+begin_example
+#+begin_src ssp
.image: <filename> sha256:<HEX> bytes:<n> px:<width>x<height>
.image: <filename> missing:true
-#+end_example
+#+end_src
Filename first, as the object's handle on the image. The remaining fields
-are self describing =key:value= tokens, *so that further fields may be
-added without invalidating existing readers*; =px:= is omitted when the
-pixel size is unknown. =px:= is the file's own size, not the display size,
+are self describing ~key:value~ tokens, *so that further fields may be
+added without invalidating existing readers*; ~px:~ is omitted when the
+pixel size is unknown. ~px:~ is the file's own size, not the display size,
which the object's text already carries.
-** 6.5 The =.has= flags
+** 6.5 The ~.has~ flags
:PROPERTIES:
:CUSTOM_ID: sec-6-5
:END:
@@ -555,7 +1005,8 @@ the table is the contract.
*Checked*: every line of the 36 document reference collection matches one
of the eight line shapes below, 721,363 lines with none left over.
-#+begin_src peg
+#+NAME: ssp-grammar
+#+begin_src peg :tangle ssp.peg
Document <- Header Source Meta Make DocHas Section* EOF
Header <- "% SiSU Document Abstraction v" Version EOL
"% Source: " Value EOL Blank
@@ -608,9 +1059,9 @@ Digit <- [0-9]
- *Tolerate unknown properties* within a known major version, since the
minor part is raised precisely by adding them. Ignoring them is
conforming behaviour.
-- *Treat =[0]= as not an identity.* Objects with no citation number are
+- *Treat ~[0]~ as not an identity.* Objects with no citation number are
numerous and share the number.
-- *Stop at =.parent: 0=* when walking upward.
+- *Stop at ~.parent: 0~* when walking upward.
** 8.2 A reader should
:PROPERTIES:
@@ -635,12 +1086,12 @@ Digit <- [0-9]
:CUSTOM_ID: sec-9
:END:
The model this format writes down is specified in
-[[file:ocda-model.org][=ocda-model.org=]]: objects, citation numbers, structure,
+[[file:ocda-model.org][~ocda-model.org~]]: objects, citation numbers, structure,
sections, segments and digests. This document adds nothing to the model and
subtracts nothing from it; it says how the model is written as text.
-The =.ocda.db= is the same abstraction as sqlite, and is *built by reading
-a =.ssp= back*: the document is emitted as =.ssp=, read straight in, and
+The ~.ocda.db~ is the same abstraction as sqlite, and is *built by reading
+a ~.ssp~ back*: the document is emitted as ~.ssp~, read straight in, and
what comes back is written. So the database cannot carry an object property
this format cannot express, and the two cannot drift. They share the
version, which is why a bump moves both.
@@ -653,9 +1104,9 @@ well, which this format does not.
:PROPERTIES:
:CUSTOM_ID: sec-10
:END:
-- =example-autonomous-contract.ssp= - one document, complete and unedited.
-- =example-wealth-of-networks.ssp= - an excerpt of a large one: verbatim
- lines with marked elisions, keeping the preamble, the =@head= section,
+- ~example-autonomous-contract.ssp~ - one document, complete and unedited.
+- ~example-wealth-of-networks.ssp~ - an excerpt of a large one: verbatim
+ lines with marked elisions, keeping the preamble, the ~@head~ section,
and a run of body objects including one that embeds an image.
Each carries, in its opening comments, the command that regenerates it.