docgen: more explanations

admin/generation-documents.md

@@ -45,26 +45,7 @@ La valeur à indiquer dans le champ "substituant" est à déduire des informatio
 
 ### Nommage de variables
 
-Les variables contiennent des informations importées d'objets présents dans le logiciel. Par objet, nous entendons, par exemple, un utilisateur (User), un usager (Person), etc…
+TODO
-
-Ces objets comportent plusieurs champs. On accède à ces champs en concaténant les noms de la variable qui contient un objet, et le nom des champs de ces objets.
-
-Par exemple: le créateur d'un document est disponible sous la variable `creator`. Cette variable est un objet de type `User`. Cet objet contient ces trois champs ([la liste complète est disponible ci-dessous](#sec:gendoc-var-user)):
-
-* `username`;
-* `service`;
-* `email`;
-
-Alors, pour indiquer le nom du créateur, son email et son service, on préfixe la variable par `creator`, et on ajoute les noms des champs de l'objet `User`, en commençant par une majuscule pour ces champs. Exemple:
-
-```
-Pour joindre ${creatorUsername} (service: ${creatorService}),
-vous pouvez envoyer un courriel à l'adresse ${creatorEmail}.
-```
-
-Pour nommer les variables et les concaténer, nous utilisons la syntaxe camelcase [^camelcase], avec la première lettre en bas de casse (en minuscule).
-
-[^camelcase]: <https://fr.wikipedia.org/wiki/Camel_case>
 
 #### Exemple: application aux objets "date"
 
@@ -80,41 +61,27 @@ personBirthdateShort=15/06/1980
 personBirthdateLong=15 juin 1980
 ```
 
-### Cas où une variable peut être de deux natures différentes
-
-Certaines variables peuvent être de deux natures différentes, par exemple, soit une personne, soit un tiers. Dans ce cas, les variables qui sont de noms différents sont à l'état "vide". Par exemple, le champ "date de naissance" n'est pas disponible pour un tiers, dans ce cas, il est vide.
-
-Exemple, une liste des interlocuteurs principaux. Le premier est une personne:
-
-```
-text=Maxime Berger
-firstName=Maxime
-lastName=Berger
-birthDate=19/01/1996
-type=
-job=
-```
-
-Le second est un tiers:
-
-```
-text=Jean Couteau
-firstName=Jean
-lastName=Couteau
-birthDate=
-type=Médecin
-job=Assistant social
-```
 
 ### Cas où une variable est optionnelle
 
 Lorsqu'une variable est optionnelle, si sa valeur est inconnue ou vide, alors tout ses champs apparaissent avec une chaine de caractère vide.
 
+L'arbre des variables est toujours identique, sur toute la profondeur de celles-ci. L'administrateur est garanti qu'un champ existera, même si sa valeur n'est pas présente dans la base de donnée.
+
 ## Variables disponibles par document
 
-Lorsqu'une variable n'est pas de type "texte", ses champs sont complétés par ceux décrits [dans la section suivante](#sec:gendoc-champs-objets).
+Pour chaque contexte où un document est généré, les variables disponibles sont listées [dans la section suivante](#sec:gendoc-champs-documents). Le type des variables est indiqué.
 
-### Pour chaque document
+Les variables pour chaque type sont décrites [dans la section suivante](#sec:gendoc-champs-objets):
+
+* si le type commence par une majuscule, alors cette variable comporte des sous-champs, et il faut se reporter à la description des variables pour ce type;
+* si le type commence par une minuscule, alors cette variable peut être utilisée directement dans le document:
+
+    * s'il s'agit d'un booléen (`bool`), le champ peut être utilisé dans des tests;
+    * les champs `text` et `int` peuvent faire l'objet de test sur l'égalité;
+    * les champs de type `int` peuvent faire l'objet de comparaison sur l'ordre de grandeur (par exemple, le champs `age` des objets de type `Person` peut être filtré `> 18` ou `< 18` pour distinguer les adultes des enfants).
+
+### Pour chaque document { #sec:gendoc:champs-documents }
 
 #### Paramètres pour l'administrateur fonctionnel