preliminaries

docs/gettingstarted.rst

@@ -97,17 +97,34 @@ The variables
 
 Here is a :term:`dictionary` example with a variable into it:
 
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/03/config.yaml
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/firefox/00-proxy.yml
    :linenos:
    :language: yaml
    :caption: A rougail dictionnary file with a variable named `proxy_mode`. It's the Rougail YAML dictionary format.
    :name: RougailDictionaryFirstVariable
 
-:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/03/config.yaml>`
+:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/firefox/00-proxy.yml>`
 
-Here we declare a **variable** named `proxy_mode` with a variable :term:`default value`.
+Here we declare a **variable** named `proxy_mode` without a :term:`default value`.
 A variable can be defined with no default value at all.
 
+Here is the same variable with a description label:
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
+   :linenos:
+   :language: yaml
+   :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a description.
+   :name: RougailDictionaryFirstVariableDescription
+
+The same with a default value:
+
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_005/firefox/00-proxy.yml
+   :linenos:
+   :language: yaml
+   :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value.
+   :name: RougailDictionaryFirstVariableDefault
+
 variable
 
     A variable is a declaration unit that represents a business domain metaphor,
@@ -115,6 +132,10 @@ variable
     in a application, but a variable represents something more that a configuration option.
     It provides a business domain specific representation unit.
 
+.. todo:: définir une variable avec une description, un type, l'inférence de type,
+          les notations condensées,
+          une family sans variable doit avoir un type: family,
+
 .. note:: Dictionaries can just define a list of variables, but we will see that
           we can specify a lot more. We can define variables **and** their relations,
           **and** the relations between them.

docs/index.rst

@@ -8,6 +8,8 @@
 Rougail
 ===========
 
+.. todolist::
+
 .. image:: images/logo.png
 
 - is a `delicious cooked dish <https://fr.wikipedia.org/wiki/Rougail>`_ from the Mauritius  and Reunion Islands,

docs/tutorial/preliminary.rst

@@ -5,8 +5,60 @@ Preliminaries
 
    You need to know how to:
 
-   - manipulate a rougail :term:`dictionary`
-   - use a rougail format version
-   - use the rougail command line
+   - create a Rougail :term:`dictionary`
+   - define a Rougail format version
+   - define a Rougail :term:`variable`
+
+.. type-along:: Workshop
+
+   - define a Rougail :term:`dictionary`
+
+     :ref:`Here is an empty Rougail dictionnary <RougailDictionaryEmptyFile>`
+
+   - define a variable and its default value
+
+     :ref:`Here is a first Rougail variable in a Rougail dictionnary <RougailDictionaryFirstVariable>`
+
+   - define a variable with a description
+
+     :ref:`Here is a Rougail variable with a description <RougailDictionaryFirstVariableDescription>`
+
+   - define a variable with a description and a default value
+
+     :ref:`Here is a Rougail variable with a description <RougailDictionaryFirstVariableDefault>`
+
+
+The integrator role
+----------------------
+
+.. glossary::
+
+    integrator
+
+        An integrator in the Rougail logic is the person who writes the dictionaries.
+        He has the responsibilité of the integration process, that is,
+        defines the variables and the relationship between them, the variables that are allowed
+        (or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency**
+        of the variables.
+
+        .. image:: images/integrator.png
+
+.. important:: Note that there is a strong consistency, it means that the validation is done across
+               the entire structure, not only with a schema (type) validation system.
+
+The operator role
+---------------------
+
+.. glossary::
+
+    operator
+
+        An operator ih the Rougail logic is the person who gives values to the pre-defined variables,
+        his responsabilities are to set variable values correctly.
+
+        The :term:`user values`, that is the values that have been set by the operator, are validated
+        by the dictionary structure.
+
+        .. image:: images/operator.png
+
 
-- :ref:`Here is an empty rougail dictionnary <RougailDictionaryEmptyFile>`