diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 325 |
1 files changed, 0 insertions, 325 deletions
@@ -1,325 +0,0 @@ -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 - 2020 Ralph Amissah, All Rights Reserved." - - license: "AGPL 3 or later" - - hompage: [ - "http://www.doc_reform.org", - "http://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" - domain: "localhost" - data_http: "http" - data_domain: "localhost" - data_root_url: "http://localhost" - data_root_path: "/var/www/html" - data_root_part: "" - images_root_part: "image" - cgi_title: "≅ SiSU Spine search" - cgi_http: "http" - cgi_domain: "localhost" - cgi_bin_url: "http://localhost/cgi-bin" - cgi_bin_part: "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 - --harvest extract info on authors & topics from document header metadata - --harvest-authors extract info on authors from document header metadata - --harvest-topics extract info on topics from document header metadata - --hide-ocn object cite numbers - --html process html output - --html-link-harvest place links back to harvest 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 - -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-harvest --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* - - spine -v --html --html-link-search --html-link-harvest --epub --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* - - spine -v --html --epub --latex --odt --harvest --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* - -## harvest - -if you have a document collection with documents that have metadata headers a -summary of the collection can be made using the harvest command - - spine -v --harvest --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* - - spine -v --harvest ~spineMarkupSamples/pod/* - - spine -v --html --html-link-search --html-link-harvest --harvest --output=`echo ~webDocRoot` ~spineMarkupSamples/pod/* - - spine -v --html --html-link-search --html-link-harvest --harvest ~spineMarkupSamples/pod/* - -## sqlite - -### 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-harvest --harvest --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/* |