diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst index 87baa966c..44e5c49a8 100644 --- a/docs/tutorial/disabled.rst +++ b/docs/tutorial/disabled.rst @@ -1,45 +1,122 @@ -The `disabled` property +Disabling things ======================== .. objectives:: Objectives - In this section we will learn: - - - what a *property* is (actually we already used one: the :term:`mandatory` property - - how to disable a family (yes, a family can disapear in the outerspace) - - explain the `disabled` property + In this section we will see what a disabled variable or family is, and why it can be interesting + to assign the `disabled` property to a variable or a family. - We will see what is a disabled variable or family is, and why it is interesting to do that. + We will disable a whole family here (yes, a family can disapear in the outerspace). -.. prerequisites:: Reminder +.. prerequisites:: Prerequisites - - We have three variables: :confval:`proxy_mode`, :confval:`address` and :confval:`port` placed in the `http_proxy` subfamily. + - We assume that Rougail's library is :ref:`installed ` on your computer. -A disabled property assigned to a family + - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step + by checking out the corresponding tag of the `rougail-tutorials` git repository. + Each tag corresponds to a stage of progress in the tutorial. + 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 ` + in the repository. + + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git switch --detach v1.1_040 + +A disabled family --------------------------------------------- +First, a definition: .. 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 property is a state (`disabled`, `mandatory`, `frozen`, `hidden`...) + of a family, a subfamily or a variable. + These properties change the usual behavior of a variable or family. + +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 + :language: yaml + :caption: The `manual` family has the `disabled` property set in this :file:`firefox/10-manual.yml` structure file + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + description: Manual proxy configuration + disabled: true + + http_proxy: # HTTP Proxy + + address: + description: HTTP address + type: domainname + params: + allow_ip: true + + port: + description: HTTP Port + type: port + default: 8080 + +.. raw:: html + :class: terminal + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/cmd_ro.txt + +.. + rougail -m firefox/ -u yaml -yf config/02/config.yml + +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 + :class: output + +We can deduce that the `manual` family is not taken into account by Rougail. .. glossary:: disabled - - The disabled property is a property of a variable or a family that is kind of deactivated - for the whole configuration. -Let's come back to our use case, we have a choice between five options + 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. + + +.. 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: + +.. 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 + +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 + :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 + :class: output + +Let's have a look at 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 -The five choices are: +These five choices are: - No proxy - Auto-detect proxy settings for this network @@ -48,23 +125,27 @@ The five choices are: - 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 when they are not necessary**. +the `address` and `port` variables, there is no point in setting them. +We could say 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 configuration. +We shall fill and use in these variables in the `Manual proxy configuration` context only. +Otherwise, **we need to disable them when they are not necessary**. -.. important:: We need to have the ability to **disable** variables that are not used - in a given context. +If we fill them in, Rougail CLI will output a warning and the :term:`operator` will wonder : "what am I doing?". +I shall fill and use in these variables only in the `Manual proxy configuration` context. -.. type-along:: disabling the :confval:`address` and :confval:`port` variables +.. important:: We need to **disable** variables or families that are not used + in a given usage context. + +.. type-along:: Disabling a group of variables is disabling a family 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. +subfamily. We can then disable the whole `manual` subfamily in order to +disable the `http_proxy` family and all 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 +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml :linenos: :language: yaml :caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file @@ -89,100 +170,39 @@ disable the variables that are placed in it. type: port default: 8080 +Notice the `disabled: true` parameter set in the `manual` family. -We can see here the `disabled: true` parameter set in the `manual` family. A conditional disabled family ------------------------------ -.. warning:: In this section, we will **intentionally** create an inconsistency in the configuration - in order to explore the `disabled` property's behavior. +.. 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:: + + git switch --detach v1.1_041 -We are going to +What we need is a *dynamic setting* of the disable/enable property of the `manual` family. +The idea in this section is to dynamically set the enable/disable tag according to the chosen context. -- select **the manual mode** value for the `proxy_mode` -- assing the `example.net` value to the `address` validate in the user data file. - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/config/03/config.yaml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/firefox/10-manual.yml :linenos: :language: yaml - :caption: The manual setting in the :file:`config/03/config.yaml` user datas file + :caption: The :file:`firefox/10-manual.yml` structure file. The `manual` family dynamically enabled or disabled + .. + %YAML 1.2 --- - proxy_mode: Manual proxy configuration - manual: - http_proxy: - address: example.net + version: 1.1 -.. warning:: Remember that the `manual` family is disabled, so are the variables it contains. - - -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 - -.. - 
🛑 ERRORS
-    ┗━━ cannot access to optiondescription "manual" (Manual proxy configuration) because has property 
-        "disabled"
-    ╭────────────────────────── Caption ──────────────────────────╮
-    │ Variable                           Default value            │
-    │ Undocumented variable              Modified value           │
-    │ Undocumented but modified variable (Original default value) │
-    ╰─────────────────────────────────────────────────────────────╯
-    Variables:
-    ┗━━ 📓 proxy_mode: Manual proxy configuration (No proxy)
-
- -.. questions:: Question - - How to avoid these error messages? - -Contextual setting of a property ------------------------------------- - -To avoid this type of error, what we need is a *dynamic setting* of the disable/enable property of the `manual` family. - -.. type-along:: The conditional disabled property - -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 (enable) 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' + variable: _.proxy_mode + when_not: Manual proxy configuration - http_proxy: - description: HTTP Proxy + http_proxy: # HTTP Proxy address: description: HTTP address @@ -195,6 +215,67 @@ Here is how we can achieve this: type: port default: 8080 +FIXME : trouver une autre formulation et expliquer un peu plus, notamment le "when_not" +.. note:: The `_.` Rougail's notation means the variable in the current workspace. + +We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value. + +As the default value for the `proxy_mode`'s variable is `No proxy`, the `manual` familiy is disabled. + +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 + +.. + rougail -m firefox/ -u yaml -yf config/01/config.ym + +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 + +.. + 
╭──────────────────── Caption ─────────────────────╮
+    │ Undocumented but modified variable Default value │
+    ╰──────────────────────────────────────────────────╯
+    Variables:
+    ┗━━ 📓 Configure Proxy Access to the Internet: No proxy
+
+ +We can see that the `manual` family and all the variables into it are not present. + +.. type-along:: Dynamically enabling the `manual` family + +Now if we choose **the manual mode**, that is the `Manual proxy configuration` value for the `proxy_mode`, things become slightly different. + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yaml + :linenos: + :language: yaml + :caption: The `proxy_mode`'s manual setting in the :file:`config/03/config.yaml` user datas file + +.. + --- + proxy_mode: Manual proxy configuration + manual: + http_proxy: + address: http.proxy.net + port: 3128 + use_for_https: false + +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 the `manual` family is activated (enabled). + +.. note:: Remember 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. + +FIXME expliquer ici mieux le "when_not" + .. rubric:: Explanation Here we have the `disabled` property like this: @@ -209,28 +290,18 @@ Here we have the `disabled` property like this: Here the `disabled` property **depends on** the value of another variable. The `variable` parameter allows you to define the name of the target variable on which the `disabled` property depends. - .. keypoints:: Key points progress **summary** We have the ability to build a contextual setting: - - if `proxy_mode` is not `'Manual proxy configuration'` it disables the `manual` family - - if `proxy_mode == 'Manual proxy configuration'` it enables the `manual` family + - if `proxy_mode` is not `'Manual proxy configuration'` the `manual` family is disabled + - if `proxy_mode == 'Manual proxy configuration'` the `manual` family is enabled **Keywords** - - the :term:`property` concept - - the `disabled` property - - the `variable` target property - - a disabled variable or family - - raising a configuration's consistency error - - a variable based contextual disabled family - - **Progress** + - 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 - - 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 dynamically disabled the `manual` family (and the `http_proxy` sub family). -