--- a/doc/book/en/A030-foundation.en.txt	Mon Dec 29 11:16:49 2008 -0800
+++ b/doc/book/en/A030-foundation.en.txt	Mon Dec 29 13:50:42 2008 -0800
@@ -29,6 +29,6 @@
 http://collections.musees-haute-normandie.fr/collections/), etc.
 
 In 2008, `CubicWeb` was ported for a new type of source : the datastore 
-from GoogleAppEngine_.
+from `GoogleAppEngine`_.
 
 .. include:: A03a-concepts.en.txt

--- a/doc/book/en/A03a-concepts.en.txt	Mon Dec 29 11:16:49 2008 -0800
+++ b/doc/book/en/A03a-concepts.en.txt	Mon Dec 29 13:50:42 2008 -0800
@@ -3,10 +3,21 @@
 Concepts
 --------
 
+This section aims to provide you the keys of success with `CubicWeb`
+by clarifying the terms specific to our framework.
+
 Global architecture
 ~~~~~~~~~~~~~~~~~~~
 .. image:: images/archi_globale.en.png
 
+
+`CubicWeb` framework is a server/client application framework. Those two 
+parties communicates through RQL (`CubicWeb` query language implementation)
+and ResultSet (which will be explained in :ref:`TermsVocabulary`).
+
+The server manages all interactions with sources.
+
+
 .. note::
   For real, the client and server sides are integrated in the same
   process and interact directly, without the needs for distants
@@ -20,6 +31,11 @@
 Terms and vocabulary
 ~~~~~~~~~~~~~~~~~~~~~
 
+`CubicWeb` defines its own terminology. To make sure there is no confusion
+while reading this book, we strongly recommand you take time to go through
+the following definitions that are the basics to understand while
+developing with `CubicWeb`.
+
 *schema*
   The schema defines the data model of an application based on entities
   and relations, modeled with a comprehensive language made of Python
@@ -27,13 +43,13 @@
   of an application. It is initially defined in the file system and is
   stored in the database at the time an instance is created. `CubicWeb`
   provides a certain number of system entities included automatically as
-  it is necessarry for the core of `CubicWeb` and a library of
-  cubes that can be explicitely included if necessary.
-
+  it is necessary for the core of `CubicWeb` and a library of
+  cubes (which defined application entities) that can be explicitely 
+  included if necessary.
 
 *entity type*
-  An entity is a set of attributes; the essential attribute of
-  an entity is its key, named eid
+  An entity type is a set of attributes; the essential attribute of
+  an entity is its key, named eid.
 
 *relation type*
   Entities are linked to each others by relations. In `CubicWeb`
@@ -51,8 +67,8 @@
   to an entity attribute.
 
 *relation definition*
-  a relation definition is a 3-uple (subject entity type, relation type, object entity type),
-  with an associated set of property such as cardinality, constraints...
+  A relation definition is a 3-uple (subject entity type, relation type, object
+  entity type), with an associated set of property such as cardinality, constraints...
   
 *repository*
   This is the RQL server side of `CubicWeb`. Be carefull not to get
@@ -76,7 +92,7 @@
 *cube*
   A cube is a model grouping one or multiple data types and/or views
   to provide a specific functionnality or a complete `CubicWeb` application
-  potentially using other cubes. The available subes are located in the file
+  potentially using other cubes. The available cubes are located in the file
   system at `/path/to/forest/cubicweb/cubes` for a Mercurial forest installation,
   for a debian packages installation they will be located in 
   `/usr/share/cubicweb/cubes`.
@@ -86,13 +102,13 @@
   cubes.
 
 *instance*
-  An instance is a specific installation of a cube. All the required 
-  configuration files necessarry for the well being of your web application
+  An instance is a specific installation of one or multiple cubes. All the required 
+  configuration files necessary for the well being of your web application
   are grouped in an instance. This will refer to the cube(s) your application
   is based on.
   For example logilab.org and our intranet are two instances of a single
   cube jpl, developped internally.
-  The instances are defined in the directory `~/etc/cubicweb.d`.
+  The instances are defined in the directory `/etc/cubicweb.d`.
 
 *application*
   The term application is sometime used to talk about an instance
@@ -102,7 +118,7 @@
 
 *result set*
   This object contains the results of an RQL query sent to the source
-  and information on the query.
+  and informations on the query.
 
 *Pyro*
   `Python Remote Object`_, distributed objects system similar to Java's RMI
@@ -127,7 +143,10 @@
   the same identifier.
 
 *rql*
- XXX
+ Relation Query Language in order to empasize the way of browsing relations.
+ This query language is inspired by SQL but is highest level, its implementation
+ generates SQL.
+
  
 .. _`Python Remote Object`: http://pyro.sourceforge.net/
 .. _`yams`: http://www.logilab.org/project/yams/
@@ -137,9 +156,9 @@
 ~~~~~~~~~~~~~~~~~
 
 The engine in `CubicWeb` is a set of classes managing a set of objects loaded
-dynamically at the startup of `CubicWeb` (*appobjects*). Those dynamics objects, based on the schema
-or the library, are building the final application. The differents dymanic components are
-for example:
+dynamically at the startup of `CubicWeb` (*appobjects*). Those dynamics objects,
+based on the schema or the library, are building the final application.
+The differents dymanic components are for example:
 
 * client and server side
 
@@ -174,9 +193,9 @@
 API Python/RQL
 ~~~~~~~~~~~~~~
 
-Inspired from the standard db-api, with a Connection object having the methods
-cursor, rollback and commit essentially. The most important method is
-the `execute` method of a cursor :
+The Python API developped to interface with RQL is inspired from the standard db-api,
+with a Connection object having the methods cursor, rollback and commit essentially. 
+The most important method is the `execute` method of a cursor :
 
 `execute(rqlstring, args=None, eid_key=None, build_descr=True)`
 
@@ -203,11 +222,11 @@
 The `Request` class (`cubicweb.web`)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A request instance is created when an HTPP request is sent to the web server.
+A request instance is created when an HTTP request is sent to the web server.
 It contains informations such as forms parameters, user authenticated, etc.
 
 **Globally, a request represents a user query, either through HTTP or not
-(we also talk about RQL queries on the server side for example)**
+(we also talk about RQL queries on the server side for example).**
 
 An instance of `Request` has the following attributes:
 
@@ -219,7 +238,7 @@
 But also:
 
 :Session data handling:
-  * `session_data()`, returns a dictinnary containing all the session data
+  * `session_data()`, returns a dictionnary containing all the session data
   * `get_session_data(key, default=None)`, returns a value associated to the given
     key or the value `default` if the key is not defined
   * `set_session_data(key, value)`, assign a value to a key
@@ -232,7 +251,7 @@
   * `set_cookie(cookie, key, maxage=300)`, adds a header HTTP `Set-Cookie`,
     with a minimal 5 minutes length of duration by default (`maxage` = None
     returns a *session* cookie which will expire when the user closes the browser
-    window
+    window)
   * `remove_cookie(cookie, key)`, forces a value to expire
 
 :URL handling:
@@ -252,7 +271,7 @@
   * dictionnary `data` to store data to share informations between components
     *while a request is executed*
 
-Please note down that this class is abstract and that a concrete implementation
+Please note that this class is abstract and that a concrete implementation
 will be provided by the *frontend* web used (in particular *twisted* as of
 today). For the views or others that are executed on the server side,
 most of the interface of `Request` is defined in the session associated
@@ -272,7 +291,7 @@
   to take care of the register, only the identifier `id`.
 
 We can find a certain number of attributes and methods defined in this class 
-and so common to all the application objects:
+and common to all the application objects.
 
 At the recording, the following attributes are dynamically added to
 the *subclasses*:
@@ -284,13 +303,13 @@
 We also find on instances, the following attributes:
 
 * `req`, `Request` instance
-* `rset`, the *result set* associated to the object if necessarry
+* `rset`, the *result set* associated to the object if necessary
 * `cursor`, rql cursor on the session
 
 
 :URL handling:
   * `build_url(method=None, **kwargs)`, returns an absolute URL based on
-    the given arguments. The *controller* supposed to handle the response
+    the given arguments. The *controller* supposed to handle the response,
     can be specified through the special parameter `method` (the connection
     is theoretically done automatically :).
 
@@ -314,16 +333,18 @@
     also call the method `complete()` on the entity before returning it
 
 :Data formatting:
-  * `format_date(date, date_format=None, time=False)`
-  * `format_time(time)`
+  * `format_date(date, date_format=None, time=False)` returns a string for a 
+    mx date time according to application's configuration
+  * `format_time(time)` returns a string for a mx date time according to
+    application's configuration
 
 :And more...:
 
   * `external_resource(rid, default=_MARKER)`, access to a value defined in the
     configuration file `external_resource`
     
-  * `tal_render(template, variables)`, 
-
+  * `tal_render(template, variables)`, renders a precompiled page template with 
+    variables in the given dictionary as context
 
 .. note::
   When we inherit from `AppObject` (even not directly), you *always* have to use
@@ -453,7 +474,8 @@
 
 * the file ``__pkginfo__.py``
 * the schema definition
-  XXX false, we may want to have cubes which are only adding a service, no persistent data (eg embeding for instance)
+  XXX false, we may want to have cubes which are only adding a service, 
+  no persistent data (eg embeding for instance)
 
 
 Standard library

--- a/doc/book/en/B0011-schema-stdlib.en.txt	Mon Dec 29 11:16:49 2008 -0800
+++ b/doc/book/en/B0011-schema-stdlib.en.txt	Mon Dec 29 13:50:42 2008 -0800
@@ -5,7 +5,7 @@
 
 The library defines a set of entities schemas that are required by the system
 or commonly used in `CubicWeb` applications.
-Of course, you can extend those schemas if necessarry.
+Of course, you can extend those schemas if necessary.
 
 
 System schemas

--- a/doc/book/en/B0012-schema-definition.en.txt	Mon Dec 29 11:16:49 2008 -0800
+++ b/doc/book/en/B0012-schema-definition.en.txt	Mon Dec 29 13:50:42 2008 -0800
@@ -9,7 +9,7 @@
 for example ::
 
   class Personne(EntityType):
-    """A person with the properties and the relations necessarry for my
+    """A person with the properties and the relations necessary for my
     application"""
 
     last_name = String(required=True, fulltextindexed=True)
@@ -35,7 +35,7 @@
   - `created_by` (`EUser`) (which user created the entity)
   
   - `owned_by` (`EUser`) (who does the entity belongs to, by default the 
-     creator but not necessarry and it could have multiple owners)
+     creator but not necessary and it could have multiple owners)
      
   - `is` (`EEType`)
 

--- a/doc/book/en/B0030-data-as-objects.en.txt	Mon Dec 29 11:16:49 2008 -0800
+++ b/doc/book/en/B0030-data-as-objects.en.txt	Mon Dec 29 13:50:42 2008 -0800
@@ -49,7 +49,7 @@
 
   * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, 
     returns a string enabling the display of an attribute value in a given format
-    (the value is automatically recovered if necessarry)
+    (the value is automatically recovered if necessary)
 
   * `display_name(form='')`, returns a string to display the entity type by 
     specifying the preferred form (`plural` for a plural form)
@@ -129,7 +129,7 @@
 
 It is possible to simplify this dictionnary:
 
-* if we want to specifiy a single marker, it is not necessarry to
+* if we want to specifiy a single marker, it is not necessary to
   use a tuple as the value, the marker by itself (characters string)
   is enough
 * if we only care about a single type of relation and not about the target

--- a/doc/book/en/B0031-define-entities.en.txt	Mon Dec 29 11:16:49 2008 -0800
+++ b/doc/book/en/B0031-define-entities.en.txt	Mon Dec 29 13:50:42 2008 -0800
@@ -69,7 +69,7 @@
 * `generated`, indicates that an attribute is dynamically computed
   or other,  and that it should not be displayed in the editing form.
 
-If necessarry, it is possible to overwrite the method  
+If necessary, it is possible to overwrite the method  
 `relation_category(rtype, x='subject')` to dynamically compute
 a relation editing category.
 
@@ -92,7 +92,7 @@
   entity and link to it automatically
 
 
-If necessarry, it is possible to overwrite the method  
+If necessary, it is possible to overwrite the method  
 `relation_mode(rtype, targettype, x='subject')` to dynamically
 compute a relation creation category.
 

--- a/doc/book/en/B1020-define-views.en.txt	Mon Dec 29 11:16:49 2008 -0800
+++ b/doc/book/en/B1020-define-views.en.txt	Mon Dec 29 13:50:42 2008 -0800
@@ -180,7 +180,7 @@
 
 A *template* is responsible for:
 
-1. executing RQL query of data to render if necessarry
+1. executing RQL query of data to render if necessary
 2. identifying the view to use to render data if it is not specified
 3. composing the HTML page to return
 

--- a/doc/book/en/B1030-form-management.en.txt	Mon Dec 29 11:16:49 2008 -0800
+++ b/doc/book/en/B1030-form-management.en.txt	Mon Dec 29 13:50:42 2008 -0800
@@ -126,7 +126,7 @@
 
 * `__errorurl`: initial form URL, used for redirecting in case a validation
   error is raised during editing. If this one is not specified, an error page
-  is displayed instead of going back to the form (which is, if necessarry,
+  is displayed instead of going back to the form (which is, if necessary,
   responsible for displaying the errors)
 
 * `__form_id`: initial view form identifier, used if `__action_apply` is

--- a/doc/book/en/C030-instance-config.en.txt	Mon Dec 29 11:16:49 2008 -0800
+++ b/doc/book/en/C030-instance-config.en.txt	Mon Dec 29 13:50:42 2008 -0800
@@ -14,7 +14,7 @@
 
 It is a simple text file format INI. In the following description,
 each option name is prefixed with its own section and followed by its
-default value if necessarry, e.g. "`<section>.<option>` [value]."
+default value if necessary, e.g. "`<section>.<option>` [value]."
 
 
 Configuring the Web server

--- a/doc/book/en/C040-rql.en.txt	Mon Dec 29 11:16:49 2008 -0800
+++ b/doc/book/en/C040-rql.en.txt	Mon Dec 29 13:50:42 2008 -0800
@@ -30,7 +30,7 @@
 (the current implementation of RQL generates SQL). For that it is limited
 to the way of browsing relations and introduces variables. 
 The user does not need to know the model underlying SQL, but the `CubicWeb` 
-scheam defining the application.
+schema defining the application.
 
 Versa
 `````