review

docs/tutorial/domainname.rst

@@ -25,7 +25,7 @@ Some suitable types
        git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
        git switch --detach v1.1_030
 
-.. type-along:: let's recap how far we've come
+.. type-along:: Let's recap how far we've come
 
 We have an `http_proxy` family with an `address` variable in it.
 

docs/tutorial/family.rst

@@ -27,7 +27,7 @@ Group variables inside families
        git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
        git switch --detach v1.1_020
 
-.. type-along:: let's recap how far we've come
+.. type-along:: Let's recap how far we've come
 
 We have this choice variable in its structure definition file:
 
@@ -203,7 +203,7 @@ otherwise we will get an error if we try to access this variable:
     <span style="color: #ff0000">┗━━ </span>  - manual.http_proxy.address (HTTP address)
     </pre>
 
-.. type-along:: let's set user values in a user data file
+.. type-along:: Let's set user values in a user data file
 
 Here is a user data file sample: 
 
@@ -248,18 +248,18 @@ Everything is OK:
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 HTTP address: example.net ◀ loaded from the YAML file "config/02/config.yml"
     </pre>
 
-Let's recap about the user datas. We can see in this Rougail CLI output that:
+Let's recap about the user data. We can see in this Rougail CLI output that:
 
 - the `proxy_mode` value is set by default by the :term:`integrator`
 - the `address` value is has been set by an :term:`operator`
 
-.. keypoints:: let's review the key points
+.. keypoints:: Let's review the key points
 
     **Keywords**
     
     - we know how to define :term:`variable`\ s inside of a family
     - we now know what a :term:`mandatory` variable is and why it is necessary to assign values to the variables
-    - we kwow how to set a variable's :term:`user value <user datas>`
+    - we kwow how to set a variable's :term:`user value <user data>`
     - we have the big picture : the :term:`configuration`, which is (the structure files + the user data files)
     
     **Progress**

docs/tutorial/index.rst

@@ -20,8 +20,8 @@ More precisely, this tutorial aims at reproducing :term:`variable`\ s behind thi
 
 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.
+.. attention:: We are not coding a Firefox plugin here.
-          We are just going to handle some of the firefox configuration settings
+          We are just going to handle some of the Firefox configuration settings
           with Rougail. We are just validating them. 
           
           The configuration option values entered by the user have to be:
@@ -36,7 +36,7 @@ Let's dive into this **configuration options validation** use case.
 
    It is advisable to follow this tutorial with the help of the corresponding :tutorial:`Rougail git repository tutorial <src/branch/1.1>`.
    You can instead copy/paste or download the different file contents that are explained in this tutorial step and save the files to your computer.
-   However, if you use the git rougail tutorial repository, you will have all the necessary files distributed in the correct tree structure, 
+   However, if you use the git Rougail tutorial repository, you will have all the necessary files distributed in the correct tree structure, 
    which is in our opinion much more practical.
    
    ::
@@ -45,7 +45,7 @@ Let's dive into this **configuration options validation** use case.
 
 .. toctree::
    :titlesonly:
-   :caption: The firefox tutorial
+   :caption: The Firefox tutorial
 
    preliminary
    choice

docs/tutorial/preliminary.rst

@@ -65,6 +65,7 @@ This is an empty Rougail :term:`structure description file: <structure file>`
 :tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_000/firefox/00-proxy.yml>`
 
 This `version` specification is just the Rougail YAML's format version specification.
+YAML files are loaded using a version 1.2 file parser. It is recommended (but not mandatory) to specify this in the file header, especially for linters.
 By now, we have an empty structure file with the format specification in it.
 
 Let's add our first variable
@@ -249,11 +250,8 @@ The chosen value is indicated in the Rougail's CLI output as the default choice.
 
 - here is the short-hand default setting and description:
 
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml
+.. code-block:: yaml
-   :language: yaml
-   :caption: The short-hand way of setting a default value and a description
 
-..           
     proxy_mode: No proxy  # Configure Proxy Access to the Internet
 
 - and there is the verbose way of setting a default value:
@@ -267,7 +265,7 @@ The chosen value is indicated in the Rougail's CLI output as the default choice.
 There are some other :term:`short-hand ways <short-hand notation>` with Rougail that you may encounter
 as you read the Rougail's documentation and tutorial.
 
-.. admonition:: how to set a value -- the assignment
+.. admonition:: How to set a value -- the assignment
 
     A default value has been set, great. This raises a question about what a normal value is.
 
@@ -300,20 +298,20 @@ Now we will talk about the one that defines the values. His role is called the o
         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>`.
 
-It is the operator's responsibility to set the user datas variables values.
+It is the operator's responsibility to set the user data variables values.
 The operator does not handle the structure files,
 he is responsible of other files called the :term:`user data files <user data file>`.
 
 .. glossary::
 
-    user datas
+    user data
 
         User datas, as opposed to structured datas, are datas that only concern the assignment of values
         and not the consistency of the variables between them.
 
         The variable's values are also called **user values**.
         
-        The consistency field is outside of the user datas scope.
+        The consistency field is outside of the user data scope.
         The consistency is handled in the :term:`structured datas <structured data>`\ 's scope.
 
 .. important:: For now, we don't know how to disable the default `mandatory` settings,
@@ -329,14 +327,14 @@ he is responsible of other files called the :term:`user data files <user data fi
         └── config
             └── config.yml
 
-.. type-along:: how to set a user data value
+.. type-along:: How to set a user data value
 
 If the integrator has not set any default value in his structure file,
 it's up to the operator to do the job in the `config.yml` file:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/config.yml
    :language: yaml
-   :caption: A Rougail user datas file :file:`config/config.yml`, with a value set.
+   :caption: A Rougail user data file :file:`config/config.yml`, with a value set.
    :name: RougailConfigDefaultValue
 
 ..
@@ -372,7 +370,7 @@ Now the `proxy_mode`'s new `No proxy` value is the same as the default value but
 comes from the :file:`config/02/config.yml` user data file. From now on this `proxy_mode` variable's value
 is a user data value and not a default value (even if it's actually the same value).
 
-.. type-along:: structure values and user data values
+.. type-along:: Structure values and user data values
 
 We can see with the Rougail CLI utility where the values come from.
 It can come from an integrator's setting or from an operator's setting.
@@ -385,7 +383,7 @@ It can come from an integrator's setting or from an operator's setting.
 Most of the time, the integrator and the operator are one and the same person,
 here we are talking about roles and not necessarily about people.
 
-.. type-along:: user data files are where the user values live
+.. type-along:: User data files are where the user values live
 
 We need to set the values ​​in separate files, called `user data files`.
 
@@ -393,12 +391,12 @@ We need to set the values ​​in separate files, called `user data files`.
 
    user data file
    
-       A user data file is a file where only :term:`user datas` are set. 
+       A user data file is a file where only :term:`user data` are set.
 
-       A user file is a file where there are only user datas in it, users can set values, called user values -- 
+       A user file is a file where there are only user data in it, users can set values, called user values --
        that is variable's values that have been set by an :term:`operator`\ .
        
-       see also :term:`user datas` 
+       see also :term:`user data`
 
 .. glossary::
 
@@ -419,4 +417,3 @@ We need to set the values ​​in separate files, called `user data files`.
     - a variable's user value
     - the :term:`integrator` and :term:`operator` roles
     - a :term:`configuration`
-