path: root/org/spine_info.org

-*- 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 contents
**** org contents tangle

#+HEADER: :tangle "../README"
#+HEADER: :noweb yes
#+BEGIN_SRC text
<<sisudoc_spine_README_header_org>>

<<sisudoc_spine_README_project_header_info>>

,* Summary

<<sisudoc_spine_README_summary>>

,* Installation, Compilation

<<sisudoc_spine_README_install_summary>>

,*** build using nix flakes on linux (binary in ./result/bin)

<<sisudoc_spine_README_install_build_using_nix_flakes>>

,* sisudoc-spine pod structure

<<sisudoc_spine_pod_dir_structure>>

,* Document processing examples

<<sisudoc_spine_README_commands>>
#+END_SRC

**** org header

#+NAME: sisudoc_spine_README_header_org
#+BEGIN_SRC org
-*- 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 contents tangle

#+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>>

### build using nix flakes on linux (binary in ./result/bin)

<<sisudoc_spine_README_install_build_using_nix_flakes>>

# sisudoc-spine pod structure

<<sisudoc_spine_pod_dir_structure>>

# Document processing examples

<<sisudoc_spine_README_commands>>
#+END_SRC

** project yaml 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

** sample pod directory

#+NAME: sisudoc_spine_pod_dir_structure
#+BEGIN_SRC  man
pod (directory may contain multiple documents)
 └── the_wealth_of_networks.yochai_benkler
     ├── conf
     │   └── sisu_document_make
     ├── media
     │   ├── image
     │   │   ├── won_benkler_2_1.png
     │   │   ├── won_benkler_6_1.png
     │   │   ├── won_benkler_7_1.png
     │   │   ├── won_benkler_7_2.png
     │   │   ├── won_benkler_7_3a.png
     │   │   ├── won_benkler_7_3b.png
     │   │   ├── won_benkler_7_4.png
     │   │   ├── won_benkler_7_5.png
     │   │   ├── won_benkler_7_6.png
     │   │   └── won_benkler_9_1.png
     │   └── text
     │       └── en
     │           └── the_wealth_of_networks.yochai_benkler.sst
     └── pod.manifest
#+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 --depth=1 git://git.sisudoc.org/software/sisudoc-spine && \
  git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine-search-cgi && \
  git clone --depth=1 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
#+END_SRC

**** install build project using nix flakes

#+NAME: sisudoc_spine_README_install_build_using_nix_flakes
#+BEGIN_SRC text

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 under current discusson 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

*** org files ./org

- .org literate programming:
  - copyright asserted
  - omitted
    - license
    - dependency information

#+HEADER: :tangle "../org/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