diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 138 |
1 files changed, 138 insertions, 0 deletions
@@ -0,0 +1,138 @@ +-*- 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 + +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" + +* Summary + +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] + +* Installation, Compilation + +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. + +* Document processing examples + +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 |