-*- 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 <> <> ,* Summary <> ,* Installation, Compilation <> ,*** build using nix flakes on linux (binary in ./result/bin) <> ,* sisudoc-spine pod structure <> ,* Document processing examples <> #+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 <> # Summary <> # Installation, Compilation <> ### build using nix flakes on linux (binary in ./result/bin) <> # sisudoc-spine pod structure <> # Document processing examples <> #+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 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 #+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 <> #+END_SRC *** code org ./org #+HEADER: :tangle "../org/COPYRIGHT" #+HEADER: :noweb yes #+BEGIN_SRC text <> #+END_SRC *** org files ./org - .org literate programming: - copyright asserted - omitted - license - dependency information #+HEADER: :tangle "./COPYRIGHT" #+HEADER: :noweb yes #+BEGIN_SRC text <> #+END_SRC *** doc (markup samples) ./doc #+HEADER: :NO-tangle "../doc/COPYRIGHT" #+HEADER: :noweb yes #+BEGIN_SRC text <> #+END_SRC ** incorporate *** copyright #+NAME: sisudoc_spine_samples_rights #+HEADER: :noweb yes #+BEGIN_SRC text - Name: spine - SiSU Spine, Doc Reform <> <> <> <> #+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