project_name: Spine, Doc Reform description: [ "documents, structuring, processing, publishing", search, object numbering, static content generator, sisu markup ] author: name: Ralph Amissah email: ralph.amissah@gmail.com copyright: "(C) 2015 - 2023 Ralph Amissah, All Rights Reserved." license: "AGPL 3 or later" homepage: [ "https://www.doc_reform.org", "https://www.sisudoc.org" ] # Installation, Compilation SiSU spine is written in the programming language D for which there are 3 compilers: - dmd - ldc - gdc 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 dub --compiler=ldc2 -color --config=ldc -b release dub --compiler=dmd -color --config=dmd dub --compiler=gdc-10 -color --config=gdc -b release make ldc make dmd there has been some coalescence around the Meson build system 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 for a list of commands from the program type: spine -h at the time of writing this provides the following output: --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. # Examples ## curate if you have a document collection with documents that have metadata headers a summary of the collection can be made using the curate command spine -v --curate --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* spine -v --curate ~spineMarkupSamples/pod/* spine -v --html --html-link-search --html-link-curate --curate --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* spine -v --html --html-link-search --html-link-curate --curate ~spineMarkupSamples/pod/* ## sqlite if configuartion has been set specify just - the desired output and - the markup document/pod(s) to process spine -v --html ~spineMarkupSamples/markup/pod/sisu-manual if configuartion has not been set or to overide the set configration specify - the output path as well as - the desired output and - the markup document/pod(s) to process note: ~webDocRoot should be the path to web doc root, provide a suitable output path. spine -v --html --html-link-search --html-link-curate --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* spine -v --html --html-link-search --html-link-curate --epub --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* spine -v --html --epub --latex --odt --curate --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* ### create db if there is no sqlite db you first need to create one, to do so - the name of the db and - the root path for document output must be specified: spine -v \ --sqlite-db-create --sqlite-db-filename="spine.search.db" \ --output=/var/www/html \ ~spineMarkupSamples/pod/* spine -v --sqlite-db-create --sqlite-db-filename="spine.search.db" --output=`echo ~webDocRoot` if you have a configration file providing this information that is to be used for a document collection you can point to the document collection: spine -v --sqlite-db-create ~spineMarkupSamples/pod ### populate db must specify: - the name of the db and - the root path for document output spine -v --sqlite-update \ --sqlite-db-filename="spine.search.db" \ --output=/var/www/html \ ~spineMarkupSamples/pod/* spine -v --sqlite-update --sqlite-db-filename="spine.search.db" --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* if you have a configration file providing this information that is to be used for a document collection you can point to the document collection: spine -v --sqlite-update ~spineMarkupSamples/pod/* ### generate a cgi search form in d spine -v --cgi-search-form-codegen \ --output=/var/www/html \ ~spineMarkupSamples/pod spine -v --cgi-search-form-codegen --config=~spineMarkupSamples/pod spine -v --cgi-search-form-codegen --config=~spineMarkupSamples/pod/.dr/config_local_site spine --cgi-search-form-codegen --output=`echo ~webDocRoot` ~spineMarkupSamples/pod spine --cgi-search-form-codegen --cgi-sqlite-search-filename="spine_search" --output=`echo ~webDocRoot` spine -v --cgi-search-form-codegen \ --sqlite-db-filename="spine.search.db" \ --cgi-sqlite-search-filename="spine-search" \ --output=/var/www/html \ ~spineMarkupSamples/pod #### compile the cgi search form cd /var/www/html/cgi # /var/www/html (default document root) cd ~webDocRoot/cgi the directory ~webDocRoot/cgi/src should contain two files - spine_search.d (or whatever you named it) - cgi.d (by Adam Rupee) dub --force --compiler=ldc2 && sudo cp -v cgi-bin/spine-search /usr/lib/cgi-bin/. should compile spine-search in ~webDocRoot/cgi/cgi-bin and copy it to the cgi-bin directory spine -v --sqlite-db-create --sqlite-db-filename="spine.search.db" --cgi-sqlite-search-filename="spine-search" --output=`echo ~webDocRoot` spine -v --sqlite-db-create ~spineMarkupSamples/pod spine -v --html --html-link-search --cgi-sqlite-search-filename="spine-search" --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* 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/* ### create db & search form spine -v \ --sqlite-db-create --sqlite-db-filename="spine.search.db" \ --cgi-search-form-codegen --cgi-sqlite-search-filename="spine-search" \ --output=/var/www/html \ ~spineMarkupSamples/pod/* ### html with links to search form spine -v --html \ --html-link-search \ --output=`echo ~webDocRoot` \ ~spineMarkupSamples/pod/*