From 683bd862f5a7429801c68fd85e5184b08779499d Mon Sep 17 00:00:00 2001
From: Emmanuel Garette <egarette@cadoles.com>
Date: Sat, 30 Jan 2021 19:42:46 +0100
Subject: [PATCH] documentation

---
 doc/auto.rst                 |  23 -----
 doc/check.rst                |   2 +
 doc/condition.rst            |   1 +
 doc/family.rst               |  79 +++++++++++++++
 doc/fill.rst                 |  63 ++++++++----
 doc/index.rst                |   0
 doc/mode.rst                 |   8 ++
 doc/variable.rst             | 186 ++++++++++++++++++++++++++++++++++-
 doc/variables.rst            |   9 ++
 src/rougail/data/rougail.dtd |   1 +
 10 files changed, 325 insertions(+), 47 deletions(-)
 delete mode 100644 doc/auto.rst
 create mode 100644 doc/check.rst
 create mode 100644 doc/condition.rst
 create mode 100644 doc/family.rst
 create mode 100644 doc/index.rst
 create mode 100644 doc/mode.rst
 create mode 100644 doc/variables.rst

diff --git a/doc/auto.rst b/doc/auto.rst
deleted file mode 100644
index 322719f9..00000000
--- a/doc/auto.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-Valeur automatiquement modifiée
-===============================
-
-Une variable avec valeur automatiquement modifiée est une variable dont la valeur sera considéré comme modifié quand le serveur sera déployé.
-
-Voici un variable a valeur automatiquement modifiée :
-
-    <variable name="my_variable" type="oui/non" description="My variable" auto_save="True">
-
-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.
-
-Valeur en lecture seule automatique
-===================================
-
-Une variable avec valeur en lecture seule automatique est une variable dont la valeur ne sera plus modifiable par l'utilisateur quand le serveur sera déployé.
-
-Voici un variable à valeur en lecture seule automatique :
-
-    <variable name="my_variable" type="oui/non" description="My variable" auto_freeze="True">
-
-Dans ce cas la valeur est fixée à la valeur actuelle et elle ne sera plus modifiable par l'utilisateur.
-Par exemple, si la valeur de cette variable est issue d'un calcul, la valeur ne sera plus recalculée.
diff --git a/doc/check.rst b/doc/check.rst
new file mode 100644
index 00000000..451dba53
--- /dev/null
+++ b/doc/check.rst
@@ -0,0 +1,2 @@
+<!ATTLIST variable remove_check (True|False) "False">            
+
diff --git a/doc/condition.rst b/doc/condition.rst
new file mode 100644
index 00000000..c42ac529
--- /dev/null
+++ b/doc/condition.rst
@@ -0,0 +1 @@
+<!ATTLIST variable remove_condition (True|False) "False">
diff --git a/doc/family.rst b/doc/family.rst
new file mode 100644
index 00000000..f3c9ef41
--- /dev/null
+++ b/doc/family.rst
@@ -0,0 +1,79 @@
+Famille
+=======
+
+Une famille
+-----------
+
+Une famille est un conteneur de variables.
+
+Pour décrire une famille il faut mettre au minimum un nom :
+
+    <family name="my_family"/>
+
+Cette famille doit être placé dans une balise "variables" :
+
+    <variables>
+        <family name="my_family"/>
+    </variables>
+
+Description et aide sur la famille
+----------------------------------
+
+En plus d'un nom, il est possible de mettre une "description" à la famille. C'est une information "utilisateur" qui nous permettra d'avoir des informations complémentaires sur le contenu de cette famille :
+
+    <family name="my_family" description="This is a great family"/>
+
+En plus de la description, il est possible de préciser une aide complémentaire :
+
+    <family name="my_family" help="This is a great family"/>
+
+Mode de la famille
+------------------
+
+Le mode par défaut d'une famille correspond au mode le plus petite des variables dans cette famille.
+
+Changer le mode d'une famille permet de définir le mode par défaut des variables inclusent dans cette famille.
+
+Pour définir le mode :
+
+   <family name="my_family" mode="expert"/>
+
+Cacher une famille
+------------------
+
+Il est possible de cacher une famille, ainsi toutes les variables inclusent dans cette famille.
+
+Cacher une famille signifie qu'elle ne sera pas visible lorsqu'on modifie la configuration du service.
+Par contre ces variables sont accessibles lorsqu'on va utiliser ces variables.
+
+Pour cacher une famille :
+
+   <family name="my_family" hidden="True"/>
+
+Les familles crées dynamiquement
+--------------------------------
+
+Pour créer une famille crées 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.rst b/doc/fill.rst
index 8472836a..9e693b60 100644
--- a/doc/fill.rst
+++ b/doc/fill.rst
@@ -6,11 +6,11 @@ Une variable calculée est une variable donc sa valeur est le résultat d'une fo
 Variable avec une valeur par défaut calculée
 --------------------------------------------
 
-Créons une variable de type "oui/non" donc la valeur est retournée par la fonction "return_no" :
+Créons une variable dont la valeur est retournée par la fonction "return_no" :
 
     <variables>
         <family name="family">
-            <variable name="my_calculated_variable" type="oui/non" description="My calculated variable"/>
+            <variable name="my_calculated_variable"/>
         </family>
     </variables>
     <constraints>
@@ -20,14 +20,14 @@ Créons une variable de type "oui/non" donc la valeur est retournée par la fonc
 Puis créons la fonction "return_no" :
 
     def return_no():
-        return 'non'
+        return 'no'
 
-Dans ce cas, la valeur par défaut est la valeur retournée par la fonction (ici "non"), elle sera calculée tant que l'utilisateur n'a pas de spécifié une valeur à cette variable.
+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" type="oui/non" description="My calculated variable">
-        <value>oui</value>
+    <variable name="my_calculated_variable">
+        <value>yes</value>
     </variable>
 
 Cette valeur par défaut sera complètement ignorée.
@@ -37,7 +37,7 @@ 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 :
 
-    <variable name="my_calculated_variable" type="oui/non" description="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.
 
@@ -54,7 +54,7 @@ Déclarons un calcul avec paramètre :
 
     <constraints>
         <fill name="return_value" target="my_calculated_variable">
-            <param>non</param>
+            <param>no</param>
         </fill>
     </constraints>
 
@@ -63,7 +63,7 @@ Créons la fonction correspondante :
     def return_value(value):
         return value
 
-La variable aura donc "non" comme valeur puisque le paramètre aura la valeur fixe "non".
+La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "no".
 
 Paramètre nommée
 ----------------
@@ -72,11 +72,11 @@ Déclarons une contrainte avec un paramètre nommée :
 
     <constraints>
         <fill name="return_value" target="my_calculated_variable">
-            <param name="valeur">non</param>
+            <param name="valeur">no</param>
         </fill>
     </constraints>
 
-Dans ce cas la fonction return_value sera exécuté avec le paramètre nommé "valeur" dont sa valeur sera "non".
+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
 ------------------------
@@ -93,10 +93,10 @@ Créons la fonction correspondante :
 
     def return_value_with_number(value):
         if value == 1:
-            return 'non'
-        return 'oui'
+            return 'no'
+        return 'yes'
 
-La variable aura donc "non" comme valeur puisque le paramètre aura la valeur fixe "1".
+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
 -------------------------------------------------------
@@ -105,7 +105,7 @@ Créons deux variables avec une contrainte de type variable qui contient le nom
 
     <variables>
         <family name="family">
-            <variable name="my_calculated_variable" type="oui/non" description="My calculated variable"/>
+            <variable name="my_calculated_variable"/>
             <variable name="my_variable" type="number" description="My variable">
                 <value>1</value>
             </variable>
@@ -117,8 +117,8 @@ Créons deux variables avec une contrainte de type variable qui contient le nom
         </fill>
     </constraints>
 
-Si l'utilisateur laisse la valeur 1 à "my_variable", la valeur par défault de la variable "my_calculated_variable" sera "non".
-Si la valeur de "my_variable" est différent de 1, la valeur par défaut de la variable "my_calculated_variable" sera "oui".
+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
 ------------------------------------------------------------------------
@@ -148,7 +148,7 @@ Un paramètre de type "variable" peut être "optional" :
 
     <variables>
         <family name="family">
-            <variable name="my_calculated_variable" type="oui/non" description="My calculated variable"/>
+            <variable name="my_calculated_variable"/>
         </family>
     </variables>
     <constraints>
@@ -263,7 +263,7 @@ Dans un premier dictionnaire déclarons notre variable et notre calcule :
 
     <variables>
         <family name="family">
-            <variable name="my_calculated_variable" type="oui/non" description="My calculated variable"/>
+            <variable name="my_calculated_variable"/>
         </family>
     </variables>
     <constraints>
@@ -283,3 +283,28 @@ Dans un second dictionnaire il est possible de redéfinir le calcul :
 
 Dans ce cas, à aucun moment la fonction "return_no" ne sera exécuté. Seul la fonction "return_yes" le sera.
 
+Redéfinition avec suppression d'un calcul
+-----------------------------------------
+
+Il se peut que dans un dictionnaire on décide de définir une valeur par défaut à une variable via un calcul.
+
+Dans un second dictionnaire il est possible de supprimer ce calcul.
+
+Dans un premier dictionnaire déclarons notre variable et notre calcule :
+
+    <variables>
+        <family name="family">
+            <variable name="my_calculated_variable"/>
+        </family>
+    </variables>
+    <constraints>
+        <fill name="return_no" target="my_calculated_variable"/>
+    </constraints>
+
+Dans un second dictionnaire supprimer ce calcul :
+
+    <variables>
+        <family name="family">
+            <variable name="my_calculated_variable" redefine="True" remove_fill="True"/>
+        </family>
+    </variables>
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 00000000..e69de29b
diff --git a/doc/mode.rst b/doc/mode.rst
new file mode 100644
index 00000000..66bc294e
--- /dev/null
+++ b/doc/mode.rst
@@ -0,0 +1,8 @@
+Mode
+====
+
+Il existe trois "mode" dans Rougail :
+
+- basic : variables indispensables à la mise en place d'un service
+- normal : variables couramment modifié par l'utilisateur
+- expert : variables a manipuler avec précausion et en toute connaissance de cause
diff --git a/doc/variable.rst b/doc/variable.rst
index f88ff313..66d86256 100644
--- a/doc/variable.rst
+++ b/doc/variable.rst
@@ -1,13 +1,189 @@
 Variable
 ========
 
+Un variable
+-----------
+
+Une variable est forcement dans une famille. Il faut donc déjà avoir créer une famille.
+
+Une variable est déjà un nom. C'est à dire qu'on pourra utiliser plus tard la variable via ce nom.
+
+    <variable name="my_variable"/>
+
+Description et aide sur la variable
+----------------------------------
+
+En plus d'un nom, il est possible de mettre une "description" à la variable. C'est une information "utilisateur" qui nous permettra d'avoir des informations complémentaires sur le contenu de cette variable :
+
+    <variable name="my_variable" description="This is a greate variable"/>
+
+En plus de la description, il est possible de préciser une aide complémentaire :
+
+    <variable name="my_variable" help="This is a greate variable"/>
+
+Le type de la variable
+----------------------
+
+Une variable a un type. Ce type permet de définir les valeurs acceptées par cette variable :
+
+- string : chaine de caractère (type par défaut)
+- number : un nombre
+- float : un chiffre flottant
+- boolean : True ou False si aucune valeur n'est défini la valeur par défaut cette variable sera True
+- password : un mot de passe
+- mail : une adresse mail
+- filename : nom de fichier au sens Unix (exemple : '/etc/passwd')
+- date : une date au format "%Y-%m-%d" (exemple : "2021-01-30")
+- unix_user : nom d'utilisateur au sens Unix
+- ip : n'importe quelle adresse IPv4
+- cidr : n'importe quelle adresse IPv4 au format CIDR
+- local_ip : adresse IPv4 sur un réseau local, si l'adresse IPv4 n'est pas local, un warning sera afficher mais la valeur sera accepté tout de même
+- netmask : masque d'une adresse IPv4
+- network : adresse réseau
+- network_cidr : adresse réseau au format CIDR
+- broadcast : adresse de diffusion
+- netbios : nom netbios
+- domain : nom de domaine
+- hostname : nom d'hôte
+- web_address : adresse web (http://www.cadoles.com/)
+- port : port
+- mac : adresse MAC
+- schedule : périodicité du schedule, les valeurs possibles sont "none", "daily", "weekly" ou "monthly"
+- schedulemod : type de schedule, les valeurs possibles sont "pre" ou "post"
+
+Pour définir le type d'une variable :
+
+    <variable name="my_variable" type="number"/>
+
+Variable à valeur multiple
+--------------------------
+
+Par défaut une variable ne peut acceuillir qu'une seule valeur. Il peut être utile de pouvoir spécifier plusieurs valeurs à une même variable.
+
+Pour définir une variable à valeur multiple :
+
+    <variable name="my_variable" multi="True"/>
+
+Mode de la variable
+-------------------
+
+Le mode par défaut d'une variable correspond au mode de la famille.
+
+Pour définir le mode :
+
+   <variable name="my_variable" mode="expert"/>
+
+Cacher une variable
+-------------------
+
+Il est possible de cacher une variable.
+
+Cacher une variable signifie qu'elle ne sera pas visible lorsqu'on modifie la configuration du service.
+Par contre cette variable sont accessibles lorsqu'on va l'utiliser.
+
+Pour cacher une variable :
+
+   <variable name="my_variable" hidden="True"/>
+
+Désactiver une variable
+-----------------------
+
+Il est possible de désactiver une variable.
+
+Désactiver une variable signifie qu'elle ne sera pas visible lorsqu'on modifie la configuration du service mais également lorsqu'on va l'utiliser.
+
+Pour désactiver une variable :
+
+   <variable name="my_variable" disabled="True"/>
+
 Variable obligatoire
 --------------------
 
 Variable dont une valeur est requise :
 
-    <variables>
-        <family name="family">
-            <variable name="my_variable" type="oui/non" description="My variable" mandatory="True"/>
-        </family>
-    </variables>
+    <variable name="my_variable" mandatory="True"/>
+
+Valeur par défaut d'une variable
+--------------------------------
+
+Il est possible de fixer les valeurs par défaut d'une variable :
+
+    <variable name="my_variable">
+        <value>value</value>
+    </variable>
+
+Pour une variable multiple, il est possible de préciser plusieurs valeurs :
+
+    <variable name="my_variable" multi="True">
+        <value>value 1</value>
+        <value>value 2</value>
+    </variable>
+
+Une valeur par défaut peut également être `une valeur calculer <fill.rst>`.
+
+Redéfinir une variable
+----------------------
+
+Il est possible de définir une variable dans un dictionnaire et de changer son comportement dans une second dictionnaire.
+
+Attention trois attributs ne sont redéfinisable :
+
+- name
+- type
+- multi
+
+Créons notre variable :
+
+    <variable name="my_variable"/>
+
+Et redéfinisons là :
+
+    <variable name="my_variable" redefine="True" description="New description"/>
+
+Créer une variable inexistante
+------------------------------
+
+Il est parfois utile de créer une variable si elle n'existe pas dans un autre dictionnaire :
+
+    <variable name="my_variable" exists="False"/>
+
+Si cette variable existe dans un autre dictionnaire, elle ne sera pas modifier ni recréé
+
+Redéfinir une variable si elle existe
+-------------------------------------
+
+Parfois on veut pouvoir redéfinir une variable mais seulement dans le cas où elle existe déjà :
+
+    <variable name="my_variable" redefine="True" exists="True" hidden="True"/>
+
+Variable à valeur automatiquement modifiée
+------------------------------------------
+
+Une variable avec valeur automatiquement modifiée est une variable dont la valeur sera considéré comme modifié quand le serveur sera déployé.
+
+Voici une variable a valeur automatiquement modifiée :
+
+    <variable name="my_variable" auto_save="True">
+        <value>my_value</value>
+    </variable>
+
+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.
+
+Variable à valeur en lecture seule automatique
+----------------------------------------------
+
+Une variable avec valeur en lecture seule automatique est une variable dont la valeur ne sera plus modifiable par l'utilisateur quand le serveur sera déployé.
+
+Voici un variable à valeur en lecture seule automatique :
+
+    <variable name="my_variable" auto_freeze="True"/>
+
+Dans ce cas la valeur est fixée à la valeur actuelle et elle ne sera plus modifiable par l'utilisateur.
+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 en lecteur seul que si elles sont une valeurs.
+
+<!ATTLIST variable test CDATA #IMPLIED>
diff --git a/doc/variables.rst b/doc/variables.rst
new file mode 100644
index 00000000..0b4e9933
--- /dev/null
+++ b/doc/variables.rst
@@ -0,0 +1,9 @@
+Variables
+=========
+
+La balise variable est le conteneur de l'ensemble des familles dans laquelle on pourra placer des variables :
+
+    <?xml version='1.0' encoding='UTF-8'?>
+    <rougail>
+        <variables/>
+    </rougail>
diff --git a/src/rougail/data/rougail.dtd b/src/rougail/data/rougail.dtd
index fda8fb9e..c5c37bd6 100644
--- a/src/rougail/data/rougail.dtd
+++ b/src/rougail/data/rougail.dtd
@@ -80,6 +80,7 @@
 <!ATTLIST override templating (True|False) "True">
 
 <!ELEMENT variables (family*)>
+
 <!ELEMENT family (variable*)>
 <!ATTLIST family name CDATA #REQUIRED>
 <!ATTLIST family description CDATA #IMPLIED>