--- a/doc/book/en/04-01-schema-stdlib.en.txt	Wed Nov 19 08:41:47 2008 -0800
+++ b/doc/book/en/04-01-schema-stdlib.en.txt	Wed Nov 19 09:57:22 2008 -0800
@@ -1,70 +1,71 @@
 .. -*- coding: utf-8 -*-
 
-Schémas prédéfinies dans la librairie
--------------------------------------
-
-La librairie définit un certain nombre de schémas d'entités nécessaires
-au système ou bien couramment utilisées dans les application `cubicweb`.
-Vous pouvez bien entendu étendre ces schémas au besoin.
-
-
-Schémas "systèmes"
-``````````````````
+Pre-defined schemas in the library
+----------------------------------
 
-* `EUser`, utilisateurs du système
-* `EGroup`, groupes d'utilisateurs
-* `EEType`, types d'entité
-* `ERType`, types de relation
-
-* `State`, état d'un workflow
-* `Transition`, transition d'un workflow
-* `TrInfo`, enregistrement d'un passage de transition pour une entité
-
-* `EmailAddress`, adresse électronique, utilisé par le système de notification
-  pour les utilisateurs et par d'autres schéma optionnels
-
-* `EProperty`, utilisé pour configurer l'application
-* `EPermission`, utilisé pour configurer la sécurité de l'application
-
-* `Card`, fiche documentaire générique
-* `Bookmark`, un type d'entité utilisé pour permetter à un utilisateur de
-  personnaliser ses liens de navigation dans l'application.
+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.
 
 
-Composants de la librairie
-``````````````````````````
-Une application est construite sur la base de plusieurs composants de base.
-Parmi les composants de base disponible, on trouve par exemple :
+System schemas
+``````````````
+The system entities available are :
+
+* `EUser`, system users
+* `EGroup`, users groups
+* `EEType`, entity type
+* `ERType`, relation type
+
+* `State`, workflow state
+* `Transition`, workflow transition
+* `TrInfo`, record of a transition trafic for an entity 
+
+* `EmailAddress`, email address, used by the system to send notifications
+  to the users and also used by others optionnals schemas
+
+* `EProperty`, used to configure the application
+* `EPermission`, used to configure the security of the application
 
-* `ecomment`, fournit le type d'entité `Comment` permettant de commenter les
-  entités du site
-  
-* `emailinglist`, fournit le type d'entité `Mailinglist` regroupant des
-  informations sur une liste de discussion
+* `Card`, generic documenting card
+* `Bookmark`, an entity type used to allow a user to customize his links within
+  the application
+
+Cubes in the library
+````````````````````
+
+An application is based on several basic cubes. In the set of available
+basic cubes we can find by example :
 
-* `efile`, fournit les types d'entités `File` et `Image` utilisés pour
-  représenter des fichiers (texte ou binaire) avec quelques données
-  supplémentaires comme le type MIME ou l'encodage le cas échéant ().
+* `comment`, provides an entity type for `Comment` allowing us to comment others
+  site's entities
+
+* `mailinglist`, provides an entity type for `Mailinglist` which groups informations
+  in a discussion list
+
+* `file`, provides entity types for `File` et `Image` used to represent
+  files (text or binary) with additionnal informations such as MIME type or
+  encoding.
   
-* `elink`, fournit le type d'entité lien internet (`Link`)
+* `link`, provides an entity type for hypertext link (`Link`)
 
-* `eblog`, fournit le type d'entité weblog (`Blog`)
+* `blog`, provides an entity type weblog (`Blog`)
 
-* `eperson`, fournit le type d'entité personne physique (`Person`)
+* `person`, provides an entity type for a person (`Person`)
 
-* `eaddressbook`, fournit les types d'entités utilisés pour représenter des n°
-  de téléphone (`PhoneNumber`) et des adresses postales (`PostalAddress`)
+* `addressbook`, provides an entity type used to represent phone 
+  numbers (`PhoneNumber`) and mailing address (`PostalAddress`)
   
-* `eclasstags`, système de classfication à base d'étiquettes (`Tag`)
+* `classtags`, categorization system based on tags (`Tag`)
 
-* `eclassfolders`, système de classification à base de dossiers hiérarchiques
-  destinés à créer des rubriques de navigation (`Folder`)
+* `classfolders`, categorization system based on folders hierarchy in order 
+  to create navigation sections (`Folder`)
 
-* `eemail`, gestion d'archives de courriers électroniques (`Email`, `Emailpart`,
+* `email`, archiving management for emails (`Email`, `Emailpart`,
   `Emailthread`)
 
-* `ebasket`, gestion de paniers (`Basket`) permettant de regrouper des entités
+* `basket`, basket management (`Basket`) allowing to group entities
 
-Pour déclarer l'utilisation d'un composant, une fois celui-ci installé, ajoutez
-le nom du composant à la variable `__use__` du fichier `__pkginfo__.py` de
-votre propre composant.
+To declare the use of a component, once installed, add the name of the component
+to the variable `__use__` in the file `__pkginfo__.py` of your own component.
+

--- a/doc/book/en/04-02-schema-definition.en.txt	Wed Nov 19 08:41:47 2008 -0800
+++ b/doc/book/en/04-02-schema-definition.en.txt	Wed Nov 19 09:57:22 2008 -0800
@@ -1,30 +1,30 @@
 .. -*- coding: utf-8 -*-
 
-Définition d'un type d'entité
------------------------------
+Entity type definition
+----------------------
 
-Un type d'entité est définit par une classe python héritant de `EntityType`. Le
-nom de la classe correspond au nom du type. Ensuite le corps de la classe
-contient la description des attributs et des relations pour ce type d'entité,
-par exemple ::
+An entity type is defined by a Python class which inherits `EntityType`. The
+class name correponds to the type name. Then the content of the class contains
+the description of attributes and relations for the defined entity type,
+by example ::
 
   class Personne(EntityType):
-    """une personne avec les propriétés et relations nécessaires à mon
+    """A person with the properties and the relations necessarry for my
     application"""
 
-    nom = String(required=True, fulltextindexed=True)
-    prenom = String(required=True, fulltextindexed=True)
-    civilite = String(vocabulary=('M', 'Mme', 'Mlle'))
-    date_naiss = Date()
-    travaille_pour = SubjectRelation('Company', cardinality='?*')
+    last_name = String(required=True, fulltextindexed=True)
+    first_name = String(required=True, fulltextindexed=True)
+    title = String(vocabulary=('M', 'Mme', 'Mlle'))
+    date_of_birth = Date()
+    works_for = SubjectRelation('Company', cardinality='?*')
 
-* le nom de l'attribut python correspond au nom de l'attribut ou de la relation
-  dans cubicweb.
+* the name of the Python attribute corresponds to the name of the attribute
+  or the relation in `CubicWeb` application.
 
-* tout les types de bases sont disponibles nativement : `String`, `Int`, `Float`,
+* all built-in types are available : `String`, `Int`, `Float`,
   `Boolean`, `Date`, `Datetime`, `Time`, `Byte`.
 
-* Chaque type d'entité a au moins les méta-relations suivantes :
+* each entity type has at least the following meta-relations :
 
   - `eid` (`Int`)
   
@@ -32,181 +32,175 @@
   
   - `modification_date` (`Datetime`)
   
-  - `created_by` (`EUser`) (quel utilisateur a créé l'entité)
+  - `created_by` (`EUser`) (which user created the entity)
   
-  - `owned_by` (`EUser`) (à qui appartient l'entité, par défaut le
-     créateur mais pas forcément et il peut exister plusieurs propriétaires)
+  - `owned_by` (`EUser`) (who does the entity belongs to, by default the 
+     creator but not necessarry and it could have multiple owners)
      
   - `is` (`EEType`)
 
   
-* il est également possible de définir des relations dont le type d'entité est
-  l'objet en utilisant `ObjectRelation` plutôt que `SubjectRelation`
+* it is also possible to define relations of type object by using `ObjectRelation`
+  instead of `SubjectRelation`
 
-* le premier argument de `SubjectRelation` et `ObjectRelation` donne
-  respectivement le type d'entité objet /sujet de la relation. Cela
-  peut être : 
+* the first argument of `SubjectRelation` and `ObjectRelation` gives respectively
+  the object/subject entity type of the relation. This could be :  
 
-  * une chaine de caractères correspondant à un type d'entité
+  * a string corresponding to an entity type
 
-  * un tuple de chaines de caractères correspondant à plusieurs types d'entité
+  * a tuple of string correponding to multiple entities types
 
-  * les chaînes de caractères spéciales suivantes :
+  * special string such as follows :
 
-    - "**" : tout les types d'entité
-    - "*" : tout les types d'entité non méta
-    - "@" : tout les types d'entité méta mais non "système" (i.e. servant à la
-      description du schema en base)
+    - "**" : all types of entities
+    - "*" : all types of non-meta entities 
+    - "@" : all types of meta entities but not system entities (e.g. used for
+      the basic schema description)
 
-* il est possible d'utiliser l'attribut possible `meta` pour marquer un type
-  d'entité comme étant "méta" (i.e. servant à décrire / classifier d'autre
-  entités) 
+* it is possible to use the attribute `meta` to flag an entity type as a `meta`
+  (e.g. used to describe/categorize other entities)
+
+* optional properties for attributes and relations : 
 
-* propriétés optionnelles des attributs et relations : 
+  - `description` : string describing an attribute or a relation. By default
+    this string will be used in the editing form of the entity, which means
+    that it is supposed to help the end-user and should be flagged by the
+    function `_` to be properly internationalized.
 
-  - `description` : chaine de caractères décrivant un attribut ou une
-    relation. Par défaut cette chaine sera utilisée dans le formulaire de saisie
-    de l'entité, elle est donc destinée à aider l'utilisateur final et doit être
-    marquée par la fonction `_` pour être correctement internationalisée.
+  - `constraints` : list of conditions/constraints that the relation needs to
+    satisfy (c.f. `Contraints`_)
 
-  - `constraints` : liste de contraintes devant être respecté par la relation
-    (c.f. `Contraintes`_)
-
-  - `cardinality` : chaine de 2 caractères spécifiant la cardinalité de la
-    relation. Le premier caractère donne la cardinalité de la relation sur le
-    sujet, le 2eme sur l'objet. Quand une relation possède plusieurs sujets ou
-    objets possibles, la cardinalité s'applique sur l'ensemble et non un à un (et
-    doit donc à priori être cohérente...). Les valeurs possibles sont inspirées
-    des expressions régulières :
+  - `cardinality` : two characters string which specify the cardinality of the
+    relation. The first character defines the cardinality of the relation on
+    the subject, the second on the object of the relation. When a relation
+    has multiple possible subjects or objects, the cardinality applies to all
+    and not on a one to one basis (so it must be consistent...). The possible
+    values are inspired from regular expressions syntax :
 
     * `1`: 1..1
     * `?`: 0..1
     * `+`: 1..n
     * `*`: 0..n
 
-  - `meta` : booléen indiquant que la relation est une méta relation (faux par
-    défaut)
+  - `meta` : boolean indicating that the relation is a meta-relation (false by
+    default)
 
-* propriétés optionnelles des attributs : 
+* optionnal properties for attributes : 
 
-  - `required` : booléen indiquant si l'attribut est obligatoire (faux par
-    défaut)
+  - `required` : boolean indicating if the attribute is required (false by default)
 
-  - `unique` : booléen indiquant si la valeur de l'attribut doit être unique
-    parmi toutes les entités de ce type (faux par défaut)
+  - `unique` : boolean indicating if the value of the attribute has to be unique
+    or not within all entities of the same type (false by default)
 
-  - `indexed` : booléen indiquant si un index doit être créé dans la base de
-    données sur cette attribut (faux par défaut). C'est utile uniquement si vous
-    savez que vous allez faire de nombreuses recherche sur la valeur de cet
-    attribut. 
+  - `indexed` : boolean indicating if an index needs to be created for this 
+    attribute in the database (false by default). This is usefull only if
+    you know that you will have to run numerous searches on the value of this
+    attribute.
 
-  - `default` : valeur par défaut de l'attribut. A noter que dans le cas des
-    types date, les chaines de caractères correspondant aux mots-clés RQL
-    `TODAY` et `NOW` sont utilisables.
+  - `default` : default value of the attribute. In case of date types, the values
+    which could be used correpond to the RQL keywords `TODAY` and `NOW`.
+  
+  - `vocabulary` : specify static possible values of an attribute
 
-  - `vocabulary` : spécifie statiquement les valeurs possibles d'un attribut
-
-* propriétés optionnelles des attributs de type `String` : 
+* optionnal properties of type `String` : 
 
-  - `fulltextindexed` : booléen indiquant si l'attribut participe à l'index plein
-    texte (faux par défaut) (*valable également sur le type `Byte`*)
+  - `fulltextindexed` : boolean indicating if the attribute is part of
+    the full text index (false by default) (*applicable on the type `Byte`
+    as well*)
 
-  - `internationalizable` : booléen indiquant si la valeur de cet attribut est
-    internationalisable (faux par défaut) 
+  - `internationalizable` : boolean indicating if the value of the attribute
+    is internationalizable (false by default)
 
-  - `maxsize` : entier donnant la taille maximum de la chaine (pas de limite par
-    défaut)  
+  - `maxsize` : integer providing the maximum size of the string (no limit by default)
 
-* propriétés optionnelles des relations : 
+* optionnal properties for relations : 
 
-  - `composite` : chaîne indiquant que le sujet (composite == 'subject') est
-    composé de ou des objets de la relation. Pour le cas opposé (l'objet est
-    composé de ou des sujets de la relation, il suffit de mettre 'object' comme
-    valeur. La composition implique que quand la relation est supprimé (et donc
-    aussi quand le composite est supprimé), le ou les composés le sont
-    également. 
+  - `composite` : string indicating that the subject (composite == 'subject')
+    is composed of the objects of the relations. For the opposite case (when
+    the object is composed of the subjects of the relation), we just need
+    to set 'object' as the value. The composition implies that when the relation
+    is deleted (so when the composite is deleted), the composed are also deleted.
 
-Contraintes
-```````````
-Par défaut les types de contraintes suivant sont disponibles :
+Contraints
+``````````
+By default, the available constraints types are :
 
-* `SizeConstraint` : permet de spécifier une taille minimale et/ou maximale sur
-  les chaines de caractères (cas générique de `maxsize`)
+* `SizeConstraint` : allows to specify a minimum and/or maximum size on
+  string (generic case of `maxsize`)
 
-* `BoundConstraint` : permet de spécifier une valeur minimale et/ou maximale sur
-  les types numériques
+* `BoundConstraint` : allows to specify a minimum and/or maximum value on 
+  numeric types
 
-* `UniqueConstraint` : identique à "unique=True"
+* `UniqueConstraint` : identical to "unique=True"
 
-* `StaticVocabularyConstraint` : identique à "vocabulary=(...)"
+* `StaticVocabularyConstraint` : identical to "vocabulary=(...)"
 
-* `RQLConstraint` : permet de spécifier une requête RQL devant être satisfaite
-  par le sujet et/ou l'objet de la relation. Dans cette requête les variables `S`
-  et `O` sont préféfinies respectivement comme l'entité sujet et objet de la
-  relation
+* `RQLConstraint` : allows to specify a RQL query that needs to be satisfied
+  by the subject and/or the object of the relation. In this query the variables
+  `S` and `O` are reserved for the entities subject and object of the 
+  relation.
 
-* `RQLVocabularyConstraint` : similaire à la précédente, mais exprimant une
-  contrainte "faible", i.e. servant uniquement à limiter les valeurs apparaissant
-  dans la liste déroulantes du formulaire d'édition, mais n'empêchant pas une
-  autre entité d'être séléctionnée
+* `RQLVocabularyConstraint` : similar to the previous type of constraint except
+  that it does not express a "strong" constraint, which means it is only used to
+  restrict the values listed in the drop-down menu of editing form, but it does
+  not prevent another entity to be selected
 
 
-Définition d'un type de relation
---------------------------------
+Relation type definition
+------------------------
 
-Un type de relation est définit par une classe python héritant de `RelationType`. Le
-nom de la classe correspond au nom du type. Ensuite le corps de la classe
-contient la description des propriétés de ce type de relation, ainsi
-qu'éventuellement une chaine pour le sujet et une autre pour l'objet permettant
-de créer des définitions de relations associées (auquel cas il est possibles de
-donner sur la classe les propriétés de définition de relation explicitées
-ci-dessus), par exemple ::
+A relation is defined by a Python class heriting `RelationType`. The name
+of the class corresponds to the name of the type. The class then contains
+a description of the properties of this type of relation, and could as well 
+contains a string for the subject and a string for the object. This allows to create
+new definition of associated relations, (so that the class can have the 
+definition properties from the relation) by example ::
 
-  class verrouille_par(RelationType):
-    """relation sur toutes les entités applicatives indiquant que celles-ci sont vérouillées
+  class locked_by(RelationType):
+    """relation on all entities indicating that they are locked"""
     inlined = True
     cardinality = '?*'
     subject = '*'
     object = 'EUser'
 
-En plus des permissions, les propriétés propres aux types de relation (et donc
-partagés par toutes les définitions de relation de ce type) sont :
-
-* `inlined` : booléen contrôlant l'optimisation physique consistant à stocker la
-  relation dans la table de l'entité sujet au lieu de créer une table spécifique
-  à la relation. Cela se limite donc aux relations dont la cardinalité
-  sujet->relation->objet vaut 0..1 ('?') ou 1..1 ('1')
-
-* `symetric` : booléen indiquant que la relation est symétrique. i.e.
-  `X relation Y` implique `Y relation X`
-
-Dans le cas de définitions de relations simultanée, `sujet` et `object` peuvent
-tout deux valoir la même chose que décrite pour le 1er argument de
-`SubjectRelation` et `ObjectRelation`.
-
-A partir du moment où une relation n'est ni mise en ligne, ni symétrique, et
-ne nécessite pas de permissions particulières, sa définition (en utilisant
-`SubjectRelation` ou `ObjectRelation`) est suffisante.
+In addition to the permissions, the properties of the relation types
+(shared also by all definition of relation of this type) are :
 
 
-Définition des permissions
---------------------------
+* `inlined` : boolean handling the physical optimization for archiving
+  the relation in the subject entity table, instead of creating a specific
+  table for the relation. This applies to the relation when the cardinality
+  of subject->relation->object is 0..1 (`?`) or 1..1 (`1`)
+
+* `symetric` : boolean indication that the relation is symetrical, which
+  means `X relation Y` implies `Y relation X`
+
+In the case of simultaneous relations definitions, `subject` and `object`
+can both be equal to the value of the first argument of `SubjectRelation`
+and `ObjectRelation`.
 
-La définition des permissions se fait à l'aide de l'attribut `permissions` des
-types d'entité ou de relation. Celui-ci est un dictionnaire dont les clés sont
-les types d'accès (action), et les valeurs les groupes ou expressions autorisées. 
+When a relation is not inlined and not symetrical, and it does not require
+specific permissions, its definition (by using `SubjectRelation` and
+`ObjectRelation`) is all we need.
 
-Pour un type d'entité, les actions possibles sont `read`, `add`, `update` et
+Permissions definition
+----------------------
+
+Define permissions is set through to the attribute `permissions` of entities and
+relations types. It defines a dictionnary where the keys are the access types
+(action), and the values are the authorized groups or expressions.
+
+For an entity type, the possible actions are `read`, `add`, `update` and
 `delete`.
 
-Pour un type de relation, les actions possibles sont `read`, `add`, et `delete`.
+For a relation type, the possible actions are `read`, `add`, and `delete`.
 
-Pour chaque type d'accès, un tuple indique le nom des groupes autorisés et/ou
-une ou plusieurs expressions RQL devant être vérifiées pour obtenir
-l'accès. L'accès est donné à partir du moment où l'utilisateur fait parti d'un
-des groupes requis ou dès qu'une expression RQL est vérifiée.
+For each access type, a tuple indicates the name of the authorized groups and/or
+one or multiple RQL expressions to satisfy to grant access. The access is
+provided once the user is in the listed groups or one of the RQL condition is
+satisfied.
 
-Les groupes standards sont :
+The standard groups are :
 
 * `guests`
 
@@ -214,59 +208,55 @@
 
 * `managers`
 
-* `owners` : groupe virtuel correspondant au propriétaire d'une entité. Celui-ci
-  ne peut être utilisé que pour les actions `update` et `delete` d'un type
-  d'entité. 
+* `owners` : virtual group corresponding to the entity's owner.
+  This can only be used for the actions `update` and `delete` of an entity
+  type.
 
-Il est également possible d'utiliser des groupes spécifiques devant être pour
-cela créés dans le precreate de l'application (`migration/precreate.py`).
+It is also possible to use specific groups if they are define in the precreate 
+of the application (``migration/precreate.py``).
 
-Utilisation d'expression RQL sur les droits en écriture
-```````````````````````````````````````````````````````
-Il est possible de définir des expressions RQL donnant des droits de
-modification (`add`, `delete`, `update`) sur les types d'entité et de relation.
+Use of RQL expression for writing rights
+````````````````````````````````````````
+It is possible to define RQL expression to provide update permission 
+(`add`, `delete` and `update`) on relation and entity types.
 
-Expression RQL pour les permissions sur un type d'entité :
+RQL expression for entity type permission :
 
-* il faut utiliser la classe `ERQLExpression`
+* you have to use the class `ERQLExpression`
 
-* l'expression utilisée correspond à la clause WHERE d'une requête RQL
+* the used expression corresponds to the WHERE statement of an RQL query
 
-* dans cette expression, les variables X et U sont des références prédéfinies
-  respectivement sur l'entité courante (sur laquelle l'action est vérifiée) et
-  sur l'utilisateur ayant effectué la requête
+* in this expression, the variables X and U are pre-defined references
+  respectively on the current entity (on which the action is verified) and
+  on the user who send the request
 
-* il est possible d'utiliser dans cette expression les relations spéciales
-  "has_<ACTION>_permission" dont le sujet est l'utilisateur et l'objet une
-  variable quelquonque, signifiant ainsi que l'utilisateur doit avoir la
-  permission d'effectuer l'action <ACTION> sur la ou les entités liées cette
-  variable
+* it is possible to use, in this expression, a special relation 
+  "has_<ACTION>_permission" where the subject is the user and the 
+  object is a any variable, meaning that the user needs to have
+  permission to execute the action <ACTION> on the entities related
+  to this variable 
 
-Pour les expressions RQL sur un type de relation, les principes sont les mêmes
-avec les différences suivantes :
+For RQL expressions on a relation type, the principles are the same except 
+for the following :
 
-* il faut utiliser la classe `RRQLExpression` dans le cas d'une relation non
-  finale
+* you have to use the class `RQLExpression` in the case of a non-final relation
 
-* dans cette expression, les variables S, O et U sont des références
-  prédéfinies respectivement sur le sujet et l'objet de la relation
-  courante (sur laquelle l'action est vérifiée) et sur l'utilisateur
-  ayant effectué la requête
+* in the expression, the variables S, O and U are pre-defined references
+  to respectively the subject and the object of the current relation (on
+  which the action is being verified) and the user who executed the query
 
-* On peut aussi définir des droits sur les attributs d'une entité (relation non
-  finale), sachant les points suivants :
+* we can also defined rights on attributes of an entity (non-final relation),
+  knowing that : 
 
-  - pour définir des expressions rql, il faut utiliser la classe `ERQLExpression`
-    dans laquelle X représentera l'entité auquel appartient l'attribut
-
-  - les permissions 'add' et 'delete' sont équivalentes. En pratique seul
-    'add'/'read' son pris en considération
+  - to defines RQL expression, we have to use the class `ERQLExpression`
+    in which X represents the entity the attribute belongs to
 
+  - the permissions `add` and `delete` are equivalent. Only `add`/`read`
+    are actually taken in consideration.
 
-En plus de cela, le type d'entité `EPermission` de la librairie standard permet
-de construire des modèles de sécurités très complexes et dynamiques. Le schéma
-de ce type d'entité est le suivant : ::
-
+In addition to that the entity type `EPermission` from the standard library
+allow to build very complex and dynamic security architecture. The schema of
+this entity type is as follow : ::
 
     class EPermission(MetaEntityType):
 	"""entity type that may be used to construct some advanced security configuration
@@ -283,7 +273,8 @@
 							  "definition of the entity's type to be useful."))
 
 
-Exemple de configuration extrait de *jpl* ::
+Example of configuration ::
+
 
     ...
 
@@ -311,38 +302,37 @@
 		       }
 	inlined = True
 
-Cette configuration suppose indique qu'une entité `EPermission` de nom
-"add_version" peut-être associée à un projet et donner le droit de créer des
-versions sur ce projet à des groupes spécifiques. Il est important de noter les
-points suivants :
+This configuration indicates that an entity `EPermission` named
+"add_version" can be associated to a project and provides rights to create
+new versions on this project to specific groups. It is important to notice that :
+
+* in such case, we have to protect both the entity type "Version" and the relation
+  associating a version to a project ("version_of")
 
-* dans ce cas il faut protéger à la fois le type d'entité "Version" et la
-  relation liant une version à un projet ("version_of")
+* because of the genricity of the entity type `EPermission`, we have to execute
+  a unification with the groups and/or the states if necessary in the expression
+  ("U in_group G, P require_group G" in the above example)
 
-* du fait de la généricité du type d'entité `EPermission`, il faut effectuer
-  l'unification avec les groupes et / ou les états le cas échéant dans
-  l'expression ("U in_group G, P require_group G" dans l'exemple ci-dessus)
+Use of RQL expression for reading rights
+````````````````````````````````````````
+
+The principles are the same but with the following restrictions :
+
+* we can not use `RRQLExpression` on relation types for reading
+
+* special relations "has_<ACTION>_permission" can not be used
 
 
-Utilisation d'expression RQL sur les droits en lecture
+Note on the use of RQL expression for `add` permission
 ``````````````````````````````````````````````````````
-Les principes sont les mêmes mais avec les restrictions suivantes :
-
-* on ne peut de `RRQLExpression` sur les types de relation en lecture
-
-* les relations spéciales "has_<ACTION>_permission" ne sont pas utilisables
-
-
-Note sur l'utilisation d'expression RQL sur la permission 'add'
-```````````````````````````````````````````````````````````````
-L'utilisation d'expression RQL sur l'ajout d'entité ou de relation pose
-potentiellement un problème pour l'interface utilisateur car si l'expression
-utilise l'entité ou la relation à créer, on est pas capable de vérifier les
-droits avant d'avoir effectué l'ajout (noter que cela n'est pas un problème coté
-serveur rql car la vérification des droits est effectuée après l'ajout
-effectif). Dans ce cas les méthodes de vérification des droits (check_perm,
-has_perm) peuvent inidquer qu'un utilisateur n'a pas le droit d'ajout alors
-qu'il pourrait effectivement l'obtenir. Pour palier à ce soucis il est en général
-nécessaire dans tel cas d'utiliser une action reflétant les droits du schéma
-mais permettant de faire la vérification correctement afin qu'elle apparaisse
-bien le cas échéant.
+Potentially, the use of an RQL expression to add an entity or a relation
+can cause problems for the user interface, because if the expression uses
+the entity or the relation to create, then we are not able to verify the 
+permissions before we actually add the entity (please note that this is
+not a problem for the RQL server at all, because the permissions checks are
+done after the creation). In such case, the permission check methods 
+(check_perm, has_perm) can indicate that the user is not allowed to create 
+this entity but can obtain the permission. 
+To compensate this problem, it is usually necessary, for such case,
+to use an action that reflects the schema permissions but which enables
+to check properly the permissions so that it would show up if necessary.

--- a/doc/book/en/04-define-schema.en.txt	Wed Nov 19 08:41:47 2008 -0800
+++ b/doc/book/en/04-define-schema.en.txt	Wed Nov 19 09:57:22 2008 -0800
@@ -1,20 +1,21 @@
 .. -*- coding: utf-8 -*-
 
-Définition du modèle de données (*schéma*)
-==========================================
+Data model definition (*schema*)
+================================
 
-Le schéma est l'élément central d'une application d'CubicWeb, définissant le modèle
-de données manipulé. Il est généralement défini à partir de type d'entités
-existants dans la librairie et d'autres spécifiques, généralement décrites dans
-un ou plusieurs fichiers python dans le sous-répertoire `schema` du modèle.
+The schema is the core piece of a `CubicWeb` application as it defines
+the data model handled. It is based on entities types already defined
+in the `CubicWeb` standard library and others, more specific, we would 
+expect to find in one or more Python files under the `schema` directory.
 
-A ce niveau il est important de noter la différence entre type de relation et
-définition de relation : un type de relation est uniquement un nom de relation
-avec éventuellement quelques propriétés supplémentaires (voir plus bas), alors
-qu'une définition de relation est un triplet complet "<type d'entité sujet>
-<type de relation> <type d'entité objet>". Eventuellement un type de relation
-sera créé implicitement si aucun n'est associé à une définition de relation du
-schema.
+At this point, it is important to make clear the difference between
+relation type and relation definition: a relation type is only a relation
+name with potentially other additionnal properties (see XXXX), whereas a 
+relation definition is a complete triplet 
+"<subject entity type> <relation type> <object entity type>". 
+A relation type could have been implied if none is related to a 
+relation definition of the schema.
+
 
 .. include:: 04-01-schema-stdlib.en.txt
 .. include:: 04-02-schema-definition.en.txt