aboutsummaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2020-10-16 19:16:18 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2020-10-19 13:26:15 -0400
commit0c693b23c4ff8f98a151884a24f150a5ff746dd4 (patch)
treef638d7942cab5b20adc3761ad7fcb62283eeefd8 /README.md
parentcgi.d arsd update (diff)
org mode, unique code-block names & adjust headers
- avoid org-mode undefined behavior, provide unique code-block names
Diffstat (limited to 'README.md')
-rw-r--r--README.md326
1 files changed, 326 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ac35e9f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,326 @@
+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/*