From eeba80204716eeece635b14f4aa165b79883b67a Mon Sep 17 00:00:00 2001 From: gwen Date: Tue, 6 Jan 2026 11:48:15 +0100 Subject: [PATCH] disabled ok --- docs/tutorial/disabled.rst | 177 +++++++++++++++++++++++-------------- 1 file changed, 113 insertions(+), 64 deletions(-) diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst index bdbffdb42..c60cfad91 100644 --- a/docs/tutorial/disabled.rst +++ b/docs/tutorial/disabled.rst @@ -75,7 +75,8 @@ Here we are going to assign the `disabled` property to the `manual` family: type: port default: 8080 -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 @@ -91,7 +92,7 @@ The Rougail CLI outputs this: :class: output We can deduce from the Rougail CLI output that the `manual` family is not taken into account by Rougail. -Let's first examine what this disabled property does. +So what does this disabled property exactly? .. glossary:: @@ -99,16 +100,15 @@ Let's first examine what this disabled property does. 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 simply doesn't exist. It is deactivated for the whole configuration. + It simply doesn't exist (it is deactivated) for the whole configuration. +.. note:: Note that, as with any property, if a family has been disabled, all variables and sub-families that it contains are disabled. -.. note:: Note that if a family has been disabled, all variables and sub-families that it contains are disabled. - -If we still wanna try to assign values to variables that have been disabled: +And if we try to assign values to variables that have been disabled, here is what happens: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/config.yml :language: yaml - :caption: Here in the :file:`config/02/config.yml` user data file, we assign values to disabled variables + :caption: In this :file:`config/02/config.yml` user data file, we assign values to variables that have been disabled If we launch the Rougail CLI: @@ -123,9 +123,9 @@ It outputs: :class: output We can see that the Rougail CLI is warning us about the variables that we are trying to assign values on which are disabled. -That is to say, they are not taken into account at the :term:`configuration` level. +Because it is not logical. We are trying to assign values to variables that are not taken into account at the :term:`configuration` level. -If we have a closer look at our use case, we have a choice between five options +Let's look again at our use case. We have a choice between five options in order to set the proxy mode: .. image:: images/firefox_01.png @@ -142,10 +142,10 @@ Actually if the `Manual proxy configuration` is not selected, we don't need to s these `address` and `port` variables, there is no point in setting them in four out of our five use cases. -We could say that we disable them in order to expose the fact that we don't use them, +The first 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. -Otherwise, **we need to disable them when they are not necessary**. +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. He will wonder : "oh, what am I doing?", I shall fill and use in these variables only in the `Manual proxy configuration` context. @@ -153,8 +153,9 @@ He will wonder : "oh, what am I doing?", I shall fill and use in these variables .. important:: We need to **disable** variables or families that are not used in a given usage context. -.. type-along:: Disabling variables one by one can be replaced by disabling a family +.. type-along:: Disabling a 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 all the subfamilies and the variables in it. @@ -199,10 +200,11 @@ A conditional disabled family git switch --detach v1.1_041 -What could be usefull here is a *dynamic setting* of the disable/enable property of 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. **It is conditioned by** 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. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/firefox/10-manual.yml :linenos: @@ -243,11 +245,12 @@ The target variable is `_.proxy_mode`. The `.` notation means the path of the family or subfamily you're currently in. The `_.` notation means the parent path of the current family or subfamily path. -Regarding the `when_not` parameter, it means that if the target variable's value -is `Manual proxy configuration` then the `manual` **will not** be disabled (that is, it will be enabled). - -Here as the default value for the `proxy_mode`'s variable is `No proxy`, the `manual` familiy is disabled. +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 +(that is, it will be **enabled**). +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**. Let's launch the Rougail CLI on an empty user value file: @@ -276,12 +279,12 @@ 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` +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, -then the `manual` family is re-activated (enabled). - -Now we are going to select the ** manual mode**, that is the `Manual proxy configuration` -value for the `proxy_mode` variable, and things will become slightly different. +then the `manual` family **is enabled**: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yml :linenos: @@ -297,15 +300,49 @@ value for the `proxy_mode` variable, and things will become slightly different. port: 3128 use_for_https: false -.. note:: Remember that this activation/deactivation of the `manual` family - depends on the value of the `proxy_mode` variable. Here we have - chosen the `Manual proxy configuration` value. +Let's launch the Rougail CLI to verify this: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/cmd_ro.txt + :class: terminal + +.. + rougail -m firefox/ -u yaml -yf config/02/config.yml + +It outputs: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/output_ro.html + :class: output + +.. + 
╭────────────── Caption ───────────────╮
+    │ Variable Modified value              │
+    │          (⏳ Original default value) │
+    ╰──────────────────────────────────────╯
+    Variables:
+    ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): Manual proxy 
+    ┃   configuration ◀ loaded from the YAML file "config/02/config.yml" (⏳ No 
+    ┃   proxy)
+    ┗━━ 📂 manual (Manual proxy configuration)
+        ┣━━ 📂 http_proxy (HTTP Proxy)
+        ┃   ┣━━ 📓 address (HTTP address): http.proxy.net ◀ loaded from the YAML 
+        ┃   ┃   file "config/02/config.yml"
+        ┃   ┗━━ 📓 port (HTTP Port): 3128 ◀ loaded from the YAML file 
+        ┃       "config/02/config.yml" (⏳ 8080)
+        ┗━━ 📓 use_for_https (Also use this proxy for HTTPS): false ◀ loaded from 
+            the YAML file "config/02/config.yml" (⏳ true)
+
.. rubric:: Explanation 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 +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. + Copy HTTP manual proxy to HTTPS manual proxy --------------------------------------------- @@ -322,7 +359,8 @@ We have split the definition of the `manual` familiy into two specific files: :class: output :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/tree.html -Here is the new :file:`20-manual.yml` file: +Here is the new :file:`20-manual.yml` file, which looks like the :file:`10-manual.yml` file +except that it is dedicated to the HTTPS protocol: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/firefox/20-manual.yml :linenos: @@ -450,22 +488,22 @@ We have this output: :class: output :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/output_ro.html -FIXME: il y a un dans le 
-
 .. 
-    
> [!CAUTION]
-    > 
-    > - manual (Manual proxy configuration)
-    >   - https_proxy (HTTPS Proxy)
-    >     - address (HTTPS address): :stop_sign: <span style="color: #C23636">mandatory variable but is inaccessible and has no value</span>
+    
🛑 Caution
+    ┗━━ manual (Manual proxy configuration)
+        ┗━━ https_proxy (HTTPS Proxy)
+            ┗━━ address (HTTPS address): 🛑 mandatory variable but is inaccessible 
+                and has no value
     

 
-We are going to see how to point HTTPS variables to HTTPS variables
-   
+Which is logical, HTTPS proxy variables have no values set yet. 
+We are going to see how to point HTTPS variables to HTTP variables.
+
 A conditional hidden family
 ----------------------------
 
-Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen.
+Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen,
+let's have a look at our use case again:
 
 .. image:: images/firefox_manual_https.png
 
@@ -494,7 +532,9 @@ Let's introduce a new Rougail concept here:
        Sometimes somes minor changes in the :term:`user datas ` may involve chain reactions 
        in the whole :term:`configuration`.
        The **context** is the state of the user datas at one moment, the set of the values of the variables
-       at a given moment. This term also refers to the ability of a system to handle 
+       at a given moment. 
+       
+       This term refers in Rougail to the ability of a system to handle 
        the *statefull* state of a configuration. 
        It expresses the transition between one situation to another situation, 
        that is, the deeply **statefull** aspects of a data set.
@@ -503,7 +543,7 @@ Let's introduce a new Rougail concept here:
 .. type-along:: A new variable which has the `boolean` type
 
 The best way to reproduce the `"Also use this HTTP proxy variables for HTTPS"` checkbox in the firefox interface
-is to add a boolean variable in our structure. A boolean variable can reproduce this binary choice option.
+is to add this `use_for_https` variable in our structure file. This boolean variable can reproduce this binary choice option.
 
 Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
 Well, it depends on the :term:`context`. 
@@ -531,8 +571,8 @@ With this :confval:`use_for_https` boolean variable, there are two possibilities
    
    **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 deactivating them. The `manual.https_proxy.address` 
-   and the `manual.http_proxy.port` variables shall not be disabled (deactivated) in the manual mode. 
+   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. 
 
 Let's introduce a new concept here:
 
@@ -541,8 +581,10 @@ Let's introduce a new concept here:
    hidden
    
        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. This is the main difference 
-       between the `hidden` and the `disabled` properties (with the `disabled` property, the variables are *deactivated*.
+       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*.
 
 Now we can set a `hidden` property to the `https_proxy` family:
 
@@ -555,7 +597,7 @@ Here is our new :file:`20-manual.yml` structure file:
 
 We have now a `hidden` property assigned to the `https_proxy` family. 
 The variable that drives the hidden/show behavior is the `use_for_https` variable because the `hidden` property has 
-a `variable` target parameter: `variable: _.use_for_https`
+a `variable` target parameter that points to it: `variable: _.use_for_https`.
 
 .. prerequisites:: Reminder
 
@@ -589,16 +631,6 @@ Here, the defaut value of `manual.https_proxy.address` points to `manual.http_pr
 This is the same thing for the default value of the `manual.https_proxy.port` variable, 
 which points to the `manual.http_proxy.port` value.
 
-We also say that the default value is *calculated*.
-
-.. glossary::
-
-   calculated
-   
-       We say that a variable's value or a default variable's value is calculated 
-       when there is a pointer which refers to another variable's value 
-       or if there is some :term:`jinja` code or a python function that calculates it. 
-
 To summarize the HTTP and HTTPS configuration in the manual use case context, 
 here are the two :file:`firefox/10-manual.yml` and :file:`firefox/20-manual.yml` structure files:
 
@@ -663,27 +695,44 @@ here are the two :file:`firefox/10-manual.yml` and :file:`firefox/20-manual.yml`
             variable: __.http_proxy.port
     ...
 
+We can see here that the `address` variable's default value is contitionned by the `__.http_proxy.address` variable's value. 
+The target variable is `http_proxy.address`. 
+
+The `.` notation means the path of the family or subfamily  you're currently in.
+The `__.` notation means the parent path of the parent path of the current subfamily path.
+
+.. note::  We also say that the `manual.https_proxy.address` and the the `manual.https_proxy.port` default values are *calculated*.
+
+.. glossary::
+
+   calculated
+   
+       We say that a variable's value or a default variable's value is calculated 
+       when there is a pointer which refers to another variable's value 
+       or if there is some :term:`jinja` code or a python function that calculates it. 
 
 .. keypoints:: Key points progress
 
     **summary**
     
-    We have now the ability to build a contextual setting:
+    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
-
-    - FIXME add the hidden steps
-
-    We have arrived at the end of the proxy's manual configuration's section.
+    - if the `use_for_https` variable's value is `true`, the HTTP configuration will be reused in the HTTPS situation 
+      and the `https_proxy` familiy 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 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
-    - The :term:`hidden` property set to a family
-    - The fact that a property can be set dynamically
-    - The conditional dependency of a `hidden` property that depends on a `boolean` variable.
-    - A calculated default value 
+      we call it a variable based contextual disabled family,
+    - The :term:`hidden` property set to a family,
+    - The fact that a property can be set dynamically,
+    - The conditional dependency of a `hidden` property can depends on a `boolean` variable,
+    - We know whant a calculated default value is.