--- a/doc/book/en/03-01-installation.en.txt	Tue Nov 18 11:51:22 2008 -0800
+++ b/doc/book/en/03-01-installation.en.txt	Tue Nov 18 15:06:33 2008 -0800
@@ -3,81 +3,90 @@
 Installation
 ============
 
-Installation de Cubicweb et de ses dépendances
-----------------------------------------------
+Installation of `Cubicweb` and its dependancies
+-----------------------------------------------
 
-`CubicWeb` est disponible via un entrepôt Mercurial utilisant l'extension forest.
-Vous devez donc dans un premier temps vous assurer que Mercurial est bien installé
-et que vous avez l'extension forest.
+`CubicWeb` is available as a Mercurial repository using the forest extension.
+First make sure Mercurial is installed and that the forest extension is
+available.
 
-Installation de Mercurial
-`````````````````````````
-Veuillez vous référer a la documentation en ligne du projet Mercurial_.
+Mercurial installation
+``````````````````````
 
+Please refer to the project online documentation Mercurial_.
 .. _Mercurial: http://www.selenic.com/mercurial/wiki/
 
-Installation de l'extension forest
-``````````````````````````````````
-Dans un premier temps, récupérez une copie des sources via: http://hg.akoha.org/hgforest/.
-Ensuite, ajoutez a votre ``~/.hgrc`` les lignes suivantes ::
+We also provide in this book a quick guide on how to use
+Mercurial (:ref:`Mercurial`).
+
+
+Installation of the forest extension
+````````````````````````````````````
+
+Set up the forest extension by getting a copy of the sources 
+from http://hg.akoha.org/hgforest/ and adding the following 
+lines to your ``~/.hgrc``: ::
 
    [extensions]
    hgext.forest=
    # or, if forest.py is not in the hgext dir:
    # forest=/path/to/forest.py
 
-Récupération des sources
-````````````````````````
-Clonez la foret dans votre répertoire de travail. 
+Get `CubicWeb` source code
+``````````````````````````
+
+Clone the forest in you working directory.
 
 ::
 
   hg fclone http://www.logilab.org/hg/forests/cubicweb
 
 .. note:: 
-  Nous vous recommandons de créer un lien symbolique vers l'outil ``cubicweb-ctl``
-  que vous allez etre amené a utiliser.
+  We recommand you to create a symbolic link to the command ``cubicweb-ctl``
+  as you will use it pretty often.
 
   ::
     
     $ ln -s /path/to/forest/cubicweb/bin/cubicweb-ctl ~/bin
 
-Installation de Postgres
-````````````````````````
-Veuillez vous référer a la documentation en ligne du projet Postgres_.
+Postgres installation
+`````````````````````
+
+Please refer to the project online documentation Postgres_.
 
 .. _Postgres: http://www.postgresql.org/
 
-Vous allez devoir installer les trois paquets suivants: `postgres-8.3`,
+You need to install the three following packages: `postgres-8.3`,
 `postgres-contrib-8.3` and `postgresql-plpython-8.3`.
 
 
-On pourra ensuite installer les paquets suivants :
+Then you can install:
 
-* `pyro` si vous voulez que l'entrepôt soit accessible via Pyro ou si le client
-  et le serveur ne sont pas sur la même machine (auquel cas il faut installer ce
-  paquet sur les machines clientes et serveur)
+* `pyro` if you wish the repository is accessible through Pyro
+  or if the client and the server are not running on the same machine
+  (in suche case the packages will have to be isntalled on both
+  machines)
 
-* `python-ldap` si vous voulez utiliser une source ldap sur le serveur
-
+* `python-ldap` if you plan to use a LDAP source on the server
 
 .. _ConfigurationEnv:
 
-Configuration de l'environnement
---------------------------------
+Environment configuration
+-------------------------
 
 [FIXME]
 Ces variables ne sont plus requises pour le bon fonctionnement de `CubicWeb`, non?
 A part rajouter la foret dans le PYTHONPATH, rien de plus ne doit etre fait?
 
-Mettez à jour votre variable d'environemment PYTHONPATH afin d'y ajouter
-le chemin d'acces a votre foret ``cubicweb``. 
+Update the environment variable PYTHONPATH to add to it the path to
+the forest ``cubicweb``.
 
-Ajouter les lignes suivantes à son `.bashrc` ou `.bash_profile` pour configurer
-votre environnement de développement ::
+Add the following lines to either `.bashrc` or `.bash_profile` to configure
+your development environment ::
   
   export PYTHONPATH=/full/path/to/cubicweb-forest
   
+  //deprecated??
   export ERUDI_REGISTRY=~/etc/erudi.d/
   export ERUDI_TEMPLATES=~/hg/
   export ERUDI_RUNTIME=/tmp/
@@ -88,63 +97,63 @@
 
 .. _ConfigurationPostgres:
 
-Configuration Postgres
+Postgres configuration
 ----------------------
-* Tout d'abord vous devez initialiser votre base de données Postgres via la
-  commande ``initidb``.
+
+* First you have to initialize the database Postgres with the command ``initdb``.
   ::
 
     $ initdb -D /path/to/pgsql
 
-  Une fois ces paquets installés vous pouvez lancer votre server de base de 
-  données Postgres avec la commande suivante: ::
+  Once initialized, you can launch the database server Postgres 
+  with the command: ::
   
     $ postgres -D /path/to/psql
 
-  Si vous ne pouvez exécuter cette commande pour des raisons de permissions
-  assurez-vous que votre utilisateur a droit d'écriture sur les la base de données.
-
+  If you cannot execute this command due to permission issues, please
+  make sure that your username has write access on the database.
   ::
  
     $ chown username /path/to/pgsql
 
-* Création d'un super utilisateur pour la création d'instance (**root**) ::
+* Create a superuser for `CubicWeb` instance (**root**) ::
 
     createuser -s username
 
-  Initialisez le mot de passe de ce superutilisateur ``username`` via
-  ``su - postgres`` puis ``psql``.
+  Initialize the password of the superuser you juste created with 
+  ``su - postgres`` and ``psql``.
 
-  Un mot de passe de connection pour cet utilisateur vous sera demandé. Il
-  faudra utiliser ce login / mot de passe à la création d'instance via
-  `cubicweb-ctl`
+  This password will be asked to you later on where you will create an
+  instance with `cubicweb-ctl create`
 
 [XXX]
 Est-ce que ces etapes sont vraiment necessaires? 
 sand : lors de l'installation de ma bdd cela n'a pas ete fait
 et il semble que tout aille bien. Doit etre verifie avec les experts.
 
-* installation des extensions pour l'index plein texte ::
+* installation of plain-text index extension ::
 
-    cat /usr/share/postgresql/8.1/contrib/tsearch2.sql | psql -U pgadmin template1
+    cat /usr/share/postgresql/8.3/contrib/tsearch2.sql | psql -U username template1
 
-* installation du langage plpythonu par défaut ::
+* installation of plpythonu language by default ::
 
     createlang -U pgadmin plpythonu template1
 
 
-Configuration Pyro
+Pyro configuration
 ------------------
-Si vous utilisez Pyro, il est nécessaire d'avoir un serveur de noms Pyro
-tournant sur votre réseau (par défaut celui-ci est repéré par une requête
-broadcast). Pour cela il faut soit :
+
+If you use Pyro, it is required to have a name server Pyro runing on your
+network (by default it is identified by a broadcast request).
+
+To do so, you need to :
 
-* le lancer à la main avant le démarrage de erudi avec la commande `pyro-ns`
+* launch the server manually before starting cubicweb with `pyro-ns`
 
-* le lancer à la main avant le démarrage de erudi sous forme d'un serveur avec
-  la commande `pyro-nsd start`
+* launch the server manually before starting cubicweb as a server with
+  `pyro-nsd start`
 
-* éditer le fichier */etc/default/pyro-nsd* pour que le serveur de nom pyro soit
-  lancé automatiquement au démarrage de la machine
+* edit the file ``/etc/default/pyro-nsd`` so that the name server pyro
+  will be launched automatically when the macine fire up
 
 

--- a/doc/book/en/03-02-create-instance.en.txt	Tue Nov 18 11:51:22 2008 -0800
+++ b/doc/book/en/03-02-create-instance.en.txt	Tue Nov 18 15:06:33 2008 -0800
@@ -1,127 +1,124 @@
 .. -*- coding: utf-8 -*-
 
-===================================
-Creation de votre premiere instance
-===================================
+===============================
+Creation of your first instance
+===============================
+
+What is an instance?
+====================
+
+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.
+
+An instance is a container that refers to cubes and configuration 
+parameters for your web application.
+
+We recommand not to define schema, entities or views in the instance
+file system itself but in the cube, in order to maintain re-usability of
+entities and their views. We strongly recommand to develop cubes which
+could be used in other instances (modular approach).
 
 
-Qu'est-ce qu'une instance?
-==========================
+What is a cube?
+===============
 
-Une instance CubicWeb consiste en un dossier situe dans ``~/etc/cubicweb.d``
-qui permettra de lancer une application web. Une instance est cree a partir
-d'un ou plusieurs cubes.
-
-Nous recommandons de ne pas definir de schema, entites ou vues dans l'instance 
-meme si cela est possible dans un but de re-utilisabilite des entities et de leurs
-vues. Nous conseillons plutot de developper des cubes qui pourront par la suite
-etre utilises dans d'autres instances (approche modulaire).
+A cube defines entities, their views, their schems and workflows
+in an independant directory located in ``/path/to/forest/cubicweb/cubes/``.
 
-L'instance n'est qu'un conteneur referrant a des cubes et a des parametres
-des configuration de l'application web.
-
-Qu'est-ce qu'un cube?
-=====================
+When an instance is created, you list one or more cubes that your instance
+will use. Use a cube means having the entities defined in your cube's schema
+available in your instance as well as their views and workflows.
 
-Un cube definit des entities, leur vues, leur schemas et leur workflow 
-dans un repertoire independant situe dans ``/path/to/forest/cubicweb/cubes/``.
-
-Lors de la creation d'une instance, vous avez la possibilite de lister
-le ou les cubes que votre instance va utiliser. Utiliser un cube signifie
-avoir a disposition dans votre instance les entites definies dans le schema
-de votre cube ainsi que les vues et les workflows.
+.. note::
+   The commands used below are more detailled in the section dedicated to 
+   :ref:`cubicweb-ctl`.
 
 
-.. note::
-   Les commandes utilisees ci-apres sont detaillees dans la section
-   dediee a :ref:`cubicweb-ctl`.
-
+Create a cube
+=============
 
-Création d'un cube
-==================
-
-Commençons par créer un squelette qui nous servira de base au développement de
-notre cube ou application ::
+Let's start by creating the cube environment in which we will develop ::
 
   cd ~/hg
 
-  cubicweb-ctl newtemplate moncube
+  cubicweb-ctl newcube mycube
 
-  # répondre aux questions
+  # answer questions 
   hg init moncube
-  cd moncube
+  cd mycube
   hg add .
   hg ci
 
-A partir de là si tout va bien, votre cube devrait être affiché par
-`cubicweb-ctl list` dans la section *Available components*, si ce n'est pas le cas
-revoir la section :ref:`ConfigurationEnv`.
+If all went well, you should see the cube you just create in the list
+returned by `cubicweb-ctl list` in the section *Available components*,
+and if it is not the case please refer to :ref:`ConfigurationEnv`.
+
+To use a cube, you have to list it in the variable ``__use__``
+of the file ``__pkginfo__.py`` of the instance.
+This variable is used for the instance packaging (dependencies
+handled by system utility tools such as APT) and the usable cubes
+at the time the base is created (import_erschema('MyCube') will
+not properly work otherwise).
+
+Instance creation
+=================
+
+Now that we created our cube, we can create an instance to view our
+application in a web browser. To do so we will use a `all-in-on` 
+configuration to simplify things ::
+
+  cubicweb-ctl create -c all-in-one mycube myinstance
+
+.. note::
+  Please note that we created a new cube for a demo purpose but
+  you could have use an existing cube available in our standard library
+  such as blog or person by example.
+
+A serie of questions will be prompted to you, the default answer is usually
+sufficient. You can anyway modify the configuration later on by editing
+configuration files. When a user/psswd is requested to access the database
+please use the login you create at the time you configured the database
+(:ref:`ConfigurationPostgres`).
+
+It is important to distinguish here the user used to access the database and
+the user used to login to the cubicweb application. When a `CubicWeb` application
+starts, it uses the login/psswd for the database to get the schema and handle
+low transaction [FIXME - bas niveau]. But, when ``cubicweb-ctl create`` asks for
+a manager login/psswd of `CubicWeb`, it refers to an application user you will
+use during the development to administrate your web application. It will be 
+possible, later on, to create others users for your final web application.
+
+When this command is completed, the definition of your instance is
+located in *~/etc/cubicweb.d/moninstance/*. To launch it, you just type ::
+
+  cubicweb-ctl start -D myinstance
+
+The option `-D` specify the *debug mode* : the instance is not running in
+server mode and does not disconnect from the termnial, which simplifies debugging
+in case the instance is not properly launched. You can see how it looks by
+visiting the URL `http://localhost:8080` (the port number depends of your 
+configuration). To login, please use the cubicweb administrator login/psswd you 
+defined when you created the instance.
+
+To shutdown the instance, Crtl-C in the terminal window is enough.
+If you did not use the option `-D`, then type ::
+
+  cubicweb-ctl stop myinstance
+
+This is it! All is settled down to start developping your data model...
 
 
-Pour utiliser un cube, il faut le mentionner dans la variable
-__use__ du fichier __pkginfo__ de l'application. Cette variable
-contrôle à la fois le packaging de l'application (dépendances gérées
-par les utilitaires système comme les outils APT) et les composants
-effectivement utilisables lors de la création de la base
-(import_erschema('Moncomposant') ne fonctionne pas sinon).
-
-Création d'une instance de développement
-========================================
-
-Maintenant que nous avons notre squelette de modèle, on peut en créer une
-instance afin de voir ce que tout ça donne dans un simple navigateur web.
-Nous allons utiliser une configuration `all-in-one` afin de simplifier les
-choses ::
+Usage of `cubicweb-liveserver`
+------------------------------
 
-  cubicweb-ctl create -c all-in-one moncube moninstance
-
-Une série de questions vont être posées, la réponse par défaut est généralement
-suffisante. Vous pourrez de toute façon modifier la configuration par la suite
-en éditant les fichiers générés. Lorsqu'un login/mot de passe d'accès au sgbd
-vous est demandé, il est recommandé d'utiliser l'utilisateur créé lors de la
-:ref:`ConfigurationPostgres`.
-
-Il est important de distinguer ici l'utilisateur utilisé pour accéder au sgbd,
-et l'utilisateur utilisé pour s'authentifier dans l'application cubicweb. Lorsque
-l'application cubicweb démarre, elle utilise le login/mot de passe sgdb pour
-récupérer le schéma et gérer les transactions bas-niveau. En revanche, lorsque
-`cubicweb-ctl create` vous demande un login/mot de passe `manager` pour cubicweb, il
-s'agit d'un utilisateur qui sera créé dans l'application `cubicweb` pour pouvoir
-s'y connecter dans un premier temps et l'administrer. Il sera par la suite possible
-de créer des utilisateurs différents pour l'application.
+To quickly test a new cube, you can also use the script `cubicweb-liveserver`
+which allows to create an application in memory (use of SQLite database by 
+default) and make it accessible through a web server ::
 
-A l'issue de cette commande, la définition de votre instance se trouve dans
-*~/etc/cubicweb.d/moninstance/*. Pour la lancer, il suffit de taper ::
-
-  cubicweb-ctl start -D moninstance
-
-L'option `-D` indique le *debug mode* : l'instance ne passe pas en mode serveur
-et ne se déconnecte pas du terminal, ce qui simplifie le dépannage en cas de non
-démarrage de l'instance. Vous pouvez ensuite allez voir ce que ça donne en
-pointant votre navigateur sur l'url `http://localhost:8080` (le n° de port
-dépend de votre configuration). Pour vous authentifier vous pouvez utiliser le
-login/mot de passe administrateur que vous avez spécifié lors de la création de
-l'instance.
-
-Pour arrêter l'instance, un Ctrl-C dans la fenêtre où vous l'avez lancé
-suffit. Si l'option `-D` a été omise, il faut taper ::
-
-  cubicweb-ctl stop moninstance
+  cubicweb-ctl live-server mycube
 
-Voilà, tout est en place pour démarrer le développement du modèle...
-
-
-Utilisation de cubicweb-liveserver
-----------------------------------
+or by using an existing database (SQLite or Postgres)::
 
-Afin de tester rapidement un nouveau cube, on peut également
-utiliser le script `cubicweb-liveserver` qui permet de créer une
-application en mémoire (utilisant une base de données SQLite par
-défaut) et la rendre accessible via un serveur web::
+  cubicweb-ctl live-server -s myfile_sources mycube
 
-  cubicweb-ctl live-server moncomposant
-
-ou bien, pour utiliser une base de données existante (SQLite ou postgres)::
-
-  cubicweb-ctl live-server -s monfichier_sources moncomposant
-

--- a/doc/book/en/03-04-mercurial.en.txt	Tue Nov 18 11:51:22 2008 -0800
+++ b/doc/book/en/03-04-mercurial.en.txt	Tue Nov 18 15:06:33 2008 -0800
@@ -1,5 +1,7 @@
 .. -*- coding: utf-8 -*-
 
+.. _Mercurial:
+
 Présentation de Mercurial
 -------------------------
 

--- a/doc/book/en/03-setup.en.txt	Tue Nov 18 11:51:22 2008 -0800
+++ b/doc/book/en/03-setup.en.txt	Tue Nov 18 15:06:33 2008 -0800
@@ -2,8 +2,8 @@
 
 .. _MiseEnPlaceEnv:
 
-Installation et mise en place d'un environnement `CubicWeb`
-===========================================================
+Installation and set-up of a `CubicWeb` environment
+===================================================
 
 .. toctree::
    :maxdepth: 1