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

* with error message & text at location of failure

1 files changed, 81 insertions, 30 deletions

diff --git a/README b/README
index 303784c8..ef26c287 100644
--- a/README
+++ b/README
@@ -948,6 +948,75 @@ or if for a particular version:
 
   sisu --query-0.38
 
+MARKUP RULES, DOCUMENT STRUCTURE AND METADATA REQUIREMENTS
+..........................................................
+
+minimal content/structure requirement:
+
+[metadata]
+
+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:
+
+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~)
+
+
+* 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)
+
+
 MARKUP EXAMPLES
 ...............
 
@@ -2011,9 +2080,9 @@ 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 ╋ breaks the page, starts a new page.
+page new =\= breaks the page, starts a new page.
 
-page break -\- or ┼ breaks a column, starts a new column, if using columns,
+page break -\- 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
@@ -2022,19 +2091,11 @@ page break:
 
 -\\-
 
-or
-
-<:pb>
-
 
 page (break) new:
 
 =\\=
 
-or
-
-<:pn>
-
 
 page (break) line across page (dividing paragraphs):
 
@@ -2191,8 +2252,8 @@ Configure substitution in _sisu/sisu_document_make
 
 	Creator:  Ralph Amissah
 
-	Rights:  Copyright (C) Ralph Amissah 2014;\\ License: GPL 3 (part of SiSU
-               documentation)
+	Rights:  Copyright: Copyright (C) Ralph Amissah 2014 \\ License: GPL 3
+               (part of SiSU documentation)
 
 	Subject:  ebook, epublishing, electronic book, electronic publishing,
                electronic document, electronic citation, data structure,
@@ -2213,31 +2274,21 @@ Configure substitution in _sisu/sisu_document_make
 	Filetype:  SiSU text insert 5.0,
 
 	Source digest:  SHA256(README.ssm.sst)=
-               e9ee6379dcf3a05c2b0ae19f091f7e2b1579d7b8a683996a8c53eb57249497c4
+               e6badfab7c24f0b217e1ab3b2d8cebb70a7fa9f1a8af9f907f029aa19fca3e74
 
-	Generated by:  Generated by: SiSU 6.0.4 of 2014w06/5 (2014-02-14)
+	Generated by:  Generated by: SiSU 6.0.5 of 2014w15/3 (2014-04-16)
 
-	Ruby version:  ruby 2.1.0p0 (2013-12-25) [i386-linux-gnu]
+	Ruby version:  ruby 2.1.1p76 (2014-02-24) [i386-linux-gnu]
 
-	Document (ao) last generated:  2014-02-14 00:05:38 -0500
+	Document (ao) last generated:  2014-05-08 16:40:57 -0400
 
 ==============================================================================
 
 
 plaintext (plain text):
-   http://niu/manual/en/txt/README.txt
-
-Other versions of this document:
-
-manifest:
-   http://niu/manual/en/manifest/README.html
-
-at:
-   http://niu/manual
-
-
+   README
 
-* Generated by: SiSU 6.0.4 of 2014w06/5 (2014-02-14)
-* Ruby version: ruby 2.1.0p0 (2013-12-25) [i386-linux-gnu]
-* Last Generated on: 2014-02-14 00:05:39 -0500
+* Generated by: SiSU 6.0.5 of 2014w15/3 (2014-04-16)
+* Ruby version: ruby 2.1.1p76 (2014-02-24) [i386-linux-gnu]
+* Last Generated on: 2014-05-08 16:40:59 -0400
 * SiSU http://www.sisudoc.org/