docs(abstract): properties, ..

docs/concepts.rst

@@ -1,7 +1,18 @@
 Abstract presentation
 =========================
 
-Rougail, a powerful, free/open-source configuration language that combines declaration, data validation, and templating in a single, declarative syntax.
+Rougail, a powerful, free/open-source configuration manager and language that combines declaration, data validation, and templating in a single, declarative syntax.
+
+It will be useful to:
+
+- define variables (the structure) easily and their constraintes
+- loads those variables
+- generate variables documentation
+- loads variables' values
+- validate the variables and the overall consistency handling system
+- generate custom table views
+- export to different common format (YAML, Ansible, ...)
+- ...
 
 Why another configuration manager?
 -------------------------------------
@@ -24,36 +35,41 @@ At the time of the design of Rougail, there were structuring choices that define
 
 The steps in Rougail can be explain as follows:
 
-- loads the variable structure file
+- loads the variable structured data
 - loads the user data
-- reads, validates, exports the data
+- reads, validates, exports, document, ... the data
 
-Structure
+Structured data
-~~~~~~~~~
+~~~~~~~~~~~~~~~~~
+
+Structured data is also called Rougail format.
 
 .. glossary::
 
-   structure file
+   structured data
 
-       A structure file in the Rougail meaning is a YAML file that describes variables
+       A configuration-first DSL (domain-specific language) designed for describing variables, consistency
-       and their dependencies.
+       and describe the relationships between variables in a declarative style.
-       There can be a lot of structure files located in many different folders.
 
-       Rougail reads all the structure files and loads them into a single object
+       The language is a mix of YAML ans Jinja Templating.
-       that represents the whole :term:`context`.
+
+       It goes beyond traditional schema languages (like JSON Schema, OpenAPI, Cuelang)
+       by combinig type systems, powerful validation, consistency of the configuration and documentation.
+
+Structured data are commonly place in structure file.
 
 User data
-~~~~~~~~~
+~~~~~~~~~~
 
 .. glossary::
 
     user data
 
-        User datas, as opposed to structured datas, are datas that only concern the assignment of values
+        User datas, as opposed to structured data, 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 data scope.
         The consistency is handled in the :term:`structured datas <structured data>`\ 's scope.
 
@@ -68,22 +84,25 @@ Here a some user data examples:
 Output
 ~~~~~~~
 
+Structured and user data form a coherent configuration useful for different purpose.
+
+Output is here to define what kind of data we want.
+
 And some output examples:
 
-Ensuite on pourra définir sous quelle forme on veut recueillir l'information (Outputs) :
+- term:`Tiramisu` object
+- extract JSON
+- extract to Ansible inventory
+- documentation
+- custom table views
 
-- un objet Tiramisu
-- une extraction JSON
-- un export pour l'inventaire Ansible
-- de la documetation
-- ...
 .. list-table::
    :widths: 15 45
    :header-rows: 1
 
    * - Step
 
-   * - Structure
+   * - Structured data
 
    * - User data
 
@@ -94,27 +113,9 @@ What kind of actor?
 
 It's clear that Rougail can be used in many contexts.
 
-Here we'll define actor names. Obviously, these aren't the only possible actors. We're just defining the actors within the Rougail context. Choice your own actor name if you wish to personnalize in your specific context.
+Here we'll define actor names. Obviously, these aren't the only possible actors.
 
-.. list-table::
+We're just defining the actors within the Rougail context. Choice your own actor name if you wish to personnalize in your specific context.
-   :widths: 15 45
-   :header-rows: 1
-
-   * - Step
-     - Description
-     - Actor
-
-   * - Structure
-     - The actor who defines the structure
-     - Integrator
-
-   * - User data
-     - The actor who sets the values
-     - Operator
-
-   * - Output
-     - The actor who uses the variables with their values
-     - Operator
 
 .. glossary::
 
@@ -136,10 +137,30 @@ Here we'll define actor names. Obviously, these aren't the only possible actors.
         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>`.
 
+.. list-table::
+   :widths: 15 45
+   :header-rows: 1
+
+   * - Step
+     - Actor
+     - Description
+
+   * - Structured data
+     - Integrator
+     - The actor who defines the structure
+
+   * - User data
+     - Operator
+     - The actor who sets the values
+
+   * - Output
+     - Operator or integrator
+     - The actor who uses the variables with their values
+
 Variable lifetime
 ----------------------
 
-Rougail's is a configuration language and data validation tool designed to simplify defining, validating, and generating structured configuration and data. 
+Rougail's is a configuration language and data validation tool designed to simplify defining, validating, and generating structured configuration and data.
 
 Rougail aims to define variables.
 
@@ -154,13 +175,11 @@ The lifecycle of a variable includes the generic stages (like, in the Python lan
    :header-rows: 1
 
    * - Creation
-     - Initialization
      - Assignment
      - Reading
      - Destruction
 
    * - Variables are assigned a name and a type
-     - Their first value is assigned
      - The variable's value is modified
      - The variable's value is used
      - The variable terminates upon the destruction of the object
@@ -171,12 +190,12 @@ But other concepts are included in the lifecycle:
    :widths: 15 45
    :header-rows: 1
 
-   * - Documentation
+   * - Permission
-     - Permission
+     - Documentation
      - Specialization
 
-   * - Informations for variable documentation like description or help. Those informations are used to build documentation, changelog, ...
+   * - Properties describe access constraints
-     - Properties describe access constraints
+     - Informations for variable documentation like description or help. Those informations are used to build documentation, changelog, ...
      - Define usage, selection,...
 
 
@@ -188,23 +207,23 @@ But other concepts are included in the lifecycle:
      - Actor
      - Lifetime
 
-   * - Structure
+   * - Structured data
      - Integrator
-     - Creation + initialization
+     - Creation
 
    * - User data
      - Operator
-     - Assignment + permission
+     - Assignment and permission
 
    * - Output
-     - Operator
+     - Operator or integrator
-     - Reading + permission + documentation + specialization
+     - Reading, permission, documentation and specialization
 
-Mutability
+Variable mutability
----------------
+---------------------
 
-Structure
+Structured data
-~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~
 
 When the integrator define the structure, variable are mutable.
 
@@ -212,19 +231,15 @@ Even if the default behavior is to conflict when multiple declarations for the s
 
 It's possible to explicitly allow to unifying (combined) multiple variables declarations.
 
-There is no value, strictly speaking. It's a default value. As other parameter, the default value is explicitly mutable.
-
 User data
 ~~~~~~~~~~
 
 It's no more possible to modifying variable definition.
 
-The value is now mutable.
-
 Output
 ~~~~~~~
 
-Variable definition and value setting are immutable.
+Variable definition settings are immutable.
 
 .. list-table::
    :widths: 15 45
@@ -233,29 +248,39 @@ Variable definition and value setting are immutable.
    * - Step
      - Actor
      - Lifetime
-     - Variable mutation
+     - Variable mutability
-     - Value mutation
 
-   * - Structure
+   * - Structured data
      - Integrator
      - Creation + initialization
      - Mutable
-     - N/A
 
    * - User data
      - Operator
-     - Assignment + permission
+     - Assignment and permission
      - Immutable
-     - Mutable
 
    * - Output
-     - Operator
+     - Operator or integrator
-     - Reading + permission + documentation + specialization
+     - Reading, permission, documentation and specialization
-     - Immutable
      - Immutable
 
-Read write or read only mode
+Value access
------------------------------
+-------------
+
+In the `structured data` step, there is no value, strictly speaking. It's a default value.
+As other parameters, the default value is explicitly mutable.
+
+In the `user data` step, we can modify the values. That's precisely the purpose of this step.
+The configuration is said to be in `read write` mode.
+
+But at the `output` step, it is obviously no longer possible to modify the value.
+The configuration is said to be in `read only` mode.
+
+.. attention::
+   It is important not to confuse `value` and `calculated value`.
+   The result of a calculation can change over time.
+   In this case, the value does indeed correspond to the result of the calculation.
 
 .. list-table::
    :widths: 15 45
@@ -264,34 +289,63 @@ Read write or read only mode
    * - Step
      - Actor
      - Lifetime
-     - Variable mutation
+     - Variable mutability
-     - Value mutation
+     - Value
-     - Read/Write
 
-   * - Structure
+   * - Structured data
      - Integrator
      - Creation + initialization
      - Mutable
-     - N/A
+     - Mutable default value
-     - N/A
 
    * - User data
      - Operator
-     - Assignment + permission
+     - Assignment and permission
      - Immutable
-     - Mutable
      - Read write
 
    * - Output
-     - Operator
+     - Operator or integrator
-     - Reading + permission + documentation + specialization
+     - Reading, permission, documentation and specialization
-     - Immutable
      - Immutable
      - Read only
 
 Access control
 -----------------
 
+.. FIXME: duplicate from tutorial/properties.rst
+
+Access control is achieved through `properties`.
+
+
+.. glossary::
+
+   property
+
+       A property is a state (`disabled`, `mandatory`, `frozen`, `hidden`...)
+       of a family or a variable.
+       These properties change the usual behavior of a variable or family.
+
+The properties can be defined permanently or according to the result of a calculation.
+
+There is two main properties.
+
+Hidden variable
+~~~~~~~~~~~~~~~
+
+A `hidden` variable is a variable whose value cannot be modified by the operator.
+
+This could be an internal variable used by the integrator that is not supposed to change.
+
+Or a variable that only makes sense in a particular context. Therefore, this variable can be hidden and then unhidden depending on the context.
+
+Disabled variable
+~~~~~~~~~~~~~~~~~
+
+A `disabled` variable is a variable that will not be accessible to any of the actors (integrator and operator).
+
+This property is generally used dynamically to remove access to the variable depending on the context.
+
 .. list-table::
    :widths: 15 45
    :header-rows: 1
@@ -299,31 +353,27 @@ Access control
    * - Step
      - Actor
      - Lifetime
-     - Variable mutation
+     - Variable mutability
-     - Value mutation
+     - Value
-     - Read/Write
      - Access control
 
-   * - Structure
+   * - Structured data
      - Integrator
      - Creation + initialization
      - Mutable
-     - N/A
+     - Mutable default value
-     - N/A
      - N/A
 
    * - User data
      - Operator
-     - Assignment + permission
+     - Assignment and permission
      - Immutable
-     - Mutable
      - Read write
      - hidden + disabled
 
    * - Output
-     - Operator
+     - Operator or integrator
-     - Reading + permission + documentation + specialization
+     - Reading, permission, documentation and specialization
-     - Immutable
      - Immutable
      - Read only
      - disabled + mandatory

docs/structfile.rst

@@ -1,6 +1,20 @@
 The structure files
 =====================
 
+Definition
+------------
+
+.. glossary::
+
+   structure file
+
+       A structure file in the Rougail meaning is a YAML file that describes variables
+       and their dependencies.
+       There can be a lot of structure files located in many different folders.
+
+       Rougail reads all the structure files and loads them into a single object
+       that represents the whole :term:`context`.
+
 The header of a structure file
 -----------------------------------
 
@@ -39,10 +53,10 @@ The structured data
 
    structured data
    
-       We sometimes call "structured datas" the datas that are defined in the structure files,
+       We sometimes call "structured datas" the datas that are defined the structure,
        as opposed to :term:`user datas <user data>`\ .
-       For example when a value of a variable is defined in the structured datas, that is
+       For example when a value of a variable is defined in the structured datas
-       in a structured file, the assigned value's status is that the variable's value is a default value. 
+       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.
 

docs/tutorial/properties.rst

@@ -3,17 +3,17 @@ Define access to variable or family
 
 .. objectives:: Objectives
 
-   In this section we will see what a disabled variable or family is, and why it can be interesting 
+   In this section we will see what a disabled variable or family is, and why it can be interesting
-   to assign the `disabled` property to a variable or a family. 
+   to assign the `disabled` property to a variable or a family.
    Then we'll see the same thing for the `hidden` property.
-   We'll also learn the difference between disabling and hiding families or variables. 
+   We'll also learn the difference between disabling and hiding families or variables.
-   
+
    We will:
-   
+
    - create a `disabled` family
    - use a new family or variable's property: the `hidden` property
 
-Disabling and hiding are two families or variables properties. 
+Disabling and hiding are two families or variables properties.
 
 .. prerequisites:: Prerequisites
 
@@ -24,12 +24,12 @@ Disabling and hiding are two families or variables properties.
       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_050 <src/tag/v1.1_050/README.md>` to :tutorial:`v1.1_053 <src/tag/v1.1_053/README.md>` 
+    this workshop page corresponds to the tags :tutorial:`v1.1_050 <src/tag/v1.1_050/README.md>` to :tutorial:`v1.1_053 <src/tag/v1.1_053/README.md>`
     in the repository.
 
     ::
-   
+
        git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
        git switch --detach v1.1_050
 
@@ -40,15 +40,15 @@ Let's begin with defining what a property is:
 .. glossary::
 
    property
-   
+
        A property is a state (`disabled`, `mandatory`, `frozen`, `hidden`...)
-       of a family, a subfamily or a variable. 
+       of a family, a subfamily or a variable.
        These properties change the usual behavior of a variable or family.
 
 A disabled family
 ------------------
 
-Here we are going to assign the `disabled` property to the `manual` family: 
+Here we are going to assign the `disabled` property to the `manual` family:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/firefox/10-manual.yml
    :language: yaml
@@ -76,17 +76,17 @@ Here we are going to assign the `disabled` property to the `manual` family:
           type: port
           default: 8080
 
-Notice that we have this `disabled: true` property assigned to the `manual` family. 
+Notice that we have this `disabled: true` property assigned to the `manual` family.
 Let's launch the Rougail CLI on this structure file (whith an empty user data file):
 
 .. raw:: html
    :class: terminal
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/01/cmd_ro.txt
 
-.. 
+..
     rougail -m firefox/ -u yaml -yf config/02/config.yml
 
-The Rougail CLI outputs this: 
+The Rougail CLI outputs this:
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/01/output_ro.html
@@ -100,7 +100,7 @@ So what does this disabled property exactly?
    disabled
 
        The disabled property is a property that can be assigned to a variable or a family.
-       It makes the :term:`configuration` act as if the variable or family that has this property has not even been defined. 
+       It makes the :term:`configuration` act as if the variable or family that has this property has not even been defined.
        It simply doesn't exist (it is deactivated) for the whole configuration.
 
 .. note:: Note that if a family has been disabled, all variables and sub-families that it contains are disabled.
@@ -120,11 +120,11 @@ If we launch the Rougail CLI:
 ..
     rougail -m firefox/ -u yaml -yf config/02/config.yml --cli.unknown_user_data_error
 
-.. note:: The `--cli.unknown_user_data_error` option changes the behaviour of the Rougail CLI's standard output: 
+.. note:: The `--cli.unknown_user_data_error` option changes the behaviour of the Rougail CLI's standard output:
-          when an unknown (or disabled or hidden) variable is declared in the :term:`user data file <user data>` 
+          when an unknown (or disabled or hidden) variable is declared in the :term:`user data file <user data>`
           then it appears in the output as an error instead of a warning.
 
-It outputs: 
+It outputs:
 
 .. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_050/config/02/output_unknown.html
@@ -152,11 +152,11 @@ Because it is not logical. We are trying to assign values to variables that are
 
 The point is that we disable them in order to expose the fact that we don't use them,
 but it's not just that: if we fill them in, there might be a problem in the overall integrity of the whole :term:`configuration`.
-We shall fill and use in these variables in the `Manual proxy configuration` use case context only. 
+We shall fill and use in these variables in the `Manual proxy configuration` use case context only.
 Otherwise, **we need to disable them when they are not used**.
 
-In a practical point of view, if we fill them in, Rougail CLI will output a warning and the :term:`operator` will see it. 
+In a practical point of view, if we fill them in, Rougail CLI will output a warning and the :term:`operator` will see it.
-He will wonder : "oh, what am I doing?", I shall fill and use in these variables only in the `Manual proxy configuration` context. 
+He will wonder : "oh, what am I doing?", I shall fill and use in these variables only in the `Manual proxy configuration` context.
 
 A conditional disabled family
 ------------------------------
@@ -166,7 +166,7 @@ in order to set the proxy mode:
 
 .. image:: images/firefox_01.png
 
-These five choices are: 
+These five choices are:
 
 - No proxy
 - Auto-detect proxy settings for this network
@@ -174,20 +174,20 @@ These five choices are:
 - Manual proxy configuration
 - Automatic proxy configuration URL
 
-Actually if the `Manual proxy configuration` is not selected, we don't need to set 
+Actually if the `Manual proxy configuration` is not selected, we don't need to set
-these `address` and `port` variables, there is no point in setting them in 
+these `address` and `port` variables, there is no point in setting them in
 four out of our five use cases.
 
 .. important:: We need to **disable** variables or families that are not used
                in a given usage context.
 
-Disabling variables one by one can be replaced by disabling a whole family. 
+Disabling variables one by one can be replaced by disabling a whole family.
-If we don't choose the manual mode, we need to **disable** the whole `manual` family, it will disable 
+If we don't choose the manual mode, we need to **disable** the whole `manual` family, it will disable
-all the subfamilies and the variables in it. 
+all the subfamilies and the variables in it.
 
 Note that we've placed theses variables in the `http_proxy`
-subfamily. We can then disable it or even the parent `manual` subfamily in order to 
+subfamily. We can then disable it or even the parent `manual` subfamily in order to
-disable the `http_proxy` family and all the variables that are placed in it, because 
+disable the `http_proxy` family and all the variables that are placed in it, because
 the `manual` family variables shall be used only in the manual proxy use case context.
 
 Notice the `disabled: true` parameter set in the `manual` family:
@@ -197,7 +197,7 @@ Notice the `disabled: true` parameter set in the `manual` family:
    :language: yaml
    :caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file is disabled here
 
-.. 
+..
     ---
     manual:
       description: Manual proxy configuration
@@ -220,14 +220,14 @@ Notice the `disabled: true` parameter set in the `manual` family:
 .. type-along:: For those who follow the tutorial with the help of the git repository
 
     Now you need to checkout the :tutorial:`v1.1_051 <src/tag/v1.1_051/README.md>` version::
-     
+
           git switch --detach v1.1_051
 
-What could be usefull here is a *dynamically* disable or enable the `manual` family. 
+What could be usefull here is a *dynamically* disable or enable the `manual` family.
 The idea in this section is to dynamically set the enable/disable property according to the chosen use case context.
 
-In rougail, we can set a property's value **depending on** the value of another variable. 
+In rougail, we can set a property's value **depending on** the value of another variable.
-**The property's value is conditioned by** another variable. 
+**The property's value is conditioned by** another variable.
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/firefox/10-manual.yml
    :linenos:
@@ -258,29 +258,29 @@ In rougail, we can set a property's value **depending on** the value of another
           type: port
           default: 8080
 
-Now the `disabled` property has some parameter defined. First, let's explaine the `variable` parameter. 
+Now the `disabled` property has some parameter defined. First, let's explaine the `variable` parameter.
-This parameter specifies the target variable. The value of this target variable 
+This parameter specifies the target variable. The value of this target variable
 will be used to dynamically enable or disable our `manual` family.
 
-We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value. 
+We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value.
-The target variable is `_.proxy_mode`. 
+The target variable is `_.proxy_mode`.
 
 .. note:: The `_.` notation means the current path of the family you're currently in.
-          
+
-          In the python quasi algorithmic notation we could say that:  
+          In the python quasi algorithmic notation we could say that:
-          
+
           .. code-block:: python
-          
+
               _.proxy_mode == proxy_mode
-              
+
           This is true only because in our use case `proxy_mode` is located on the root path.
 
-Now regarding the `when_not` parameter, this means that if the target variable's value 
+Now regarding the `when_not` parameter, this means that if the target variable's value
-is `Manual proxy configuration` then the `manual` familiy **will not** be disabled 
+is `Manual proxy configuration` then the `manual` familiy **will not** be disabled
-(that is, it will be **enabled**). 
+(that is, it will be **enabled**).
 
-Regarding as the default value use case, the `proxy_mode`'s variable is `No proxy` by default. 
+Regarding as the default value use case, the `proxy_mode`'s variable is `No proxy` by default.
-The `manual` familiy is then **disabled by default**. 
+The `manual` familiy is then **disabled by default**.
 
 Let's launch the Rougail CLI on an empty user value file:
 
@@ -288,16 +288,16 @@ Let's launch the Rougail CLI on an empty user value file:
    :class: terminal
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/01/cmd_ro.txt
 
-.. 
+..
     rougail -m firefox/ -u yaml -yf config/01/config.ym
 
-We have this output: 
+We have this output:
 
 .. raw:: html
    :class: output
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/01/output_ro.html
 
-.. 
+..
     <pre>╭──────────────────── Caption ─────────────────────╮
     │ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #ffd700">Default value</span> │
     ╰──────────────────────────────────────────────────╯
@@ -309,11 +309,11 @@ We can see that the `manual` family and all the variables into it are not presen
 
 .. type-along:: Dynamically enabling the `manual` family
 
-Now we are going to choose the **manual mode**, that is the `Manual proxy configuration` 
+Now we are going to choose the **manual mode**, that is the `Manual proxy configuration`
 value for the `proxy_mode` variable, and things will become slightly different.
 
 If the manual mode for the proxy is not selected, then the `manual` family is disabled.
-On the other hand, if the manual proxy's configuration mode is selected, 
+On the other hand, if the manual proxy's configuration mode is selected,
 then the `manual` family **is enabled**:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/config.yml
@@ -334,43 +334,43 @@ Let's launch the Rougail CLI to verify this:
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/cmd_ro.txt
-   :class: terminal 
+   :class: terminal
 
-.. 
+..
     rougail -m firefox/ -u yaml -yf config/02/config.yml
 
-It outputs: 
+It outputs:
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/output_ro.html
-   :class: output 
+   :class: output
 
-.. 
+..
     <pre>╭────────────── Caption ───────────────╮
     │ Variable <span style="color: #00aa00">Modified value</span>              │
     │          (⏳ Original default value) │
     ╰──────────────────────────────────────╯
     Variables:
     <span style="color: #5c5cff">┣━━ </span>📓 proxy_mode (Configure Proxy Access to the Internet): <span style="color: #00aa00">Manual proxy </span>
-    <span style="color: #5c5cff">┃   </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/02/config.yml" (⏳ No 
+    <span style="color: #5c5cff">┃   </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/02/config.yml" (⏳ No
     <span style="color: #5c5cff">┃   </span>proxy)
     <span style="color: #5c5cff">┗━━ </span>📂 manual (Manual proxy configuration)
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>📂 http_proxy (HTTP Proxy)
-    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML 
+    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┃   </span>file "config/02/config.yml"
-    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file 
+    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">    </span>"config/02/config.yml" (⏳ 8080)
-    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from 
+    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span>the YAML file "config/02/config.yml" (⏳ true)
     </pre>
 
 .. rubric:: Explanation
 
-Here the `disabled` property **depends on** the value of the `proxy_mode` variable. 
+Here the `disabled` property **depends on** the value of the `proxy_mode` variable.
 It is the `variable` parameter that allows you to define the name of the target variable on which the `disabled` property depends.
 
-Please remember that this activation/deactivation of the `manual` family 
+Please remember that this activation/deactivation of the `manual` family
-depends on the value of the `proxy_mode` variable. Here we have 
+depends on the value of the `proxy_mode` variable. Here we have
 chosen the `Manual proxy configuration` value, so the `address` and `port` variables appear.
 
 A hidden family
@@ -379,20 +379,20 @@ A hidden family
 .. type-along:: For those who follow the tutorial with the help of the git repository
 
     Now you need to checkout the :tutorial:`v1.1_052 <src/tag/v1.1_052/README.md>` version::
-     
+
           git switch --detach v1.1_052
 
 Let's introduce a new property here:
 
-.. glossary:: 
+.. glossary::
 
    hidden
-   
+
-       A variable or family's property is hidden if its value **shall not be seen** in a given :term:`context`. 
+       A variable or family's property is hidden if its value **shall not be seen** in a given :term:`context`.
-       Anyway, these variables can be used if the context evolves. 
+       Anyway, these variables can be used if the context evolves.
-       
+
        This is the main difference between the `hidden` and the `disabled` properties:
-       
+
        - with the `disabled` property, the variables are *deactivated*
        - with the `hidden` property, the variables are just not seen when loading the user data.
 
@@ -439,24 +439,24 @@ Here is our new :file:`20-manual.yml` structure file:
 
    This is a port setting for the manual HTTPS configuration
 
-We have now a `hidden` property assigned to the `https_proxy` family, which is 
+We have now a `hidden` property assigned to the `https_proxy` family, which is
 hiding these two variables.
 
-.. questions:: Why a `hidden` property? 
+.. questions:: Why a `hidden` property?
 
     Here is a detailed explanation of this choice of the `hidden` property:
 
     We are in a use case where we want the HTTP mode configuration to be identical to the HTTPS mode configuration, so:
 
     - we need to have access to the HTTP mode configuration details
-    - this HTTP configuration will be duplicated using references to the default values, 
+    - this HTTP configuration will be duplicated using references to the default values,
-      so there is no need to request intervention from the :term:`operator` 
+      so there is no need to request intervention from the :term:`operator`
       to fill in the details of the default HTTPS configuration
-    - however, the :term:`operator` may want to have access to the HTTPS mode configuration if he wishes to, 
+    - however, the :term:`operator` may want to have access to the HTTPS mode configuration if he wishes to,
-      in order to assign customised values to it. 
+      in order to assign customised values to it.
       Therefore, the :term:`operator` must obviously be able to access this HTTPS configuration.
 
-If we launch the Rougail CLI on the this user data 
+If we launch the Rougail CLI on the this user data
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_052/config/01/config.yml
    :linenos:
@@ -477,17 +477,17 @@ If we launch the Rougail CLI on the this user data
 Let's launch the Rougail in read only (`RO`) mode first:
 
 .. raw:: html
-   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_052/config/01/cmd_ro.txt 
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_052/config/01/cmd_ro.txt
    :class: terminal
 
 ..
     rougail -m firefox/ -u yaml -yf config/01/config.yml
 
-We have this output: 
+We have this output:
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_052/config/01/output_ro.html
-   :class: output 
+   :class: output
 
 ..
     <pre><span style="font-weight: bold; color: #ffff00">🔔 Warning</span>
@@ -504,52 +504,52 @@ We have this output:
     ╰──────────────────────────────────────╯
     Variables:
     <span style="color: #5c5cff">┣━━ </span>📓 proxy_mode (Configure Proxy Access to the Internet): <span style="color: #00aa00">Manual proxy </span>
-    <span style="color: #5c5cff">┃   </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/01/config.yml" (⏳ No 
+    <span style="color: #5c5cff">┃   </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/01/config.yml" (⏳ No
     <span style="color: #5c5cff">┃   </span>proxy)
     <span style="color: #5c5cff">┗━━ </span>📂 manual (Manual proxy configuration)
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>📂 http_proxy (HTTP Proxy)
-    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML 
+    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┃   </span>file "config/01/config.yml"
-    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file 
+    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">    </span>"config/01/config.yml" (⏳ 8080)
-    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from 
+    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span>the YAML file "config/01/config.yml" (⏳ true)
     </pre>
 
 Now let's launch the Rougail CLI in read write mode (`RW`) on the same user data:
 
 .. raw:: html
-   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_052/config/01/cmd_rw.txt 
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_052/config/01/cmd_rw.txt
    :class: terminal
 
-We have this output: 
+We have this output:
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_052/config/01/output_rw.html
-   :class: output 
+   :class: output
 
 .. type-along:: The read only mode view and the read write mode view
 
 .. FIXME: à unifier avec l'autre définition de ro et rw dans la page dédiée rougail/rw_ro_modes.html
 
-.. glossary:: 
+.. glossary::
 
    read only mode
-   
+
-      We call this mode the `RO` mode. In this mode it is impossible to modify the values of the variables. 
+      We call this mode the `RO` mode. In this mode it is impossible to modify the values of the variables.
       This is the standard configuration usage mode.
 
-   read write mode 
+   read write mode
-      
+
-      We call this mode the `RW` mode. In this mode you can edit the variables, even these that have 
+      We call this mode the `RW` mode. In this mode you can edit the variables, even these that have
       been hidden or disabled.
-          
+
-Why these modes ? In this way, the :term:`operator` or the :term:`integrator` don't have to 
+Why these modes ? In this way, the :term:`operator` or the :term:`integrator` don't have to
-add or pop familiy properties each time we pass from one use (editing mode) to another 
+add or pop familiy properties each time we pass from one use (editing mode) to another
-(configuration using mode) to an other. Swithching modes with setting properties is not a good idea. 
+(configuration using mode) to an other. Swithching modes with setting properties is not a good idea.
 It's better to change the read write and the read_only mode inside a Rougail CLI session.
 
-.. note:: During a standard Rougail CLI session, the default usage is the read only mode. 
+.. note:: During a standard Rougail CLI session, the default usage is the read only mode.
           We can switch at any time tho the read write mode by adding the `--cli.read_write`
           Rougail CLI parameter.
 
@@ -560,14 +560,14 @@ In the both `RO` and `RW` modes of the Rougail CLI session, we have this warning
     🔔 Warning
     ┗━━ manual (Manual proxy configuration)
         ┗━━ https_proxy (HTTPS Proxy)
-            ┗━━ address (HTTPS address): 🔔 family "https_proxy" (HTTPS Proxy) has 
+            ┗━━ address (HTTPS address): 🔔 family "https_proxy" (HTTPS Proxy) has
-                property hidden, so cannot access to "address" (HTTPS address), it 
+                property hidden, so cannot access to "address" (HTTPS address), it
-                will be ignored when loading from the YAML file 
+                will be ignored when loading from the YAML file
                 "config/01/config.yml"
 
 We are warned that the `https_proxy` family has the `hidden` property.
 
-Note that this is only in the read only mode that the variables that lives in the `https_proxy` familiy are 
+Note that this is only in the read only mode that the variables that lives in the `https_proxy` familiy are
 set as **unmodifiable variable**:
 
 ::
@@ -576,17 +576,17 @@ set as **unmodifiable variable**:
         ┣━━ 📓 address (HTTPS address): http.proxy.net
         ┗━━ 📓 port (HTTPS Port): 3128
 
-It is logical that we don't have this unmodifiable setting in the read write mode, 
+It is logical that we don't have this unmodifiable setting in the read write mode,
 because the read/write mode is designed to be an editing mode.
 
 .. questions:: Question: shall we use the `disabled` property here?
 
-   Is it relevant to use the :term:`disabled property <disabled>` here? 
+   Is it relevant to use the :term:`disabled property <disabled>` here?
-   
+
-   **answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use case, 
+   **answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use case,
    we simply have to point their values ​​in one direction or another depending on this or that context,
-   that's why it is absolutely not a question of disabling them. The `manual.https_proxy.address` 
+   that's why it is absolutely not a question of disabling them. The `manual.https_proxy.address`
-   and the `manual.http_proxy.port` variables shall not be disabled in the manual mode. 
+   and the `manual.http_proxy.port` variables shall not be disabled in the manual mode.
 
 A conditional hidden family
 ----------------------------
@@ -594,7 +594,7 @@ A conditional hidden family
 .. type-along:: For those who follow the tutorial with the help of the git repository
 
     Now you need to checkout the :tutorial:`v1.1_053 <src/tag/v1.1_053/README.md>` version::
-     
+
           git switch --detach v1.1_053
 
 Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen,
@@ -606,10 +606,10 @@ Let's have a look at the HTPPS configuration corresponding structure file:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/firefox/20-manual.yml
    :linenos:
-   :language: yaml 
+   :language: yaml
    :caption: the :file:`firefox/20-manual.yml` structure file
 
-.. 
+..
     %YAML 1.2
     ---
     version: 1.1
@@ -642,39 +642,39 @@ We have added a new variable, named `use_for_https` here:
 
    This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS
 
-The variable that drives the hidden/show behavior is the `use_for_https` variable because the `hidden` property has 
+The variable that drives the hidden/show behavior is the `use_for_https` variable because the `hidden` property has
 a `variable` target parameter that points to it: `variable: _.use_for_https`.
 
 .. prerequisites:: Reminder
 
-   The underscore and the point before the variable (`_.use_for_https`) points to the variable that lives in the same 
+   The underscore and the point before the variable (`_.use_for_https`) points to the variable that lives in the same
    family.
 
 Let's introduce a new Rougail concept here:
 
-.. glossary:: 
+.. glossary::
 
    context
-   
+
        A :term:`configuration` is highly statefull and can change at any moment.
-       Sometimes somes minor changes in the :term:`user data <user data>` may involve chain reactions 
+       Sometimes somes minor changes in the :term:`user data <user data>` may involve chain reactions
        in the whole :term:`configuration`.
        The **context** is the state of the user data at one moment, the set of the values of the variables
-       at a given moment. 
+       at a given moment.
-       
+
-       This term refers in Rougail to the ability of a system to handle 
+       This term refers in Rougail to the ability of a system to handle
-       the *statefull* state of a configuration. 
+       the *statefull* state of a configuration.
-       It expresses the transition between one situation to another situation, 
+       It expresses the transition between one situation to another situation,
        that is, the deeply **statefull** aspects of a data set.
 
 Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
-Well, it depends on the :term:`context`. 
+Well, it depends on the :term:`context`.
 
-.. questions:: Question: how does it work? 
+.. questions:: Question: how does it work?
 
    How will this variable drive the reuse of HTTP data to HTTPS data?
 
-With this :confval:`use_for_https` boolean variable, there are two possibilities, and only two: 
+With this :confval:`use_for_https` boolean variable, there are two possibilities, and only two:
 
 - The http proxy's configuration will be reused for the https proxy's configuration
 - The http proxy's will not be reused for the https proxy's configuration
@@ -697,21 +697,21 @@ Here is an example with different user values for handling HTTP and HTTPS:
       https_proxy:
         address: https.proxy.net
 
-If we launch the Rougail CLI: 
+If we launch the Rougail CLI:
 
 .. raw:: html
    :class: terminal
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/01/cmd_ro.txt
 
-.. 
+..
     rougail -m firefox/ -u yaml -yf config/01/config.yml
 
-We have this output: 
+We have this output:
 
 .. raw:: html
    :class: output
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/01/output_ro.html
-   
+
 ..
     <pre>╭────────────── Caption ───────────────╮
     │ Variable <span style="color: #ffd700">Default value</span>               │
@@ -720,24 +720,24 @@ We have this output:
     ╰──────────────────────────────────────╯
     Variables:
     <span style="color: #5c5cff">┣━━ </span>📓 proxy_mode (Configure Proxy Access to the Internet): <span style="color: #00aa00">Manual proxy </span>
-    <span style="color: #5c5cff">┃   </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/01/config.yml" (⏳ No 
+    <span style="color: #5c5cff">┃   </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/01/config.yml" (⏳ No
     <span style="color: #5c5cff">┃   </span>proxy)
     <span style="color: #5c5cff">┗━━ </span>📂 manual (Manual proxy configuration)
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>📂 http_proxy (HTTP Proxy)
-    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML 
+    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┃   </span>file "config/01/config.yml"
-    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file 
+    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">    </span>"config/01/config.yml" (⏳ 8080)
-    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from 
+    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span>the YAML file "config/01/config.yml" (⏳ true)
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📂 https_proxy (HTTPS Proxy)
-    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTPS address): <span style="color: #00aa00">https.proxy.net</span> ◀ loaded from the YAML 
+    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTPS address): <span style="color: #00aa00">https.proxy.net</span> ◀ loaded from the YAML
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span>file "config/01/config.yml"
     <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTPS Port): <span style="color: #ffd700">8080</span>
     </pre>
 
 Notice that we have this `use_for_https` `boolean` type variable, its default value is `True`.
-We want to offer the possibility of providing an identical or possibly different proxy configuration for the HTTP and for the HTTPS protocols. 
+We want to offer the possibility of providing an identical or possibly different proxy configuration for the HTTP and for the HTTPS protocols.
 
 Here is an example with identical HTTP and HTTPS proxy configuration:
 
@@ -758,19 +758,19 @@ Here is an example with identical HTTP and HTTPS proxy configuration:
 Let's launch the Rougail CLI:
 
 .. raw:: html
-   :class: terminal 
+   :class: terminal
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/02/cmd_ro.txt
 
-.. 
+..
     rougail -m firefox/ -u yaml -yf config/02/config.yml
 
-We have this output: 
+We have this output:
 
 .. raw:: html
    :class: output
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/02/output_ro.html
-   
+
-.. 
+..
     <pre><span style="font-weight: bold; color: #ff0000">🛑 Caution</span>
     <span style="color: #ff0000">┗━━ </span>manual (Manual proxy configuration)
     <span style="color: #ff0000">    </span><span style="color: #ff0000">┗━━ </span>https_proxy (HTTPS Proxy)
@@ -778,26 +778,26 @@ We have this output:
     <span style="color: #ff0000">    </span><span style="color: #ff0000">    </span><span style="color: #ff0000">    </span><span style="color: #ff0000">and has no value</span>
     </pre>
 
-Which is logical, HTTPS proxy variables have no values set yet. 
+Which is logical, HTTPS proxy variables have no values set yet.
 We are going to see how to point HTTPS variables to HTTP variables.
 
 .. keypoints:: Key points progress
 
     **summary**
-    
+
     We have now the ability to build *contextual settings*:
 
     - if the `proxy_mode` variable's value is not `'Manual proxy configuration'` the `manual` family is disabled
     - if the `proxy_mode` variable's value is `'Manual proxy configuration'` then the `manual` family is enabled
-    - if the `use_for_https` variable's value is `true`, the HTTP configuration will be reused in the HTTPS situation 
+    - if the `use_for_https` variable's value is `true`, the HTTP configuration will be reused in the HTTPS situation
       and the `https_proxy` family will be hidden
     - if the `manual.https_proxy.address` has no value set, the defaut value is the same as the `manual.http_proxy.address`'s value
       (same behavior with the HTTP port and the HTTPS port variable)
-      
+
     And yes, we did it. We have arrived at the end of the proxy's manual configuration's section.
 
     **Keywords**
-    
+
     - We now know what a *property* is, we have seen in details the :term:`disabled` property,
     - We can target a variable's value in the `disabled` property's value,
       we call it a variable based contextual disabled family,