aboutsummaryrefslogtreecommitdiffhomepage
path: root/README
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 /README
parentadd a few non-pod markup samples (diff)
READMEs & general copyright file
Diffstat (limited to 'README')
-rw-r--r--README138
1 files changed, 138 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..ce88f31
--- /dev/null
+++ b/README
@@ -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