READMEs & general copyright file

1 files changed, 138 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..ce88f31
--- /dev/null
+++ b/README
@@ -0,0 +1,138 @@
+-*- mode: org -*-
+#+TITLE:       spine (sisudoc) (project) README
+#+DESCRIPTION: README for spine
+#+FILETAGS:    :spine:build:tools:
+#+AUTHOR:      Ralph Amissah
+#+EMAIL:       [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]]
+#+COPYRIGHT:   Copyright (C) 2015 - 2024 Ralph Amissah
+#+LANGUAGE:    en
+#+STARTUP:     content hideblocks hidestars noindent entitiespretty
+#+OPTIONS:     H:3 num:nil toc:t \n:nil @:t ::t |:t ^:nil _:nil -:t f:t *:t <:t
+#+PROPERTY:    header-args  :exports code
+#+PROPERTY:    header-args+ :noweb yes
+#+PROPERTY:    header-args+ :eval no
+#+PROPERTY:    header-args+ :results no
+#+PROPERTY:    header-args+ :cache no
+#+PROPERTY:    header-args+ :padline no
+
+project_name: "sisudoc spine (doc reform) markup samples"
+
+description:
+  - "markup samples for the project sisudoc spine"
+  - "sisu markup"
+  - "search"
+  - "object numbering"
+  - "static content generator"
+
+author:
+  name:  "Ralph Amissah"
+  email: ralph.amissah@gmail.com
+
+copyright: "(C) 2015 - 2024 Ralph Amissah, All Rights Reserved."
+
+license:
+  - "markup samples substantive content: as granted by original authors & publishers (as indicated in each document)"
+  - "project code: AGPL 3 or later"
+
+homepage:
+  - "https://sisudoc.org"
+  - "https://doc-reform.org"
+
+git:
+  - "https://git.sisudoc.org"
+
+* Summary
+
+These are document markup samples for the program sisudoc-spine prepared in the
+markup language sisu. The markup of document headers for sisudoc-spine now use
+yaml (instead of bespoke sisu markup headers) and sisudoc-spine documents are
+(optionally) presented in a preferred directory structure that is absent in
+sisu.
+
+Sample files are provided under the directory: ./markup/
+
+A few document samples without the formal directory structure are provided in:
+
+./markup/non-pod-samples/
+
+This is the easiest way to start preparation of a document, in a file with a
+.sst extension, marked up in sisu. Any images belonging to documents going in a
+sub-directory called image. sisudoc-spine can be run against the prepared .sst
+file.
+
+sisudoc-spine organizes document source into pods (sisupods). Document samples
+using the directory structure for sisudoc-spine are located under: ./markup/pod/
+(this includes a number of prepared books and articles).
+
+individual .sst files with their associated images are automatically converted
+to sisupods if the source is to be shared or bundled with the commands:
+
+spine --source [.sst document name]
+# or bundled with:
+spine --pod [.sst document name]
+
+or
+
+spine --source --pod [.sst document name]
+
+* Installation, Compilation
+
+These are document markup samples for the program sisudoc-spine and as such
+there is no installation that needs to be done. You may use the examples to
+understand how you might markup your own documents. To produce output, you would
+run the program sisudoc-spine against the markup sample using a command line
+instruction. The sources of relevant parts of the project are here:
+
+  https://sisudoc.org
+  https://git.sisudoc.org
+
+  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
+
+you may wish to clone these into a directory created for the purpose, e.g.
+
+  mkdir ~/git.sisudoc
+  cd ~/git.sisudoc
+
+and then git clone sisudoc-spine-samples
+
+sisudoc-spine-samples provides markup samples for sisudoc-spine to use
+sisudoc-spine to generate document output see the README in that directory.
+
+  cd sisudoc-spine-samples
+
+If you happen to be using Nix or NixOS (x86_64-linux so far), you can install
+sisudoc-spine from the flake.nix file provided in this (sisudoc-spine-samples)
+directory tree, without first cloning sisudoc-spine (the flake will fetch and
+build from online source).
+
+NOTE all actions to build sisudoc-spine are taken within the directory
+sisudoc-spine-samples
+
+choose one of the following nix flake runes to build sisudoc-spine (here in the
+sisudoc-spine-samples directory tree):
+
+  nix build ".#spine-overlay-ldc" --print-build-logs
+
+  nix build ".#spine-overlay-dmd" --print-build-logs
+
+the result which can be used to generate content should be available in:
+
+  ./result/bin/spine
+
+What you do with these is run sisudoc-spine (now available loocally) against the
+document source to get the desired output.
+
+* Document processing examples
+
+e.g.:
+
+  ./result/bin/spine -v --source --pod --epub --html --html-link-curate --html-link-markup --curate --output=./OUTPUT_TEST_sisudocSpine ./markup/pod/*
+
+with sisudoc-spine installed, for a list of commands from the program type:
+
+  spine -h
+
+or see the README in sisudoc-spine for more information and examples of command
+flags and configuration options