sisu markup sample .sst edits

track on sisu markup sample

1 files changed, 204 insertions, 32 deletions

diff --git a/org/spine_markup_sample.org b/org/spine_markup_sample.org
index c328d53..d7e2148 100644
--- a/org/spine_markup_sample.org
+++ b/org/spine_markup_sample.org
@@ -45,7 +45,9 @@ doc:
 #+BEGIN_SRC text
 <<spine_markup_sample_header_metadata>>
 <<spine_markup_sample_header_make>>
-<<spine_markup_sample_body>>
+<<spine_markup_sample_body_document_title>>
+<<spine_markup_sample_body_sisu_description>>
+<<spine_markup_sample_body_sisu_markup>>
 <<spine_markup_sample_body_introduction>>
 <<spine_markup_sample_body_markup_header>>
 <<spine_markup_sample_body_markup_substantive_text>>
@@ -90,7 +92,7 @@ date:
   modified: "2012-10-03"
 
 rights:
-  copyright: "Copyright (C) Ralph Amissah 2007"
+  copyright: "Ralph Amissah 2007"
   license: "GPL 3 (part of SiSU documentation)"
 
 classify:
@@ -104,32 +106,202 @@ classify:
 #+NAME: spine_markup_sample_header_make
 #+BEGIN_SRC yaml
 make:
+  doc_type: "book"
+  breaks: "new=:B; break=1"
   auto_num_top_at_level: "1"
   substitute: [
       [ "[$]{2}\\{sisudoc\\}", "www.sisudoc.org" ]
     ]
-#substitute: [ "[$]{2}\\{sisudoc\\}", "www.sisudoc.org" ]
+  #substitute: [ "[$]{2}\\{sisudoc\\}", "www.sisudoc.org" ]
   bold: "Debian|SiSU"
   italics: "Linux|GPL|LaTeX|SQL"
-  breaks: "new=:B; break=1"
-  home_button_text: [
-      "{doc-reform}https://doc-reform.org",
-      "{sources / git}https://git.sisudoc.org/",
-      "{SiSU}https://sisudoc.org"
-    ]
-  footer: [
-      "{SiSU}https://sisudoc.org",
-      "{git}https://git.sisudoc.org"
-    ]
+  home_button_text:
+    - "{doc-reform}https://doc-reform.org"
+    - "{sources / git}https://git.sisudoc.org"
+    - "{SiSU}https://sisudoc.org"
+  footer:
+    - "{SiSU}https://sisudoc.org"
+    - "{git}https://git.sisudoc.org"
 
 #+END_SRC
 
-*** document body
+*** document title
 
-#+NAME: spine_markup_sample_body
+#+NAME: spine_markup_sample_body_document_title
 #+BEGIN_SRC text
 :A~ @title @creator
 
+#+END_SRC
+
+*** sisu description
+
+#+NAME: spine_markup_sample_body_sisu_description
+#+BEGIN_SRC text
+:B~ SiSU Description
+
+1~description SiSU an outline
+
+SiSU is an object-centric, lightweight markup based, document structuring,
+parser, publishing and search tool for document collections. It is command line
+oriented and generates static content that is currently made searchable at an
+object level through an SQL database. Markup helps define (delineate) objects
+(primarily various types of text block) which are tracked in sequence,
+substantive objects being numbered sequentially by the program for object
+citation.
+
+2~ Summary
+
+An object is a unit of text within a document the most common being a paragraph.
+Objects include individual headings, paragraphs, tables, grouped text of various
+types such as code blocks and within poems, verse. Objects have properties and
+attributes, of particular significance are headings and their levels which
+provide document structure. A heading is an object with a hierarchical value,
+that conceptually contains other objects (such as paragraphs and possibly
+sub-headings etc.). Objects are tracked sequentially as they relate to each
+other object within a document and substantive objects are numbered
+sequentially, for citation purposes. Notably footnotes are not objects in
+themselves, rather belonging to the object from which they are referenced, and
+following their own per-document, sequential numbering sequence. From heading
+objects (linked) tables of content may be generated, and if additional metadata
+is provided book type indexes can be generated that link back to the objects to
+which they relate. Unpacking this a bit further. SiSU as a concept independent
+of its markup language and the parsers that have been implemented, is based on
+ideas discussed below.
+
+2~ Object-Centricity. On objects
+
+In SiSU objects are the fundamental unit from which larger constructs within a
+document and the document itself is built. Breaking the document into objects
+provides interesting possibilities.
+
+Conceptually within SiSU, objects are the building blocks or individual units of
+construction of a document. Objects are usually blocks of text, the most common
+of which is the paragraph, other examples include: individual headings, tables,
+grouped text of various types, a code block is a single object however many
+lines it runs, whereas each verse in a poem is an object ... and as mentioned an
+object could also, for example, be an image. Objects can be formatted and placed
+as needed, providing flexibility and enabling multiple types of representation
+across disparate formats and text receptacle, examples including html, epub,
+latex (in the past mind-maps) and sql (populated at an object level, and thereby
+providing search with that degree of granularity).
+
+Additionally spine can hand over the parsed object model itself, as a PEG
+parsable text file (.ssp) or as an sqlite database, so that other programs may
+consume the document as an already parsed structure rather than parsing the
+markup again.
+
+2~ On objects sequence
+
+Sequence is what makes the numbering reproducible, the same source gives the
+same numbers on every run and in every format, and provides the basis of
+citation. This follows authorship, it is part of the definition of a document
+and how a document is written to convey meaning.
+
+2~ Object Numbers & Citation
+
+Most objects within a document are meant by the author to be a substantive part
+of the document and substantive objects are numbered for citation purposes.
+(Where an object is deemed by the author to be not substantive numbering may be
+turned off for that object). All such objects are numbered sequentially and can
+be referenced thereby for citation purposes. An object number is attached to the
+text, not to where the text happens to land, so it survives reformatting, a
+change of paper size, or a move to a format that has no pages at all.
+
+Object numbers provide the possibility of citing/locating text precisely across
+different document formats and different languages (assuming the document has
+been translated). For search it also makes it possible to identify precisely
+where search criteria is met within each document in the form of an index or to
+view those precise text objects before deciding which documents are of interest.
+Additionally the use of objects (and that objects are numbered) frees the
+possibility to represent the document in the manner considered most suitable to
+a specific document format whilst retaining its structural (and citation)
+integrity.
+
+To be clear (if obvious) page numbers provide none of this functionality.
+
+Object numbering suits published or finalised works, where it provides a fixed
+means of reference.
+
+2~ Characteristics (objects have properties and attributes)
+
+Objects have properties (and may have attributes). By properties I here refer to
+the fundamental type of object, be it a heading, a paragraph, table, verse etc.
+Attributes extend further and may include other things that one might wish to
+associate with the object (examples not necessarily currently available/
+implemented in SiSU might include, formatting whether it is indented, or
+metadata e.g. the associated language, or programming language for a code block).
+
+2~ Document structure (Headings provide document structure through the heading level property)
+
+The types of document of interest to SiSU have structure that is captured by the
+heading level property. Headings are individual objects like any other with the
+additional properties that (i) they may be regarded as containing the other
+objects following them sequentially (until the next heading of a similar or
+higher level), heading objects may include other headings (sub-headings), and
+
+(ii) that they have a hierarchy, the root "heading" being the document title. To
+allow documents of different structural shapes to be represented, headings fall
+into two bands. The upper band organises the document above the level at which
+text is written: the document root, which is its title, and beneath it part,
+subpart and subsubpart, which contain other headings rather than text of their
+own. The lower band heads substantive text: a chapter or segment level and up to
+three levels of sub-heading beneath it. The segment level is what output formats
+that divide a document into pieces, such as segmented html and epub, break on.
+
+2~ Notes
+
+Footnotes and endnotes marked up and written within the object to which they
+belong and remain part of it. They are not numbered in the object citation
+series: a note is reached through the object that references it, and carries its
+own number in a series of its own. There are several such series: a regular
+numbered series, unnumbered asterisked notes, and a numbered asterisked series
+for editorial notes.
+
+An output format may present a note where it is written, at the foot of a
+"page", or gathered with the others at the end of the document, linked in both
+directions. Where notes are gathered as endnotes the same note appears twice
+in the rendering; it remains one note, belonging to one object, and it is the
+object carrying it that is numbered and that is searched.
+
+In the document abstraction the gathered notes form a section of their own,
+prepared once for the formats that display them. Those objects take no object
+number and are excluded from the search database, where a note is indexed as
+part of the object it belongs to.
+
+2~ The Document Header
+
+SiSU documents have a header carrying document metadata, at a minimum the title
+and the author. The header may also carry processing instructions, telling the
+program how the document is to be treated: from which heading level to number
+headings automatically, words or phrases to be emphasised throughout, text
+substitutions to apply, where the document should be segmented/broken for output
+formats that are divided into parts.
+
+% In addition the document header may contain markup instruction (e.g. how to
+% identify headings within the document, in which case those headings need not
+% be found and treated accordingly).
+
+SiSU parsers have now been implemented in different programming paradigms and
+languages a couple of times, the chosen markup has been left unchanged though
+the document headers have been modified.
+
+2~ Document Collections
+
+Spine produces documents of uniform structure, carrying metadata, written to
+predictable output locations in the file system or in an sql database. This
+makes collection level work possible: metadata driven curation, producing author
+and topic indexes across the whole collection, and a single search database
+spanning every document in it and every object within each document.
+
+The markup described in the rest of this document is the means by which an
+author states the structure that all of this depends on.
+
+#+END_SRC
+
+*** document body
+
+#+NAME: spine_markup_sample_body_sisu_markup
+#+BEGIN_SRC text
 :B~ SiSU Markup
 ={ SiSU markup:test }
 
@@ -141,7 +313,7 @@ make:
 #+BEGIN_SRC text
 1~markup Introduction to SiSU Markup~{ From sometime after SiSU 0.58 it should be possible to describe SiSU markup using SiSU, which though not an original design goal is useful. }~
 
-2~ Summary
+2~ Markup Summary
 
 This is the D version of the program sisu on which the markup it uses is based.
 
@@ -197,7 +369,7 @@ A~ (level A [title])
   code block:tic syntax
 }
 
-structure rules (document heirarchy, heading levels):
+structure rules (document hierarchy, heading levels):
 
 there are two sets of heading levels ABCD (title & parts if any) and 1234
 (segment & subsegments if any)
@@ -352,7 +524,7 @@ date:
   modified: "2020-04-11"
 
 rights:
-  copyright: "Copyright (C) Ralph Amissah 2007, 2026"
+  copyright: "Ralph Amissah 2007, 2020, 2026"
   license: "AGPL 3 (part of SiSU Spine documentation)"
 
 classify:
@@ -473,7 +645,7 @@ make:
   bold: "Debian|SiSU" # [regular expression of words/phrases to be made bold]
   italics: "Linux|GPL|LaTeX|SQL" # [regular expression of words/phrases to italicise]
   breaks: "new=:B; break=1"
-  home_button_text: "{SiSU}https://sisudoc.org; {sources / git}https://git.sisudoc.org/projects/"
+  home_button_text: "{SiSU}https://sisudoc.org; {sources / git}https://git.sisudoc.org"
   footer: "{SiSU}https://sisudoc.org; {git}https://git.sisudoc.org"
   headings: text to match for each level
     (e.g. PART; Chapter; Section; Article; or another: none; BOOK|FIRST|SECOND; none; CHAPTER;)
@@ -1463,19 +1635,19 @@ 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.
+% 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