Merge development from couchdesign branch

5 files changed, 123 insertions, 16 deletions

diff --git a/.mrconfig b/.mrconfig
index 8705018..724a793 100644
--- a/.mrconfig
+++ b/.mrconfig
@@ -1,21 +1,30 @@
 
 [source/account]
-checkout = git clone 'https://source.virtual-assembly.org/feature/account.git' 'account'
+checkout = git clone 'git://source.virtual-assembly.org/feature/account.git' 'account'
+
+[source/account-secure]
+checkout = git clone 'git://source.redpill.dk/account-secure.git' 'account-secure'
 
 [source/account-shell]
-checkout = git clone 'https://source.virtual-assembly.org/feature/account-shell.git' 'account-shell'
+checkout = git clone 'git://source.virtual-assembly.org/feature/account-shell.git' 'account-shell'
+
+[source/accounting]
+checkout = git clone 'git://source.couchdesign.dk/accounting.git' 'accounting'
 
 [source/chat]
-checkout = git clone 'https://source.virtual-assembly.org/feature/chat.git' 'chat'
+checkout = git clone 'git://source.virtual-assembly.org/feature/chat.git' 'chat'
 
 [source/source]
-checkout = git clone 'https://source.redpill.dk/source.git' 'source'
+checkout = git clone 'git://source.redpill.dk/source.git' 'source'
 
 [source/system]
-checkout = git clone 'https://source.redpill.dk/system.git' 'system'
+checkout = git clone 'git://source.redpill.dk/system.git' 'system'
+
+[source/system-desktop]
+checkout = git clone 'git://source.couchdesign.dk/system-desktop.git' 'system-desktop'
 
 [source/system-gateway]
-checkout = git clone 'https://source.redpill.dk/system-gateway.git' 'system-gateway'
+checkout = git clone 'git://source.redpill.dk/system-gateway.git' 'system-gateway'
 
 [source/about]
-checkout = git clone 'https://source.couchdesign.dk/org.git' 'about'
+checkout = git clone 'git://source.couchdesign.dk/org.git' 'about'
diff --git a/Makefile b/Makefile
index cd21f72..a6839fc 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-# Depends: myrepos git mkdocs linkchecker libtext-hogan-perl
+# Depends: myrepos git mkdocs w3c-linkchecker libtext-hogan-perl
 
 domain ?= example.org
 shellhost ?= shell.$(domain)
@@ -20,13 +20,16 @@ all: doc
 
 doc: docs $(patsubst %,docs/%,$(subst -,/,$(notdir $(wildcard source/*))))
 	mkdocs build
-	linkchecker site/index.html
 
+check:
+	checklink site/index.html
+
+# TODO: drop symlink removal when 2020-06-19 is well in the past
 docs:
 	mkdir -p docs
-	ln -sf ../README.md docs/index.md
-#	ln -sf ../USE.md    docs/use.md
-#	ln -sf ../ADMIN.md  docs/admin.md
+	find docs -type l -delete
+	$(MUSTACHE) < README.md > docs/index.md
+	$(MUSTACHE) < SETUP.md > docs/setup.md
 
 docs/%: source
 	mkdir -p docs/$*
@@ -50,4 +53,4 @@ clean:
 distclean: clean
 	rm -rf source
 
-.PHONY: all doc clean distclean
+.PHONY: all doc check clean distclean
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
diff --git a/TODO b/TODO
index a954a9f..0dc895e 100644
--- a/TODO
+++ b/TODO
@@ -1,2 +1,8 @@
   * Fail build if output html contains square brackets.
   * Implement po4a internationalisation and localization routines.
+  * define taxonomies
+    + fields (of interest)
+    + domains (of access control)
+    + state (of maturity/maintenance)
+  * define relationships
+    + doap-deps
diff --git a/mkdocs.yml b/mkdocs.yml
index 2436a8e..baf9b19 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,29 +1,43 @@
 site_name: System features
 repo_url: https://source.couchdesign.dk/features.git/
+markdown_extensions:
+    - toc:
+        permalink: '§'
+    - codehilite:
+        guess_lang: False
 nav:
 - Introductions:
     - Account: 'account/index.md'
     - 'Account shell': 'account/shell/index.md'
+    - 'Account security': 'account/secure/index.md'
+    - Accounting: 'accounting/index.md'
     - Chat: 'chat/index.md'
     - System: 'system/index.md'
+    - 'System desktop': 'system/desktop/index.md'
     - 'System gateway': 'system/gateway/index.md'
     - Source: 'source/index.md'
 - Use:
 #    - Introduction: 'use.md'
 #    - Account: 'account/use.md'
     - 'Account shell': 'account/shell/use.md'
+    - 'Account security': 'account/secure/use.md'
+    - Accounting: 'accounting/use.md'
     - Chat: 'chat/use.md'
     - Source: 'source/use.md'
 - Administration:
 #    - Introduction: 'admin.md'
     - Account: 'account/admin.md'
     - 'Account shell': 'account/shell/admin.md'
+    - 'Account security setup': 'account/secure/setup.md'
 #    - Chat: 'chat/admin.md'
+    - 'System desktop setup': 'system/desktop/setup.md'
     - 'System gateway setup': 'system/gateway/setup.md'
 - Development:
 #    - Introduction: 'devel.md'
     - System: 'system/devel.md'
 - About:
-    - Structure: 'about/index.md'
-    - 'Technical setup': 'about/setup.md'
-    - 'Maintenance': 'about/admin.md'
+    - Website: 'index.md'
+    - 'Website setup': 'setup.md'
+    - 'Source structure': 'about/index.md'
+    - 'Source setup': 'about/setup.md'
+    - 'Source maintenance': 'about/admin.md'