v6: ao, document markup structure check, skip processing file on major error

* with error message & text at location of failure

2 files changed, 79 insertions, 0 deletions

diff --git a/data/doc/sisu/CHANGELOG_v6 b/data/doc/sisu/CHANGELOG_v6
index d2bcea38..be37cbe6 100644
--- a/data/doc/sisu/CHANGELOG_v6
+++ b/data/doc/sisu/CHANGELOG_v6
@@ -28,6 +28,9 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_6.0.5.orig.tar.xz
   sisu_6.0.5.orig.tar.xz
   sisu_6.0.5-1.dsc
 
+* ao, document structure check, stop processing on major error
+  (with error message & text at location of failure)
+
 * ao_syntax, address possible manual use of url delimiters「」
 
 * composite, fix includes, provide extra newline after inserted comment
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 be6d7b9d..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