.d files made, emacs org babel tangle run on .org files

12 files changed, 258 insertions, 194 deletions

diff --git a/lib/sdp/ao_abstract_doc_source.d b/lib/sdp/ao_abstract_doc_source.d
index 2fec35d..303011b 100644
--- a/lib/sdp/ao_abstract_doc_source.d
+++ b/lib/sdp/ao_abstract_doc_source.d
@@ -1,10 +1,12 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sisu_abstract_doc_source.d
+  document abstraction
+  ao_abstract_doc_source.d
 */
 mixin template SiSUdocAbstraction() {
   class Abstraction {
+  /* abstract marked up document */
     auto abstract_doc_source(char[][] markup_sourcefile_content) {
+      /* initialize */
       mixin ObjectSetters;
       mixin AssertionsOnMarkupDocumentStructure;
       mixin AssertionsOnBlocks;
@@ -134,6 +136,8 @@ mixin template SiSUdocAbstraction() {
       auto dochead_make = parseJSON(header_make_jsonstr).object;
       auto dochead_metadata = parseJSON(header_metadata_jsonstr).object;
       foreach (line; markup_sourcefile_content) {
+      /* loop markup document/text line by line */
+        /* scope */
         scope(exit) {
         }
         scope(failure) {
@@ -143,8 +147,11 @@ mixin template SiSUdocAbstraction() {
           writeln("  node: ", node);
         }
         line = replaceAll(line, rgx.true_dollar, "$$$$");
+          // dollar represented as $$ needed to stop submatching on $
+          // (substitutions using ${identifiers} must take into account (e.g. happen earlier))
         debug(source) {                                  // source lines
           writeln(line);
+          // writeln(scr_txt_marker["green"], line);
         }
         debug(srclines) {
           if (!line.empty) {                             // source lines, not empty
@@ -152,7 +159,9 @@ mixin template SiSUdocAbstraction() {
           }
         }
         if ((!line.empty) && (ft["ocn_status_multi_obj"] == 0)) {
+        /* not multi-line object, check whether ocn is on or turned off */
           if (match(line, rgx.ocn_block_marks)) {
+          /* switch off ocn */
             if (match(line, rgx.ocn_off_block)) {
               ft["ocn_status_multi_obj"] = 1;
               debug(ocnoff) {
@@ -189,6 +198,7 @@ mixin template SiSUdocAbstraction() {
           }
         }
         if (ft["code"] == 1) {
+        /* block object: code */
           if (ft["curly_code"] == 1) {
             if (auto m = match(line, rgx.block_curly_code_close)) {
               debug(code) {                              // code (curly) close
@@ -219,10 +229,12 @@ mixin template SiSUdocAbstraction() {
             }
           }
         } else if (!match(line, rgx.regular_parse_skip)) {
+        /* object other than code block object (includes regular text paragraph) */
           if (((match(line, rgx.heading_biblio)
           || (ft["heading_biblio"] == 1)))
           && (!match(line, rgx.heading))
           && (!match(line, rgx.comment))) {
+          /* within block object: biblio */
             if (match(line, rgx.heading_biblio)) {
               ft["heading_biblio"] = 1;
             }
@@ -303,6 +315,7 @@ mixin template SiSUdocAbstraction() {
               biblio_tag_entry="";
             }
           } else if (ft["poem"] == 1) {
+          /* within block object: poem */
             if (ft["curly_poem"] == 1) {
               if (auto m = match(line, rgx.block_curly_poem_close)) {
                 object["obj"]="verse"; // check that this is as you please
@@ -498,6 +511,7 @@ mixin template SiSUdocAbstraction() {
                 }
               }
             }
+          /* within block object: group */
           } else if (ft["group"] == 1) {
             if (ft["curly_group"] == 1) {
               if (auto m = match(line, rgx.block_curly_group_close)) {
@@ -529,6 +543,7 @@ mixin template SiSUdocAbstraction() {
               }
             }
           } else if (ft["block"] == 1) {
+          /* within block object: block */
             if (ft["curly_block"] == 1) {
               if (auto m = match(line, rgx.block_curly_block_close)) {
                 debug(block) {                           // block (curly) close
@@ -559,6 +574,7 @@ mixin template SiSUdocAbstraction() {
               }
             }
           } else if (ft["quote"] == 1) {
+          /* within block object: quote */
             if (ft["curly_quote"] == 1) {
               if (auto m = match(line, rgx.block_curly_quote_close)) {
                 debug(quote) {                           // quote (curly) close
@@ -589,6 +605,7 @@ mixin template SiSUdocAbstraction() {
               }
             }
           } else if (ft["table"] == 1) {
+          /* within block object: table */
             if (ft["curly_table"] == 1) {
               if (auto m = match(line, rgx.block_curly_table_close)) {
                 debug(table) {                           // table (curly) close
@@ -619,6 +636,7 @@ mixin template SiSUdocAbstraction() {
               }
             }
           } else {
+          /* not within a block group */
             assert(
               (ft["blocks"] == 0)
               || (ft["blocks"] == 2),
@@ -626,6 +644,7 @@ mixin template SiSUdocAbstraction() {
             );
             assertions_flag_types_block_status_none_or_closed(ft);
             if (auto m = match(line, rgx.block_curly_code_open)) {
+            /* curly code open */
               debug(code) {                              // code (curly) open
                 writeln(
                   scr_txt_color["blue"],
@@ -638,6 +657,7 @@ mixin template SiSUdocAbstraction() {
               ft["code"] = 1;
               ft["curly_code"] = 1;
             } else if (auto m = match(line, rgx.block_curly_poem_open)) {
+            /* curly poem open */
               object.remove("obj");
               object.remove("markup");
               object.remove("is");
@@ -658,6 +678,7 @@ mixin template SiSUdocAbstraction() {
               ft["poem"] = 1;
               ft["curly_poem"] = 1;
             } else if (auto m = match(line, rgx.block_curly_group_open)) {
+            /* curly group open */
               debug(group) {                             // group (curly) open
                 writeln(
                   scr_txt_color["blue"],
@@ -670,6 +691,7 @@ mixin template SiSUdocAbstraction() {
               ft["group"] = 1;
               ft["curly_group"] = 1;
             } else if (auto m = match(line, rgx.block_curly_block_open)) {
+            /* curly block open */
               debug(block) {                             // block (curly) open
                 writeln(
                   scr_txt_color["blue"],
@@ -682,6 +704,7 @@ mixin template SiSUdocAbstraction() {
               ft["block"] = 1;
               ft["curly_block"] = 1;
             } else if (auto m = match(line, rgx.block_curly_quote_open)) {
+            /* curly quote open */
               debug(quote) {                             // quote (curly) open
                 writeln(
                   scr_txt_color["blue"],
@@ -694,6 +717,7 @@ mixin template SiSUdocAbstraction() {
               ft["quote"] = 1;
               ft["curly_quote"] = 1;
             } else if (auto m = match(line, rgx.block_curly_table_open)) {
+            /* curly table open */
               debug(table) {                             // table (curly) open
                 writeln(
                   scr_txt_color["blue"],
@@ -706,6 +730,7 @@ mixin template SiSUdocAbstraction() {
               ft["table"] = 1;
               ft["curly_table"] = 1;
             } else if (auto m = match(line, rgx.block_tic_code_open)) {
+            /* tic code open */
               debug(code) {                              // code (tic) open
                 writeln(
                   scr_txt_color["blue"],
@@ -718,6 +743,7 @@ mixin template SiSUdocAbstraction() {
               ft["code"] = 1;
               ft["tic_code"] = 1;
             } else if (auto m = match(line, rgx.block_tic_poem_open)) {
+            /* tic poem open */
               object.remove("obj");
               object.remove("markup");
               object.remove("is");
@@ -738,6 +764,7 @@ mixin template SiSUdocAbstraction() {
               ft["poem"] = 1;
               ft["tic_poem"] = 1;
             } else if (auto m = match(line, rgx.block_tic_group_open)) {
+            /* tic group open */
               debug(group) {                             // group (tic) open
                 writeln(
                   scr_txt_color["blue"],
@@ -750,6 +777,7 @@ mixin template SiSUdocAbstraction() {
               ft["group"] = 1;
               ft["tic_group"] = 1;
             } else if (auto m = match(line, rgx.block_tic_block_open)) {
+            /* tic block open */
               debug(block) {                             // block (tic) open
                 writeln(
                   scr_txt_color["blue"],
@@ -762,6 +790,7 @@ mixin template SiSUdocAbstraction() {
               ft["block"] = 1;
               ft["tic_block"] = 1;
             } else if (auto m = match(line, rgx.block_tic_quote_open)) {
+            /* tic quote open */
               debug(quote) {                             // quote (tic) open
                 writeln(
                   scr_txt_color["blue"],
@@ -774,6 +803,7 @@ mixin template SiSUdocAbstraction() {
               ft["quote"] = 1;
               ft["tic_quote"] = 1;
             } else if (auto m = match(line, rgx.block_tic_table_open)) {
+            /* tic table open */
               debug(table) {                             // table (tic) open
                 writeln(
                   scr_txt_color["blue"],
@@ -786,6 +816,8 @@ mixin template SiSUdocAbstraction() {
               ft["table"] = 1;
               ft["tic_table"] = 1;
             } else if (!line.empty) {
+            /* line not empty */
+            /* non blocks (headers, paragraphs) & closed blocks */
               assert(
                 !line.empty,
                 "line tested, line not empty surely"
@@ -796,6 +828,7 @@ mixin template SiSUdocAbstraction() {
                 "code block status: none or closed"
               );
               if (ft["blocks"] == 2) {
+              // blocks closed, unless followed by book index
                 debug(check) {                           // block
                   writeln(__LINE__);
                   tell_l("red", line);
@@ -807,14 +840,17 @@ mixin template SiSUdocAbstraction() {
                 );
               }
               if (auto m = match(line, rgx.book_index)) {
+              /* match book_index */
                 debug(bookindexmatch) {                       // book index
                   writeln(
                     scr_txt_color["blue"], "* [bookindex] ", scr_txt_color["off"],
                     to!string(m.captures[1]), "\n"
                   );
+                  // writeln(scr_txt_marker["blue"], to!string(m.captures[1]), "\n");
                 }
                 object["bookindex"] = to!string(m.captures[1]);
               } else if (auto m = match(line, rgx.book_index_open))  {
+              /* match open book_index */
                 ft["book_index"] = 1;
                 book_idx_tmp = to!string(m.captures[1]);
                 debug(bookindexmatch) {                       // book index
@@ -826,6 +862,7 @@ mixin template SiSUdocAbstraction() {
                   );
                 }
               } else if (ft["book_index"] == 1 )  {
+              /* book_index flag set */
                 if (auto m = match(line, rgx.book_index_close))  {
                   ft["book_index"] = 0;
                   object["bookindex"] = book_idx_tmp ~ to!string(m.captures[1]);
@@ -842,7 +879,9 @@ mixin template SiSUdocAbstraction() {
                   book_idx_tmp ~= line;
                 }
               } else {
+              /* not book_index */
                 if (auto m = match(line, rgx.comment)) {
+                /* matched comment */
                   debug(comment) {
                     tell_l("blue", line);
                   }
@@ -866,6 +905,7 @@ mixin template SiSUdocAbstraction() {
                   ft["para"] = 0;
                   counter++;
                 } else if (auto m = match(line, rgx.header_make)) {
+                /* matched header_make */
                   debug(header1) {                          // header
                     tell_l("yellow", line);
                   }
@@ -877,6 +917,7 @@ mixin template SiSUdocAbstraction() {
                   line_occur["header_make"]++;
                   object["obj"] ~= line ~= "\n";
                 } else if (auto m = match(line, rgx.header_metadata)) {
+                /* matched header_metadata */
                   debug(header1) {                          // header
                     tell_l("yellow", line);
                   }
@@ -889,8 +930,10 @@ mixin template SiSUdocAbstraction() {
                   object["obj"] ~= line ~= "\n";
                 } else if (ft["header_make"] == 1
                 && (line_occur["header_make"] > 0)) {
+                /* header_make flag set */
                   if (auto m = match(line, rgx.header_sub)) {
-                    debug(header1) {                        // header sub
+                  /* sub-header */
+                    debug(header1) {
                       tell_l("yellow", line);
                     }
                     line_occur["header_make"]++;
@@ -898,8 +941,10 @@ mixin template SiSUdocAbstraction() {
                   }
                 } else if (ft["header_metadata"] == 1
                 && (line_occur["header_metadata"] > 0)) {
+                /* header_metadata flag set */
                   if (auto m = match(line, rgx.header_sub)) {
-                    debug(header1) {                        // header sub
+                  /* sub-header */
+                    debug(header1) {
                       tell_l("yellow", line);
                     }
                     line_occur["header_metadata"]++;
@@ -909,8 +954,10 @@ mixin template SiSUdocAbstraction() {
                 && (line_occur["heading"] == 0))
                 && ((ft["para"] == 0)
                 && (ft["heading"] == 0))) {
+                /* heading or para but neither flag nor line exists */
                   if ((to!string(dochead_make["make"]["headings"]).length > 2)
                   && (ft["make_headings"] == 0)) {
+                  /* headings found */
                     debug(headingsfound) {
                       writeln(dochead_make["make"]["headings"]);
                     }
@@ -979,6 +1026,7 @@ mixin template SiSUdocAbstraction() {
                   && (line_occur["heading"] == 0))
                   && ((ft["para"] == 0)
                   && (ft["heading"] == 0))) {
+                  /* heading make set */
                     if (match(line, rgx_h_B)) {
                       line = "B~ " ~ line;
                       debug(headingsfound) {
@@ -1023,6 +1071,7 @@ mixin template SiSUdocAbstraction() {
                     }
                   }
                   if (auto m = match(line, rgx.heading)) {
+                  /* heading match */
                     ft["heading"] = 1;
                     ft["header"] = 0;
                     ft["header_make"] = 0;
@@ -1145,6 +1194,7 @@ mixin template SiSUdocAbstraction() {
                       tell_l("yellow", strip(line));
                     }
                   } else if (line_occur["para"] == 0) {
+                  /* para matches */
                     if (auto m = match(line, rgx.para_indent)) {
                       debug(paraindent) {                    // para indent
                         tell_l("blue", line);
@@ -1191,25 +1241,31 @@ mixin template SiSUdocAbstraction() {
                     line_occur["para"]++;
                   }
                 } else if (line_occur["header_make"] > 0) {
-                  debug(header) {                          // para
+                /* header_make */
+                // should be caught by sub-header
+                  debug(header) {
                     tell_l("red", line);
                   }
                   object["obj"] ~= line ~= "\n";
                   line_occur["header_make"]++;
                 } else if (line_occur["header_metadata"] > 0) {
+                /* header_metadata */
+                // should be caught by sub-header
                   debug(header) {                          // para
                     tell_l("red", line);
                   }
                   object["obj"] ~= line ~= "\n";
                   line_occur["header_metadata"]++;
                 } else if (line_occur["heading"] > 0) {
+                /* heading */
                   debug(heading) {                         // heading
                     tell_l("blue", line);
                   }
                   object["obj"] ~= line ~= "\n";
                   line_occur["heading"]++;
                 } else if (line_occur["para"] > 0) {
-                  debug(para) {                            // para
+                /* paragraph */
+                  debug(para) {
                     tell_l("blue", line);
                   }
                   object["obj"] ~= line;
@@ -1217,6 +1273,7 @@ mixin template SiSUdocAbstraction() {
                 }
               }
             } else if (ft["blocks"] == 2) {
+            /* line empty, with blocks flag */
               assert(
                 line.empty,
                 "line should be empty"
@@ -1427,6 +1484,8 @@ mixin template SiSUdocAbstraction() {
                 ft["quote"] = 0;
               }
             } else {
+            /* line empty */
+              /* line.empty, post contents, empty variables: */
               assert(
                 line.empty,
                 "line should be empty"
@@ -1437,6 +1496,7 @@ mixin template SiSUdocAbstraction() {
               );
               if ((ft["header_make"] == 1)
               && (line_occur["header_make"] > 0)) {
+              /* header_make instructions (current line empty) */
                 auto dochead_metadata_and_make =
                   set_header.header_metadata_and_make_jsonstr(strip(object["obj"]), dochead_metadata, dochead_make);
                 static assert(!isTypeTuple!(dochead_metadata_and_make));
@@ -1457,6 +1517,7 @@ mixin template SiSUdocAbstraction() {
                 processing.remove("verse");
               } else if ((ft["header_metadata"] == 1)
               && (line_occur["header_metadata"] > 0)) {
+              /* header_metadata (current line empty) */
                 auto dochead_metadata_and_make =
                   set_header.header_metadata_and_make_jsonstr(strip(object["obj"]), dochead_metadata, dochead_make);
                 static assert(!isTypeTuple!(dochead_metadata_and_make));
@@ -1479,6 +1540,7 @@ mixin template SiSUdocAbstraction() {
                 processing.remove("verse");
               } else if ((ft["heading"] == 1)
               && (line_occur["heading"] > 0)) {
+              /* heading object (current line empty) */
                 ocn = ocn_emit(ft["ocn_status"]);
                 object["bookindex"] =
                   ("bookindex" in object) ? object["bookindex"] : "";
@@ -1508,6 +1570,7 @@ mixin template SiSUdocAbstraction() {
                     object["lvn"],
                     object["lcn"]
                   );
+                // track previous heading and make assertions
                 debug(objectrelated1) { // check
                   tell_l("blue", line);
                 }
@@ -1530,6 +1593,7 @@ mixin template SiSUdocAbstraction() {
                 processing.remove("verse");
                 counter++;
               } else if ((ft["para"] == 1) && (line_occur["para"] > 0)) {
+              /* paragraph object (current line empty) */
                 ocn = ocn_emit(ft["ocn_status"]);
                 object["bookindex"] =
                   ("bookindex" in object) ? object["bookindex"] : "";
@@ -1582,43 +1646,49 @@ mixin template SiSUdocAbstraction() {
                   line == null,
                   "line variable should be empty, should not occur"
                 );
+                // check what happens when paragraph separated by 2 newlines
               }
-            }
-          }
-        }
+            } // close else for line empty
+          } // close else for not the above
+        } // close after non code, other blocks or regular text
         if (((contents_arbitrary_max_length_set[counter-1]["is"] == "para")
         || (contents_arbitrary_max_length_set[counter-1]["is"] == "heading"))
         && (counter-1 > previous_count)) {
           if (match(contents_arbitrary_max_length_set[counter-1]["obj"],
           rgx.inline_notes_delimiter_al_regular_number_note)) {
+            // endnotes/ footnotes for
+            // doc objects other than paragraphs & headings
+            // various forms of grouped text
             previous_count=counter-1;
             notesection.gather_notes_for_endnote_section(contents_arbitrary_max_length_set, counter-1);
           }
         }
-      }
+      } // closed: loop markup document/text line by line
+      /* post loop markup document/text */
       debug(objectrelated2) { // check
           tell_l("blue", line);
       }
-/*
-  Backmatter:
-  * endnotes
-  * glossary
-  * references / bibliography
-  * book index
-*/
+      /*
+        Backmatter:
+        * endnotes
+        * glossary
+        * references / bibliography
+        * book index
+      */
       obj_im.obj_inline_markup("doc_end_reset", "");
       auto en_tuple = notesection.endnote_objects(ocn);
       static assert(!isTypeTuple!(en_tuple));
       auto endnotes = en_tuple[0];
       ocn = en_tuple[1];
-debug(endnotes) {
-  writeln(__LINE__, " ", endnotes.length);
-  foreach (n; endnotes) {
-    writeln(n);
-  }
-}
+      debug(endnotes) {
+        writeln(__LINE__, " ", endnotes.length);
+        foreach (n; endnotes) {
+          writeln(n);
+        }
+      }
       auto contents = contents_arbitrary_max_length_set[0..counter].dup;
       auto biblio_unsorted_incomplete = biblio_arr_json[0..count_biblio_entry].dup;
+      // destroy(biblio_arr_json);
       auto biblio = new Bibliography();
       auto biblio_ordered = biblio.bibliography(biblio_unsorted_incomplete);
       auto bi = new BookIndexReportSection();
@@ -1628,56 +1698,57 @@ debug(endnotes) {
       auto bookindex = bi_tuple[0];
       auto document = contents ~ endnotes ~ bookindex;
       ocn = bi_tuple[1];
-debug(bookindex) {                         // bookindex
-  foreach (bi_entry; bookindex) {
-    writeln(bi_entry["obj"]);
-  }
-}
-debug(heading) {                         // heading
-  string spc;
-  foreach (o; document) {
-    if (o["is"] == "heading") {
-      switch (o["lvn"]) {
-      case "0":
-        spc="";
-        break;
-      case "1":
-        spc="  ";
-        break;
-      case "2":
-        spc="    ";
-        break;
-      case "3":
-        spc="      ";
-        break;
-      case "4":
-        spc="        ";
-        break;
-      case "5":
-        spc="          ";
-        break;
-      case "6":
-        spc="            ";
-        break;
-      case "7":
-        spc="              ";
-        break;
-      case "8":
-        spc="                ";
-        break;
-      default:
-        spc="";
-        break;
+      debug(bookindex) {                         // bookindex
+        foreach (bi_entry; bookindex) {
+          writeln(bi_entry["obj"]);
+        }
+      }
+      debug(heading) {                         // heading
+        string spc;
+        foreach (o; document) {
+          if (o["is"] == "heading") {
+            switch (o["lvn"]) {
+            case "0":
+              spc="";
+              break;
+            case "1":
+              spc="  ";
+              break;
+            case "2":
+              spc="    ";
+              break;
+            case "3":
+              spc="      ";
+              break;
+            case "4":
+              spc="        ";
+              break;
+            case "5":
+              spc="          ";
+              break;
+            case "6":
+              spc="            ";
+              break;
+            case "7":
+              spc="              ";
+              break;
+            case "8":
+              spc="                ";
+              break;
+            default:
+              spc="";
+              break;
+            }
+            writeln(
+              spc, "* ", " ",
+              strip(o["obj"]),
+              "\n            ",
+              o["attrib"]
+            );
+            // tell_l("yellow", spc, strip(o["obj"]));
+          }
+        }
       }
-      writeln(
-        spc, "* ", " ",
-        strip(o["obj"]),
-        "\n            ",
-        o["attrib"]
-      );
-    }
-  }
-}
       destroy(contents);
       destroy(endnotes);
       destroy(bookindex);
diff --git a/lib/sdp/ao_assertions.d b/lib/sdp/ao_assertions.d
index 7cd1713..8cdbc87 100644
--- a/lib/sdp/ao_assertions.d
+++ b/lib/sdp/ao_assertions.d
@@ -1,6 +1,6 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sisu_assertions.d
+  assertions
+  ao_assertions.d
 */
 mixin template AssertionsOnMarkupDocumentStructure() {
   auto assertions_doc_structure(string[string] object, uint[string] lv) {
@@ -107,7 +107,7 @@ mixin template AssertionsOnMarkupDocumentStructure() {
         assert(lv["h5"] == 0);
         assert(lv["h6"] == 0);
         assert(lv["h7"] == 0);
-      } else {  // (lv["h0"] >0)
+      } else {
         assert(lv["h0"] == 0,"error should not enter level A a second time");
       }
       break;
@@ -219,4 +219,3 @@ mixin template AssertionsOnBlocks() {
       "block status: none or closed");
   }
 }
-
diff --git a/lib/sdp/ao_defaults.d b/lib/sdp/ao_defaults.d
index 8996587..6599e69 100644
--- a/lib/sdp/ao_defaults.d
+++ b/lib/sdp/ao_defaults.d
@@ -1,6 +1,6 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sisu_defaults.d
+  defaults
+  ao_defaults.d
 */
 template SiSUheader() {
   auto header_make_jsonstr = `{
@@ -75,7 +75,7 @@ template SiSUheader() {
     },
     "links": {
     }
-  }`; // links
+  }`;
   auto pointer_head_main =
     [
       "creator",
@@ -165,11 +165,8 @@ template SiSUheader() {
   auto config_jsonstr = `{
   }`;
 }
-/*
-* RgxInitFlags
-*/
+/* regex flags */
 template SiSUrgxInitFlags() {
-// mixin template RgxInit() {
   int[string] flag_type = [
     "make_headings"        : 0,
     "header_make"          : 0,
@@ -231,7 +228,7 @@ template SiSUbiblio() {
     "note"                             : "",
     "short_name"                       : "",
     "id"                               : ""
-  }`; // is: book, article, magazine, newspaper, blog, other
+  }`;
   auto biblio_tag_map = [
     "au"                               : "author_raw",
     "ed"                               : "editor_raw",
diff --git a/lib/sdp/ao_emitter.d b/lib/sdp/ao_emitter.d
index dd7103d..c9b1a7e 100644
--- a/lib/sdp/ao_emitter.d
+++ b/lib/sdp/ao_emitter.d
@@ -1,6 +1,6 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sisu_emitter.d
+  emitters
+  ao_emitters.d
 */
 mixin template Emitters() {
   mixin InternalMarkup;
@@ -420,7 +420,6 @@ mixin template Emitters() {
     }
   }
   class ObjAttrib : AssertObjAttrib {
-// auto sink = appender!(char[])();
     auto attrib = new ObjAttributes();
     string[string] obj_attrib;
     string obj_attributes(string obj_is_, string obj_raw, string node)
@@ -1027,6 +1026,9 @@ mixin template Emitters() {
       int counter
     )
     in {
+      // endnotes/ footnotes for
+      // doc objects other than paragraphs & headings
+      // various forms of grouped text
       assert((contents_arbitrary_max_length_set[counter]["is"] == "para")
       || (contents_arbitrary_max_length_set[counter]["is"] == "heading"));
       assert(counter > previous_count);
@@ -1150,6 +1152,9 @@ mixin template Emitters() {
       int count_biblio_entry;
       count_biblio_entry=0;
       foreach (bibent; biblio_unordered) {
+        // update bib to include deemed_author, needed for:
+        // sort_bibliography_array_by_deemed_author_year_title
+        // either: sort on multiple fields, or; create such sort field
         JSONValue j = parseJSON(bibent);
         if (!empty(j["fulltitle"].str)) {
           if (!empty(j["author_raw"].str)) {
diff --git a/lib/sdp/ao_interface.d b/lib/sdp/ao_interface.d
index 224603d..b50bee7 100644
--- a/lib/sdp/ao_interface.d
+++ b/lib/sdp/ao_interface.d
@@ -1,6 +1,6 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sisu_interface.d
+  interface
+  ao_interface.d
 */
 mixin template Interfaces() {
   interface AssertOCN {
@@ -142,4 +142,3 @@ mixin template Interfaces() {
     }
   }
 }
-
diff --git a/lib/sdp/ao_markup_source_raw.d b/lib/sdp/ao_markup_source_raw.d
index 3d937ac..fb76e98 100644
--- a/lib/sdp/ao_markup_source_raw.d
+++ b/lib/sdp/ao_markup_source_raw.d
@@ -1,6 +1,6 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sisu_markup_source_raw.d
+  markup source raw
+  ao_markup_source_raw.d
 */
 mixin template SiSUmarkupRaw() {
   class MarkupRaw {
@@ -11,12 +11,21 @@ mixin template SiSUmarkupRaw() {
         "file not found"
       );
       string source_txt_str;
-      if (exists(fn_src)) {
-        source_txt_str = readText(fn_src); // ok
-        std.utf.validate(source_txt_str);
+      try {
+        if (exists(fn_src)) {
+          source_txt_str = readText(fn_src); // ok
+        }
       }
-      // string source_txt_str = cast(string) read(fn_src);
-      // std.utf.validate(source_txt_str);
+      catch (ErrnoException ex) {
+        // Handle errors
+      }
+      catch (UTFException ex) {
+        // Handle validation errors
+      }
+      catch (FileException ex) {
+        // Handle errors
+      }
+      std.utf.validate(source_txt_str);
       return source_txt_str;
     }
     final private char[][] markupSourceLineArray(in string src_text) {
diff --git a/lib/sdp/ao_object_setter.d b/lib/sdp/ao_object_setter.d
index f2abd7f..ff76143 100644
--- a/lib/sdp/ao_object_setter.d
+++ b/lib/sdp/ao_object_setter.d
@@ -1,6 +1,6 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sisu_setter.d
+  object setter
+  ao_object_setter.d
 */
 mixin template ObjectSetters() {
   class ObjectAbstractSet {
diff --git a/lib/sdp/ao_output_debugs.d b/lib/sdp/ao_output_debugs.d
index 501d2a0..c6bdfe1 100644
--- a/lib/sdp/ao_output_debugs.d
+++ b/lib/sdp/ao_output_debugs.d
@@ -1,6 +1,6 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sdp_output_debugs.d
+  output debugs
+  ao_output_debugs.d
 */
 template SiSUoutputDebugs() {
   class SDPoutputDebugs {
@@ -331,15 +331,6 @@ template SiSUoutputDebugs() {
                 // fixed ERROR! range violation!
                 // error in bookindex ... (ch7 ... building the cc machine, an extra semi colon)
                 break;
-              // case ".sst":
-              //   assert(check["last_ocn"] == "0","last ocn should be: 0");
-              //   break;
-              // case ".sst":
-              //   assert(check["last_ocn"] == "0","last ocn should be: 0");
-              //   break;
-              // case ".sst":
-              //   assert(check["last_ocn"] == "0","last ocn should be: 0");
-              //   break;
               default:
                 writeln(fn_src);
                 break;
diff --git a/lib/sdp/ao_rgx.d b/lib/sdp/ao_rgx.d
index d8df52c..21101b5 100644
--- a/lib/sdp/ao_rgx.d
+++ b/lib/sdp/ao_rgx.d
@@ -1,12 +1,10 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sisu_rgx.d
+  regex
+  ao_rgx.d
 */
 mixin template RgxInit() {
-/*
-** misc
-*/
   class Rgx {
+    /* misc */
     static flag_action               = ctRegex!(`^(--[a-z][a-z0-9-]+)$`);
     static flag_action_str           = ctRegex!(` (--[a-z][a-z0-9-]+)`);
     static src_pth                   = ctRegex!(`^([a-zA-Z0-9._-]+/)*([a-zA-Z0-9._-]+[.]ss[tm])$`);
@@ -27,13 +25,9 @@ mixin template RgxInit() {
     static levels_markup             = ctRegex!(`^[A-D1-4]$`);
     static levels_numbered           = ctRegex!(`^[0-9]$`);
     static levels_numbered_headings  = ctRegex!(`^[0-7]$`);
-/*
-** insert markup file
-*/
+    /* insert markup file */
     static insert_src_fn_ssi_or_sst  = ctRegex!(`^<<\s*(?P<path>[a-zA-Z0-9._-]+/)*(?P<filename>[a-zA-Z0-9._-]+[.]ss[ti])$`);
-/*
-** header & comments
-*/
+    /* header & comments */
     static comment                   = ctRegex!(`^%+ `);
     static header                    = ctRegex!(`^@([a-z_]+):(?:\s|$)`);
     static header_make               = ctRegex!(`^@(make):(?:\s|$)`);
@@ -41,9 +35,7 @@ mixin template RgxInit() {
     static header_sub                = ctRegex!(`^[ ]+:([a-z_]+):\s`);
     static head_main                 = ctRegex!(`^@([a-z_]+):\s*(.*)`, "m");
     static head_sub                  = ctRegex!(`^[ ]*:([a-z_]+):\s+(.+)`, "m");
-/*
-** heading & paragraph operators
-*/
+    /* heading & paragraph operators */
     static heading            = ctRegex!(`^:?([A-D1-4])[~]([a-z0-9_.-]*[?]?) `);
     static heading_marker     = ctRegex!(`^:?([A-D1-4])[~]`);
     static heading_title      = ctRegex!(`^:?[A-D1-4][~][a-z0-9_.-]*[?]?\s+(.+?)$`);
@@ -55,9 +47,7 @@ mixin template RgxInit() {
     static para_indent        = ctRegex!(`^_([1-9]) `);
     static para_indent_hang   = ctRegex!(`^_([0-9])_([0-9]) `);
     static para_attribs       = ctRegex!(`^_(([0-9])(_([0-9]))?|_([1-9])?[*]) `);
-/*
-** blocked markup tics
-*/
+    /* blocked markup tics */
     static block_tic_code_open       = ctRegex!("^`{3} (code)");
     static block_tic_poem_open       = ctRegex!("^`{3} (poem)");
     static block_tic_group_open      = ctRegex!("^`{3} (group)");
@@ -65,9 +55,7 @@ mixin template RgxInit() {
     static block_tic_quote_open      = ctRegex!("^`{3} (quote)");
     static block_tic_table_open      = ctRegex!("^`{3} (table)");
     static block_tic_close           = ctRegex!("^(`{3})$","m");
-/*
-** blocked markup curly
-*/
+    /* blocked markup curly */
     static block_curly_code_open     = ctRegex!(`^(code[{].*?$)`);
     static block_curly_code_close    = ctRegex!(`^([}]code)`);
     static block_curly_poem_open     = ctRegex!(`^(poem[{].*?$)`);
@@ -80,9 +68,7 @@ mixin template RgxInit() {
     static block_curly_quote_close   = ctRegex!(`^([}]quote)`);
     static block_curly_table_open    = ctRegex!(`^(table[{].*?$)`);
     static block_curly_table_close   = ctRegex!(`^([}]table)`);
-/*
-** inline markup font face mod
-*/
+    /* inline markup font face mod */
     static inline_emphasis           = ctRegex!(`\*\{(?P<text>.+?)\}\*`);
     static inline_bold               = ctRegex!(`!\{(?P<text>.+?)\}!`);
     static inline_italics            = ctRegex!(`/\{(?P<text>.+?)\}/`);
@@ -91,9 +77,7 @@ mixin template RgxInit() {
     static inline_strike             = ctRegex!(`-\{(?P<text>.+?)\}-`);
     static inline_insert             = ctRegex!(`\+\{(?P<text>.+?)\}\+`);
     static inline_mono               = ctRegex!(`#\{(?P<text>.+?)\}#`);
-/*
-** inline markup footnotes
-*/
+    /* inline markup footnotes */
     static true_dollar                           = ctRegex!(`\$`, "gm");
     static inline_notes_al                       = ctRegex!(`【(?:[*+]\s+|\s*)(.+?)】`, "mg");
     static inline_notes_al_gen                   = ctRegex!(`【.+?】`, "m");
@@ -104,10 +88,8 @@ mixin template RgxInit() {
     static inline_al_delimiter_open_and_close_regular   = ctRegex!(`【|】`, "m");
     static inline_notes_delimiter_al_regular            = ctRegex!(`【(.+?)】`, "m");
     static inline_notes_delimiter_al_regular_number_note = ctRegex!(`【(\d+)\s+(.+?)】`, "m");
-
     static inline_al_delimiter_open_asterisk         = ctRegex!(`【\*`, "m");
     static inline_al_delimiter_open_plus             = ctRegex!(`【\+`, "m");
-
     static inline_curly_delimiter_open_regular             = ctRegex!(`~\{\s*`, "m");
     static inline_curly_delimiter_close_regular            = ctRegex!(`\s*\}~`, "m");
     static inline_curly_delimiter_open_and_close_regular   = ctRegex!(`~\{\s*|\s*\}~`, "m");
@@ -122,47 +104,34 @@ mixin template RgxInit() {
     static inline_text_and_note_square_sp        = ctRegex!(`(.+?)~\[[*+]+\s+(.+?)\]~`, "mg");
     static inline_text_and_note_square           = ctRegex!(`(.+?)~\[\s*(.+?)\]~`, "mg");
     static inline_note_square_delimiters         = ctRegex!(`(~\[\s*)(.+?)(\]~)`, "mg");
-/*
-** inline markup book index
-*/
+    /* inline markup book index */
     static book_index                = ctRegex!(`^=\{\s*(.+?)\}$`, "m");
     static book_index_open           = ctRegex!(`^=\{\s*([^}]+?)$`);
     static book_index_close          = ctRegex!(`^(.*?)\}$`, "m"); // strip
-/*
-** no ocn object
-*/
+    /* no ocn object */
     static ocn_off                   = ctRegex!(`~#$`, "m");
     static ocn_off_dh                = ctRegex!(`-#$`, "m");
     static ocn_off_all               = ctRegex!(`[~-]#$`, "m");
-/*
-** no ocn block
-*/
+    /* no ocn block */
     static ocn_off_block             = ctRegex!(`^--~#$`);
     static ocn_off_block_dh          = ctRegex!(`^---#$`);
     static ocn_off_block_close       = ctRegex!(`^--\+#$`);
+    // static auto_ocn_ignore           = ctRegex!(`^[+~*$-]{3,}$`); // reminder
     static ocn_block_marks           = ctRegex!(`^--[+~-]#$`);
-/*
-** ignore outside code blocks
-*/
+    /* ignore outside code blocks */
     static regular_parse_skip        = ctRegex!(`^(--[+~-]#|-[\\]{2}-|=[.\\]{2}=)$`); // not structural info
-/*
-** line& page breaks
-*/
+    /* line & page breaks */
     static break_line_within_object  = ctRegex!(`[\\]{2}( |$)`);
-// static break_line_break_within_object  = ctRegex!(`( |^)[\\]{2}( |$)`);
+    // static break_line_break_within_object  = ctRegex!(`( |^)[\\]{2}( |$)`);
     static break_page                = ctRegex!(`^-[\\]{2}-$`);
     static break_page_new            = ctRegex!(`^=[\\]{2}=$`);
     static break_page_line_across    = ctRegex!(`^=[.]{2}=$`);
     static break_string              = ctRegex!(`』`);
-// ancestry, parent
+    // ancestry, parent
     static parent                    = ctRegex!(`([0-7]):([0-9]+)`);
-/*
-** json
-*/
+    /* json */
     static tailing_comma             = ctRegex!(`,$`, "m");
-/*
-** head
-*/
+    /* head */
     static main_headers              = ctRegex!(`^(?:creator|title|rights|date|original|classify|identifier|notes|publisher|make|links)$`, "m");
     static subhead_creator           = ctRegex!(`^(?:author|translator|illustrator)$`, "m");
     static subhead_title             = ctRegex!(`^(?:main|sub(?:title)?|full|language|edition|note)$`, "m");
@@ -174,22 +143,13 @@ mixin template RgxInit() {
     static subhead_notes             = ctRegex!(`^(?:abstract|description)$`, "m");
     static subhead_publisher         = ctRegex!(`^(?:name)$`, "m");
     static subhead_make              = ctRegex!(`^(?:cover_image|home_button_image|home_button_text|footer|headings|num_top|breaks|substitute|bold|italics|emphasis|texpdf_font|css)$`, "m");
-/*
-** biblio tags
-*/
+    /* biblio tags */
     static biblio_tags               = ctRegex!(`^(is|au|author_raw|author|author_arr|editor_raw|ed|editor_arr|ti|title|subtitle|fulltitle|lng|language|trans|src|jo|journal|in|vol|volume|edn|edition|yr|year|pl|place|pb|pub|publisher|url|pg|pages|note|short_name|id):\s+(.+)`);
     static biblio_abbreviations      = ctRegex!(`^(au|ed|ti|lng|jo|vol|edn|yr|pl|pb|pub|pg|pgs|sn)$`);
-/*
-** bookindex split
-*/
+    /* bookindex split */
     static bi_main_terms_split       = ctRegex!(`\s*;\s*`);
     static bi_main_term_plus_rest_split = ctRegex!(`\s*:\s*`);
     static bi_sub_terms_plus_ocn_offset_split = ctRegex!(`\s*\|\s*`);
     static bi_term_and_ocns_match    = ctRegex!(`^(.+?)\+(\d+)`);
-/*
-* url matching     http://url.is/got and { text }http://url.is/got
-* image matching
-* header substitution & bold & italics lists
-*/
   }
 }
diff --git a/lib/sdp/ao_scan_inserts.d b/lib/sdp/ao_scan_inserts.d
index 3f655c0..ab705eb 100644
--- a/lib/sdp/ao_scan_inserts.d
+++ b/lib/sdp/ao_scan_inserts.d
@@ -1,6 +1,6 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sisu_scan_inserts.d
+  inserts
+  ao_inserts.d
 */
 mixin template SiSUdocInserts() {
   class Inserts {
@@ -103,7 +103,7 @@ mixin template SiSUdocInserts() {
           cont_arbitrary_max_length_set_[counter["add"]] = line;
           ++counter["add"]; ++add;
         }
-      }
+      } // end src subdoc (inserts) loop
       auto contents_ = cont_arbitrary_max_length_set_[0 .. counter["add"]].dup;
       auto t = tuple(contents_, add);
       return t;
@@ -216,7 +216,7 @@ mixin template SiSUdocInserts() {
           cont_arbitrary_max_length_set[add] = line;
           ++add;
         }
-      }
+      } // end src doc loop
       auto contents = cont_arbitrary_max_length_set[0..add].dup;
       debug(insert) {                              // insert file
         writeln(__LINE__);
diff --git a/lib/sdp/ao_utils.d b/lib/sdp/ao_utils.d
index 70ad667..20e8988 100644
--- a/lib/sdp/ao_utils.d
+++ b/lib/sdp/ao_utils.d
@@ -1,6 +1,6 @@
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sisu_utils.d
+  utils
+  ao_util.d
 */
 mixin template ScreenTxtColors() {
   string[string] scr_txt_color = [
diff --git a/lib/sdp/sdp.d b/lib/sdp/sdp.d
index 27fb169..6c10a83 100644
--- a/lib/sdp/sdp.d
+++ b/lib/sdp/sdp.d
@@ -1,34 +1,37 @@
 #!/usr/bin/env rdmd
 /*
-#+OPTIONS: ^:nil _:nil#+OPTIONS: ^:nil _:nil
-* sdp.d  :sdp:
+  sdp
+  sdp.d
 */
 import
   std.stdio,
   std.file,
+  std.exception,
+  // std.path,
   std.regex,
   std.utf,
   std.string,
   std.array,
   std.json,
   std.process,
-  std.exception,
   std.typecons,
   std.algorithm,
   std.range,
   std.container,
   std.traits,
-  lib.sdp.ao_output_debugs,         // ao_output_debugs.d
-  lib.sdp.ao_defaults,              // ao_defaults.d
-  lib.sdp.ao_rgx,                   // ao_rgx.d
-  lib.sdp.ao_interface,             // ao_interface.d
-  lib.sdp.ao_emitter,               // ao_emitter.d
-  lib.sdp.ao_scan_inserts,          // ao_scan_inserts.d
-  lib.sdp.ao_markup_source_raw,     // ao_markup_source_raw.d
-  lib.sdp.ao_abstract_doc_source,   // ao_abstract_doc_source.d
-  lib.sdp.ao_assertions,            // ao_assertions.d
-  lib.sdp.ao_object_setter,         // ao_object_setter.d
-  lib.sdp.ao_utils;                 // ao_utils.d
+  // std.variant,
+  lib.sdp.ao_output_debugs,        // ao_output_debugs.d       ao_output_debugs.org
+  lib.sdp.ao_defaults,             // ao_defaults.d            ao_defaults.arg
+  lib.sdp.ao_rgx,                  // ao_rgx.d                 ao_rgx.org
+  lib.sdp.ao_interface,            // ao_interface.d           ao_interface.arg
+  lib.sdp.ao_emitter,              // ao_emitter.d             ao_emitter.org
+  lib.sdp.ao_scan_inserts,         // ao_scan_inserts.d        ao_scan_inserts.org
+  lib.sdp.ao_markup_source_raw,    // ao_markup_source_raw.d   ao_markup_source_raw.org
+  lib.sdp.ao_abstract_doc_source,  // ao_abstract_doc_source.d ao_abstract_doc_source.org
+  lib.sdp.ao_assertions,           // ao_assertions.d          ao_assertions.org
+  lib.sdp.ao_object_setter,        // ao_object_setter.d       ao_object_setter.org
+  lib.sdp.ao_utils;                // ao_utils.d               ao_utils.org
+  // std.conv;
 import std.conv : to;
 mixin RgxInit; mixin Interfaces; mixin Emitters;
 void main(string[] argv) {
@@ -44,6 +47,13 @@ void main(string[] argv) {
   auto raw = new MarkupRaw();
   auto abs = new Abstraction();
   auto dbg = new SDPoutputDebugs();
+  // struct DocumentParts {
+  //   string[string][] contents;
+  //   JSONValue[string] metadata_json;
+  //   JSONValue[string] make_json;
+  //   string[][string][string] bookindex_unordered_hashes;
+  //   JSONValue[] biblio;
+  // }
   char[][] msc;
   string[1000] fns_src;
   string flag_action;
@@ -61,6 +71,7 @@ void main(string[] argv) {
         scr_txt_color["off"],
       );
     }
+    // writeln("0");
   }
   scope(failure) {
     debug(checkdoc) {
@@ -70,6 +81,7 @@ void main(string[] argv) {
         scr_txt_color["off"],
       );
     }
+    // writeln("1");
   }
   foreach(cmdlnins; argv) {
     if (match(cmdlnins, rgx.flag_action)) {
@@ -91,6 +103,7 @@ void main(string[] argv) {
             fn_src
           );
         }
+        // writeln("0");
       }
       scope(failure) {
         debug(checkdoc) {
@@ -101,39 +114,53 @@ void main(string[] argv) {
             fn_src
           );
         }
+        // writeln("1");
       }
+      enforce(
+        match(fn_src, rgx.src_pth),
+        "not a sisu markup filename"
+      );
       auto markup_sourcefile_content =
         raw.markupSourceContentRawLineArray(fn_src); // alternative call
+        // raw.markupSourceLineArray(raw.markupSourceString(fn_src)); // alternative calls (milliseconds faster?)
       debug(insert) {
         string[string] sysenv;
         sysenv["pwd"] = shell("pwd");
         writeln(sysenv["pwd"]);
         auto m = match(fn_src, rgx.src_pth);
+        // auto m = match(fn_src, rgx.src_pth);
         auto markup_src_file_path = m.captures[1];
         writeln("markup source file path: ", markup_src_file_path); // writeln(m.captures[1]);
         writeln(m.captures[2]);
       }
       if (match(fn_src, rgx.src_fn_master)) {
+      /* if master file scan document source for document imports (inserted sub-documents) */
         auto ins = new Inserts();
         auto markup_master_sourcefile_content =
           ins.scan_doc_source(markup_sourcefile_content, fn_src);
         msc = markup_master_sourcefile_content;
-      } else {
+      } else if (match(fn_src, rgx.src_fn)) {
         msc = markup_sourcefile_content;
+      } else {
+        writeln("not a recognized filename");
       }
       debug(raw) {
         foreach (line; msc) {
           writeln(line);
         }
       }
+      /* process document ao_abstract_doc_source SiSUdocAbstraction::Abstraction return abstraction as tuple */
       auto t =
         abs.abstract_doc_source(msc);
       static assert(!isTypeTuple!(t));
       auto contents = t[0];
+      // static assert(!isIterable!(contents));
       auto metadata_json = t[1];
       auto make_json = t[2];
       auto bookindex_unordered_hashes = t[3];
       auto biblio = t[4];
+      // destroy(t);
+      // DocumentParts
       debug(checkdoc) {
         dbg.abstract_doc_source_debugs(
           contents,
@@ -145,6 +172,8 @@ void main(string[] argv) {
           actions
         );
       }
+      // compose abstract document markup state
+      // append book index
       scope(exit) {
         destroy(msc);
         destroy(t);
@@ -155,7 +184,11 @@ void main(string[] argv) {
         destroy(fn_src);
         destroy(biblio);
       }
-    } else { // terminate, stop
+    } else {
+      /* no recognized filename provided */
+      writeln("no recognized filename");
+      break;
+      // terminate, stop
     }
   }
 }