v5 v6: ao_composite, nested includes, .ssi (insert) can now include .ssi & .sst

* .ssm can contain/include .sst or .ssi
  .sst files can be processed independently, they do not contain other files
  .ssi files have been only insertions of text & are not processed independently
  but as part of an ssm
  change proposed:
  .ssm unchanged,
  .sst unchanged,
  .ssi as before, but can include .sst or .ssi, so:
  files are only insertions & are not processed independently but as part of an
  .ssm or another .ssi
  i.e. as before with the addition that it like a .ssm can contain/include
  .sst or .ssi
* requested feature, (Closes: #744408)
  User beware. In previous versions there has been a deliberate attempt to keep
  it easy to follow documents & not have to dig through different levels of
  includes, as this is more likely to lead to errors in markup.
  The idea of nested includes has not been attractive (messy for a document),
  however, this is now made possible, use with care
  * it is not as easy to see document structure at a glance, and structural
    errors may be introduced and will need to be taken care of (requiring
    document markup debugging)
  * allowing .ssi to also include other .ssi or .sst could lead to infinite
    recursion if an .ssi includes another which includes itself; stopping after
    an additional level of includes seems arbitrary, and possibly prone to error
    if you are dealing with many documents
* requires testing
* version bump, new behavior added to .ssi one of the 3 sisu filetypes

3 files changed, 70 insertions, 3 deletions

diff --git a/data/doc/sisu/CHANGELOG_v5 b/data/doc/sisu/CHANGELOG_v5
index ca6fecf2..a87629fa 100644
--- a/data/doc/sisu/CHANGELOG_v5
+++ b/data/doc/sisu/CHANGELOG_v5
@@ -42,6 +42,35 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_5.5.0.orig.tar.xz
   * auto name segment, extract "number" from heading, fix
   * check that all auto given number based seg names are unique
 
+* ao_composite, nested includes, .ssi (insert) can include .ssi & .sst
+~ .ssm can contain/include .sst or .ssi
+  .sst files can be processed independently, they do not contain other files
+  .ssi files have been only insertions of text & are not processed independently
+  but as part of an ssm
+  change proposed:
+  .ssm unchanged,
+  .sst unchanged,
+  .ssi as before, but can include .sst or .ssi, so:
+  files are only insertions & are not processed independently but as part of an
+  .ssm or another .ssi
+  i.e. as before with the addition that it like a .ssm can contain/include
+  .sst or .ssi
+~ requested feature, (Closes: #744408)
+  User beware. In previous versions there has been a deliberate attempt to keep
+  it easy to follow documents & not have to dig through different levels of
+  includes, as this is more likely to lead to errors in markup.
+  The idea of nested includes has not been attractive (messy for a document),
+  however, this is now made possible, use with care
+  ~ it is not as easy to see document structure at a glance, and structural
+    errors may be introduced and will need to be taken care of (requiring
+    document markup debugging)
+  ~ allowing .ssi to also include other .ssi or .sst could lead to infinite
+    recursion if an .ssi includes another which includes itself; stopping after
+    an additional level of includes seems arbitrary, and possibly prone to error
+    if you are dealing with many documents
+~ requires testing
+~ version bump, new behavior added to .ssi one of the 3 sisu filetypes
+
 %% 5.4.5.orig.tar.xz (2014-07-07:27/1)
 http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=log;h=refs/tags/sisu_5.4.5
 http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=log;h=refs/tags/debian/sisu_5.4.5-1
diff --git a/data/doc/sisu/CHANGELOG_v6 b/data/doc/sisu/CHANGELOG_v6
index a1e1de70..c4a7d1a9 100644
--- a/data/doc/sisu/CHANGELOG_v6
+++ b/data/doc/sisu/CHANGELOG_v6
@@ -32,6 +32,35 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_6.1.0.orig.tar.xz
   * auto name segment, extract "number" from heading, fix
   * check that all auto given number based seg names are unique
 
+* ao_composite, nested includes, .ssi (insert) can include .ssi & .sst
+~ .ssm can contain/include .sst or .ssi
+  .sst files can be processed independently, they do not contain other files
+  .ssi files have been only insertions of text & are not processed independently
+  but as part of an ssm
+  change proposed:
+  .ssm unchanged,
+  .sst unchanged,
+  .ssi as before, but can include .sst or .ssi, so:
+  files are only insertions & are not processed independently but as part of an
+  .ssm or another .ssi
+  i.e. as before with the addition that it like a .ssm can contain/include
+  .sst or .ssi
+~ requested feature, (Closes: #744408)
+  User beware. In previous versions there has been a deliberate attempt to keep
+  it easy to follow documents & not have to dig through different levels of
+  includes, as this is more likely to lead to errors in markup.
+  The idea of nested includes has not been attractive (messy for a document),
+  however, this is now made possible, use with care
+  ~ it is not as easy to see document structure at a glance, and structural
+    errors may be introduced and will need to be taken care of (requiring
+    document markup debugging)
+  ~ allowing .ssi to also include other .ssi or .sst could lead to infinite
+    recursion if an .ssi includes another which includes itself; stopping after
+    an additional level of includes seems arbitrary, and possibly prone to error
+    if you are dealing with many documents
+~ requires testing
+~ version bump, new behavior added to .ssi one of the 3 sisu filetypes
+
 %% 6.0.11.orig.tar.xz (2014-07-07:27/1)
 http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=log;h=refs/tags/sisu_6.0.11
 http://sources.sisudoc.org/gitweb/?p=code/sisu.git;a=log;h=refs/tags/debian/sisu_6.0.11-1
diff --git a/data/doc/sisu/sisu.org b/data/doc/sisu/sisu.org
index 265abda9..8800572d 100644
--- a/data/doc/sisu/sisu.org
+++ b/data/doc/sisu/sisu.org
@@ -2247,15 +2247,24 @@ consider,
 I have to date deliberately tried to keep it easy to follow documents & not have too much depth ...
 The idea of recursive includes is un-attractive (messy for a document)
 
-.ssm currently can contain .sst or .ssi
+.ssm currently can contain/include .sst or .ssi
 .sst files can be processed independently,
-.ssi files are only insertions & cannot
+.ssi files are only insertions & are not processed independently but as part of an ssm
+
+change proposed
+.ssm unchanged
+.sst unchanged
+.ssi as before, but can include .sst or .ssi, so:
+  files are only insertions & are not processed independently but as part of an .ssm or another .ssi
+  i.e. as before with the addition that it like a .ssm can contain/include .sst or .ssi
+
+this is pretty much as requested by wishlist 744408
 
 allowing .ssi to also include other .ssi or .sst could lead to recursive .ssi
-allowing .ssm to also include other .ssm .ssi or .sst could lead to recursive .ssm
 
 stopping after an additional level of includes seems arbitrary, and possibly prone to error if you are dealing with many documents
 
+***** Discard
 a possibility would be to have another file extension to flag the role of the file,
 .ssmi (not very attractive) might do it
 (providing visual cue signalling its role as both a master file and an insertion/included file that cannot be processed independently)