diff options
Diffstat (limited to 'org/spine_info.org')
| -rw-r--r-- | org/spine_info.org | 343 |
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 |