v5: single document root A~ (recalibrate headings); level D~ possible

* :A~ document title, single document root (ln==0)
* introduce additional possible heading level, D~
* markup rule change: single document root
* breaks much downstream code, recalibrate (fix, test, fix & test again)
* v4 & v5 bifurcate (diverge "un-merge-ably")

1 files changed, 23 insertions, 4 deletions

diff --git a/data/doc/sisu/CHANGELOG_v5 b/data/doc/sisu/CHANGELOG_v5
index e359ad89..9e7547dd 100644
--- a/data/doc/sisu/CHANGELOG_v5
+++ b/data/doc/sisu/CHANGELOG_v5
@@ -33,10 +33,29 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_5.2.0.orig.tar.xz
   sisu_5.2.0.orig.tar.xz
   sisu_5.2.0-1.dsc
 
-* recalibrate heading levels A~ root 0, introduce possible D~
-  * downstream code consequences
-  * markup change of possibilities with possible (occasional) consequences
-  * v5 now diverges "un-merge-ably" from v4
+* single document root A~ (recalibrate headings); level D~ possible
+  * :A~ document title, single document root (ln==0)
+  * introduce additional possible heading level, D~
+  * markup rule change: single document root
+  * breaks much downstream code, recalibrate (fix, test, fix & test again)
+  * v4 & v5 bifurcate (diverge "un-merge-ably")
+
+  Notes, rule imposed: heading level A~ becomes, document title & sole document
+  root. Significant as an expressed rule/principle, it simplifies making certain
+  document formats in particular some xml outputs, however, this has been pretty
+  much the case in practice (most documents have this implicit structure) and
+  will affect the markup of very few documents (for example all markup examples
+  so far provided are this way). This being the case, it is a subtle change,
+  because it will not be noticed (by the user) in a majority of cases. The most
+  significant changes are to internal sisu code: it is not yet enforced by the
+  software (software checks); it has implications for the way document output is
+  created; it has implications for document structure regex matches, that now
+  are attached to levels starting below level A~ (from B~ down) rather than
+  level A. One document affected by single root/title level A~ markup rule and
+  that provides a short test (for a document prepared using document structure
+  regex matches), is the U.N. Convention on Contracts for the International Sale
+  of Goods (CISG) that requires levels A-D & 1, and in previous versions of sisu
+  exceptionally required multiple level A's (using levels A-C & 1)
 
 * bin/sisu
   * (ensure SiSU_version_dir) fix