boolean type and hidden property

docs/tutorial/boolean.rst

@@ -1,15 +1,16 @@
-A new variable which has the `boolean` type
+The `hidden` property
-===============================================
+=======================
 
 .. objectives:: Objectives
 
-   In this section we will learn:
+   In this section we will:
    
-   - how to make a boolean type variable
+   - use a new family or variable's property: the `hidden` property
-   - how to reuse some value of a variable
+   - create a new variable's type: `boolean`
-     (in this use case we will reuse the HTTP configuration variables values for the HTTPS configuration)
+   - reuse a value of a variable for another variable
+     (in this use case we will reuse the HTTP configuration variables values for the HTTPS configuration).
 
-.. prerequisites:: Reminders
+.. prerequisites:: Reminder
 
    Let's summarize the configuration up to here
 
@@ -31,7 +32,7 @@ Whe have the `proxy_mode` configuration here:
         - Automatic proxy configuration URL
       default: No proxy
 
-With the manual subfamily in case of the "Manual proxy configuration" configuration option has been chosen:
+With the `manual` subfamily 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
@@ -59,9 +60,11 @@ With the manual subfamily in case of the "Manual proxy configuration" configurat
           type: port
           default: 8080
 
-.. type-along:: The HTTPS mode 
+OK then. Let's continue our proxy's configuration.
 
-Now we will focus on configuring the HTTPS mode in case of "Manual proxy 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
 
@@ -77,30 +80,38 @@ Let's set two other variables for the HTTPS use only:
 
    This is a port setting for the manual HTTPS configuration
 
-- So we have a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable
+- So we have 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
+- In the same way, we have a `manual.http_proxy.port` variable and a `manual.https_proxy.port` variable.
 
-.. type-along:: What do we want to reuse?
+The context 
+--------------
 
-Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
+Let's introduce a new Rougail concept here:
-It depends on the context. 
 
 .. glossary:: 
 
    context
    
-       A configuration is highly statefull and can change at any moment.
+       A :term:`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 
+       The **context** is the state of the user datas at one moment. The set of the values of the variables
+       in 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.
+       that is, the deeply **statefull** aspects of a data set.
 
-A new `boolean` type variable
--------------------------------
 
-We have a new variable, named `use_for_https` here:
+.. 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`
@@ -108,6 +119,10 @@ We have a new variable, named `use_for_https` here:
 
    This is a setting that enables to reuse 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
@@ -123,13 +138,13 @@ Its description in the structure file gives us this:
         type: boolean
         default: true
 
-.. type-along:: Update of the context
+.. prerequisites:: Reminder
 
-   So now we have three new variables in the manual mode of the http proxy configuration.
+   So now we have three new variables in the `manual` family which expresses 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
+   :caption: `firefox/20-manual.yml`
 
 ..
     ---
@@ -158,17 +173,17 @@ And with this :confval:`use_for_https` boolean variable, there are two possibili
 - 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: disabled?
+.. questions:: Question: shall we use the `disabled` property here?
 
    Is it relevant to use the :term:`disabled property <disabled>` here? 
    
-   **answer**: No! Because we *need* to use these variables at any case, 
+   **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. 
 
-Let's introduce here a new concept. 
+Let's introduce here a new concept here. 
 
 The hidden property
 ---------------------
@@ -213,7 +228,7 @@ Now we can set a `hidden` property to the `https_proxy` family:
 
 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
+.. important:: A `hidden` variable with the `mandatory` parameter set still shall have a defined value
 
 If we choose the manual proxy configuration mode, 
 
@@ -241,11 +256,11 @@ Rougail will raise an error:
     <span style="color: #ff0000">┗━━ </span>  - manual.http_proxy.address (HTTP address)
     </pre>
 
-A conditional hidden family with a boolean variable
+A conditional hidden family driven by 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. 
+Here is how to achieve this. 
 
 It is possible to add a `variable` parameter to the `hidden` attribute like this: