From 9ac13d4da92bb7beaf475b60aa43d932d10d8976 Mon Sep 17 00:00:00 2001
From: Emmanuel Garette <egarette@cadoles.com>
Date: Sat, 6 Feb 2021 16:41:10 +0100
Subject: [PATCH] update doc

---
 doc/family.md   |   4 +-
 doc/fill.md     | 138 ++++++++++++++++++++++++++++++------------------
 doc/variable.md |  10 ++--
 3 files changed, 95 insertions(+), 57 deletions(-)

diff --git a/doc/family.md b/doc/family.md
index dbf0b073..170e868d 100644
--- a/doc/family.md
+++ b/doc/family.md
@@ -57,9 +57,9 @@ Pour cacher une famille :
 <family name="my_family" hidden="True"/>
 ```
 
-## Famille crées dynamiquement
+## Famille crée dynamiquement
 
-Pour créer une famille crées dynamiquement, il faut créer une family fictive lié à une variable.
+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 :
diff --git a/doc/fill.md b/doc/fill.md
index 47b1b4ce..811cb7a0 100644
--- a/doc/fill.md
+++ b/doc/fill.md
@@ -6,27 +6,33 @@ Une variable calculée est une variable donc sa valeur est le résultat d'une fo
 
 Créons une variable dont la valeur est retournée par la fonction "return_no" :
 
-```<variables>
+```
+<variables>
     <family name="family">
         <variable name="my_calculated_variable"/>
     </family>
 </variables>
 <constraints>
     <fill name="return_no" target="my_calculated_variable"/>
-</constraints>```
+</constraints>
+```
 
 Puis créons la fonction "return_no" :
 
-```def return_no():
-    return 'no'```
+```
+def return_no():
+    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" :
 
-```<variable name="my_calculated_variable">
+```
+<variable name="my_calculated_variable">
     <value>yes</value>
-</variable>```
+</variable>
+```
 
 Cette valeur par défaut sera complètement ignorée.
 
@@ -34,7 +40,9 @@ Cette valeur par défaut sera complètement ignoré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 :
 
-```<variable name="my_calculated_variable" hidden="True"/>```
+```
+<variable name="my_calculated_variable" hidden="True"/>
+```
 
 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.
 
@@ -47,16 +55,20 @@ Dans ce cas un calcul peut retourner None, mais surtout un utilisateur peut spé
 
 Déclarons un calcul avec paramètre :
 
-```<constraints>
+```
+<constraints>
     <fill name="return_value" target="my_calculated_variable">
         <param>no</param>
     </fill>
-</constraints>```
+</constraints>
+```
 
 Créons la fonction correspondante :
 
-```def return_value(value):
-    return value```
+```
+def return_value(value):
+    return value
+```
 
 La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "no".
 
@@ -64,11 +76,13 @@ La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fix
 
 Déclarons une contrainte avec un paramètre nommée :
 
-```<constraints>
+```
+<constraints>
     <fill name="return_value" target="my_calculated_variable">
         <param name="valeur">no</param>
     </fill>
-</constraints>```
+</constraints>
+```
 
 Dans ce cas la fonction return_value sera exécuté avec le paramètre nommé "valeur" dont sa valeur sera "no".
 
@@ -76,18 +90,22 @@ Dans ce cas la fonction return_value sera exécuté avec le paramètre nommé "v
 
 Déclarons un calcul avec paramètre avec un nombre :
 
-```<constraints>
+```
+<constraints>
     <fill name="return_value_with_number" target="my_calculated_variable">
         <param type="number">1</param>
     </fill>
-</constraints>```
+</constraints>
+```
 
 Créons la fonction correspondante :
 
-```def return_value_with_number(value):
+```
+def return_value_with_number(value):
     if value == 1:
         return 'no'
-    return 'yes'```
+    return 'yes'
+```
 
 La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "1".
 
@@ -95,7 +113,8 @@ La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fix
 
 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 :
 
-```<variables>
+```
+<variables>
     <family name="family">
         <variable name="my_calculated_variable"/>
         <variable name="my_variable" type="number" description="My variable">
@@ -107,7 +126,8 @@ Créons deux variables avec une contrainte de type variable qui contient le nom
     <fill name="return_value_with_number" target="my_calculated_variable">
         <param type="variable">my_variable</param>
     </fill>
-</constraints>```
+</constraints>
+```
 
 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".
@@ -116,7 +136,8 @@ Si la valeur de "my_variable" est différent de 1, la valeur par défaut de la v
 
 Créons une variable et la contrainte :
 
-```<variables>
+```
+<variables>
     <family name="family">
         <variable name="my_calculated_variable" type="string" description="My calculated variable"/>
     </family>
@@ -125,7 +146,8 @@ Créons une variable et la contrainte :
     <fill name="return_value" target="my_calculated_variable">
         <param type="information">server_name</param>
     </fill>
-</constraints>```
+</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".
@@ -136,24 +158,24 @@ Suivant le contexte une variable peut exister ou ne pas exister.
 
 Un paramètre de type "variable" peut être "optional" :
 
-    <variables>
-        <family name="family">
-            <variable name="my_calculated_variable"/>
-        </family>
-    </variables>
-    <constraints>
-        <fill name="return_value" target="my_calculated_variable">
-            <param type="variable" optional="True">unknow_variable</param>
-        </fill>
-    </constraints>
+```
+<variables>
+    <family name="family">
+        <variable name="my_calculated_variable"/>
+    </family>
+</variables>
+<constraints>
+    <fill name="return_value" target="my_calculated_variable">
+        <param type="variable" optional="True">unknow_variable</param>
+    </fill>
+</constraints>
+```
 
 Dans ce cas la fonction "return_value" est exécuté sans paramètre.
 
 ## Paramètre avec variable potentiellement désactivée
 
-FIXME :
-
-<!ATTLIST param notraisepropertyerror (True|False) "False">
+FIXME : <!ATTLIST param notraisepropertyerror (True|False) "False">
 
 Il n'y a pas spécialement de test !
 
@@ -172,7 +194,8 @@ FIXME :
 
 Il est possible de faire un calcul avec comme paramètre une variable dynamique mais pour une suffix particulier :
 
-```<variables>
+```
+<variables>
     <family name='family'>
         <variable name='suffixes' type='string' description="Suffixes of dynamic family" multi="True">
             <value>val1</value>
@@ -190,7 +213,8 @@ Il est possible de faire un calcul avec comme paramètre une variable dynamique
     <fill name="return_value" target="my_calculated_variable">
         <param type="variable">vardynval1</param>
     </fill>
-</constraints>```
+</constraints>
+```
 
 Dans ce cas, valeur du paramètre de la fonction "return_value" sera la valeur de la variable "vardyn" avec le suffix "val1".
 
@@ -198,7 +222,8 @@ Dans ce cas, valeur du paramètre de la fonction "return_value" sera la valeur d
 
 Il est également possible de calculer une variable dynamique à partir d'une variable standard :
 
-```<variables>
+```
+<variables>
     <family name='family'>
         <variable name='suffixes' type='string' description="Suffixes of dynamic family" multi="True">
             <value>val1</value>
@@ -218,7 +243,8 @@ Il est également possible de calculer une variable dynamique à partir d'une va
     <fill name="return_value" target="my_calculated_variable_dyn_">
         <param type="variable">my_variable</param>
     </fill>
-</constraints>```
+</constraints>
+```
 
 Dans ce cas, les variables dynamiques "my_calculated_variable_dyn_" seront calculés à partir de la valeur de la variable "my_variable".
 Que cela soit pour la variable "my_calculated_variable_dyn_val1" et "my_calculated_variable_dyn_val2".
@@ -228,42 +254,50 @@ Si c'est ce que vous cherchez à faire, il faudra prévoir un traitement particu
 
 Dans ce cas, il faut explicitement demander la valeur du suffix dans la fonction :
 
-```<constraints>
+```
+<constraints>
     <fill name="return_value_suffix" target="my_calculated_variable_dyn_">
         <param type="variable">my_variable</param>
         <param type="suffix"/>
     </fill>
-</constraints>```
+</constraints>
+```
 
 Et ainsi faire un traitement spécifique pour ce suffix :
 
-```def return_value_suffix(value, suffix):
+```
+def return_value_suffix(value, suffix):
     if suffix == 'val1':
-        return value```
+        return value
+```
 
 ## Redéfinition des calcules
 
 Dans un premier dictionnaire déclarons notre variable et notre calcule :
 
-```<variables>
+```
+<variables>
     <family name="family">
         <variable name="my_calculated_variable"/>
     </family>
 </variables>
 <constraints>
     <fill name="return_no" target="my_calculated_variable"/>
-</constraints>```
+</constraints>
+```
 
 Dans un second dictionnaire il est possible de redéfinir le calcul :
 
-```<variables>
+```
+<variables>
     <family name="family">
         <variable name="my_calculated_variable" redefine="True"/>
     </family>
 </variables>
 <constraints>
     <fill name="return_yes" target="my_calculated_variable"/>
-</constraints>```
+</constraints>
+```
 
 Dans ce cas, à aucun moment la fonction "return_no" ne sera exécuté. Seul la fonction "return_yes" le sera.
 
@@ -275,19 +309,23 @@ Dans un second dictionnaire il est possible de supprimer ce calcul.
 
 Dans un premier dictionnaire déclarons notre variable et notre calcule :
 
-```<variables>
+```
+<variables>
     <family name="family">
         <variable name="my_calculated_variable"/>
     </family>
 </variables>
 <constraints>
     <fill name="return_no" target="my_calculated_variable"/>
-</constraints>```
+</constraints>
+```
 
 Dans un second dictionnaire supprimer ce calcul :
 
-```<variables>
+```
+<variables>
     <family name="family">
         <variable name="my_calculated_variable" redefine="True" remove_fill="True"/>
     </family>
-</variables>```
+</variables>
+```
diff --git a/doc/variable.md b/doc/variable.md
index 07a5d763..9532ef26 100644
--- a/doc/variable.md
+++ b/doc/variable.md
@@ -79,7 +79,7 @@ Pour définir le [mode](./mode.md) :
 <variable name="my_variable" mode="expert"/>
 ```
 
-## Cacher une variable
+## Variable invisible
 
 Il est possible de cacher une variable.
 
@@ -92,7 +92,7 @@ Pour cacher une variable :
 <variable name="my_variable" hidden="True"/>
 ```
 
-## Désactiver une variable
+## Variable désactive
 
 Il est possible de désactiver une variable.
 
@@ -131,7 +131,7 @@ Pour une variable multiple, il est possible de préciser plusieurs valeurs :
 </variable>
 ```
 
-Une valeur par défaut peut également être `une valeur calculer <fill.rst>`.
+Une valeur par défaut peut également être [une valeur calculer](fill.rst).
 
 ## Redéfinir une variable
 
@@ -161,7 +161,7 @@ Il est parfois utile de créer une variable si elle n'existe pas dans un autre d
 <variable name="my_variable" exists="False"/>
 ```
 
-Si cette variable existe dans un autre dictionnaire, elle ne sera pas modifier ni recréé
+Si cette variable existe dans un autre dictionnaire, elle ne sera pas modifié ni recréé
 
 ## Redéfinir une variable si elle existe
 
@@ -186,7 +186,7 @@ Voici une variable a valeur automatiquement modifiée :
 Dans ce cas la valeur est fixée à la valeur actuelle.
 Par exemple, si la valeur de cette variable est issue d'un calcul, la valeur ne sera plus recalculée.
 
-Ces variables sont généralement des variables obligatoires. En effet ces variable ne sont automatiquement modifiées que si elles sont une valeurs.
+Ces variables sont généralement des variables obligatoires. En effet ces variable ne sont automatiquement modifiées que si elles ont une valeurs.
 
 ## Variable à valeur en lecture seule automatique