From ac44b1857bfc8b504b65b4b39284b92eee93d4ac Mon Sep 17 00:00:00 2001
From: Emmanuel Garette <egarette@cadoles.com>
Date: Sat, 6 Feb 2021 17:11:17 +0100
Subject: [PATCH] reorganise

---
 doc/family/REAME.md                 |   5 ++
 doc/family/auto.md                  |  29 ++++++++
 doc/{family.md => family/simple.md} |  33 +--------
 doc/fill.md                         | 103 +++++++++++++++++-----------
 4 files changed, 99 insertions(+), 71 deletions(-)
 create mode 100644 doc/family/REAME.md
 create mode 100644 doc/family/auto.md
 rename doc/{family.md => family/simple.md} (57%)

diff --git a/doc/family/REAME.md b/doc/family/REAME.md
new file mode 100644
index 00000000..1aff0572
--- /dev/null
+++ b/doc/family/REAME.md
@@ -0,0 +1,5 @@
+# Famille
+
+  - [Une famille](simple.md)
+  - [Famille crée dynamiquement](auto.md)
+
diff --git a/doc/family/auto.md b/doc/family/auto.md
new file mode 100644
index 00000000..a160285e
--- /dev/null
+++ b/doc/family/auto.md
@@ -0,0 +1,29 @@
+# Famille crée dynamiquement
+
+Pour créer une famille dynamiquement, il faut créer une family fictive lié à une variable.
+Le nom et la description de la famille et des variables qu'elle contient sera en réalité le prefix du nouveau nom/description. Le suffix viendra de la variable liée.
+
+Par exemple :
+
+```
+<family name='my_family'>
+    <variable name='varname' multi="True">
+        <value>val1</value>
+        <value>val2</value>
+    </variable>
+</family>
+<family name='my_dyn_family_' dynamic="varname description="Describe "">
+    <variable name='my_dyn_var_'/>
+</family>
+```
+
+Créera trois familles :
+
+- la famille : "my_family"
+- la famille dynamique : "my_dyn_family_val1" avec la description "Describe val1"
+- la famille dynamique : "my_dyn_family_val2" avec la description "Describe val2"
+
+Dans la famille dynamique "my_dyn_family_val1" on retrouvera une variable "my_dyn_var_val1".
+
+Bien évidement si le contenu de "varname" venait a évolué, de nouvelles familles dynamiques pouvent apparaitre ou des familles dynamiques peuvent disparaître.
+
diff --git a/doc/family.md b/doc/family/simple.md
similarity index 57%
rename from doc/family.md
rename to doc/family/simple.md
index 170e868d..76acb0d3 100644
--- a/doc/family.md
+++ b/doc/family/simple.md
@@ -1,6 +1,4 @@
-# Famille
-
-## Une famille
+# Une famille
 
 Une famille est un conteneur de variables.
 
@@ -56,32 +54,3 @@ Pour cacher une famille :
 ```
 <family name="my_family" hidden="True"/>
 ```
-
-## Famille crée dynamiquement
-
-Pour créer une famille dynamiquement, il faut créer une family fictive lié à une variable.
-Le nom et la description de la famille et des variables qu'elle contient sera en réalité le prefix du nouveau nom/description. Le suffix viendra de la variable liée.
-
-Par exemple :
-
-```
-<family name='my_family'>
-    <variable name='varname' multi="True">
-        <value>val1</value>
-        <value>val2</value>
-    </variable>
-</family>
-<family name='my_dyn_family_' dynamic="varname description="Describe "">
-    <variable name='my_dyn_var_'/>
-</family>
-```
-
-Créera trois familles :
-
-- la famille : "my_family"
-- la famille dynamique : "my_dyn_family_val1" avec la description "Describe val1"
-- la famille dynamique : "my_dyn_family_val2" avec la description "Describe val2"
-
-Dans la famille dynamique "my_dyn_family_val1" on retrouvera une variable "my_dyn_var_val1".
-
-Bien évidement si le contenu de "varname" venait a évolué, de nouvelles familles dynamiques pouvent apparaitre ou des familles dynamiques peuvent disparaître.
diff --git a/doc/fill.md b/doc/fill.md
index 811cb7a0..a46c35a7 100644
--- a/doc/fill.md
+++ b/doc/fill.md
@@ -2,7 +2,9 @@
 
 Une variable calculée est une variable donc sa valeur est le résultat d'une fonction python.
 
-## Variable avec une valeur par défaut calculée
+## Valeur de la variable
+
+### Variable avec une valeur par défaut calculée
 
 Créons une variable dont la valeur est retournée par la fonction "return_no" :
 
@@ -26,7 +28,7 @@ def return_no():
 
 Dans ce cas, la valeur par défaut est la valeur retournée par la fonction (ici "no"), elle sera calculée tant que l'utilisateur n'a pas de spécifié une valeur à cette variable.
 
-Si l'utilisateur à définit une valeur par défaut à "my_calculated_variable" :
+Attention, si une valeur par défaut est définit dans la variable "my_calculated_variable" :
 
 ```
 <variable name="my_calculated_variable">
@@ -34,9 +36,9 @@ Si l'utilisateur à définit une valeur par défaut à "my_calculated_variable"
 </variable>
 ```
 
-Cette valeur par défaut sera complètement ignorée.
+Cette valeur par défaut sera complètement ignorée. C'est le calcul qui en définira la valeur.
 
-## Variable avec une valeur calculée
+### Variable avec une valeur calculée
 
 En ajoutant le paramètre "hidden" à "True" dans la variable précédente, l'utilisateur n'aura plus la possibilité de modifié la valeur. La valeur de la variable sera donc systématiquement calculée :
 
@@ -46,12 +48,14 @@ En ajoutant le paramètre "hidden" à "True" dans la variable précédente, l'ut
 
 Si une condition "hidden_if_in" est spécifié à la variable, la valeur sera modifiable par l'utilisateur si elle n'est pas cachée mais elle sera systèmatiquement calculée (même si elle a déjà était modifiée) si la variable est cachée.
 
-## Variable avec valeur calculée obligatoire
+### Variable avec valeur calculée obligatoire
 
-Par défaut les variables calculées ne sont pas des varibles obligatoires.
-Dans ce cas un calcul peut retourner None, mais surtout un utilisateur peut spécifier une valeur nulle à cette variable. Dans ce cas le calcul ne sera pas réalisé.
+Par défaut les variables calculées ne sont pas des variables obligatoires.
+Dans ce cas un calcul peut retourner "None" ou "", mais surtout un utilisateur peut spécifier une valeur nulle à cette variable. Dans ce cas le calcul ne sera plus réalisé.
 
-## Fonction avec une valeur fixe comme paramètre positionnel
+## Paramètre de la fonction
+
+### Paramètre positionnel
 
 Déclarons un calcul avec paramètre :
 
@@ -72,7 +76,7 @@ def return_value(value):
 
 La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "no".
 
-## Paramètre nommée
+### Paramètre nommée
 
 Déclarons une contrainte avec un paramètre nommée :
 
@@ -86,7 +90,21 @@ Déclarons une contrainte avec un paramètre nommée :
 
 Dans ce cas la fonction return_value sera exécuté avec le paramètre nommé "valeur" dont sa valeur sera "no".
 
-## Paramètre avec un nombre
+### Paramètre de type texte
+
+Dans l'exemple précédent :
+
+```
+<constraints>
+    <fill name="return_value" target="my_calculated_variable">
+        <param>no</param>
+    </fill>
+</constraints>
+```
+
+Le paramètre est de type texte (ou "string").
+
+### Paramètre de type nombre
 
 Déclarons un calcul avec paramètre avec un nombre :
 
@@ -109,7 +127,7 @@ def return_value_with_number(value):
 
 La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "1".
 
-## Paramètre dont la valeur est issue d'une autre variable
+### Paramètre de type variable
 
 Créons deux variables avec une contrainte de type variable qui contient le nom de la variable dont sa valeur sera utilisé comme paramètre :
 
@@ -132,27 +150,7 @@ Créons deux variables avec une contrainte de type variable qui contient le nom
 Si l'utilisateur laisse la valeur 1 à "my_variable", la valeur par défault de la variable "my_calculated_variable" sera "no".
 Si la valeur de "my_variable" est différent de 1, la valeur par défaut de la variable "my_calculated_variable" sera "yes".
 
-## Paramètre dont la valeur est issue d'une information de la configuration
-
-Créons une variable et la contrainte :
-
-```
-<variables>
-    <family name="family">
-        <variable name="my_calculated_variable" type="string" description="My calculated variable"/>
-    </family>
-</variables>
-<constraints>
-    <fill name="return_value" target="my_calculated_variable">
-        <param type="information">server_name</param>
-    </fill>
-</constraints>
-```
-
-Dans ce cas, l'information de la configuration "server_name" sera utilisé comme valeur de la variable "my_calculated_variable".
-Si l'information n'existe pas, la paramètre aura la valeur "None".
-
-## Paramètre avec variable potentiellement non existante
+### Paramètre avec variable potentiellement non existante
 
 Suivant le contexte une variable peut exister ou ne pas exister.
 
@@ -173,13 +171,15 @@ Un paramètre de type "variable" peut être "optional" :
 
 Dans ce cas la fonction "return_value" est exécuté sans paramètre.
 
-## Paramètre avec variable potentiellement désactivée
+Si maintenant on créé un nouveau dictionnaire en créant cette variable, la fonction sera exécuté avec le paramètre.
+
+### Paramètre avec variable potentiellement désactivée
 
 FIXME : <!ATTLIST param notraisepropertyerror (True|False) "False">
 
 Il n'y a pas spécialement de test !
 
-## Les variables suiveuses
+### Les variables suiveuses
 
 FIXME : 
 
@@ -188,11 +188,11 @@ FIXME :
 - tests/flattener_dicos/10leadership_autoleader/00-base.xml
 - tests/flattener_dicos/10leadership_autoleader_expert/00-base.xml
 
-## Les variables dynamiques
+### Les variables dynamiques
 
-### Paramètre avec variable dynamique
+#### Paramètre avec variable dynamique
 
-Il est possible de faire un calcul avec comme paramètre une variable dynamique mais pour une suffix particulier :
+Il est possible de faire un calcul avec comme paramètre [une variable d'une famille dynamique](family/auto.md) mais pour une suffix particulier :
 
 ```
 <variables>
@@ -218,9 +218,9 @@ Il est possible de faire un calcul avec comme paramètre une variable dynamique
 
 Dans ce cas, valeur du paramètre de la fonction "return_value" sera la valeur de la variable "vardyn" avec le suffix "val1".
 
-### Calcule d'une variable dynamique
+#### Calcule d'une variable dynamique
 
-Il est également possible de calculer une variable dynamique à partir d'une variable standard :
+Il est également possible de calculer [une variable d'une famille dynamique](family/auto.md) à partir d'une variable standard :
 
 ```
 <variables>
@@ -329,3 +329,28 @@ Dans un second dictionnaire supprimer ce calcul :
     </family>
 </variables>
 ```
+
+FIXME <!ATTLIST param type (string|number|variable|information|suffix) "string">
+
+### Paramètre de type information
+
+Le paramètre peut être la valeur est issue d'une information de la configuration.
+
+Créons une variable et la contrainte :
+
+```
+<variables>
+    <family name="family">
+        <variable name="my_calculated_variable" type="string" description="My calculated variable"/>
+    </family>
+</variables>
+<constraints>
+    <fill name="return_value" target="my_calculated_variable">
+        <param type="information">server_name</param>
+    </fill>
+</constraints>
+```
+
+Dans ce cas, l'information de la configuration "server_name" sera utilisé comme valeur de la variable "my_calculated_variable".
+Si l'information n'existe pas, la paramètre aura la valeur "None".
+