# HG changeset patch
# User Tero Marttila <terom@paivola.fi>
# Date 1332246305 -7200
# Node ID 12e098a732ed7cee1159ae15cd06f5e820f6173e
# Parent  a2d87cfd77e498fa55031f17592cbd3f5b162131
README: docdoc

diff -r a2d87cfd77e4 -r 12e098a732ed README
--- a/README	Tue Mar 20 14:24:58 2012 +0200
+++ b/README	Tue Mar 20 14:25:05 2012 +0200
@@ -5,17 +5,17 @@
 
     `update` also shows and commits changes in settings/ data.
 
-    -d
+    -d DIR
         Do data operations under given dir-root, as opposed to CWD.
 
     -q
-        Quiet. No log messages. XXX: still outputs diffs, though..
+        Quiet. No log messages except errors.
 
     -vDV
         Increasing logging verbosity.
 
     -p
-        Show diffs for changed output.
+        Show diffs for changed output on stdout.
 
     -F
         Force-update output files, even if newer than input files.
@@ -23,16 +23,21 @@
     -S
         Do not generate new serials for zones.
 
+    -s
+        Generate new serials for all zones.
+
     -n
         Fake-update; show changes, but don't actually commit/deploy them.
 
+        Useful for testing.
+
     -C
         Do not commit source changes.
 
     -c
         Force-commit source changes, even though -n
 
-    -m
+    -m MSG
         Commit message for source changes; optional
 
 bin/update-serial:
@@ -64,10 +69,12 @@
 
 bin/update:
     Runs update-serial/process-zone/expand-zone to keep various generated zones/views up-to-date with respect to
-    source files under settings/
+    source files under settings/.
 
     Also supports hg diff/commit/annotate integration with settings.
 
+    Acts as our configuration file, determining the data/zones layout below.
+
 settings/:
     Input files, fed through update to generate files under zones/
 
@@ -80,7 +87,7 @@
         May include a view-based $INCLUDE to include different zone data for different views.
 
     *.zone.*:
-        Additional common zone data; copied to zones/, and $INCLUDE'd from *.zone.
+        Include zonefiles, $INCLUDE'd from *.zone
 
     *.txt:
         Hosts zone data, used to generate forwards/reverse -hosts zones
@@ -88,24 +95,24 @@
 zones/:
     Output files, loaded by bind.
 
-    *.zone:
-        View-independent zone headers with expanded serial.
-
-    *.zone.hosts:
-        View-independent generated zones for hosts.
-
-    *.zone.$view:
-        Per-view copied zone data.
+    common/*
+        Common zone files shared across views.
 
-    *.zone.*:
-        Additional view-independent copied zone data.
-
-    $view/*.zone:
-        Per-view zone header with expanded $INCLUDE:s and serial.
+    hosts/*:$view
+        View-variant hosts zones generated from settings/*.txt
 
-    $view/*.zone.hosts:
-        Per-view generated zones for hosts.
+    hosts/*
+        Host zones generated from settings/*.txt, may be used in some views but not others.
 
-    $view/*.zone -> .../$.zone:
-        Symlinked generic-zone data for some specific zone; either view-specific or view-independent.
+    includes/*:$view
+        View-specific zone includes used from view/*.
 
+    includes/*.*
+        Zone includes used from view/*.
+
+    $view/*
+        Zone data for given zone/domain in given view
+
+    $view/* -> ...:
+        Symlinked generic-zone data for some specific zone; either to common/* or $view/*.
+