diff -r e88c57c10b34 -r edd2a575a8e7 doc/book/en/admin/setup.rst
--- a/doc/book/en/admin/setup.rst	Wed Apr 06 12:33:39 2011 +0200
+++ b/doc/book/en/admin/setup.rst	Fri Apr 15 11:58:33 2011 +0200
@@ -5,40 +5,37 @@
 Installation of a *CubicWeb* environment
 ========================================
 
-There are different simple ways to install |cubicweb| and its
-dependencies depending on your requirements:
+Official releases are available from the `CubicWeb.org forge`_ and from
+`PyPI`_. Since CubicWeb is developed using `Agile software development
+<http://en.wikipedia.org/wiki/Agile_software_development>`_ techniques, releases
+happen frequently. In a version numbered X.Y.Z, X changes after a few years when
+the API breaks, Y changes after a few weeks when features are added and Z
+changes after a few days when bugs are fixed.
 
-* `Distribution-specific installation`. This option shows you how to
-  easily install |cubicweb| and its requirements on your system:
-
-  - `Installation on Debian/Ubuntu`_ 
-  - `Installation on Windows`_
-  - `Install in a virtualenv`_
+Depending on your needs, you will chose a different way to install CubicWeb on
+your system:
 
-* `Official release installation`. This options is the best approach
-  for those who want a flexible and up-to-date stable
-  version. |cubicweb| is published on `PyPI`_:
-
-  - `Installation with pip`_
-  - `Installation with easy_install`_
+- `Installation on Debian/Ubuntu`_
+- `Installation on Windows`_
+- `Installation in a virtualenv`_
+- `Installation with pip`_
+- `Installation with easy_install`_
+- `Installation from tarball`_
 
-* `Lastest development version installation`. This option is
-  dedicated for power-users who want the very lastest
-  features (|cubicweb| is an `Agile software <http://en.wikipedia.org/wiki/Agile_software_development>`_).
+If you are a power-user and need the very latest features, you will
 
-  - `Installation from tarball`_
-  - `Installation from version control`_
+- `Install from version control`_
 
-Once installed, you can have a look to :ref:`ConfigEnv` for better control
+Once the software is installed, move on to :ref:`ConfigEnv` for better control
 and advanced features of |cubicweb|.
 
 .. _`Installation on Debian/Ubuntu`: DebianInstallation_
 .. _`Installation on Windows`: WindowsInstallation_
-.. _`Install in a virtualenv`: VirtualenvInstallation_
+.. _`Installation in a virtualenv`: VirtualenvInstallation_
 .. _`Installation with pip`: PipInstallation_
 .. _`Installation with easy_install`: EasyInstallInstallation_
 .. _`Installation from tarball`: TarballInstallation_
-.. _`Installation from version control`: MercurialInstallation_
+.. _`Install from version control`: MercurialInstallation_
 
 
 .. _DebianInstallation:
@@ -47,9 +44,9 @@
 ---------------------
 
 |cubicweb| is packaged for Debian/Ubuntu (and derived
-distributions). Their integrated package-management systems make
-installation and upgrading much easier for users since
-dependencies/recommends (like databases) are automatically installed.
+distributions). Their integrated package-management system make
+installation and upgrade much easier for users since
+dependencies (like databases) are automatically installed.
 
 Depending on the distribution you are using, add the appropriate line to your
 `list of sources` (for example by editing ``/etc/apt/sources.list``).
@@ -84,19 +81,20 @@
 instances. ``cubicweb-dev`` installs the development environment
 allowing you to develop new cubes.
 
-There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can acces a
-list of availble cubes using ``apt-cache search cubicweb`` or at the
-`CubicWeb.org Forge`_.
+There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
+list of available cubes using ``apt-cache search cubicweb`` or at the
+`CubicWeb.org forge`_.
 
 .. note::
 
   `cubicweb-dev` will install basic sqlite support. You can easily setup
-  :ref:`cubicweb with other database <DatabaseInstallation>` using the following virtual packages :
+  :ref:`cubicweb with other database <DatabaseInstallation>` using the following
+  virtual packages :
 
-  * `cubicweb-postgresql-support` contains necessary dependency for
+  * `cubicweb-postgresql-support` contains the necessary dependency for
     using :ref:`cubicweb with postgresql datatabase <PostgresqlConfiguration>`
 
-  * `cubicweb-mysql-support` contains necessary dependency for using
+  * `cubicweb-mysql-support` contains the necessary dependency for using
     :ref:`cubicweb with mysql database <MySqlConfiguration>`.
 
 .. _`list of sources`: http://wiki.debian.org/SourcesList
@@ -110,15 +108,14 @@
 
 You need to have `python`_ version >= 2.5 and < 3 installed.
 
-Then your best option is probably the :ref:`EasyInstallInstallation`.
-In fact it is a pure python packages manager which lacks in Windows.
-It helps users to install python packages along with dependencies,
-searching for suitable pre-compiled binaries on the
-`The Python Package Index`_.
+If you want an automated install, your best option is probably the
+:ref:`EasyInstallInstallation`. EasyInstall is a tool that helps users to
+install python packages along with their dependencies, searching for suitable
+pre-compiled binaries on the `The Python Package Index`_.
 
-Moreover, if you want better control over the process as well as
-a suitable development environment or if you are having problems with
-`easy_install`, move right away to :ref:`SetUpWindowsEnv`.
+If you want better control over the process as well as a suitable development
+environment or if you are having problems with `easy_install`, read on to
+:ref:`SetUpWindowsEnv`.
 
 .. _python:  http://www.python.org/
 .. _`The Python Package Index`: http://pypi.python.org
@@ -129,8 +126,7 @@
 --------------------
 
 Since version 3.9, |cubicweb| can be safely installed, used and contained inside
-a `virtualenv`_. You can use either 
-:ref:`pip <PipInstallation>` or
+a `virtualenv`_. You can use either :ref:`pip <PipInstallation>` or
 :ref:`easy_install <EasyInstallInstallation>` to install |cubicweb| inside an
 activated virtual environment.
 
@@ -139,52 +135,53 @@
 `pip` install
 -------------
 
-Using pip_ is the recommended way to install |cubicweb|. pip_ is a
-smart python utility that lets you automatically download, build,
-install, and manage python packages and their dependencies. It is full
-compatible with `virtualenv`_.
+pip_ is a python utility that helps downloading, building, installing, and
+managing python packages and their dependencies. It is fully compatible with
+`virtualenv`_ and installs the packages from sources published on the
+`The Python Package Index`_.
 
-pip_ install the packages from sources published on the
-*The Python Package Index* (PyPI_).
-You need a compilation environment because some dependencies have C
-extensions. If you definitively wont, installing 
-`Lxml <http://codespeak.net/lxml/>`_,
-`Twisted <http://twistedmatrix.com/trac/>`_ and 
+.. _`pip`: http://pip.openplans.org/
+.. _`virtualenv`: http://virtualenv.openplans.org/
+
+A working compilation chain is needed to build the modules that include C
+extensions. If you definitively wont, installing `Lxml
+<http://codespeak.net/lxml/>`_, `Twisted <http://twistedmatrix.com/trac/>`_ and
 `libgecode <http://www.gecode.org/>`_ will help.
 
-To install |cubicweb| and all dependencies just use the following command
-line::
+To install |cubicweb| and its dependencies, just run::
 
   pip install cubicweb
 
-There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can acces a
-list of availble cubes on
-`PyPI <http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb&submit=search>`_ 
-or at the `CubicWeb.org Forge`_.
+There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
+list of available cubes on
+`PyPI <http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb&submit=search>`_
+or at the `CubicWeb.org forge`_.
 
 For example, installing the *blog cube* is achieved by::
 
   pip install cubicweb-blog
 
-.. _`gecode library`: http://www.gecode.org/
-
-
 .. _EasyInstallInstallation:
 
 `easy_install` install
 ----------------------
 
-If you are not a Windows user and you have a compilation environment,
-we recommend you to use the PipInstallation_.
+.. note::
+
+   If you are not a Windows user and you have a compilation environment, we
+   recommend you to use the PipInstallation_.
 
-Install |cubicweb| version >= 3.9 with::
+`easy_install`_ is a python utility that helps downloading, installing, and
+managing python packages and their dependencies.
+
+Install |cubicweb| and its dependencies, run::
 
   easy_install cubicweb
 
-There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can acces a
-list of availble cubes on `PyPI
+There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
+list of available cubes on `PyPI
 <http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb&submit=search>`_
-or at the `CubicWeb.org Forge`_. 
+or at the `CubicWeb.org Forge`_.
 
 For example, installing the *blog cube* is achieved by::
 
@@ -193,10 +190,10 @@
 .. note::
 
   If you encounter problem with :ref:`cubes <AvailableCubes>` installation,
-  considere using :ref:`PipInstallation` which is more stable
-  but do not offer binaries installation.
+  consider using :ref:`PipInstallation` which is more stable
+  but can not installed pre-compiled binaries.
 
-.. _`easy_install`:   http://packages.python.org/distribute/easy_install.html
+.. _`easy_install`: http://packages.python.org/distribute/easy_install.html
 
 
 .. _SourceInstallation:
@@ -206,7 +203,7 @@
 
 .. _TarballInstallation:
 
-You can download the archive containing the sources from our download site at
+You can download the archive containing the sources from
 `http://download.logilab.org/pub/cubicweb/ <http://download.logilab.org/pub/cubicweb/>`_.
 
 Make sure you also have all the :ref:`InstallDependencies`.
@@ -220,7 +217,7 @@
 setting the :ref:`resource mode <RessourcesConfiguration>` to `user`. This will
 ease the development with the framework.
 
-There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can acces a
+There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
 list of availble cubes at the `CubicWeb.org Forge`_.
 
 
@@ -229,22 +226,14 @@
 Install from version control system
 -----------------------------------
 
-To install the lastest stable development version from our Mercurial
-repository, you can use `pip` (you need a compilation devlopment to perform
-such install)::
-
-  pip install -e "hg+http://www.logilab.org/hg/cubicweb/@stable#egg=cubicweb"
-
-Or, to develop with the framework you can keep up to date with on-going
-development by cloning our :ref:`Mercurial <MercurialPresentation>`
-repository::
+To keep-up with on-going development, clone the :ref:`Mercurial
+<MercurialPresentation>` repository::
 
   hg clone -u stable http://hg.logilab.org/cubicweb # stable branch
-  hg clone http://hg.logilab.org/cubicweb # very lastest (development branch)
+  hg clone http://hg.logilab.org/cubicweb # development branch
 
-Then a practical way to get many of CubicWeb's dependencies and a nice set
-of base cubes is to run the `clone_deps.py` script located in
-`cubicweb/bin/`::
+To get many of CubicWeb's dependencies and a nice set of base cubes, run the
+`clone_deps.py` script located in `cubicweb/bin/`::
 
   python cubicweb/bin/clone_deps.py
 
@@ -258,12 +247,10 @@
 
   In every cloned repositories, a `hg tags` will display a list of
   tags in reverse chronological order. One reasonnable option is to go to a
-  taged version: the latest published version or example, as done by
+  tagged version: the latest published version or example, as done by
   the `clone_deps` script)::
 
-   hg update cubicweb-debian-version-3.10.7-1
+   hg update cubicweb-version-3.12.2
 
 Make sure you also have all the :ref:`InstallDependencies`.
 
-.. _`pip`: http://pip.openplans.org/
-.. _`virtualenv`: http://virtualenv.openplans.org/