help & manpages, start work

1 files changed, 304 insertions, 0 deletions

diff --git a/README b/README
index d8ea96f..203ee70 100644
--- a/README
+++ b/README
@@ -19,3 +19,307 @@ project_name:  Spine, Doc Reform
         "http://www.doc_reform.org",
         "http://www.sisudoc.org"
       ]
+
+# Installation, Compilation
+
+SiSU spine is written in the programming language D for which there are 3 compilers:
+
+- dmd
+- ldc
+- gdc
+
+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
+
+  dub --compiler=ldc2 -color --config=ldc -b release
+
+  dub --compiler=dmd -color --config=dmd
+
+  dub --compiler=gdc-10 -color --config=gdc -b release
+
+  make ldc
+
+  make dmd
+
+there has been some coalescence around the Meson build system
+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"
+  domain:                      "localhost"
+  data_http:                   "http"
+  data_domain:                 "localhost"
+  data_root_url:               "http://localhost"
+  data_root_path:              "/var/www/html"
+  data_root_part:              ""
+  images_root_part:            "image"
+  cgi_title:                   "≅ SiSU Spine search"
+  cgi_http:                    "http"
+  cgi_domain:                  "localhost"
+  cgi_bin_url:                 "http://localhost/cgi-bin"
+  cgi_bin_part:                "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
+
+for a list of commands from the program type:
+
+  spine -h
+
+at the time of writing this provides the following output:
+
+                  --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
+                      --harvest extract info on authors & topics from document header metadata
+              --harvest-authors extract info on authors from document header metadata
+               --harvest-topics extract info on topics from document header metadata
+                     --hide-ocn object cite numbers
+                         --html process html output
+            --html-link-harvest place links back to harvest 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.
+
+# Examples
+
+if configuartion has been set specify just
+- the desired output and
+- the markup document/pod(s) to process
+
+  spine -v --html ~spineMarkupSamples/markup/pod/sisu-manual
+
+if configuartion has not been set or to overide the set configration specify
+- the output path as well as
+- the desired output and
+- the markup document/pod(s) to process
+
+note: ~webDocRoot should be the path to web doc root, provide a suitable output path.
+
+  spine -v --html --html-link-search --html-link-harvest  --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+
+  spine -v --html --html-link-search --html-link-harvest --epub --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+
+  spine -v --html --epub --latex --odt --harvest --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+
+## harvest
+
+if you have a document collection with documents that have metadata headers a
+summary of the collection can be made using the harvest command
+
+  spine -v --harvest --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+
+  spine -v --harvest ~spineMarkupSamples/pod/*
+
+  spine -v --html --html-link-search --html-link-harvest --harvest --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+
+  spine -v --html --html-link-search --html-link-harvest --harvest ~spineMarkupSamples/pod/*
+
+## sqlite
+
+### create db
+
+if there is no sqlite db you first need to create one, to do so
+- the name of the db and
+- the root path for document output
+must be specified:
+
+  spine -v \
+    --sqlite-db-create --sqlite-db-filename="spine.search.db" \
+    --output=/var/www/html \
+    ~spineMarkupSamples/pod/*
+
+  spine -v --sqlite-db-create --sqlite-db-filename="spine.search.db" --output=`echo ~webDocRoot`
+
+if you have a configration file providing this information that is to be used
+for a document collection you can point to the document collection:
+
+  spine -v --sqlite-db-create ~spineMarkupSamples/pod
+
+### populate db
+
+must specify:
+- the name of the db and
+- the root path for document output
+
+  spine -v --sqlite-update \
+    --sqlite-db-filename="spine.search.db" \
+    --output=/var/www/html \
+    ~spineMarkupSamples/pod/*
+
+  spine -v --sqlite-update --sqlite-db-filename="spine.search.db" --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+
+if you have a configration file providing this information that is to be used
+for a document collection you can point to the document collection:
+
+  spine -v --sqlite-update ~spineMarkupSamples/pod/*
+
+### generate a cgi search form in d
+
+  spine -v --cgi-search-form-codegen \
+    --output=/var/www/html \
+    ~spineMarkupSamples/pod
+
+  spine -v --cgi-search-form-codegen --config=~spineMarkupSamples/pod
+
+  spine -v --cgi-search-form-codegen --config=~spineMarkupSamples/pod/.dr/config_local_site
+
+  spine --cgi-search-form-codegen --output=`echo ~webDocRoot` ~spineMarkupSamples/pod
+
+  spine --cgi-search-form-codegen --cgi-sqlite-search-filename="spine_search" --output=`echo ~webDocRoot`
+
+  spine -v --cgi-search-form-codegen \
+    --sqlite-db-filename="spine.search.db" \
+    --cgi-sqlite-search-filename="spine-search" \
+    --output=/var/www/html \
+    ~spineMarkupSamples/pod
+
+#### compile the cgi search form
+
+  cd /var/www/html/cgi # /var/www/html (default document root)
+
+  cd ~webDocRoot/cgi
+
+the directory ~webDocRoot/cgi/src should contain two files
+- spine_search.d (or whatever you named it)
+- cgi.d (by Adam Rupee)
+
+  dub --force --compiler=ldc2 && sudo cp -v cgi-bin/spine-search /usr/lib/cgi-bin/.
+
+should compile spine-search in ~webDocRoot/cgi/cgi-bin and copy it to the
+cgi-bin directory
+
+  spine -v  --sqlite-db-create --sqlite-db-filename="spine.search.db" --cgi-sqlite-search-filename="spine-search" --output=`echo ~webDocRoot`
+
+  spine -v  --sqlite-db-create  ~spineMarkupSamples/pod
+
+  spine -v --html --html-link-search --cgi-sqlite-search-filename="spine-search" --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+
+  spine -v --html --html-link-search --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+
+  spine -v --html --html-link-search --cgi-sqlite-search-filename="spine-search" --html-link-harvest --harvest --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
+
+### create db & search form
+
+  spine -v \
+    --sqlite-db-create --sqlite-db-filename="spine.search.db" \
+    --cgi-search-form-codegen --cgi-sqlite-search-filename="spine-search" \
+    --output=/var/www/html \
+    ~spineMarkupSamples/pod/*
+
+### html with links to search form
+
+  spine -v --html \
+    --html-link-search \
+    --output=`echo ~webDocRoot` \
+    ~spineMarkupSamples/pod/*