proofreading

docs/gettingstarted.rst

@@ -6,49 +6,33 @@ Getting started
 Installation
 ----------------
 
-You can use the python installer and type the install command in your preferred terminal:
+- Open a shell session
+
+.. type-along:: Optional: install the Rougail library in a virtual environment
+
+- install the virtual environment: `python -m"venv' .venv`
+- activate it `./.venv/bin/activate` (or `.venv\Scripts\activate.exe` under windows)
+
+.. type-along:: Rougail's library installation
+
+You can use the `pip` python installer, here is the install command:
 
 .. code-block:: text
 
     pip install rougail
-    
-Another way to install the Rougail library in install it in a virtual environment:
-
-.. code-block:: text
-
-    python -m"venv' .venv
-
-And, under linux or Mac:
-
-.. code-block:: shell
-
-    ./.venv/bin/activate 
-
-or, under windows:
-
-.. code-block:: text 
-
-    .venv\Scripts\activate.exe 
-
-Then again:
-
-.. code-block:: text
-
-    pip install rougail
-
 
 What is a consistency handling system ?
 ------------------------------------------------
 
-.. questions:: Rougail, Tiramisu: What is all this stuff?
+.. questions:: Rougail, Tiramisu: What is it all about?
 
-    **Question**: OK, I have understood that the Rougail library enables me to take advantage of the :xref:`tiramisu` library. But what is all this for? What is exactly a consistency handling system? And again, what is this :xref:`tiramisu library` used for?
+    **Question**: OK, I have understood that the Rougail library allows me to take advantage of the :xref:`tiramisu` consistency handling library. But what is all this for? What is exactly a consistency handling system? And again, what is this :xref:`Tiramisu library <tiramisu library>` used for?
 
     **Answer**: Well, we will explain in details what this :xref:`tiramisu` library is and what Rougail is. 
     
     In (very) short: 
 
-    - Rougail is the YAML consistency description of a configuration's situation
+    - Rougail is the YAML consistency description of a :term:`context`\ 's situation
     - Tiramisu is the consistency engine linter
 
 .. glossary::
@@ -56,7 +40,7 @@ What is a consistency handling system ?
    Tiramisu
 
         :xref:`tiramisu` is a consistency handling system that has initially been designed
-        in the configuration management scope. To put it more simply,
+        in the configuration management scope. Until now,
         this library is generally used to handle configuration options.
 
         It manages variables and group of variables. In the Tiramisu scope we call
@@ -64,7 +48,7 @@ What is a consistency handling system ?
 
         Here is the :xref:`tiramisu documentation <tiramisu>`.
 
-In the Rougail scope, we call it :term:`variable`\ s and :term:`families`.
+In the Rougail scope, we call it :term:`variables <variable>` and :term:`families <family>`.
 In Rougail, the families and variables are located in the :term:`structure files <structure file>`.
 
 The structure files
@@ -75,15 +59,32 @@ The structure files
    structure file
 
        A structure file in the Rougail meaning is a YAML file that describes variables
-       and their dependencies / consistencies.
+       and their dependencies.
        There can be a lot of structure files located in many different folders.
 
-       Rougail reads all the dictionaries and loads them into a single object
+       Rougail reads all the structure files and loads them into a single object
-       that handles the variables consistency.
+       that represents the whole :term:`context`.
 
-.. image:: images/schema.png
+.. figure:: images/schema.png
+   :alt: The Rougail process
+   :align: center
 
-The main advantage is that declaring variables and writing consistency is as simple
+   The Rougail process from structure files to Tiramisu object
+
+.. glossary:: 
+
+   structured data
+   
+       We sometimes call 'structured datas' the datas that are in the structure files,
+       as opposed to :term:`user datas <user data>`\ .
+       For example when a value of a variable is defined in the structured datas, that is
+       in a structured file, the assigned value's status is that the variable's value is a default value. 
+       If the assigned value of the variable is defined in a user data file, 
+       it is an user assigned value.
+
+We'll see later on some examples of default values and user assigned values.
+   
+The main advantage of all of this 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.
 

docs/tutorial/index.rst

@@ -1,10 +1,12 @@
 Tutorial with a real world sample
 =====================================
 
-Here is a fairly complete tutorial, this is a use case that comes from the real world.
+Here is a fairly complete tutorial, it 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
+.. objectives:: 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
@@ -14,22 +16,23 @@ More precisely, this tutorial aims at reproducing :term:`variable`\ s behind thi
 
 .. image:: images/firefox.png
 
-We'll call the variables **configuration options** since that's what the variables represent in this case.
+We'll call the variables **configuration options** since that's what the variables represent in this use case.
 
 .. attention:: We are not coding a firefox plugin here.
           We are just going to handle some of the firefox configuration settings
           with Rougail.
 
+Let's dive into this **configuration options validation** use case.
+
 Presentation of the firefox option configuration variables
 -----------------------------------------------------------
 
-Let's dive into this **configuration options validation** use case.
 The values entered by the user have to be 
 
 - 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):
+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

@@ -11,11 +11,10 @@ Preliminaries
 
 .. prerequisites:: Prerequisites
 
-    We assume that Rougail's library is :ref:`globally installed <installation>` on your computer or locally in a virtual environment.
+    We assume that Rougail's library is :ref:`installed <installation>` on your computer.
 
-.. type-along:: an empty structure file
+Making a structure file 
-
+-------------------------
-    An empty structure description file
 
 .. exercise:: The folder structure
 
@@ -29,10 +28,9 @@ Preliminaries
 - First, we wil make a :term:`structure file <structure file>`, so let's create a :file:`struct.yml` file
   located in the :file:`firefox` subfolder.
 
-The structure file 
+.. type-along:: An empty structure file
---------------------
 
-This is an empty Rougail dictionnary
+This is an empty Rougail structure description file.
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
    :language: yaml
@@ -43,14 +41,15 @@ This is an empty Rougail dictionnary
     ---
     version: 1.1
 
-.. type-along:: a first variable
-
-    Let's put a variable in the Rougail :term:`structure description file <structure file>`
 
 Defining a variable and its default value
 ----------------------------------------------
 
-This is a first Rougail variable in a Rougail dictionnary.
+.. type-along:: a first variable
+
+    Let's put a variable in the Rougail :term:`structure description file <structure file>`
+
+This is a first Rougail variable in a Rougail dictionnary:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
    :language: yaml
@@ -61,7 +60,7 @@ This is a first Rougail variable in a Rougail dictionnary.
     ---
     proxy_mode:
 
-- Then if we run the Rougail CLI utility command 
+- If we run the Rougail CLI utility command 
 
 .. code-block:: text
    :class: terminal
@@ -81,10 +80,10 @@ we will actually have an error:
 
 Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet.
 
-So we can therefore see this consequence:
+We can therefore deduce this result:
-
-.. important:: Once defined, an option configuration :term:`value` is :term:`mandatory`.
 
+.. note:: Once defined, an option configuration :term:`value` is :term:`mandatory`.
+   
 Rougail waits for the `proxy_mode` configuration option's value to be set.
 
 .. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` according to the definition of Tiramisu.
@@ -93,10 +92,10 @@ Rougail waits for the `proxy_mode` configuration option's value to be set.
 
     mandatory
 
-        A variable is mandatory when a value is required, that is, `None` is not an option.
+        A variable is mandatory when a value is required, that is, `None` is not a possible value.
         It **must** have a defined value.
         
-Then we just add a variable's description, which is a good practice.
+Let's add a variable's description, which is not mandatory but which is a good practice:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml
    :language: yaml
@@ -108,7 +107,9 @@ Then we just add a variable's description, which is a good practice.
     proxy_mode:
       description: Configure Proxy Access to the Internet
 
-We need a **default value**. 
+.. type-along:: how to set a value -- the default value
+
+We need to set a value to this `proxy_mode` variable. A first way to do it is *to set a value by default*. 
 
 .. glossary::
 
@@ -131,20 +132,20 @@ So let's define a variable with a description -- **and a default value**
       default: No proxy
 
 
-.. type-along:: how to set a value
+.. type-along:: how to set a value -- the assignment
 
     A default value has been set, great. Now how do I assign a value to a variable?
 
 How to set a value
 ----------------------
 
-So far we have only talked about the one that writes the structure files. It's role is called the integrator's role.
+So far we have only talked about the one that writes the :term:`structure files <structure file>`\ . It's *role* is called the integrator's role.
 
 .. glossary::
 
     integrator
 
-        An integrator in the Rougail logic is the person who writes the :term:`structure files <structure file>`\ .
+        An integrator in the Rougail field is the person who writes the :term:`structure files <structure file>`\ .
         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**
@@ -156,25 +157,29 @@ Now we will talk about the one that defines the values. It is called the operato
 
     operator
 
-        An operator ih the Rougail logic is the person who gives :term:`value`\ s to the pre-defined variables,
+        An operator in the Rougail field is the person who assigns :term:`value`\ s to the pre-defined variables,
         his responsabilities are to set variable values correctly.
 
-        The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated. The type validation is driven by the :term:`definitions in the structure file <structure file>`.
+        The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated. The type validation is driven by the definitions in the :term:`structure file <structure file>`.
 
 Values are mandatory
 -------------------------
 
 It is the operator's responsibility to set the user datas variables values.
-The operator does not toutch the structure files, 
+The operator does not handle the structure files, 
-he is responsible for other files called the :term:`user data file`\ s. 
+he is responsible of other files called the :term:`user data file`\ s. 
 
 .. glossary::
 
     user datas
 
-        User datas, as opposed to structured datas, means datas where the consistency of the variables is not concerned, not in the scope (the consistency in the structured datas scope's).
+        User datas, as opposed to structured datas, are datas that only concern the assignment of values
-        For example, variable's values (which are also called **user values**). 
+        and not the consistency of the variables.
-    
+
+        The variable's values are also called **user values**. 
+        
+        The consistency field is outside of the user datas scope. 
+        The consistency is handled in the :term:`structured datas <structured data>`\ 's scope.
 
 .. exercise:: Folder structure update
 
@@ -218,8 +223,12 @@ Let us clarify this essential point:
 Variable's type
 -----------------
 
+.. type-along:: type inference
+
 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.
 
+.. type-along:: type setting
+
 If the operator sets an option value for example with the `number` type, like this:
 
 .. code-block:: yaml
@@ -230,11 +239,17 @@ If the operator sets an option value for example with the `number` type, like th
       type: number
 
 Then Rougail will expect a `int` or a `float` as a value for the `example_var` variable.
-In our firefox use case, the real type of the `proxy_mode` variable will be now set as a  `choice` type:
 
 .. type-along:: Defining a choice type
 
-    A choice type variable is a variable where the content is constrained by a list
+In our firefox use case, the real type of the `proxy_mode` variable will be now set as a  `choice` type:
+
+
+.. glossary::
+
+   choice type
+
+       A choice type variable is a variable where the content is constrained by a list
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
    :linenos:
@@ -255,14 +270,14 @@ In our firefox use case, the real type of the `proxy_mode` variable will be now
         - Automatic proxy configuration URL
       default: No proxy
 
-- Then if we run the Rougail CLI 
+- Let's run the Rougail CLI 
 
 .. code-block:: text
    :class: terminal
    
     rougail -v 1.1 -m firefox/
 
-We will have an output like this: 
+We have an output like this one: 
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_013/config/01/output_ro.html