--- a/doc/book/en/A02a-create-cube.en.txt	Wed Apr 22 14:14:11 2009 -0700
+++ b/doc/book/en/A02a-create-cube.en.txt	Wed Apr 22 21:43:06 2009 -0700
@@ -24,8 +24,6 @@
 
 ::
 
-  from cubicweb.schema import format_constraint
-  
   class Blog(EntityType):
     title = String(maxsize=50, required=True)
     description = String()
@@ -63,9 +61,7 @@
   cubicweb-ctl create blog blogdemo
 
 
-This command will create a directory ``~/etc/cubicweb.d/blogdemo``
-which will contain all the configuration files required to start
-you web application.
+This command will create the corresponding database and initialize it.
 
 Welcome to your web application
 -------------------------------

--- a/doc/book/en/B0040-migration.en.txt	Wed Apr 22 14:14:11 2009 -0700
+++ b/doc/book/en/B0040-migration.en.txt	Wed Apr 22 21:43:06 2009 -0700
@@ -208,3 +208,6 @@
 * `add_entity_type_table(etype, commit=True)`
 * `add_relation_type_table(rtype, commit=True)`
 * `uninline_relation(rtype, commit=True)`
+
+
+[FIXME] Add explanation on how to use cubicweb-ctl shell

--- a/doc/book/en/B1090-internationalization.en.txt	Wed Apr 22 14:14:11 2009 -0700
+++ b/doc/book/en/B1090-internationalization.en.txt	Wed Apr 22 21:43:06 2009 -0700
@@ -1,9 +1,9 @@
 .. -*- coding: utf-8 -*-
 
-.. _internationalization:
+.. _internationalisation:
 
 
-Internationalization
+Internationalisation
 ====================
 
 Cubicweb fully supports the internalization of it's content and interface.

--- a/doc/book/en/C011-installation.en.txt	Wed Apr 22 14:14:11 2009 -0700
+++ b/doc/book/en/C011-installation.en.txt	Wed Apr 22 21:43:06 2009 -0700
@@ -11,8 +11,11 @@
 `CubicWeb` is packaged for Debian and Ubuntu, but can be installed from source
 using a tarball or the Mercurial version control system.
 
+.. _DebianInstallation:
+
 Debian and Ubuntu packages
 ```````````````````````````
+
 Depending on the distribution you are using, add the appropriate line to your list
 of sources (for example by editing ``/etc/apt/sources.list``).
 
@@ -32,8 +35,7 @@
 You can now install the required packages with the following command::
 
   apt-get update 
-  apt-get install cubicweb
-  apt-get install cubicweb-dev
+  apt-get install cubicweb cubicweb-dev
 
 `cubicweb` installs the framework itself, allowing you to create
 new applications.
@@ -117,15 +119,15 @@
 
 .. note::
     If you already have an existing cluster and postgres server
-    running, you do not require to execute the initilization step
+    running, you do not need to execute the initilization step
     of your Postgres database.
 
-* First you have to initialize the database Postgres with the command ``initdb``.
+* First, initialize the database Postgres with the command ``initdb``.
   ::
 
     $ initdb -D /path/to/pgsql
 
-  Once initialized, you can launch the database server Postgres 
+  Once initialized, start the database server Postgres 
   with the command::
   
     $ postgres -D /path/to/psql
@@ -146,22 +148,14 @@
     
     $ su
     $ su - postgres
-    $ createuser -s username
+    $ createuser -s -P username
 
-  If created with the options -P (for password prompt, 
-  ``createuser -s -P username``), the password will be encrypted with
+  The option `-P` (for password prompt), will encrypt the password with
   the method set in the configuration file ``pg_hba.conf``. 
-  If you do not use this option, then the default value will be null
-  and this require to set the password in the database itself.
-  To do so: ::
+  If you do not use this option `-P`, then the default value will be null
+  and you will need to set it with::
     
-    $ su 
-    $ su - postgres
-    $ psql
-
-  And then execute de following query::
-    
-    ALTER USER username WITH PASSWORD `password`
+    $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql"
 
   This login/password will be requested when you will create an
   instance with `cubicweb-ctl create` to initialize the database of
@@ -194,12 +188,10 @@
 ------------------
 
 If you use Pyro, it is required to have a name server Pyro running on your
-network (by default it is identified by a broadcast request).
+network (by default it is detected by a broadcast request).
 
 To do so, you need to :
 
-* launch the server manually before starting cubicweb with `pyro-ns`
-
 * launch the server manually before starting cubicweb as a server with
   `pyro-nsd start`
 

--- a/doc/book/en/C012-create-instance.en.txt	Wed Apr 22 14:14:11 2009 -0700
+++ b/doc/book/en/C012-create-instance.en.txt	Wed Apr 22 21:43:06 2009 -0700
@@ -8,7 +8,7 @@
 
 A `CubicWeb` instance is a directory in ``~/etc/cubicweb.d``
 which enables us to run a web application. An instance is based on
-one or more cubes.
+a cube.
 
 An instance is a container that refers to cubes and configuration 
 parameters for your web application.

--- a/doc/book/en/C013-cubicweb-ctl.en.txt	Wed Apr 22 14:14:11 2009 -0700
+++ b/doc/book/en/C013-cubicweb-ctl.en.txt	Wed Apr 22 21:43:06 2009 -0700
@@ -52,8 +52,8 @@
 
 For more details, please see :ref:`gaecontents` .
 
-Commands to launch instance
----------------------------
+Commands to control instances
+-----------------------------
 * ``start``, starts one or more or all instances
 * ``stop``, stops one or more or all instances
 * ``restart``, restarts one or more or all instances
@@ -64,7 +64,6 @@
 * ``upgrade``, launches the existing instances migration when a new version
   of `CubicWeb` or the cubes installed is available
 * ``shell``, opens a migration shell for manual maintenance of the instance
-  (see :ref:`cubicweb-ctl-shell` for more details)
 * ``db-dump``, creates a dump of the system database
 * ``db-restore``, restores a dump of the system database
 * ``db-check``, checks data integrity of an instance. If the automatic correction
@@ -79,7 +78,7 @@
 * ``i18ncompile``, recompiles the messages catalogs of an instance. 
   This is automatically done while upgrading.
 
-Cf :ref:`Internationalisation`.
+See also chapter :ref:`internationalisation`.
 
 Other commands
 --------------
@@ -88,23 +87,6 @@
 * ``delete``, deletes an instance (configuration files and database)
 
 
-.. _cubicweb-ctl-shell:
-
-``cubicweb-ctl shell`` addon
-----------------------------
-
-This migration shell provides an interactive interface to all
-the migrations functions described in the chapter :ref:`migration`.
-
-Usage
-`````
-::
-  
-  ``cubicweb-ctl shell myapp``
-
-Examples
---------
-
 Create an instance from an existing cube
 ````````````````````````````````````````
 

--- a/doc/book/en/D000-annex.en.txt	Wed Apr 22 14:14:11 2009 -0700
+++ b/doc/book/en/D000-annex.en.txt	Wed Apr 22 21:43:06 2009 -0700
@@ -12,9 +12,9 @@
    :maxdepth: 1
 
    D010-faq.en.txt
+   D070-cookbook.en.txt
    D020-api-reference.en.txt
    D030-architecture.en.txt
    D040-modules-stdlib.en.txt
    D050-modules-cbw-api.en.txt
    D060-mercurial.en.txt
-   D070-cookbook.en.txt

--- a/doc/book/en/D010-faq.en.txt	Wed Apr 22 14:14:11 2009 -0700
+++ b/doc/book/en/D010-faq.en.txt	Wed Apr 22 21:43:06 2009 -0700
@@ -135,12 +135,6 @@
   `AppRsetObject` instances are selected on a request and a result
   set. `AppObject` instances are directly selected by id.
 
-HOW TO
-======
-
-[TO COMPLETE]
-
-
 * How to update a database after a schema modification?
 
   It depends on what has been modified in the schema.

--- a/doc/book/en/index.txt	Wed Apr 22 14:14:11 2009 -0700
+++ b/doc/book/en/index.txt	Wed Apr 22 21:43:06 2009 -0700
@@ -25,7 +25,7 @@
 for semantic web application development that promotes quality, reusability and
 efficiency.
 
-The unbeliever will read the :ref:`Overview`.
+The unbeliever will read the :ref:`Tutorial`.
 
 The hacker will join development at the forge_.