diabled property

docs/conf.py

@@ -14,7 +14,7 @@ todo_include_todos = True
 # -- Project information -----------------------------------------------------
 
 project = 'Rougail'
-copyright = '2019-2024, Silique'
+copyright = '2019-2025, Silique'
 author = 'gwen'
 
 # The short X.Y version

docs/tutorial/disabled.rst

@@ -27,8 +27,8 @@ A family can disapear in the outerspace
 A disabled family
 -----------------------
 
-Let's come back to our use case, we have a choice to make between five options
-to make a choice in order to set the proxy mode:
+Let's come back to our use case, we have a choice between five options
+in order to set the proxy mode:
 
 .. image:: images/firefox_01.png
 
@@ -128,6 +128,74 @@ As expected, we encounter an error:
     <span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
     </pre>
 
+To avoid this type of error, What we need is a *dynamic setting* of the disable/enable property. 
+
+.. type-along:: The conditional disabled property
+
+
+A conditional disabled family
+------------------------------
+
+
+If the manual mode for the proxy is not selected, then the `manual` family shall be disabled.
+On the other hand, if the manual proxy's configuration mode is selected, 
+then we need to activate the `manual` family.
+
+And we understand that this activation/deactivation of the `manual` family 
+depends on the value of the `proxy_mode` variable.
+
+In rougail, we can set a property's value depending on the value of another variable. That is, it is conditioned by another variable. 
+
+Here is how we can achieve this:
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_028/firefox/10-manual.yml
+   :linenos:
+   :language: yaml
+   :caption: The `manual` family in the :file:`firefox/10-manual.yml` structure file with a conditional disabled property
+
+.. 
+    ---
+    manual:
+      description: Manual proxy configuration
+      disabled:
+        type: variable
+        variable: proxy_mode
+        when_not: 'Manual proxy configuration'
+
+      http_proxy:
+        description: HTTP Proxy
+
+        address:
+          description: HTTP address
+          type: domainname
+          params:
+            allow_ip: true
+
+        port:
+          description: HTTP Port
+          type: port
+          default: 8080
+
+.. rubric:: Explanation
+
+Here we have the `disabled` property like this: 
+
+.. code-block:: yaml 
+
+      disabled:
+        type: variable
+        variable: proxy_mode
+        when_not: 'Manual proxy configuration'
+
+It means that the `disabled` property depends ont he `proxy_mode` variable:
+
+- if `proxy_mode == 'Manual proxy configuration'` disabled is false (that is, 
+  the `manual` family is **enabled**)
+- else the `disabled` property is true (that is, the `manual` family is **disabled**)
+
+
+
+
 .. keypoints:: Key points progress
 
     **Keywords**
@@ -136,10 +204,11 @@ As expected, we encounter an error:
     - the `disabled` property
     - disabled variable or family
     - raising a configuration's consistency error
-    
+    - variable based conditional disabled family
+        
     **Progress**
 
     - we have a :term:`family` named `manual`  and a sub family named `http_proxy`
     - And we have now two variables: :confval:`proxy_mode` and :confval:`address`. 
-    - We have disabled the `http_proxy` sub family.
+    - We have disabled the `manual` family (and the `http_proxy` sub family).