From b1f0e7e3dea430636ac0d76bfa6863233cf6d348 Mon Sep 17 00:00:00 2001 From: gwen Date: Thu, 8 Jan 2026 15:47:23 +0100 Subject: [PATCH] hidden --- docs/tutorial/disabled.rst | 305 +++++++++++++++++++++---------------- 1 file changed, 171 insertions(+), 134 deletions(-) diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst index b3bd998e6..4ba28666d 100644 --- a/docs/tutorial/disabled.rst +++ b/docs/tutorial/disabled.rst @@ -12,7 +12,6 @@ Define access to variable or family - create a `disabled` family - use a new family or variable's property: the `hidden` property - .. prerequisites:: Prerequisites - We assume that Rougail's library is :ref:`installed ` on your computer. @@ -23,16 +22,16 @@ Define access to variable or family 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 `, - this workshop page corresponds to the tags :tutorial:`v1.1_040 ` to :tutorial:`v1.1_044 ` + this workshop page corresponds to the tags :tutorial:`v1.1_050 ` to :tutorial:`v1.1_053 ` in the repository. :: git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git - git switch --detach v1.1_040 + git switch --detach v1.1_050 A disabled family ---------------------------------------------- +------------------ Disabling and hiding are two families or variables properties. Let's begin with defining what a property is: @@ -47,7 +46,7 @@ defining what a property is: 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_040/firefox/10-manual.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/firefox/10-manual.yml :language: yaml :caption: The `manual` family has the `disabled` property set in this :file:`firefox/10-manual.yml` structure file @@ -78,7 +77,7 @@ Let's launch the Rougail CLI on this structure file (whith an empty user data fi .. raw:: html :class: terminal - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/cmd_ro.txt + :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 @@ -86,7 +85,7 @@ Let's launch the Rougail CLI on this structure file (whith an empty user data fi The Rougail CLI outputs this: .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/01/output_ro.html :class: output We can deduce from the Rougail CLI output that the `manual` family is not taken into account by Rougail. @@ -104,20 +103,20 @@ So what does this disabled property exactly? 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 +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/02/config.yml :language: yaml :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: .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/cmd_ro.txt + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/02/cmd_ro.txt :class: terminal It outputs: .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/02/output_ro.html :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. @@ -164,7 +163,7 @@ the `manual` family variables shall be used only in the manual proxy use case co Notice the `disabled: true` parameter set in the `manual` family: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/firefox/10-manual.yml :linenos: :language: yaml :caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file is disabled here @@ -194,9 +193,9 @@ A conditional disabled family .. type-along:: For those who follow the tutorial with the help of the git repository - Now you need to checkout the `v1.1_041` version:: + Now you need to checkout the `v1.1_051` version:: - git switch --detach v1.1_041 + git switch --detach v1.1_051 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. @@ -204,7 +203,7 @@ The idea in this section is to dynamically set the enable/disable property accor 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 +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/firefox/10-manual.yml :linenos: :language: yaml :caption: The :file:`firefox/10-manual.yml` structure file. The `manual` family dynamically enabled or disabled @@ -253,7 +252,7 @@ Let's launch the Rougail CLI on an empty user value file: .. raw:: html :class: terminal - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/cmd_ro.txt + :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 @@ -262,7 +261,7 @@ We have this output: .. raw:: html :class: output - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/01/output_ro.html .. 
╭──────────────────── Caption ─────────────────────╮
@@ -283,7 +282,7 @@ If the manual mode for the proxy is not selected, then the `manual` family is di
 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_041/config/02/config.yml
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/config.yml
    :linenos:
    :language: yaml
    :caption: The `proxy_mode`'s manual setting in the :file:`config/02/config.yaml` user datas file
@@ -300,7 +299,7 @@ then the `manual` family **is enabled**:
 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
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/cmd_ro.txt
    :class: terminal 
 
 .. 
@@ -309,7 +308,7 @@ Let's launch the Rougail CLI to verify this:
 It outputs: 
 
 .. raw:: html
-   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/output_ro.html
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/output_ro.html
    :class: output 
 
 .. 
@@ -340,119 +339,81 @@ 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.
 
+A hidden family
+-------------------
 
+.. type-along:: For those who follow the tutorial with the help of the git repository
 
+    Now you need to checkout the `v1.1_052` version::
+     
+          git switch --detach v1.1_052
 
-FIXME
+Let's introduce a new property here:
 
+.. glossary:: 
 
+   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*
+       - with the `hidden` property, the variables are just not seen.
 
+Now we can set a `hidden` property to the `https_proxy` family:
 
-Here is an example with different user values for handling HTTP and HTTPS:
+Here is our new :file:`20-manual.yml` structure file:
 
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/config.yml
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_052/firefox/20-manual.yml
    :linenos:
    :language: yaml
-   :caption: User datas in the user data file :file:`config/01/config.yml` with `use_for_https` as false
+   :caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.
 
 ..
+    %YAML 1.2
     ---
-    proxy_mode: Manual proxy configuration
+    version: 1.1
+
     manual:
-      http_proxy:
-        address: http.proxy.net
-        port: 3128
-      use_for_https: false
+
+      use_for_https: true  # Also use this proxy for HTTPS
+
       https_proxy:
-        address: https.proxy.net
+        description: HTTPS Proxy
+        hidden: true
 
-If we launch the Rougail CLI: 
+        address:
+          description: HTTPS address
+          default:
+            variable: __.http_proxy.address
 
-.. raw:: html
-   :class: terminal
-   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/cmd_ro.txt
+        port:
+          description: HTTPS Port
+          default:
+            variable: __.http_proxy.port
+    ...
 
-.. 
-    rougail -m firefox/ -u yaml -yf config/01/config.yml
-
-We have this output: 
-
-.. raw:: html
-   :class: output
-   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/output_ro.html
-   
-..
-    
╭────────────── Caption ───────────────╮
-    │ Variable Default value               │
-    │          Modified value              │
-    │          (⏳ Original default value) │
-    ╰──────────────────────────────────────╯
-    Variables:
-    ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): Manual proxy 
-    ┃   configuration ◀ loaded from the YAML file "config/01/config.yml" (⏳ No 
-    ┃   proxy)
-    ┗━━ 📂 manual (Manual proxy configuration)
-        ┣━━ 📂 http_proxy (HTTP Proxy)
-        ┃   ┣━━ 📓 address (HTTP address): http.proxy.net ◀ loaded from the YAML 
-        ┃   ┃   file "config/01/config.yml"
-        ┃   ┗━━ 📓 port (HTTP Port): 3128 ◀ loaded from the YAML file 
-        ┃       "config/01/config.yml" (⏳ 8080)
-        ┣━━ 📓 use_for_https (Also use this proxy for HTTPS): false ◀ loaded from 
-        ┃   the YAML file "config/01/config.yml" (⏳ true)
-        ┗━━ 📂 https_proxy (HTTPS Proxy)
-            ┣━━ 📓 address (HTTPS address): https.proxy.net ◀ loaded from the YAML 
-            ┃   file "config/01/config.yml"
-            ┗━━ 📓 port (HTTPS Port): 8080
-    

-
-Notice that we have a `use_for_https` new variable, this variable is a `boolean` type, 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. 
-
-Here is an example with identical HTTP and HTTPS proxy configuration:
-
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/config.yml
-   :linenos:
-   :language: yaml
-   :caption: User datas in the user data file :file:`config/02/config.yml` with `use_for_https` as true
-
-..
-    ---
-    proxy_mode: Manual proxy configuration
-    manual:
-      http_proxy:
-        address: http.proxy.net
-        port: 3128
-      use_for_https: true
-
-Let's launch the Rougail CLI:
-
-.. raw:: html
-   :class: terminal 
-   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/cmd_ro.txt
-
-.. 
-    rougail -m firefox/ -u yaml -yf config/02/config.yml
-
-We have this output: 
-
-.. raw:: html
-   :class: output
-   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/output_ro.html
-   
-.. 
-    
🛑 Caution
-    ┗━━ manual (Manual proxy configuration)
-        ┗━━ https_proxy (HTTPS Proxy)
-            ┗━━ address (HTTPS address): 🛑 mandatory variable but is inaccessible 
-                and has no value
-    

-
-Which is logical, HTTPS proxy variables have no values set yet. 
-We are going to see how to point HTTPS variables to HTTP variables.
+We have now a `hidden` property assigned to the `https_proxy` family. 
 
 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 `v1.1_053` version::
+     
+          git switch --detach v1.1_053
+
+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 parent 
+   family.
+
 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:
 
@@ -490,12 +451,16 @@ Let's introduce a new Rougail concept here:
        It expresses the transition between one situation to another situation, 
        that is, the deeply **statefull** aspects of a data set.
 
-
 .. 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 this `use_for_https` variable in our structure file. This boolean variable can reproduce this binary choice option.
 
+- if the use of the proxy variables for https are the same of the proxy variables for http, 
+  that is, if `use_for_https` is true, the https configuration variables are hidden, that's OK. 
+- if the use of the proxy variables for https **are not** the same of the proxy variables for http, 
+  we would like to set their default values to the http proxy variables values.
+
 Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
 Well, it depends on the :term:`context`. 
 
@@ -525,35 +490,107 @@ With this :confval:`use_for_https` boolean variable, there are two possibilities
    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:
+Here is an example with different user values for handling HTTP and HTTPS:
 
-.. glossary:: 
-
-   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*.
-
-Now we can set a `hidden` property to the `https_proxy` family:
-
-Here is our new :file:`20-manual.yml` structure file:
-
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_043/firefox/20-manual.yml
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/01/config.yml
    :linenos:
    :language: yaml
-   :caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.
+   :caption: User datas in the user data file :file:`config/01/config.yml` with `use_for_https` as false
 
-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 that points to it: `variable: _.use_for_https`.
+..
+    ---
+    proxy_mode: Manual proxy configuration
+    manual:
+      http_proxy:
+        address: http.proxy.net
+        port: 3128
+      use_for_https: false
+      https_proxy:
+        address: https.proxy.net
 
-.. prerequisites:: Reminder
+If we launch the Rougail CLI: 
 
-   The underscore and the point before the variable (`_.use_for_https`) points to the variable that lives in the parent 
-   family.
+.. 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: 
+
+.. raw:: html
+   :class: output
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/01/output_ro.html
+   
+..
+    
╭────────────── Caption ───────────────╮
+    │ Variable Default value               │
+    │          Modified value              │
+    │          (⏳ Original default value) │
+    ╰──────────────────────────────────────╯
+    Variables:
+    ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): Manual proxy 
+    ┃   configuration ◀ loaded from the YAML file "config/01/config.yml" (⏳ No 
+    ┃   proxy)
+    ┗━━ 📂 manual (Manual proxy configuration)
+        ┣━━ 📂 http_proxy (HTTP Proxy)
+        ┃   ┣━━ 📓 address (HTTP address): http.proxy.net ◀ loaded from the YAML 
+        ┃   ┃   file "config/01/config.yml"
+        ┃   ┗━━ 📓 port (HTTP Port): 3128 ◀ loaded from the YAML file 
+        ┃       "config/01/config.yml" (⏳ 8080)
+        ┣━━ 📓 use_for_https (Also use this proxy for HTTPS): false ◀ loaded from 
+        ┃   the YAML file "config/01/config.yml" (⏳ true)
+        ┗━━ 📂 https_proxy (HTTPS Proxy)
+            ┣━━ 📓 address (HTTPS address): https.proxy.net ◀ loaded from the YAML 
+            ┃   file "config/01/config.yml"
+            ┗━━ 📓 port (HTTPS Port): 8080
+    

+
+Notice that we have a `use_for_https` new variable, this variable is a `boolean` type, 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. 
+
+Here is an example with identical HTTP and HTTPS proxy configuration:
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/02/config.yml
+   :linenos:
+   :language: yaml
+   :caption: User datas in the user data file :file:`config/02/config.yml` with `use_for_https` as true
+
+..
+    ---
+    proxy_mode: Manual proxy configuration
+    manual:
+      http_proxy:
+        address: http.proxy.net
+        port: 3128
+      use_for_https: true
+
+Let's launch the Rougail CLI:
+
+.. raw:: html
+   :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: 
+
+.. raw:: html
+   :class: output
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/02/output_ro.html
+   
+.. 
+    
🛑 Caution
+    ┗━━ manual (Manual proxy configuration)
+        ┗━━ https_proxy (HTTPS Proxy)
+            ┗━━ address (HTTPS address): 🛑 mandatory variable but is inaccessible 
+                and has no value
+    

+
+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