spine search info

1 files changed, 144 insertions, 204 deletions

diff --git a/org/spine_search_info.org b/org/spine_info.org
index f1a4e93..c0642ea 100644
--- a/org/spine_search_info.org
+++ b/org/spine_info.org
@@ -20,151 +20,153 @@
 
 * README :readme:
 ** tangle
-*** org
+*** org contents
+**** org contents tangle
 
 #+HEADER: :tangle "../README"
 #+HEADER: :noweb yes
-#+BEGIN_SRC text
-<<sisudoc_spine_search_readme_org_header>>
+#+BEGIN_SRC org
+<<sisudoc_spine_README_header_org>>
 
-<<sisudoc_spine_search_readme_info>>
+<<sisudoc_spine_README_project_header_info>>
 
-<<sisudoc_spine_search_readme_build_configuration_org>>
+,* Summary
 
-<<sisudoc_spine_search_readme_get-build-install_org>>
+<<sisudoc_spine_README_summary>>
 
-<<sisudoc_spine_search_readme_commands_org>>
-#+END_SRC
+,* Build Configuration
 
-*** md
+<<sisudoc_spine_README_build_configuration>>
 
-#+HEADER: :tangle "../README.md"
-#+HEADER: :noweb yes
-#+BEGIN_SRC text
-<<sisudoc_spine_search_readme_info>>
+,* Compilation, Installation
+,** D compiler (dmd, ldc2) & D build manager (dub)
 
-<<sisudoc_spine_search_readme_build_configuration_md>>
+<<sisudoc_spine_README_install_summary>>
 
-<<sisudoc_spine_search_readme_get-build-install_md>>
+,** Clone project
 
-<<sisudoc_spine_search_readme_commands_md>>
-#+END_SRC
+<<sisudoc_spine_README_install_clone>>
 
-** org header
+,** build sisudoc-spine
 
-#+NAME: sisudoc_spine_search_readme_org_header
-#+BEGIN_SRC text
--*- mode: org -*-
-#+TITLE:       spine (sisudoc) (project) README
-#+DESCRIPTION: README for spine search
-#+FILETAGS:    :spine:build:tools:
-#+AUTHOR:      Ralph Amissah
-#+EMAIL:       [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]]
-#+COPYRIGHT:   Copyright (C) 2015 - 2024 Ralph Amissah
-#+LANGUAGE:    en
-#+STARTUP:     content hideblocks hidestars noindent entitiespretty
-#+OPTIONS:     H:3 num:nil toc:t \n:nil @:t ::t |:t ^:nil _:nil -:t f:t *:t <:t
-#+PROPERTY:    header-args  :exports code
-#+PROPERTY:    header-args+ :noweb yes
-#+PROPERTY:    header-args+ :eval no
-#+PROPERTY:    header-args+ :results no
-#+PROPERTY:    header-args+ :cache no
-#+PROPERTY:    header-args+ :padline no
-#+END_SRC
+<<sisudoc_spine_README_install_build>>
 
-** project name
+,* Commands
 
-#+NAME: sisudoc_spine_search_readme_info
-#+BEGIN_SRC yaml
-project_name:  sisudoc-spine-search
+<<sisudoc_spine_README_commands>>
+#+END_SRC
 
-  description: [
-      "documents, structuring, processing, publishing",
-      search,
-      object numbering,
-      cgi search form for static content generator,
-      sisu markup
-    ]
+**** org header
 
-    author:
-      name:    Ralph Amissah
-      email:   ralph.amissah@gmail.com
+#+NAME: sisudoc_spine_README_header_org
+#+BEGIN_SRC org
+-*- mode: org -*-
+,#+TITLE:       spine (sisudoc) (project) README
+,#+DESCRIPTION: README for spine search
+,#+FILETAGS:    :spine:build:tools:
+,#+AUTHOR:      Ralph Amissah
+,#+EMAIL:       [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]]
+,#+COPYRIGHT:   Copyright (C) 2015 - 2024 Ralph Amissah
+,#+LANGUAGE:    en
+,#+STARTUP:     content hideblocks hidestars noindent entitiespretty
+,#+OPTIONS:     H:3 num:nil toc:t \n:nil @:t ::t |:t ^:nil _:nil -:t f:t *:t <:t
+,#+PROPERTY:    header-args  :exports code
+,#+PROPERTY:    header-args+ :noweb yes
+,#+PROPERTY:    header-args+ :eval no
+,#+PROPERTY:    header-args+ :results no
+,#+PROPERTY:    header-args+ :cache no
+,#+PROPERTY:    header-args+ :padline no
+#+END_SRC
+
+*** md contents tangle
 
-    copyright: "(C) 2015 - 2024 Ralph Amissah, All Rights Reserved."
+#+HEADER: :tangle "../README.md"
+#+HEADER: :noweb yes
+#+BEGIN_SRC text
+<<sisudoc_spine_README_project_header_info>>
 
-    license:   "AGPL 3 or later"
+# Summary
 
-    homepage: [
-        "https://www.sisudoc.org",
-        "https://www.doc-reform.org"
-      ]
-#+END_SRC
+<<sisudoc_spine_README_summary>>
 
-** short description (currently UNUSED)
+# Build Configuration
 
-#+NAME: sisudoc_spine_search_readme_description
-#+BEGIN_SRC text
-#+END_SRC
+<<sisudoc_spine_README_build_configuration>>
 
-** installation
-*** org
+# Compilation, Installation
+## D compiler (dmd, ldc2) & D build manager (dub)
 
-#+NAME: sisudoc_spine_search_readme_get-build-install_org
-#+HEADER: :noweb yes
-#+BEGIN_SRC text
-,* <<sisudoc_spine_search_readme_get-build-install_h1>>
+<<sisudoc_spine_README_install_summary>>
 
-<<sisudoc_spine_search_readme_get-build-install_body_summary>>
+## make a directory and clone the sisudoc-spine project
 
-,** <<sisudoc_spine_search_readme_get-build-install_body_clone_h2>>
+<<sisudoc_spine_README_install_clone>>
 
-<<sisudoc_spine_search_readme_get-build-install_body_clone>>
+## build sisudoc-spine
 
-,** <<sisudoc_spine_search_readme_get-build-install_body_build_h2>>
+<<sisudoc_spine_README_install_build>>
 
-<<sisudoc_spine_search_readme_get-build-install_body_build>>
+# Commands
+
+<<sisudoc_spine_README_commands>>
 #+END_SRC
 
-*** md
+** project yaml header
 
-#+NAME: sisudoc_spine_search_readme_get-build-install_md
-#+HEADER: :noweb yes
-#+BEGIN_SRC markdown
-## <<sisudoc_spine_search_readme_get-build-install_h1>>
+#+NAME: sisudoc_spine_README_project_header_info
+#+BEGIN_SRC yaml
+project_name: "sisudoc-spine-search"
+
+description:
+  - "documents, structuring, processing, publishing"
+  - "search"
+  - "object numbering"
+  - "cgi search form for static content generator"
+  - "sisu markup"
 
-<<sisudoc_spine_search_readme_get-build-install_body_summary>>
+author:
+  name:  "Ralph Amissah"
+  email: ralph.amissah@gmail.com
 
-## <<sisudoc_spine_search_readme_get-build-install_body_clone_h2>>
+copyright: "(C) 2015 - 2024 Ralph Amissah, All Rights Reserved."
 
-<<sisudoc_spine_search_readme_get-build-install_body_clone>>
+license:
+  - "project code: AGPL 3 or later"
 
-## <<sisudoc_spine_search_readme_get-build-install_body_build_h2>>
+homepage:
+  - "https://sisudoc.org"
+  - "https://doc-reform.org"
 
-<<sisudoc_spine_search_readme_get-build-install_body_build>>
+git:
+  - "https://git.sisudoc.org"
 #+END_SRC
 
-*** heading
+** project summary - short description
 
-#+NAME: sisudoc_spine_search_readme_get-build-install_h1
+#+NAME: sisudoc_spine_README_summary
 #+BEGIN_SRC text
-Installation, Compilation
-#+END_SRC
+This is a sample cgi search form for access to an sqlite3 db built and populated
+by sisudoc-spine. As such you probably need the whold of the sisudoc.org spine
+project.
 
-*** text body
+SiSU is an object-centric, lightweight markup based, document structuring,
+parser, publishing and search tool for document collections. It is command line
+oriented and generates static content that is currently made searchable at an
+object level through an SQL database. Markup helps define (delineate) objects
+(primarily various types of text block) which are tracked in sequence,
+substantive objects being numbered sequentially by the program for object
+citation.
 
-#+NAME: sisudoc_spine_search_readme_get-build-install_body_summary
-#+BEGIN_SRC markdown
-Development of sisudoc-spine started in 2015 on a Debian linux box.
-
-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.
+Development of sisudoc-spine started in 2015 on a Debian linux box as a
+replacement for sisu (written in Ruby, starting 2000, and Perl from 1997).
+(Using Nix and NixOS since 2020).
+#+END_SRC
 
-❯❯ D compiler and build manager
+** installation
+*** install summary
 
+#+NAME: sisudoc_spine_README_install_summary
+#+BEGIN_SRC text
 SiSU spine is written in the programming language D for which there are 3
 compilers: dmd, ldc, gdc
 - https://wiki.dlang.org/Compilers
@@ -176,13 +178,12 @@ D projects tend to use dub as project manager
 The default build tools used are dub with ldc2 (dub is also tested)
 #+END_SRC
 
-#+NAME: sisudoc_spine_search_readme_get-build-install_body_clone_h2
-#+BEGIN_SRC markdown
-make a directory and clone the sisudoc-spine project
-#+END_SRC
+*** install clone project
+
+#+NAME: sisudoc_spine_README_install_clone
+#+BEGIN_SRC text
+Make a directory and clone the sisudoc-spine project
 
-#+NAME: sisudoc_spine_search_readme_get-build-install_body_clone
-#+BEGIN_SRC markdown
   mkdir ~/git.sisudoc
   cd ~/git.sisudoc
 
@@ -196,13 +197,8 @@ all work in this installation of sisudoc-spine-search-cgi will take place in the
 directory: sisudoc-spine-search-cgi
 #+END_SRC
 
-#+NAME: sisudoc_spine_search_readme_get-build-install_body_build_h2
-#+BEGIN_SRC markdown
-build sisudoc-spine
-#+END_SRC
-
-#+NAME: sisudoc_spine_search_readme_get-build-install_body_build
-#+BEGIN_SRC markdown
+#+NAME: sisudoc_spine_README_install_build
+#+BEGIN_SRC text
 NOTE all actions to build sisudoc-spine are taken within the directory
 sisudoc-spine-search-cgi
 
@@ -266,37 +262,9 @@ dub --force --compiler=ldc2 && sudo cp -v cgi-bin/spine-search /usr/lib/cgi-bin/
 #+END_SRC
 
 ** configuration
-*** org
 
-#+NAME: sisudoc_spine_search_readme_build_configuration_org
-#+HEADER: :noweb yes
+#+NAME: sisudoc_spine_README_build_configuration
 #+BEGIN_SRC text
-,** <<sisudoc_spine_search_readme_build_configuration_h2>>
-
-<<sisudoc_spine_search_readme_build_configuration_body>>
-#+END_SRC
-
-*** md
-
-#+NAME: sisudoc_spine_search_readme_build_configuration_md
-#+HEADER: :noweb yes
-#+BEGIN_SRC markdown
-## <<sisudoc_spine_search_readme_build_configuration_h2>>
-
-<<sisudoc_spine_search_readme_configuration_body>>
-#+END_SRC
-
-*** heading
-
-#+NAME: sisudoc_spine_search_readme_build_configuration_h2
-#+BEGIN_SRC text
-Build Configuration
-#+END_SRC
-
-*** text body
-
-#+NAME: sisudoc_spine_search_readme_build_configuration_body
-#+BEGIN_SRC markdown
 sisudoc-spine-search-cgi example form is served from a web-server that has been
 configured for cgi. To get this example to work, you will need to edit the file
 in ./views/configuration.txt to match the configuration of your web-server and
@@ -317,37 +285,9 @@ enum _cfg = Cfg();
 #+END_SRC
 
 ** commands help
-*** org
-
-#+NAME: sisudoc_spine_search_readme_commands_org
-#+HEADER: :noweb yes
-#+BEGIN_SRC text
-,* <<sisudoc_spine_search_readme_commands_h2>>
-
-<<sisudoc_spine_search_readme_commands_body>>
-#+END_SRC
-
-*** md
-
-#+NAME: sisudoc_spine_search_readme_commands_md
-#+HEADER: :noweb yes
-#+BEGIN_SRC markdown
-# <<sisudoc_spine_search_readme_commands_h2>>
-
-<<sisudoc_spine_search_readme_commands_body>>
-#+END_SRC
 
-*** heading
-
-#+NAME: sisudoc_spine_search_readme_commands_h2
+#+NAME: sisudoc_spine_README_commands
 #+BEGIN_SRC text
-Commands
-#+END_SRC
-
-*** text body
-
-#+NAME: sisudoc_spine_search_readme_commands_body
-#+BEGIN_SRC markdown
 For commands to populate the db to be searched by sisudoc-spine-search-cgi see
 the README in sisudoc-spine and/or sisudoc-spine-samples
 
@@ -363,51 +303,51 @@ web-server is configured to find it.
 
 #+HEADER: :tangle "../COPYRIGHT"
 #+HEADER: :noweb yes
-#+BEGIN_SRC txt
+#+BEGIN_SRC text
 - Name: spine - SiSU Spine, Doc Reform
-  <<sisudoc_spine_search_copyright>>
+  <<sisudoc_spine_copyright>>
 
-  <<sisudoc_spine_search_license_agpl3>>
+  <<sisudoc_spine_license_agpl3>>
 
-  <<sisudoc_spine_search_summary>>
+  <<sisudoc_spine_summary>>
 
-<<sisudoc_spine_search_markup_samples>>
+<<sisudoc_spine_markup_samples>>
 
-<<sisudoc_spine_search_dependencies>>
+<<sisudoc_spine_dependencies>>
 #+END_SRC
 
 *** code source ./src
 
 #+HEADER: :tangle "../src/COPYRIGHT"
 #+HEADER: :noweb yes
-#+BEGIN_SRC txt
+#+BEGIN_SRC text
 - Name: spine - SiSU Spine, Doc Reform
-  <<sisudoc_spine_search_copyright>>
+  <<sisudoc_spine_copyright>>
 
-  <<sisudoc_spine_search_license_agpl3>>
+  <<sisudoc_spine_license_agpl3>>
 
-  <<sisudoc_spine_search_summary>>
+  <<sisudoc_spine_summary>>
 
-<<sisudoc_spine_search_markup_samples>>
+<<sisudoc_spine_markup_samples>>
 
-<<sisudoc_spine_search_dependencies>>
+<<sisudoc_spine_dependencies>>
 #+END_SRC
 
 *** code source ./src/sisudoc
 
 #+HEADER: :tangle "../src/sisudoc/COPYRIGHT"
 #+HEADER: :noweb yes
-#+BEGIN_SRC txt
+#+BEGIN_SRC text
 - Name: spine - SiSU Spine, Doc Reform
-  <<sisudoc_spine_search_copyright>>
+  <<sisudoc_spine_copyright>>
 
-  <<sisudoc_spine_search_license_agpl3>>
+  <<sisudoc_spine_license_agpl3>>
 
-  <<sisudoc_spine_search_summary>>
+  <<sisudoc_spine_summary>>
 
-<<sisudoc_spine_search_markup_samples>>
+<<sisudoc_spine_markup_samples>>
 
-<<sisudoc_spine_search_dependencies>>
+<<sisudoc_spine_dependencies>>
 #+END_SRC
 
 *** org files ./org
@@ -420,28 +360,28 @@ web-server is configured to find it.
 
 #+HEADER: :tangle "./COPYRIGHT"
 #+HEADER: :noweb yes
-#+BEGIN_SRC txt
+#+BEGIN_SRC text
 - Name: spine - SiSU Spine, Doc Reform
-  <<sisudoc_spine_search_copyright>>
+  <<sisudoc_spine_copyright>>
 
-  <<sisudoc_spine_search_summary>>
+  <<sisudoc_spine_summary>>
 
-<<sisudoc_spine_search_markup_samples>>
+<<sisudoc_spine_markup_samples>>
 #+END_SRC
 
 *** doc (markup samples) ./doc
 
 #+HEADER: :NO-tangle "../doc/COPYRIGHT"
 #+HEADER: :noweb yes
-#+BEGIN_SRC txt
+#+BEGIN_SRC text
 <<data>>
 #+END_SRC
 
 ** incorporate
 *** copyright
 
-#+NAME: sisudoc_spine_search_copyright
-#+BEGIN_SRC txt
+#+NAME: sisudoc_spine_copyright
+#+BEGIN_SRC text
 - Description: documents, structuring, processing, publishing, search
   - static content generator
 
@@ -454,8 +394,8 @@ web-server is configured to find it.
 *** license
 **** AGPLv3
 
-#+NAME: sisudoc_spine_search_license_agpl3
-#+BEGIN_SRC txt
+#+NAME: sisudoc_spine_license_agpl3
+#+BEGIN_SRC text
 - code under src/* src/sisudoc/*
   - License: AGPL 3 or later:
 
@@ -485,8 +425,8 @@ web-server is configured to find it.
 
 *** spine_summary
 
-#+NAME: sisudoc_spine_search_summary
-#+BEGIN_SRC txt
+#+NAME: sisudoc_spine_summary
+#+BEGIN_SRC text
 - Spine, Doc Reform (related to SiSU) uses standard:
   - docReform markup syntax (based on SiSU markup)
     - standard SiSU markup syntax with modified headers and minor
@@ -498,7 +438,7 @@ web-server is configured to find it.
   [https://www.sisudoc.org]
 #+END_SRC
 
-#+BEGIN_SRC txt
+#+BEGIN_SRC text
   - Homepages:
     [https://www.sisudoc.org]
     [https://www.sisudoc.org]
@@ -509,8 +449,8 @@ web-server is configured to find it.
 
 *** markup_samples
 
-#+NAME: sisudoc_spine_search_markup_samples
-#+BEGIN_SRC txt
+#+NAME: sisudoc_spine_markup_samples
+#+BEGIN_SRC text
 - Spine, Doc Reform (SiSU) markup samples
   Individual document content Copyright (Author) [as stated in document header]
   Individual document content License (Author) [as stated in document header]
@@ -518,8 +458,8 @@ web-server is configured to find it.
 
 *** dependencies
 
-#+NAME: sisudoc_spine_search_dependencies
-#+BEGIN_SRC txt
+#+NAME: sisudoc_spine_dependencies
+#+BEGIN_SRC text
 - Dependencies [check dub.json or dub.sdl]
 
   - Name: d2sqlite3