From 3aed61cdb121d179990839fac2eb03299ada18d6 Mon Sep 17 00:00:00 2001
From: gwen <gwenaelremond@free.fr>
Date: Tue, 6 May 2025 16:49:03 +0200
Subject: [PATCH] disabled

---
 docs/tutorial/disabled.rst | 128 +++++++++++++++++++++++++++++++++++--
 1 file changed, 121 insertions(+), 7 deletions(-)

diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst
index 13d578f70..e6e841512 100644
--- a/docs/tutorial/disabled.rst
+++ b/docs/tutorial/disabled.rst
@@ -5,27 +5,141 @@ A family can disapear in the outerspace
 
    In this section we will learn:
 
-   - what is a *property*
-   - the `disabled` property
+   - what a *property* is
+   - what the `disabled` property is
    
    What is a disabled variable or family is, and why it is interesting to do that.
 
 .. prerequisites:: Reminders
 
-   - We have three variables: :confval:`proxy_mode`, :confval:`address` and :confval:`port`
+   - We have three variables: :confval:`proxy_mode`, :confval:`address` and :confval:`port` placed in the `http_proxy` subfamily.
+
+.. type-along:: The disabled property
+
+.. glossary::
+
+   property
+   
+       A property is a state (disabled, frozen, read_write, read_only, hidden ...)
+       of a family, a subfamily or a variable. These properties may vary 
+       depending on the context.
+
+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:
+
+.. image:: images/firefox_01.png
+
+The five choices are: 
+
+- No proxy
+- Auto-detect proxy settings for this network
+- Use system proxy settings
+- Manual proxy configuration
+- Automatic proxy configuration URL
+
+If the `Manual proxy configuration` is not selected, we don't need to set 
+the :confval:`address` and :confval:`port` variables, there is no point 
+in setting them. It's not just that: if we fill them in, there might be a problem in the overall integrity of the configuration. We shall fill and use in these variables 
+only in the `Manual proxy configuration` context. Otherwise, we need to disable them.
+
+.. important:: We need to have the ability to **disable** variables that are not used
+               in a given context. 
+
+If we don't choose the manual mode, we need to **disable** these variables. 
+They are not used anymore. 
+
+Note that we've placed theses variables in the `http_proxy`
+subfamily. We can then disable the whole `http_proxy` subfamily in order to 
+disable the variables that are placed in it.
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/firefox/10-manual.yml
+   :linenos:
+   :language: yaml
+   :caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file
+
+.. 
+    ---
+    manual:
+      description: Manual proxy configuration
+      disabled: true
+
+      http_proxy:
+        description: HTTP Proxy
+
+        address:
+          description: HTTP address
+          type: domainname
+          params:
+            allow_ip: true
+
+        port:
+          description: HTTP Port
+          type: port
+          default: 8080
 
 
+We can see here the `disabled: true` parameter set in the `manual` family.
 
----
-manual:
-  description: Manual proxy configuration
-  disabled: true
+.. attention:: We will intentionally create an inconsistency here in order to 
+               explore the `disabled` property's behavior.
+
+Let's decide to make an inconsistency in the configuration: we are going to 
+select **the manual mode** as its variables are disabled. 
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/config/03/config.yaml
+   :linenos:
+   :language: yaml
+   :caption: The manual setting in the :file:`config/03/config.yaml` user datas file
+
+..
+    ---
+    proxy_mode: Manual proxy configuration
+    manual:
+      http_proxy:
+        address: example.net
 
 
+Now let's validate the consitency of the configuration:
 
+.. code-block:: text
+   :class: terminal
 
+   rougail -v 1.1 -m firefox/ -u file -ff config/03/config.yaml   
 
+As expected, we encounter an error:
 
+.. raw:: html
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/config/03/output_ro.html
+   :class: error-box
 
+..
+    <pre>🛑 ERRORS
+    <span style="color: #ff0000">┗━━ </span>cannot access to optiondescription "manual" (Manual proxy configuration) because has property 
+    <span style="color: #ff0000">    </span>"disabled"
+    ╭────────────────────────── Caption ──────────────────────────╮
+    │ Variable                           <span style="color: #ffd700">Default value</span>            │
+    │ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
+    │ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
+    ╰─────────────────────────────────────────────────────────────╯
+    Variables:
+    <span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
+    </pre>
 
+.. keypoints:: Key points progress
 
+    **Keywords**
+    
+    - the :term:`property` concept
+    - the `disabled` property
+    - disabled variable or family
+    - raising a configuration's consistency error
+    
+    **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.
+