1 files changed, 78 insertions, 10 deletions
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
index fbd6d1f4..e3eefbac 100644
--- a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
+++ b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst
@@ -65,6 +65,82 @@ or if for a particular version:
 
 _1 sisu --query-0.38
 
+2~ Markup Rules, document structure and metadata requirements
+
+minimal content/structure requirement:
+
+[metadata]
+
+@title:
+
+@creator:
+
+[levels]
+
+``` code
+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:
+
+``` code
+A~ [title]              .
+   required (== 1)   followed by B~ or 1~
+B~ [part]               *
+   followed by C~ or 1~
+C~ [subpart]            *
+   followed by D~ or 1~
+D~ [subsubpart]         *
+   followed by 1~
+1~ [segment (chapter)]  +
+   required (>= 1)   followed by text or 2~
+text                    *
+   followed by more text or 1~, 2~
+   or relevant part *()
+2~ [subsegment]         *
+   followed by text or 3~
+text                    *
+   followed by more text or 1~, 2~ or 3~
+   or relevant part, see *()
+3~ [subsubsegment]      *
+   followed by text
+text                    *
+   followed by more text or 1~, 2~ or 3~ or relevant part, see *()
+
+*(B~ if none other used;
+  if C~ is last used: C~ or B~;
+  if D~ is used: D~, C~ or B~)
+```
+
+``` code
+* level A~ is the tile and is mandatory
+* there can only be one level A~
+* heading levels BCD, 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~ Markup Examples
 
 3~ Online
@@ -1168,9 +1244,9 @@ To draw a dividing line dividing paragraphs, see the section on page breaks.
 
 Page breaks are only relevant and honored in some output formats. A page break or a new page may be inserted manually using the following markup on a line on its own:
 
-page new =\\= or <:pn> breaks the page, starts a new page.
+page new =\\= (or <:pn>) breaks the page, starts a new page.
 
-page break -\\- or <:pb> breaks a column, starts a new column, if using columns, else breaks the page, starts a new page.
+page break -\\- (or <:pb>) breaks a column, starts a new column, if using columns, else breaks the page, starts a new page.
 
 page break line across page -..- draws a dividing line, dividing paragraphs
 
@@ -1180,10 +1256,6 @@ code{
 
 -\\-
 
-or
-
-<:pb>
-
 }code
 
 page (break) new:
@@ -1192,10 +1264,6 @@ code{
 
 =\\=
 
-or
-
-<:pn>
-
 }code
 
 page (break) line across page (dividing paragraphs):