path: root/org/spine_search_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

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

<<sisudoc_spine_search_readme_info>>

<<sisudoc_spine_search_readme_build_configuration_org>>

<<sisudoc_spine_search_readme_get-build-install_org>>

<<sisudoc_spine_search_readme_commands_org>>
#+END_SRC

*** md

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

<<sisudoc_spine_search_readme_build_configuration_md>>

<<sisudoc_spine_search_readme_get-build-install_md>>

<<sisudoc_spine_search_readme_commands_md>>
#+END_SRC

** org header

#+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

** project name

#+NAME: sisudoc_spine_search_readme_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
    ]

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

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

    license:   "AGPL 3 or later"

    homepage: [
        "https://www.sisudoc.org",
        "https://www.doc-reform.org"
      ]
#+END_SRC

** short description (currently UNUSED)

#+NAME: sisudoc_spine_search_readme_description
#+BEGIN_SRC text
#+END_SRC

** installation
*** org

#+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_search_readme_get-build-install_body_summary>>

,** <<sisudoc_spine_search_readme_get-build-install_body_clone_h2>>

<<sisudoc_spine_search_readme_get-build-install_body_clone>>

,** <<sisudoc_spine_search_readme_get-build-install_body_build_h2>>

<<sisudoc_spine_search_readme_get-build-install_body_build>>
#+END_SRC

*** md

#+NAME: sisudoc_spine_search_readme_get-build-install_md
#+HEADER: :noweb yes
#+BEGIN_SRC markdown
## <<sisudoc_spine_search_readme_get-build-install_h1>>

<<sisudoc_spine_search_readme_get-build-install_body_summary>>

## <<sisudoc_spine_search_readme_get-build-install_body_clone_h2>>

<<sisudoc_spine_search_readme_get-build-install_body_clone>>

## <<sisudoc_spine_search_readme_get-build-install_body_build_h2>>

<<sisudoc_spine_search_readme_get-build-install_body_build>>
#+END_SRC

*** heading

#+NAME: sisudoc_spine_search_readme_get-build-install_h1
#+BEGIN_SRC text
Installation, Compilation
#+END_SRC

*** text body

#+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.

❯❯ 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://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

#+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

#+NAME: sisudoc_spine_search_readme_get-build-install_body_clone
#+BEGIN_SRC markdown
  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
#+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
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/.
#+END_SRC

** configuration
*** org

#+NAME: sisudoc_spine_search_readme_build_configuration_org
#+HEADER: :noweb yes
#+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
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();
#+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
#+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

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.
#+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_search_copyright>>

  <<sisudoc_spine_search_license_agpl3>>

  <<sisudoc_spine_search_summary>>

<<sisudoc_spine_search_markup_samples>>

<<sisudoc_spine_search_dependencies>>
#+END_SRC

*** code source ./src

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

  <<sisudoc_spine_search_license_agpl3>>

  <<sisudoc_spine_search_summary>>

<<sisudoc_spine_search_markup_samples>>

<<sisudoc_spine_search_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_search_copyright>>

  <<sisudoc_spine_search_license_agpl3>>

  <<sisudoc_spine_search_summary>>

<<sisudoc_spine_search_markup_samples>>

<<sisudoc_spine_search_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_search_copyright>>

  <<sisudoc_spine_search_summary>>

<<sisudoc_spine_search_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_search_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_search_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_search_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_search_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_search_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: 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