From 36a89758161478e2f0c8f2bea4c51db456672efa Mon Sep 17 00:00:00 2001
From: Jonas Smedegaard <dr@jones.dk>
Date: Fri, 19 Jun 2020 13:46:04 +0200
Subject: add SETUP file

---
 SETUP.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 SETUP.md

(limited to 'SETUP.md')

diff --git a/SETUP.md b/SETUP.md
new file mode 100644
index 0000000..53d419c
--- /dev/null
+++ b/SETUP.md
@@ -0,0 +1,68 @@
+# Setting up feature documentation
+
+> Setup feature documentation for reading, editing, or publishing
+
+This documents setting up the feature documentation system,
+either for reading or editing the source files,
+or for generating a website
+e.g. for public display.
+
+
+## Prerequisites
+
+To edit documentation files,
+you only need some plain-text editor
+(e.g. `nano`, `vim`, `emacs`, or `mcedit`),
+and `git` to syncronize your changes with others:
+
+    sudo apt install git
+
+To generate a website from the collection of source files,
+you additionally need `Make` and `MKDocs`
+(but you don't need `LESS` which gets included by default,
+so can suppress installing that):
+
+    sudo apt install make mkdocs less-
+
+(if you use LESS elsewhere on your system,
+then skip the `less-` part of above command).
+
+
+## Fetch features
+
+The documentation is grouped by "feature",
+each tracked in a separate git.
+All features are pulled together in the git "features"
+using this command:
+
+    make init
+
+You can repeat the command later,
+e.g. after updating the "features" git
+where additional features added.
+
+Simple re-init may fail, however
+(e.g. after a git update _removing_ some features).
+More reliable is to do a [cleanup|#Cleanup]
+and then a fresh init.
+
+
+## Build website
+
+This command generates a website from the feature texts:
+
+    make
+
+
+## Cleanup
+
+All fetched and generated files can be removed
+with this command:
+
+    make distclean
+
+Alternatively
+(e.g. when needing to clean while offline),
+this command removed only generated files:
+
+    make clean
-- 
cgit v1.2.3