--- a/doc/book/en/B060-form-management.en.txt	Mon Dec 08 09:08:29 2008 -0800
+++ b/doc/book/en/B060-form-management.en.txt	Mon Dec 08 17:29:00 2008 -0800
@@ -1,133 +1,137 @@
 .. -*- coding: utf-8 -*-
 
-Gestion de formulaires
-======================
+Forms handling
+==============
 
-Contrôle de la génération automatique de formulaire pour les entités manipulée
-------------------------------------------------------------------------------
+Automatically generated forms management for handled entities
+-------------------------------------------------------------
+
 XXX FILLME
 
-* les formulaires 'edition' et 'creation'
+* forms ``edition`` and ``creation``
 
-Le formulaire généré par défaut ne vous convient pas ? Vous êtes peut-être pas
-obligé de le refaire à la main ! :)
+The form generated by default does not fit your needs? You are not
+required to re-do all by hands! :)
 
-* rtags primary, secondary, generated, generic,
+* rtags primary, secondary, generated, generic, 
   `Entity.relation_category(rtype, x='subject')`
 * inline_view (now a rtag?)
-* spécification widget
+* widget specification
 
+Editing controller behavior by default (id: `edit`)
+---------------------------------------------------
+
+Editing control
+```````````````
 
-Fonctionnement du contrôleur d'édition par défaut (id: 'edit')
---------------------------------------------------------------
+Re-requisites: the parameters related to entities to edit are
+specified as follows ::
 
-Contrôle de l'édition
-`````````````````````
-Prérequis: les paramètres liés aux entités à éditer sont spécifiés de la forme ::
+  <field name>:<entity eid>
+
+where entity eid could be a letter in case of an entity to create. We
+name those parameters as *qualified*.
 
-  <nom de champ>:<eid de l'entité>
-
-où l'eid de l'entité pourra être une lettre dans le cas d'une entité à créer. On
-dénommera ces paramètres comme *qualifié*.
+1. Retrieval of entities to edit by looking for the forms parameters
+   starting by `eid:` and also having a parameter `__type` associated
+   (also *qualified* by eid)
 
-1. récupération des entités à éditer en cherchant les paramètres de formulaire
-   commençant par 'eid:' ayant également un paramètre '__type' associé
-   (également *qualifié* par l'eid évidemment)
+2. For all the attributes and the relations of an entity to edit: 
+   
+   1. search for a parameter `edits-<relation name>` or `edito-<relation name>`
+      qualified in the case of a relation where the entity is object
+   2. if found, the value returned is considered as the initial value
+      for this relaiton and we then look for the new value(s)  in the parameter
+      <relation name> (qualified)
+   3. if the value returned is different from the initial value, an database update
+      request is done
 
-2. pour tous les attributs et relations de chaque entité à éditer
+3. For each entity to edit:
 
-   1. recherche d'un paramètre 'edits-<nom relation>' ou 'edito-<nom relation>'
-      qualifié dans le cas d'une relation dont l'entité est objet
-   2. si trouvé, la valeur récupérée est considérée comme la valeur originale
-      pour cette relation, et on cherche la (ou les) nouvelle(s) valeur(s) dans
-      le paramètre <nom relation> (qualifié)
-   3. si la valeur est différente de l'originale, une requête de modification en
-      base est effectuée
+   1. if a qualified parameter `__linkto` is specified, its value has to be
+      a string (or a list of string) such as: ::
+        
+        <relation type>:<eids>:<target>
+      
+      where <target> is either `subject` or `object` and each eid could be
+      separated from the others by a `_`. Target specifies if the *edited entity*
+      is subject or object of the relation and each relation specified will
+      be inserted.
 
-3. pour chaque entité à éditer
+    2. if a qualified parameter `__clone_eid` is specified for an entity, the
+       relations of the specified entity passed as value of this parameter are 
+       copied on the edited entity.
 
-   1. si un paramètre `__linkto` qualifié est spécifié, sa valeur doit être une
-      chaine (ou une liste de chaine) de la forme : ::
+    3. if a qualified parameter `__delete` is specified, its value must be
+       a string or a list of string such as follows: ::
+          
+          <ssubjects eids>:<relation type>:<objects eids>
 
-        <relation type>:<eids>:<target>
+       where each eid subject or object can be seperated from the other 
+       by `_`. Each relation specified will be deleted.
 
-      où <target> vaut 'subject' ou 'object' et chaque eid peut-être séparé d'un
-      autre par un '_'. Target spécifie *l'entité éditée* est sujet ou objet de la
-      relation et chaque relation ainsi spécifiée sera insérée.
+    4. if a qualified parameter `__insert` is specified, its value should
+       follow the same pattern as `__delete`, but each relation specified is
+       inserted.
 
-   2. si un paramètre `__cloned_eid` qualifié est spécifié pour une entité, les
-      relations de l'entité spécifiée en valeur de cette argument sont copiées sur
-      l'entité éditée
+4. If the parameters `__insert` and/or `__delete` are found not qualified,
+   they are interpreted as explained above (independantly from the number
+   of entities edited).
+
+5. If no entity is edited but the form contains the parameters `__linkto`
+   and `eid`, this one is interpreted by using the value specified for `eid`
+   to designate the entity on which to add the relations.
 
 
-   3. si un paramètre `__delete` qualifié est spécifié, sa valeur doit être une
-      chaine (ou une liste de chaine) de la forme : ::
+.. note::
+   
+   * If the parameter `__action_delete` is found, all the entities specified
+     as to be edited will be deleted.
+   
+   * If the parameter`__action_cancel` is found, no action is completed.
 
-	<subject eids>:<relation type>:<object eids>
-
-      où chaque eid sujet ou objet peut-être séparé d'un autre par un '_'. Chaque
-      relation ainsi spécifiée sera supprimée.
+   * If the parameter `__action_apply` is found, the editing is applied 
+     normally but the redirection is done on the form 
+     (see :ref:`RedirectionControl`).
 
-   4. si un paramètre `__insert` qualifié est spécifié, sa valeur doit être de
-      même format que pour `__delete`, mais chaque relation ainsi spécifiée sera 
-      insérée.
+   * The parameter `__method` is also supported as for the main template
+     (XXX not very consistent, maybe __method should be dealed in the view
+     controller).
 
-4. si les paramètres `__insert` et/ou  `__delete` sont trouvés non qualifiés,
-   ils sont interprétés comme décrit ci-dessus (quelque soit le nombre d'entité
-   édité)
+   * If no entity is found to be edited and if there is no parameter
+     `__action_delete`, `__action_cancel`, `__linkto`, `__delete` or
+     `__insert`, an error is raised.
 
-5. si aucune entité n'est éditée mais que le formulaire contient les paramètres
-   `__linkto` et `eid`, celui-ci est interprété en prenant la valeur spécifié
-   par le paramètre `eid` pour désigner l'entité sur laquelle ajouter les
-   relations
+   * Using the parameter `__message` in the form will allow to use its value
+     as a message to provide the user once the editing is completed.
 
 
-A noter que :
-
-* si le paramètre `__action_delete` est trouvé, toutes les entités comme
-  spécifiées à éditer seront supprimées
-
-* si le paramètre `__action_cancel` est trouvé, aucune action n'est effectuée
-
-* si le paramètre `__action_apply` est trouvé, l'édition est effectuée
-  normalement mais la redirection sera effectuée sur le formulaire (cf `Contrôle
-  de la redirection`_)
+Redirection control
+```````````````````
+.. RedirectionControl::
 
-* le paramètre `__method` est également supporté comme sur le template principal
-  (XXX not very consistent, maybe __method should be dealed in the view controller) 
+Once editing is completed, there is still an issue left: where should we go
+now? If nothing is specified, the controller will do his job but it does not
+mean we will be happy with the result. We can control that by using the
+following parameters:
 
-* si aucune entité à éditer n'est trouvée et qu'il n'y a pas de paramètre
-  `__action_delete`, `__action_cancel`, `__linkto`, `__delete` ou `__insert`,
-  une erreur est levée
+* `__redirectpath`: path of the URL (relative to the root URL of the site,
+  no form parameters
 
-* placer dans le formulaire le paramètre `__message` permettra d'utiliser la
-  valeur de ce paramètre comme message d'information à l'utilisateur une fois
-  l'édition effectuée.
-
+* `__redirectparams`: forms parameters to add to the path
 
-Contrôle de la redirection
-``````````````````````````
-Une fois que l'édition s'est bien passé, reste un problème : c'est bien beau
-tout ça, mais où qu'on va maintenant ?? Si rien n'est spécifié, le controlleur
-se débrouille, mais comme il fait pas toujours ce qu'on voudrait, on peut
-controller ça en utilisant les paramètres suivant :
+* `__redirectrql`: redirection RQL request 
+
+* `__redirectvid`: redirection view identifier
 
-* `__redirectpath`: chemin de l'url (relatif à la racine du site, sans paramètre
-  de formulaire
-  
-* `__redirectparams`: paramètres de formulaires à ajouter au chemin
-  
-* `__redirectrql`: requête RQL de redirection
-
-* `__redirectvid`: identifiant de vue de redirection
+* `__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,
+  responsible for displaying the errors)
 
-* `__errorurl`: url du formulaire original, utilisé pour la redirection en cas
-  d'erreur de validation pendant l'édition. Si celui-ci n'est pas spécifié, une
-  page d'erreur sera présentée plutot qu'un retour sur le formulaire (qui est le
-  cas échéant responsable d'afficher les erreurs)
+* `__form_id`: initial view form identifier, used if `__action_apply` is
+  found
 
-* `__form_id`: identifiant de vue du formulaire original, utilisée si
-  `__action_apply` est trouvé
+In general we use either `__redirectpath` and `__redirectparams` or 
+`__redirectrql` and `__redirectvid`.
 
-En général on utilise soit `__redirectpath et `__redirectparams` soit
-`__redirectrql` et `__redirectvid`.