-*- 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 <> <> <> <> <> #+END_SRC *** md #+HEADER: :tangle "../README.md" #+HEADER: :noweb yes #+BEGIN_SRC text <> <> <> <> #+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 ,* <> <> ,** <> <> ,** <> <> #+END_SRC *** md #+NAME: sisudoc_spine_search_readme_get-build-install_md #+HEADER: :noweb yes #+BEGIN_SRC markdown ## <> <> ## <> <> ## <> <> #+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 ,** <> <> #+END_SRC *** md #+NAME: sisudoc_spine_search_readme_build_configuration_md #+HEADER: :noweb yes #+BEGIN_SRC markdown ## <> <> #+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 ,* <> <> #+END_SRC *** md #+NAME: sisudoc_spine_search_readme_commands_md #+HEADER: :noweb yes #+BEGIN_SRC markdown # <> <> #+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 <> <> <> <> <> #+END_SRC *** code source ./src #+HEADER: :tangle "../src/COPYRIGHT" #+HEADER: :noweb yes #+BEGIN_SRC txt - Name: spine - SiSU Spine, Doc Reform <> <> <> <> <> #+END_SRC *** code source ./src/sisudoc #+HEADER: :tangle "../src/sisudoc/COPYRIGHT" #+HEADER: :noweb yes #+BEGIN_SRC txt - Name: spine - SiSU Spine, Doc Reform <> <> <> <> <> #+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 <> <> <> #+END_SRC *** doc (markup samples) ./doc #+HEADER: :NO-tangle "../doc/COPYRIGHT" #+HEADER: :noweb yes #+BEGIN_SRC txt <> #+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