From 0293d4d455d5ed963e37ecf335bb255518b0dadc Mon Sep 17 00:00:00 2001 From: gwen Date: Tue, 27 May 2025 15:33:32 +0200 Subject: [PATCH] contexte --- docs/tutorial/boolean.rst | 131 +++++++++++++++++++++++++++++++++++--- 1 file changed, 122 insertions(+), 9 deletions(-) diff --git a/docs/tutorial/boolean.rst b/docs/tutorial/boolean.rst index ac0f2d398..a3f9d3b30 100644 --- a/docs/tutorial/boolean.rst +++ b/docs/tutorial/boolean.rst @@ -83,7 +83,19 @@ Let's set two other variables for the HTTPS use only: .. type-along:: What do we want to reuse? Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode? -It depends on the situation. +It depends on the context. + +.. glossary:: + + context + + A configuration is highly statefull and can change at any moment. + Sometimes somes minor changes in the :term:`user datas` involves chain reactions + in the whole :term:`configuration`. + The context is the state of the user datas at one moment, this term also refers + 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. A new `boolean` type variable ------------------------------- @@ -111,7 +123,7 @@ Its description in the structure file gives us this: type: boolean default: true -.. type-along:: Update on the situation +.. type-along:: Update of the context So now we have three new variables in the manual mode of the http proxy configuration. @@ -151,10 +163,10 @@ And with this :confval:`use_for_https` boolean variable, there are two possibili Is it relevant to use the :term:`disabled property ` here? **answer**: No! Because we *need* to use these variables at any case, - we simply have to point their values ​​in one direction or another depending on this or that situation. + we simply have to point their values ​​in one direction or another depending on this or that context. - It is absolutely not a question of deactivating them. The :confval:`manual.https_proxy.address` - and the :confval:`manual.http_proxy.port` variables shall not be disabled (deactivated) in the manual mode. + 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. Let's introduce here a new concept. @@ -166,12 +178,113 @@ The hidden property hidden A variable or family's property is hidden if its value shall not be seen in a given consistency. - Anyway, these variables can be used again if the situation evolves. This is the main difference + Anyway, these variables can be used again if the context evolves. This is the main difference between the `hidden` and the `disabled` properties. +Now we can set a `hidden` property to the `https_proxy` family: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/firefox/20-manual.yml + :language: yaml + :caption: The `https_proxy` subfamily with the `hidden` property + :name: HiddenPropertySubfamily + +.. + --- + manual: + + use_for_https: + description: Also use this proxy for HTTPS + default: true + + https_proxy: + description: HTTPS Proxy + hidden: true + + address: + description: HTTPS address + type: domainname + params: + allow_ip: true + + port: + description: HTTPS Port + type: port + default: 8080 + +The whole `https_proxy` family has been set to `hidden` here. + +.. type-along:: A `hidden` variable with the `mandatory` parameter set still shall have a defined value + +If we choose the manual proxy configuration mode, + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/config/03/config.yaml + :language: yaml + :caption: The Manual proxy configuration value is set .. - How can we tell Rougail that this :confval:`use_for_https` boolean variable is used to enable/disable - the use of variables from the entire family? - + --- + proxy_mode: Manual proxy configuration + +Note that in this context, if we don't set a value to the `manual.http_proxy.address` mandatory variable, even if it is `hidden`, +Rougail will raise an error: + +.. todo:: Ce raw html là est sur manual.http_proxy.address et pas manual.https_proxy.address + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/config/03/output_ro.html + :class: error-box + +.. + 
🛑 ERRORS
+    ┣━━ The following variables are mandatory but have no value:
+    ┗━━   - manual.http_proxy.address (HTTP address)
+
+ +A conditional hidden family with a boolean variable +-------------------------------------------------------- + +But we want this `hidden` property to be assigned dynamically depending on the `use_for_https` `true` or `false` value. +How to achieve this. + +It is possible to add a `variable` parameter to the `hidden` attribute like this: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_034/firefox/20-manual.yml + :language: yaml + :caption: The hidden property now depends on the value of `manual.use_for_https` + +.. + --- + manual: + + use_for_https: + description: Also use this proxy for HTTPS + default: true + + https_proxy: + description: HTTPS Proxy + hidden: + variable: manual.use_for_https + + address: + description: HTTPS address + type: domainname + params: + allow_ip: true + + port: + description: HTTPS Port + type: port + default: 8080 + +.. keypoints:: Key points + + **Keywords** + + - 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. + + **Progress** + + We have arrived at the end of the proxy's manual configuration's section.