Merge development from couchdesign branch

1 files changed, 75 insertions, 0 deletions

diff --git a/SETUP.md b/SETUP.md
new file mode 100644
index 0000000..cd1492e
--- /dev/null
+++ b/SETUP.md
@@ -0,0 +1,75 @@
+# 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
+
+For reading or editing documentation files,
+you only need some plain-text editor
+(e.g. `nano`, `vim`, `emacs`, or `mcedit`),
+and `git` and `myrepos` to syncronize your changes with others:
+
+    sudo apt install git myrepos
+
+For generating website from the collection of source files,
+you additionally need `MKDocs` and some helper tools:
+
+    sudo apt install make w3c-linkchecker libtext-hogan-perl mkdocs
+
+For checking quality of generated website,
+you need an extra helper tool:
+
+    sudo apt install w3c-linkchecker
+
+
+## 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
+
+
+## Check website
+
+This command checks generated website for flaws in links:
+
+    make check
+
+
+## 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