review
This commit is contained in:
parent
aabc937d1c
commit
8b02c79dcc
4 changed files with 71 additions and 74 deletions
|
|
@ -25,7 +25,7 @@ Some suitable types
|
|||
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
||||
git switch --detach v1.1_030
|
||||
|
||||
.. type-along:: let's recap how far we've come
|
||||
.. type-along:: Let's recap how far we've come
|
||||
|
||||
We have an `http_proxy` family with an `address` variable in it.
|
||||
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ Group variables inside families
|
|||
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
||||
git switch --detach v1.1_020
|
||||
|
||||
.. type-along:: let's recap how far we've come
|
||||
.. type-along:: Let's recap how far we've come
|
||||
|
||||
We have this choice variable in its structure definition file:
|
||||
|
||||
|
|
@ -203,7 +203,7 @@ otherwise we will get an error if we try to access this variable:
|
|||
<span style="color: #ff0000">┗━━ </span> - manual.http_proxy.address (HTTP address)
|
||||
</pre>
|
||||
|
||||
.. type-along:: let's set user values in a user data file
|
||||
.. type-along:: Let's set user values in a user data file
|
||||
|
||||
Here is a user data file sample:
|
||||
|
||||
|
|
@ -248,18 +248,18 @@ Everything is OK:
|
|||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📓 HTTP address: example.net ◀ loaded from the YAML file "config/02/config.yml"
|
||||
</pre>
|
||||
|
||||
Let's recap about the user datas. We can see in this Rougail CLI output that:
|
||||
Let's recap about the user data. We can see in this Rougail CLI output that:
|
||||
|
||||
- the `proxy_mode` value is set by default by the :term:`integrator`
|
||||
- the `address` value is has been set by an :term:`operator`
|
||||
|
||||
.. keypoints:: let's review the key points
|
||||
.. keypoints:: Let's review the key points
|
||||
|
||||
**Keywords**
|
||||
|
||||
- we know how to define :term:`variable`\ s inside of a family
|
||||
- we now know what a :term:`mandatory` variable is and why it is necessary to assign values to the variables
|
||||
- we kwow how to set a variable's :term:`user value <user datas>`
|
||||
- we kwow how to set a variable's :term:`user value <user data>`
|
||||
- we have the big picture : the :term:`configuration`, which is (the structure files + the user data files)
|
||||
|
||||
**Progress**
|
||||
|
|
|
|||
|
|
@ -20,8 +20,8 @@ More precisely, this tutorial aims at reproducing :term:`variable`\ s behind thi
|
|||
|
||||
We'll call the variables **configuration options** since that's what the variables represent in this use case.
|
||||
|
||||
.. attention:: We are not coding a firefox plugin here.
|
||||
We are just going to handle some of the firefox configuration settings
|
||||
.. attention:: We are not coding a Firefox plugin here.
|
||||
We are just going to handle some of the Firefox configuration settings
|
||||
with Rougail. We are just validating them.
|
||||
|
||||
The configuration option values entered by the user have to be:
|
||||
|
|
@ -36,7 +36,7 @@ Let's dive into this **configuration options validation** use case.
|
|||
|
||||
It is advisable to follow this tutorial with the help of the corresponding :tutorial:`Rougail git repository tutorial <src/branch/1.1>`.
|
||||
You can instead copy/paste or download the different file contents that are explained in this tutorial step and save the files to your computer.
|
||||
However, if you use the git rougail tutorial repository, you will have all the necessary files distributed in the correct tree structure,
|
||||
However, if you use the git Rougail tutorial repository, you will have all the necessary files distributed in the correct tree structure,
|
||||
which is in our opinion much more practical.
|
||||
|
||||
::
|
||||
|
|
@ -45,7 +45,7 @@ Let's dive into this **configuration options validation** use case.
|
|||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:caption: The firefox tutorial
|
||||
:caption: The Firefox tutorial
|
||||
|
||||
preliminary
|
||||
choice
|
||||
|
|
|
|||
|
|
@ -65,6 +65,7 @@ This is an empty Rougail :term:`structure description file: <structure file>`
|
|||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_000/firefox/00-proxy.yml>`
|
||||
|
||||
This `version` specification is just the Rougail YAML's format version specification.
|
||||
YAML files are loaded using a version 1.2 file parser. It is recommended (but not mandatory) to specify this in the file header, especially for linters.
|
||||
By now, we have an empty structure file with the format specification in it.
|
||||
|
||||
Let's add our first variable
|
||||
|
|
@ -249,11 +250,8 @@ The chosen value is indicated in the Rougail's CLI output as the default choice.
|
|||
|
||||
- here is the short-hand default setting and description:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
:caption: The short-hand way of setting a default value and a description
|
||||
.. code-block:: yaml
|
||||
|
||||
..
|
||||
proxy_mode: No proxy # Configure Proxy Access to the Internet
|
||||
|
||||
- and there is the verbose way of setting a default value:
|
||||
|
|
@ -267,7 +265,7 @@ The chosen value is indicated in the Rougail's CLI output as the default choice.
|
|||
There are some other :term:`short-hand ways <short-hand notation>` with Rougail that you may encounter
|
||||
as you read the Rougail's documentation and tutorial.
|
||||
|
||||
.. admonition:: how to set a value -- the assignment
|
||||
.. admonition:: How to set a value -- the assignment
|
||||
|
||||
A default value has been set, great. This raises a question about what a normal value is.
|
||||
|
||||
|
|
@ -300,20 +298,20 @@ Now we will talk about the one that defines the values. His role is called the o
|
|||
The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated.
|
||||
The type validation is driven by the definitions in the :term:`structure file <structure file>`.
|
||||
|
||||
It is the operator's responsibility to set the user datas variables values.
|
||||
It is the operator's responsibility to set the user data variables values.
|
||||
The operator does not handle the structure files,
|
||||
he is responsible of other files called the :term:`user data files <user data file>`.
|
||||
|
||||
.. glossary::
|
||||
|
||||
user datas
|
||||
user data
|
||||
|
||||
User datas, as opposed to structured datas, are datas that only concern the assignment of values
|
||||
and not the consistency of the variables between them.
|
||||
|
||||
The variable's values are also called **user values**.
|
||||
|
||||
The consistency field is outside of the user datas scope.
|
||||
The consistency field is outside of the user data scope.
|
||||
The consistency is handled in the :term:`structured datas <structured data>`\ 's scope.
|
||||
|
||||
.. important:: For now, we don't know how to disable the default `mandatory` settings,
|
||||
|
|
@ -329,14 +327,14 @@ he is responsible of other files called the :term:`user data files <user data fi
|
|||
└── config
|
||||
└── config.yml
|
||||
|
||||
.. type-along:: how to set a user data value
|
||||
.. type-along:: How to set a user data value
|
||||
|
||||
If the integrator has not set any default value in his structure file,
|
||||
it's up to the operator to do the job in the `config.yml` file:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/config.yml
|
||||
:language: yaml
|
||||
:caption: A Rougail user datas file :file:`config/config.yml`, with a value set.
|
||||
:caption: A Rougail user data file :file:`config/config.yml`, with a value set.
|
||||
:name: RougailConfigDefaultValue
|
||||
|
||||
..
|
||||
|
|
@ -372,7 +370,7 @@ Now the `proxy_mode`'s new `No proxy` value is the same as the default value but
|
|||
comes from the :file:`config/02/config.yml` user data file. From now on this `proxy_mode` variable's value
|
||||
is a user data value and not a default value (even if it's actually the same value).
|
||||
|
||||
.. type-along:: structure values and user data values
|
||||
.. type-along:: Structure values and user data values
|
||||
|
||||
We can see with the Rougail CLI utility where the values come from.
|
||||
It can come from an integrator's setting or from an operator's setting.
|
||||
|
|
@ -385,7 +383,7 @@ It can come from an integrator's setting or from an operator's setting.
|
|||
Most of the time, the integrator and the operator are one and the same person,
|
||||
here we are talking about roles and not necessarily about people.
|
||||
|
||||
.. type-along:: user data files are where the user values live
|
||||
.. type-along:: User data files are where the user values live
|
||||
|
||||
We need to set the values in separate files, called `user data files`.
|
||||
|
||||
|
|
@ -393,12 +391,12 @@ We need to set the values in separate files, called `user data files`.
|
|||
|
||||
user data file
|
||||
|
||||
A user data file is a file where only :term:`user datas` are set.
|
||||
A user data file is a file where only :term:`user data` are set.
|
||||
|
||||
A user file is a file where there are only user datas in it, users can set values, called user values --
|
||||
A user file is a file where there are only user data 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`
|
||||
see also :term:`user data`
|
||||
|
||||
.. glossary::
|
||||
|
||||
|
|
@ -419,4 +417,3 @@ We need to set the values in separate files, called `user data files`.
|
|||
- a variable's user value
|
||||
- the :term:`integrator` and :term:`operator` roles
|
||||
- a :term:`configuration`
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue