path: root/org/spine_info.org

-*- mode: org -*-
#+TITLE:       sisudoc spine (doc_reform) information files
#+DESCRIPTION: documents - structuring, various output representations & search
#+FILETAGS:    :spine:info:
#+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
#+PROPERTY:    header-args  :exports code
#+PROPERTY:    header-args+ :noweb yes
#+PROPERTY:    header-args+ :results no
#+PROPERTY:    header-args+ :cache no
#+PROPERTY:    header-args+ :padline no
#+PROPERTY:    header-args+ :mkdirp yes
#+OPTIONS:     H:3 num:nil toc:t \n:t ::t |:t ^:nil -:t f:t *:t

- [[./doc-reform.org][doc-reform.org]]  [[./][org/]]
- [[./spine_build_scaffold.org][spine_build_scaffold.org]]

* README :readme:
** tangle
*** org contents
**** org contents tangle

#+HEADER: :tangle "../README"
#+HEADER: :noweb yes
#+BEGIN_SRC org
<<sisudoc_spine_README_header_org>>

<<sisudoc_spine_README_project_header_info>>

,* Summary

<<sisudoc_spine_README_summary>>

,* Compilation, Installation
,** D compiler (dmd, ldc2) & D build manager (dub)

<<sisudoc_spine_README_install_summary>>

,** Clone project

<<sisudoc_spine_README_install_clone>>

,** build sisudoc-spine

<<sisudoc_spine_README_install_build>>

,* Commands - document processing examples

,** basic output

<<sisudoc_spine_README_command_examples_basic>>

,** curate

<<sisudoc_spine_README_command_examples_curate_text>>

,** sqlite

<<sisudoc_spine_README_command_examples_sqlite_text>>

,*** create db

<<sisudoc_spine_README_command_examples_create_db_text>>

,*** populate db

<<sisudoc_spine_README_command_examples_populate_db_text>>

,*** generate a cgi search form in d

<<sisudoc_spine_README_command_examples_search_db_cgi_text>>

,**** compile the cgi search form

<<sisudoc_spine_README_command_examples_compile_search_db_cgi_text>>

,*** create db & search form

<<sisudoc_spine_README_command_examples_create_db_and_search_form_text>>

,*** html with links to search form

<<sisudoc_spine_README_command_examples_html_with_links_to_search_form_text>>

,** commands help

<<sisudoc_spine_README_commands_help>>

,* Configure

,* command line instruction

<<sisudoc_spine_README_configure_command_line>>

,* configure environment

<<sisudoc_spine_README_configure_env>>

,* configuration files

<<sisudoc_spine_README_configure_files>>
#+END_SRC

**** org header

#+NAME: sisudoc_spine_README_header_org
#+BEGIN_SRC org
-*- mode: org -*-
,#+TITLE:       spine (sisudoc) (project) README
,#+DESCRIPTION: README for spine
,#+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

#+HEADER: :tangle "../README.md"
#+HEADER: :noweb yes
#+BEGIN_SRC text
<<sisudoc_spine_README_project_header_info>>

# Summary

<<sisudoc_spine_README_summary>>

# Compilation, Installation
## D compiler (dmd, ldc2) & D build manager (dub)

<<sisudoc_spine_README_install_summary>>

## Clone project

<<sisudoc_spine_README_install_clone>>

## build sisudoc-spine

<<sisudoc_spine_README_install_build>>

# Commands - document processing examples

## basic output

<<sisudoc_spine_README_command_examples_basic>>

## curate

<<sisudoc_spine_README_command_examples_curate_text>>

## sqlite

<<sisudoc_spine_README_command_examples_sqlite_text>>

### create db

<<sisudoc_spine_README_command_examples_create_db_text>>

### populate db

<<sisudoc_spine_README_command_examples_populate_db_text>>

### generate a cgi search form in d

<<sisudoc_spine_README_command_examples_search_db_cgi_text>>

#### compile the cgi search form

<<sisudoc_spine_README_command_examples_compile_search_db_cgi_text>>

### create db & search form

<<sisudoc_spine_README_command_examples_create_db_and_search_form_text>>

### html with links to search form

<<sisudoc_spine_README_command_examples_html_with_links_to_search_form_text>>

## commands help

<<sisudoc_spine_README_commands_help>>

# Configure

## command line instruction

<<sisudoc_spine_README_configure_command_line>>

## configure environment

<<sisudoc_spine_README_configure_env>>

## configuration files

<<sisudoc_spine_README_configure_files>>
#+END_SRC

** project yaml header

#+NAME: sisudoc_spine_README_project_header_info
#+BEGIN_SRC yaml
project_name: "sisudoc spine (doc reform)"

description:
  - "documents, structuring, processing, publishing"
  - "search"
  - "object numbering"
  - "static content generator"
  - "sisu markup"

author:
  name:  "Ralph Amissah"
  email: ralph.amissah@gmail.com

copyright: "(C) 2015 - 2024 Ralph Amissah, All Rights Reserved."

license:
  - "project code: AGPL 3 or later"

homepage:
  - "https://sisudoc.org"
  - "https://doc-reform.org"

git:
  - "https://git.sisudoc.org"
#+END_SRC

** project summary - short description

#+NAME: sisudoc_spine_README_summary
#+BEGIN_SRC text
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.

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

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

D projects tend to use dub as project manager
- 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)
#+END_SRC

*** install clone project

#+NAME: sisudoc_spine_README_install_clone
#+BEGIN_SRC text
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

all work in this installation of and use of sisudoc-spine will take place in the
directory: sisudoc-spine
#+END_SRC

*** install build project

#+NAME: sisudoc_spine_README_install_build
#+BEGIN_SRC text
NOTE all actions to build sisudoc-spine are taken within the directory
sisudoc-spine

cd sisudoc-spine

to build directly with dub, either:

for ldc2:
  # on nix (get dependencies by setting your development environment):
  nix develop ".#dsh-nixpkgs-ldc-dub" --print-build-logs -c zsh

  # assuming you have ldc2 & dub installed on your system:
  dub run --compiler=ldmd2 --config=ldmd2 --combined --skip-registry=all
  dub --compiler=ldmd2 --config=ldmd2

  dub run --compiler=ldc2 --config=ldc2 --combined --skip-registry=all
  dub --compiler=ldc2 --config=ldc2

for dmd:
  # on nix (get dependencies by setting your development environment):
  nix develop ".#dsh-nixpkgs-dmd-dub" --print-build-logs -c zsh

  # assuming you have dmd & dub installed on your system:
  dub run --compiler=dmd --config=dmd --combined --skip-registry=all
  dub --compiler=dmd --config=dmd

to build with make using the provided makefile, (assuming you have the named
compiler and dub installed on your system) either:

for ldc2:

  make ldc

for dmd:

  make dmd

to build using nix flakes on linux / nixos

for ldc2:

  nix build ".#spine-nixpkgs-ldc" --print-build-logs

for dmd:

  nix build ".#spine-nixpkgs-dmd" --print-build-logs

The Meson build system was used briefly to build spine, but the spine build
tooling for Meson has not been updated, maintained or tested in recent years.

  meson
  ninja -C build
  meson setup --wipe build && ninja -v -C build
  make meson

- https://mesonbuild.com/

dub --force --compiler=ldc2 && sudo cp -v cgi-bin/spine-search /usr/lib/cgi-bin/.
#+END_SRC

** commands
*** commands basic

#+NAME: sisudoc_spine_README_command_examples_basic
#+BEGIN_SRC text
For the most basic output you will need to specify:

- the spine binary (executable)
- the (recognized) path to a prepared (spine marked up) document or document
  collection
- the (path to) where the output is to be placed
- the output types you seek

export SpineBIN=./result/bin/spine
export SpinePOD=../sisudoc-spine-samples/markup/pod
export SpineOUT=./OUTPUT_TEST_sisudocSpine

${SpineBIN} -v --source --pod --epub --html --html-link-curate --html-link-markup --curate --output=${SpineOUT} ${SpinePOD}/*
${SpineBIN} -v --source --pod --latex --latex-init --epub --html --html-link-pdf --html-link-curate --html-link-markup --curate --output=${SpineOUT} ${SpinePOD}/*

which would execute the following command:

./result/bin/spine -v --source --pod --epub --html --html-link-curate --html-link-markup --curate --output=./OUTPUT_TEST_sisudocSpine ../sisudoc-spine-samples/markup/pod/*
./result/bin/spine -v --source --pod --latex --latex-init --epub --html --html-link-pdf --html-link-curate --html-link-markup --curate --output=./OUTPUT_TEST_sisudocSpine ../sisudoc-spine-samples/markup/pod/*
#+END_SRC

*** commands help

#+NAME: sisudoc_spine_README_commands_help
#+BEGIN_SRC text
for a list of commands from the program type:

  spine -h
#+END_SRC

#+BEGIN_SRC text
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.
#+END_SRC

*** other command instruction examples

#+NAME: sisudoc_spine_README_command_examples_curate_text
#+BEGIN_SRC text
if you have a document collection with documents that have metadata headers a
summary of the collection can be made using the curate command:

${SpineBIN} -v --curate --output=${SpineOUT} ${SpinePOD}/*

spine -v --curate --output=./OUTPUT_TEST_sisudocSpine ../sisudoc-spine-samples/markup/pod/*

${SpineBIN} -v --html --html-link-curate --curate --output=${SpineOUT} ${SpinePOD}/*

spine -v --html --html-link-curate --curate --output=./OUTPUT_TEST_sisudocSpine ../sisudoc-spine-samples/markup/pod/*
#+END_SRC

#+NAME: sisudoc_spine_README_command_examples_sqlite_text
#+BEGIN_SRC text
Configuration and setup are required to use sqlite search with sisudoc-spine for
the first.

- sqlite3 will need to be installed and recognized as such by the program

- you will need to have a web server configured to run cgi

- sisudoc-spine-search-cgi will need to be compiled and the binary placed in the
  appropriate cgi path

- you will need to use sisudoc-spine to initialize the database (create tables
  and indexes)

- sisudoc-spine can be used to populate the database, and produce html with
  entry submission fields that link to the cgi search

if configuartion has been set specify just
- the desired output and
- the markup document/pod(s) to process

spine -v --html --html-link-search ${SpinePOD}/*

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

note: ~webDocRoot should be the path to web doc root, provide a suitable output path.

  spine -v --html --html-link-search --html-link-curate  --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*

  spine -v --html --html-link-search --html-link-curate --epub --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*

  spine -v --html --epub --latex --odt --curate --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/*
#+END_SRC

#+NAME: sisudoc_spine_README_command_examples_create_db_text
#+BEGIN_SRC text
If there is no sqlite db, you first need to create one (an empty db - tables &
indexes), to do so you must specify:

- the spine binary (executable)
- the name of the db and
- the path for where the db is to be built

(& you must of course have write permission):

spine -v --sqlite-db-create --sqlite-db-filename="spineishearch.db" --sqlite-db-path="/var/www/sqlite"

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 (where the
configuraton file "config_local_site" will be looked for in the .dr
sub-directory):

spine -v --sqlite-db-create ${SpinePOD}

To drop (destroy) and re-create a db, you instead would use: --sqlite-db-recreate
#+END_SRC

#+NAME: sisudoc_spine_README_command_examples_populate_db_text
#+BEGIN_SRC text
To populate a db with documents prepared for sisudoc-spine, you must specify:
- the spine binary (executable)
- the name of the db
- the path to the db
- the (recognized) path to a prepared (spine marked up) document or document
- 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/*

  ${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="${SpineSearchActionRemote}" --curate --sqlite-update --sqlite-kb-filename="${SpineSQLdb}" --output=${SpineOUT} ${SpinePOD}/*
#+END_SRC

#+NAME: sisudoc_spine_README_command_examples_search_db_cgi_text
#+BEGIN_SRC text
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
#+END_SRC

#+NAME: sisudoc_spine_README_command_examples_compile_search_db_cgi_text
#+BEGIN_SRC text
  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-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}/*

#+END_SRC

#+NAME: sisudoc_spine_README_command_examples_create_db_and_search_form_text
#+BEGIN_SRC text
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/*
#+END_SRC

#+NAME: sisudoc_spine_README_command_examples_html_with_links_to_search_form_text
#+BEGIN_SRC text
${SpineBIN} -v --epub --html --html-link-curate --curate --output=${SpineOUT} ${SpinePOD}/*

${SpineBIN} -v --source --pod --latex --latex-init --epub --html --html-link-pdf --html-link-curate --html-link-markup --curate --output=${SpineOUT} ${SpinePOD}/*

${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}/*

spine -v --html \
  --html-link-search \
  --output=`echo ~webDocRoot` \
  ${SpinePOD}/*
#+END_SRC

** configuration
*** configure, command line flag settings

#+NAME: sisudoc_spine_README_configure_command_line
#+BEGIN_SRC text
Many configuration options can be passed directly from the command line using
command line flags. Evident from the examples given of basic commands.
#+END_SRC

*** configure, environment, exports

#+NAME: sisudoc_spine_README_configure_env
#+BEGIN_SRC text
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

# ❯❯ url to activate search (as configured on web server)
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
#+END_SRC

*** configure, configuration files

#+NAME: sisudoc_spine_README_configure_files
#+BEGIN_SRC text
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=~spineMarkup/pod/.dr/my_config

here are two sample configuration files

sample 1. a localhost (check your paths):

<<sisudoc_spine_configuration_sample1>>

sample 2. sisudoc:

<<sisudoc_spine_configuration_sample2>>
#+END_SRC

**** configuration sample 1: assumes localhost web server

#+NAME: sisudoc_spine_configuration_sample1
#+BEGIN_SRC yaml
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:                  ""
#+END_SRC

**** configuration sample 2: web server with domain name

#+NAME: sisudoc_spine_configuration_sample2
#+BEGIN_SRC yaml
flag:
  act0:                        "--html"
  act1:                        "--html --epub"
output:
  path:                        "/srv/www/spine"
default:
  language:                    "en"
  papersize:                   "a4,letter.portrait,b4.portrait"
  text_wrap:                   "80"
  digest:                      "sha256"
webserv:
  http:                        "https"
  domain:                      "sisudoc.org"
  data_http:                   "https"
  data_domain:                 "sisudoc.org"
  data_root_url:               "https://sisudoc.org"
  data_root_path:              "/srv/www/spine"
  data_root_part:              "/spine"
  images_root_part:            "image"
  cgi_search_form_title:       "≅ SiSU Spine search"
  cgi_http:                    "https"
  cgi_domain:                  "sisudoc.org"
  cgi_bin_part:                "cgi-bin"
  cgi_bin_path:                "/var/www/cgi/cgi-bin"
  cgi_search_script:           "spine_search"
  cgi_search_script_raw_fn_d:  "spine_search.d"
  cgi_port:                    ""
  cgi_user:                    ""
  cgi_action:                  "https://sisudoc.org/spine_search"
  db_sqlite_filename:          "spine.search.db"
  db_sqlite_path:              "/var/www/sqlite"
  db_pg_table:                 ""
  db_pg_user:                  ""
#+END_SRC

* COPYRIGHT & LICENSE
** notices
*** project (project root) ./

#+HEADER: :tangle "../COPYRIGHT"
#+HEADER: :noweb yes
#+BEGIN_SRC txt
- Name: spine - SiSU Spine, Doc Reform
  <<sisudoc_spine_copyright>>

  <<sisudoc_spine_license_agpl3>>

  <<sisudoc_spine_summary>>

<<sisudoc_spine_markup_samples>>

<<sisudoc_spine_dependencies>>
#+END_SRC

*** code org ./org

#+HEADER: :tangle "../org/COPYRIGHT"
#+HEADER: :noweb yes
#+BEGIN_SRC txt
- Name: spine - SiSU Spine, Doc Reform
  <<sisudoc_spine_copyright>>

  <<sisudoc_spine_license_agpl3>>

  <<sisudoc_spine_summary>>

<<sisudoc_spine_markup_samples>>

<<sisudoc_spine_dependencies>>
#+END_SRC

*** code source ./src

#+HEADER: :tangle "../src/COPYRIGHT"
#+HEADER: :noweb yes
#+BEGIN_SRC txt
- Name: spine - SiSU Spine, Doc Reform
  <<sisudoc_spine_copyright>>

  <<sisudoc_spine_license_agpl3>>

  <<sisudoc_spine_summary>>

<<sisudoc_spine_markup_samples>>

<<sisudoc_spine_dependencies>>
#+END_SRC

*** code source ./src/sisudoc

#+HEADER: :tangle "../src/sisudoc/COPYRIGHT"
#+HEADER: :noweb yes
#+BEGIN_SRC txt
- Name: spine - SiSU Spine, Doc Reform
  <<sisudoc_spine_copyright>>

  <<sisudoc_spine_license_agpl3>>

  <<sisudoc_spine_summary>>

<<sisudoc_spine_markup_samples>>

<<sisudoc_spine_dependencies>>
#+END_SRC

*** org files ./org

- .org literate programming:
  - copyright asserted
  - omitted
    - license
    - dependency information

#+HEADER: :tangle "./COPYRIGHT"
#+HEADER: :noweb yes
#+BEGIN_SRC txt
- Name: spine - SiSU Spine, Doc Reform
  <<sisudoc_spine_copyright>>

  <<sisudoc_spine_summary>>

<<sisudoc_spine_markup_samples>>
#+END_SRC

*** doc (markup samples) ./doc

#+HEADER: :NO-tangle "../doc/COPYRIGHT"
#+HEADER: :noweb yes
#+BEGIN_SRC txt
<<data>>
#+END_SRC

** incorporate
*** copyright

#+NAME: sisudoc_spine_copyright
#+BEGIN_SRC txt
- Description: documents, structuring, processing, publishing, search
  - static content generator

- Author: Ralph Amissah
  [ralph.amissah@gmail.com]

- Copyright: (C) 2015 - 2024 Ralph Amissah
#+END_SRC

*** license
**** AGPLv3

#+NAME: sisudoc_spine_license_agpl3
#+BEGIN_SRC txt
- code under src/* src/sisudoc/*
  - License: AGPL 3 or later:

    Spine, Doc Reform (SiSU), a framework for document structuring, publishing and
    search

    Copyright (C) Ralph Amissah

    This program is free software: you can redistribute it and/or modify it
    under the terms of the GNU AFERO General Public License as published by
    the Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
    for more details.

    You should have received a copy of the GNU General Public License along
    with this program. If not, see [https://www.gnu.org/licenses/].

    If you have Internet connection, the latest version of the AGPL should be
    available at these locations:
    [https://www.fsf.org/licensing/licenses/agpl.html]
    [https://www.gnu.org/licenses/agpl.html]
#+END_SRC

*** spine_summary

#+NAME: sisudoc_spine_summary
#+BEGIN_SRC txt
- Spine, Doc Reform (related to SiSU) uses standard:
  - docReform markup syntax (based on SiSU markup)
    - standard SiSU markup syntax with modified headers and minor
      modifications
  - docReform object numbering (based on SiSU object citation numbering)
    - standard SiSU document object numbering

- Homepages:
  [https://www.sisudoc.org]
#+END_SRC

#+BEGIN_SRC txt
  - Homepages:
    [https://www.sisudoc.org]
    [https://www.sisudoc.org]

  - Git
    []
#+END_SRC

*** markup_samples

#+NAME: sisudoc_spine_markup_samples
#+BEGIN_SRC txt
- 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]
#+END_SRC

*** dependencies

#+NAME: sisudoc_spine_dependencies
#+BEGIN_SRC txt
- Dependencies [check dub.json or dub.sdl]

  - Name: d2sqlite3
    - Description:
      This is a small wrapper around SQLite for the D programming language.

    - Author:
      [Nicolas Sicard]
      [https://github.com/dlang-community/d2sqlite3/graphs/contributors]

    - Copyright: (C) 2011-2018, Nicolas Sicard

    - code:
      - License: BSL-1.0
        Boost Software License 1.0
        [https://www.boost.org/LICENSE_1_0.txt]

    - Homepages:
      [https://github.com/dlang-community/d2sqlite3]
      [https://code.dlang.org/packages/d2sqlite3]

    - src/ext_depends/d2sqlite3
    - sundry/spine_search_cgi/src/ext_depends_cgi/d2sqlite3

  - Name: dyaml
    - Description:
      D:YAML is an open source YAML parser and emitter library for the D programming language.

    - Author:
      [Ferdinand Majerech]

    - Copyright: (C) 2011-2018, Ferdinand Majerech

    - code:
      - License: BSL-1.0
        Boost Software License 1.0
        [https://www.boost.org/LICENSE_1_0.txt]

    - Homepages:
      [https://github.com/dlang-community/D-YAML]
      [https://code.dlang.org/packages/dyaml]

    - src/ext_depends/D-YAML

  - Name: imageformats
    - Description:

    - Author:
      [Tero Hänninen]

    - Copyright: (C) Tero Hänninen

    - code:
      - License: BSL-1.0
        Boost Software License 1.0
        [https://www.boost.org/LICENSE_1_0.txt]

    - Homepages:
      [https://github.com/lgvz/imageformats]
      [https://code.dlang.org/packages/imageformats]

    - src/ext_depends/imageformats

  - Name: tinyendian (dyaml dependency)
    - Description:
      TinyEndian is a minimal endianness library for the D programming language.

    - Author:
      [Ferdinand Majerech]

    - Copyright: (C) 2014 Ferdinand Majerech

    - code:
      - License: BSL-1.0
        Boost Software License 1.0
        [https://www.boost.org/LICENSE_1_0.txt]

    - Homepages:
      [https://github.com/dlang-community/tinyendian]
      [https://code.dlang.org/packages/tinyendian]

    - src/ext_depends/tinyendian

- Name: cgi.d
  - Description:

  - Author:
    [Adam D. Ruppe]

  - Copyright: (C) 2008 - 2023 Adam D. Ruppe

  - code: cgi.d
    aria2c https://raw.githubusercontent.com/adamdruppe/arsd/master/cgi.d

    - License: BSL-1.0
      Boost Software License 1.0
      [https://www.boost.org/LICENSE_1_0.txt]
      (Check the bottom of the file for details)

  - Homepages:
    [https://github.com/adamdruppe/arsd]

  - sundry/spine_search_cgi/src/ext_depends_cgi/arsd
#+END_SRC

* CHANGELOG :changelog:

#+BEGIN_SRC sh
CHL="CHANGELOG"
git log --pretty=format:'-_-%+s %+as %ae%+h%d%+b' --no-merges \
  | sed "/^\\s*$/d" | sed "s/^\([ ]\)*\*/\1-/" | sed "s/ \+$//" | sed "s/^-_-$//" \
  > ${CHL}
#+END_SRC

#+BEGIN_SRC sh
git log --pretty=format:"-_-_%+s %+as %ae%+h%d%+b" --no-merges \
  > ${CHL} && sed -i '/^$/d; s/^\([ ]\)*\*/\1-/; s/ \+$//; s/^-_-_//' ${CHL}
#+END_SRC