Cleanup of install, update and general documentation

Signed-off-by: Nico Schottelius <nico@brief.schottelius.org>

docs/web/cdist.mdwn

@@ -10,24 +10,10 @@ cdist is an alternative to other configuration management systems like
 [chef](http://wiki.opscode.com/display/chef/)
 and [puppet](http://www.puppetlabs.com/).
 
- * Browse the **documentation** for the [latest version](man/latest) or [all versions (>= 2.0.4)](man)
- * Read how to [[install or update cdist|install-update]]
+ * **Documentation** for the [latest version](man/latest) or [all versions (>= 2.0.4)](man)
+ * [[Installation|install]]
+ * [[Update|update]]
+ * [[Supported Operating Systems|os]]
  * [[Support|support]]
 
-### OS support
-
-cdist was tested or is know to run on at least
-
- * [Archlinux](http://www.archlinux.org/)
- * [Debian](http://www.debian.org/)
- * [CentOS](http://www.centos.org/)
- * [Fedora](http://fedoraproject.org/)
- * [FreeBSD](http://www.freebsd.org)
- * [Gentoo](http://www.gentoo.org/)
- * [Mac OS X](http://www.apple.com/macosx/)
- * [OpenBSD](http://www.openbsd.org)
- * [Redhat](http://www.redhat.com/)
- * [Ubuntu](http://www.ubuntu.com/)
- * [XenServer](http://www.citrix.com/xenserver/)
-
 [[!tag cdist unix]]

docs/web/cdist/install.mdwn

@@ -1,42 +1,44 @@
+[[!toc levels=3]]
+
 ## Requirements
 
-### Server
+### Source Host
+
+This is the machine you use to configure the target hosts.
 
- * A posix like shell
+ * /bin/sh: A posix like shell (for instance bash, dash, zsh)
  * Python (>= 3.2 required)
  * SSH client
  * Asciidoc (for building the manpages)
 
-### Client ("target host")
+### Target Hosts
 
- * A posix like shell
+ * /bin/sh: A posix like shell (for instance bash, dash, zsh)
  * SSH server
 
-
-## Installation
-
-### Preparation
+## Python Installation
 
 Ensure you have Python 3.2 installed on the machine you use to **deploy to the targets**
 (the ***source host***).
 
-#### Archlinux
+### Archlinux
 
-Archlinux already has python >= 3.2, so you only need to do:
+Archlinux includes a recent python in the extra repository. 
+You can install it using
 
     pacman -S python
 
-#### CentOS
+### CentOS
 
 See the "From source" section
 
 #### Debian
 
-For Debian >= wheezy:
+For Debian **wheezy** or newer:
 
     aptitude install python3
 
-On squeeze you can add following line in **/etc/apt/sources.list**
+On **squeeze** you can add following line in **/etc/apt/sources.list**
 
   deb http://ftp.debian.org/debian wheezy main
 
@@ -51,16 +53,16 @@ removed on **python3.2** installation. You surely want to reinstall them:
 
   apt-get install -t wheezy openssh-server openssh-client
 
-For older Debian versions, installing python 3.2 manually is required.
+For older Debian versions, installing python 3.2 from source is required.
 
+### Fedora
 
-#### Fedora
-
-For Fedora >= 15:
+Fedora 15 and newer includes a recent python.
+You can install it using
 
     yum install python3
 
-#### FreeBSD
+### FreeBSD
 
 For the port:
 
@@ -70,7 +72,9 @@ For the package:
 
     pkg_add -r python32
 
-#### Gentoo
+You can also use any newer version, but at least python 3.2 is required.
+
+### Gentoo
 
 Gentoo only provides python 3.2 in testing packages (http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=3&chap=3).
 If you want to ensure nothing breaks you must set back the python version to what was default before.
@@ -80,7 +84,7 @@ If you want to ensure nothing breaks you must set back the python version to wha
     eselect python list
     eselect python list set python3.2
 
-#### Max OS X
+### Max OS X
 
 You can choose between Homebrew and Macports, either way works:
 
@@ -93,7 +97,7 @@ You can choose between Homebrew and Macports, either way works:
     port install python32
     ln -s /opt/local/bin/python3.2 /opt/local/bin/python3
 
-#### From Source
+### From Source
 
 For those operating systems not yet support Python 3.2:
 
@@ -109,7 +113,7 @@ This installs python 3.2 to /usr/local/bin. Ensure this directory is in
 your PATH environment variable.
 
 
-### Get cdist
+## Install cdist
 
 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.
@@ -129,7 +133,8 @@ To install cdist, execute the following commands:
 There are at least the following branches available:
 
  * Development: master
- * 2.0: Python rewrite of cdist core [stable branch]
+ * 2.0: Current stable branch
+ * 2.1: Currently experimental - the next stable branch
 
 Old versions:
 
@@ -157,62 +162,4 @@ may vanish at any point. To select a specific branch use
  * git://github.com/telmich/cdist.git ([github](https://github.com/telmich/cdist))
  * git://git.code.sf.net/p/cdist/code ([sourceforge](https://sourceforge.net/p/cdist/code))
 
-## Update
-
-To upgrade cdist in the current branch use
-
-    git pull
-
-    # Also update the manpages
-    ./build man
-    export MANPATH=$MANPATH:$(pwd -P)/doc/man
-
-If you stay on a version branche (i.e. 1.0, 1.1., ...), nothing should break.
-The master branch on the other hand is the development branch and may not be
-working, break your setup or eat the tree in your garden.
-
-### Upgrading from 1.7 to 2.0
-
-* Ensure python (>= 3.2) is installed on the server
-* Use "cdist config host" instead of "cdist-deploy-to host"
-* Use "cdist config -p host1 host2" instead of "cdist-mass-deploy"
-* Use "cdist banner" for fun
-* Use **\_\_object_fq** instead of **\_\_self** in manifests
-
-### Upgrading from 1.6 to 1.7
-
-* If you used the global explorer **hardware_type**, you need to change
-  your code to use **machine** instead.
-
-### Upgrading from 1.5 to 1.6
-
-* If you used **\_\_package_apt --preseed**, you need to use the new
-  type **\_\_debconf_set_selections** instead.
-* The **\_\_package** types accepted either --state deinstalled or
-  --state uninstaaled. Starting with 1.6, it was made consistently
-  to --state removed.
-
-### Upgrading from 1.3 to 1.5
-
-No incompatiblities.
-
-### Upgrading from 1.2 to 1.3
-
-Rename **gencode** of every type to **gencode-remote**.
-
-### Upgrading from 1.1 to 1.2
-
-No incompatiblities.
-
-### Upgrading from 1.0 to 1.1
-
-In 1.1 the type **\_\_file** was split into **\_\_directory**, **\_\_file** and
-**\_\_link**. The parameter **--type** was removed from **\_\_file**. Thus you
-need to replace **\_\_file** calls in your manifests:
-
- * Remove --type from all \_\_file calls
- * If type was symlink, use \_\_link and --type symbolic
- * If type was directory, use \_\_directory
-
-
 [[!tag cdist unix]]

docs/web/cdist/update.mdwn

@@ -0,0 +1,59 @@
+## Update
+
+To upgrade cdist in the current branch use
+
+    git pull
+
+    # Also update the manpages
+    ./build man
+    export MANPATH=$MANPATH:$(pwd -P)/doc/man
+
+If you stay on a version branche (i.e. 1.0, 1.1., ...), nothing should break.
+The master branch on the other hand is the development branch and may not be
+working, break your setup or eat the tree in your garden.
+
+### Upgrading from 1.7 to 2.0
+
+* Ensure python (>= 3.2) is installed on the server
+* Use "cdist config host" instead of "cdist-deploy-to host"
+* Use "cdist config -p host1 host2" instead of "cdist-mass-deploy"
+* Use "cdist banner" for fun
+* Use **\_\_object_fq** instead of **\_\_self** in manifests
+
+### Upgrading from 1.6 to 1.7
+
+* If you used the global explorer **hardware_type**, you need to change
+  your code to use **machine** instead.
+
+### Upgrading from 1.5 to 1.6
+
+* If you used **\_\_package_apt --preseed**, you need to use the new
+  type **\_\_debconf_set_selections** instead.
+* The **\_\_package** types accepted either --state deinstalled or
+  --state uninstaaled. Starting with 1.6, it was made consistently
+  to --state removed.
+
+### Upgrading from 1.3 to 1.5
+
+No incompatiblities.
+
+### Upgrading from 1.2 to 1.3
+
+Rename **gencode** of every type to **gencode-remote**.
+
+### Upgrading from 1.1 to 1.2
+
+No incompatiblities.
+
+### Upgrading from 1.0 to 1.1
+
+In 1.1 the type **\_\_file** was split into **\_\_directory**, **\_\_file** and
+**\_\_link**. The parameter **--type** was removed from **\_\_file**. Thus you
+need to replace **\_\_file** calls in your manifests:
+
+ * Remove --type from all \_\_file calls
+ * If type was symlink, use \_\_link and --type symbolic
+ * If type was directory, use \_\_directory
+
+
+[[!tag cdist unix]]