modifs

docs/dictionary.rst

@@ -21,7 +21,7 @@ It is also possible to :term:`redefine` elements to change the behavior of a fam
 The default namespace
 -------------------------
 
-The families and variables contained in these dictionaries are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace :doc:`with the `variable_namespace` parameter of the configuration <configuration>`.
+The families and variables contained in these dictionaries are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace with the :term:`variable namespace <variable_namespace>` parameter of the :doc:`configuration <configuration>`.
 
 This namespace is a bit special, it can access variables in another namespace.
 

docs/family.rst

@@ -1,19 +1,28 @@
-A family
+The families
-============
+=============
 
 Synopsis
 ---------
 
-A family is a container of variables and subfamily.
+.. glossary::
+
+   family
+   families
+
+       A family of variables is simply a collection of variables that refer to
+       the same business model category. It's just a variables container.
+       Think of it as a container as well as a namespace.
 
 .. attention:: A family without a subfamily or subvariable will be automatically deleted.
 
-Name
+Naming conventions
--------------
+------------------------
 
-It is with this name that we will be able to interact with the family.
+It is with its name that we will be able to interact with the family.
 
-It's best to follow the :ref:`convention on variable names`.
+.. seealso:: 
+
+    Have a look at the :ref:`convention on variable names`.
 
 Shorthand declaration
 ----------------------------
@@ -35,7 +44,7 @@ If you add comment in same line of name, this comment is use as description:
 Parameters
 ---------------
 
-.. FIXME: faire une page sur la "convention on variable names"
+.. todo:: faire une page sur la "convention on variable names"
 
 .. list-table::
    :widths: 15 45

docs/gettingstarted.rst

@@ -4,17 +4,14 @@ Getting started
 What is a consistency handling system ?
 ------------------------------------------------
 
-.. questions::
+.. questions:: Question
 
     "OK, I have understood that the Rougail stuff enables me to take advantage of :xref:`tiramisu`.
-
     But what is all this for?
-
     What is exactly a consistency handling system?
-
     And again, what is this :xref:`tiramisu` library used for?"
 
-    *Answer*: Well, now we explain what this :xref:`tiramisu` library is, and how we are using it.
+    **Answer**: Well, now we explain what this :xref:`tiramisu` library is, and how we are using it.
 
 .. glossary::
 
@@ -30,9 +27,7 @@ What is a consistency handling system ?
         Here is the :xref:`tiramisu library`.
 
 In the Rougail scope, we call it :term:`variable`\ s and :term:`families`.
-In Rougail, the families and variables are located in the :term:`structure files <dictionaries>`.
+In Rougail, the families and variables are located in the :term:`structure files <dictionaries>` (the term "dictionary" is also used as a synonym).
-
-And this is what we are going to explain in this page.
 
 The structure files
 ---------------------
@@ -43,31 +38,27 @@ The structure files
    dictionary
    dictionaries
 
-       A dictionary in the Rougail meaning is a YAML file that describes variables
+       A dictionary or a a structure file in the Rougail meaning is a YAML file that describes variables
        and their dependencies / consistencies.
        There can be a lot of dictionary files located in many different folders.
 
        Rougail reads all the dictionaries and loads them into a single object
        that handles the variables consistency.
 
-       A dictionary file is a structure file, we call a dictionary a structure file.
-
 .. image:: images/schema.png
 
 The main advantage is that declaring variables and writing consistency is as simple
 as writing YAML. With Rougail it is not necessary to write :term:`Tiramisu` code any more.
 It simplifies a lot of things.
 
-And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative mode (that is, in a YAML file).
+And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative style (that is, in a YAML file).
 
-Once the structure files are loaded by Rougail, we find all the power of the :term:`Tiramisu` configuration management tool.
+Once the structure files are loaded by Rougail, the Tiramisu configuration management tool can check the consistency of the variables between them.
 
 The YAML structure files format
 ------------------------------------
 
-Before getting started with Rougail we need to learn the specifics of the YAML dictionaries file format (as well as some templating concepts).
+We need to learn first the specifics of the YAML dictionaries file format in Rougail, as well as some templating concepts.
-
-.. todo:: parler de jinja https://jinja.palletsprojects.com
 
 Here is an empty rougail dictionary YAML file
 
@@ -106,7 +97,6 @@ The variables
 Here is a :term:`structure file <dictionary>` example with a variable into it:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/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
@@ -115,15 +105,12 @@ Here is a :term:`structure file <dictionary>` example with a variable into it:
     ---
     proxy_mode:
 
-:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml>`
-
 Here we declare a **variable** named `proxy_mode` without a 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_011/firefox/00-proxy.yml
-   :linenos:
    :language: yaml
    :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a description.
    :name: RougailDictionaryFirstVariableDescription
@@ -136,7 +123,6 @@ Here is the same variable with a description label:
 The same with a default value:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/00-proxy.yml
-   :linenos:
    :language: yaml
    :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value.
    :name: RougailDictionaryFirstVariableDefault
@@ -149,108 +135,15 @@ The same with a default value:
 
 variable
 
-    A variable is a declaration unit that represents a business domain metaphor,
+    A :term:`variable` is a declaration unit that represents a business domain metaphor,
     the most common example is that a variable that represents a configuration option
     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.
-
-In the next step, we will explain through a tutorial how to construct a list of variables.
-
 Families of variables
 --------------------------
 
-.. glossary::
+family
 
-   family
+    A :term:`family` is simply a container of variables and subfamily.
-   families
-
-       A family of variables is simply a collection of variables that refer to
-       the same business model category. It's just a variables container.
-       Think of it as a container as well as a namespace.
-
-A "hello world" with Rougail
-------------------------------
-
-We're gonna make the simplest possible example.
-
-.. prerequisites:: Prerequisites
-
-    We assume that Rougail's library is installed on your computer (or in a virtual environment).
-
-.. exercise:: Hello world's workshop
-
-    Here is the tree structure we want to have::
-
-        workplace
-        ├── dict
-        │   ├── hello.yml
-        └── hello.py
-
-- Let's make a :file:`workplace` directory, with a :file:`dict` subfolder.
-- First, we need a :term:`dictionary`, so let's make the :file:`hello.yml` file
-  which is located in the :file:`dict` subfolder, with the following content:
-
-.. code-block:: yaml
-   :caption: The `hello.yaml` file
-
-    ---
-    version: '1.1'
-    hello:
-      default: world
-
-.. todo:: mettre un appel à la CLI pour lancer le truc
-
-We launch the script:
-
-.. code-block:: bash
-
-    python hello.py
-
-And we obtain the following result:
-
-.. code-block:: python
-
-    {'rougail.hello': 'world'}
-
-**Congratulations ! You have successfully completed your first Rougail script.**
-
-A "Hello, <name> " sample with a family
-------------------------------------------
-
-Let's continuing on our "Hello world" theme and add a :term:`family` container.
-
-.. code-block:: yaml
-   :caption: the :file:`hello.yml` file
-   :linenos:
-
-    ---
-    version: '1.1'
-    world:
-      description: Hello world family container
-      name:
-        description: Somebody to say hello
-        default: rougail
-
-Here, we have a family named `world`.
-This family contains a variable named `name`
-
-Again, let's validate this YAML file against Rougail's API:
-
-.. code-block:: bash
-
-    python hello.py
-
-We then have the output:
-
-.. code-block:: python
-
-    {'rougail.world.name': 'rougail'}
 

docs/index.rst

@@ -10,11 +10,32 @@ Rougail
 
 .. todolist::
 
+
+.. todo:: définir les termes suivants
+
+    family.rst:25: WARNING: label non défini: 'convention on variable names'
+    /family.rst:114: WARNING: term not in glossary: 'calculation'
+    /variable.rst:39: WARNING: label non défini: 'convention on variable names'
+    /variable.rst:83: WARNING: term not in glossary: 'leading'
+    /variable.rst:100: WARNING: term not in glossary: 'required'
+    /variable.rst:102: WARNING: term not in glossary: 'leader'
+    /variable.rst:102: WARNING: term not in glossary: 'follower'
+    /variable.rst:126: WARNING: term not in glossary: 'multiple'
+    /variable.rst:126: WARNING: term not in glossary: 'multiple'
+    /variable.rst:131: WARNING: term not in glossary: 'calculation'
+    /variable.rst:143: WARNING: term not in glossary: 'calculation'
+    /variable.rst:148: WARNING: term not in glossary: 'calculation'
+    /variable.rst:153: WARNING: term not in glossary: 'calculation'
+    /dictionary.rst:9: WARNING: term not in glossary: 'templates'
+    /dictionary.rst:19: WARNING: term not in glossary: 'redefine'
+    /dictionary.rst:24: WARNING: term not in glossary: 'variable_namespace'
+
+
 .. image:: images/logo.png
 
 - is a `delicious cooked dish <https://fr.wikipedia.org/wiki/Rougail>`_ from the Mauritius  and Reunion Islands,
 
-- it is also a `Python3 <https://www.python.org/>`_ library  which enables us to conveniently load application :term:`variable`\ s in a simple `YAML <https://yaml.org/>`_ format in such a way that the end user consumer can handle them consistently (that is, against an user-defined consistency).
+- it is also a `Python <https://www.python.org/>`_ library  which enables us to conveniently load application :term:`variable`\ s in a simple `YAML <https://yaml.org/>`_ format in such a way that the end user consumer can handle them consistently (that is, against an user-defined consistency).
 
 In other words, using Rougail in your application or your python libraries can tansform end user consumer defined consistency rules into highly consistent business objects.
 

docs/tutorial/index.rst

@@ -1,29 +1,35 @@
 Tutorial with a real world sample
 =====================================
 
-Here's a quite well supplied tutorial, we're gonna start with a use case that comes from the real world.
+Here is a fairly complete tutorial, this is a use case that comes from the real world.
+At the end of the tutorial you will have a good understanding of rougail.
 
 .. objectives:: Configuring (the setting of) your favorite web browser
 
     This tutorial will show you an example of Rougail use based on the
-    "how to set a proxy" in the `Mozilla Firefox <https://www.mozilla.org/en-US/firefox/new/>`_ browser
+    *how to set a proxy* in the `Mozilla Firefox <https://www.mozilla.org/en-US/firefox/new/>`_ browser
     use case.
 
-More precisely, this tutorial aims at reproducing :term:`variable`\ s (in this use case we will call them configuration options) behind this Mozilla Firefox settings page:
+More precisely, this tutorial aims at reproducing :term:`variable`\ s behind this Mozilla Firefox settings page:
 
 .. image:: images/firefox.png
 
-.. note:: We are not coding a firefox plugin here.
+We'll call the variables **configuration options** since that's what the variables represent in this case.
+
+.. attention:: We are not coding a firefox plugin here.
           We are just going to handle some of the firefox configuration settings
           with Rougail.
 
 Presentation of the firefox option configuration variables
 -----------------------------------------------------------
 
-Let's dive into this configuration validation use case.
+Let's dive into this **configuration options validation** use case.
-The values entered by the user that have to be validated.
+The values entered by the user have to be 
 
-At first glance we have a selection of five options configuration values that we need to fill in:
+- validated
+- consitent.
+
+At first glance we can see that we have a selection of five configuration options values that we need to fill in (they are highlighted here in this screenshot):
 
 .. image:: images/firefox_01.png
 

docs/tutorial/preliminary.rst

@@ -9,27 +9,30 @@ Preliminaries
    - define a Rougail format version
    - define a Rougail :term:`variable` and set its :term:`value`
 
-.. type-along:: Reminders
+.. type-along:: Basics
 
-   We already learned in other workshops how to:
+Dictionary
+-------------
 
-   - define a Rougail :term:`structure description file <dictionary>`
+Define a Rougail :term:`structure description file <dictionary>`
 
-     :ref:`Here is an empty Rougail dictionnary <RougailDictionaryEmptyFile>`
+https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_000/firefox/00-proxy.yml
 
-   - define a variable and its default value
+
+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
+- 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
+- define a variable with a description and a default value
 
  :ref:`Here is a Rougail variable with a default value <RougailDictionaryFirstVariableDefault>`
 
-
 The integrator role
 ----------------------
 
@@ -121,7 +124,7 @@ Rougail waits for the `proxy_mode` configuration option's value to be set.
 
         A variable is mandatory when a value is required, that is, `None` is not an option.
 
-Typing a variable
+Variable's type
 -----------------
 
 If the `type` attribute is not set, rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined in the structure file.

docs/variable.rst

@@ -13,22 +13,30 @@ Synopsis
 
    value
 
-        A variable can have a default value, that is a option configuration setting in the :term:`dictionary` structure,
+        A value is a variable's setting. 
-        or no value at all, then the value needs to be define by the :term:`operator`.
+        Variable can have a default value, that is a setting defined in the :term:`dictionary` structure,
+        or no value at all, then the value needs to be define later by the :term:`operator`.
 
 .. discussion:: Discussion
 
-                This definition makes a heavy use of data typing.
+    The variable is, by definition, strongly typed. 
-                Indeed, depending on the type system definition of the constistency handling system used, variables may only be able to store a specified data type.
+    Rougail uses static type definition and even type inference. 
+    Indeed, the constistency handling system heavyly relies on the type system definition. 
+    Variables may only be able to store a specified data type.
     OK, variables are the containers for storing the values. It has something to do with typing.
-                But this is not just about typing.
     
-Name
+    But consitency handling system is is not just about strong typing. It is more than that.
+
+Names
 ------
 
-Variable's associated symbolic name.
+Variable name 
 
-It's best to follow the :ref:`convention on variable names`.
+    Variable's associated symbolic name.
+
+.. seealso:: 
+
+    Have a look at the :ref:`convention on variable naming link <convention on variable names>`.
 
 Shorthand declaration
 ----------------------------