-*- 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 <> <> ,* Summary <> ,* Build Configuration <> ,* Compilation, Installation ,** D compiler (dmd, ldc2) & D build manager (dub) <> ,** make a directory & clone the sisudoc-spine project <> ,** build sisudoc-spine <> ,*** build using nix flakes on linux (binary in ./result/bin) <> ,*** build using dub directly (binary in ./bin) <> ,* Commands <> #+END_SRC **** org header #+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 #+HEADER: :tangle "../README.md" #+HEADER: :noweb yes #+BEGIN_SRC text <> # Summary <> # Build Configuration <> # Compilation, Installation ## D compiler (dmd, ldc2) & D build manager (dub) <> ## make a directory & clone the sisudoc-spine project <> ## build sisudoc-spine <> ### build using nix flakes on linux (binary in ./result/bin) <> ### build using dub directly (binary in ./bin) <> # Commands <> #+END_SRC ** project yaml header #+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" 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 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). #+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 (or just sisudoc-spine- search-cgi as needed) Make a directory and clone the sisudoc-spine project mkdir ~/git.sisudoc cd ~/git.sisudoc git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine && \ git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine-search-cgi && \ git clone --depth=1 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 *** install & build cgi search form **** install & build cgi search form #+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 cd sisudoc-spine-search-cgi NOTE: - if dub is used to build, the resulting binary should be located in ./bin: - if "nix build" is used the resulting binary should be in ./result/bin cd sisudoc-spine #+END_SRC **** install build project using nix flakes #+NAME: sisudoc_spine_README_install_build_using_nix_flakes #+BEGIN_SRC text you need to have nix installed on your system, and to have nix flakes enabled, on Debian for example, you would do the following: sudo apt install nix create the file in the given path & filename: ~/.config/nix/nix.conf with the following content: experimental-features = flakes nix-command which can be achieved thusly: mkdir -p ~/.config/nix && echo "experimental-features = flakes nix-command" >> ~/.config/nix/nix.conf - to use the D compiler ldc2: nix build ".#spine-search-nixpkgs-ldc" --print-build-logs # or nix build ".#spine-search-overlay-ldc" --print-build-logs - to use the D compiler dmd: nix build ".#spine-search-nixpkgs-dmd" --print-build-logs # or nix build ".#spine-search-overlay-dmd" --print-build-logs #+END_SRC #+END_SRC **** install build project using dub directly #+NAME: sisudoc_spine_README_install_build_using_dub_directly #+BEGIN_SRC text - to use the D compiler 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 or dub run --compiler=ldc2 --config=ldc2 --combined --skip-registry=all - to use the D compiler 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 #+END_SRC ** configuration #+NAME: sisudoc_spine_README_build_configuration #+BEGIN_SRC text 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 #+NAME: sisudoc_spine_README_commands #+BEGIN_SRC text 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 text - Name: spine - SiSU Spine, Doc Reform <> <> <> <> <> #+END_SRC *** code source ./src #+HEADER: :tangle "../src/COPYRIGHT" #+HEADER: :noweb yes #+BEGIN_SRC text - Name: spine - SiSU Spine, Doc Reform <> <> <> <> <> #+END_SRC *** code source ./src/sisudoc #+HEADER: :tangle "../src/sisudoc/COPYRIGHT" #+HEADER: :noweb yes #+BEGIN_SRC text - Name: spine - SiSU Spine, Doc Reform <> <> <> <> <> #+END_SRC *** org files ./org - .org literate programming: - copyright asserted - omitted - license - dependency information #+HEADER: :tangle "../org/COPYRIGHT" #+HEADER: :noweb yes #+BEGIN_SRC text - Name: spine - SiSU Spine, Doc Reform <> <> <> #+END_SRC *** doc (markup samples) ./doc #+HEADER: :tangle-NO "../doc/COPYRIGHT" #+HEADER: :noweb yes #+BEGIN_SRC text <> #+END_SRC ** incorporate *** copyright #+NAME: sisudoc_spine_copyright #+BEGIN_SRC text - 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 text - 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 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 modifications - docReform object numbering (based on SiSU object citation numbering) - standard SiSU document object numbering - Homepages: [https://www.sisudoc.org] #+END_SRC #+BEGIN_SRC text - Homepages: [https://www.sisudoc.org] [https://www.sisudoc.org] - Git [] #+END_SRC *** markup_samples #+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] #+END_SRC *** dependencies #+NAME: sisudoc_spine_dependencies #+BEGIN_SRC text - 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