add SETUP file

1 files changed, 68 insertions, 0 deletions

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