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.

# sisudoc-spine pod structure

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

# 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