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

project_name: "sisudoc-spine-search"

description:
  - "documents, structuring, processing, publishing"
  - "search"
  - "object numbering"
  - "cgi search form for 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"

* Summary

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.

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).

* Build Configuration

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
in particular: the the web server url; the name of the cgi script and; the name
and location of the sqlite database. The following is an example
./views/configuration.txt file.

struct Cfg {
  string http_request_type     = "http";
  string http_host             = "localhost";
  string www_url_doc_subroot   = "/spine";
  string cgi_filename          = "spine_search";
  string cgi_search_form_title = "≅ SiSU Spine search ፨";
  string db_sqlite_path        = "/var/www/sqlite";
  string db_sqlite_filename    = "spine.search.db";
}
enum _cfg = Cfg();

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

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)

** Clone project

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 sisudoc-spine-search-cgi will take place in the
directory: sisudoc-spine-search-cgi

** build sisudoc-spine

NOTE all actions to build sisudoc-spine are taken within the directory
sisudoc-spine-search-cgi

cd sisudoc-spine-search-cgi

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

  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

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

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

## with make

### ldc2

  make ldc

### dmd

  make dmd

## with nix on linux / nixos

### ldc2

  nix build ".#spine-search-nixpkgs-ldc" --print-build-logs
  # or
  nix build ".#spine-search-overlay-ldc" --print-build-logs

### dmd

  nix build ".#spine-search-nixpkgs-dmd" --print-build-logs
  # or
  nix build ".#spine-search-overlay-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/.

* Commands

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

However, a number of command instructions provided will not work unless the
sqlite db has been initialised and like the web content, this the sqlite databse
will not be found by sisudoc-spine-search-cgi unless it is placed where the
web-server is configured to find it.