# HG changeset patch
# User Sandrine Ribeau <sandrine.ribeau@logilab.fr>
# Date 1225820554 28800
#      Tue Nov 04 09:42:34 2008 -0800
# Node ID 3d869f4b93f63e1bec09b9750be508cb8d6d198f
# Parent  e8512b775e2de33550c901d1597aee8403107a36
Merge content with RQL doc which was under cubicweb/doc/devmanual_fr.

diff --git a/doc/canonisation.txt b/doc/canonisation.txt
--- a/doc/canonisation.txt
+++ b/doc/canonisation.txt
@@ -1,4 +1,4 @@
-Idées sur la canonisation
+Idées sur la canonisation
 =========================
 
 from ginco.rql.node_lib import Variable
@@ -11,7 +11,7 @@
 Exemple 1
 ---------
 
-Formules équivalentes
+Formules équivalentes
 `````````````````````
 
   Any N, N2 where N is Note, N2 is Note, N ecrit_par P1, P1 nom 'jphc', N2 ecrit_par P2, P2 nom 'ocy' ;
@@ -34,7 +34,7 @@
                  }
 }
 
-N.name  = 'is_Note:ecrit_par:1' # 1 car c'est la première variable séléctionnée
+N.name  = 'is_Note:ecrit_par:1' # 1 car c'est la première variable séléctionnée
 N2.name = 'is_Note:ecrit_par:2' # deviner pourquoi 2 ...
 P1.name = 'ecrit_par_jphc'
 P2.name = 'ecrit_par_ocy'
@@ -66,7 +66,7 @@
 Exemple 2
 ---------
 
-Formules équivalentes
+Formules équivalentes
 `````````````````````
 
   Note N WHERE N ecrit_le D, N ecrit_par P, P nom 'jphc', D day > (today-10);
@@ -118,7 +118,7 @@
 Exemple 3
 ---------
 
-Formules équivalentes
+Formules équivalentes
 `````````````````````
 
   Note N WHERE N ecrit_le D, D day > (today -10), N ecrit_par P, P nom 'jphc' or P nom 'ludal';
@@ -168,10 +168,10 @@
 
 
 
-Problèmes
+Problèmes
 ---------
 
-.1 Les paires de formules suivantes sont considérées comme identiques par
+.1 Les paires de formules suivantes sont considérées comme identiques par
    l'algorithme ci-dessus alors qu'elles ne le sont pas:
 
 Note N WHERE N ecrit_le D, D day > (today -10), N ecrit_par P, P nom 'jphc' or P nom 'ludal';
@@ -189,4 +189,4 @@
                   'nom_nom' :   [(Y, 'jphc', Y, 'ludal')]
                  }
 
-.2 risque de collision dans les noms de variables non sélectionnées (un exemple ?).
\ No newline at end of file
+.2 risque de collision dans les noms de variables non sélectionnées (un exemple ?).
\ No newline at end of file
diff --git a/doc/specifications_fr.txt b/doc/specifications_fr.txt
--- a/doc/specifications_fr.txt
+++ b/doc/specifications_fr.txt
@@ -9,10 +9,6 @@
 :Version: $Revision: 1.10 $
 :Date: $Date: 2004-05-18 15:04:13 $
 
-.. contents::
-
-
-
 Introduction
 ============
 
@@ -25,6 +21,9 @@
 langage ne devant quasiment pas voir de différence entre un attribut et une
 relation).
 
+RQL s'inspire de SQL mais se veut plus haut niveau. Une connaissance du schéma
+Cubicweb définissant l'application est nécessaire.
+
 
 Comparaison avec des langages existants
 ---------------------------------------
@@ -56,19 +55,19 @@
 Les différents types de requêtes
 --------------------------------
 
-Recherche
+Recherche (`Any`)
   Ce type de requête permet d'extraire des entités ou des attributs d'entités.
 
-Insertion d'entités
+Insertion d'entités (`INSERT`)
   Ce type de requête permet d'insérer de nouvelles entités dans la base. On
   permettra également la création directe de relations sur les entités
   nouvellement créées.
 
-Mise à jour d'entités, création de relations
+Mise à jour d'entités, création de relations (`SET`)
   Ce type de requête permet de mettre à jours des entités existantes dans la base,
   ou de créer des relations entres des entités existantes.
 
-Suppression d'entités ou de relation
+Suppression d'entités ou de relation (`DELETE`)
   Ce type de requête permet de supprimer des entités et relations existantes dans
   la base.
 
@@ -77,10 +76,30 @@
 Exemples
 ========
 
-(voir le tutoriel pour plus d'exemples)
+(voir le tutoriel :ref:`tutorielRQL` pour plus d'exemples)
+
+Requête de recherche
+--------------------
+
+  [`DISTINCT`] <type d'entité> V1(, V2)\*
+  [`GROUPBY` V1(, V2)\*]  [`ORDERBY` <orderterms>]
+  [`WHERE` <restriction>] 
+  [`LIMIT` <value>] [`OFFSET` <value>]
 
-Recherche
----------
+:type d'entité:
+  Type de la ou des variables séléctionnées. 
+  Le type spécial `Any`, revient à ne pas spécifier de type.
+:restriction:
+  liste des relations à parcourir sous la forme 
+    `V1 relation V2|<valeur constante>`
+:orderterms:
+  Définition de l'ordre de selection : variable ou n° de colonne suivie de la
+  méthode de tri (`ASC`, `DESC`), ASC étant la valeur par défaut.
+:note pour les requêtes groupées:
+  Pour les requêtes groupées (i.e. avec une clause `GROUPBY`), toutes les
+  variables sélectionnée doivent être soit groupée soit aggrégée.
+
+
 
 - *recherche de l'objet ayant l'identifiant 53*
   ::
@@ -132,8 +151,18 @@
        X is Personne, X nom N, X prenom P
 
 
-Insertion d'entités
+Requête d'insertion
 -------------------
+   `INSERT` <type d'entité> V1(, <type d'entité> V2)\* `:` <assignements>
+   [`WHERE` <restriction>] 
+
+:assignements:
+  liste des relations à assigner sous la forme `V1 relation V2|<valeur constante>`
+
+La restriction permet de définir des variables utilisées dans les assignements.
+
+Attention, si une restriction est spécifiée, l'insertion est effectuée *pour
+chaque ligne de résultat renvoyée par la restriction*.
 
 - *insertion d'une nouvelle personne nommée 'bidule'*
   ::
@@ -151,8 +180,13 @@
        INSERT Personne X: X nom 'bidule', X ami Y WHERE Y nom 'chouette'
 
 
-Mise à jour d'entités, création de relations
---------------------------------------------
+Requête de mise à jour, création de relations
+---------------------------------------------
+   `SET` <assignements>
+   [`WHERE` <restriction>] 
+
+Attention, si une restriction est spécifiée, la mise à jour est effectuée *pour
+chaque ligne de résultat renvoyée par la restriction*.
 
 - *renommage de la personne nommée 'bidule' en 'toto', avec modification du prénom*
   ::
@@ -165,8 +199,13 @@
        SET X know Y WHERE X ami Y
 
 
-Suppression d'entités ou de relations
--------------------------------------
+Requête de suppression
+----------------------
+   `DELETE` (<type d''entité> V) | (V1 relation v2),...
+   [`WHERE` <restriction>] 
+
+Attention, si une restriction est spécifiée, la suppression est effectuée *pour
+chaque ligne de résultat renvoyée par la restriction*.
 
 - *supression de la personne nommé 'toto'*
   ::
@@ -196,13 +235,16 @@
     GROUPBY, ORDERBY, ASC, DESC
 
 
-Typage
-------
+Variables et Typage
+-------------------
 
 Au niveau de RQL, on ne fait pas de distinction entre entités et attributs. La
 valeur d'un attribut est considérée comme une entité d'un type particulier (voir
 ci-dessous), lié à une (vraie) entité par une relation du nom de l'attribut.
 
+Les entités et valeurs à parcourir et / ou séléctionner sont représentées dans
+la requête par des *variables* qui doivent être écrites en majuscule.
+
 Il existe un type spécial **Any**, revenant à ne pas spécifier de type.
 
 On peut contraindre les types possibles pour une variable à l'aide de la
@@ -220,6 +262,13 @@
 booléens. On s'attend donc à recevoir un schéma dans lequel les types String,
 Int, Float, Date et Boolean sont définis.
 
+* `String` (litéral: entre doubles ou simples quotes).
+* `Int`, `Float` (le séparateur étant le '.').
+* `Date`, `Datetime`, `Time` (litéral: chaîne YYYY/MM/DD[ hh:mm] ou mots-clés
+  `TODAY` et `NOW`).
+* `Boolean` (mots-clés `TRUE` et `FALSE`).
+* mot-clé `NULL`.
+
 
 Opérateurs
 ----------
@@ -243,9 +292,21 @@
 `````````````````````````
 ::
 
-    <, <=, >=, >, ~=, IN, LIKE
+    =, <, <=, >=, >, ~=, IN, LIKE
+
+* L'opérateur `=` est l'opérateur par défaut.
 
-"LIKE" est équivalent à "~="
+* L'opérateur `LIKE` équivalent à `~=` permet d'utiliser le caractère `%` dans 
+  une chaine de caractère pour indiquer que la chaîne doit commencer ou terminer 
+  par un préfix/suffixe::
+    
+    Any X WHERE X nom ~= 'Th%'
+    Any X WHERE X nom LIKE '%lt'
+
+* L'opérateur `IN` permet de donner une liste de valeurs possibles::
+
+    Any X WHERE X nom IN ('chauvat', 'fayolle', 'di mascio', 'thenault')
+
 
 XXX nico: A truc <> 'titi' ne serait-il pas plus pratique que NOT A
 truc 'titi' ?
@@ -264,8 +325,8 @@
 5. ','
 
 
-Fonctions
----------
+Fonctionnalités avancées
+------------------------
 
 Fonctions d'aggrégat
 ````````````````````
@@ -279,6 +340,23 @@
 
     UPPER, LOWER
 
+Relations optionnelles
+``````````````````````
+
+* Elles permettent de sélectionner des entités liées ou non à une autre.
+
+* Il faut utiliser le `?` derrière la variable pour spécifier que la relation
+  vers celle-ci est optionnelle :
+
+  - Anomalies d'un projet attachées ou non à une version ::
+
+      Any X,V WHERE X concerns P, P eid 42, X corrected_in V?
+
+  - Toutes les fiches et le projet qu'elles documentent le cas échéant ::
+
+      Any C,P WHERE C is Card, P? documented_by C
+
+
 
 Grammaire BNF
 -------------
@@ -375,11 +453,25 @@
 Négation
 ````````
 
-Une requête du type "Document X where not X owned_by U" revient à dire "les
-documents n'ayant pas de relation 'owned_by'". La variable U ne doit être
-utilisée à aucun autre endroit.
+* Une requête du type `Document X WHERE NOT X owned_by U` revient à dire "les
+  documents n'ayant pas de relation `owned_by`". 
+* En revanche la requête `Document X WHERE NOT X owned_by U, U login "syt"`
+  revient à dire "les  documents n'ayant pas de relation `owned_by` avec
+  l'utilisateur syt". Ils peuvent avoir une relation "owned_by" avec un autre
+  utilisateur.
+
+Identité
+````````
 
+On peut utiliser la relation spéciale `identity` dans une requête pour
+rajouter une contrainte d'identité entre deux variables. C'est l'équivalent
+du ``is`` en python::
 
+  Any A WHERE A comments B, A identity B
+
+retournerait l'ensemble des objets qui se commentent eux-mêmes. La relation
+`identity` est surtout pratique lors de la définition des règles de sécurités
+avec des `RQLExpressions`.
 
 Implémentation
 ==============
diff --git a/doc/tutoriel_fr.txt b/doc/tutoriel_fr.txt
--- a/doc/tutoriel_fr.txt
+++ b/doc/tutoriel_fr.txt
@@ -1,5 +1,7 @@
 .. -*- coding: utf-8 -*-
 
+.. _tutorielRQL:
+
 ============================================
 Tutoriel "Relation Query Language" (Hercule)
 ============================================