doc: Finish merging remaining documentation updates

Signed-off-by: Sol Jerome <sol.jerome@gmail.com>

11 files changed, 200 insertions, 275 deletions

diff --git a/doc/installation/distributions.txt b/doc/installation/distributions.txt
index 5a86e81d5..38b34f14d 100644
--- a/doc/installation/distributions.txt
+++ b/doc/installation/distributions.txt
@@ -3,15 +3,134 @@
 .. _distributions:
 
 ===========================
-Distribution-specific notes 
+Distribution-specific notes
 ===========================
 
-The installation of Bcfg2 on a specific distribution depends on 
-the used package management tool and the disposability in the 
-distribution's package :term:`repository`
-. 
+The installation of Bcfg2 on a specific distribution depends on the
+package management tool and the availability of the package in the
+distribution's repository.
 
-.. toctree::
-   :glob:
+ArchLinux
+=========
 
-   distro/*
+Packages for `Arch Linux`_ are available in the Arch User Repository (AUR_).
+Just use `pacman` to perform the installation ::
+
+   pacman -S bcfg2 bcfg2-server
+
+.. _Arch Linux: http://www.archlinux.org/
+.. _AUR: http://aur.archlinux.org/packages.php?ID=20979
+
+Debian
+======
+
+Packages of Bcfg2 are available for Debian Lenny, Debian Squeeze, and
+Debian Sid. The fastest way to get Bcfg2 onto your Debian system
+is to use ``apt-get`` or ``aptitude``. ::
+
+   sudo aptitude install bcfg2 bcfg2-server
+
+If you want to use unofficial packages from Bcfg2 see the instructions
+at `CustomDebianRepository`_.
+
+.. _CustomDebianRepository: http://trac.mcs.anl.gov/projects/bcfg2/wiki/PrecompiledPackages#UnofficialDebianRepository
+
+Fedora
+======
+
+The fastest way to get Bcfg2 Packages_ onto your Fedora_ system is to
+use `yum` or PackageKit. Yum will pull in all dependencies of Bcfg2
+automatically. ::
+
+    su -c 'yum install bcfg2-server bcfg2'
+
+Be aware that the latest release of Bcfg2 may only be available for the
+Development release of Fedora (Rawhide).  With the activation of the
+Rawhide repository of Fedora you will be able to install it. ::
+
+    su -c 'yum install --enablerepo=rawhide bcfg2-server bcfg2'
+
+This way is not recommended on production systems. Only for testing.
+
+Gentoo
+======
+
+Early in July 2008, Bcfg2 was added to the Gentoo portage tree. So far
+it's still keyworded for all architectures, but we are actively working
+to get it marked as stable.
+
+If you don't use portage to install Bcfg2, you'll want to make sure you
+have all the prerequisites installed first. For a server, you'll need:
+
+* ``app-admin/gamin`` or ``app-admin/fam``
+* ``dev-python/lxml``
+
+Clients will need at least:
+
+* ``app-portage/gentoolkit``
+
+OS X
+====
+
+Bcfg2 can be installed either via MacPorts or by creating a native OS X
+package.
+
+MacPorts
+--------
+
+Once macports is installed::
+
+    port install bcfg2
+
+Using native OS X python
+------------------------
+
+First, make sure you have Xcode installed as you need ``packagemaker`` which
+comes bundled in the Developer tools.
+
+Clone the git source::
+
+    git clone git://git.mcs.anl.gov/bcfg2.git
+
+Change to the osx directory and type make. Your new package should be
+located at bcfg2-$VERSION.pkg (where $VERSION is that which is specified
+in setup.py).
+
+RHEL / Centos / Scientific Linux
+================================
+
+While you can go about building all these things from source, this
+section will try and meet the dependencies using packages from EPEL_
+[#f1]_. The *el5* and the soon available *el6* package should be compatible
+with `CentOS`_ 5.x/6.x and `Scientific Linux`_.
+
+EPEL_::
+
+    [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm
+
+Install the bcfg2-server and bcfg2 RPMs::
+
+    [root@centos ~]# yum install bcfg2-server bcfg2
+
+.. note::
+
+    The latest package for *el5* is only available in the testing repository.
+
+.. [#f1] For more details check the EPEL_ `instructions <http://fedoraproject.org/wiki/EPEL/FAQ#howtouse>`_
+
+.. _CentOS: http://www.centos.org/
+.. _Scientific Linux: http://www.scientificlinux.org/
+.. _EPEL: http://fedoraproject.org/wiki/EPEL
+.. _RPMForge: https://rpmrepo.org/RPMforge
+
+Ubuntu
+======
+
+We highly recommend following the instructions at `ubuntu-installation`_
+in order to install a recent version of Bcfg2 on your system. However,
+if you would like to install the older package, you can use the following
+command::
+
+   sudo aptitude install bcfg2 bcfg2-server
+
+.. _ubuntu-installation: http://trac.mcs.anl.gov/projects/bcfg2/wiki/PrecompiledPackages#UbuntuLaunchpadBcfg2PPA
diff --git a/doc/installation/distro/archlinux.txt b/doc/installation/distro/archlinux.txt
deleted file mode 100644
index 75ff59c49..000000000
--- a/doc/installation/distro/archlinux.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _installation-archlinux:
-
-.. _Arch Linux: http://www.archlinux.org/
-.. _AUR: http://aur.archlinux.org/packages.php?ID=20979
-
-
-ArchLinux
-=========
-
-Packages for `Arch Linux`_ are available in the Arch User Repository (AUR_).
-Just use `pacman` to perform the installation :: 
-
-   pacman -S bcfg2 bcfg2-server 
-
-
diff --git a/doc/installation/distro/debian.txt b/doc/installation/distro/debian.txt
deleted file mode 100644
index 67a4f1d9d..000000000
--- a/doc/installation/distro/debian.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _debian:
-
-.. _Wiki: http://trac.mcs.anl.gov/projects/bcfg2/wiki/PrecompiledPackages#UnofficialDebianRepository
-
-Debian
-======
-
-Packages of Bcfg2 are available for Debian Lenny, Debian Squeeze, and
-Debian Sid. The fastest way to get Bcfg2 onto your Debian system
-is to use `apt-get` or `aptitude`. :: 
-
-   sudo aptitude install bcfg2 bcfg2-server
-
-If you want to use unofficial packages from Bcfg2. Add the following line
-to your `/etc/apt/sources.list` file :: 
-
-   deb ftp://ftp.mcs.anl.gov/pub/bcfg/debian sarge/
-
-Now just run `aptitute` in the way it is mentioned above. 
-
-For more details about running prerelease version of Bcfg2 on Debian
-systems, please refer to the Wiki_.
diff --git a/doc/installation/distro/fedora.txt b/doc/installation/distro/fedora.txt
deleted file mode 100644
index 92771b974..000000000
--- a/doc/installation/distro/fedora.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _Packages: https://admin.fedoraproject.org/pkgdb/acls/name/bcfg2
-.. _Fedora: https://www.fedoraproject.org
-
-.. _fedora-installation:
-
-Fedora
-======
-
-The fastest way to get Bcfg2 Packages_ onto your Fedora_ system is to
-use `yum` or PackageKit. Yum will pull in all dependencies of Bcfg2
-automatically. ::
-
-    $ su -c 'yum install bcfg2-server bcfg2'
-
-Be aware that the latest release of Bcfg2 may only be available for the
-Development release of Fedora (Rawhide).  With the activation of the
-Rawhide repository of Fedora you will be able to install it. ::
-
-    $ su -c 'yum install --enablerepo=rawhide bcfg2-server bcfg2'
-
-This way is not recommanded on productive systems. Only for testing. 
diff --git a/doc/installation/distro/gentoo.txt b/doc/installation/distro/gentoo.txt
deleted file mode 100644
index 5497a01b2..000000000
--- a/doc/installation/distro/gentoo.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _gentoo-installation:
-
-.. _Freenode: http://chat.freenode.net
-.. _#bcfg2: irc://chat.freenode.net/bcfg2
-
-
-Gentoo
-======
-
-Early in July 2008, Bcfg2 was added to the Gentoo portage tree. So far
-it's only keyworded for ~x86, but we hope to see it soon in the amd64 and
-x64-solaris ports.  If you're using Gentoo on some other architecture, it
-should still work provided that you have a reasonably up to date Python;
-try adding `app-admin/bcfg2 ~*` to your `/etc/portage/package.keywords`
-file.
-
-If you don’t use portage to install Bcfg2, you’ll want to make sure you
-have all the prerequisites installed first. For a server, you’ll need:
-
-* ``app-admin/gamin`` or ``app-admin/fam``
-* ``dev-python/lxml``
-
-Clients will need at least:
-
-* ``app-portage/gentoolkit``
diff --git a/doc/installation/distro/osx.txt b/doc/installation/distro/osx.txt
deleted file mode 100644
index 8b7a5a95d..000000000
--- a/doc/installation/distro/osx.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _osx-installation:
-
-.. _Freenode: http://chat.freenode.net
-.. _#bcfg2: irc://chat.freenode.net/bcfg2
-
-
-OS X
-====
-
-Once macports is installed::
-
-    port install bcfg2
-
-Using native OS X python
-------------------------
-
-First, make sure you have Xcode installed as you need `packagemaker` which 
-comes bundled in the Developer tools.
-
-Clone the git source::
-
-    git clone git://git.mcs.anl.gov/bcfg2.git
-
-Change to the osx directory and type make. Your new package should be located 
-at bcfg2-'''$VERSION'''.pkg (where '''$VERSION''' is that which is specified
-in setup.py).
-
diff --git a/doc/installation/distro/rhel.txt b/doc/installation/distro/rhel.txt
deleted file mode 100644
index 49e43179f..000000000
--- a/doc/installation/distro/rhel.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _CentOS: http://www.centos.org/
-.. _Red Hat/RHEL: http://www.redhat.com/rhel/
-.. _Scientific Linux: http://www.scientificlinux.org/
-.. _EPEL: http://fedoraproject.org/wiki/EPEL
-.. _RPMForge: https://rpmrepo.org/RPMforge
-
-.. _rhel-installation:
-
-RHEL / Centos / Scientific Linux 
-================================
-
-While you can go about building all these things from source, this
-section will try and meet the dependencies using packages from EPEL_
-[#f1]_. The *el5* and the soon available *el6* package should be compatible
-with `CentOS`_ 5.x/6.x and `Scientific Linux`_.
-
-EPEL_::
-
-    [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm
-
-Install the bcfg2-server and bcfg2 RPMs::
-
-    [root@centos ~]# yum install bcfg2-server bcfg2
-
-.. note::
-
-    The latest package for *el5* is only available in the testing repository.
-
-.. [#f1] For more details check the EPEL_ `instructions <http://fedoraproject.org/wiki/EPEL/FAQ#howtouse>`_
diff --git a/doc/installation/distro/ubuntu.txt b/doc/installation/distro/ubuntu.txt
deleted file mode 100644
index 694cce865..000000000
--- a/doc/installation/distro/ubuntu.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _ubuntu-installation:
-
-.. _Ubuntu: http://www.ubuntu.com
-.. _Wiki: http://trac.mcs.anl.gov/projects/bcfg2/wiki/PrecompiledPackages#UbuntuLaunchpadBcfg2PPA
-
-Ubuntu
-======
-
-The steps to bring Bcfg2 onto your Ubuntu_ system depends on your
-release. 
-
-* Dapper
-   Add the following lines to `/etc/apt/sources.list` ::
-
-      deb ftp://ftp.mcs.anl.gov/pub/bcfg/ubuntu dapper/
-      deb http://archive.ubuntu.com/ubuntu dapper universe
-      deb-src http://archive.ubuntu.com/ubuntu dapper universe
-
-* Edgy
-   Add the following lines to `/etc/apt/sources.list` ::
-
-      deb ftp://ftp.mcs.anl.gov/pub/bcfg/ubuntu edgy/
-      deb http://archive.ubuntu.com/ubuntu edgy universe
-      deb-src http://archive.ubuntu.com/ubuntu edgy universe
-
-* Feisty
-   Those packages are available from the Ubuntu_ repositories.
-
-To install the packages, just lauch the following command ::
-
-   sudo aptitude install bcfg2 bcfg2-server
-
-For more details about running prerelease version of Bcfg2 on Ubuntu_
-systems, please refer to the Wiki_.
diff --git a/doc/installation/packages.txt b/doc/installation/packages.txt
index a15e3e98e..b175d2625 100644
--- a/doc/installation/packages.txt
+++ b/doc/installation/packages.txt
@@ -9,34 +9,34 @@
 .. _RPMForge: https://rpmrepo.org/RPMforge
 
 
-Building packages from source
-=============================
+Building RPM packages from source
+=================================
 
 The Bcfg2 distribution contains two different spec files.
 
 Building from Tarball
 ---------------------
 
-* Copy the tarball to `/usr/src/packages/SOURCES/`
-* Extract another copy of it somewhere else (eg: `/tmp`) and retrieve
-  the `misc/bcfg2.spec` file
+* Copy the tarball to ``/usr/src/packages/SOURCES/``
+* Extract another copy of it somewhere else (eg: ``/tmp``) and retrieve
+  the ``misc/bcfg2.spec`` file
 * Run ::
 
-   rpmbuild -ba bcfg2.spec
+    rpmbuild -ba bcfg2.spec
 
-* The resulting RPMs will be in `/usr/src/packages/RPMS/` and SRPMs 
-  in `/usr/src/packages/SRPMS`
+* The resulting RPMs will be in ``/usr/src/packages/RPMS/`` and SRPMs
+  in ``/usr/src/packages/SRPMS``
 
 Building from an GIT Checkout
 -----------------------------
 
-* Change to the `redhat/` directory in the working copy
+* Change to the ``redhat/`` directory in the working copy
 * Run ::
 
     make
 
-* The resulting RPMs will be in `/usr/src/redhat/RPMS/ `and SRPMs 
-  in `/usr/src/redhat/SRPMS` and will have the SVN revision appended 
+* The resulting RPMs will be in ``/usr/src/redhat/RPMS/`` and SRPMs
+  in ``/usr/src/redhat/SRPMS`` and will have the SVN revision appended
 
 Building RPM packages with ``rpmbuild``
 ---------------------------------------
@@ -47,35 +47,35 @@ The *el5* package should be compatible with CentOS 5.x.
 
 * Installation of the EPEL_ repository package ::
 
-   [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm
+    [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm
 
 * Now you can install the rest of the prerequisites ::
 
-   [root@centos ~]# yum install python-genshi python-cheetah python-lxml
+    [root@centos ~]# yum install python-genshi python-cheetah python-lxml
 
 * After installing git, check out the master branch ::
 
-   [root@centos redhat]# git clone git://git.mcs.anl.gov/bcfg2.git
+    [root@centos redhat]# git clone git://git.mcs.anl.gov/bcfg2.git
 
 * Install the ``fedora-packager`` package ::
 
-   [root@centos ~]# yum install fedora-packager
+    [root@centos ~]# yum install fedora-packager
 
 * A directory structure for the RPM build process has to be established. ::
 
-   [you@centos ~]$ rpmdev-setuptree
+    [you@centos ~]$ rpmdev-setuptree
 
 * Change to the *redhat* directory of the checked out Bcfg2 source::
 
-   [you@centos ~]$ cd bcfg2/redhat/
+    [you@centos ~]$ cd bcfg2/redhat/
 
-* In the particular directory is a ``Makefile`` which will do the job of 
+* In the particular directory is a ``Makefile`` which will do the job of
   building the RPM packages. You can do this as root, but it's not
   recommanded ::
 
-   [you@centos redhat]$ make
+    [you@centos redhat]$ make
 
 * Now the new RPM package can be installed. Please adjust the path to
   your RPM package ::
 
-   [root@centos ~]# rpm -ihv /home/YOU/rpmbuild/RPMS/noarch/bcfg2-server-1.0.0-0.2r5835.noarch.rpm
+    [root@centos ~]# rpm -ihv /home/YOU/rpmbuild/RPMS/noarch/bcfg2-server-1.0.0-0.2r5835.noarch.rpm
diff --git a/doc/installation/prerequisites.txt b/doc/installation/prerequisites.txt
index e4ea715b0..758ee4a21 100644
--- a/doc/installation/prerequisites.txt
+++ b/doc/installation/prerequisites.txt
@@ -14,16 +14,22 @@ what software is needed on the client and server side.
 Bcfg2 Client
 ------------
 
-=====================================   ===================  ==============================
-Software                                Version              Requires
-=====================================   ===================  ==============================
-libxml2 (if lxml is used)               Any             
-libxslt (if lxml is used)               Any                  libxml2
-python                                  2.3-2.4, 2.5 [#f1]_
-lxml or elementtree [#f2]_              Any                  lxml: libxml2, libxslt, python
-python-apt [#f3]_	                    Any                  python
-debsums (if APT tool driver is used) 	Any 	
-=====================================   ===================  ==============================
++----------------------------+---------------+--------------------------------+
+| Software                   | Version       | Requires                       |
++============================+===============+================================+
+| libxml2 (if lxml is used)  | Any           |                                |
++----------------------------+---------------+--------------------------------+
+| libxslt (if lxml is used)  | Any           | libxml2                        |
++----------------------------+---------------+--------------------------------+
+| python                     | >= 2.3 [#f1]_ |                                |
++----------------------------+---------------+--------------------------------+
+| lxml or elementtree [#f2]_ | Any           | lxml: libxml2, libxslt, python |
++----------------------------+---------------+--------------------------------+
+| python-apt [#f3]_          | Any           | python                         |
++----------------------------+---------------+--------------------------------+
+| debsums (if APT tool       | Any           |                                |
+| driver is used)            |               |                                |
++----------------------------+---------------+--------------------------------+
 
 
 .. [#f1] python 2.5 works with elementtree.
@@ -33,15 +39,20 @@ debsums (if APT tool driver is used) 	Any
 Bcfg2 Server
 ------------
 
-=====================================   =============  ==============================
-Software                                Version        Requires
-=====================================   =============  ==============================
-libxml2                                 2.6.24+              
-libxslt                                 Any            libxml2
-python                                  2.2-2.5
-lxml                                    0.9+           lxml: libxml2, libxslt, python
-gamin or fam                            Any
-python-gamin or python-fam              Any            gamin or fam, python
-M2crypto 	                            Any 	       python, openssl 
-=====================================   =============  ==============================
-	
++----------------------------+----------+--------------------------------+
+| Software                   | Version  | Requires                       |
++============================+==========+================================+
+| libxml2                    | 2.6.24+  |                                |
++----------------------------+----------+--------------------------------+
+| libxslt                    | Any      | libxml2                        |
++----------------------------+----------+--------------------------------+
+| python                     | 2.2-2.5  |                                |
++----------------------------+----------+--------------------------------+
+| lxml                       | 0.9+     | lxml: libxml2, libxslt, python |
++----------------------------+----------+--------------------------------+
+| gamin or fam               | Any      |                                |
++----------------------------+----------+--------------------------------+
+| python-gamin or python-fam | Any      | gamin or fam, python           |
++----------------------------+----------+--------------------------------+
+| M2crypto                   | Any      | python, openssl                |
++----------------------------+----------+--------------------------------+
diff --git a/doc/installation/source.txt b/doc/installation/source.txt
index e21f7150f..3ea0404ad 100644
--- a/doc/installation/source.txt
+++ b/doc/installation/source.txt
@@ -1,64 +1,46 @@
 .. -*- mode: rst -*-
 
-.. _Download: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Download
-.. _GPG:     http://pgpkeys.mit.edu:11371/pks/lookup?op=get&search=0x75BF2C177F7D197E
-.. _GPGKey:  ftp://ftp.mcs.anl.gov/pub/bcfg/bcfg2-1.1.0.tar.gz.gpg
-.. _Tarball: ftp://ftp.mcs.anl.gov/pub/bcfg/bcfg2-1.1.0.tar.gz
-
-.. |md5sum| replace:: 13593938daf7e8b9a81cb4b677dc7f99
-.. |version| replace:: 1.1.0
-.. |rel_date| replace:: 9/27/10
+.. _GPG1: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x75BF2C177F7D197E
+.. _GPG2: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x80B8492FA88FFF4B
 
 .. _source:
 
+Installation from source
+========================
+
 Download
-========
+--------
 
 Tarball
--------
+^^^^^^^
 
 The Bcfg2 source tarball can be grabbed from the Download_ page.
 
-=========  ========  ======= ============== =====================
-Version    URL       GPG key Release Date   md5sum
-=========  ========  ======= ============== =====================
-|version|  Tarball_  GPGKey_ |rel_date|     |md5sum|   
-=========  ========  ======= ============== =====================
-
-The full command to use with ``wget`` are listed below. Please 
-replace ``<version>`` with |version|. ::
-
-   wget ftp://ftp.mcs.anl.gov/pub/bcfg/bcfg2-<version>.tar.gz
-   wget ftp://ftp.mcs.anl.gov/pub/bcfg/bcfg2-<version>.tar.gz.gpg
-
-All tarballs are signed with GPG key `7F7D197E <GPGKey>`_. You can verify
-your download by importing the key and running ::
-
-   $ gpg --recv-keys 0x75bf2c177f7d197e
-   $ gpg --verify bcfg2-<version>.tar.gz.gpg bcfg2-<version>.tar.gz
-
-For older or prepreleases please visit the Download_ wiki page.
+All tarballs are signed with GPG keys `7F7D197E <GPG1>`_ or `A88FFF4B
+<GPG2>`_. You can verify your download by importing the keys and running ::
 
+    gpg --recv-keys 0x75bf2c177f7d197e 0x80B8492FA88FFF4B
+    gpg --verify bcfg2-<version>.tar.gz.gpg bcfg2-<version>.tar.gz
 
 Git checkout
-------------
+^^^^^^^^^^^^
 
 You can also get the latest (possibly broken) code via git ::
 
-   git clone git://git.mcs.anl.gov/bcfg2.git
+    git clone git://git.mcs.anl.gov/bcfg2.git
 
-Installation from source
-========================
+Install
+-------
 
 If you are working with the release tarball of Bcfg2 you need to 
 untar it before you can go on with the installation ::
 
-   tar -xzf bcfg2-<version>.tar.gz
+    tar -xzf bcfg2-<version>.tar.gz
 
-Now you can build Bcfg2 with. If you are working with a SVN checkout
-no <version> need to be specified. ::
+Now you can build Bcfg2 with. If you are working from a git clone no
+<version> need to be specified. ::
 
-   cd bcfg2-<version>
-   python setup.py install --prefix=/install/prefix
+    cd bcfg2-<version>
+    python setup.py install --prefix=/install/prefix
 
 This will install both the client and server on that machine.