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

@@ -1,14 +1,14 @@
 Getting started
 ====================
 
-Presentation of the firefox configuration options 
+Presentation of the firefox configuration options
 --------------------------------------------------
 
 At first glance we can see that we have a selection of five configuration options that we need to fill in, they are highlighted here in this screenshot:
 
 .. image:: images/firefox_01.png
 
-We'll learn in this tutorial how to set the values of the configuration options in a clean way with the Rougail library. 
+We'll learn in this tutorial how to set the values of the configuration options in a clean way with the Rougail library.
 
 .. objectives:: Objectives of this section
 
@@ -27,7 +27,7 @@ We'll learn in this tutorial how to set the values of the configuration options
       Each tag corresponds to a stage of progress in the tutorial.
       Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.
 
-    If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`, 
+    If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
     this workshop page corresponds to the tags :tutorial:`v1.1_000 <src/tag/v1.1_000>` to :tutorial:`v1.1_003 <src/tag/v1.1_003>`
     in the repository:
 
@@ -36,7 +36,7 @@ We'll learn in this tutorial how to set the values of the configuration options
        git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
        git switch --detach v1.1_000
       
-Creating a structure file 
+Creating a structure file
 --------------------------
 
 .. demo:: The folder structure
@@ -51,21 +51,22 @@ Creating a structure file
 - First, we will create a :term:`structure file <structure file>`, so let's create a :file:`00-proxy.yml` file
   located in the :file:`firefox` subfolder.
 
-This is an empty Rougail :term:`structure description file: <structure file>` 
+This is an empty Rougail :term:`structure description file: <structure file>`
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
    :language: yaml
    :caption: An empty Rougail structure file with only the YAML header and the version number
    :name: RougailStructVersion
 
-.. 
+..
     ---
     version: 1.1
 
 :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. 
+This `version` specification is just the Rougail YAML's format version specification.
-By now, we have an empty structure file with the format specification in it. 
+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
 ------------------------------
@@ -87,7 +88,7 @@ Here we define a variable named `proxy_mode`:
    :caption: A Rougail structure file with only one variable in it
    :name: RougailDictionaryFirstVariableName
 
-.. 
+..
     ---
     proxy_mode:
 
@@ -100,7 +101,7 @@ Let's run the Rougail CLI utility command in a terminal:
    
     rougail -m firefox/
 
-Well, we notice that we have an error: 
+Well, we notice that we have an error:
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/01/output_ro.html
@@ -115,11 +116,11 @@ It's because this first defined variable is :term:`mandatory` and needs to have
 
 We can therefore deduce the fact that:
 
-.. admonition:: Fact 
+.. admonition:: Fact
 
     Once defined, an option configuration :term:`value` is :term:`mandatory` by default.
     That is to say, it is absolutely necessary to assign a value to this variable.
-   
+
 Rougail expects the `proxy_mode` configuration option's value to be set.
 
 .. glossary::
@@ -129,9 +130,9 @@ Rougail expects the `proxy_mode` configuration option's value to be set.
         A variable is mandatory when a value is required, that is, `None` **is not** a possible value.
         It **must** have a defined value.
 
-.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` 
+.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>`
-    according to the :xref:`Tiramisu <tiramisu>` underlyning consistency system. 
+    according to the :xref:`Tiramisu <tiramisu>` underlyning consistency system.
-    You will learn that it is actually possible to disable the mandatory property behavior, 
+    You will learn that it is actually possible to disable the mandatory property behavior,
     but you need to declare it explicitely.
 
 Describe the variable
@@ -150,19 +151,19 @@ Let's add a variable's description, which is not mandatory but which is usually
    :caption: A Rougail structure file with a variable and a description
    :name: RougailStructFirstVariableDescription
 
-.. 
+..
     ---
     proxy_mode:  # Configure Proxy Access to the Internet
 
 :tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_002/firefox/00-proxy.yml>`
 
-You have two way to define a variable's description: 
+You have two way to define a variable's description:
 
 - the verbose way:
 
   .. code-block:: yaml
   
-      proxy_mode:  
+      proxy_mode:
         description: Configure Proxy Access to the Internet
 
 
@@ -183,8 +184,8 @@ we have this output:
 .. raw:: html
    :class: output
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_002/config/01/output_rw.html
-   
+
-.. 
+..
     <pre>╭──────────────────── Caption ─────────────────────╮
     │ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #ffd700">Default value</span> │
     ╰──────────────────────────────────────────────────╯
@@ -192,11 +193,11 @@ we have this output:
     <span style="color: #5c5cff">┗━━ </span>📓 <span style="color: #ff0000">Configure Proxy Access to the Internet</span>: <span style="color: #ffd700">null</span>
     </pre>
 
-We can see here that the variable's description string "Configure Proxy Access to the Internet" is used 
+We can see here that the variable's description string "Configure Proxy Access to the Internet" is used
 to refer to the `proxy_mode` variable.
 
 .. note:: The description is used in UI tools and outputs instead of the variable name.
-          The goal here is to provide an explanation of the variable for the user, 
+          The goal here is to provide an explanation of the variable for the user,
           not to show the technical name of the variable as defined by the :term:`integrator`.
 
 Set a default value
@@ -208,16 +209,16 @@ Set a default value
      
           git switch --detach v1.1_003
 
-We will learn different ways to set a value, the first way is setting a *default* value. 
+We will learn different ways to set a value, the first way is setting a *default* value.
 
 .. glossary::
 
     default value
         
-        A default value is a variable value that is predefined, that's why this value is placed 
+        A default value is a variable value that is predefined, that's why this value is placed
         right in the structure file.
 
-Let's add a default value to this `proxy_mode` variable. 
+Let's add a default value to this `proxy_mode` variable.
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml
     :language: yaml
@@ -236,7 +237,7 @@ The `proxy_mode` variable requires a value, that's why we have set a `No proxy`
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/01/output_ro.html
    :class: output
 
-.. 
+..
     <pre>╭─────── Caption ────────╮
     │ Variable <span style="color: #ffd700">Default value</span> │
     ╰────────────────────────╯
@@ -244,19 +245,16 @@ The `proxy_mode` variable requires a value, that's why we have set a `No proxy`
     <span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
     </pre>
 
-As we have set the `proxy_mode`'s value as `No proxy` by default, 
+As we have set the `proxy_mode`'s value as `No proxy` by default,
 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
-    proxy_mode: No proxy # Configure Proxy Access to the Internet
 
-- and there is the verbose way of setting a default value: 
+- and there is the verbose way of setting a default value:
 
 .. code-block:: yaml
 
@@ -264,10 +262,10 @@ The chosen value is indicated in the Rougail's CLI output as the default choice.
       description: Configure Proxy Access to the Internet
       default: No proxy
 
-There are some other :term:`short-hand ways <short-hand notation>` with Rougail that you may encounter 
+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.
 
@@ -275,7 +273,7 @@ as you read the Rougail's documentation and tutorial.
 
 .. type-along:: The different Rougail roles and setting a variable's value
 
-So far we have only talked about the actor that writes the :term:`structure files <structure file>`\ . 
+So far we have only talked about the actor that writes the :term:`structure files <structure file>`\ .
 The one who writes the structure file plays the *role* of the *integrator*.
 
 .. glossary::
@@ -297,26 +295,26 @@ Now we will talk about the one that defines the values. His role is called the o
         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 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, 
+The operator does not handle the structure files,
-he is responsible of other files called the :term:`user data files <user data file>`. 
+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 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, 
+.. important:: For now, we don't know how to disable the default `mandatory` settings,
    so if neither a default value nor a user value are set for a given variable, Rougail will raise an error.
 
 .. exercise:: Folder structure update
@@ -329,29 +327,29 @@ 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, 
+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
 
-.. 
+..
     ---
     proxy_mode: No proxy
 
 :tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_003/config/02/config.yml>`
 
-The operator needs to add the `-u yaml -yf config/config.yml` options to the Rougail CLI: 
+The operator needs to add the `-u yaml -yf config/config.yml` options to the Rougail CLI:
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/cmd_ro.txt
    :class: terminal
 
-.. 
+..
     rougail -m firefox/ -u yaml -yf config/02/config.yml
 
 which gives us this output:
@@ -360,7 +358,7 @@ which gives us this output:
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/output_ro.html
    :class: output
 
-.. 
+..
     <pre>╭──────── Caption ────────╮
     │ Variable Modified value │
     ╰─────────────────────────╯
@@ -368,24 +366,24 @@ which gives us this output:
     <span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yml"
     </pre>
 
-Now the `proxy_mode`'s new `No proxy` value is the same as the default value but we see in the Rougail CLI output that the value 
+Now the `proxy_mode`'s new `No proxy` value is the same as the default value but we see in the Rougail CLI output that the value
 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. 
+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.
 
 .. admonition:: Reminder
 
     - the integrator works on structure files, he can define default value for variables
     - the operator works on user data files, he only can set user data values for variables
-    
-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
+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
 
 We need to set the values ​​in separate files, called `user data files`.
 
@@ -393,19 +391,19 @@ 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::
 
-   configuration 
+   configuration
    
        We call configuration the whole system structure and user values,
-       and when we speak of consistency, it is in relation to this whole set. 
+       and when we speak of consistency, it is in relation to this whole set.
 
 .. keypoints:: Key points progress
 
@@ -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`
-