path: root/org/sdp.org

#+TITLE: sdp hub
#+AUTHOR: Ralph Amissah
#+EMAIL: [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]]
#+DESCRIPTION for documents - structuring, publishing in multiple formats and search
#+KEYWORDS
#+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
#+FILETAGS: :sdp:rel:hub:
#+TAGS: assert(a) class(c) debug(d) mixin(m) sdp(s) tangle(T) template(t) WEB(W) noexport(n)

[[../maker.org][maker.org makefile]]  [[./][org/]]
* 0. version.txt (set version)                                      :version:
** set program version

#+NAME: version_txt
#+BEGIN_SRC d  :tangle ../views/version.txt
/+ obt - org generated file +/
struct Version {
  int major;
  int minor;
  int patch;
}
enum ver = Version(0, 19, 0);
#+END_SRC

#+NAME: version_txt

** 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. sdp (sisu document parser)                                         :sdp:

- 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:

#+BEGIN_SRC d  :tangle ../src/sdp/sdp.d :shebang #!/usr/bin/env rdmd
/+
  sdp: sisu document parser
       a SiSU document parser writen in D
       see http://sisudoc.org.
+/
module sdp.sisu_document_parser;
import
  sdp.conf.compile_time_info,
  sdp.meta.metadoc;
<<imports_sdp>>
<<mixin_sdp_version>>
<<mixin_pre_main>>
/++ A SiSU document parser writen in D. +/
void main(string[] args) {
  <<sdp_mixin>>
  <<sdp_args>>
  <<sdp_env>>
  <<sdp_do_selected>>
  if (fns_src.length > 0) {
    foreach(fn_src; fns_src) {
      if (!empty(fn_src)) {
        <<sdp_each_file_do_scope>>
        <<sdp_abstraction>>
        <<sdp_each_file_do_debugs_checkdoc>>
        <<sdp_each_file_do_selected_output>>
        <<sdp_each_file_do_scope_exit>>
      } else {
        <<sdp_no_filename_provided>>
      }
    }
  }
}
unittest {
  /++
  name        "sdp"
  description "A SiSU document parser writen in D."
  homepage    "http://sisudoc.org"
  +/
}
#+END_SRC

** 1. pre-loop init                                                   :init:
*** init
**** imports                                                      :import:
***** sdp                                                           :sdp:

#+NAME: imports_sdp
#+BEGIN_SRC d
import sdp.meta;
import
  std.getopt,
  std.process;
import
  sdp.meta.metadoc_summary,
  sdp.meta.metadoc_from_src,
  sdp.meta.conf_make_meta,
  // sdp.meta.conf_make_meta_native,
  sdp.meta.conf_make_meta_sdlang,
  sdp.meta.conf_make_meta_composite,
  sdp.meta.defaults,
  sdp.meta.doc_debugs,
  sdp.meta.read_config_files,
  sdp.meta.read_source_files,
  sdp.meta.rgx,
  sdp.output.hub,
  sdp.output.paths_source;
#+END_SRC

****** notes
├── src
│   ├── sdp.d
│   └── sdp
│       ├── metadoc_from_src.d
│       ├── ...
│       └── compile_time_info.d
└── 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]]
[[./meta_read_source_files.org][meta_read_source_files]]
[[./compile_time_info.org][compile time info]]
[[./output.org][output]]
[[./sdp.org][sdp]]

keep up to date, configuration in ../maker.org
check:
- http://github.com/Abscissa/SDLang-D
- https://github.com/abscissa/libInputVisitor

sdlang.parser,
sdlang.exceptions;

std.conv,
std.variant,

**** mixins                                                        :mixin:
***** version.txt                                               :version:

#+NAME: mixin_sdp_version
#+BEGIN_SRC d
mixin(import("version.txt"));
#+END_SRC

***** pre main mixins
#+NAME: mixin_pre_main
#+BEGIN_SRC d
mixin CompileTimeInfo;
#+END_SRC

***** sdp "main" mixins                                             :sdp:

#+NAME: sdp_mixin
#+BEGIN_SRC d
mixin SiSUrgxInit;
mixin SiSUregisters;
mixin SiSUextractSDLang;
mixin SiSUnode;
mixin SiSUbiblio;
mixin SiSUrgxInitFlags;
mixin outputHub;
#+END_SRC

**** init                                                           :init:

#+NAME: sdp_args
#+BEGIN_SRC d
string[] fns_src;
string flag_action;
string arg_unrecognized;
enum dAM { abstraction, matters }
static auto rgx = Rgx();
#+END_SRC

*** scope (run complete)                                            :scope:

#+NAME: sdp_args
#+BEGIN_SRC d
scope(success) {
  debug(checkdoc) {
    writefln(
      "~ run complete, ok ~ (sdp-%s.%s.%s, %s v%s, %s %s)",
      ver.major, ver.minor, ver.patch,
      __VENDOR__, __VERSION__,
      bits, os,
    );
  }
}
scope(failure) {
  debug(checkdoc) {
    stderr.writefln(
      "run failure",
    );
  }
}
#+END_SRC

*** config files and command line arguements
**** 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]]

#+NAME: sdp_args
#+BEGIN_SRC d
bool[string] opts = [
  "assertions"         : false,
  "concordance"        : false,
  "debug"              : false,
  "digest"             : false,
  "docbook"            : false,
  "epub"               : false,
  "html"               : false,
  "html-seg"           : false,
  "html-scroll"        : false,
  "manifest"           : false,
  "ocn"                : true,
  "odt"                : false,
  "pdf"                : false,
  "postgresql"         : false,
  "qrcode"             : false,
  "sisupod"            : false,
  "source"             : false,
  "sqlite"             : false,
  "sqlite-create"      : false,
  "sqlite-drop"        : false,
  "text"               : false,
  "verbose"            : false,
  "xhtml"              : false,
  "xml-dom"            : false,
  "xml-sax"            : 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,
];
auto helpInfo = getopt(args,
  std.getopt.config.passThrough,
  "assert",             "--assert set optional assertions on",                        &opts["assertions"],
  "concordance",        "--concordance file for document",                            &opts["concordance"],
  "debug",              "--debug only relevant when debug options compiled in",       &opts["debug"],
  "digest",             "--digest hash digest for each object",                       &opts["digest"],
  "docbook",            "--docbook process docbook output",                           &opts["docbook"],
  "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"],
  "odf",                "--odf process odf:odt output",                               &opts["odt"],
  "odt",                "--odt process odf:odt output",                               &opts["odt"],
  "pdf",                "--pdf process pdf output",                                   &opts["pdf"],
  "pg",                 "--pg process postgresql output",                             &opts["postgresql"],
  "postgresql",         "--postgresql process postgresql output",                     &opts["postgresql"],
  "qrcode",             "--qrcode with document metadata",                            &opts["qrcode"],
  "sisupod",            "--sisupod sisupod source content bundled",                   &opts["sisupod"],
  "source",             "--source markup source text content",                        &opts["source"],
  "sqlite-create",      "--sqlite-create create db, create tables",                   &opts["sqlite-create"],
  "sqlite-drop",        "--sqlite-drop drop tables & db",                             &opts["sqlite-drop"],
  "sqlite",             "--sqlite process sqlite output",                             &opts["sqlite"],
  "text",               "--text process text output",                                 &opts["text"],
  "txt",                "--txt process text output",                                  &opts["text"],
  "verbose|v",          "--verbose output to terminal",                               &opts["verbose"],
  "xhtml",              "--xhtml process xhtml output",                               &opts["xhtml"],
  "xml-dom",            "--xml-dom process xml dom output",                           &opts["xml-dom"],
  "xml-sax",            "--xml-sax process xml sax output",                           &opts["xml-sax"],
  "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"],
);
if (helpInfo.helpWanted) {
  defaultGetoptPrinter("Some information about the program.", helpInfo.options);
}
foreach(arg; args[1..$]) {
  if (arg.match(rgx.flag_action)) {
    flag_action ~= " " ~ arg;   // flags not taken by getopt
  } else if (arg.match(rgx.src_pth)) {
    fns_src ~= arg;             // gather input markup source file names for processing
  } else {                      // anything remaining, unused
    arg_unrecognized ~= " " ~ arg;
  }
}
#+END_SRC

**** environment                                             :environment:

#+NAME: sdp_env
#+BEGIN_SRC d
auto env = [
  "pwd" : environment["PWD"],
  "home" : environment["HOME"],
];
#+END_SRC

**** TODO config files (load & read) (so far only SDLang)   :config:files:

#+NAME: sdp_conf_files
#+BEGIN_SRC d
auto sdl_root_config_share = configRead!()("config_share", env);
auto sdl_root_config_local = configRead!()("config_local", env);
auto conf_files_composite_make = confFilesSDLtoStruct!()(sdl_root_config_share, sdl_root_config_local);
#+END_SRC

** 2a. actions independed of processing files
#+NAME: sdp_do_selected
#+BEGIN_SRC d
if (!(opts["skip-output"])) {
  outputHubOp!()(opts);
}
#+END_SRC

** _2b. processing: loop each file_ [+2]                          :loop:files:
*** scope (loop)                                                    :scope:

#+NAME: sdp_each_file_do_scope
#+BEGIN_SRC d
scope(success) {
  debug(checkdoc) {
    writefln(
      "%s\n%s",
      "~ document complete, ok ~",
      "------------------------------------------------------------------",
    );
  }
}
scope(failure) {
  debug(checkdoc) {
    stderr.writefln(
      "~ document run failure ~ (%s  v%s)\n\t%s",
      __VENDOR__, __VERSION__,
      fn_src
    );
  }
}
enforce(
  fn_src.match(rgx.src_pth),
  "not a sisu markup filename"
);
#+END_SRC

*** 1. _document abstraction_ [#A]

- return tuple of:
  - doc_abstraction (the document)
  - doc_matters

#+NAME: sdp_abstraction
#+BEGIN_SRC d
auto t = SiSUabstraction!()(fn_src, opts, env);
static assert(!isTypeTuple!(t));
static assert(t.length==2);
auto doc_abstraction = t[dAM.abstraction];
auto doc_matters = t[dAM.matters];
#+END_SRC

*** 2. _output processing_ (post abstraction processing)
**** 0. abstraction _print summary_                    :abstraction:summary:

#+NAME: sdp_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: sdp_each_file_do_debugs_checkdoc
#+BEGIN_SRC d
/+ ↓ debugs +/
if ((doc_matters.opt_action["debug"])
|| (doc_matters.opt_action["verbose"])
) {
  SiSUdebugs!()(doc_abstraction, doc_matters);
}
#+END_SRC

**** 2. _process outputs_                                          :outputs:
- [[./output_hub.org][output_hub]]

#+NAME: sdp_each_file_do_selected_output
#+BEGIN_SRC d
/+ ↓ output hub +/
if (!(opts["skip-output"])) {
  outputHub!()(doc_abstraction, doc_matters);
}
#+END_SRC

*** scope (on loop exit)                                       :scope:exit:

#+NAME: sdp_each_file_do_scope_exit
#+BEGIN_SRC d
scope(exit) {
  debug(checkdoc) {
    writefln(
      "processed file: %s",
      fn_src
    );
  }
  destroy(fn_src);
}
#+END_SRC

** +2c. no valid filename provided+
#+NAME: sdp_no_filename_provided
#+BEGIN_SRC d
/+ no recognized filename provided +/
writeln("no recognized filename");
break; // terminate, stop
#+END_SRC

* 2. _document abstraction functions_                  :module:sdp:abstraction:
** 0. module template

#+BEGIN_SRC d  :tangle ../src/sdp/meta/metadoc.d
module sdp.meta.metadoc;
template SiSUabstraction() {
  <<imports_sdp>>
  <<sdp_mixin>>
  enum headBody { header, body_content, insert_filelist }
  enum makeMeta { make, meta }
  enum docAbst  { doc_abstraction, section_keys, segnames, segnames_0_4, images }
  static auto rgx = Rgx();
  auto SiSUabstraction(Fn,O,E)(
    Fn fn_src,
    O opts,
    E env,
  ){
    <<sdp_conf_files>>
    <<sdp_each_file_do_read_and_split_sisu_markup_file_content_into_header_and_body>>
    <<sdp_each_file_do_split_sisu_markup_file_header_into_make_and_meta>>
    <<sdp_each_file_do_document_abstraction>>
    <<sdp_each_file_do_document_matters>>
    auto t = tuple(doc_abstraction, doc_matters);
    static assert(t.length==2);
    return t;
  }
}
#+END_SRC

** 1. (a) _read in raw file_ (b) split content into: _doc header & doc content_
- [[./meta_read_source_files.org][meta_read_source_files]]

- read in the source marked up document and
  - split the document into:
    - document header
    - document body
  - if a master document make a list of insert files
- return a tuple of:
  - header
  - body
  - insert file list

#+NAME: sdp_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 +/
auto _header_body_inserts =
  SiSUrawMarkupContent!()(fn_src);
static assert(!isTypeTuple!(_header_body_inserts));
static assert(_header_body_inserts.length==3);
debug(header_and_body) {
  writeln(header);
  writeln(_header_body_inserts.length);
  writeln(_header_body_inserts.length[headBody.body_content][0]);
}
#+END_SRC

** 2. _document metadata_ & _make instructions_       :doc:header:metadata:make:
- [[./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: sdp_each_file_do_split_sisu_markup_file_header_into_make_and_meta
#+BEGIN_SRC d
/+ ↓ split header into make and meta +/
auto _make_and_meta_struct =
  docHeaderMakeAndMetaTupExtractAndConvertToStruct!()(conf_files_composite_make, _header_body_inserts[headBody.header]); // breakage ...
#+END_SRC

** 3. _document abstraction, tuple_ (pre-output-processing)       :processing:
- [[./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: sdp_each_file_do_document_abstraction
#+BEGIN_SRC d
/+ ↓ document abstraction: process document, return abstraction as tuple +/
auto da = SiSUdocAbstraction!()(
  _header_body_inserts[headBody.body_content],
  _make_and_meta_struct,
  opts
);
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];
#+END_SRC

** 4. _document matters_ (doc info gathered, various sources)

- prepare document_matters, miscellany about processing and the document of use
  in downstream processing

#+NAME: sdp_each_file_do_document_matters
#+BEGIN_SRC d
struct DocumentMatters {
  auto keys_seq() {
    /+ contains .seg & .scroll sequences +/
    auto _k = _document_section_keys_sequenced;
    return _k;
  }
  string[] segnames() {
    string[] _k = _doc_html_segnames;
    return _k;
  }
  string[] segnames_lv_0_to_4() {
    string[] _k = _doc_epub_segnames_0_4;
    return _k;
  }
  auto conf_make_meta() {
    auto _k = _make_and_meta_struct;
    return _k;
  }
  auto source_filename() {
    string _k = fn_src;
    return _k;
  }
  auto src_path_info() {
    string _pwd = env["pwd"];
    auto _k = SiSUpathsSRC!()(_pwd, fn_src);
    return _k;
  }
  auto opt_action() {
    bool[string] _k = opts;
    return _k;
  }
  auto environment() {
    auto _k = env;
    return _k;
  }
  auto language() {
    string _k;
    if (auto m = fn_src.match(rgx.language_code_and_filename)) {
      _k = m.captures[1];
    } else {
      _k = "en";
    }
    return _k;
  }
  auto file_insert_list() {
    string[] _k = _header_body_inserts[headBody.insert_filelist];
    return _k;
  }
  auto image_list() {
    auto _k = _images;
    return _k;
  }
}
auto doc_matters = DocumentMatters();
#+END_SRC

* 3. document abstraction _summary_            :module:sdp:metadoc_summary:
** 0. module template

#+BEGIN_SRC d :tangle ../src/sdp/meta/metadoc_summary.d
module sdp.meta.metadoc_summary;
template SiSUabstractionSummary() {
  auto SiSUabstractionSummary(S,T)(
    auto return ref const S  doc_abstraction,
    auto return 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
  sdp.meta.defaults,
  sdp.meta.rgx;
import
  std.array,
  std.exception,
  std.stdio,
  std.regex,
  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_obj_cite_number" : "NA [debug \"checkdoc\" not run]",
  "last_obj_cite_number_body"  : "0",
  "last_obj_cite_number_bkidx" : "0",
];
foreach (k; doc_matters.keys_seq.seg) {
  foreach (obj; doc_abstraction[k]) {
    if (obj.of_part != "empty") {
      if (!empty(obj.obj_cite_number)) {
        if (k == "body") {
          check["last_obj_cite_number_body"] = obj.obj_cite_number;
        }
        if (!(obj.obj_cite_number.empty)) {
          check["last_obj_cite_number"] = obj.obj_cite_number;
        }
      }
      if (k == "bookindex_seg") {
        if (obj.obj_cite_number_type == 2) {
          check["last_obj_cite_number_bkidx"] = obj.obj_cite_number_bkidx;
        }
      }
    }
  }
}
#+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(%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.source_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_obj_cite_number_body"]),
  "last obj_cite_number:",
  to!int(check["last_obj_cite_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_obj_cite_number_bkidx"]),
  "length blurb:",
  (doc_abstraction["blurb"].length > 1)
  ? (to!int(doc_abstraction["blurb"].length))
  : 0,
  __FILE__,
  __LINE__,
  markup.repeat_character_by_number_provided("-", min_repeat_number),
);
#+END_SRC

* __END__
dev notes

** sdp glossary / terms

|------+-------------------------------------|
| sdp  | 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_share"                  | (unless subsequently overridden)       | (all docs within)   |   |
|----+---------------------------------+----------------------------------------+---------------------+---|
| 2. | config file                     | local site specific                    | per directory       |   |
|    | "config_local"                  |                                        | (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_share | sdl_root_config_local   |                        |                             |
|---------------------+-----------------------+-------------------------+------------------------+-----------------------------|
| 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              |                             |
|                     | - num_depth           | - num_depth             | - 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-create               |
|                     |                       |                         |                        | sqlite-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             |                             |
|---------------------+-----------------------+-------------------------+------------------------+-----------------------------|