From ae6ddaf551882eabb1b801818db19687c1a30fe2 Mon Sep 17 00:00:00 2001
From: Jonas Smedegaard <dr@jones.dk>
Date: Fri, 20 Jan 2017 12:33:34 +0100
Subject: Extend to cover more details and routines.

---
 USE.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 89 insertions(+), 9 deletions(-)

diff --git a/USE.md b/USE.md
index bcb05ca..8225a1d 100644
--- a/USE.md
+++ b/USE.md
@@ -1,8 +1,22 @@
-# Ikiwiki build environment
+# Creating and editing a website
 
-## Minimal
+## Ikiwiki
 
-Minimal bootstrapping:
+Ikiwiki is web development tool,
+creating static content from markdown source.
+
+Content is maintained
+either by use of a git clone,
+or via a web interface.
+
+Styling is maintained
+by use of a git clone,
+
+
+### Minimal
+
+Quick bootstrap and test build,
+without git support for maintenance:
 
 	git clone git://source.jones.dk/ikiwiki
 	cd ikiwiki
@@ -11,16 +25,82 @@ Minimal bootstrapping:
 
 Result is then below build/ .
 
-## Git-tracked
+### Setup
+
+Fork base Ikiwiki framework,
+and pick a branch:
+
+  * master: closest to Debian-released Ikiwiki
+  * master-da: danish locale
+  * plaintext: templates adapted for plaintext plugin
+  * plaintext-da: plaintext adaptation + danish locale
+
+	git clone --origin ikiwiki git://source.jones.dk/ikiwiki example
+	cd example
+	git reset --hard ikiwiki/plaintitle-da
 
-Named website project as forked git,
-with content and styling separately tracked in git:
+Create separately tracked content and styling
+(or fork from existing projects, similar to above):
 
-	git clone git://source.jones.dk/ikiwiki mysite
-	cd mysite
 	git init content
 	git init styling
+
+Initialize setup file and environment:
+
 	make init
+
+Adapt and extend setup skeleton file based on generated setup files,
+and re-initialize
+(changes directly to setup file are *not* preserved):
+
+	$EDITOR config/ikiwiki.setup.in
+	git commit -m "My changes." config/ikiwiki.setup.in
+	rm config/ikiwiki.setup
+	make init
+
+(Publish)[src#publish] each git,
+using subdirs (e.g. example example/content example/styling).
+
+Make an initial full build:
+
+	make -B
+
+
+### Build
+
+Gentle refresh:
+
 	make
 
-Result is then below build/ .
+Forced full (re)build:
+
+	make -B
+
+In both cases,
+result is then below build/ .
+
+
+## Publish
+
+Clone web account,
+bootstrap,
+and register to account the use of ikiwiki:
+
+	ssh [[!template id=webuser]]@[[!template id=webhost]]
+	git clone /srv/git/[[!template id=githost]]/example ~/private_webdata/example
+	cd ~/private_webdata/example
+	git clone /srv/git/[[!template id=githost]]/example/content
+	git clone /srv/git/[[!template id=githost]]/example/styling
+	mkdir build
+	mkdir --parents ~/public_websites/www.example.org
+	mkdir --parents ~/public_cgi/example
+	ln --symbolic --relative -T ~/public_websites/www.example.org build/html
+	ln --symbolic --relative -T ~/public_cgi/example build/cgi
+	make init
+	make -B
+	mkdir -p ~/.ikiwiki
+	echo [[!template id=webuser]] $PWD/config/ikiwiki.setup >> ~/.ikiwiki/wikilist
+	logout
+
+Tell your hostmaster to enable publishing of your website,
+and to register centrally your use of ikiwiki.
-- 
cgit v1.2.3