diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-09-09 20:59:38 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-09-09 20:59:38 -0400 |
| commit | b2bcd9f6297b581f6b6db1d25e87e3c69c171894 (patch) | |
| tree | 48c96e3c17ab4fe6555fe6a33542adfd57b25013 /markup/pod-samples | |
| parent | homepage description touch (diff) | |
sisu_markup.sst modest update
Diffstat (limited to 'markup/pod-samples')
| -rw-r--r-- | markup/pod-samples/pod/sisu-manual/media/text/en/sisu_markup.sst | 483 |
1 files changed, 272 insertions, 211 deletions
diff --git a/markup/pod-samples/pod/sisu-manual/media/text/en/sisu_markup.sst b/markup/pod-samples/pod/sisu-manual/media/text/en/sisu_markup.sst index ae092ee..fc3aa3e 100644 --- a/markup/pod-samples/pod/sisu-manual/media/text/en/sisu_markup.sst +++ b/markup/pod-samples/pod/sisu-manual/media/text/en/sisu_markup.sst @@ -15,7 +15,7 @@ date: modified: "2012-10-03" rights: - copyright: "2007 Ralph Amissah" + copyright: "Ralph Amissah 2007" license: "GPL 3 (part of SiSU documentation)" classify: @@ -33,24 +33,17 @@ make: italics: "Linux|GPL|LaTeX|SQL" home_button_text: - "{doc-reform}https://doc-reform.org" - - "{sources / git}https://git.sisudoc.org/projects/" + - "{sources / git}https://git.sisudoc.org" - "{SiSU}https://sisudoc.org" footer: - "{SiSU}https://sisudoc.org" - - "{git}https://git.sisudoc.org/projects" - -# home_button_text: "{SiSU}https://sisudoc.org; {sources / git}https://git.sisudoc.org/projects/" -# footer: "{SiSU}https://sisudoc.org; {git}https://git.sisudoc.org/projects" -# substitute: "/[$]{2}[{]sisudoc[}]/,'www.sisudoc.org'" -# substitute: "/${sisudoc}/,'www.sisudoc.org'" -# substitute: [ "[$]{2}\\{sisudoc\\}", "www.sisudoc.org" ] -# home_button_image: "{won_benkler.png }https://cyber.law.harvard.edu/wealth_of_networks/Main_Page" + - "{git}https://git.sisudoc.org" :A~ @title-author-date :B~ SiSU Description -1~description 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 @@ -60,104 +53,152 @@ object level through an SQL database. Markup helps define (delineate) objects substantive objects being numbered sequentially by the program for object citation. -!_ Summary. +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 heirarchical value, +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 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. +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. -!_ Unpacking this a bit further. -SiSU as a concept independent of its markup language and the parsers that have -been implemented, is based on the following ideas: +2~ Object-Centricity. On objects -!_ 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. -!_ Objects are fundamental building blocks: 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 which include code blocks and verse within poems, -... 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 disperate formats and text recepticle, 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). - -!_ Sequential. Objects have sequence: -That objects have sequence, goes largely without saying, this follows -authorship, it is part of the definition of a document and how a document is -written to convey meaning. - -!_ Object Numbers & Citation. Substantive objects are numbered for citation purposes: +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. All such objects are numbered sequentially and can be -referenced thereby for citation purposes. 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 -in 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 wilst -retaining its structural (and citation) integrity). - -!_ Characteristics. Objects have properties and attributes: +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) +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) -!_ Document structure. Heading objects hold documents structure: -Heading objects hold documents structure through their 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 heirarchy, the root "heading" being the document title. \\ -A complication was intruduced to provide greater flexibility across document -output formats. Headings have two sets of levels, the level under which -substantive text occurs, this would be a chapter or segment level, and above -that in the heirarchy if needed are document section separators, book, section, -part. - -!_ Non-objects -Most but not all parts of a document are treated as objects. Notably footnotes -are not objects in themselves, rather belonging to the object from which they -are referenced, and following their own 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. - -!_ The Document Header. -SiSU document have headers which contain document metadata, at a minimum the -document title and author. 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) + +(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. -This is the core of sisu, beyond which there is more but largely in the form of -choices based on ... existing output formats and of implementation detail, -deciding what attributes of objects, or within objects should be supported, -extending markup to allow for the generation of book indexes from if tagging -provided. +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. 2~ Older Descriptions @@ -294,7 +335,7 @@ more up to date output format representations. 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. @@ -329,7 +370,8 @@ minimal content/structure requirement, minimum being: metadata ``` code -title: "SiSU Spine" +title: + main: "SiSU Spine" subtitle: "Markup" creator: @@ -349,9 +391,10 @@ 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 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): @@ -387,8 +430,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: @@ -397,11 +445,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 @@ -412,15 +462,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 @@ -480,7 +540,7 @@ date: modified: "2020-04-11" rights: - copyright: "Copyright (C) Ralph Amissah 2007, 2020" + copyright: "Ralph Amissah 2007, 2020, 2026" license: "AGPL 3 (part of SiSU Spine documentation)" classify: @@ -623,7 +683,6 @@ identifier: }code - code{ links: [ @@ -643,7 +702,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/gitweb/" + 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;) @@ -666,14 +725,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] @@ -681,21 +743,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{ @@ -705,7 +775,7 @@ code{ }code -2~ Font Attributes +2~ Text Face Attributes ={ SiSU markup:font attributes } !_ markup example: @@ -1324,33 +1394,24 @@ group{ group{ -The Road Not Taken Related Poem Content Details - -BY ROBERT FROST +Thoughts -Two roads diverged in a yellow wood, -And sorry I could not travel both -And be one traveler, long I stood -And looked down one as far as I could -To where it bent in the undergrowth; +by Myra Viola Wilds -Then took the other, as just as fair, -And having perhaps the better claim, -Because it was grassy and wanted wear; -Though as for that the passing there -Had worn them really about the same, +What kind of thoughts now, do you carry + In your travels day by day +Are they bright and lofty visions, + Or neglected, gone astray? -And both that morning equally lay -In leaves no step had trodden black. -Oh, I kept the first for another day! -Yet knowing how way leads on to way, -I doubted if I should ever come back. +Matters not how great in fancy, + Or what deeds of skill you’ve wrought; +Man, though high may be his station, + Is no better than his thoughts. -I shall be telling this with a sigh -Somewhere ages and ages hence: -Two roads diverged in a wood, and I— -I took the one less traveled by, -And that has made all the difference. +Catch your thoughts and hold them tightly, + Let each one an honor be; +Purge them, scourge them, burnish brightly, + Then in love set each one free. }group ={ output:group block markup example;SiSU markup output:group block (curly brace syntax) } @@ -1433,33 +1494,24 @@ block{ block{ -The Road Not Taken Related Poem Content Details - -BY ROBERT FROST +Thoughts -Two roads diverged in a yellow wood, -And sorry I could not travel both -And be one traveler, long I stood -And looked down one as far as I could -To where it bent in the undergrowth; +by Myra Viola Wilds -Then took the other, as just as fair, -And having perhaps the better claim, -Because it was grassy and wanted wear; -Though as for that the passing there -Had worn them really about the same, +What kind of thoughts now, do you carry + In your travels day by day +Are they bright and lofty visions, + Or neglected, gone astray? -And both that morning equally lay -In leaves no step had trodden black. -Oh, I kept the first for another day! -Yet knowing how way leads on to way, -I doubted if I should ever come back. +Matters not how great in fancy, + Or what deeds of skill you’ve wrought; +Man, though high may be his station, + Is no better than his thoughts. -I shall be telling this with a sigh -Somewhere ages and ages hence: -Two roads diverged in a wood, and I— -I took the one less traveled by, -And that has made all the difference. +Catch your thoughts and hold them tightly, + Let each one an honor be; +Purge them, scourge them, burnish brightly, + Then in love set each one free. }block ={ output:group block markup example;SiSU markup output:group block (curly brace syntax) } @@ -1542,33 +1594,24 @@ poem{ poem{ -*{The Road Not Taken}*~{ published in 1916 as the first poem in the collection Mountain Interval. }~ +*{Thoughts}*~{ https://poets.org/anthology/poems-public-domain }~ -by Robert Frost +by Myra Viola Wilds -Two roads diverged in a yellow wood, -And sorry I could not travel both -And be one traveler, long I stood -And looked down one as far as I could -To where it bent in the undergrowth; +What kind of thoughts now, do you carry + In your travels day by day +Are they bright and lofty visions, + Or neglected, gone astray? -Then took the other, as just as fair, -And having perhaps the better claim, -Because it was grassy and wanted wear; -Though as for that the passing there -Had worn them really about the same, +Matters not how great in fancy, + Or what deeds of skill you’ve wrought; +Man, though high may be his station, + Is no better than his thoughts. -And both that morning equally lay -In leaves no step had trodden black. -Oh, I kept the first for another day! -Yet knowing how way leads on to way, -I doubted if I should ever come back. - -I shall be telling this with a sigh -Somewhere ages and ages hence: -Two roads diverged in a wood, and I— -I took the one less traveled by, -And that has made all the difference. +Catch your thoughts and hold them tightly, + Let each one an honor be; +Purge them, scourge them, burnish brightly, + Then in love set each one free. }poem ={ output:group block markup example;SiSU markup output:group block (curly brace syntax) } @@ -1576,33 +1619,24 @@ And that has made all the difference. !_ tics delimiter, resulting group text output: ``` poem -!{The Road Not Taken}!~{ published in 1916 as the first poem in the collection Mountain Interval. }~ - -by Robert Frost - -Two roads diverged in a yellow wood, -And sorry I could not travel both -And be one traveler, long I stood -And looked down one as far as I could -To where it bent in the undergrowth; - -Then took the other, as just as fair, -And having perhaps the better claim, -Because it was grassy and wanted wear; -Though as for that the passing there -Had worn them really about the same, - -And both that morning equally lay -In leaves no step had trodden black. -Oh, I kept the first for another day! -Yet knowing how way leads on to way, -I doubted if I should ever come back. - -I shall be telling this with a sigh -Somewhere ages and ages hence: -Two roads diverged in a wood, and I— -I took the one less traveled by, -And that has made all the difference. +!{Thoughts}!~{ https://poets.org/anthology/poems-public-domain }~ + +by Myra Viola Wilds + +What kind of thoughts now, do you carry + In your travels day by day +Are they bright and lofty visions, + Or neglected, gone astray? + +Matters not how great in fancy, + Or what deeds of skill you’ve wrought; +Man, though high may be his station, + Is no better than his thoughts. + +Catch your thoughts and hold them tightly, + Let each one an honor be; +Purge them, scourge them, burnish brightly, + Then in love set each one free. ``` ={ output:group block markup example;SiSU markup output:group block (curly brace syntax) } @@ -1726,7 +1760,7 @@ code(number){ 3~ Tables ={ SiSU markup:tables;tables } -Tables may be prepared in two either of two forms +Tables may be prepared in either of two forms !_ markup example: @@ -1803,7 +1837,7 @@ Very active contributors*** | 0| 31| 190| 692| 1,6 No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000 No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000 -* Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month. +_* Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month. }code @@ -1820,7 +1854,7 @@ Very active contributors*** | 0| 31| 190| 692| 1,6 No. of English language articles| 25| 16,000| 101,000| 190,000| 320,000| 630,000 No. of articles, all languages | 25| 19,000| 138,000| 490,000| 862,000|1,600,000 -* Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month. +_* Contributed at least ten times; ** at least 5 times in last month; *** more than 100 times in last month. 2~ Additional breaks - linebreaks within objects, column and page-breaks ={ SiSU markup:breaks (page and line);breaks } @@ -1882,9 +1916,28 @@ code{ }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. @@ -1909,6 +1962,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 } @@ -2189,16 +2254,12 @@ which is convenient for editing. 1~ Substitutions ={ SiSU markup:substitutions;substitutions } -!_ markup example: +Configure substitution in _sisu/sisu_document_make code{ -The current Debian is ${debian_stable} the next debian will be ${debian_testing} - -Configure substitution in _sisu/sisu_document_make - -@make: - :substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*' +make: + substitute: /${debian_stable}/,'*{Wheezy}*' /${debian_testing}/,'*{Jessie}*' }code @@ -2285,7 +2346,7 @@ $$$ Difference?~{ puzzle away }~ -* !glossary +_* !glossary head @@ -2332,10 +2393,10 @@ document ... heading levels above the current heading level which it logically falls under and to which it belongs (headings preceding current level under which it occurs) -!_ decendants -decendant headings are sub-headings beneath the current heading level, heading +!_ descendants +descendant headings are sub-headings beneath the current heading level, heading levels below the current heading level which are derived from it and belong to -it (sub-headings contained beneath current level); decendant objects are the +it (sub-headings contained beneath current level); descendant objects are the range of objects contained by a heading (ocn ranges for each heading in document body) @@ -2359,7 +2420,7 @@ ordinary markup, with indication that section is to be treated as blurb certain forms of output are conveniently segmented, e.g. epub and segmented html. The document is broken into chunks indicated by markup level 1 heading (numeric level 4 headings) as the significant level at which the document should -be segmented, and including all decendant objects of that level. For a longer +be segmented, and including all descendant objects of that level. For a longer text/book this will usually the chapter level. (this is significant in e.g. for epub and segmented html, which are broken by segment, usually chosen to be chapter) |
