aboutsummaryrefslogtreecommitdiffhomepage
path: root/org/spine_info.org
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2024-05-13 18:19:38 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2024-05-13 18:51:53 -0400
commitf38130e8d8a4a34e3eb29da06ac76edbc686f761 (patch)
tree1879950724bb84b98f911eaa01616f43d5f30610 /org/spine_info.org
parentadd a few non-pod markup samples (diff)
READMEs & general copyright file
Diffstat (limited to 'org/spine_info.org')
-rw-r--r--org/spine_info.org343
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