From f227f1bba2a908339afaa18de6fbfcad100a1405 Mon Sep 17 00:00:00 2001
From: Nico Schottelius <nico@kr.ethz.ch>
Date: Fri, 4 Mar 2011 10:58:26 +0100
Subject: [PATCH] update readme

Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
---
 REAL_README | 68 ++++++++++++++++++++++++++++++-----------------------
 1 file changed, 39 insertions(+), 29 deletions(-)

diff --git a/REAL_README b/REAL_README
index 5b950519..238baa22 100644
--- a/REAL_README
+++ b/REAL_README
@@ -1,5 +1,7 @@
 [[!meta title="cdist - configuration management"]]
 
+[[!toc  levels=2]]
+
 ## Introduction
 
 cdist configures your system and is similar to
@@ -11,21 +13,20 @@ and [puppet](http://www.puppetlabs.com/), but
 it ticks differently:
 
  * cdist sticks completly to the KISS (keep it simple and stupid) paradigma
-  * cdist's core is very small (currently around 400 lines of code)
+  * cdist's core is very small (< 1k lines of code)
   * There is only one type to extend cdist called ***type***.
+  * One main development target: ***It must be incredible easy to add new types.***
  * cdist is UNIX
   * It reuses existing tools like cat, find, mv, ...
   * cdist's documentation is bundled as manpages
  * cdist is written in POSIX shell
   * No special requirements like high level interpreters needed on server or target
 
-MAIN AIM:  It MUST be incredible easy/dumb to add new types.
-
 
 ### Architecture
 
  * Push mode (server pushes configuration)
- * Pull mode (client triggers configuration)
+ * Pull mode planned (client triggers configuration)
  * User defines configuration in shell scripts (called ***manifests***)
  * Cdist generates internal configuration (cconfig style) and afterwards applies configuration
 
@@ -56,35 +57,48 @@ but is not. Or: The reason why I began to write cdist.
 ### Server
 
  * A posix like shell
- * SSH-Client (for push architecture)
- * SSH-Server (for pull architecture)
+ * SSH-Client
 
-### Client
+### Client ("target host")
 
  * A posix like shell
- * SSH-Client (for pull architecture)
- * SSH-Server (for push architecture)
+ * SSH-Server
 
-## Installation
 
-Cdist stable always in master
+## Getting cdist
 
- * Create a new unpriviliged user (probably "cdist")
- * Become that user, execute the following code:
+You can clone cdist from git, which gives you the advantage of having
+a version control in place for development of your own stuff as well.
 
-git clone git://git.schottelius.org/cdist
-cd cdist
-export PATH=$PATH:$(pwd -P)/bin
+There are at least two branches available:
+
+ * 1.0: stable branch of version 1.0
+ * next: preparing next cdist version
+
+Other branches may be available as well for features or bugfixes, but they
+may vanish at any point.
+
+
+### Installation
+
+To install cdist, execute the following commands:
+
+    git clone git://git.schottelius.org/cdist
+    cd cdist
+    export PATH=$PATH:$(pwd -P)/bin
+
+
+### Update
+
+As the stable branch always contains the stable code, you can upgrade
+cdist using
+
+    git pull
+
+If there are any incompatibilities, at least the minor version (1.0 -> 1.1)
+will change and thus a git pull will never break your cdist installation
+(in theory).
  
-That's it.
-
-Operation on the server is run as "cdist" user.
-Operation on the client is run as "root" user.
-
-## Update
-
-git pull && make install
-
 ## Support
 
 ### IRC
@@ -96,7 +110,3 @@ You can join the development ***IRC channel***
 
 Bug reports, questions, patches, etc. should be send to the
 [cdist mailing list](http://l.schottelius.org/mailman/listinfo/cdist).
-
-## Commercial Support
-
-To be done.