SiSU Markup

2. Introduction to SiSU Markup ¹

2.1. Summary

This is the D version of the program sisu on which the markup it uses is based.

SiSU source documents are plaintext (UTF-8) ² files

All paragraphs are separated by an empty line.

Markup is comprised of: *

●  at the top of a document, the document header made up of semantic meta-data about the document and if desired additional processing instructions (such an instruction to automatically number headings from a particular level down)

●  followed by the prepared substantive text of which the most important single characteristic is the markup of different heading levels, which define the primary outline of the document structure. Markup of substantive text includes:

●  heading levels defines document structure

●  text basic attributes, italics, bold etc.

●  grouped text (objects), which are to be treated differently, such as code blocks or poems.

●  footnotes/endnotes

●  linked text and images

●  paragraph actions, such as indent, bulleted, numbered-lists, etc.

2.2. Markup Rules, document structure and metadata requirements

minimal content/structure requirement, minimum being:

metadata

title: "SiSU Spine"
  subtitle: "Markup"

creator:
  author: "Amissah, Ralph"  

levels

A~ (level A [title])

1~ (at least one level 1 [segment/(chapter)])  

structure rules (document heirarchy, heading levels):

there are two sets of heading levels ABCD (title & parts if any) and 123 (segment & subsegments if any)

sisu has the fllowing levels (that may be described as document parts, headings and subheadings):

A~ [title (& author)]
   - document root, required once (== 1)
   - followed by part B~ or level 1~
   - often written in the form:
     A~ @title @creator
     where title and creator are taken from the document header

B~ [part]
   - part B is followed by a part C~ if there is one or level 1~

C~ [subpart]
   - part C is followed by a part D~ if there is one or level 1~

D~ [subsubpart]
   - part D is followed by level 1~

1~ [heading, segment (chapter)]
   - level 1 required at least once (>= 1)
   - is followed by level 2~ or
     by text which can then be followed
     - by more text or by levels 1~ or 2~ (or relevant part)
   - level 1 in html (and epub) is the basis of a document segment and in a book
     would correspond to a chapter

2~ [sub-heading]
   - followed by level 3~ or
   - by text which can then be followed
     by more text or by levels 1~, 2~ or 3~ (or relevant part)

3~ [sub-sub-heading]
   - followed by text which can be followed
     by more text or by levels 1~, 2~ or 3~ (or relevant part)  

Rules:

- level A~ is mandatory, it is the (document root and) title

- there can only be one document root == level/part A~

- 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),

- heading levels A~ B~ C~ D~ are followed by other heading levels rather
  than substantive text
  - which may be the subsequent sequential (alphabetic) heading part level
  - or a heading (segment) level 1~

- there must be at least one heading (segment) level 1~
  (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

- heading levels 1~ 2~ 3~ 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)  

2.3. Markup Examples

2.3.1. Online

Markup examples are available in the form of prepared texts that were written under creative commons license that permit re-publication.

There is of course this document, which is provided with the program and provides a cursory overview of sisu markup. Running sisu spine against it gives an overview of the output produced by the program.