primarily org related

1 files changed, 72 insertions, 51 deletions

diff --git a/org/spine.org b/org/spine.org
index 2696511..d9db466 100644
--- a/org/spine.org
+++ b/org/spine.org
@@ -1,5 +1,5 @@
 -*- mode: org -*-
-#+TITLE:       spine (doc_reform) hub
+#+TITLE:       spine ≅ (doc-reform) hub
 #+DESCRIPTION: documents - structuring, various output representations & search
 #+FILETAGS:    :spine:hub:
 #+AUTHOR:      Ralph Amissah
@@ -44,7 +44,7 @@
 module doc_reform.sisu_document_parser;
 /++
 name        "spine"
-description "A SiSU inspired document parser writen in D."
+description "A SiSU inspired document parser written in D."
 homepage    "https://sisudoc.org"
 +/
 <<imports_spine>>
@@ -55,17 +55,17 @@ string project_name = "spine";
 string program_name = "spine";
 @system void main(string[] args) {
   <<spine_mixin>>
-  <<spine_init_0>>
-  <<spine_init_1>>
-  <<spine_init_2>>
-  <<spine_args_0_args_init_opts>>
-  <<spine_args_0_args_init_settings>>
-  <<spine_args_1_args_get_options_aa>>
-  <<spine_args_2_args_get_options_aa2str>>
-  <<spine_args_3_program_info>>
-  <<spine_args_4_get_configuration_details>>
-  <<spine_args_5_call_output_hub>>
-  <<spine_args_6_process_args>>
+  <<spine_init_curate_metadata>>
+  <<spine_init_few>>
+  <<spine_init_scope>>
+  <<spine_args_init_opts>>
+  <<spine_args_init_settings>>
+  <<spine_args_get_options_aa>>
+  <<spine_args_get_options_aa2str>>
+  <<spine_args_program_info>>
+  <<spine_args_get_configuration_details>>
+  <<spine_args_call_output_hub>>
+  <<spine_args_process_args>>
   if (_manifests.length > 1                            // _manifests[0] initialized dummy element
   && _opt_action.abstraction) {
     if (_opt_action.parallelise) {                     // see else
@@ -74,12 +74,7 @@ string program_name = "spine";
         if (!empty(manifest.src.filename)) {
           <<spine_each_file_do_scope>>
           <<spine_each_file_do_abstraction>>
-          <<spine_each_file_do_debugs_checkdoc_0>>
-          <<spine_each_file_do_debugs_checkdoc_1>>
-          <<spine_each_file_do_debugs_checkdoc_2>>
-          <<spine_each_file_do_debugs_checkdoc_3>>
-          <<spine_each_file_do_debugs_checkdoc_4>>
-          <<spine_each_file_do_debugs_checkdoc_5>>
+          <<spine_each_file_do_show>>
           <<spine_each_file_do_selected_output>>
           <<spine_each_file_do_scope_exit>>
         } else {
@@ -94,12 +89,7 @@ string program_name = "spine";
         if (!empty(manifest.src.filename)) {
           <<spine_each_file_do_scope>>
           <<spine_each_file_do_abstraction>>
-          <<spine_each_file_do_debugs_checkdoc_0>>
-          <<spine_each_file_do_debugs_checkdoc_1>>
-          <<spine_each_file_do_debugs_checkdoc_2>>
-          <<spine_each_file_do_debugs_checkdoc_3>>
-          <<spine_each_file_do_debugs_checkdoc_4>>
-          <<spine_each_file_do_debugs_checkdoc_5>>
+          <<spine_each_file_do_show>>
           <<spine_each_file_do_selected_output>>
           <<spine_each_file_do_scope_exit>>
         } else {
@@ -175,7 +165,7 @@ string program_name = "spine";
     - docReform object numbering
       - standard SiSU object citation numbering & system
 
-  - Hompages:
+  - Homepages:
     [https://www.doc_reform.org]
     [https://www.sisudoc.org]
 
@@ -292,14 +282,14 @@ mixin outputHub;
 
 **** init :init:
 
-#+NAME: spine_init_0
+#+NAME: spine_init_curate_metadata
 #+BEGIN_SRC d
 auto hvst = spineCurateMetadata!();
 #+END_SRC
 
 **** args :args:
 
-#+NAME: spine_init_1
+#+NAME: spine_init_few
 #+BEGIN_SRC d
 string flag_action;
 string arg_unrecognized;
@@ -309,7 +299,7 @@ static auto rgx = RgxI();
 
 *** scope (run complete) :scope:
 
-#+NAME: spine_init_2
+#+NAME: spine_init_scope
 #+BEGIN_SRC d
 scope(success) {
   writefln(
@@ -335,7 +325,7 @@ scope(failure) {
 
 ***** initialize opts
 
-#+NAME: spine_args_0_args_init_opts
+#+NAME: spine_args_init_opts
 #+BEGIN_SRC d
 bool[string] opts = [
   "abstraction"                 : false,
@@ -347,11 +337,11 @@ bool[string] opts = [
   "debug"                       : false,
   "digest"                      : false,
   "epub"                        : false,
-  "curate"                     : false,
-  "curate-authors"             : false,
-  "curate-topics"              : false,
+  "curate"                      : false,
+  "curate-authors"              : false,
+  "curate-topics"               : false,
   "html"                        : false,
-  "html-link-curate"           : false,
+  "html-link-curate"            : false,
   "html-link-search"            : false,
   "html-seg"                    : false,
   "html-scroll"                 : false,
@@ -403,9 +393,27 @@ bool[string] opts = [
 
 ***** initialize settings
 
-see also: config_d_cfte.org
-
-#+NAME: spine_args_0_args_init_settings
+NOTES on configuration hierarchy:
+- compile time program defaults views/configuration.txt in config_d_cfte.org
+  - config_d_cfte.org (writes views/configuration.txt)
+    - compile time program defaults, set in views/configuration.txt
+    - found in: _cfg.*
+- run time default configuration administrators config ".dr/config_site_local"
+  - in_source_files.org readConfigSite (reads administrators site defaults from
+    yaml config file)
+  - meta_conf_make_meta.org struct ConfCompositeSiteLocal
+    - administrator site defaults read from yaml configuration file
+      ".dr/config_site_local"
+    - found in: "doc_matters.conf_make_meta.conf." (incorporates _cfg.* as
+      initial default values that are overridden if set)
+    - ("conf_make_meta.make" (& "conf_make_meta.meta") also available taken from
+      document headers)
+- command line execution configuration instruction
+  - spine.org (org heading: initialize settings) (command line overrides)
+    - command line settings/overrides
+    - found in: doc_matters.opt.action.*
+
+#+NAME: spine_args_init_settings
 #+BEGIN_SRC d
 string[string] settings = [
   "output"                      : "",    //_cfg.www_doc_root,          // "/srv/www/spine/static" or "/var/www/html"
@@ -413,6 +421,8 @@ string[string] settings = [
   "www-host"                    : "",    //_cfg.www_host,              // start with "localhost" ?
   "www-host-doc-root"           : "",    //_cfg.www_host_doc_root,     // start with "localhost" ?
   "www-url-doc-root"            : "",    //_cfg.www_url_doc_root,      // start with "http://localhost" ?
+  "cgi-http"                    : "",    //_cfg.cgi_http,              // suggest
+  "cgi-host"                    : "",    //_cfg.cgi_host,              // suggest
   "cgi-bin-root"                : "",    //_cfg.cgi_bin_root,          // suggest "/var/www/cgi/cgi-bin"
   "cgi-sqlite-search-filename"  : "",    //_cfg.cgi_filename,          // suggest "spine_search" (though "spine-search" would have been preferable?)
   "cgi-url-root"                : "",    //_cfg.cgi_url_root,          // start with "http://localhost/cgi-bin" ?
@@ -430,7 +440,7 @@ string[string] settings = [
 
 ***** set & describe
 
-#+NAME: spine_args_1_args_get_options_aa
+#+NAME: spine_args_get_options_aa
 #+BEGIN_SRC d
 auto helpInfo = getopt(args,
   std.getopt.config.passThrough,
@@ -524,7 +534,7 @@ if (helpInfo.helpWanted) {
 **** getopt hash to struct
 - move getopt options to struct
 
-#+NAME: spine_args_2_args_get_options_aa2str
+#+NAME: spine_args_get_options_aa2str
 #+BEGIN_SRC d
 enum outTask { source_or_pod, sqlite, sqlite_multi, latex, odt, epub, html_scroll, html_seg, html_stuff }
 struct OptActions {
@@ -752,7 +762,7 @@ struct OptActions {
     return settings["www-host-doc-root"];
   }
   @trusted string  webserver_url_doc_root() {
-    return settings["www-url-root"];
+    return settings["www-url-doc-root"];
   }
   @trusted string  webserver_http() {
     return settings["www-http"];
@@ -879,7 +889,7 @@ OptActions _opt_action = OptActions();
 **** env
 - environmental info
 
-#+NAME: spine_args_3_program_info
+#+NAME: spine_args_program_info
 #+BEGIN_SRC d
 @safe auto program_info() {
   struct ProgramInfo {
@@ -911,12 +921,12 @@ auto _env = [
 
 *** get/read site config
 
-#+NAME: spine_args_4_get_configuration_details
+#+NAME: spine_args_get_configuration_details
 #+BEGIN_SRC d
 auto _manifested = PathMatters!()(_opt_action, _env, "");
 auto _manifests = [ _manifested ];
 auto _conf_file_details = configFilePaths!()(_manifested, _env, _opt_action.config_path_set);
-ConfComposite _config;
+ConfComposite _siteConfig;
 if (
   _opt_action.require_processing_files
   && _opt_action.config_path_set.empty
@@ -928,7 +938,7 @@ if (
         _conf_file_details = configFilePaths!()(_manifested, _env, _opt_action.config_path_set);
         auto _config_local_site_struct = readConfigSite!()(_conf_file_details, _opt_action, _cfg);
         import doc_reform.meta.conf_make_meta_yaml;
-        _config = _config_local_site_struct.configParseYAMLreturnSpineStruct!()(_config, _manifested, _opt_action); // - get local site config
+        _siteConfig = _config_local_site_struct.configParseYAMLreturnSpineStruct!()(_siteConfig, _manifested, _opt_action); // - get local site config
         break;
       }
     }
@@ -936,17 +946,17 @@ if (
 } else { /+ local site config +/
   auto _config_local_site_struct = readConfigSite!()(_conf_file_details, _opt_action, _cfg);
   import doc_reform.meta.conf_make_meta_yaml;
-  _config = _config_local_site_struct.configParseYAMLreturnSpineStruct!()(_config, _manifested, _opt_action); // - get local site config
+  _siteConfig = _config_local_site_struct.configParseYAMLreturnSpineStruct!()(_siteConfig, _manifested, _opt_action); // - get local site config
 }
 if (_opt_action.show_config) {
   import doc_reform.meta.metadoc_show_config;
-  spineShowSiteConfig!()(_opt_action, _config);
+  spineShowSiteConfig!()(_opt_action, _siteConfig);
 }
 #+END_SRC
 
 *** use config for operations that do not require file processing
 
-#+NAME: spine_args_5_call_output_hub
+#+NAME: spine_args_call_output_hub
 #+BEGIN_SRC d
 if (!(_opt_action.skip_output)) {
   if ((_opt_action.debug_do)
@@ -954,7 +964,7 @@ if (!(_opt_action.skip_output)) {
   ) {
     writeln("step0 commence → (without processing files)");
   }
-  outputHubOp!()(_env, _opt_action, _config);
+  outputHubOp!()(_env, _opt_action, _siteConfig);
   if ((_opt_action.debug_do)
   || (_opt_action.very_verbose)
   ) {
@@ -965,10 +975,10 @@ if (!(_opt_action.skip_output)) {
 
 *** opt action on processing files (loop args)
 
-#+NAME: spine_args_6_process_args
+#+NAME: spine_args_process_args
 #+BEGIN_SRC d
-ConfComposite _make_and_meta_struct = _config;
-destroy(_config);
+ConfComposite _make_and_meta_struct = _siteConfig;
+destroy(_siteConfig);
 foreach(arg; args[1..$]) {
   if (arg.match(rgx.flag_action)) { /+ cli instruction, flag do +/
     flag_action ~= " " ~ arg;   // flags not taken by getopt
@@ -1200,6 +1210,17 @@ if ((doc_matters.opt.action.debug_do)
 *** 2. _output processing_ (post abstraction processing)
 **** 0. abstraction
 ***** show document summary - abstraction _print summary_ (to screen) :abstraction:summary:
+
+#+NAME: spine_each_file_do_show
+#+BEGIN_SRC d
+<<spine_each_file_do_debugs_checkdoc_0>>
+<<spine_each_file_do_debugs_checkdoc_1>>
+<<spine_each_file_do_debugs_checkdoc_2>>
+<<spine_each_file_do_debugs_checkdoc_3>>
+<<spine_each_file_do_debugs_checkdoc_4>>
+<<spine_each_file_do_debugs_checkdoc_5>>
+#+END_SRC
+
 --show-summary (abstraction summary)
 
 #+NAME: spine_each_file_do_debugs_checkdoc_0