From 6da067f206c1917314ff614d32298416d50d907b Mon Sep 17 00:00:00 2001 From: gwen Date: Wed, 7 Jan 2026 16:42:21 +0100 Subject: [PATCH] typos --- docs/tutorial/disabled.rst | 22 +-- docs/tutorial/hidden.rst | 382 ------------------------------------- 2 files changed, 11 insertions(+), 393 deletions(-) delete mode 100644 docs/tutorial/hidden.rst diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst index c60cfad91..93a349312 100644 --- a/docs/tutorial/disabled.rst +++ b/docs/tutorial/disabled.rst @@ -1,15 +1,17 @@ -Disabling things -======================== +Define access to variable or family +========================================== .. objectives:: Objectives + FIXME: refaire les objectifs + 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'll also learn the difference between disabling and hiding families or variables. We will: - - `disable` a whole family here (yes, a family can disapear in the outerspace!) + - create a `disabled` family - use a new family or variable's property: the `hidden` property - reuse a value of a variable for another variable (in this use case we will reuse the HTTP configuration variables values for the configuration of the HTTPS). @@ -123,7 +125,7 @@ It outputs: :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. -Because it is not logical. We are trying to assign values to variables that are not taken into account at the :term:`configuration` level. +Because it is not logical. We are trying to assign values to variables that are not taken into account in the :term:`configuration`. Let's look again at our use case. We have a choice between five options in order to set the proxy mode: @@ -242,8 +244,7 @@ will be used to dynamically enable or disable our `manual` family. We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value. The target variable is `_.proxy_mode`. -The `.` notation means the path of the family or subfamily you're currently in. -The `_.` notation means the parent path of the current family or subfamily path. +.. note:: The `_.` notation means the current path of the family you're currently in. Now regarding the `when_not` parameter, this means that if the target variable's value is `Manual proxy configuration` then the `manual` familiy **will not** be disabled @@ -519,7 +520,7 @@ We have added two other variables for the HTTPS use only: This is a port setting for the manual HTTPS configuration -We have now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable +We have now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable. In the same way, we have a `manual.http_proxy.port` variable and a `manual.https_proxy.port` variable. Let's introduce a new Rougail concept here: @@ -529,9 +530,9 @@ Let's introduce a new Rougail concept here: context A :term:`configuration` is highly statefull and can change at any moment. - Sometimes somes minor changes in the :term:`user datas ` may involve chain reactions + Sometimes somes minor changes in the :term:`user data ` may involve chain reactions in the whole :term:`configuration`. - The **context** is the state of the user datas at one moment, the set of the values of the variables + The **context** is the state of the user data at one moment, the set of the values of the variables at a given moment. This term refers in Rougail to the ability of a system to handle @@ -698,8 +699,7 @@ here are the two :file:`firefox/10-manual.yml` and :file:`firefox/20-manual.yml` We can see here that the `address` variable's default value is contitionned by the `__.http_proxy.address` variable's value. The target variable is `http_proxy.address`. -The `.` notation means the path of the family or subfamily you're currently in. -The `__.` notation means the parent path of the parent path of the current subfamily path. +The `__.` notation means the parent path of the current subfamily path. .. note:: We also say that the `manual.https_proxy.address` and the the `manual.https_proxy.port` default values are *calculated*. diff --git a/docs/tutorial/hidden.rst b/docs/tutorial/hidden.rst deleted file mode 100644 index 32c204bf8..000000000 --- a/docs/tutorial/hidden.rst +++ /dev/null @@ -1,382 +0,0 @@ -:orphan: - -The `hidden` property -======================= - -.. objectives:: Objectives - - In this section we will: - - - use a new family or variable's property: the `hidden` property - - create a variable with a new type, the `boolean` type - - reuse a value of a variable for another variable - (in this use case we will reuse the HTTP configuration variables values for the configuration of the HTTPS). - -.. prerequisites:: Reminder - - Let's summarize the configuration up to here - -Whe have the `proxy_mode` configuration here: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/00-proxy.yml - :language: yaml - :caption: firefox/00-proxy.yml - -.. - --- - proxy_mode: - description: Configure Proxy Access to the Internet - choices: - - No proxy - - Auto-detect proxy settings for this network - - Use system proxy settings - - Manual proxy configuration - - Automatic proxy configuration URL - default: No proxy - -With the `manual` family that is used in case of the `"Manual proxy configuration"` value of the `proxy_mode` variable has been chosen: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/10-manual.yml - :language: yaml - :caption: firefox/10-manual.yml - -.. - --- - manual: - description: Manual proxy configuration - disabled: - 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 - -OK then. Let's continue our proxy's configuration. - -.. type-along:: The HTTPS mode - -Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen. - -.. image:: images/firefox_manual_https.png - -We are going to define two other variables for the HTTPS use only: - -.. confval:: https_proxy.address - :type: `domainname` - - This is an address setting for the manual HTTPS configuration - -.. confval:: https_proxy.port - :type: `port` - - This is a port setting for the manual HTTPS configuration - -- There are now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable -- In the same way, we have a `manual.http_proxy.port` variable and a `manual.https_proxy.port` variable. - -The context --------------- - -Let's introduce a new Rougail concept here: - -.. glossary:: - - context - - A :term:`configuration` is highly statefull and can change at any moment. - Sometimes somes minor changes in the :term:`user datas` may involve chain reactions - in the whole :term:`configuration`. - The **context** is the state of the user datas at one moment. The set of the values of the variables - at a given 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 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 a boolean variable in our structure. A boolean variable can reproduce this binary choice option. - -Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode? -Well, it depends on the :term:`context`. - -Let's create a new variable, named `use_for_https` here: - -.. confval:: use_for_https - :type: `boolean` - :default: `true` - - This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS - -.. questions:: Question: how does it work? - - How will this variable drive the reuse of HTTP data to HTTPS data? - -Its description in the structure file gives us this: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/20-manual.yml - :language: yaml - :caption: firefox/20-manual.yml - -.. - --- - manual: - - use_for_https: - description: Also use this proxy for HTTPS - type: boolean - default: true - -.. prerequisites:: Reminder - - So now we have three new variables in the `manual` family (with its `https_proxy` subfamily) which express the manual mode of the http proxy configuration. - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_032/firefox/20-manual.yml - :language: yaml - :caption: `firefox/20-manual.yml` - -.. - --- - manual: - - use_for_https: - description: Also use this proxy for HTTPS - default: true - - https_proxy: - description: HTTPS Proxy - - address: - description: HTTPS address - type: domainname - params: - allow_ip: true - - port: - description: HTTPS Port - type: port - default: 8080 - -And with this :confval:`use_for_https` boolean variable, there are two possibilities, and only two: - -- The http proxy's configuration will be reused for the https proxy's configuration -- The http proxy's will not be reused for the https proxy's configuration - -.. questions:: Question: shall we use the `disabled` property here? - - Is it relevant to use the :term:`disabled property ` here? - - **answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use case, - 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 `manual.https_proxy.address` - and the `manual.http_proxy.port` variables shall not be disabled (deactivated) in the manual mode. - -We have to create a new property here. - -The `hidden` property ----------------------- - -.. 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 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. - -.. warning:: A `hidden` variable with the `mandatory` parameter set still shall have a defined value, - even if it's hidden. - -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 - -.. - --- - 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: - -.. 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 contextual hidden family driven by a boolean variable ------------------------------------------------------------ - -What we want is having this `hidden` property assigned dynamically depending on the `use_for_https` `true` or `false` value. - -Here is how to achieve 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 - -Yes, it is possible to add a `variable` parameter to the `hidden` attribute. - -Variable type and parameters type are copied with default value ------------------------------------------------------------------- - -.. discussion:: A contextualized default value - - A contextualized default value is a default value (of a variable) that is driven by another variable. - This variable type and its parameters type are copied in the default value's target variable. - -There is something left in the https configuration mode of the proxy: - -- 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. - -By now, the default settings are set like this: - -.. code-block:: yaml - - port: - description: HTTPS Port - type: port - default: 8080 - -The dynamic setting of a default can be achieved in this way: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_035/firefox/20-manual.yml - :language: yaml - :caption: A default variable's value dynamically set - -.. - --- - 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 - default: - variable: manual.http_proxy.address - - port: - description: HTTPS Port - type: port - default: - variable: manual.http_proxy.port - -The default value is a pointer to another variable's value. -Here, the defaut value of `manual.https_proxy.address` points to `manual.http_proxy.address`. - -This is the same thing for the default value of the `manual.https_proxy.port` variable, -which points to the `manual.http_proxy.port` value. - -We also say that the default value is *calculated*. - -.. glossary:: - - calculated - - We say that a variable's value or a default variable's value is calculated - when there is a pointer which refers to another variable's value - or if there is some :term:`jinja` code or a python function that calculates it. - -.. 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. - - A calculated default value - - **Progress** - - We have arrived at the end of the proxy's manual configuration's section.