READMEs & general copyright file

1 files changed, 343 insertions, 0 deletions

diff --git a/org/spine_info.org b/org/spine_info.org
new file mode 100644
index 0000000..769b31e
--- /dev/null
+++ b/org/spine_info.org
@@ -0,0 +1,343 @@
+-*- mode: org -*-
+#+TITLE:       sisudoc spine (doc_reform) information files
+#+DESCRIPTION: documents - structuring, various output representations & search
+#+FILETAGS:    :spine:info:
+#+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
+#+PROPERTY:    header-args  :exports code
+#+PROPERTY:    header-args+ :noweb yes
+#+PROPERTY:    header-args+ :results no
+#+PROPERTY:    header-args+ :cache no
+#+PROPERTY:    header-args+ :padline no
+#+PROPERTY:    header-args+ :mkdirp yes
+#+OPTIONS:     H:3 num:nil toc:t \n:t ::t |:t ^:nil -:t f:t *:t
+
+- [[./doc-reform.org][doc-reform.org]]  [[./][org/]]
+- [[./spine_build_scaffold.org][spine_build_scaffold.org]]
+
+* README :readme:
+** tangle
+*** org
+**** org text
+
+#+HEADER: :tangle "../README"
+#+HEADER: :noweb yes
+#+BEGIN_SRC text
+<<sisudoc_spine_readme_org_header_org>>
+
+<<sisudoc_spine_readme_project_header_info>>
+
+,* Summary
+
+<<sisudoc_spine_readme_summary>>
+
+,* Installation, Compilation
+
+<<sisudoc_spine_readme_install_summary>>
+
+,* Document processing examples
+
+<<sisudoc_spine_readme_commands>>
+#+END_SRC
+
+**** org header
+
+#+NAME: sisudoc_spine_readme_org_header_org
+#+BEGIN_SRC text
+-*- 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
+#+END_SRC
+
+*** md
+
+#+HEADER: :tangle "../README.md"
+#+HEADER: :noweb yes
+#+BEGIN_SRC markdown
+<<sisudoc_spine_readme_project_header_info>>
+
+# Summary
+
+<<sisudoc_spine_readme_summary>>
+
+# Installation, Compilation
+
+<<sisudoc_spine_readme_install_summary>>
+
+# Document processing examples
+
+<<sisudoc_spine_readme_commands>>
+#+END_SRC
+
+** project header
+
+#+NAME: sisudoc_spine_readme_project_header_info
+#+BEGIN_SRC yaml
+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"
+#+END_SRC
+
+** summary - short description
+
+#+NAME: sisudoc_spine_readme_summary
+#+BEGIN_SRC text
+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]
+#+END_SRC
+
+** installation
+
+#+NAME: sisudoc_spine_readme_install_summary
+#+BEGIN_SRC markdown
+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.
+#+END_SRC
+
+** commands help
+
+#+NAME: sisudoc_spine_readme_commands
+#+BEGIN_SRC markdown
+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
+#+END_SRC
+
+* COPYRIGHT & LICENSE
+** notices
+*** project (project root) ./
+
+#+HEADER: :tangle "../COPYRIGHT"
+#+HEADER: :noweb yes
+#+BEGIN_SRC text
+<<sisudoc_spine_samples_rights>>
+#+END_SRC
+
+*** code org ./org
+
+#+HEADER: :tangle "../org/COPYRIGHT"
+#+HEADER: :noweb yes
+#+BEGIN_SRC text
+<<sisudoc_spine_samples_rights>>
+#+END_SRC
+
+*** org files ./org
+
+- .org literate programming:
+  - copyright asserted
+  - omitted
+    - license
+    - dependency information
+
+#+HEADER: :tangle "./COPYRIGHT"
+#+HEADER: :noweb yes
+#+BEGIN_SRC text
+<<sisudoc_spine_samples_rights>>
+#+END_SRC
+
+*** doc (markup samples) ./doc
+
+#+HEADER: :NO-tangle "../doc/COPYRIGHT"
+#+HEADER: :noweb yes
+#+BEGIN_SRC text
+<<data>>
+#+END_SRC
+
+** incorporate
+*** copyright
+
+#+NAME: sisudoc_spine_samples_rights
+#+HEADER: :noweb yes
+#+BEGIN_SRC text
+- Name: spine - SiSU Spine, Doc Reform
+  <<sisudoc_spine_copyright>>
+
+  <<sisudoc_spine_document_samples_licenses>>
+
+  <<sisudoc_spine_summary>>
+
+<<sisudoc_spine_markup_samples>>
+#+END_SRC
+
+#+NAME: sisudoc_spine_copyright
+#+BEGIN_SRC text
+- Description: documents, structuring, processing, publishing, search
+  - static content generator
+
+- Author: Ralph Amissah
+  [ralph.amissah@gmail.com]
+
+- Copyright: (C) 2015 - 2024 Ralph Amissah
+#+END_SRC
+
+*** license
+**** Document Markup Samples
+
+#+NAME: sisudoc_spine_document_samples_licenses
+#+BEGIN_SRC text
+- code under markup/* as granted by original authors & publishers (as indicated
+  in each document)
+
+Markup samples are works that have the indivicual licenses as granted by the
+authors and/or original publishers of the works, that are indicated in each
+document under in the license section of the document header metadata.
+#+END_SRC
+
+*** spine_summary
+
+#+NAME: sisudoc_spine_summary
+#+BEGIN_SRC text
+- Spine, Doc Reform (related to SiSU) uses standard:
+  - docReform markup syntax (based on SiSU markup)
+    - standard SiSU markup syntax with modified headers and minor
+      modifications
+  - docReform object numbering (based on SiSU object citation numbering)
+    - standard SiSU document object numbering
+
+- Homepages:
+  [https://sisudoc.org]
+
+- Git
+  [https://git.sisudoc.org]
+#+END_SRC
+
+*** markup_samples
+
+#+NAME: sisudoc_spine_markup_samples
+#+BEGIN_SRC text
+- Spine, Doc Reform (SiSU) markup samples
+  Individual document content Copyright (Author) [as stated in document header]
+  Individual document content License (Author) [as stated in document header]
+#+END_SRC
+
+* CHANGELOG :changelog:
+
+#+BEGIN_SRC sh
+CHL="CHANGELOG"
+git log --pretty=format:'-_-%+s %+as %ae%+h%d%+b' --no-merges \
+  | sed "/^\\s*$/d" | sed "s/^\([ ]\)*\*/\1-/" | sed "s/ \+$//" | sed "s/^-_-$//" \
+  > ${CHL}
+#+END_SRC
+
+#+BEGIN_SRC sh
+git log --pretty=format:"-_-_%+s %+as %ae%+h%d%+b" --no-merges \
+  > ${CHL} && sed -i '/^$/d; s/^\([ ]\)*\*/\1-/; s/ \+$//; s/^-_-_//' ${CHL}
+#+END_SRC