From 4e2c4a0e4907cd373fc703f8c100cf7e78f2ba05 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Wed, 2 Sep 2026 23:06:22 -0400 Subject: 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) --- .../media/text/en/sisu-spine-markup.sst | 100 +++++++++++++++++---- org/spine_markup_sample.org | 100 +++++++++++++++++---- 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 -- cgit v1.2.3