0.1.0 renamed doc-reform, doc_reform (& rad)

- from sdp

1 files changed, 1524 insertions, 0 deletions

diff --git a/org/doc_reform.org b/org/doc_reform.org
new file mode 100644
index 0000000..eb10646
--- /dev/null
+++ b/org/doc_reform.org
@@ -0,0 +1,1524 @@
+#+TITLE:       doc_reform hub
+#+DESCRIPTION: documents - structuring, various output representations & search
+#+FILETAGS:    :doc_reform:hub:
+#+AUTHOR:      Ralph Amissah
+#+EMAIL:       [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]]
+#+LANGUAGE:    en
+#+STARTUP:     indent content
+#+OPTIONS:     H:3 num:nil toc:t \n:nil @:t ::t |:t ^:nil _:nil -:t f:t *:t <:t
+#+OPTIONS:     TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-toc
+#+OPTIONS:     author:nil email:nil creator:nil timestamp:nil
+#+PROPERTY:    header-args :padline no :exports code :noweb yes
+#+EXPORT_SELECT_TAGS:  export
+#+EXPORT_EXCLUDE_TAGS: noexport
+#+TAGS: assert(a) class(c) debug(d) mixin(m) doc_reform(s) tangle(T) template(t) WEB(W) noexport(n)
+
+[[../maker.org][maker.org makefile]]  [[./][org/]]
+* 0. version.txt (set version)                                      :version:
+** set program version
+
+#+BEGIN_SRC d  :tangle ../views/version.txt
+/+ obt - org generated file +/
+struct Version {
+  int major;
+  int minor;
+  int patch;
+}
+enum ver = Version(0, 1, 0);
+#+END_SRC
+
+** compilation restrictions (supported compilers)
+
+http://dlang.org/spec/version.html#predefined-versions
+
+#+BEGIN_SRC d  :tangle ../views/version.txt
+version (Posix) {
+  version (DigitalMars) {
+  } else version (LDC) {
+  } else version (GNU) {
+  } else {
+    static assert (0, "Unsupported D compiler");
+  }
+} else {
+  static assert (0, "Unsupported D compiler");
+}
+#+END_SRC
+
+* 1. doc_reform (sisu document parser)                           :doc_reform:
+** notes
+- deal with imports
+- get options
+  - get command line instructions
+  - read config instructions
+- process files as instructed by options
+  - read in file
+  - process file
+  - output
+
+** 0. sdp src/sdp                                                 :template:
+
+- process files (act according to requirements of each type)
+  - by sourcefilename
+  - by sourcefiles contents identifier
+  - by zip filename
+
+#+BEGIN_SRC d  :tangle ../src/doc_reform/doc_reform.d :shebang #!/usr/bin/env rdmd
+module doc_reform.sisu_document_parser;
+import
+  doc_reform.conf.compile_time_info,
+  doc_reform.meta.metadoc;
+<<imports_doc_reform>>
+import std.algorithm;
+import std.parallelism;
+<<mixin_doc_reform_version>>
+<<mixin_pre_main>>
+/++
+name        "doc_reform"
+description "A SiSU inspired document parser writen in D."
+homepage    "http://sisudoc.org"
++/
+void main(string[] args) {
+  <<doc_reform_mixin>>
+  <<doc_reform_args>>
+  <<doc_reform_do_selected>>
+  if (_manifests.length > 1) {                            // _manifests[0] initialized dummy element
+    foreach(manifest; parallel(_manifests[1..$])) {
+      if (!empty(manifest.src.filename)) {
+        <<doc_reform_each_file_do_scope>>
+        <<doc_reform_each_file_do_abstraction>>
+        <<doc_reform_each_file_do_debugs_checkdoc>>
+        <<doc_reform_each_file_do_selected_output>>
+        <<doc_reform_each_file_do_scope_exit>>
+      } else {
+        <<doc_reform_no_filename_provided>>
+      }
+    }
+  }
+}
+#+END_SRC
+
+** 1. pre-loop init                                                   :init:
+*** init
+**** imports                                                      :import:
+***** doc_reform                                             :doc_reform:
+
+#+NAME: imports_doc_reform
+#+BEGIN_SRC d
+import
+  std.getopt,
+  std.file,
+  std.path,
+  std.process;
+import
+  doc_reform.meta,
+  doc_reform.meta.metadoc_summary,
+  doc_reform.meta.metadoc_from_src,
+  doc_reform.meta.conf_make_meta_structs,
+  doc_reform.meta.conf_make_meta_toml,
+  doc_reform.meta.conf_make_meta_json,
+  doc_reform.meta.defaults,
+  doc_reform.meta.doc_debugs,
+  doc_reform.meta.rgx,
+  doc_reform.source.paths_source,
+  doc_reform.source.read_config_files,
+  doc_reform.source.read_source_files,
+  doc_reform.output.hub;
+#+END_SRC
+
+****** notes
+├── src
+│   ├── doc_reform.d
+│   └── doc_reform
+│       ├── conf
+│       ├── meta
+│       └── output
+└── views
+    └── version.txt
+
+[[./meta_abstraction.org][meta_abstraction]]
+[[./meta_conf_make_meta.org][meta_conf_make_meta]]
+[[./meta_defaults.org][meta_defaults]]
+[[./meta_output_debugs.org][meta_output_debugs]]
+[[./source_read_files.org][source_read_files]]
+[[./compile_time_info.org][compile time info]]
+[[./output.org][output]]
+[[./doc_reform.org][doc_reform]]
+
+keep up to date, configuration in ../maker.org
+
+check:
+- http://github.com/Abscissa/SDLang-D
+- https://github.com/abscissa/libInputVisitor
+
+std.conv,
+std.variant,
+
+- https://code.dlang.org/packages/toml
+- https://github.com/toml-lang/toml
+- https://github.com/toml-lang/toml/blob/master/README.md
+
+**** mixins                                                        :mixin:
+***** version.txt                                               :version:
+
+#+NAME: mixin_doc_reform_version
+#+BEGIN_SRC d
+mixin(import("version.txt"));
+#+END_SRC
+
+***** pre main mixins
+#+NAME: mixin_pre_main
+#+BEGIN_SRC d
+mixin CompileTimeInfo;
+#+END_SRC
+
+***** doc_reform "main" mixins                               :doc_reform:
+
+#+NAME: doc_reform_mixin
+#+BEGIN_SRC d
+mixin SiSUrgxInit;
+mixin contentJSONtoSiSUstruct;
+mixin SiSUbiblio;
+mixin SiSUrgxInitFlags;
+mixin outputHub;
+#+END_SRC
+
+**** init                                                           :init:
+
+#+NAME: doc_reform_args
+#+BEGIN_SRC d
+string flag_action;
+string arg_unrecognized;
+enum dAM { abstraction, matters }
+static auto rgx = Rgx();
+#+END_SRC
+
+*** scope (run complete)                                            :scope:
+
+#+NAME: doc_reform_args
+#+BEGIN_SRC d
+scope(success) {
+  debug(checkdoc) {
+    writefln(
+      "~ run complete, ok ~ (doc_reform-%s.%s.%s, %s D:%s, %s %s)",
+      ver.major, ver.minor, ver.patch,
+      __VENDOR__, __VERSION__,
+      bits, os,
+    );
+  }
+}
+scope(failure) {
+  debug(checkdoc) {
+    stderr.writefln(
+      "run failure",
+    );
+  }
+}
+#+END_SRC
+
+*** getopt args for loop                                      :args:getopt:
+
+look into using getopt
+[[http://dlang.org/phobos/std_getopt.html][getopt]]
+[[http://dlang.org/library/std/getopt.html][getopt]]
+
+**** getopt
+
+#+NAME: doc_reform_args
+#+BEGIN_SRC d
+bool[string] opts = [
+  "abstraction"        : false,
+  "assertions"         : false,
+  "concordance"        : false,
+  "debug"              : false,
+  "digest"             : false,
+  "epub"               : false,
+  "html"               : false,
+  "html-seg"           : false,
+  "html-scroll"        : false,
+  "manifest"           : false,
+  "ocn"                : true,
+  "pp2"                : false,
+  "quiet"              : false,
+  "sisupod"            : false,
+  "source"             : false,
+  "sqlite-discrete"    : false,
+  "sqlite-db-create"   : false,
+  "sqlite-db-drop"     : false,
+  "sqlite-db-recreate" : false,
+  "sqlite-delete"      : false,
+  "sqlite-insert"      : false,
+  "sqlite-update"      : false,
+  "text"               : false,
+  "verbose"            : false,
+  "very-verbose"        : false,
+  "xhtml"              : false,
+  "section_toc"        : true,
+  "section_body"       : true,
+  "section_endnotes"   : true,
+  "section_glossary"   : true,
+  "section_biblio"     : true,
+  "section_bookindex"  : true,
+  "section_blurb"      : true,
+  "backmatter"         : true,
+  "skip-output"        : false,
+];
+string[string] settings = [
+  "output-dir"         : "",
+  "site-config-dir"    : "",
+  "lang"               : "all",
+  "sqlite-filename"    : "documents",
+];
+auto helpInfo = getopt(args,
+  std.getopt.config.passThrough,
+  "abstraction",        "--abstraction document abstraction ",                                      &opts["abstraction"],
+  "assert",             "--assert set optional assertions on",                                      &opts["assertions"],
+  "concordance",        "--concordance file for document",                                          &opts["concordance"],
+  "debug",              "--debug",                                                                  &opts["debug"],
+  "digest",             "--digest hash digest for each object",                                     &opts["digest"],
+  "epub",               "--epub process epub output",                                               &opts["epub"],
+  "html",               "--html process html output",                                               &opts["html"],
+  "html-seg",           "--html-seg process html output",                                           &opts["html-seg"],
+  "html-scroll",        "--html-seg process html output",                                           &opts["html-scroll"],
+  "manifest",           "--manifest process manifest output",                                       &opts["manifest"],
+  "ocn",                "--ocn object cite numbers (default)",                                      &opts["ocn"],
+  "pp2",                "--pp2 nested parallelisation",                                             &opts["pp2"],
+  "quiet",              "--quiet output to terminal",                                               &opts["quiet"],
+  "sisupod",            "--sisupod sisupod source content bundled",                                 &opts["sisupod"],
+  "source",             "--source markup source text content",                                      &opts["source"],
+  "sqlite-discrete",    "--sqlite process discrete sqlite output",                                  &opts["sqlite-discrete"],
+  "sqlite-db-create",   "--sqlite-db-create create db, create tables",                              &opts["sqlite-db-create"],
+  "sqlite-db-drop",     "--sqlite-db-drop drop tables & db",                                        &opts["sqlite-db-drop"],
+  "sqlite-db-recreate", "--sqlite-db-recreate create db, create tables",                            &opts["sqlite-db-recreate"],
+ // "sqlite-db-populate", "--sqlite-db-populate create db & tables, insert specified",  &opts["sqlite-db-populate"],
+  "sqlite-delete",      "--sqlite process sqlite output",                                           &opts["sqlite-delete"],
+  "sqlite-insert",      "--sqlite process sqlite output",                                           &opts["sqlite-insert"],
+  "sqlite-update",      "--sqlite process sqlite output",                                           &opts["sqlite-update"],
+  "text",               "--text process text output",                                               &opts["text"],
+  "txt",                "--txt process text output",                                                &opts["text"],
+  "verbose|v",          "--verbose output to terminal",                                             &opts["verbose"],
+  "very-verbose",       "--very-verbose output to terminal",                                        &opts["very-verbose"],
+  "xhtml",              "--xhtml process xhtml output",                                             &opts["xhtml"],
+  "section-toc",        "--section-toc process table of contents (default)",                        &opts["section_toc"],
+  "section-body",       "--section-body process document body (default)",                           &opts["section_body"],
+  "section-endnotes",   "--section-endnotes process document endnotes (default)",                   &opts["section_endnotes"],
+  "section-glossary",   "--section-glossary process document glossary (default)",                   &opts["section_glossary"],
+  "section-biblio",     "--section-biblio process document biblio (default)",                       &opts["section_biblio"],
+  "section-bookindex",  "--section-bookindex process document bookindex (default)",                 &opts["section_bookindex"],
+  "section-blurb",      "--section-blurb process document blurb (default)",                         &opts["section_blurb"],
+  "backmatter",         "--section-backmatter process document backmatter (default)",               &opts["backmatter"],
+  "skip-output",        "--skip-output",                                                            &opts["skip-output"],
+  "output-dir",         "--output-dir=[dir path]",                                                  &settings["output-dir"],
+  "site-config-dir",    "--site-config-dir=[dir path]",                                             &settings["site-config-dir"],
+  "sqlite-filename",    "--sqlite-filename=[filename].sqlite",                                      &settings["sqlite-filename"],
+  "lang",               "--lang=[lang code e.g. =en or =en,es]",                                    &settings["lang"],
+);
+if (helpInfo.helpWanted) {
+  defaultGetoptPrinter("Some information about the program.", helpInfo.options);
+}
+#+END_SRC
+
+**** getopt hash to struct
+
+#+NAME: doc_reform_args
+#+BEGIN_SRC d
+enum outTask { sisupod, source, sqlite, sqlite_multi, epub, html_scroll, html_seg, html_stuff }
+struct OptActions {
+  auto assertions() {
+    return opts["assertions"];
+  }
+  auto concordance() {
+    return opts["concordance"];
+  }
+  auto debug_do() {
+    return opts["debug"];
+  }
+  auto digest() {
+    return opts["digest"];
+  }
+  auto epub() {
+    return opts["epub"];
+  }
+  auto html() {
+    bool _is = (
+      opts["html"]
+      || opts["html-seg"]
+      || opts["html-scroll"]
+    )
+    ? true
+    : false;
+    return _is;
+  }
+  auto html_seg() {
+    bool _is = (
+      opts["html"]
+      || opts["html-seg"]
+    )
+    ? true
+    : false;
+    return _is;
+  }
+  auto html_scroll() {
+    bool _is = (
+      opts["html"]
+      || opts["html-scroll"]
+    )
+    ? true
+    : false;
+    return _is;
+  }
+  auto html_stuff() {
+    bool _is = (
+      opts["html"]
+      || opts["html-scroll"]
+      || opts["html-seg"]
+    )
+    ? true
+    : false;
+    return _is;
+  }
+  auto manifest() {
+    return opts["manifest"];
+  }
+  auto ocn() {
+    return opts["ocn"];
+  }
+  auto quiet() {
+    return opts["quiet"];
+  }
+  auto sisupod() {
+    return opts["sisupod"];
+  }
+  auto source() {
+    return opts["source"];
+  }
+  auto sqlite_discrete() {
+    return opts["sqlite-discrete"];
+  }
+  auto sqlite_db_drop() {
+    bool _is = (
+      opts["sqlite-db-recreate"]
+      || opts["sqlite-db-drop"]
+    )
+    ? true
+    : false;
+    return _is;
+  }
+  auto sqlite_db_create() {
+    bool _is = (
+      opts["sqlite-db-recreate"]
+      || opts["sqlite-db-create"]
+    )
+    ? true
+    : false;
+    return _is;
+  }
+  auto sqlite_insert() {
+    return opts["sqlite-insert"];
+  }
+  auto sqlite_delete() {
+    return opts["sqlite-delete"];
+  }
+  auto sqlite_update() {
+    return opts["sqlite-update"];
+  }
+  auto text() {
+    return opts["text"];
+  }
+  auto verbose() {
+    bool _is = (
+      opts["verbose"]
+      || opts["very-verbose"]
+    )
+    ? true
+    : false;
+    return _is;
+  }
+  auto very_verbose() {
+    return opts["very-verbose"];
+  }
+  auto xhtml() {
+    return opts["xhtml"];
+  }
+  auto section_toc() {
+    return opts["section_toc"];
+  }
+  auto section_body() {
+    return opts["section_body"];
+  }
+  auto section_endnotes() {
+    return opts["section_endnotes"];
+  }
+  auto section_glossary() {
+    return opts["section_glossary"];
+  }
+  auto section_biblio() {
+    return opts["section_biblio"];
+  }
+  auto section_bookindex() {
+    return opts["section_bookindex"];
+  }
+  auto section_blurb() {
+    return opts["section_blurb"];
+  }
+  auto backmatter() {
+    return opts["backmatter"];
+  }
+  auto skip_output() {
+    return opts["skip-output"];
+  }
+  auto languages_set() {
+    return settings["lang"].split(",");
+  }
+  auto output_dir_set() {
+    return settings["output-dir"];
+  }
+  auto sqlite_filename() {
+    return settings["sqlite-filename"];
+  }
+  auto pp2() {
+    return opts["pp2"];
+  }
+  auto output_task_scheduler() {
+    int[] schedule;
+    if (sisupod) {
+      schedule ~= outTask.sisupod;
+    }
+    if (source) {
+      schedule ~= outTask.source;
+    }
+    if (sqlite_discrete) {
+      schedule ~= outTask.sqlite;
+    }
+    if (epub) {
+      schedule ~= outTask.epub;
+    }
+    if (html_scroll) {
+      schedule ~= outTask.html_scroll;
+    }
+    if (html_seg) {
+      schedule ~= outTask.html_seg;
+    }
+    if (html_stuff) {
+      schedule ~= outTask.html_stuff;
+    }
+    return schedule.sort().uniq;
+  }
+  auto abstraction() {
+    bool _is = (
+      opts["abstraction"]
+      || concordance
+      || epub
+      || html
+      || manifest
+      || sisupod
+      || source
+      || sqlite_discrete
+      || sqlite_delete
+      || sqlite_insert
+      || sqlite_update
+    )
+    ? true
+    : false;
+    return _is;
+  }
+}
+auto _opt_action = OptActions();
+#+END_SRC
+
+**** env
+
+#+NAME: doc_reform_args
+#+BEGIN_SRC d
+auto _env = [
+  "pwd" : environment["PWD"],
+  "home" : environment["HOME"],
+];
+#+END_SRC
+
+*** opt actions on processing files & file paths (pods, src etc.)
+
+#+NAME: doc_reform_args
+#+BEGIN_SRC d
+auto _manifest_start = PodManifest!()("");
+auto _manifest_matter = PathMatters!()(_opt_action, _env, "");
+auto _manifests = [ _manifest_matter ];
+foreach(arg; args[1..$]) {
+  _manifest_start = PodManifest!()(arg);
+  if (arg.match(rgx.flag_action)) {
+    flag_action ~= " " ~ arg;   // flags not taken by getopt
+  } else if (
+    !(arg.match(rgx.src_pth_sst_or_ssm))
+    && _manifest_start.pod_manifest_file_with_path
+    && _opt_action.abstraction
+  ) {
+    string contents_location_raw_;
+    string contents_location_;
+    string sisudoc_txt_ = _manifest_start.pod_manifest_file_with_path;
+    enforce(
+      exists(sisudoc_txt_)!=0,
+      "file not found: «" ~
+      sisudoc_txt_ ~ "»"
+    );
+    if (exists(sisudoc_txt_)) {
+      try {
+        if (exists(sisudoc_txt_)) {
+          contents_location_raw_ = sisudoc_txt_.readText;
+        }
+      } catch (ErrnoException ex) {
+      } catch (FileException ex) {
+        // Handle errors
+      }
+      if (contents_location_raw_.match(rgx.pod_content_location)) { // (file name followed by language codes \n)+
+        foreach (m; contents_location_raw_.matchAll(rgx.pod_content_location)) {
+          foreach (n; m.captures[2].matchAll(rgx.language_codes)) {
+            contents_location_ ~= "media/text/" ~ n.captures[1].to!string ~ "/" ~ m.captures[1].to!string ~ "\n";
+          }
+        }
+      } else {
+        contents_location_ = contents_location_raw_;
+      }
+    } else {
+      writeln("manifest not found: ", sisudoc_txt_);
+    }
+    auto contents_locations_arr
+      = (cast(char[]) contents_location_).split;
+    auto tmp_dir_ = (sisudoc_txt_).dirName.array;
+    foreach (contents_location; contents_locations_arr) {
+      assert(contents_location.match(rgx.src_pth_sst_or_ssm),
+        "not a recognised file: «" ~
+        contents_location ~ "»"
+      );
+      auto contents_location_pth_ = (contents_location).to!string;
+      auto lang_rgx_ = regex(r"/(" ~ _opt_action.languages_set.join("|") ~ ")/");
+      if (_opt_action.languages_set[0] == "all"
+        || (contents_location_pth_).match(lang_rgx_)
+      ) {
+        auto _fns = (((tmp_dir_).chainPath(contents_location_pth_)).array).to!string;
+        _manifest_matter = PathMatters!()(_opt_action, _env, arg, _fns, contents_locations_arr);
+        _manifests ~= _manifest_matter;
+      }
+    }
+  } else if (arg.match(rgx.src_pth_sst_or_ssm)) {
+    if (exists(arg)==0) {
+      writeln("ERROR >> Processing Skipped! File not found: ", arg);
+    } else {
+      _manifest_matter = PathMatters!()(_opt_action, _env, arg, arg);
+      _manifests ~= _manifest_matter;
+    }
+  } else if (arg.match(rgx.src_pth_zip)) {
+    // fns_src ~= arg;          // gather input markup source file names for processing
+  } else {                      // anything remaining, unused
+    arg_unrecognized ~= " " ~ arg;
+  }
+}
+#+END_SRC
+
+*** config files load & read
+
+#+NAME: doc_reform_conf_files_in_toml
+#+BEGIN_SRC d
+auto _config_document_struct = readConfigDoc!()(_manifest, _env);    // document config file
+auto _config_local_site_struct = readConfigSite!()(_manifest, _env); // local site config
+ConfCompositePlus _make_and_meta_struct;
+_make_and_meta_struct = configParseTOMLreturnSiSUstruct!()(_make_and_meta_struct, _config_document_struct);
+_make_and_meta_struct = configParseTOMLreturnSiSUstruct!()(_make_and_meta_struct, _config_local_site_struct);
+#+END_SRC
+
+*** opt actions independent of processing files (no files no processing loop)
+
+#+NAME: doc_reform_do_selected
+#+BEGIN_SRC d
+if (!(_opt_action.skip_output)) {
+  debug(steps) {
+    writeln("step0 commence → (without processing files)");
+  }
+  outputHubOp!()(_env, _opt_action);
+  debug(steps) {
+    writeln("- step0 complete");
+  }
+}
+#+END_SRC
+
+** _2. processing: (loop each file)_ [+2]                         :loop:files:
+*** scope (loop)                                                    :scope:
+
+#+NAME: doc_reform_each_file_do_scope
+#+BEGIN_SRC d
+scope(success) {
+  if (!(_opt_action.quiet)) {
+    writefln(
+      "%s\n%s",
+      "~ document complete, ok ~",
+      "------------------------------------------------------------------",
+    );
+  }
+}
+scope(failure) {
+  debug(checkdoc) {
+    stderr.writefln(
+      "~ document run failure ~ (%s  v%s)\n\t%s\n%s",
+      __VENDOR__, __VERSION__,
+      manifest.src.filename,
+      "------------------------------------------------------------------",
+    );
+  }
+}
+enforce(
+  manifest.src.filename.match(rgx.src_pth_types),
+  "not a sisu markup filename: «" ~
+  manifest.src.filename ~ "»"
+);
+#+END_SRC
+
+*** 1. _document abstraction_ [#A]
+
+- return tuple of:
+  - doc_abstraction (the document)
+  - doc_matters
+
+#+NAME: doc_reform_each_file_do_abstraction
+#+BEGIN_SRC d
+debug(steps) {
+  writeln("--->\nstepX commence → (document abstraction)");
+}
+auto t = SiSUabstraction!()(_env, _opt_action, manifest);
+static assert(!isTypeTuple!(t));
+static assert(t.length==2);
+auto doc_abstraction = t[dAM.abstraction];
+auto doc_matters = t[dAM.matters];
+debug(steps) {
+  writeln("- stepX complete");
+}
+#+END_SRC
+
+*** 2. _output processing_ (post abstraction processing)
+**** 0. abstraction _print summary_                    :abstraction:summary:
+
+#+NAME: doc_reform_each_file_do_debugs_checkdoc
+#+BEGIN_SRC d
+/+ ↓ debugs +/
+if (doc_matters.opt.action.verbose) {
+  SiSUabstractionSummary!()(doc_abstraction, doc_matters);
+}
+#+END_SRC
+
+**** 1. _debug_ (document parts, checkdoc)                  :debug:checkdoc:
+- [[./meta_output_debugs.org][meta_output_debugs]]
+
+#+NAME: doc_reform_each_file_do_debugs_checkdoc
+#+BEGIN_SRC d
+/+ ↓ debugs +/
+if ((doc_matters.opt.action.debug_do)
+|| (doc_matters.opt.action.verbose)
+) {
+  SiSUdebugs!()(doc_abstraction, doc_matters);
+}
+#+END_SRC
+
+**** 2. _process outputs_                                          :outputs:
+- [[./output_hub.org][output_hub]]
+
+#+NAME: doc_reform_each_file_do_selected_output
+#+BEGIN_SRC d
+/+ ↓ output hub +/
+if (!(doc_matters.opt.action.skip_output)) {
+  debug(steps) {
+    writeln("step5 commence → (process outputs)");
+  }
+  outputHub!()(doc_abstraction, doc_matters);
+  debug(steps) {
+    writeln("- step5 complete");
+  }
+}
+#+END_SRC
+
+*** scope (on loop exit)                                       :scope:exit:
+
+#+NAME: doc_reform_each_file_do_scope_exit
+#+BEGIN_SRC d
+scope(exit) {
+  if (!(_opt_action.quiet)) {
+    writefln(
+      "processed file: %s",
+      manifest.src.filename
+    );
+  }
+  destroy(manifest);
+}
+#+END_SRC
+
+** +2c. no valid filename provided+
+#+NAME: doc_reform_no_filename_provided
+#+BEGIN_SRC d
+/+ no recognized filename provided +/
+writeln("no recognized filename");
+break; // terminate, stop
+#+END_SRC
+
+* 2. _document abstraction functions_           :module:doc_reform:abstraction:
+** 0. module template
+
+#+BEGIN_SRC d  :tangle ../src/doc_reform/meta/metadoc.d
+module doc_reform.meta.metadoc;
+template SiSUabstraction() {
+  <<imports_doc_reform>>
+  <<doc_reform_mixin>>
+  enum headBody { header, body_content, insert_file_list, image_list }
+  enum makeMeta { make, meta }
+  enum docAbst  { doc_abstraction, section_keys, segnames, segnames_0_4, images }
+  static auto rgx = Rgx();
+  auto SiSUabstraction(E,O,M)(
+    E _env,
+    O _opt_action,
+    M _manifest
+  ){
+    <<doc_reform_conf_files_in_toml>>
+    <<doc_reform_each_file_do_read_and_split_sisu_markup_file_content_into_header_and_body>>
+    <<doc_reform_each_file_do_split_sisu_markup_file_header_into_make_and_meta_structs>>
+    <<doc_reform_each_file_do_document_abstraction>>
+    <<doc_reform_each_file_do_document_matters>>
+    auto t = tuple(doc_abstraction, doc_matters);
+    static assert(t.length==2);
+    return t;
+  }
+}
+#+END_SRC
+
+** 1. raw file content split, doc: _header_, _content_ +(lists: subdocs? images?)
+- [[./source_read_files.org][source_read_files]]
+
+- read in the _marked up source document_ and
+  - split the document into:
+    - document header
+    - document body
+      - from markup source
+      - if master document from sub documents content
+  - if a master document
+    - make a list of insert files
+  - if build source pod requested
+    - scan for list of images
+      (action avoided if not needed at this stage)
+
+- _return a tuple of_:
+  - header
+  - body
+  - insert file list
+  - image list (if build source pod requested)
+
+if build source pod requested all information needed to build it available at this point
+  - manifest related information  _manifest
+  - insert file list              _header_body_insertfilelist_imagelist[headBody.insert_file_list]
+  - image list                    _header_body_insertfilelist_imagelist[headBody.image_list]
+
+#+NAME: doc_reform_each_file_do_read_and_split_sisu_markup_file_content_into_header_and_body
+#+BEGIN_SRC d
+/+ ↓ read file (filename with path) +/
+/+ ↓ file tuple of header and content +/
+debug(steps) {
+  writeln("step1 commence → (get document header & body & insert file list & if needed image list)"
+  );
+}
+auto _header_body_insertfilelist_imagelist
+  = SiSUrawMarkupContent!()(_opt_action, _manifest.src.path_and_fn);
+static assert(!isTypeTuple!(_header_body_insertfilelist_imagelist));
+static assert(_header_body_insertfilelist_imagelist.length==4);
+debug(steps) {
+  writeln("- step1 complete");
+}
+debug(header_and_body) {
+  writeln(header);
+  writeln(_header_body_insertfilelist_imagelist.length);
+  writeln(_header_body_insertfilelist_imagelist.length[headBody.body_content][0]);
+}
+#+END_SRC
+
+** 2. _document metadata_ & _make instructions_ (struct from toml)
+- [[./meta_conf_make_meta.org][meta_conf_make_meta]]
+
+- read _document header_, split into:
+  - metadata
+  - make instructions
+- read config files
+  - consolidate make instructions
+- _return tuple of_:
+  - document metadata
+  - make instructions (from configuration files & document header make
+    instructions)
+
+#+NAME: doc_reform_each_file_do_split_sisu_markup_file_header_into_make_and_meta_structs
+#+BEGIN_SRC d
+/+ ↓ split header into make and meta +/
+debug(steps) {
+  writeln("step2 commence → (read document header - toml, return struct)");
+}
+_make_and_meta_struct =
+docHeaderMakeAndMetaTupTomlExtractAndConvertToStruct!()(
+  _make_and_meta_struct,
+  _header_body_insertfilelist_imagelist[headBody.header]
+);
+debug(steps) {
+  writeln("- step2 complete");
+}
+#+END_SRC
+
+** 3. _document abstraction, tuple_ (output-pre-processing) [#A]
+- [[./meta_abstraction.org][meta_abstraction]]
+
+- prepare the document abstraction used in downstream processing
+
+- _return tuple of_:
+  - document abstraction (_the_document_ or doc_abstraction)
+  - document abstraction keys
+    - (head, toc, body, endnotes, glossary, bibliography, bookindex, blurb,
+      tail)
+    - (transfer to _doc_matters_)
+  - segnames for html epub (transfer to _doc_matters_)
+  - image list (transfer to _doc_matters_)
+
+#+NAME: doc_reform_each_file_do_document_abstraction
+#+BEGIN_SRC d
+/+ ↓ document abstraction: process document, return abstraction as tuple +/
+debug(steps) {
+  writeln("step3 commence → (document abstraction (da); da keys; segnames; doc_matters)");
+}
+auto da = SiSUdocAbstraction!()(
+  _header_body_insertfilelist_imagelist[headBody.body_content],
+  _make_and_meta_struct,
+  _opt_action,
+  _manifest,
+  true,
+);
+static assert(!isTypeTuple!(da));
+static assert(da.length==5);
+auto doc_abstraction = da[docAbst.doc_abstraction]; /+ head ~ toc ~ body ~ endnotes_seg ~ glossary ~ bibliography ~ bookindex ~ blurb; +/
+auto _document_section_keys_sequenced = da[docAbst.section_keys];
+string[] _doc_html_segnames = da[docAbst.segnames];
+string[] _doc_epub_segnames_0_4 = da[docAbst.segnames_0_4];
+auto _images = da[docAbst.images];
+debug(steps) {
+  writeln("- step3 complete");
+}
+#+END_SRC
+
+** 4. _document matters_ (doc info gathered, various sources) [#A]
+
+- prepare document_matters, miscellany about processing and the document of use
+  in downstream processing
+
+#+NAME: doc_reform_each_file_do_document_matters
+#+BEGIN_SRC d
+debug(steps) {
+  writeln("step4 commence → (doc_matters)");
+}
+struct DocumentMatters {
+  auto conf_make_meta() { // TODO meld with all make instructions
+    return _make_and_meta_struct;
+  }
+  auto env() {
+    struct Env_ {
+      auto pwd() {
+        return _manifest.env.pwd;
+      }
+      auto home() {
+        return _manifest.env.home;
+      }
+    }
+    return Env_();
+  }
+  auto opt() {
+    struct Opt_ {
+      auto action() {
+        /+ getopt options, commandline instructions, raw
+         - processing instructions --epub --html etc.
+         - command line config instructions --output-path
+        +/
+        return _opt_action;
+      }
+    }
+    return Opt_();
+  }
+  auto src() {
+    return _manifest.src;
+  }
+  auto src_path_info() {
+    return SiSUpathsSRC!()(_manifest.env.pwd, _manifest.src.file_with_absolute_path); // would like (to have and use) relative path
+  }
+  auto srcs() {
+    struct SRC_ {
+      auto file_insert_list() {
+        return _header_body_insertfilelist_imagelist[headBody.insert_file_list];
+      }
+      auto image_list() {
+        return _images;
+      }
+    }
+    return SRC_();
+  }
+  auto pod() {
+    return _manifest.pod;
+  }
+  auto sqlite() {
+    struct SQLite_ {
+      string filename() {
+        return _opt_action.sqlite_filename;
+      }
+    }
+    return SQLite_();
+  }
+  auto xml() {
+    struct XML_ {
+      auto keys_seq() {
+        /+ contains .seg & .scroll sequences +/
+        return _document_section_keys_sequenced;
+      }
+      string[] segnames() {
+        return _doc_html_segnames;
+      }
+      string[] segnames_lv_0_to_4() {
+        return _doc_epub_segnames_0_4;
+      }
+    }
+    return XML_();
+  }
+  auto output_path() {
+    return _manifest.output.path;
+  }
+}
+auto doc_matters = DocumentMatters();
+debug(steps) {
+  writeln("- step4 complete");
+}
+#+END_SRC
+
+* 3. document abstraction _summary_         :module:doc_reform:metadoc_summary:
+** 0. module template
+
+#+BEGIN_SRC d :tangle ../src/doc_reform/meta/metadoc_summary.d
+module doc_reform.meta.metadoc_summary;
+template SiSUabstractionSummary() {
+  auto SiSUabstractionSummary(S,T)(
+    auto ref const S  doc_abstraction,
+    auto ref       T  doc_matters,
+  ) {
+    <<metadoc_summary_imports>>
+    mixin InternalMarkup;
+    <<metadoc_summary_initialize>>
+    if (doc_matters.opt.action.verbose) {
+      <<meta_metadoc_summary>>
+    }
+  }
+}
+#+END_SRC
+
+** init
+*** imports
+
+#+name: metadoc_summary_imports
+#+BEGIN_SRC d
+import
+  doc_reform.meta.defaults,
+  doc_reform.meta.rgx;
+import
+  std.array,
+  std.exception,
+  std.regex,
+  std.stdio,
+  std.string,
+  std.traits,
+  std.typecons,
+  std.uni,
+  std.utf,
+  std.conv : to;
+#+END_SRC
+
+*** initialize                                                     :report:
+
+#+name: metadoc_summary_initialize
+#+BEGIN_SRC d
+auto markup = InlineMarkup();
+#+END_SRC
+
+** (last ocn)
+
+#+name: meta_metadoc_summary
+#+BEGIN_SRC d
+string[string] check = [
+  "last_object_number" : "NA [debug \"checkdoc\" not run]",
+  "last_object_number_body"  : "0",
+  "last_object_number_book_index" : "0",
+];
+foreach (k; doc_matters.xml.keys_seq.seg) {
+  foreach (obj; doc_abstraction[k]) {
+    if (obj.metainfo.is_of_part != "empty") {
+      if (!empty(obj.metainfo.object_number)) {
+        if (k == "body") {
+          check["last_object_number_body"] = obj.metainfo.object_number;
+        }
+        if (!(obj.metainfo.object_number.empty)) {
+          check["last_object_number"] = obj.metainfo.object_number;
+        }
+      }
+      if (k == "bookindex_seg") {
+        if (obj.metainfo.object_number_type == 2) {
+          check["last_object_number_book_index"] = obj.metainfo.object_number_book_index;
+        }
+      }
+    }
+  }
+}
+#+END_SRC
+
+** summary
+
+#+name: meta_metadoc_summary
+#+BEGIN_SRC d
+auto min_repeat_number = 66;
+auto char_repeat_number = (doc_matters.conf_make_meta.meta.title_full.length
+  + doc_matters.conf_make_meta.meta.creator_author.length + 4);
+char_repeat_number = (char_repeat_number > min_repeat_number)
+? char_repeat_number
+: min_repeat_number;
+writefln(
+  "%s\n\"%s\", %s\n%s\n%s\n%30-s%10-d\n%30-s%10-d\n%30-s%10-d\n%30-s%10-d\n%30-s%10-d\n%30-s%10-d\n%30-s%10-d\n%30-s%10-d\n%30-s%10-d\n%30-s%10-d\n%30-s%10-d\n(%s: %s)\n%s",
+  markup.repeat_character_by_number_provided("-", char_repeat_number),
+  doc_matters.conf_make_meta.meta.title_full,
+  doc_matters.conf_make_meta.meta.creator_author,
+  doc_matters.src.filename,
+  markup.repeat_character_by_number_provided("-", char_repeat_number),
+  "length toc arr:",
+  to!int(doc_abstraction["toc_seg"].length),
+  "length doc_abstraction arr:",
+  to!int(doc_abstraction["body"].length),
+  "last doc body ocn:",
+  to!int(check["last_object_number_body"]),
+  "last object_number:",
+  to!int(check["last_object_number"]),
+  "length endnotes:",                                // subtract headings
+  (doc_abstraction["endnotes"].length > 2)
+  ? (to!int(doc_abstraction["endnotes"].length - 2))
+  : 0,
+  "length glossary:",
+  (doc_abstraction["glossary"].length > 1)
+  ? (to!int(doc_abstraction["glossary"].length))
+  : 0,
+  "length biblio:",
+  (doc_abstraction["bibliography"].length > 1)
+  ? (to!int(doc_abstraction["bibliography"].length))
+  : 0,
+  "length bookindex:",
+  (doc_abstraction["bookindex_seg"].length > 1)
+  ? (to!int(doc_abstraction["bookindex_seg"].length))
+  : 0,
+  "  last book idx ocn:",
+  to!int(check["last_object_number_book_index"]),
+  "length blurb:",
+  (doc_abstraction["blurb"].length > 1)
+  ? (to!int(doc_abstraction["blurb"].length))
+  : 0,
+  "number of segments:",
+  (doc_matters.xml.segnames.length > 1)
+  ? (to!int(doc_matters.xml.segnames.length))
+  : 0,
+  __FILE__,
+  __LINE__,
+  markup.repeat_character_by_number_provided("-", min_repeat_number),
+);
+#+END_SRC
+
+* __END__
+dev notes
+
+** doc_reform glossary / terms
+
+|------+-------------------------------------|
+| doc_reform  | sisu document parser                |
+|------+-------------------------------------|
+| dmso | document markup, structure, objects |
+|------+-------------------------------------|
+| meta | meta document, document abstraction |
+| mda  | meta, meta document abstraction     |
+| adr  | abstract document representation    |
+| dar  | document abstract representation    |
+| (da) | (document abstraction)              |
+|      | (code representation of document)   |
+|------+-------------------------------------|
+| ao   | abstract objects                    |
+|      | (code representation of objects)    |
+|------+-------------------------------------|
+
+consider
+|-------+----------------------------------------------|
+| dao   | document abstraction, objects                |
+|-------+----------------------------------------------|
+| daso  | document abstraction, structure, objects     |
+|-------+----------------------------------------------|
+| drso  | document representation, structure, objects  |
+|-------+----------------------------------------------|
+| daows | document abstraction, objects with structure |
+|-------+----------------------------------------------|
+
+** the document notes
+*** document sections
+**** summary
+
+|--------------+--------------+------+---+--------------------------------------------------+--------------------------------+---+---|
+| section      | part         | opt. |   | objects                                          | ocn                            |   |   |
+|--------------+--------------+------+---+--------------------------------------------------+--------------------------------+---+---|
+| front matter | head         | *    |   |                                                  | no                             |   |   |
+|--------------+--------------+------+---+--------------------------------------------------+--------------------------------+---+---|
+| toc          | toc          |      |   | generated from headings                          | no                             |   |   |
+|--------------+--------------+------+---+--------------------------------------------------+--------------------------------+---+---|
+| body         | body         | *    |   | default section                                  | yes                            |   |   |
+|              |              |      |   | - headings                                       |                                |   |   |
+|              |              |      |   | - paras                                          |                                |   |   |
+|              |              |      |   | - code                                           |                                |   |   |
+|              |              |      |   | - poem                                           |                                |   |   |
+|              |              |      |   | - group                                          |                                |   |   |
+|              |              |      |   | - block                                          |                                |   |   |
+|              |              |      |   | - quote                                          |                                |   |   |
+|              |              |      |   | - table                                          |                                |   |   |
+|--------------+--------------+------+---+--------------------------------------------------+--------------------------------+---+---|
+| back matter  | endnote      |      |   | generated from inline note markup                | no (each endnote belongs to    |   |   |
+|              |              |      |   |                                                  | a (body) object)               |   |   |
+|--------------+--------------+------+---+--------------------------------------------------+--------------------------------+---+---|
+|              | glossary     |      |   | identified section, limited markup               | possibly, to make searchable   |   |   |
+|              |              |      |   | - heading                                        | hidden                         |   |   |
+|              |              |      |   | - paras                                          |                                |   |   |
+|--------------+--------------+------+---+--------------------------------------------------+--------------------------------+---+---|
+|              | bibliography |      |   | generated from inline special markup             | possibly, to make searchable   |   |   |
+|              |              |      |   | appended to paragraphs contained in body section | hidden                         |   |   |
+|              |              |      |   | - heading                                        |                                |   |   |
+|              |              |      |   | - paras                                          |                                |   |   |
+|--------------+--------------+------+---+--------------------------------------------------+--------------------------------+---+---|
+|              | book index   |      |   | generated from inline special markup             | possibly, special numbering or |   |   |
+|              |              |      |   | - heading                                        | could use term as anchor?      |   |   |
+|              |              |      |   | - paras                                          | to make searchable             |   |   |
+|              |              |      |   |                                                  | hidden                         |   |   |
+|--------------+--------------+------+---+--------------------------------------------------+--------------------------------+---+---|
+|              | blurb        |      |   | identified section, limited markup               | no (unless non-substantive     |   |   |
+|              |              |      |   | - heading                                        | given special numbering)       |   |   |
+|              |              |      |   | - paras                                          |                                |   |   |
+|--------------+--------------+------+---+--------------------------------------------------+--------------------------------+---+---|
+
+**** on abstraction
+
+- abstract for downstream processing
+  - identify document structure and objects
+    - identify document structure (headings/levels/sections)
+    - identify objects (headings, paragraphs, tables, code blocks, verse ...)
+  - set document, generate common abstraction for downstream parsing
+    - set different _document sections_:
+      - _head_, toc, _body_, endnotes, glossary, bibliography, book index, blurb
+    - _object numbers_, heading/ chapter numbering etc, endnote numbers
+      - _regular ocn_
+        - body objects
+        - glossary objects
+        - bibliography objects
+      - _special ocn_
+        - non substantive text (provide special numbers)
+          - blurb objects
+        - book index
+      - special (_exceptions_)
+        - endnotes
+  - unify object representations
+    - multiple markups for same object type given single representation
+  - extract object attributes
+  - unify inline markup on objects
+    - inline markup made easier to identify
+
+- simplify downstream parsing
+
+*** objects
+**** summary
+
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+|       |              | identified by              | object notes             | attributes     | inline          | embedded       | special    |
+|       |              |                            |                          |                |                 | appended       | characters |
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+| para  | heading      | level markers              |                          |                | - italics       | - endnotes     |            |
+|       |              | at start of line           |                          |                |                 | - bibliography |            |
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+|       | paragraph    | delimited by two new lines | default object           | - indent       | - bold          | - endnotes     |            |
+|       |              |                            | [discard leading &       | - bullet       | - italics       | - bibliography |            |
+|       |              |                            | newline whitespace]      |                | - underscore    |                |            |
+|       |              |                            |                          |                | - strikethrough |                |            |
+|       |              |                            |                          |                | - superscript   |                |            |
+|       |              |                            |                          |                | - subscript     |                |            |
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+| block |              | open and close tags        |                          |                |                 |                |            |
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+| TODO  | quote        |                            |                          | - language?    |                 |                |            |
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+| TODO  | group        |                            | - inline markup applied  | - language?    | as paragraph    | - endnotes     |            |
+|       |              |                            | - [discard leading &     |                |                 | - bibliography |            |
+|       |              |                            | newline whitespace]      |                |                 |                |            |
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+| TODO  | block        |                            | - inline markup applied  |                | as paragraph    | - endnotes     |            |
+|       |              |                            | - whitespace indentation |                |                 | - bibliography |            |
+|       |              |                            | & newlines               |                |                 |                |            |
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+|       | poem / verse | open and close tags        | verse is the object      |                |                 | - endnotes     |            |
+|       |              |                            | - inline markup applied  |                |                 | - bibliography |            |
+|       |              | (for poem)                 | - whitespace indentation |                |                 |                |            |
+|       |              |                            | & newlines               |                |                 |                |            |
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+|       | code         |                            | - contents untouched     | - syntax       |                 |                |            |
+|       |              |                            | - whitespace indentation | - numbered     |                 |                |            |
+|       |              |                            | & newlines               |                |                 |                |            |
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+|       | table        |                            |                          | - column width |                 |                |            |
+|       |              |                            |                          | - heading row  |                 |                |            |
+|-------+--------------+----------------------------+--------------------------+----------------+-----------------+----------------+------------|
+
+**** ocn
+
+|-------------+-----------------------+-----------------------+----------------+------|
+| objects     | section / part        | ocn described         | how used       | type |
+|-------------+-----------------------+-----------------------+----------------+------|
+| regular ocn |                       |                       |                |      |
+|-------------+-----------------------+-----------------------+----------------+------|
+|             | body objects          | seq. digit            | anchor         | ocn  |
+|             |                       | [0-9]+                | visible        |      |
+|-------------+-----------------------+-----------------------+----------------+------|
+|             | glossary objects      | seq. digit            | anchor         | ocn  |
+|             |                       | [0-9]+                | not-visible    |      |
+|             |                       |                       | (for search)   |      |
+|-------------+-----------------------+-----------------------+----------------+------|
+|             | bibliography objects  | seq. digit            | anchor         | ocn  |
+|             |                       | [0-9]+                | not-visible    |      |
+|             |                       |                       | (for search)   |      |
+|-------------+-----------------------+-----------------------+----------------+------|
+| special ocn |                       |                       |                |      |
+|-------------+-----------------------+-----------------------+----------------+------|
+|             | non-substantive text  | x char + seq. digit   | anchor         | non  |
+|             | (within body & blurb) | x[0-9]+               | not-visible    |      |
+|             |                       |                       | (for search)   |      |
+|-------------+-----------------------+-----------------------+----------------+------|
+|             | book index            | i char + seq. digit   | anchor         | idx  |
+|             |                       | i[0-9]+               | not-visible    |      |
+|             |                       |                       | (for search)   |      |
+|-------------+-----------------------+-----------------------+----------------+------|
+| without ocn |                       |                       |                |      |
+|-------------+-----------------------+-----------------------+----------------+------|
+|             | endnotes              | ocn of parent object  | no ocn         | fn   |
+|             |                       | + footnote seq. digit | anchor visible |      |
+|-------------+-----------------------+-----------------------+----------------+------|
+
+** make config - _composite make_
+
+work on composite make a unification of make instructions for each document run
+
+extract instructions from all config files, unify the make instructions and
+provide the result as a single set of make instructions for each document parsed
+
+- 1. general, document_make config file (to be applied to all documents unless
+  overridden by document or command line instruction)
+- 2. local, site specific (site local instructions such as the site's url, cgi
+  location etc.)
+- 3. each document header, make (the document header contains metadata and may
+  include make instructions for that document)
+  - make
+  - meta
+- 4. command line instruction, make (some make instructions may be passed
+  through the command line)
+
+*** instruction sources
+
+|----+---------------------------------+----------------------------------------+---------------------+---|
+|    | make instruction source         |                                        | varies (applies to) |   |
+|----+---------------------------------+----------------------------------------+---------------------+---|
+| 0. | unify the following as a single | take into account all the instructions |                     |   |
+|    | set of make instructions        | provided below, provide interface      |                     |   |
+|----+---------------------------------+----------------------------------------+---------------------+---|
+| 1. | document_make file              | to be applied to all documents         | per directory       |   |
+|    | "config_document"               | (unless subsequently overridden)       | (all docs within)   |   |
+|----+---------------------------------+----------------------------------------+---------------------+---|
+| 2. | config file                     | local site specific                    | per directory       |   |
+|    | "config_local_site"             |                                        | (all docs within)   |   |
+|----+---------------------------------+----------------------------------------+---------------------+---|
+| 3. | document header make            | make instructions contained            | per document        |   |
+|    |                                 | in document header                     | (single doc)        |   |
+|----+---------------------------------+----------------------------------------+---------------------+---|
+| 4. | command line instruction        | make instruction passed                | each command        |   |
+|    |                                 |                                        | (all docs within)   |   |
+|----+---------------------------------+----------------------------------------+---------------------+---|
+
+*** config & metadata (from instruction sources)
+
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     | 1. document make file    | 2. config file             | 3. document header     | 4. command line instruction |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+| comment, fixed:     | per dir (sisupod)        | per dir                    | per document (sisupod) | per command instruction     |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     | sdl_root_config_document | sdl_root_config_local_site |                        |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+| local site specific |                          | *                          |                        | *?                          |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          | webserv                    |                        |                             |
+|                     |                          | - url_root                 |                        |                             |
+|                     |                          | - path                     |                        |                             |
+|                     |                          | - images                   |                        |                             |
+|                     |                          | - cgi                      |                        |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          | webserv_cgi                |                        |                             |
+|                     |                          | - host                     |                        |                             |
+|                     |                          | - base_path                |                        |                             |
+|                     |                          | - port                     |                        |                             |
+|                     |                          | - user                     |                        |                             |
+|                     |                          | - file_links               |                        |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          | processing                 |                        |                             |
+|                     |                          | - path                     |                        |                             |
+|                     |                          | - dir                      |                        |                             |
+|                     |                          | - concord_max              |                        |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          | flag (configure)           |                        | (call)                      |
+|                     |                          | - act0                     |                        | act0                        |
+|                     |                          | - act1                     |                        | act1                        |
+|                     |                          | - act2                     |                        | act2                        |
+|                     |                          | - act3                     |                        | act3                        |
+|                     |                          | - act4                     |                        | act4                        |
+|                     |                          | - act5                     |                        | act5                        |
+|                     |                          | - act6                     |                        | act6                        |
+|                     |                          | - act7                     |                        | act7                        |
+|                     |                          | - act8                     |                        | act8                        |
+|                     |                          | - act9                     |                        | act9                        |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          | default                    |                        |                             |
+|                     |                          | - papersize                |                        |                             |
+|                     |                          | - text_wrap                |                        |                             |
+|                     |                          | - emphasis                 |                        |                             |
+|                     |                          | - language                 |                        |                             |
+|                     |                          | - digest                   |                        |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          | permission                 |                        |                             |
+|                     |                          | - share_source             |                        |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          | program_select             |                        |                             |
+|                     |                          | - editor                   |                        |                             |
+|                     |                          | - epub_viewer              |                        |                             |
+|                     |                          | - html_viewer              |                        |                             |
+|                     |                          | - odf_viewer               |                        |                             |
+|                     |                          | - pdf_viewer               |                        |                             |
+|                     |                          | - xml_viewer               |                        |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          | search                     |                        |                             |
+|                     |                          | - flag                     |                        |                             |
+|                     |                          | - action                   |                        |                             |
+|                     |                          | - db                       |                        |                             |
+|                     |                          | - title                    |                        |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+| make instruction    | **                       | omit or override share?    | **                     | *?                          |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     | make                     | make                       | make                   |                             |
+|                     | - bold                   | - bold                     | - bold                 |                             |
+|                     | - breaks                 | - breaks                   | - breaks               |                             |
+|                     | - cover_image            | - cover_image              | - cover_image          |                             |
+|                     | - css                    | - css                      | - css                  |                             |
+|                     | - emphasis               | - emphasis                 | - emphasis             |                             |
+|                     | - footer                 | - footer                   | - footer               |                             |
+|                     | - headings               | - headings                 | - headings             |                             |
+|                     | - home_button_image      | - home_button_image        | - home_button_image    |                             |
+|                     | - home_button_text       | - home_button_text         | - home_button_text     |                             |
+|                     | - italics                | - italics                  | - italics              |                             |
+|                     | - num_top                | - num_top                  | - num_top              |                             |
+|                     | - auto_num_depth         | - auto_num_depth           | - auto_num_depth       |                             |
+|                     | - substitute             | - substitute               | - substitute           |                             |
+|                     | - texpdf_font            | - texpdf_font              | - texpdf_font          |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+| actions             |                          |                            |                        | *                           |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            |                        | assertions                  |
+|                     |                          |                            |                        | concordance                 |
+|                     |                          |                            |                        | debug                       |
+|                     |                          |                            |                        | digest                      |
+|                     |                          |                            |                        | docbook                     |
+|                     |                          |                            |                        | epub                        |
+|                     |                          |                            |                        | html                        |
+|                     |                          |                            |                        | html-seg                    |
+|                     |                          |                            |                        | html-scroll                 |
+|                     |                          |                            |                        | manifest                    |
+|                     |                          |                            |                        | ocn                         |
+|                     |                          |                            |                        | odt                         |
+|                     |                          |                            |                        | pdf                         |
+|                     |                          |                            |                        | postgresql                  |
+|                     |                          |                            |                        | qrcode                      |
+|                     |                          |                            |                        | sisupod                     |
+|                     |                          |                            |                        | source                      |
+|                     |                          |                            |                        | sqlite                      |
+|                     |                          |                            |                        | sqlite-db-create            |
+|                     |                          |                            |                        | sqlite-db-drop              |
+|                     |                          |                            |                        | text                        |
+|                     |                          |                            |                        | verbose                     |
+|                     |                          |                            |                        | xhtml                       |
+|                     |                          |                            |                        | xml-dom                     |
+|                     |                          |                            |                        | xml-sax                     |
+|                     |                          |                            |                        | section_toc                 |
+|                     |                          |                            |                        | section_body                |
+|                     |                          |                            |                        | section_endnotes            |
+|                     |                          |                            |                        | section_glossary            |
+|                     |                          |                            |                        | section_biblio              |
+|                     |                          |                            |                        | section_bookindex           |
+|                     |                          |                            |                        | section_blurb               |
+|                     |                          |                            |                        | backmatter                  |
+|                     |                          |                            |                        | skip-output                 |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+| metadata            |                          |                            | *                      |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            | classify               |                             |
+|                     |                          |                            | - dewey                |                             |
+|                     |                          |                            | - keywords             |                             |
+|                     |                          |                            | - loc                  |                             |
+|                     |                          |                            | - subject              |                             |
+|                     |                          |                            | - topic_register       |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            | creator                |                             |
+|                     |                          |                            | - author               |                             |
+|                     |                          |                            | - author_email         |                             |
+|                     |                          |                            | - illustrator          |                             |
+|                     |                          |                            | - translator           |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            | date                   |                             |
+|                     |                          |                            | - added_to_site        |                             |
+|                     |                          |                            | - available            |                             |
+|                     |                          |                            | - created              |                             |
+|                     |                          |                            | - issued               |                             |
+|                     |                          |                            | - modified             |                             |
+|                     |                          |                            | - published            |                             |
+|                     |                          |                            | - valid                |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            | identifier             |                             |
+|                     |                          |                            | - isbn                 |                             |
+|                     |                          |                            | - oclc                 |                             |
+|                     |                          |                            | - pg                   |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            | links                  |                             |
+|                     |                          |                            | - link                 |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            | notes                  |                             |
+|                     |                          |                            | - abstract             |                             |
+|                     |                          |                            | - description          |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            | original               |                             |
+|                     |                          |                            | - language             |                             |
+|                     |                          |                            | - source               |                             |
+|                     |                          |                            | - title                |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            | publisher              |                             |
+|                     |                          |                            | - name                 |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            | rights                 |                             |
+|                     |                          |                            | - copyright            |                             |
+|                     |                          |                            | - cover                |                             |
+|                     |                          |                            | - illustrations        |                             |
+|                     |                          |                            | - license              |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|
+|                     |                          |                            | title                  |                             |
+|                     |                          |                            | - edition              |                             |
+|                     |                          |                            | - full                 |                             |
+|                     |                          |                            | - language             |                             |
+|                     |                          |                            | - main                 |                             |
+|                     |                          |                            | - note                 |                             |
+|                     |                          |                            | - sub                  |                             |
+|                     |                          |                            | - subtitle             |                             |
+|---------------------+--------------------------+----------------------------+------------------------+-----------------------------|