work on more generic install + instructions

1 files changed, 224 insertions, 152 deletions

diff --git a/README b/README
index 2695e17..d1a6c1f 100644
--- a/README
+++ b/README
@@ -40,176 +40,137 @@ project_name:  Spine, Doc Reform
 
 * Installation, Compilation
 
-SiSU spine is written in the programming language D for which there are 3 compilers:
+Development of sisudoc-spine started in 2015 on a Debian linux box.
 
-- dmd
-- ldc
-- gdc
+Development since 2020 has been on a NixOS linux box, my laptop. If you are
+fortunate enough to be using the same the build instructions should be presented
+on entering the sisudoc-spine directory. It should be little problem building on
+other linuxes with the right dependencies. At one time, debconf-18 I was
+persuaded to try meson, and for a couple of years maintained a meson build, that
+dropped out of use before or on my making the switch to nixos in 2020.
+
+❯❯ D compiler and build manager
+
+SiSU spine is written in the programming language D for which there are 3
+compilers: dmd, ldc, gdc
+- https://wiki.dlang.org/Compilers
 
 D projects tend to use dub as project manager
-https://code.dlang.org/packages/dub
-https://code.dlang.org/packages/dub
-https://github.com/dlang/dub/blob/master/source/dub/commandline.d
+- https://code.dlang.org/packages/dub
+- https://github.com/dlang/dub/blob/master/source/dub/commandline.d
+
+The default build tools used are dub with ldc2 (dub is also tested)
+
+** make a directory and clone the sisudoc-spine project-heading
+
+# make a directory and clone the sisudoc-spine project
+
+  mkdir ~/git.sisudoc
+  cd ~/git.sisudoc
+
+  git clone git://git.sisudoc.org/software/sisudoc-spine && \
+  git clone git://git.sisudoc.org/software/sisudoc-spine-search-cgi && \
+  git clone git://git.sisudoc.org/markup/sisudoc-spine-samples
+
+such a relative directory layout will be assumed in the examples that provided
+
+** build sisudoc-spine
+
+## directly with dub
+### ldc2
 
-  dub --compiler=ldc2 -color --config=ldc -b release
+  dub --compiler=ldmd2 --config=ldmd2
+  dub --verbose --compiler=ldmd2 -color --config=ldmd2
 
-  dub --compiler=dmd -color --config=dmd
+  dub --compiler=ldc2 --config=ldc2
+  dub --verbose --compiler=ldc2 -color --config=ldc2
 
-  dub --compiler=gdc-10 -color --config=gdc -b release
+### dmd
+
+  dub --compiler=dmd --config=dmd
+
+## with make
+
+### ldc2
 
   make ldc
 
+### dmd
+
   make dmd
 
-there has been some coalescence around the Meson build system
-https://mesonbuild.com/
+## with nix on linux / nixos
 
-  meson
+### ldc2
 
-  ninja -C build
+  nix develop ".#dsh-nixpkgs-ldc-dub" --print-build-logs -c zsh
+  nix build ".#spine-nixpkgs-ldc" --print-build-logs
 
-  meson setup --wipe build && ninja -v -C build
+### dmd
+
+  nix develop ".#dsh-nixpkgs-dmd-dub" --print-build-logs -c zsh
+  nix build ".#spine-nixpkgs-dmd" --print-build-logs
+
+## the Meson build system was used briefly
+
+On recommendation at debconf-18 meson was used briefly. It has neither been tested nor used since the move to nix.
 
+- https://mesonbuild.com/
+
+  meson
+  ninja -C build
+  meson setup --wipe build && ninja -v -C build
   make meson
 
 dub --force --compiler=ldc2 && sudo cp -v cgi-bin/spine-search /usr/lib/cgi-bin/.
 
-* Configuration
-
-Configuration files are yaml files
-
-The following paths are searched:
-
-  ~/.dr/config_local_site
-  ~/path_to_pod_root/.dr/config_local_site
-
-e.g. processing
-
-  ~spineMarkupSamples/pod/*
-
-will search:
-
-  ~spineMarkupSamples/pod/.dr/config_local_site
-
-  ~/.dr/config_local_site
-
-to specify an alternative configuration file to use on the command line (in this
-example named "my_config"):
-
-  spine -v --html --config=~spineMarkupSamples/pod/.dr/my_config
-
-here is a sample configuration file:
-
-flag:
-  act0:                        "--html"
-  act1:                        "--html --epub"
-output:
-  path:                        "/var/www/html"
-default:
-  language:                    "en"
-  papersize:                   "a4"
-  text_wrap:                   "80"
-  digest:                      "sha256"
-webserv:
-  http:                        "http"
-  host:                        "localhost"
-  data_http:                   "http"
-  data_host:                   "localhost"
-  data_root_url:               "http://localhost"
-  data_root_path:              "/var/www/html"
-  data_root_part:              ""
-  images_root_part:            "image"
-  cgi_search_form_title:       "≅ SiSU Spine search ፨"
-  cgi_http:                    "http"
-  cgi_host:                    "localhost"
-  cgi_bin_url:                 "http://localhost/cgi-bin"
-  cgi_bin_subpath:             "/cgi-bin"
-  cgi_bin_path:                "/usr/lib/cgi-bin"
-  cgi_search_script:           "spine-search"
-  cgi_search_script_raw_fn_d:  "spine_search.d"
-  cgi_port:                    ""
-  cgi_user:                    ""
-  cgi_action:                  "http://localhost/cgi-bin/spine-search"
-  db_sqlite:                   "spine.search.db"
-  db_pg_table:                 ""
-  db_pg_user:                  ""
-
-* Commands
+* Document processing examples
+
+These examples assume the file layout suggested in cloning the git.sisudoc.org
+repository, i.e. that the directories sisudoc-spine and sisudoc-spine-samples
+are next to each other on a directory tree. Assuming this to be the case, you
+may wish to set the following exports with adjustments accoring to your specific
+needs for these examples.
+
+# ❯❯ set spine binary location:
+export SpineBIN=./result/bin/spine
+# ❯❯ nix builds spine binary:
+#export SpineBIN=./result/bin/spine
+# ❯❯ dub builds spine binary (name depends on build, check):
+#export SpineBIN=./bin/spine
+#export SpineBIN=./bin/spine-ldc
+#export SpineBIN=./bin/spine-dmd
+# ❯❯ location of source files:
+export SpineDOC=../sisudoc-spine-samples
+# ❯❯ location of source files pod:
+export SpinePOD=${SpineDOC}/markup/pod
+# ❯❯ sisudoc-spine output processing path:
+export SpineOUT=./OUTPUT_TEST_sisudocSpine
+# ❯❯ sisudoc-spine output processing path (web server e.g.):
+#export SpineOUT=/srv/www/spine
+export SpineSearchActionLocal='http://localhost/spine_search'
+export SpineSearchActionRemote='https://sisudoc.org/spine_search'
+# ❯❯ path configured for cgi search form:
+export SpineCGIform='spine_search'
+# ❯❯ search form db name:
+export SpineSQLdb='spine.search.db'
+# ❯❯ configuration cgi search form path:
+#export SpineCGIbin=/var/www/cgi/cgi-bin
+# ❯❯ configuration db path:
+#export SpineDBpath=/var/www/sqlite
 
-for a list of commands from the program type:
+*** html with links to search form
 
-  spine -h
+${SpineBIN} -v --epub --html --html-link-curate --curate --output=${SpineOUT} ${SpinePOD}/*
 
-at the time of writing this provides the following output:
+${SpineBIN} -v --source --pod --latex --latex-init --epub --html --html-link-pdf --html-link-curate --html-link-markup --curate --output=${SpineOUT} ${SpinePOD}/*
 
-                  --abstraction document abstraction
-                       --assert set optional assertions on
-      --cgi-search-form-codegen generates (pre-compiled) d code for search of specified db
-   --cgi-sqlite-search-filename =[filename]
-                  --concordance file for document
-                       --config =/path/to/config/file/including/filename
-                         --dark alternative dark theme
-                        --debug debug
-                       --digest hash digest for each object
-                         --epub process epub output
-                      --curate extract info on authors & topics from document header metadata
-              --curate-authors extract info on authors from document header metadata
-               --curate-topics extract info on topics from document header metadata
-                     --hide-ocn object cite numbers
-                         --html process html output
-            --html-link-curate place links back to curate in segmented html
-             --html-link-search html embedded search submission
-                     --html-seg process html output
-                  --html-scroll process html output
-                         --lang =[lang code e.g. =en or =en,es]
-                        --latex output for pdfs
-            --latex-color-links mono or color links for pdfs
-                        --light default light theme
-                     --manifest process manifest output
-                      --ocn-off object cite numbers
-                          --odf open document format text (--odt)
-                          --odt open document format text
-                       --output =/path/to/output/dir specify where to place output
-                     --parallel parallelisation
-        --parallel-subprocesses nested parallelisation
-                          --pdf latex output for pdfs
-              --pdf-color-links mono or color links for pdfs
-                          --pod spine (doc reform) pod source content bundled
--q                      --quiet output to terminal
-           --section-backmatter document backmatter (default)
-               --section-biblio document biblio (default)
-                --section-blurb document blurb (default)
-                 --section-body document body (default)
-            --section-bookindex document bookindex (default)
-             --section-endnotes document endnotes (default)
-             --section-glossary document glossary (default)
-                  --section-toc table of contents (default)
-                       --serial serial processing
-                  --skip-output skip output
-                  --show-config show config
-                    --show-make show make
-                --show-metadata show metadata
-                 --show-summary show summary
-                       --source document markup source
-              --sqlite-discrete process discrete sqlite output
-             --sqlite-db-create create db, create tables
-               --sqlite-db-drop drop tables & db
-           --sqlite-db-recreate create db, create tables
-                --sqlite-delete sqlite output
-              --sqlite-db-filename =[filename].sql.db
-                --sqlite-insert sqlite output
-                --sqlite-update sqlite output
-                         --text text output
-                   --theme-dark alternative dark theme
-                  --theme-light default light theme
-                          --txt text output
--v                    --verbose output to terminal
-                 --very-verbose output to terminal
-                       --workon (reserved for some matters under development & testing)
-                        --xhtml xhtml output
--h                       --help This help information.
+${SpineBIN} -v --source --pod --latex --latex-init --epub --html --html-link-search --html-link-pdf --html-link-curate --html-link-markup --cgi-sqlite-search-filename="${SpineCGIform}" --cgi-url-action="${SpineSearchActionLocal}" --curate --sqlite-update --sqlite-db-filename="${SpineSQLdb}" --output=${SpineOUT} ${SpinePOD}/*
 
-* Examples
+spine -v --html \
+  --html-link-search \
+  --output=`echo ~webDocRoot` \
+  ${SpinePOD}/*
 
 ** curate
 
@@ -232,7 +193,7 @@ if configuartion has been set specify just
 
   spine -v --html ~spineMarkupSamples/markup/pod/sisu-manual
 
-if configuartion has not been set or to overide the set configration specify
+if configuration has not been set or to overide the set configuration specify
 - the output path as well as
 - the desired output and
 - the markup document/pod(s) to process
@@ -327,6 +288,9 @@ cgi-bin directory
 
   spine -v --html --html-link-search --cgi-sqlite-search-filename="spine-search" --html-link-curate --curate --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
 
+  ${SpineBIN} -v --source --pod --latex --latex-init --epub --html --html-link-search --html-link-pdf --html-link-curate --html-link-markup --cgi-sqlite-search-filename="${SpineCGIform}" --cgi-url-action="${SpineSearchActionLocal}" --curate --sqlite-update --sqlite-db-filename="${SpineSQLdb}" --output=${SpineOUT} ${SpinePOD}/*
+
+
 *** create db & search form
 
   spine -v \
@@ -335,9 +299,117 @@ cgi-bin directory
     --output=/var/www/html \
     ~spineMarkupSamples/pod/*
 
-*** html with links to search form
+* Commands
 
-  spine -v --html \
-    --html-link-search \
-    --output=`echo ~webDocRoot` \
-    ~spineMarkupSamples/pod/*
+for a list of commands from the program type:
+
+  spine -h
+
+at the time of writing this provides the following output:
+                  --abstraction document abstraction
+              --allow-downloads allow downloads (includes cgi.d from github)
+                       --assert set optional assertions on
+                 --cgi-bin-root path to cgi-bin directory
+                 --cgi-url-root url to cgi-bin (to find cgi-bin)
+               --cgi-url-action url to post to cgi-bin search form
+             --cgi-search-title if generating a cgi search form the title to use for it
+   --cgi-sqlite-search-filename =[filename] default is spine-search
+                  --concordance file for document
+                       --curate extract info on authors & topics from document header metadata
+               --curate-authors extract info on authors from document header metadata
+                --curate-topics extract info on topics from document header metadata
+                         --dark alternative dark theme
+                       --digest hash digest for each object
+                         --epub process epub output
+                 --generated-by generated by headers (software version & time)
+                     --hide-ocn object cite numbers
+                         --html process html output
+             --html-link-curate place links back to curate in segmented html
+             --html-link-markup provide html link to markup source, shared optionally
+                --html-link-pdf provide html link to pdf a4 & letter output
+             --html-link-pdf-a4 provide html link to pdf a4 output
+         --html-link-pdf-letter provide html link to pdf letter size output
+             --html-link-search html embedded search submission
+                     --html-seg process html output
+                  --html-scroll process html output
+                         --lang =[lang code e.g. =en or =en,es]
+                        --latex latex output (for pdfs)
+            --latex-color-links mono or color links for pdfs
+                   --latex-init initialise latex shared files (see latex-header-sty)
+             --latex-header-sty latex document header sty files
+                        --light default light theme
+                     --manifest process manifest output
+                      --ocn-off object cite numbers
+                          --odf open document format text (--odt)
+                          --odt open document format text
+                       --output =/path/to/output/dir specify where to place output
+                     --parallel parallelisation
+        --parallel-subprocesses nested parallelisation
+                          --pdf latex output for pdfs
+              --pdf-color-links mono or color links for pdfs
+                     --pdf-init initialise latex shared files (see latex-header-sty)
+                          --pod spine (doc reform) pod source content bundled
+-q                      --quiet output to terminal
+           --section-backmatter document backmatter (default)
+               --section-biblio document biblio (default)
+                --section-blurb document blurb (default)
+                 --section-body document body (default)
+            --section-bookindex document bookindex (default)
+             --section-endnotes document endnotes (default)
+             --section-glossary document glossary (default)
+                  --section-toc table of contents (default)
+                       --serial serial processing
+                  --skip-output skip output
+                  --show-config show config
+                  --show-curate show curate
+          --show-curate-authors show curate authors
+           --show-curate-topics show curate topics
+                    --show-epub show epub
+                    --show-html show html
+                   --show-latex show latex
+                    --show-make show make
+                --show-manifest show manifest
+                --show-metadata show metadata
+                     --show-pod show pod
+                  --show-sqlite show sqlite
+                 --show-summary show summary
+                       --source document markup source
+                   --set-digest default hash digest type (e.g. sha256)
+                --set-papersize default papersize (latex pdf eg. a4 or a5 or b4 or letter)
+                 --set-textwrap default textwrap (e.g. 80 (characters)
+              --sqlite-discrete process discrete sqlite output
+             --sqlite-db-create create db, create tables
+               --sqlite-db-drop drop tables & db
+           --sqlite-db-filename sqlite db to create, populate & make available for search
+               --sqlite-db-path sqlite db path
+           --sqlite-db-recreate create db, create tables
+                --sqlite-delete sqlite output
+                --sqlite-insert sqlite output
+                --sqlite-update sqlite output
+                     --www-http http or https
+                     --www-host web server host (domain) name
+            --www-host-doc-root web host host (domain) name with path to doc root
+             --www-url-doc-root e.g. http://localhost
+                         --text text output
+                   --theme-dark alternative dark theme
+                  --theme-light default light theme
+                          --txt text output
+-v                    --verbose output to terminal
+                 --very-verbose output to terminal
+                       --workon (reserved for some matters under development & testing)
+                        --xhtml xhtml output
+                       --config =/path/to/config/file/including/filename
+                        --debug debug
+                 --debug-curate debug curate
+         --debug-curate-authors debug curate authors
+          --debug-curate-topics debug curate topics
+                   --debug-epub debug epub
+                --debug-harvest debug harvest
+                   --debug-html debug html
+                  --debug-latex debug latex
+               --debug-manifest debug manifest
+               --debug-metadata debug metadata
+                    --debug-pod debug pod
+                 --debug-sqlite debug sqlite
+                 --debug-stages debug stages
+-h                       --help This help information.