diff options
Diffstat (limited to 'org')
| -rw-r--r-- | org/config_dub.org | 11 | ||||
| -rw-r--r-- | org/config_env.org | 48 | ||||
| -rw-r--r-- | org/config_make.org | 19 | ||||
| -rw-r--r-- | org/config_nix.org | 39 | ||||
| -rw-r--r-- | org/spine_info.org | 461 |
5 files changed, 379 insertions, 199 deletions
diff --git a/org/config_dub.org b/org/config_dub.org index c91eb94..a6e715a 100644 --- a/org/config_dub.org +++ b/org/config_dub.org @@ -55,32 +55,33 @@ "license": "AGPL-3.0+", "targetPath": "./bin", "sourcePaths": [ "./src/sisudoc" ], + "importPaths": [ "./views" ], "stringImportPaths": [ "./views" ], "buildRequirements": [ "allowWarnings" ], "targetType": "executable", "buildTypes": { "dmd": { - "dflags": [ "-J=views", "-I=src/sisudoc" ], + "dflags": [ "-O", "-J=views", "-I=src/sisudoc" ], "buildOptions": [ "inline", "verbose" ], "buildRequirements": [ "allowWarnings" ] }, "ldc2": { - "dflags": [ "-O2", "-J=views", "-I=src/sisudoc" ], + "lflags": [ "-O2", "-I=src/sisudoc" ], "buildOptions": [ "optimize", "inline", "verbose" ], "buildRequirements": [ "allowWarnings" ] }, "ldmd2": { - "dflags": [ "-O2", "-boundscheck=on", "-J=views", "-I=src/sisudoc", "-color=on" ], + "dflags": [ "-O", "-J=views", "-I=src/sisudoc" ], "buildOptions": [ "optimize", "inline", "verbose" ], "buildRequirements": [ "allowWarnings" ] }, "gdc": { - "dflags": [ "-O2", "-J=views", "-I=src/sisudoc" ], + "lflags": [ "-O2", "-J=views", "-I=src/sisudoc" ], "buildOptions": [ "optimize", "inline" ], "buildRequirements": [ "allowWarnings" ] }, "gdmd": { - "dflags": [ "-O2", "-J=views", "-I=src/sisudoc" ], + "dflags": [ "-O", "-J=views", "-I=src/sisudoc" ], "buildOptions": [ "optimize", "inline" ], "buildRequirements": [ "allowWarnings" ] } diff --git a/org/config_env.org b/org/config_env.org index 744c898..165a53a 100644 --- a/org/config_env.org +++ b/org/config_env.org @@ -76,7 +76,7 @@ echo ' ❯❯ nix flake show ❯❯ nix flake update && nix flake check && nix flake show -- for a dev shell: +- for a dev shell (develop environment): ❯❯ nix develop ❯❯ nix develop ".#" --print-build-logs -c zsh ❯❯ nix develop ".#dsh-nixpkgs-dmd-dub" --print-build-logs -c zsh @@ -85,15 +85,29 @@ echo ' ❯❯ nix develop ".#dsh-overlay-ldc-dub" --print-build-logs -c zsh ❯❯ nix flake show -- to build project: +- to build project + ❯❯ nix build --print-build-logs ❯❯ nix build ".#" --print-build-logs + +- to build project (for build dependencies select appropriate dev env & build): + + ❯❯ nix develop ".#dsh-nixpkgs-dmd-dub" --print-build-logs -c zsh ❯❯ nix build ".#spine-nixpkgs-dmd" --print-build-logs + + ❯❯ nix develop ".#dsh-overlay-dmd-dub" --print-build-logs -c zsh ❯❯ nix build ".#spine-overlay-dmd" --print-build-logs + + ❯❯ nix develop ".#dsh-nixpkgs-ldc-dub" --print-build-logs -c zsh ❯❯ nix build ".#spine-nixpkgs-ldc" --print-build-logs + + ❯❯ nix develop ".#dsh-overlay-ldc-dub" --print-build-logs -c zsh ❯❯ nix build ".#spine-overlay-ldc" --print-build-logs - - (see nix other/additional build options): - ❯❯ nix flake show + + - for develop environment & build options + + ❯❯ nix flake show + ❯❯ nix flake update && nix flake check && nix flake show ' #+END_SRC @@ -166,19 +180,33 @@ fi #+HEADER: :tangle ../.envrc-local_ #+HEADER: :noweb yes #+BEGIN_SRC sh -export DFLAGS="-O2 -inline -boundscheck=on -color=on" export SpineVER=$(git describe --long --tags | sed 's/^[ a-z_-]\+\([0-9.]\+\)/\1/;s/\([^-]*-g\)/r\1/;s/-/./g') -export SpineBIN=result/bin -export SpinePROJ=~/grotto/repo/git.repo/projects/doc-reform/code/software/spine -export SpineDOC=~/grotto/repo/git.repo/projects/project-spine/doc-reform-markup/sisudoc-spine-markup-samples +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 -export SpineOUT=/srv/www/spine -export SpineOUTversioned=/srv/www/spine/${SpineVER} +# ❯❯ sisudoc-spine output processing path: +export SpineOUT=./OUTPUT_TEST_sisudocSpine +# ❯❯ sisudoc-spine output processing path (web server e.g.): +#export SpineOUT=/srv/www/spine +#export SpineOUTversioned=${SpineOUT}/${SpineVER} +# ❯❯ path configured for cgi search form: export SpineSearchActionLocal='http://localhost/spine_search' export SpineSearchActionRemote='https://sisudoc.org/spine_search' +# ❯❯ cgi search form name: 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 #export SpineDBpath=/srv/www/spine/sqlite #+END_SRC diff --git a/org/config_make.org b/org/config_make.org index 9e36285..abae71c 100644 --- a/org/config_make.org +++ b/org/config_make.org @@ -128,7 +128,7 @@ flake-check: echo -e '❯❯ nix build ".#spine-ldc" --print-build-logs |& nom\n❯❯ nix build ".#spine-dmd" --print-build-logs |& nom\n'; \ echo -e '❯❯ make -s\n❯❯ make -s nix-build-ldc\n❯❯ make -s nix-build-dmd\n'; \ echo -e '❯❯ make -s ldc\n❯❯ make -s dmd\n'; \ - echo -e '❯❯ $(DUB) --compiler=ldc2 --build=ldc2\n❯❯ $(DUB) --compiler=dmd --build=dmd\n'; + echo -e '❯❯ $(DUB) --compiler=ldmd2 --build=ldmd2\n❯❯ $(DUB) --compiler=dmd --build=dmd\n'; nix-devshell: echo -ne '\n❯❯ nix flake update && nix flake check --show-trace && nix flake show && nix develop ".#devShell"\n\n❯❯ nix build ".#default" --print-build-logs\n❯❯ nix build ".#spine-dmd" --print-build-logs\n❯❯ nix build ".#spine-ldc" --print-build-logs\n❯❯ nix build ".#spine-gdc" --print-build-logs\n\n'; \ @@ -164,7 +164,6 @@ buildPhase: exit 1; \ fi; \ echo "$${DC_} used as D compiler to build $${pname}"; \ - export DFLAGS="-O2 -inline"; \ dub build --compiler=$${DC} --build=$${DC_} --combined --skip-registry=all; checkPhase: @@ -623,7 +622,7 @@ all_clean: clean tangle dmd ldc gdc all_ver_clean: clean tangle dmd_ver ldc_ver gdc_ver dmd: dub_upgrade - $(DUB) --compiler=dmd --build=dmd --build=release-nobounds + $(DUB) --compiler=dmd --build=dmd notify-send -t 0 'D dmd compiled test release executable ready' 'spine-dmd' # assumes git tags with program version @@ -663,22 +662,26 @@ gdc_rel_tangle: tangle gdc_rel_expunge_tangle: expunge skel tangle gdc_rel_tangle ldc: dub_upgrade - $(DUB) --compiler=ldc2 --build=ldc2 --build=release + $(DUB) --compiler=ldmd2 --build=ldmd2 notify-send -t 0 'D ldc compiled test release executable ready' 'spine-ldc' +#ldc: dub_upgrade +# $(DUB) --compiler=ldc2 --build=ldc2 +# notify-send -t 0 'D ldc compiled test release executable ready' 'spine-ldc' + # assumes git tags with program version ldc_ver: dub_upgrade - $(DUB) --compiler=ldc2 --config=ldc-version + $(DUB) --compiler=ldmd2 --config=ldc-version mv bin/spine-ldc-ver bin-archive/spine-$(PROG_VER_DECLARED)-tag-$(PROG_VER_GIT)-ldc - notify-send -t 0 'D ldc2 compiled test release executable ready' 'spine-$(PROG_VER_DECLARED)-tag-$(PROG_VER_GIT)-ldc' + notify-send -t 0 'D ldc2 (ldmd2) compiled test release executable ready' 'spine-$(PROG_VER_DECLARED)-tag-$(PROG_VER_GIT)-ldc' ldc_clean_ver: clean tangle ldc_ver ldc_rel: expunge skel tangle - $(DUB) --compiler=ldc2 --config=spine-release + $(DUB) --compiler=ldmd2 --config=ldmd2 ldc_rel_tangle: tangle - $(DUB) --compiler=ldc2 --config=spine-ldc + $(DUB) --compiler=ldmd2 --config=ldmd2 ldc_rel_expunge_tangle: expunge skel tangle ldc_rel_tangle diff --git a/org/config_nix.org b/org/config_nix.org index efadebe..4495aea 100644 --- a/org/config_nix.org +++ b/org/config_nix.org @@ -72,7 +72,7 @@ pkgs-ovl = pkgsForSystem system; pkgs-nix = nixpkgsFor.${system}; in - with pkgs-ovl; { + with pkgs-nix; { default = stdenv.mkDerivation { inherit pname; inherit version; @@ -111,8 +111,8 @@ src = self; inherit shell; inherit devEnv; - buildInputs = with pkgs-nix; [sqlite]; - nativeBuildInputs = with pkgs-nix; [dub dmd gnumake]; + buildInputs = with pkgs-ovl; [sqlite]; + nativeBuildInputs = with pkgs-ovl; [dub dmd gnumake]; buildPhase = '' runHook preBuild buildCMD="dub build --cache=local --compiler=$(type -P dmd) --build=dmd --combined --skip-registry=all" @@ -135,10 +135,10 @@ inherit shell; inherit devEnv; buildInputs = with pkgs-nix; [sqlite]; - nativeBuildInputs = with pkgs-nix; [dub ldc gnumake]; + nativeBuildInputs = with pkgs-ovl; [dub ldc gnumake]; buildPhase = '' runHook preBuild - buildCMD="dub build --cache=local --compiler=$(type -P ldc2) --build=ldc2 --combined --skip-registry=all" + buildCMD="dub build --cache=local --compiler=$(type -P ldmd2) --build=ldmd2 --combined --skip-registry=all" echo $buildCMD $buildCMD echo $buildCMD @@ -157,8 +157,8 @@ src = self; inherit shell; inherit devEnv; - buildInputs = [sqlite]; - nativeBuildInputs = [dub dmd gnumake]; + buildInputs = with pkgs-ovl; [sqlite]; + nativeBuildInputs = with pkgs-ovl; [dub dmd gnumake]; buildPhase = '' runHook preBuild buildCMD="dub build --cache=local --compiler=$(type -P dmd) --build=dmd --combined --skip-registry=all" @@ -180,11 +180,11 @@ src = self; inherit shell; inherit devEnv; - buildInputs = [sqlite]; - nativeBuildInputs = [dub ldc gnumake]; + buildInputs = with pkgs-ovl; [sqlite]; + nativeBuildInputs = with pkgs-ovl; [dub ldc gnumake]; buildPhase = '' runHook preBuild - buildCMD="dub build --cache=local --compiler=$(type -P ldc2) --build=ldc2 --combined --skip-registry=all" + buildCMD="dub build --cache=local --compiler=$(type -P ldmd2) --build=ldmd2 --combined --skip-registry=all" echo $buildCMD $buildCMD echo $buildCMD @@ -203,8 +203,8 @@ # src = self; # inherit shell; # inherit devEnv; - # buildInputs = [ sqlite ]; - # nativeBuildInputs = [ dub gdc gnumake ]; + # buildInputs = with pkgs-ovl; [ sqlite ]; + # nativeBuildInputs = with pkgs-ovl; [ dub gdc gnumake ]; # buildPhase = '' # runHook preBuild # dub build --cache=local --compiler=$(type -P gdc) --build=gdc --combined --skip-registry=all @@ -227,16 +227,15 @@ pkgs-ovl = pkgsForSystem system; pkgs-nix = nixpkgsFor.${system}; shellHook = '' - export DFLAGS="-O2 -boundscheck=on" export Date=`date "+%Y%m%d"` ''; in - with pkgs-ovl; { + with pkgs-nix; { dsh-overlay = mkShell { name = "spine base dev shell"; inherit shell; inherit devEnv; - packages = [ + packages = with pkgs-ovl; [ ldc #dmd dub @@ -249,7 +248,7 @@ name = "spine base dev shell"; inherit shell; inherit devEnv; - packages = with pkgs-nix; [ + packages = [ dmd dub gnumake @@ -261,7 +260,7 @@ name = "spine base dev shell"; inherit shell; inherit devEnv; - packages = with pkgs-nix; [ + packages = [ ldc dub gnumake @@ -273,7 +272,7 @@ name = "spine base dev shell"; inherit shell; inherit devEnv; - packages = [ + packages = with pkgs-ovl; [ dmd dub gnumake @@ -285,7 +284,7 @@ name = "spine base dev shell"; inherit shell; inherit devEnv; - packages = [ + packages = with pkgs-ovl; [ ldc dub gnumake @@ -566,7 +565,6 @@ with ( buildPhase = '' runHook preBuild HOME="$PWD" - DFLAGS="-O2 -inline" for DC_ in dmd ldmd2 gdmd; do echo "- check for D compiler $DC_" DC=$(type -P $DC_ || echo "") @@ -1000,7 +998,6 @@ buildPhase: exit 1; \ fi; \ echo "$${DC_} used as D compiler to build $${pname}"; \ - export DFLAGS="-O2 -inline"; \ dub build --compiler=$${DC} --build=release --combined --skip-registry=all; checkPhase: runHook preCheck; \ diff --git a/org/spine_info.org b/org/spine_info.org index 4cfa865..7d09b92 100644 --- a/org/spine_info.org +++ b/org/spine_info.org @@ -25,17 +25,15 @@ #+HEADER: :tangle "../README" #+HEADER: :noweb yes #+BEGIN_SRC text -<<sisu_spine_readme_org_header>> +<<sisudoc_spine_readme_org_header>> -<<sisu_spine_readme_info>> +<<sisudoc_spine_readme_info>> -<<sisu_spine_readme_install_org>> +<<sisudoc_spine_readme_install_org>> -<<sisu_spine_readme_configuration_org>> +<<sisudoc_spine_readme_examples_org>> -<<sisu_spine_readme_commands_org>> - -<<sisu_spine_readme_examples_org>> +<<sisudoc_spine_readme_commands_org>> #+END_SRC *** md @@ -43,20 +41,18 @@ #+HEADER: :tangle "../README.md" #+HEADER: :noweb yes #+BEGIN_SRC text -<<sisu_spine_readme_info>> - -<<sisu_spine_readme_install_md>> +<<sisudoc_spine_readme_info>> -<<sisu_spine_readme_configuration_md>> +<<sisudoc_spine_readme_install_md>> -<<sisu_spine_readme_commands_md>> +<<sisudoc_spine_readme_examples_md>> -<<sisu_spine_readme_examples_md>> +<<sisudoc_spine_readme_commands_md>> #+END_SRC ** org header -#+NAME: sisu_spine_readme_org_header +#+NAME: sisudoc_spine_readme_org_header #+BEGIN_SRC text -*- mode: org -*- #+TITLE: spine (sisudoc) (project) README @@ -78,7 +74,7 @@ ** project name -#+NAME: sisu_spine_readme_info +#+NAME: sisudoc_spine_readme_info #+BEGIN_SRC yaml project_name: Spine, Doc Reform @@ -106,72 +102,150 @@ project_name: Spine, Doc Reform ** short description (currently UNUSED) -#+NAME: sisu_spine_readme_description +#+NAME: sisudoc_spine_readme_description #+BEGIN_SRC text #+END_SRC ** installation *** org -#+NAME: sisu_spine_readme_install_org +#+NAME: sisudoc_spine_readme_install_org #+HEADER: :noweb yes #+BEGIN_SRC text -,* <<sisu_spine_readme_install_heading>> +,* <<sisudoc_spine_readme_install_h1>> + +<<sisudoc_spine_readme_install_body_summary>> + +,** <<sisudoc_spine_readme_install_body_clone_h2>> + +<<sisudoc_spine_readme_install_body_clone>> -<<sisu_spine_readme_install_body>> +,** <<sisudoc_spine_readme_install_body_build_h2>> + +<<sisudoc_spine_readme_install_body_build>> #+END_SRC *** md -#+NAME: sisu_spine_readme_install_md +#+NAME: sisudoc_spine_readme_install_md #+HEADER: :noweb yes #+BEGIN_SRC markdown -# <<sisu_spine_readme_install_heading>> +## <<sisudoc_spine_readme_install_h1>> + +<<sisudoc_spine_readme_install_body_summary>> + +## <<sisudoc_spine_readme_install_body_clone_h2>> + +<<sisudoc_spine_readme_install_body_clone>> + +## <<sisudoc_spine_readme_install_body_build_h2>> -<<sisu_spine_readme_install_body>> +<<sisudoc_spine_readme_install_body_build>> #+END_SRC *** heading -#+NAME: sisu_spine_readme_install_heading +#+NAME: sisudoc_spine_readme_install_h1 #+BEGIN_SRC text Installation, Compilation #+END_SRC *** text body -#+NAME: sisu_spine_readme_install_body +#+NAME: sisudoc_spine_readme_install_body_summary #+BEGIN_SRC markdown -SiSU spine is written in the programming language D for which there are 3 compilers: +Development of sisudoc-spine started in 2015 on a Debian linux box. -- dmd -- ldc -- gdc +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://code.dlang.org/packages/dub -https://github.com/dlang/dub/blob/master/source/dub/commandline.d +- 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_readme_install_body_clone_h2 +#+BEGIN_SRC markdown +make a directory and clone the sisudoc-spine project-heading +#+END_SRC + +#+NAME: sisudoc_spine_readme_install_body_clone +#+BEGIN_SRC markdown +# make a directory and clone the sisudoc-spine project - dub --compiler=ldc2 -color --config=ldc -b release + mkdir ~/git.sisudoc + cd ~/git.sisudoc - dub --compiler=dmd -color --config=dmd + 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 - dub --compiler=gdc-10 -color --config=gdc -b release +such a relative directory layout will be assumed in the examples that provided +#+END_SRC + +#+NAME: sisudoc_spine_readme_install_body_build_h2 +#+BEGIN_SRC markdown +build sisudoc-spine +#+END_SRC + +#+NAME: sisudoc_spine_readme_install_body_build +#+BEGIN_SRC markdown +## directly with dub +### ldc2 + + dub --compiler=ldmd2 --config=ldmd2 + dub --verbose --compiler=ldmd2 -color --config=ldmd2 + + dub --compiler=ldc2 --config=ldc2 + dub --verbose --compiler=ldc2 -color --config=ldc2 + +### dmd + + dub --compiler=dmd --config=dmd + +## with make + +### ldc2 make ldc +### dmd + make dmd -there has been some coalescence around the Meson build system -https://mesonbuild.com/ +## with nix on linux / nixos - meson +### ldc2 - ninja -C build + nix develop ".#dsh-nixpkgs-ldc-dub" --print-build-logs -c zsh + nix build ".#spine-nixpkgs-ldc" --print-build-logs - meson setup --wipe build && ninja -v -C build +### dmd + + nix develop ".#dsh-nixpkgs-dmd-dub" --print-build-logs -c zsh + nix build ".#spine-nixpkgs-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/. @@ -180,34 +254,34 @@ dub --force --compiler=ldc2 && sudo cp -v cgi-bin/spine-search /usr/lib/cgi-bin/ ** configuration *** org -#+NAME: sisu_spine_readme_configuration_org +#+NAME: sisudoc_spine_readme_configuration_org #+HEADER: :noweb yes #+BEGIN_SRC text -,* <<sisu_spine_readme_configuration_heading>> +,* <<sisudoc_spine_readme_configuration_h1>> -<<sisu_spine_readme_configuration_body>> +<<sisudoc_spine_readme_configuration_body>> #+END_SRC *** md -#+NAME: sisu_spine_readme_configuration_md +#+NAME: sisudoc_spine_readme_configuration_md #+HEADER: :noweb yes #+BEGIN_SRC markdown -# <<sisu_spine_readme_configuration_heading>> +# <<sisudoc_spine_readme_configuration_h1>> -<<sisu_spine_readme_configuration_body>> +<<sisudoc_spine_readme_configuration_body>> #+END_SRC *** heading -#+NAME: sisu_spine_readme_configuration_heading +#+NAME: sisudoc_spine_readme_configuration_h1 #+BEGIN_SRC text Configuration #+END_SRC *** text body -#+NAME: sisu_spine_readme_configuration_body +#+NAME: sisudoc_spine_readme_configuration_body #+BEGIN_SRC markdown Configuration files are yaml files @@ -271,63 +345,71 @@ webserv: ** commands help *** org -#+NAME: sisu_spine_readme_commands_org +#+NAME: sisudoc_spine_readme_commands_org #+HEADER: :noweb yes #+BEGIN_SRC text -,* <<sisu_spine_readme_commands_heading>> +,* <<sisudoc_spine_readme_commands_h2>> -<<sisu_spine_readme_commands_body>> +<<sisudoc_spine_readme_commands_body>> #+END_SRC *** md -#+NAME: sisu_spine_readme_commands_md +#+NAME: sisudoc_spine_readme_commands_md #+HEADER: :noweb yes #+BEGIN_SRC markdown -# <<sisu_spine_readme_commands_heading>> +# <<sisudoc_spine_readme_commands_h2>> -<<sisu_spine_readme_commands_body>> +<<sisudoc_spine_readme_commands_body>> #+END_SRC *** heading -#+NAME: sisu_spine_readme_commands_heading +#+NAME: sisudoc_spine_readme_commands_h2 #+BEGIN_SRC text Commands #+END_SRC *** text body -#+NAME: sisu_spine_readme_commands_body +#+NAME: sisudoc_spine_readme_commands_body #+BEGIN_SRC markdown 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-search-form-codegen generates (pre-compiled) d code for search of specified db - --cgi-sqlite-search-filename =[filename] + --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 - --config =/path/to/config/file/including/filename + --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 - --debug debug --digest hash digest for each object --epub process epub output - --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 + --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-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 output for pdfs + --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 @@ -338,6 +420,7 @@ at the time of writing this provides the following output: --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) @@ -351,18 +434,35 @@ at the time of writing this provides the following output: --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-db-filename =[filename].sql.db --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 @@ -371,93 +471,149 @@ at the time of writing this provides the following output: --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 ** command examples *** text body org -#+NAME: sisu_spine_readme_examples_org +#+NAME: sisudoc_spine_readme_examples_org #+HEADER: :noweb yes #+BEGIN_SRC markdown -,* Examples +,* Document processing examples + +<<sisudoc_spine_readme_env_exports>> + +,*** html with links to search form + +<<sisudoc_spine_readme_examples_html_with_links_to_search_form_text>> ,** curate -<<sisu_spine_readme_examples_curate_text>> +<<sisudoc_spine_readme_examples_curate_text>> ,** sqlite -<<sisu_spine_readme_examples_sqlite_text>> +<<sisudoc_spine_readme_examples_sqlite_text>> ,*** create db -<<sisu_spine_readme_examples_create_db_text>> +<<sisudoc_spine_readme_examples_create_db_text>> ,*** populate db -<<sisu_spine_readme_examples_populate_db_text>> +<<sisudoc_spine_readme_examples_populate_db_text>> ,*** generate a cgi search form in d - <<sisu_spine_readme_examples_search_db_cgi_text>> + <<sisudoc_spine_readme_examples_search_db_cgi_text>> ,**** compile the cgi search form -<<sisu_spine_readme_examples_compile_search_db_cgi_text>> +<<sisudoc_spine_readme_examples_compile_search_db_cgi_text>> ,*** create db & search form - <<sisu_spine_readme_examples_create_db_and_search_form_text>> + <<sisudoc_spine_readme_examples_create_db_and_search_form_text>> +#+END_SRC -,*** html with links to search form +*** env exports - <<sisu_spine_readme_examples_html_with_links_to_search_form_text>> +#+NAME: sisudoc_spine_readme_env_exports +#+BEGIN_SRC markdown +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 +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 *** text body md -#+NAME: sisu_spine_readme_examples_md +#+NAME: sisudoc_spine_readme_examples_md #+HEADER: :noweb yes #+BEGIN_SRC markdown -# Examples +# Document processing examples + +<<sisudoc_spine_readme_env_exports>> + +### html with links to search form + +<<sisudoc_spine_readme_examples_html_with_links_to_search_form_text>> ## curate -<<sisu_spine_readme_examples_curate_text>> +<<sisudoc_spine_readme_examples_curate_text>> ## sqlite -<<sisu_spine_readme_examples_sqlite_text>> +<<sisudoc_spine_readme_examples_sqlite_text>> ### create db -<<sisu_spine_readme_examples_create_db_text>> +<<sisudoc_spine_readme_examples_create_db_text>> ### populate db -<<sisu_spine_readme_examples_populate_db_text>> +<<sisudoc_spine_readme_examples_populate_db_text>> ### generate a cgi search form in d - <<sisu_spine_readme_examples_search_db_cgi_text>> + <<sisudoc_spine_readme_examples_search_db_cgi_text>> #### compile the cgi search form -<<sisu_spine_readme_examples_compile_search_db_cgi_text>> +<<sisudoc_spine_readme_examples_compile_search_db_cgi_text>> ### create db & search form - <<sisu_spine_readme_examples_create_db_and_search_form_text>> - -### html with links to search form - - <<sisu_spine_readme_examples_html_with_links_to_search_form_text>> + <<sisudoc_spine_readme_examples_create_db_and_search_form_text>> #+END_SRC *** text body content -#+NAME: sisu_spine_readme_examples_curate_text +#+NAME: sisudoc_spine_readme_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 @@ -471,7 +627,7 @@ summary of the collection can be made using the curate command spine -v --html --html-link-search --html-link-curate --curate ~spineMarkupSamples/pod/* #+END_SRC -#+NAME: sisu_spine_readme_examples_sqlite_text +#+NAME: sisudoc_spine_readme_examples_sqlite_text #+BEGIN_SRC text if configuartion has been set specify just - the desired output and @@ -479,7 +635,7 @@ if configuartion has been set specify just spine -v --html ~spineMarkupSamples/markup/pod/sisu-manual -if configuartion has not been set or to overide the set configration specify +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 @@ -493,7 +649,7 @@ note: ~webDocRoot should be the path to web doc root, provide a suitable output spine -v --html --epub --latex --odt --curate --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* #+END_SRC -#+NAME: sisu_spine_readme_examples_create_db_text +#+NAME: sisudoc_spine_readme_examples_create_db_text #+BEGIN_SRC text if there is no sqlite db you first need to create one, to do so - the name of the db and @@ -513,7 +669,7 @@ for a document collection you can point to the document collection: spine -v --sqlite-db-create ~spineMarkupSamples/pod #+END_SRC -#+NAME: sisu_spine_readme_examples_populate_db_text +#+NAME: sisudoc_spine_readme_examples_populate_db_text #+BEGIN_SRC text must specify: - the name of the db and @@ -532,7 +688,7 @@ for a document collection you can point to the document collection: spine -v --sqlite-update ~spineMarkupSamples/pod/* #+END_SRC -#+NAME: sisu_spine_readme_examples_search_db_cgi_text +#+NAME: sisudoc_spine_readme_examples_search_db_cgi_text #+BEGIN_SRC text spine -v --cgi-search-form-codegen \ --output=/var/www/html \ @@ -553,7 +709,7 @@ spine -v --cgi-search-form-codegen \ ~spineMarkupSamples/pod #+END_SRC -#+NAME: sisu_spine_readme_examples_compile_search_db_cgi_text +#+NAME: sisudoc_spine_readme_examples_compile_search_db_cgi_text #+BEGIN_SRC text cd /var/www/html/cgi # /var/www/html (default document root) @@ -577,9 +733,12 @@ cgi-bin directory 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: sisu_spine_readme_examples_create_db_and_search_form_text +#+NAME: sisudoc_spine_readme_examples_create_db_and_search_form_text #+BEGIN_SRC text spine -v \ --sqlite-db-create --sqlite-db-filename="spine.search.db" \ @@ -588,12 +747,18 @@ spine -v \ ~spineMarkupSamples/pod/* #+END_SRC -#+NAME: sisu_spine_readme_examples_html_with_links_to_search_form_text +#+NAME: sisudoc_spine_readme_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` \ - ~spineMarkupSamples/pod/* + ${SpinePOD}/* #+END_SRC * manpage :manpage: @@ -602,21 +767,21 @@ spine -v --html \ #+HEADER: :tangle "../doc/man/man1/spine.1" #+HEADER: :noweb yes #+BEGIN_SRC man -<<sisu_spine_manpage_head>> -<<sisu_spine_manpage_description>> -<<sisu_spine_manpage_flags>> -<<sisu_spine_manpage_flags_db>> -<<sisu_spine_manpage_config>> -<<sisu_spine_manpage_pod_dir_structure>> -<<sisu_spine_manpage_cli_examples>> -<<sisu_spine_manpage_docs>> -<<sisu_spine_manpage_markup>> +<<sisudoc_spine_manpage_head>> +<<sisudoc_spine_manpage_description>> +<<sisudoc_spine_manpage_flags>> +<<sisudoc_spine_manpage_flags_db>> +<<sisudoc_spine_manpage_config>> +<<sisudoc_spine_manpage_pod_dir_structure>> +<<sisudoc_spine_manpage_cli_examples>> +<<sisudoc_spine_manpage_docs>> +<<sisudoc_spine_manpage_markup>> #+END_SRC ** manpage *** head -#+NAME: sisu_spine_manpage_head +#+NAME: sisudoc_spine_manpage_head #+BEGIN_SRC man .TH "spine" "1" "2020-04-05" "0.10.0" "Spine" .br @@ -638,7 +803,7 @@ sisu --pg (--createdb|update [filename/wildcard]|--dropall) *** description -#+NAME: sisu_spine_manpage_description +#+NAME: sisudoc_spine_manpage_description #+BEGIN_SRC man .SH SISU - MANUAL, RALPH AMISSAH @@ -738,7 +903,7 @@ document structure information. For more see: <https://sisudoc.org> or ** flags *** general -#+NAME: sisu_spine_manpage_flags +#+NAME: sisudoc_spine_manpage_flags #+BEGIN_SRC man .SH DOCUMENT PROCESSING COMMAND FLAGS @@ -1047,7 +1212,7 @@ Produce output without identifying numbers in margins of html or *** db flags -#+NAME: sisu_spine_manpage_flags_db +#+NAME: sisudoc_spine_manpage_flags_db #+BEGIN_SRC man .SH DATABASE COMMANDS @@ -1116,7 +1281,7 @@ The -v is for verbose output. ** configuration file -#+NAME: sisu_spine_manpage_config +#+NAME: sisudoc_spine_manpage_config #+BEGIN_SRC man .SH CONFIGURATION @@ -1167,7 +1332,7 @@ webserv: ** sample pod directory -#+NAME: sisu_spine_manpage_pod_dir_structure +#+NAME: sisudoc_spine_manpage_pod_dir_structure #+BEGIN_SRC man .SH SAMPLE POD DIRECTORY STRUCTURE .BR @@ -1200,7 +1365,7 @@ pod (directory may contain multiple documents) ** examples -#+NAME: sisu_spine_manpage_cli_examples +#+NAME: sisudoc_spine_manpage_cli_examples #+BEGIN_SRC man .SH COMMAND LINE EXAMPLES @@ -1236,7 +1401,7 @@ dub --force --compiler=ldc2 && sudo cp -v cgi-bin/spine-search /usr/lib/cgi-bin/ ** docs *** sources -#+NAME: sisu_spine_manpage_docs +#+NAME: sisudoc_spine_manpage_docs #+BEGIN_SRC man .BR @@ -1311,7 +1476,7 @@ Available man pages are converted back to html using man2html: *** markup -#+NAME: sisu_spine_manpage_markup +#+NAME: sisudoc_spine_manpage_markup #+BEGIN_SRC man .SH INTRODUCTION TO SISU MARKUP[^3] @@ -4728,15 +4893,15 @@ matches are found. #+HEADER: :noweb yes #+BEGIN_SRC txt - Name: spine - SiSU Spine, Doc Reform - <<sisu_spine_copyright>> + <<sisudoc_spine_copyright>> - <<sisu_spine_license_agpl3>> + <<sisudoc_spine_license_agpl3>> - <<sisu_spine_summary>> + <<sisudoc_spine_summary>> -<<sisu_spine_markup_samples>> +<<sisudoc_spine_markup_samples>> -<<sisu_spine_dependencies>> +<<sisudoc_spine_dependencies>> #+END_SRC *** code source ./src @@ -4745,15 +4910,15 @@ matches are found. #+HEADER: :noweb yes #+BEGIN_SRC txt - Name: spine - SiSU Spine, Doc Reform - <<sisu_spine_copyright>> + <<sisudoc_spine_copyright>> - <<sisu_spine_license_agpl3>> + <<sisudoc_spine_license_agpl3>> - <<sisu_spine_summary>> + <<sisudoc_spine_summary>> -<<sisu_spine_markup_samples>> +<<sisudoc_spine_markup_samples>> -<<sisu_spine_dependencies>> +<<sisudoc_spine_dependencies>> #+END_SRC *** code source ./src/sisudoc @@ -4762,15 +4927,15 @@ matches are found. #+HEADER: :noweb yes #+BEGIN_SRC txt - Name: spine - SiSU Spine, Doc Reform - <<sisu_spine_copyright>> + <<sisudoc_spine_copyright>> - <<sisu_spine_license_agpl3>> + <<sisudoc_spine_license_agpl3>> - <<sisu_spine_summary>> + <<sisudoc_spine_summary>> -<<sisu_spine_markup_samples>> +<<sisudoc_spine_markup_samples>> -<<sisu_spine_dependencies>> +<<sisudoc_spine_dependencies>> #+END_SRC *** org files ./org @@ -4785,11 +4950,11 @@ matches are found. #+HEADER: :noweb yes #+BEGIN_SRC txt - Name: spine - SiSU Spine, Doc Reform - <<sisu_spine_copyright>> + <<sisudoc_spine_copyright>> - <<sisu_spine_summary>> + <<sisudoc_spine_summary>> -<<sisu_spine_markup_samples>> +<<sisudoc_spine_markup_samples>> #+END_SRC *** doc (markup samples) ./doc @@ -4803,7 +4968,7 @@ matches are found. ** incorporate *** copyright -#+NAME: sisu_spine_copyright +#+NAME: sisudoc_spine_copyright #+BEGIN_SRC txt - Description: documents, structuring, processing, publishing, search - static content generator @@ -4817,7 +4982,7 @@ matches are found. *** license **** AGPLv3 -#+NAME: sisu_spine_license_agpl3 +#+NAME: sisudoc_spine_license_agpl3 #+BEGIN_SRC txt - code under src/* src/sisudoc/* - License: AGPL 3 or later: @@ -4848,7 +5013,7 @@ matches are found. *** spine_summary -#+NAME: sisu_spine_summary +#+NAME: sisudoc_spine_summary #+BEGIN_SRC txt - Spine, Doc Reform (related to SiSU) uses standard: - docReform markup syntax (based on SiSU markup) @@ -4872,7 +5037,7 @@ matches are found. *** markup_samples -#+NAME: sisu_spine_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] @@ -4881,7 +5046,7 @@ matches are found. *** dependencies -#+NAME: sisu_spine_dependencies +#+NAME: sisudoc_spine_dependencies #+BEGIN_SRC txt - Dependencies [check dub.json or dub.sdl] @@ -4986,20 +5151,6 @@ matches are found. [https://github.com/adamdruppe/arsd] - sundry/spine_search_cgi/src/ext_depends_cgi/arsd - -- Name: dub2nix - - Description: - - - Author: - [Lionello Lunesu] - - - Copyright: (C) 2019 Lionello Lunesu - - - code: mkDub.nix (modified as needed) - - License: MIT License - - - Homepages: - [https://github.com/lionello/dub2nix] #+END_SRC * CHANGELOG :changelog: |