aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--.envrc-local_26
-rw-r--r--.envrc-nix22
-rw-r--r--README376
-rw-r--r--README.md378
-rw-r--r--derivation.nix1
-rw-r--r--dub.json11
-rw-r--r--flake.lock6
-rw-r--r--flake.nix37
-rw-r--r--makefile19
-rw-r--r--org/config_dub.org11
-rw-r--r--org/config_env.org48
-rw-r--r--org/config_make.org19
-rw-r--r--org/config_nix.org39
-rw-r--r--org/spine_info.org461
14 files changed, 904 insertions, 550 deletions
diff --git a/.envrc-local_ b/.envrc-local_
index 83afce0..fdb7953 100644
--- a/.envrc-local_
+++ b/.envrc-local_
@@ -1,15 +1,29 @@
-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
diff --git a/.envrc-nix b/.envrc-nix
index 9602489..f0e1774 100644
--- a/.envrc-nix
+++ b/.envrc-nix
@@ -20,7 +20,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
@@ -29,13 +29,27 @@ 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
'
diff --git a/README b/README
index 2695e17..d1a6c1f 100644
--- a/README
+++ b/README
@@ -40,176 +40,137 @@ project_name: Spine, Doc Reform
* Installation, Compilation
-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)
+
+** make a directory and clone the sisudoc-spine project-heading
+
+# 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
+
+** build sisudoc-spine
+
+## directly with dub
+### ldc2
- dub --compiler=ldc2 -color --config=ldc -b release
+ dub --compiler=ldmd2 --config=ldmd2
+ dub --verbose --compiler=ldmd2 -color --config=ldmd2
- dub --compiler=dmd -color --config=dmd
+ dub --compiler=ldc2 --config=ldc2
+ dub --verbose --compiler=ldc2 -color --config=ldc2
- dub --compiler=gdc-10 -color --config=gdc -b release
+### 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/.
-* Configuration
-
-Configuration files are yaml files
-
-The following paths are searched:
-
- ~/.dr/config_local_site
- ~/path_to_pod_root/.dr/config_local_site
-
-e.g. processing
-
- ~spineMarkupSamples/pod/*
-
-will search:
-
- ~spineMarkupSamples/pod/.dr/config_local_site
-
- ~/.dr/config_local_site
-
-to specify an alternative configuration file to use on the command line (in this
-example named "my_config"):
-
- spine -v --html --config=~spineMarkupSamples/pod/.dr/my_config
-
-here is a sample configuration file:
-
-flag:
- act0: "--html"
- act1: "--html --epub"
-output:
- path: "/var/www/html"
-default:
- language: "en"
- papersize: "a4"
- text_wrap: "80"
- digest: "sha256"
-webserv:
- http: "http"
- host: "localhost"
- data_http: "http"
- data_host: "localhost"
- data_root_url: "http://localhost"
- data_root_path: "/var/www/html"
- data_root_part: ""
- images_root_part: "image"
- cgi_search_form_title: "≅ SiSU Spine search ፨"
- cgi_http: "http"
- cgi_host: "localhost"
- cgi_bin_url: "http://localhost/cgi-bin"
- cgi_bin_subpath: "/cgi-bin"
- cgi_bin_path: "/usr/lib/cgi-bin"
- cgi_search_script: "spine-search"
- cgi_search_script_raw_fn_d: "spine_search.d"
- cgi_port: ""
- cgi_user: ""
- cgi_action: "http://localhost/cgi-bin/spine-search"
- db_sqlite: "spine.search.db"
- db_pg_table: ""
- db_pg_user: ""
-
-* Commands
+* Document processing examples
+
+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
-for a list of commands from the program type:
+*** html with links to search form
- spine -h
+${SpineBIN} -v --epub --html --html-link-curate --curate --output=${SpineOUT} ${SpinePOD}/*
-at the time of writing this provides the following output:
+${SpineBIN} -v --source --pod --latex --latex-init --epub --html --html-link-pdf --html-link-curate --html-link-markup --curate --output=${SpineOUT} ${SpinePOD}/*
- --abstraction document abstraction
- --assert set optional assertions on
- --cgi-search-form-codegen generates (pre-compiled) d code for search of specified db
- --cgi-sqlite-search-filename =[filename]
- --concordance file for document
- --config =/path/to/config/file/including/filename
- --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
- --hide-ocn object cite numbers
- --html process html output
- --html-link-curate place links back to curate in segmented html
- --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-color-links mono or color links for pdfs
- --light default light theme
- --manifest process manifest output
- --ocn-off object cite numbers
- --odf open document format text (--odt)
- --odt open document format text
- --output =/path/to/output/dir specify where to place output
- --parallel parallelisation
- --parallel-subprocesses nested parallelisation
- --pdf latex output for pdfs
- --pdf-color-links mono or color links for pdfs
- --pod spine (doc reform) pod source content bundled
--q --quiet output to terminal
- --section-backmatter document backmatter (default)
- --section-biblio document biblio (default)
- --section-blurb document blurb (default)
- --section-body document body (default)
- --section-bookindex document bookindex (default)
- --section-endnotes document endnotes (default)
- --section-glossary document glossary (default)
- --section-toc table of contents (default)
- --serial serial processing
- --skip-output skip output
- --show-config show config
- --show-make show make
- --show-metadata show metadata
- --show-summary show summary
- --source document markup source
- --sqlite-discrete process discrete sqlite output
- --sqlite-db-create create db, create tables
- --sqlite-db-drop drop tables & db
- --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
- --text text output
- --theme-dark alternative dark theme
- --theme-light default light theme
- --txt text output
--v --verbose output to terminal
- --very-verbose output to terminal
- --workon (reserved for some matters under development & testing)
- --xhtml xhtml output
--h --help This help information.
+${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}/*
-* Examples
+spine -v --html \
+ --html-link-search \
+ --output=`echo ~webDocRoot` \
+ ${SpinePOD}/*
** curate
@@ -232,7 +193,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
@@ -327,6 +288,9 @@ cgi-bin directory
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}/*
+
+
*** create db & search form
spine -v \
@@ -335,9 +299,117 @@ cgi-bin directory
--output=/var/www/html \
~spineMarkupSamples/pod/*
-*** html with links to search form
+* Commands
- spine -v --html \
- --html-link-search \
- --output=`echo ~webDocRoot` \
- ~spineMarkupSamples/pod/*
+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-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
+ --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
+ --digest hash digest for each object
+ --epub process epub output
+ --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-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 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
+ --odf open document format text (--odt)
+ --odt open document format text
+ --output =/path/to/output/dir specify where to place output
+ --parallel parallelisation
+ --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)
+ --section-biblio document biblio (default)
+ --section-blurb document blurb (default)
+ --section-body document body (default)
+ --section-bookindex document bookindex (default)
+ --section-endnotes document endnotes (default)
+ --section-glossary document glossary (default)
+ --section-toc table of contents (default)
+ --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-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
+ --txt text output
+-v --verbose output to terminal
+ --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.
diff --git a/README.md b/README.md
index 586e5c1..9d4afc4 100644
--- a/README.md
+++ b/README.md
@@ -21,178 +21,139 @@ project_name: Spine, Doc Reform
"https://www.doc-reform.org"
]
-# Installation, Compilation
+## Installation, Compilation
-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)
+
+## make a directory and clone the sisudoc-spine project-heading
+
+# 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
+
+## build sisudoc-spine
+
+## directly with dub
+### ldc2
- dub --compiler=ldc2 -color --config=ldc -b release
+ dub --compiler=ldmd2 --config=ldmd2
+ dub --verbose --compiler=ldmd2 -color --config=ldmd2
- dub --compiler=dmd -color --config=dmd
+ dub --compiler=ldc2 --config=ldc2
+ dub --verbose --compiler=ldc2 -color --config=ldc2
- dub --compiler=gdc-10 -color --config=gdc -b release
+### 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/.
-# Configuration
-
-Configuration files are yaml files
-
-The following paths are searched:
-
- ~/.dr/config_local_site
- ~/path_to_pod_root/.dr/config_local_site
-
-e.g. processing
-
- ~spineMarkupSamples/pod/*
-
-will search:
-
- ~spineMarkupSamples/pod/.dr/config_local_site
-
- ~/.dr/config_local_site
-
-to specify an alternative configuration file to use on the command line (in this
-example named "my_config"):
-
- spine -v --html --config=~spineMarkupSamples/pod/.dr/my_config
-
-here is a sample configuration file:
-
-flag:
- act0: "--html"
- act1: "--html --epub"
-output:
- path: "/var/www/html"
-default:
- language: "en"
- papersize: "a4"
- text_wrap: "80"
- digest: "sha256"
-webserv:
- http: "http"
- host: "localhost"
- data_http: "http"
- data_host: "localhost"
- data_root_url: "http://localhost"
- data_root_path: "/var/www/html"
- data_root_part: ""
- images_root_part: "image"
- cgi_search_form_title: "≅ SiSU Spine search ፨"
- cgi_http: "http"
- cgi_host: "localhost"
- cgi_bin_url: "http://localhost/cgi-bin"
- cgi_bin_subpath: "/cgi-bin"
- cgi_bin_path: "/usr/lib/cgi-bin"
- cgi_search_script: "spine-search"
- cgi_search_script_raw_fn_d: "spine_search.d"
- cgi_port: ""
- cgi_user: ""
- cgi_action: "http://localhost/cgi-bin/spine-search"
- db_sqlite: "spine.search.db"
- db_pg_table: ""
- db_pg_user: ""
-
-# Commands
+# Document processing examples
+
+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
-for a list of commands from the program type:
+### html with links to search form
- spine -h
+${SpineBIN} -v --epub --html --html-link-curate --curate --output=${SpineOUT} ${SpinePOD}/*
-at the time of writing this provides the following output:
+${SpineBIN} -v --source --pod --latex --latex-init --epub --html --html-link-pdf --html-link-curate --html-link-markup --curate --output=${SpineOUT} ${SpinePOD}/*
- --abstraction document abstraction
- --assert set optional assertions on
- --cgi-search-form-codegen generates (pre-compiled) d code for search of specified db
- --cgi-sqlite-search-filename =[filename]
- --concordance file for document
- --config =/path/to/config/file/including/filename
- --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
- --hide-ocn object cite numbers
- --html process html output
- --html-link-curate place links back to curate in segmented html
- --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-color-links mono or color links for pdfs
- --light default light theme
- --manifest process manifest output
- --ocn-off object cite numbers
- --odf open document format text (--odt)
- --odt open document format text
- --output =/path/to/output/dir specify where to place output
- --parallel parallelisation
- --parallel-subprocesses nested parallelisation
- --pdf latex output for pdfs
- --pdf-color-links mono or color links for pdfs
- --pod spine (doc reform) pod source content bundled
--q --quiet output to terminal
- --section-backmatter document backmatter (default)
- --section-biblio document biblio (default)
- --section-blurb document blurb (default)
- --section-body document body (default)
- --section-bookindex document bookindex (default)
- --section-endnotes document endnotes (default)
- --section-glossary document glossary (default)
- --section-toc table of contents (default)
- --serial serial processing
- --skip-output skip output
- --show-config show config
- --show-make show make
- --show-metadata show metadata
- --show-summary show summary
- --source document markup source
- --sqlite-discrete process discrete sqlite output
- --sqlite-db-create create db, create tables
- --sqlite-db-drop drop tables & db
- --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
- --text text output
- --theme-dark alternative dark theme
- --theme-light default light theme
- --txt text output
--v --verbose output to terminal
- --very-verbose output to terminal
- --workon (reserved for some matters under development & testing)
- --xhtml xhtml output
--h --help This help information.
+${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}/*
-# Examples
+spine -v --html \
+ --html-link-search \
+ --output=`echo ~webDocRoot` \
+ ${SpinePOD}/*
## curate
@@ -215,7 +176,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
@@ -310,6 +271,9 @@ cgi-bin directory
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}/*
+
+
### create db & search form
spine -v \
@@ -318,9 +282,117 @@ cgi-bin directory
--output=/var/www/html \
~spineMarkupSamples/pod/*
-### html with links to search form
+# Commands
- spine -v --html \
- --html-link-search \
- --output=`echo ~webDocRoot` \
- ~spineMarkupSamples/pod/*
+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-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
+ --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
+ --digest hash digest for each object
+ --epub process epub output
+ --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-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 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
+ --odf open document format text (--odt)
+ --odt open document format text
+ --output =/path/to/output/dir specify where to place output
+ --parallel parallelisation
+ --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)
+ --section-biblio document biblio (default)
+ --section-blurb document blurb (default)
+ --section-body document body (default)
+ --section-bookindex document bookindex (default)
+ --section-endnotes document endnotes (default)
+ --section-glossary document glossary (default)
+ --section-toc table of contents (default)
+ --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-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
+ --txt text output
+-v --verbose output to terminal
+ --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.
diff --git a/derivation.nix b/derivation.nix
index e8789f0..2ed8b4e 100644
--- a/derivation.nix
+++ b/derivation.nix
@@ -48,7 +48,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 "")
diff --git a/dub.json b/dub.json
index 01a6fbc..349a619 100644
--- a/dub.json
+++ b/dub.json
@@ -10,32 +10,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/flake.lock b/flake.lock
index bbaeebe..10002d2 100644
--- a/flake.lock
+++ b/flake.lock
@@ -20,11 +20,11 @@
},
"nixpkgs": {
"locked": {
- "lastModified": 1714562304,
- "narHash": "sha256-Mr3U37Rh6tH0FbaDFu0aZDwk9mPAe7ASaqDOGgLqqLU=",
+ "lastModified": 1714912032,
+ "narHash": "sha256-clkcOIkg8G4xuJh+1onLG4HPMpbtzdLv4rHxFzgsH9c=",
"owner": "NixOS",
"repo": "nixpkgs",
- "rev": "bcd44e224fd68ce7d269b4f44d24c2220fd821e7",
+ "rev": "ee4a6e0f566fe5ec79968c57a9c2c3c25f2cf41d",
"type": "github"
},
"original": {
diff --git a/flake.nix b/flake.nix
index 8ce9b66..495e86c 100644
--- a/flake.nix
+++ b/flake.nix
@@ -49,7 +49,7 @@
pkgs-ovl = pkgsForSystem system;
pkgs-nix = nixpkgsFor.${system};
in
- with pkgs-ovl; {
+ with pkgs-nix; {
default = stdenv.mkDerivation {
inherit pname;
inherit version;
@@ -88,8 +88,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"
@@ -112,10 +112,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
@@ -134,8 +134,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"
@@ -157,11 +157,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
@@ -180,8 +180,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
@@ -204,16 +204,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
@@ -226,7 +225,7 @@
name = "spine base dev shell";
inherit shell;
inherit devEnv;
- packages = with pkgs-nix; [
+ packages = [
dmd
dub
gnumake
@@ -238,7 +237,7 @@
name = "spine base dev shell";
inherit shell;
inherit devEnv;
- packages = with pkgs-nix; [
+ packages = [
ldc
dub
gnumake
@@ -250,7 +249,7 @@
name = "spine base dev shell";
inherit shell;
inherit devEnv;
- packages = [
+ packages = with pkgs-ovl; [
dmd
dub
gnumake
@@ -262,7 +261,7 @@
name = "spine base dev shell";
inherit shell;
inherit devEnv;
- packages = [
+ packages = with pkgs-ovl; [
ldc
dub
gnumake
diff --git a/makefile b/makefile
index 3573b4c..59651de 100644
--- a/makefile
+++ b/makefile
@@ -77,7 +77,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'; \
@@ -113,7 +113,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:
@@ -572,7 +571,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
@@ -612,22 +611,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_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: