sisu-spine-markup.sst edits, updates

sisu-spine-markup.sst needs review and update, it was taken from
the much older sisu (ruby) writing and was itself a part of a more
comprehensive document (sisu-manual). Some updates.

(assisted by Claude-Code)

2 files changed, 162 insertions, 38 deletions

diff --git a/data/pod/sisu-spine-markup/media/text/en/sisu-spine-markup.sst b/data/pod/sisu-spine-markup/media/text/en/sisu-spine-markup.sst
index 42c0377..eb4163b 100644
--- a/data/pod/sisu-spine-markup/media/text/en/sisu-spine-markup.sst
+++ b/data/pod/sisu-spine-markup/media/text/en/sisu-spine-markup.sst
@@ -83,7 +83,8 @@ minimal content/structure requirement, minimum being:
 metadata
 
 ``` code
-title: "SiSU Spine"
+title:
+  main: "SiSU Spine"
   subtitle: "Markup"
 
 creator:
@@ -105,7 +106,8 @@ A~ (level A [title])
 
 structure rules (document heirarchy, heading levels):
 
-there are two sets of heading levels ABCD (title & parts if any) and 123 (segment & subsegments if any)
+there are two sets of heading levels ABCD (title & parts if any) and 1234
+(segment & subsegments if any)
 ={ SiSU markup:heading levels }
 
 sisu has the fllowing levels (that may be described as document parts, headings and subheadings):
@@ -141,8 +143,13 @@ D~ [subsubpart]
      by more text or by levels 1~, 2~ or 3~ (or relevant part)
 
 3~ [sub-sub-heading]
+   - followed by level 4~ or
+   - by text which can then be followed
+     by more text or by levels 1~, 2~, 3~ or 4~ (or relevant part)
+
+4~ [sub-sub-sub-heading]
    - followed by text which can be followed
-     by more text or by levels 1~, 2~ or 3~ (or relevant part)
+     by more text or by levels 1~, 2~, 3~ or 4~ (or relevant part)
 ```
 
 Rules:
@@ -151,11 +158,13 @@ Rules:
 - level A~ is mandatory, it is the (document root and) title
 
 - there can only be one document root == level/part A~
+  (object citation number 1, by definition)
 
 - heading levels B,C,D, are optional and there may be several of each
   (where all three are used corresponding to e.g. Book, Part, Section)
-  - sublevels that are used must follow each other sequentially
-    (alphabetically),
+  - the part levels are optional as a group, and those that are used must
+    follow each other sequentially (alphabetically), so a C~ may not follow
+    an A~ directly, and a D~ may not follow a B~
 
 - heading levels A~ B~ C~ D~ are followed by other heading levels rather
   than substantive text
@@ -166,15 +175,25 @@ Rules:
   (the level on which the text is segmented, in a book would correspond
   to the Chapter level)
 
-- additional heading levels 1~ 2~ 3~ are optional and there may be several
-  of each
+- additional heading levels 1~ 2~ 3~ 4~ are optional and there may be
+  several of each
+
+- heading levels are not skipped: a sub-level is entered from the level
+  immediately above it, so a 2~ is entered from a 1~, a 3~ from a 2~ and
+  a 4~ from a 3~. A 1~ followed directly by a 3~ is a markup error and
+  the program will stop and report it, naming the file, the line, the
+  level reached and the level that is missing
 
-- heading levels 1~ 2~ 3~ are followed by text (which may be followed by
+- heading levels 1~ 2~ 3~ 4~ are followed by text (which may be followed by
   the same heading level)
   and/or the next lower numeric heading level (followed by text)
   or indeed return to the relevant part level
   (as a corollary to the rules above substantive text/ content
-  must be preceded by a level 1~ (2~ or 3~) heading)
+  must be preceded by a level 1~ (2~ 3~ or 4~) heading)
+
+- every object belongs to (has as its parent) the heading it falls under,
+  with one exception: a footnote or endnote belongs to the object it is
+  called from, whether that is a paragraph, a block or a heading
 ```
 
 2~ Markup Examples
@@ -378,14 +397,17 @@ make:
 2~heading_levels Heading Levels
 ={ SiSU markup:heading levels }
 
-Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section
-headings, followed by other heading levels, and 1 -6 being headings followed by
-substantive text or sub-headings. :A~ usually the title :A~? conditional level 1
-heading (used where a stand-alone document may be imported into another)
+Heading levels are :A~ ,:B~ ,:C~ ,:D~ ,1~ ,2~ ,3~ ,4~ - :A~ to :D~ being the
+title and part / section headings, which are followed by other heading levels;
+1~ to 4~ being headings followed by substantive text or sub-headings. Note, the
+colon preceeding the letter headings is optional (they may be represented as A~
+B~ C~ and D~ respectively).
 
 !_ :A~ [heading text]
-Top level heading [this usually has similar content to the title [title] ]
-NOTE: the heading levels described here are in 0.38 notation, see heading
+Top level heading, the document root [this usually has similar content to the
+title in the document header, and is commonly written as :A~ @title @creator].
+There is exactly one, and it is required.
+(:A~? conditional level 1 heading (used where a stand-alone document may be imported into another))
 
 !_ :B~ [heading text]
 Second level heading [this is a heading level divider]
@@ -393,21 +415,29 @@ Second level heading [this is a heading level divider]
 !_ :C~ [heading text]
 Third level heading [this is a heading level divider]
 
+!_ :D~ [heading text]
+Fourth level heading [this is a heading level divider]
+
 !_ 1~ [heading text]
-Top level heading preceding substantive text of document or sub-heading 2, the
+Top level heading preceding substantive text of document or sub-heading 2~, the
 heading level that would normally be marked 1. or 2. or 3. etc. in a document,
 and the level on which sisu by default would break html output into named
 segments, names are provided automatically if none are given (a number),
 otherwise takes the form 1~my_filename_for_this_segment
 
 !_ 2~ [heading text]
-Second level heading preceding substantive text of document or sub-heading 3 ,
+Second level heading preceding substantive text of document or sub-heading 3~,
 the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc. in
 a document.
 
 !_ 3~ [heading text]
-Third level heading preceding substantive text of document, that would normally
-be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
+Third level heading preceding substantive text of document or sub-heading 4~,
+that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a
+document
+
+!_ 4~ [heading text]
+Fourth level heading preceding substantive text of document, that would
+normally be marked 1.1.1.1 or 1.1.2.1 etc. in a document
 
 code{
 
@@ -1274,6 +1304,26 @@ code{
 
 2~ Excluding Object Numbers
 
+Every substantive object in a document is given an object citation number
+(ocn), assigned sequentially in document order. The number belongs to the
+object, not to the page or the file, and it is the same number in every output
+format that spine generates from the document: the paragraph that is 47 in the
+html is 47 in the epub, in the LaTeX/pdf, in the plain text and in the sqlite
+database.
+
+That is what makes an object citable. A reference to "ocn 47" of a document
+resolves to the same piece of text for anyone, whatever format they are
+reading, without depending on an edition, a pagination or a URL; searches
+return objects rather than documents, and a search result can link straight to
+the object in a chosen output; and where translations are prepared so that
+objects correspond, the same number reaches the same object in each language.
+
+Suppressing an object's number therefore does not hide the object, it makes it
+non-citable: it drops out of that shared numbering. That is what is wanted for
+matter that is not part of the text being reproduced (a preamble, an editorial
+note, a heading introduced only to segment an output), and is not wanted for
+anything a reader might want to cite or search to.
+
 Object numbers can be switched off by adding a ~# to the end of a text object.
 
 Sometimes it is wished to switch off object numbers for a larger group of text.
@@ -1298,6 +1348,18 @@ to switch of object numbering for a single objct, to the end of the object add ~
 
 }code
 
+"dummy headings" represented by a -# (dash instead of a tilde) may be used where
+a heading (that is not in the original text being reproduced) is introduced only
+for segmentation purposes (to make sure a new chapter / segment is begun) for a
+particular output format, as somtimes occurs for segmented html. For example
+where there is intoroductory text (or a preamble) immediately after the document
+title/root, (without a heading) html segmentation would require a level 1~
+heading which might be added as 1~ [Introduction].-# This not only skips an
+object number, it also supresses reproducing the heading where possible (e.g. it
+would appear in the table of contents but be skipped in the text body). If a
+regular ocn suppresion marker ~# is used on a heading, the ocn is skipped, but
+the heading will always be shown.
+
 2~ Bibliography / References
 ={ SiSU markup:references|bibliography|citations;references }
 
diff --git a/org/spine_markup_sample.org b/org/spine_markup_sample.org
index f6747c2..c328d53 100644
--- a/org/spine_markup_sample.org
+++ b/org/spine_markup_sample.org
@@ -176,7 +176,8 @@ minimal content/structure requirement, minimum being:
 metadata
 
 ``` code
-title: "SiSU Spine"
+title:
+  main: "SiSU Spine"
   subtitle: "Markup"
 
 creator:
@@ -198,7 +199,8 @@ A~ (level A [title])
 
 structure rules (document heirarchy, heading levels):
 
-there are two sets of heading levels ABCD (title & parts if any) and 123 (segment & subsegments if any)
+there are two sets of heading levels ABCD (title & parts if any) and 1234
+(segment & subsegments if any)
 ={ SiSU markup:heading levels }
 
 sisu has the fllowing levels (that may be described as document parts, headings and subheadings):
@@ -234,8 +236,13 @@ D~ [subsubpart]
      by more text or by levels 1~, 2~ or 3~ (or relevant part)
 
 3~ [sub-sub-heading]
+   - followed by level 4~ or
+   - by text which can then be followed
+     by more text or by levels 1~, 2~, 3~ or 4~ (or relevant part)
+
+4~ [sub-sub-sub-heading]
    - followed by text which can be followed
-     by more text or by levels 1~, 2~ or 3~ (or relevant part)
+     by more text or by levels 1~, 2~, 3~ or 4~ (or relevant part)
 ```
 
 Rules:
@@ -244,11 +251,13 @@ Rules:
 - level A~ is mandatory, it is the (document root and) title
 
 - there can only be one document root == level/part A~
+  (object citation number 1, by definition)
 
 - heading levels B,C,D, are optional and there may be several of each
   (where all three are used corresponding to e.g. Book, Part, Section)
-  - sublevels that are used must follow each other sequentially
-    (alphabetically),
+  - the part levels are optional as a group, and those that are used must
+    follow each other sequentially (alphabetically), so a C~ may not follow
+    an A~ directly, and a D~ may not follow a B~
 
 - heading levels A~ B~ C~ D~ are followed by other heading levels rather
   than substantive text
@@ -259,15 +268,25 @@ Rules:
   (the level on which the text is segmented, in a book would correspond
   to the Chapter level)
 
-- additional heading levels 1~ 2~ 3~ are optional and there may be several
-  of each
+- additional heading levels 1~ 2~ 3~ 4~ are optional and there may be
+  several of each
+
+- heading levels are not skipped: a sub-level is entered from the level
+  immediately above it, so a 2~ is entered from a 1~, a 3~ from a 2~ and
+  a 4~ from a 3~. A 1~ followed directly by a 3~ is a markup error and
+  the program will stop and report it, naming the file, the line, the
+  level reached and the level that is missing
 
-- heading levels 1~ 2~ 3~ are followed by text (which may be followed by
+- heading levels 1~ 2~ 3~ 4~ are followed by text (which may be followed by
   the same heading level)
   and/or the next lower numeric heading level (followed by text)
   or indeed return to the relevant part level
   (as a corollary to the rules above substantive text/ content
-  must be preceded by a level 1~ (2~ or 3~) heading)
+  must be preceded by a level 1~ (2~ 3~ or 4~) heading)
+
+- every object belongs to (has as its parent) the heading it falls under,
+  with one exception: a footnote or endnote belongs to the object it is
+  called from, whether that is a paragraph, a block or a heading
 ```
 
 2~ Markup Examples
@@ -489,14 +508,17 @@ make:
 2~heading_levels Heading Levels
 ={ SiSU markup:heading levels }
 
-Heading levels are :A~ ,:B~ ,:C~ ,1~ ,2~ ,3~ ... :A - :C being part / section
-headings, followed by other heading levels, and 1 -6 being headings followed by
-substantive text or sub-headings. :A~ usually the title :A~? conditional level 1
-heading (used where a stand-alone document may be imported into another)
+Heading levels are :A~ ,:B~ ,:C~ ,:D~ ,1~ ,2~ ,3~ ,4~ - :A~ to :D~ being the
+title and part / section headings, which are followed by other heading levels;
+1~ to 4~ being headings followed by substantive text or sub-headings. Note, the
+colon preceeding the letter headings is optional (they may be represented as A~
+B~ C~ and D~ respectively).
 
 !_ :A~ [heading text]
-Top level heading [this usually has similar content to the title [title] ]
-NOTE: the heading levels described here are in 0.38 notation, see heading
+Top level heading, the document root [this usually has similar content to the
+title in the document header, and is commonly written as :A~ @title @creator].
+There is exactly one, and it is required.
+(:A~? conditional level 1 heading (used where a stand-alone document may be imported into another))
 
 !_ :B~ [heading text]
 Second level heading [this is a heading level divider]
@@ -504,21 +526,29 @@ Second level heading [this is a heading level divider]
 !_ :C~ [heading text]
 Third level heading [this is a heading level divider]
 
+!_ :D~ [heading text]
+Fourth level heading [this is a heading level divider]
+
 !_ 1~ [heading text]
-Top level heading preceding substantive text of document or sub-heading 2, the
+Top level heading preceding substantive text of document or sub-heading 2~, the
 heading level that would normally be marked 1. or 2. or 3. etc. in a document,
 and the level on which sisu by default would break html output into named
 segments, names are provided automatically if none are given (a number),
 otherwise takes the form 1~my_filename_for_this_segment
 
 !_ 2~ [heading text]
-Second level heading preceding substantive text of document or sub-heading 3 ,
+Second level heading preceding substantive text of document or sub-heading 3~,
 the heading level that would normally be marked 1.1 or 1.2 or 1.3 or 2.1 etc. in
 a document.
 
 !_ 3~ [heading text]
-Third level heading preceding substantive text of document, that would normally
-be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document
+Third level heading preceding substantive text of document or sub-heading 4~,
+that would normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a
+document
+
+!_ 4~ [heading text]
+Fourth level heading preceding substantive text of document, that would
+normally be marked 1.1.1.1 or 1.1.2.1 etc. in a document
 
 code{
 
@@ -1433,6 +1463,26 @@ code{
 #+BEGIN_SRC text
 2~ Excluding Object Numbers
 
+Every substantive object in a document is given an object citation number
+(ocn), assigned sequentially in document order. The number belongs to the
+object, not to the page or the file, and it is the same number in every output
+format that spine generates from the document: the paragraph that is 47 in the
+html is 47 in the epub, in the LaTeX/pdf, in the plain text and in the sqlite
+database.
+
+That is what makes an object citable. A reference to "ocn 47" of a document
+resolves to the same piece of text for anyone, whatever format they are
+reading, without depending on an edition, a pagination or a URL; searches
+return objects rather than documents, and a search result can link straight to
+the object in a chosen output; and where translations are prepared so that
+objects correspond, the same number reaches the same object in each language.
+
+Suppressing an object's number therefore does not hide the object, it makes it
+non-citable: it drops out of that shared numbering. That is what is wanted for
+matter that is not part of the text being reproduced (a preamble, an editorial
+note, a heading introduced only to segment an output), and is not wanted for
+anything a reader might want to cite or search to.
+
 Object numbers can be switched off by adding a ~# to the end of a text object.
 
 Sometimes it is wished to switch off object numbers for a larger group of text.
@@ -1457,6 +1507,18 @@ to switch of object numbering for a single objct, to the end of the object add ~
 
 }code
 
+"dummy headings" represented by a -# (dash instead of a tilde) may be used where
+a heading (that is not in the original text being reproduced) is introduced only
+for segmentation purposes (to make sure a new chapter / segment is begun) for a
+particular output format, as somtimes occurs for segmented html. For example
+where there is intoroductory text (or a preamble) immediately after the document
+title/root, (without a heading) html segmentation would require a level 1~
+heading which might be added as 1~ [Introduction].-# This not only skips an
+object number, it also supresses reproducing the heading where possible (e.g. it
+would appear in the table of contents but be skipped in the text body). If a
+regular ocn suppresion marker ~# is used on a heading, the ocn is skipped, but
+the heading will always be shown.
+
 #+END_SRC
 
 ***** bibliography