diff --git a/docs/tutorial/boolean.rst b/docs/tutorial/boolean.rst index ef4ef6a5b..9628da415 100644 --- a/docs/tutorial/boolean.rst +++ b/docs/tutorial/boolean.rst @@ -6,9 +6,9 @@ The `hidden` property In this section we will: - use a new family or variable's property: the `hidden` property - - create a new variable's type: `boolean` + - 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 HTTPS configuration). + (in this use case we will reuse the HTTP configuration variables values for the configuration of the HTTPS). .. prerequisites:: Reminder @@ -32,7 +32,7 @@ Whe have the `proxy_mode` configuration here: - Automatic proxy configuration URL default: No proxy -With the `manual` subfamily that is used in case of the `"Manual proxy configuration"` value of the `proxy_mode` variable has been chosen: +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 @@ -68,7 +68,7 @@ Now we will focus on configuring the HTTPS mode in case of `"Manual proxy config .. image:: images/firefox_manual_https.png -Let's set two other variables for the HTTPS use only: +We are going to define two other variables for the HTTPS use only: .. confval:: https_proxy.address :type: `domainname` @@ -80,7 +80,7 @@ Let's set two other variables for the HTTPS use only: This is a port setting for the manual HTTPS configuration -- So we have two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable +- 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 @@ -93,10 +93,10 @@ 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` involves chain reactions - in the whole :term:`configuration`. + 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 - in a given moment. + 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, @@ -117,7 +117,7 @@ Let's create a new variable, named `use_for_https` here: :type: `boolean` :default: `true` - This is a setting that enables to reuse the HTTP proxy configuration for HTTPS + This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS .. questions:: Question: how does it work? @@ -140,7 +140,7 @@ Its description in the structure file gives us this: .. prerequisites:: Reminder - So now we have three new variables in the `manual` family which expresses the manual mode of the http proxy configuration. + 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 @@ -183,16 +183,16 @@ And with this :confval:`use_for_https` boolean variable, there are two possibili 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 here. +We have to create a new property here. -The hidden property ---------------------- +The `hidden` property +---------------------- .. glossary:: hidden - A variable or family's property is hidden if its value shall not be seen in a given consistency. + 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. diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst index 30d6eedf3..7f7b83851 100644 --- a/docs/tutorial/disabled.rst +++ b/docs/tutorial/disabled.rst @@ -5,17 +5,19 @@ The `disabled` property In this section we will learn: - - how to disable a family,(yes, a family can disapear in the outerspace) - what a *property* is - - what the `disabled` property is + - how to disable a family (yes, a family can disapear in the outerspace) + - explain the `disabled` property - What is a disabled variable or family is, and why it is interesting to do that. + We will see what is a disabled variable or family is, and why it is interesting to do that. .. prerequisites:: Reminder - We have three variables: :confval:`proxy_mode`, :confval:`address` and :confval:`port` placed in the `http_proxy` subfamily. -.. type-along:: The disabled property +A disabled property assigned to a family +--------------------------------------------- + .. glossary:: @@ -25,10 +27,6 @@ The `disabled` property of a family, a subfamily or a variable. These properties may vary depending on the context. - -A disabled family ------------------------ - .. glossary:: disabled @@ -52,11 +50,13 @@ The five choices are: 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. +only in the `Manual proxy configuration` context. 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. +.. type-along:: disabling the :confval:`address` and :confval:`port` variables + If we don't choose the manual mode, we need to **disable** these variables. They are not used anymore. @@ -92,11 +92,17 @@ disable the variables that are placed in it. We can see here the `disabled: true` parameter set in the `manual` family. -.. attention:: We will intentionally create an inconsistency here in order to - explore the `disabled` property's behavior. +A conditional disabled family +------------------------------ -Let's decide to make an inconsistency in the configuration: we are going to -select **the manual mode** as its variables are disabled. +.. warning:: In this section, we will **intentionally** create an inconsistency in the configuration + in order to explore the `disabled` property's behavior. + + +We are going to + +- 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 :linenos: @@ -110,6 +116,8 @@ select **the manual mode** as its variables are disabled. http_proxy: address: example.net +.. warning:: Remember that the `manual` family is disabled, so are the variables it contains. + Now let's validate the consitency of the configuration: @@ -137,23 +145,25 @@ As expected, we encounter an error: ┗━━ πŸ““ proxy_mode: Manual proxy configuration (No proxy) -To avoid this type of error, What we need is a *dynamic setting* of the disable/enable property. +.. 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 - -A conditional disabled family ------------------------------- - - 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 the `manual` family. +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. +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: @@ -196,27 +206,31 @@ Here we have the `disabled` property like this: variable: proxy_mode when_not: 'Manual proxy configuration' -It means that the `disabled` property **depends on** the value of another variable. +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. -What does it allow you to do? - -- if `proxy_mode` is not `'Manual proxy configuration'` it disables the `manual` family -- if `proxy_mode == 'Manual proxy configuration'` it enables the `manual` family .. 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 + **Keywords** - the :term:`property` concept - the `disabled` property - - disabled variable or family + - the `variable` target property + - a disabled variable or family - raising a configuration's consistency error - - variable based conditional disabled family + - a variable based contextual disabled family **Progress** - 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 disabled the `manual` family (and the `http_proxy` sub family). + - We have dynamically disabled the `manual` family (and the `http_proxy` sub family). diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index cc032e246..6464aa7a2 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -16,7 +16,7 @@ Preliminaries Making a structure file ------------------------- -.. exercise:: The folder structure +.. demo:: The folder structure Here is the tree structure we want to have:: diff --git a/docs/tutorial/proxymode.rst b/docs/tutorial/proxymode.rst index e584e7277..e9890a66e 100644 --- a/docs/tutorial/proxymode.rst +++ b/docs/tutorial/proxymode.rst @@ -1,4 +1,4 @@ -The `manual` family +Let's dive in ==================== .. objectives:: Objectives @@ -15,7 +15,9 @@ The `manual` family - We have a folder named :file:`firefox` and we are putting all the structure description files into it -.. type-along:: So we have this choice type variable in the structure file +.. type-along:: let's recap: we have this choice type variable + +In the structure description file, we have: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml :linenos: @@ -37,10 +39,10 @@ The `manual` family .. We're gonna put it in a :term:`family`. -.. note:: The variables, families, etc. will be created in several files for educational purposes. +.. warning:: The variables, families, etc. will be created in several files for educational purposes. Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make - a new structure file named :file:`firefox/10-manual.yml` - We could of course have put everything in one file, we decided to separate the files for reasons of ordering and clarity + a new structure file named :file:`firefox/10-manual.yml`\ . + We could of course have put everything in one file, we decided to separate the files for reasons of ordering and clarity. So we have now a `proxy_mode` variable. @@ -50,10 +52,10 @@ So we have now a `proxy_mode` variable. This is a setting that controls the proxy's type -A family named `manual` -------------------------- +Creating a new family +----------------------- -Let's create a family named `manual` +Let's create a family named `manual` which obviously corresponds to the proxy's manual configuration choice. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml :language: yaml @@ -69,17 +71,18 @@ Let's create a family named `manual` We can see that we have defined a :term:`family` here, and this family is *empty* (that is the family which is a container variable contains no variable yet). -.. admonition:: If a family is empty +.. warning:: - We need to specify the :term:`family` type here because if we don't, + If a family is empty, we need to specify the :term:`family` type here because if we don't, the Rougail's type engine will infer it by default as a :term:`variable`. - - It's because we don't have set any :term:`variable` inside. If we have a variable inside of a family, - we make a YAML block (that is, we just indent the lines) and the Rougail's type inference engine will implicitely infer it as a family. + We have to force the family type inference. + + It's because we don't have set any :term:`variable` inside yet. When we will have a variable inside of this family, + we will make a YAML block (that is, we just indent the lines) and the Rougail's type inference engine will implicitely infer the variable's container as a family type. .. type-along:: A family inside a family -Creating a family hierarchy is very easy, here is an example: +Creating a family hierarchy of family container types is very easy, here is an example: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml :language: yaml @@ -101,8 +104,8 @@ Here the `http_proxy` family lives inside the `manual` family. Putting a variable inside of a family or a sub family ---------------------------------------------------------- -Let's create a variable in its family. -The type of this variable is a `choice` type: +Let's create a variable in the `http_proxy` family. +This time, the type of this new variable is a `domainname` type: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/firefox/10-manual.yml :language: yaml @@ -123,9 +126,9 @@ The type of this variable is a `choice` type: description: HTTP address type: domainname -The :term:`operator` can now then set :term:`a value ` to the :confval:`address` variable +Now that the :confval:`address` variable is declarde, the :term:`operator` can set :term:`a value ` to the :confval:`address` variable -So we have now an `address` variable. +So we have now an :confval:`address` variable: .. confval:: address :type: `domainname` @@ -133,8 +136,8 @@ So we have now an `address` variable. This is the HTTP address of the proxy -.. note:: We encountered here a new type of variable there: the `domainname` type - +.. note:: We encountered here a new type of variable there: the `domainname` type. + There are a bunch of types available in Rougail. Assigning a user value ------------------------------------ @@ -152,7 +155,7 @@ otherwise we will get an error if we try to access this variable: ┗━━ - manual.http_proxy.address (HTTP address) -Because this variable is :term:`mandatory`. +Because the :term:`mandatory` variable attribute is infered by default for this variable. .. type-along:: user data files are where the user values lives @@ -162,14 +165,14 @@ And we need to set the values ​​in separate files too, called `user data fil user data file - A user data file is a file where only the user datas are assigned. + A user data file is a file where only :term:`user datas` are set. A user file is a file where there are only user datas in it, users can set values, called user values -- that is variable's values that have been set by an :term:`operator`\ . see also :term:`user datas` -Let's set user values in user data files +.. type-along:: let's set user values in a user data file Here is a user data file sample: @@ -233,6 +236,8 @@ Variables can have parameters We need to specify whether our variable accepts to be filled using an IP or a domain name only. This is where the ability to parameterize our variable comes in. +.. type-along:: let's create a variable parameter named `allow_ip` + .. --- manual: @@ -275,7 +280,7 @@ with IPs. A parameter is a property of a variable that can refine its behavior -.. type-along:: One more variable +.. type-along:: a second variable in the `http_proxy` family Let's create a `port` variable in the `http_proxy` family: @@ -312,9 +317,7 @@ Here is the new :file:`firefox/10-manual.yml` structure file: type: port default: 8080 -Take a look at lines 14 to 17. - -.. keypoints:: Key points progress +.. keypoints:: let's review the key points **Keywords**