0.11.0 improved message passing, using templates

1 files changed, 546 insertions, 240 deletions

diff --git a/org/sdp.org b/org/sdp.org
index f8734be..54a36a3 100644
--- a/org/sdp.org
+++ b/org/sdp.org
@@ -24,7 +24,7 @@ struct Version {
   int minor;
   int patch;
 }
-enum ver = Version(0, 10, 1);
+enum ver = Version(0, 11, 0);
 #+END_SRC
 
 ** TODO sdp src/sdp.d                                               :sdp.d:
@@ -87,18 +87,21 @@ unittest {
 #+BEGIN_SRC d
 /+ sdp: sisu document parser, see http://sisudoc.org +/
 import
-  compile_time_info,          // sdp/compile_time_info.d
-  ao_abstract_doc_source,     // sdp/ao_abstract_doc_source.d
-  ao_conf_make_meta,          // sdp/ao_conf_make_meta.d
-  ao_conf_make_meta_native,   // sdp/ao_conf_make_meta_native.d
-  ao_conf_make_meta_sdlang,   // sdp/ao_conf_make_meta_sdlang.d
-  ao_defaults,                // sdp/ao_defaults.d
-  ao_output_debugs,           // sdp/ao_output_debugs.d
-  ao_read_config_files,       // sdp/ao_read_config_files.d
-  ao_read_source_files,       // sdp/ao_read_source_files.d
-  ao_rgx,                     // sdp/ao_rgx.d
-  output_hub,                 // output_hub.d
-  output_html;                // output_html.d
+  compile_time_info,
+  ao_abstract_doc_source,
+  ao_conf_make_meta,
+  ao_conf_make_meta_native,
+  ao_conf_make_meta_sdlang,
+  ao_defaults,
+  ao_output_debugs,
+  ao_read_config_files,
+  ao_read_source_files,
+  ao_rgx,
+  output_hub,
+  output_epub,
+  output_html,
+  output_xhtmls,
+  source_sisupod;
 #+END_SRC
 
 ***** notes
@@ -156,6 +159,7 @@ private import
   std.process,
   std.stdio,
   std.file,
+  std.path,
   std.range,
   std.regex,
   std.string,
@@ -258,13 +262,15 @@ look into using getopt
 
 #+NAME: sdp_args
 #+BEGIN_SRC d
-bool[string] opt_action_bool = [
+bool[string] _opt_action_bool = [
   "assertions"         : false,
   "concordance"        : false,
   "digest"             : false,
   "docbook"            : false,
   "epub"               : false,
   "html"               : false,
+  "html_seg"           : false,
+  "html_scroll"        : false,
   "manifest"           : false,
   "ocn"                : true,
   "odt"                : false,
@@ -291,38 +297,40 @@ bool[string] opt_action_bool = [
 ];
 auto helpInfo = getopt(args,
   std.getopt.config.passThrough,
-  "assert",             "--assert set optional assertions on",                        &opt_action_bool["assertions"],
-  "concordance",        "--concordance file for document",                            &opt_action_bool["concordance"],
-  "digest",             "--digest hash digest for each object",                       &opt_action_bool["digest"],
-  "docbook",            "--docbook process docbook output",                           &opt_action_bool["docbook"],
-  "epub",               "--epub process epub output",                                 &opt_action_bool["epub"],
-  "html",               "--html process html output",                                 &opt_action_bool["html"],
-  "manifest",           "--manifest process manifest output",                         &opt_action_bool["manifest"],
-  "ocn",                "--ocn object cite numbers (default)",                        &opt_action_bool["ocn"],
-  "odf",                "--odf process odf:odt output",                               &opt_action_bool["odt"],
-  "odt",                "--odt process odf:odt output",                               &opt_action_bool["odt"],
-  "pdf",                "--pdf process pdf output",                                   &opt_action_bool["pdf"],
-  "pg",                 "--pg process postgresql output",                             &opt_action_bool["postgresql"],
-  "postgresql",         "--postgresql process postgresql output",                     &opt_action_bool["postgresql"],
-  "qrcode",             "--qrcode with document metadata",                            &opt_action_bool["qrcode"],
-  "sisupod",            "--sisupod sisupod source content bundled",                   &opt_action_bool["sisupod"],
-  "source",             "--source markup source text content",                        &opt_action_bool["source"],
-  "sqlite",             "--sqlite process sqlite output",                             &opt_action_bool["sqlite"],
-  "text",               "--text process text output",                                 &opt_action_bool["text"],
-  "txt",                "--txt process text output",                                  &opt_action_bool["text"],
-  "verbose|v",          "--verbose output to terminal",                               &opt_action_bool["verbose"],
-  "xhtml",              "--xhtml process xhtml output",                               &opt_action_bool["xhtml"],
-  "xml-dom",            "--xml-dom process xml dom output",                           &opt_action_bool["xml_dom"],
-  "xml-sax",            "--xml-sax process xml sax output",                           &opt_action_bool["xml_sax"],
-  "section-toc",        "--section-toc process table of contents (default)",          &opt_action_bool["section_toc"],
-  "section-body",       "--section-body process document body (default)",             &opt_action_bool["section_body"],
-  "section-endnotes",   "--section-endnotes process document endnotes (default)",     &opt_action_bool["section_endnotes"],
-  "section-glossary",   "--section-glossary process document glossary (default)",     &opt_action_bool["section_glossary"],
-  "section-biblio",     "--section-biblio process document biblio (default)",         &opt_action_bool["section_biblio"],
-  "section-bookindex",  "--section-bookindex process document bookindex (default)",   &opt_action_bool["section_bookindex"],
-  "section-blurb",      "--section-blurb process document blurb (default)",           &opt_action_bool["section_blurb"],
-  "backmatter",         "--section-backmatter process document backmatter (default)", &opt_action_bool["backmatter"],
-  "skip_output",        "--skip-output",                                              &opt_action_bool["skip_output"],
+  "assert",             "--assert set optional assertions on",                        &_opt_action_bool["assertions"],
+  "concordance",        "--concordance file for document",                            &_opt_action_bool["concordance"],
+  "digest",             "--digest hash digest for each object",                       &_opt_action_bool["digest"],
+  "docbook",            "--docbook process docbook output",                           &_opt_action_bool["docbook"],
+  "epub",               "--epub process epub output",                                 &_opt_action_bool["epub"],
+  "html",               "--html process html output",                                 &_opt_action_bool["html"],
+  "html_seg",           "--html-seg process html output",                             &_opt_action_bool["html_seg"],
+  "html_scroll",        "--html-seg process html output",                             &_opt_action_bool["html_scroll"],
+  "manifest",           "--manifest process manifest output",                         &_opt_action_bool["manifest"],
+  "ocn",                "--ocn object cite numbers (default)",                        &_opt_action_bool["ocn"],
+  "odf",                "--odf process odf:odt output",                               &_opt_action_bool["odt"],
+  "odt",                "--odt process odf:odt output",                               &_opt_action_bool["odt"],
+  "pdf",                "--pdf process pdf output",                                   &_opt_action_bool["pdf"],
+  "pg",                 "--pg process postgresql output",                             &_opt_action_bool["postgresql"],
+  "postgresql",         "--postgresql process postgresql output",                     &_opt_action_bool["postgresql"],
+  "qrcode",             "--qrcode with document metadata",                            &_opt_action_bool["qrcode"],
+  "sisupod",            "--sisupod sisupod source content bundled",                   &_opt_action_bool["sisupod"],
+  "source",             "--source markup source text content",                        &_opt_action_bool["source"],
+  "sqlite",             "--sqlite process sqlite output",                             &_opt_action_bool["sqlite"],
+  "text",               "--text process text output",                                 &_opt_action_bool["text"],
+  "txt",                "--txt process text output",                                  &_opt_action_bool["text"],
+  "verbose|v",          "--verbose output to terminal",                               &_opt_action_bool["verbose"],
+  "xhtml",              "--xhtml process xhtml output",                               &_opt_action_bool["xhtml"],
+  "xml-dom",            "--xml-dom process xml dom output",                           &_opt_action_bool["xml_dom"],
+  "xml-sax",            "--xml-sax process xml sax output",                           &_opt_action_bool["xml_sax"],
+  "section-toc",        "--section-toc process table of contents (default)",          &_opt_action_bool["section_toc"],
+  "section-body",       "--section-body process document body (default)",             &_opt_action_bool["section_body"],
+  "section-endnotes",   "--section-endnotes process document endnotes (default)",     &_opt_action_bool["section_endnotes"],
+  "section-glossary",   "--section-glossary process document glossary (default)",     &_opt_action_bool["section_glossary"],
+  "section-biblio",     "--section-biblio process document biblio (default)",         &_opt_action_bool["section_biblio"],
+  "section-bookindex",  "--section-bookindex process document bookindex (default)",   &_opt_action_bool["section_bookindex"],
+  "section-blurb",      "--section-blurb process document blurb (default)",           &_opt_action_bool["section_blurb"],
+  "backmatter",         "--section-backmatter process document backmatter (default)", &_opt_action_bool["backmatter"],
+  "skip_output",        "--skip-output",                                              &_opt_action_bool["skip_output"],
 );
 if (helpInfo.helpWanted) {
   defaultGetoptPrinter("Some information about the program.", helpInfo.options);
@@ -380,7 +388,7 @@ enforce(
 );
 #+END_SRC
 
-**** [#A] read in raw file (using filename with path)             :file:read:
+**** _read in raw file_ (using filename with path)             :file:read:
 [[./ao_markup_source_raw.org][ao_markup_source_raw]]
 
 #+NAME: sdp_each_file_do_read_sisu_markup_file
@@ -389,7 +397,7 @@ enforce(
 auto read_in_file_string = raw.sourceContent(fn_src);
 #+END_SRC
 
-**** [#A] split raw content file into: doc header & doc content   :file:read:
+**** split raw content file into: _doc header & doc content_   :file:read:
 
 #+NAME: sdp_each_file_do_split_sisu_markup_file_content_into_header_and_body
 #+BEGIN_SRC d
@@ -404,101 +412,125 @@ debug(header_and_body) {
 }
 #+END_SRC
 
-**** [#A] split doc header into: metadata & make   :doc:header:metadata:make:
+**** split doc header into: _metadata & make_ :doc:header:metadata:make:
 
 #+NAME: sdp_each_file_do_split_sisu_markup_file_header_into_make_and_meta
 #+BEGIN_SRC d
 /+ ↓ split header into make and meta +/
 auto header_make_and_meta_tuple = head.headerContentAA(header, conf_doc_make_aa);
 static assert(!isTypeTuple!(header_make_and_meta_tuple));
-string[string][string] dochead_make = header_make_and_meta_tuple[0];
-string[string][string] dochead_meta = header_make_and_meta_tuple[1];
+string[string][string] _dochead_make = header_make_and_meta_tuple[0];
+string[string][string] _dochead_meta = header_make_and_meta_tuple[1];
 #+END_SRC
 
-**** [#A] processing: document abstraction, tuple                :processing:
+**** [#A] processing: _document abstraction, tuple_           :processing:
 
 #+NAME: sdp_each_file_do_document_abstraction
 #+BEGIN_SRC d
 /+ ↓ document abstraction: process document, return abstraction as tuple +/
-auto t = abs.abstract_doc_source(content_body, dochead_make, dochead_meta, opt_action_bool);
+auto t = abs.abstract_doc_source(content_body, _dochead_make, _dochead_meta, _opt_action_bool);
 static assert(!isTypeTuple!(t));
-auto doc_ao_contents = t[0]; // head ~ toc ~ contents ~ endnotes_seg ~ glossary ~ bibliography ~ bookindex ~blurb;
-auto doc_html_segnames = t[1];
+auto doc_abstraction = t[0]; // head ~ toc ~ contents ~ endnotes_seg ~ glossary ~ bibliography ~ bookindex ~blurb;
+string[] doc_html_segnames = t[1];
 #+END_SRC
 
-**** document section keys view
+**** document _section keys_ sequence
 
 #+NAME: sdp_each_file_do_document_abstraction
 #+BEGIN_SRC d
 string[][string] document_section_keys_sequenced = [
-  "seg": ["head", "toc_seg", "body",],
+  "seg":    ["head", "toc_seg", "body",],
   "scroll": ["head", "toc_scroll", "body",]
 ];
-if (doc_ao_contents["endnotes_seg"].length > 1) {
-  document_section_keys_sequenced["seg"] ~= "endnotes_seg";
+if (doc_abstraction["endnotes"].length > 1) {
+  document_section_keys_sequenced["seg"]    ~= "endnotes";
+  document_section_keys_sequenced["scroll"] ~= "endnotes";
 }
-if (doc_ao_contents["endnotes_scroll"].length > 1) {
-  document_section_keys_sequenced["scroll"] ~= "endnotes_scroll";
-}
-if (doc_ao_contents["glossary"].length > 1) {
-  document_section_keys_sequenced["seg"] ~= "glossary";
+if (doc_abstraction["glossary"].length > 1) {
+  document_section_keys_sequenced["seg"]    ~= "glossary";
   document_section_keys_sequenced["scroll"] ~= "glossary";
 }
-if (doc_ao_contents["bibliography"].length > 1) {
-  document_section_keys_sequenced["seg"] ~= "bibliography";
+if (doc_abstraction["bibliography"].length > 1) {
+  document_section_keys_sequenced["seg"]    ~= "bibliography";
   document_section_keys_sequenced["scroll"] ~= "bibliography";
 }
-if (doc_ao_contents["bookindex_seg"].length > 1) {
-  document_section_keys_sequenced["seg"] ~= "bookindex_seg";
+if (doc_abstraction["bookindex_seg"].length > 1) {
+  document_section_keys_sequenced["seg"]    ~= "bookindex_seg";
 }
-if (doc_ao_contents["bookindex_scroll"].length > 1) {
+if (doc_abstraction["bookindex_scroll"].length > 1) {
   document_section_keys_sequenced["scroll"] ~= "bookindex_scroll";
 }
-if (doc_ao_contents["blurb"].length > 1) {
-  document_section_keys_sequenced["seg"] ~= "blurb";
+if (doc_abstraction["blurb"].length > 1) {
+  document_section_keys_sequenced["seg"]    ~= "blurb";
   document_section_keys_sequenced["scroll"] ~= "blurb";
 }
-if ((opt_action_bool["html"])
-|| (opt_action_bool["html_scroll"])
-|| (opt_action_bool["html_seg"])
-|| (opt_action_bool["epub"])) {
-  document_section_keys_sequenced["seg"] ~= "tail";
+if ((_opt_action_bool["html"])
+|| (_opt_action_bool["html_scroll"])
+|| (_opt_action_bool["html_seg"])
+|| (_opt_action_bool["epub"])) {
+  document_section_keys_sequenced["seg"]    ~= "tail";
   document_section_keys_sequenced["scroll"] ~= "tail";
 }
 #+END_SRC
 
-**** TODO debug (document parts, checkdoc)                   :debug:checkdoc:
+**** [#A] _document matters_
+#+NAME: sdp_each_file_do_document_abstraction
+#+BEGIN_SRC d
+struct DocumentMatters {
+  string[] keys_seq_seg() {
+    string[] _k = document_section_keys_sequenced["seg"];
+    return _k;
+  }
+  string[] keys_seq_scroll() {
+    string[] _k = document_section_keys_sequenced["scroll"];
+    return _k;
+  }
+  string[] segnames() {
+    string[] _k = doc_html_segnames;
+    return _k;
+  }
+  auto dochead_make() {
+    string[string][string] _k = _dochead_make;
+    return _k;
+  }
+  auto dochead_meta() {
+    string[string][string] _k = _dochead_meta;
+    return _k;
+  }
+  auto source_filename() {
+    string _k = fn_src;
+    return _k;
+  }
+  auto opt_action_bool() {
+    bool[string] _k = _opt_action_bool;
+    return _k;
+  }
+}
+auto doc_matters = DocumentMatters();
+#+END_SRC
+
+**** TODO _debug_ (document parts, checkdoc)              :debug:checkdoc:
 
 #+NAME: sdp_each_file_do_debugs_checkdoc
 #+BEGIN_SRC d
 /+ ↓ debugs +/
 debug(checkdoc) {
   dbg.abstract_doc_source_debugs(
-    doc_ao_contents,
-    document_section_keys_sequenced,
-    doc_html_segnames,
-    dochead_make,
-    dochead_meta,
-    fn_src,
-    opt_action_bool
+    doc_abstraction,
+    doc_matters,
   );
 }
 #+END_SRC
 
-**** TODO process outputs                                           :outputs:
+**** TODO _process outputs_                                      :outputs:
 
 #+NAME: sdp_each_file_do_selected_output
 #+BEGIN_SRC d
 /+ ↓ output hub +/
-if (!(opt_action_bool["skip_output"])) {
+if (!(_opt_action_bool["skip_output"])) {
   output.hub(
-    doc_ao_contents,
-    document_section_keys_sequenced,
-    doc_html_segnames,
-    dochead_make,
-    dochead_meta,
-    fn_src,
-    opt_action_bool
+    doc_abstraction,
+    doc_matters,
   );
 }
 #+END_SRC
@@ -516,7 +548,7 @@ scope(exit) {
   }
   destroy(content_body);
   destroy(t);
-  destroy(doc_ao_contents);
+  destroy(doc_abstraction);
   destroy(doc_html_segnames);
   destroy(fn_src);
 }
@@ -531,8 +563,10 @@ break;
 #+END_SRC
 
 * Notes
-** directory structure, program file arrangement
+** directory structure
+*** program file arrangement
 
+#+BEGIN_SRC shell
 ├── src
 │   ├── sdp.d
 │   └── sdp
@@ -550,167 +584,456 @@ break;
 │   └── sdp.d
 ├── views
 │   └── version.txt
+#+END_SRC
 
-** TODO work on
-*** program dir structure
-figure out best program dir structure for dub and compilers, issue with rdmd
-
-*** sisu document structure
-
-|---------------------+------------------------------------------+------------------------+------------------------+--------|
-|                     |                                          |                        | links                  |        |
-|---------------------+------------------------------------------+------------------------+------------------------+--------|
-| header              | sisu /header markup/                       | markup                 |                        |        |
-| - metadata          |                                          |                        |                        |        |
-| - make instructions |                                          |                        |                        |        |
-|---------------------+------------------------------------------+------------------------+------------------------+--------|
-| table of contents   | markup of headings                       | (regular content)      | scroll  #[ocn]         | output |
-|                     |                                          |                        | seg     ../[fn]/#[ocn] |        |
-|---------------------+------------------------------------------+------------------------+------------------------+--------|
-| substantive content | sisu /content markup/                      | markup                 | internal               | output |
-|                     | headings (providing document structure), |                        | scroll  #[ocn]         |        |
-|                     | paragraphs, blocks                       | (regular content)      | seg     ../[fn]/#[ocn] |        |
-|                     | blocks (code, poem, group, table)        |                        | footnotes              |        |
-|                     |                                          |                        | seg     #[ocn]         |        |
-|---------------------+------------------------------------------+------------------------+------------------------+--------|
-| endnotes            | markup within substantive content        | markup                 | scroll  #[ocn]         | output |
-|                     | (extracted from sisu /content markup/)     | (from regular content) | seg     ../[fn]/#[ocn] |        |
-|                     |                                          |                        | crosslinks             |        |
-|---------------------+------------------------------------------+------------------------+------------------------+--------|
-| glossary            | identify special section                 | markup                 |                        | output |
-|                     | regular /content markup/                   |                        |                        |        |
-|---------------------+------------------------------------------+------------------------+------------------------+--------|
-| bibliography        | identify section,                        | markup (special)       |                        | output |
-|                     | special /bibliography markup/              |                        |                        |        |
-|---------------------+------------------------------------------+------------------------+------------------------+--------|
-| book index          | extracted from markup attached to        | markup                 | scroll  #[ocn]         | output |
-|                     | related substantive content objects      |                        | seg     ../[fn]/#[ocn] |        |
-|                     | (special tags in sisu /content markup/)    | (from regular content) |                        |        |
-|---------------------+------------------------------------------+------------------------+------------------------+--------|
-| metadata            |                                          | (from regular header)  |                        | output |
-|---------------------+------------------------------------------+------------------------+------------------------+--------|
-
-- header
-
-- table of contents
-  - scroll            #[ocn]
-  - seg               ../[fn]/#[ocn]
-- substantive contents
-  contents
-  footnotes
-  - seg               #[ocn]
-  internal links
-  - scroll            #[ocn]
-  - seg               ../[fn]/#[ocn]
-- endnotes
-  - scroll
-  - seg               ../[fn]/#[ocn]
-- glossary
-- bibliography
-- book index
-  - scroll            #[ocn]
-  - seg               ../[fn]/#[ocn]
-- metadata
-
-*** config                                                         :config:
-using sdlang in sdp
-
-**** sdp config and header? file format? sdl ? yml ? json ?   :sdl:sdlang:
+*** markup files
 
-[[https://sdlang.org/][SDL: Simple Declarative Language]]  [[http://sdl4r.rubyforge.org/syntaxhighlighter_brush.html][highlighter]]
-https://github.com/Abscissa/SDLang-D
-https://github.com/Abscissa/SDLang-D/blob/master/HOWTO.md
+#+BEGIN_SRC shell
+#+END_SRC
 
-***** build/ compile
+*** source file bundles
 
-The recommended way to use SDLang-D is via DUB. Just add a dependency to
-sdlang-d in your project's dub.json or dub.sdl file as shown here. Then simply
-build your project with DUB as usual. dub dependency
-http://code.dlang.org/packages/sdlang-d
+#+BEGIN_SRC shell
+dir structure
+/tmp/_sisu_processing_/ralph/en/sisupod
+  ├── doc
+  │   └── en
+  └── image
+#+END_SRC
 
+*** src dir structure & files
+#+BEGIN_SRC txt :tangle no
+tree  /home/ralph/sisu_www/current/src/democratizing_innovation.eric_von_hippel.sst
 
-Alternatively, you can git clone both SDLang-D and the latest version of
-libInputVisitor,
+/home/ralph/sisu_www/current/src/
+democratizing_innovation.eric_von_hippel.sst
+└── sisupod
+    ├── doc
+    │   ├── en
+    │   │   └── democratizing_innovation.eric_von_hippel.sst
+    │   └── _sisu
+    │       └── sisu_document_make  // [interesting as part of larger conf.sdl]
+    └── image
+        ├── di_evh_f10-1.png
+        ├── di_evh_f11-1.png
+        ├── di_evh_f11-2.png
+        ├── di_evh_f1-1.png
+        ├── di_evh_f5-1.png
+        └── di_evh.png
 
-#+BEGIN_SRC d :tangle no
-dub fetch sdlang-d
-git clone https://github.com/Abscissa/SDLang-D
-git clone https://github.com/abscissa/libInputVisitor
 #+END_SRC
 
- and when running the compiler include:
 
-#+BEGIN_SRC d :tangle no
- -I{path to SDLang-D}/src -I{path to libInputVisitor}/src
+** document abstraction
+*** terminology / glossary
+
+- header
+  - document header, containing document specific
+    - (i) metadata information or
+    - (ii) make instructions
+
+- (document) structure
+  - relationship between headings and sub-headings, and the objects they
+    contain.
+  - Document structure is extracted from
+    - heading levels, which are either:
+      - explicitly marked up, or;
+      - determined from a make regex provided in the document header.
+    Use of document structure allow for the meaningful representation of
+    documents in alternative ways and the use of ocn permits easy reference
+    across different output formats.
+
+- heading
+  - document heading, each heading is marked indicating its level (in relation
+    to other headings), and this is used as basis for determininge document
+    structure. There are 8 levels, which are can be distinguesed as being one of
+    three types: (i) 1 title level (marked up A or numeric 0); (ii) 3 optional
+    document division levels, above text separating headings (marked up B - D,
+    or numeric 1 to 3); (iii) 4 text headings (marked up 1 - 4, or numeric 4
+    to 7)
+
+- levels == heading levels
+  - document heading level, see heading and structure
+
+- marked up headings / mark up level
+
+- collapsed headings / collapsed levels
+
+- numeric levels
+
+- dummy heading
+  - a markup level 1 / dummy level 4 that does not exist in the original text
+    that is manually inserted to maintain the documents structure rule that text
+    follows a heading of markup level 1 (rather than A to D) (numeric level 4
+    rather than 0 to 3)
+
+- relatives? relations
+  - ancestors
+    - headings preceding current level under which it occurs
+  - decendants
+    - sub-headings contained beneath current level
+    - range of objects contained by a heading (ocn ranges for each heading in document body)
+  see ancestors and decendants
+
+- document ...
+
+- ancestors
+  - heading levels above the current heading level which it logically falls
+    under and to which it belongs (headings preceding current level under which
+    it occurs)
+
+- decendants
+  - decendant headings are sub-headings beneath the current heading level,
+    heading levels below the current heading level which are derived from it and
+    belong to it (sub-headings contained beneath current level); decendant
+    objects are the range of objects contained by a heading (ocn ranges for each
+    heading in document body)
+
+- (document) sections
+  - a document can be divided into 3 parts: front; body and; back. Front matter
+    includes the table of contents (which is generated from headings) and any
+    parts of the document that are presented before the document body (this
+    might include a copyright notice for example). The document body, the
+    substantive part of the document, all its substantive objects, including:
+    headings, paragraphs, tables, verse etc. This is followed by optional
+    backmatter: endnotes, generated from inline markup; glossary, from section
+    using a subset of regular markup, with an indication that section is to be
+    treated as glossary. Note two things glossary might do that it does not,
+    there is: no automatic (sorting) alphabetisation of listing; no creation of
+    term anchor tags (perhaps it should); bibliography, created from a specially
+    marked up section, with indication that section is to be treated as
+    bibliography; bookindex generated from dedicated markup appended to objects
+    providing index terms and the relevant range; blurb made up of ordinary
+    markup, with indication that section is to be treated as blurb
+
+|-----------------------+------------------------------------------+------------------------+--------|
+| _header_                |                                          |                        |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| - metadata            | sisu /header markup/                       | markup                 |        |
+| - make instructions   |                                          |                        |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| _front matter_          |                                          |                        |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| - table of contents   | markup of headings                       | (regular content)      | output |
+|-----------------------+------------------------------------------+------------------------+--------|
+| _body_                  |                                          |                        |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| - substantive content | sisu /content markup/                      | markup                 | output |
+|                       | headings (providing document structure), | (regular content)      |        |
+|                       | paragraphs, blocks                       |                        |        |
+|                       | blocks (code, poem, group, table)        |                        |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| _backmatter_            |                                          |                        |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| - endnotes            | markup within substantive content        | markup                 | output |
+|                       | (extracted from sisu /content markup/)     | (from regular content) |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| - glossary            | identify special section                 | markup                 | output |
+|                       | regular /content markup/                   |                        |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| - bibliography        | identify section,                        | markup (special)       | output |
+|                       | special /bibliography markup/              |                        |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| - book index          | extracted from markup attached to        | markup                 | output |
+|                       | related substantive content objects      |                        |        |
+|                       | (special tags in sisu /content markup/)    | (from regular content) |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| - blurb               |                                          |                        |        |
+|-----------------------+------------------------------------------+------------------------+--------|
+| - metadata            |                                          | (from regular header)  | output |
+|-----------------------+------------------------------------------+------------------------+--------|
+
+- segment, segmented text
+  - certain forms of output are conveniently segmented, e.g. epub and segmented
+    html. The document is broken into chunks indicated by markup level 1 heading
+    (numeric level 4 headings) as the significant level at which the document
+    should be segmented, and including all decendant objects of that level. For
+    a longer text/book this will usually the chapter level. (this is significant
+    in e.g. for epub and segmented html, which are broken by segment, usually
+    chosen to be chapter)
+
+- scroll
+  - the document as a "scroll", e.g. as a single text file, or continuous html
+    document
+
+- object
+  - a unit of text. Objects include:
+    - headings;
+    - paragraphs;
+    - code blocks;
+    - grouped text;
+    - verse of poems;
+    - tables.
+  - Each substantive object is given an object number, that should make it citable.
+
+- ocn (object citation number / citation number)
+  - numbers assigned sequentially to each substantive object of a document.
+    - An ocn has the characteristic of remaining identical across output
+      formats.
+    - Translations should be prepared so number remains identical across objects
+      in different languages
+
+- citation number (see ocn / object citation number)
+
+- document abstraction (== internal representation) intermediate step,
+  - preprocessing of document, into abstraction / representation that is used by
+    all downstream processing, i.e. for all output formats. This allows
+    normalisation, reducing alternative markup options to common
+    representations, e.g. code blocks (open and close), tables, ways of
+    instructing that text be bold, shortuct way of providing and endnote
+    reference to a link
+
+- (document) internal representation (== document abstraction)
+  - see document abstraction
+
+- node representation
+
+- attribute (object attributes)
+  - when the document is abstracted attributes associated with an object, for
+    example for a:
+    - paragraph,
+      - indent (hang ... check & add),
+      - bulleted,
+    - code block,
+      - the language syntax,
+      - whether the block is numbered
+
+- inline markup
+  - when the document is abstracted, markup that remains embedded in the text,
+    such as its
+    - font face
+      - bold,
+      - italic,
+      -  emphasis,
+      -  underscore,
+      -  strike,
+      - superscript,
+      -  subscript,
+    - links,
+    - endnotes
+
+- sequential all objects backkeeping number?
+
+*** configuration (flies and command line)
+**** alternative config sources
+
+- ./_sisu/conf.sdl
+- ./_sisu/sisu_document_make
+- markup document header, make section
+- command line options
+
+**** conf.sdl
+(site wide make instruction contained in same file as site configuration file)
+
+#+BEGIN_SRC shell
+/*
+  name "SiSU sdl config"
+  author email="ralph@amissah.com"
+  description "site or directory wide environment defaults set here using sdlang see http://sdlang.org system environment info / resource configuration file, for sisu"
+  license "GPL v3 or later"
+    this file should be configured and live in
+      /etc/sisu     #per environment settings, overridden by:
+      ~/.sisu       #per user settings, overridden by:
+     ./_sisu/config #per local directory settings
+*/
+
+/* presentation/web directory, main path and subdirectories (most subdirectories are created automatically based on markup directory name) */
+// webserv \
+//   url_root      'http://www.sisudoc.org' // without dir stub, e.g. this dir would map to http://www.sisudoc.org/samples
+//   path          '~/sisu_www'             // /srv/www #either (i) / [full path from root] or (ii) ~/ [home] or (iii) ./ [pwd] or (iv) will be made from home
+//   #path         './tested'              // either (i) / [full path from root] or (ii) ~/ [home] or (iii) ./ [pwd] or (iv) will be made from home
+//   #images       'sisu/image'
+//   #man          'man'
+//   #cgi          '/usr/local/lib/sisu-cgi'
+// show_output_on  'filesystem'  // for -v and -u url information, alternatives: 'filesystem','webserver','remote_webserver','local:8111','localhost','localhost:8080','webrick','path'
+//// show_output_on 'filesystem_url'
+
+// webserv_cgi \
+//   host:         localhost
+//   base_path:    ~
+//   port:         '8081'
+//   user:         ~
+//   file_links:   www.sisudoc.org
+
+/* processing directories, main path and subdirectories */
+// processing \
+//  path=         "~" \
+//   dir=         "_sisu_processing~" \
+// //  metaverse=    'metaverse' \
+// //  tune=         'tune' \
+// //  latex=        'tex' \
+// //  texinfo=      'texinfo' \
+// //  concord_max=  400000
+
+/* output_dir_structure_by: language (language_and_filetype); filetype; or filename (original v1 & v2) */
+output_dir_structure_by "language"
+
+/* flag - set (non-default) processing flag shortcuts -1, -2 etc. (here adding color and verbosity as default)
+   making color default -c is toggle, and will now toggle color off */
+flag \
+  color= true \
+  act0=  "--digest --qrcode --text --html --epub --concordance --pdf --odf --docbook --xhtml --xml-sax --xml-dom --sqlite --manifest --verbose" \
+  act1=  "--digest --text --html --manifest" \
+  act2=  "--digest --text --html --epub --pdf --manifest" \
+  act3=  "--digest --qrcode --text --html --epub --concordance --pdf --manifest" \
+  act4=  "--digest --qrcode --text --html --epub --concordance --pdf --odf --docbook --manifest" \
+  act5=  "--digest --qrcode --text --html --epub --concordance --pdf --odf --docbook --sqlite --manifest" \
+  act6=  "--digest --qrcode --text --html --epub --concordance --pdf --odf --docbook --xhtml --xml-sax --xml-dom --sqlite --manifest" \
+  act7=  "--digest --qrcode --text --html --epub --concordance --pdf --odf --docbook --xhtml --xml-sax --xml-dom --sqlite --source --sisupod --manifest" \
+  act8=  "--digest --qrcode --text --html --epub --concordance --pdf --odf --docbook --xhtml --xml-sax --xml-dom --pg --update --manifest" \
+  act9=  "--digest --qrcode --text --html --epub --concordance --pdf --odf --docbook --xhtml --xml-sax --xml-dom --pg --update --source --sisupod --manifest"
+
+/* papersize, (LaTeX/pdf) available values: A4, US_letter, book_b5, book_a5, US_legal */
+default \
+  papersize=         "a4,letter" // 'a4,letter,b5,a5,legal'
+
+// texpdf_font       'Liberation Sans'
+// texpdf_font_sans  'Liberation Sans'
+// texpdf_font_serif 'Liberation Serif'
+// texpdf_font_mono  'Liberation Mono' #'Inconsolata'
+// text_wrap:        78
+// emphasis:         'bold' #make *{emphasis}* 'bold', 'italics' or 'underscore', default if not configured is 'bold'
+// language:         'fr'
+// language:         'en'
+// digest:           'sha' #sha is sha256, default is md5
+
+/* settings used by ssh scp */
+// remote \
+//   user         'ralph' \
+//   host         'www.sisudoc.org' \
+//   path         '/srv/www' // '/srv/sisudoc/web' // '.' #no trailing slash eg 'sisu/www'
+
+/* webrick information */
+
+/* sql database info, postgresql */
+// db
+//   engine
+//     default    'postgresql'
+// # share_source:  true
+//   postgresql \
+//     port       '5432' \
+//     user       'ralph' \\ '[provide username]'
+//     #host       'sisudoc.org'
+
+/* search */
+// search \
+//  sisu
+//    flag              false
+//    action            "http://www.sisudoc.org/cgi-bin/sisu_lng_pgsql.cgi"
+//   #action            "http://www.sisudoc.org/cgi-bin/sisu_pgsql.cgi"
+//   #action            "http://search.sisudoc.org"
+//     db               "current"
+//     title             'SiSU search form (sample)'
+// html
+//   minitoc             true
+// manifest
+//   minitoc             true
+make \
+  breaks="break=1" \
+  home_button_text="{SiSU}http://sisudoc.org; {sources / git}http://git.sisudoc.org/gitweb/"
+//  footer="{SiSU}http://sisudoc.org; {sources / git}http://git.sisudoc.org/gitweb/"
+//  home_button_image="{sisu.png }http://sisudoc.org"
+
+link "{SiSU}http://sisudoc.org"
+link "{sources / git}http://git.sisudoc.org/gitweb/"
 #+END_SRC
 
-***** Importing
+**** sisu_document_make
+(site wide make instruction)
 
-To use SDL, first import the module sdlang:
+sample
+#+BEGIN_SRC shell
+make \
+  breaks="break=1" \
+  home_button_text="{SiSU}http://sisudoc.org; {sources / git}http://git.sisudoc.org/gitweb/"
+//  footer="{SiSU}http://sisudoc.org; {sources / git}http://git.sisudoc.org/gitweb/" \
+//  home_button_text="{sisu.png }http://sisudoc.org" \
 
-#+BEGIN_SRC d :tangle no
-import sdlang;
+links \
+  link="{SiSU}http://sisudoc.org" \
+  link="{sources / git}http://git.sisudoc.org/gitweb/"
 #+END_SRC
 
-If you're not using DUB, then you must also include the path the SDLang-D sources when you compile:
+**** markup document header, make section
+(document specific make instructions)
 
-#+BEGIN_SRC d :tangle no
-rdmd --build-only -I{path to sdlang}/src -I{path to libInputVisitor}/src {other flags} yourProgram.d
-#+END_SRC
+sample
 
-***** misc
-http://forum.dlang.org/thread/hphtqkkmrfnlcipnxzai@forum.dlang.org
-http://forum.dlang.org/thread/gnfctbuhiemidetngrzi@forum.dlang.org?page=23#post-rlxlfveyyzgewhkxhhta:40forum.dlang.org
+#+BEGIN_SRC shell
+% SiSU 8.0
 
-**** other links
-http://semitwist.com/sdlang-d-docs/v0.9.3/sdlang.html  http://semitwist.com/sdlang-d-docs/
+title "The Wealth of Networks" \
+  sub="How Social Production Transforms Markets and Freedom" \
+  language="US"
 
-*** markup
-**** code
+creator \
+  author="Benkler, Yochai"
 
-#+BEGIN_SRC txt :tangle no
-code.ruby{
+date \
+  published="2006-04-03" \
+  created="2006-04-03" \
+  issued="2006-04-03" \
+  available="2006-04-03" \
+  modified="2006-04-03" \
+  valid="2006-04-03"
 
-}code
+rights \
+  copyright="Copyright (C) 2006 Yochai Benkler." \
+  license="All rights reserved. Subject to the exception immediately following, this book may not be reproduced, in whole or in part, including illustrations, in any form (beyond that copying permitted by Sections 107 and 108 of the U.S. Copyright Law and except by reviewers for the public press), without written permission from the publishers. http://creativecommons.org/licenses/by-nc-sa/2.5/ The author has made an online version of the book available under a Creative Commons Noncommercial Sharealike license; it can be accessed through the author's website at http://www.benkler.org."
 
-code.python{
+classify \
+  topic_register="SiSU markup sample:book:discourse;networks;Internet;intellectual property:patents|copyright;intellectual property:copyright:creative commons;economics;society;copyright;patents;book:subject:information society|information networks|economics|public policy|society|copyright|patents"
 
-}code
+make \
+  breaks="new=:B; break=1" \
+  home_button_image="{won_benkler.png }http://cyber.law.harvard.edu/wealth_of_networks/Main_Page" \
+  footer="{The Wealth of Networks}http://cyber.law.harvard.edu/wealth_of_networks/Main_Page; {Yochai Benkler}http://http://www.doctorow.com"
+#+END_SRC
 
-code.sh{
+**** hierarchy
 
-}code
+#+BEGIN_SRC text
+./.sisu ./_sisu ~/.sisu /etc/.sisu
+#+END_SRC
 
-code.txt{
+*** links
+**** internal
+**** configure
+site url base, needed e.g. for pdf documents that do not use relative links
 
-}code
+*** substitutions
+**** configure
+substitutions to occur within a document
 
-code.d{
+*** source
+**** sisupod
 
-}code
-#+END_SRC
+*** abstract document structure
 
-*** src dir structure & files
-#+BEGIN_SRC txt :tangle no
-tree  /home/ralph/sisu_www/current/src/democratizing_innovation.eric_von_hippel.sst
+** TODO work on
+*** sisu document structure
 
-/home/ralph/sisu_www/current/src/
-democratizing_innovation.eric_von_hippel.sst
-└── sisupod
-    ├── doc
-    │   ├── en
-    │   │   └── democratizing_innovation.eric_von_hippel.sst
-    │   └── _sisu
-    │       └── sisu_document_make  // [interesting as part of larger conf.sdl]
-    └── image
-        ├── di_evh_f10-1.png
-        ├── di_evh_f11-1.png
-        ├── di_evh_f11-2.png
-        ├── di_evh_f1-1.png
-        ├── di_evh_f5-1.png
-        └── di_evh.png
+- header
 
-#+END_SRC
+- table of contents
+  - scroll            #[ocn]
+  - seg               ../[fn]/#[ocn]
+- substantive contents
+  contents
+  footnotes
+  - seg               #[ocn]
+  internal links
+  - scroll            #[ocn]
+  - seg               ../[fn]/#[ocn]
+- endnotes
+  - scroll
+  - seg               ../[fn]/#[ocn]
+- glossary
+- bibliography
+- book index
+  - scroll            #[ocn]
+  - seg               ../[fn]/#[ocn]
+- metadata
 
 *** read markup files
 **** regular .sst
@@ -731,20 +1054,3 @@ or
   thrown away. At least the title and author information for each imported .sst
   file would have to read and available for use in its header A that is demoted
   to B
-
-*** processing files, currently using utf8
-*** check
-
-#+BEGIN_SRC text
-./.sisu ./_sisu ~/.sisu /etc/.sisu
-#+END_SRC
-
-#+BEGIN_SRC d
-/+
-writefln(
-  "pwd: %s; home: %s",
-  environment["PWD"],
-  environment["HOME"]
-);
-+/
-#+END_SRC