stove/rougail
3
0
Fork 0
Code Issues 5 Pull requests 1 Projects Releases Wiki Activity

modifs

Browse source
This commit is contained in:
gwen 2025-05-05 21:39:32 +02:00
parent 91ffd19336
commit 935b33d28e
4 changed files with 36 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
docs/tutorial/preliminary.rst
View file

@ -6,7 +6,7 @@ Preliminaries
We will learn how to:
- create a Rougail :term:`structure description file <structure file>`
- define a Rougail :term:`structure description file <structure file>` format version
- define a Rougail :term:`structure file format version <structure file>`
- define a Rougail :term:`variable` and set its :term:`value`
.. prerequisites:: Prerequisites
@ -138,7 +138,7 @@ So let's define a variable with a description -- **and a default value**
How to set a value
----------------------
So far we have only talked about the one that writes the structure files. It is called the integrator.
So far we have only talked about the one that writes the structure files. It's role is called the integrator's role.
.. glossary::
@ -159,20 +159,22 @@ Now we will talk about the one that defines the values. It is called the operato
An operator ih the Rougail logic is the person who gives :term:`value`\ s to the pre-defined variables,
his responsabilities are to set variable values correctly.
The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated by the :term:`structure file definition <structure file>`.
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 :term:`definitions in the structure file <structure file>`.
Values are mandatory
-------------------------
It is the operator's responsibility to set configuration options values.
He does not work with the structure file,
he is responsible for other files, called the configuration files.
It is the operator's responsibility to set the user datas variables values.
The operator does not toutch the structure files,
he is responsible for other files called the :term:`user data file`\ s.
.. glossary::
configuration file
user datas
User datas, as opposed to structured datas, means datas where the consistency of the variables is not concerned, not in the scope (the consistency in the structured datas scope's).
For example, variable's values (which are also called **user values**).
A configuration file is a file where only the values ​​of the configuration options are assigned. The structure, the consistency of the variables between them is not the responsibility of these files (but of the structure files).
.. exercise:: Folder structure update
@ -184,14 +186,14 @@ he is responsible for other files, called the configuration files.
└── config
└── config.yml
.. type-along:: how to set a default value in a configuration file
.. type-along:: how to set a value in a user datas file
So for example if the integrator has not set any default value in his structure file,
the operator can do it like this:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/config/02/config.yaml
:language: yaml
:caption: The Rougail configuration file :file:`config/config.yml`, with a default value set.
:caption: A Rougail user datas file :file:`config/config.yml`, with a default value set.
:name: RougailConfigDefaultValue
..
@ -202,14 +204,14 @@ With the rougail CLI the operator has to add the `-u file -ff config/config.yml`
.. code-block:: text
:class: terminal
:caption: A rougail Command Line Utility call with the :file:`config/config.yml` Rougail configuration file
:caption: A rougail Command Line Utility call with the :file:`config/config.yml` Rougail user datas file
rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml
Let us clarify this essential point:
- the integrator works on dictionaries
- the operator works on configuration files
- the integrator works on structure files
- the operator works on user data files
.. note:: 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.

36
docs/tutorial/proxymode.rst
View file

@ -75,7 +75,7 @@ We can see that we have defined a :term:`family` here, and this family is *empty
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 indent) and the Rougail's type inference engine will implicitely infer it as 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.
.. type-along:: A family inside a family
@ -154,20 +154,24 @@ otherwise we will get an error if we try to access this variable:
Because this variable is :term:`mandatory`.
.. type-along:: user files are where the user values lives
.. type-along:: user data files are where the user values lives
And we need to set the values ​​in separate files too, called `user files`.
And we need to set the values ​​in separate files too, called `user data files`.
.. glossary::
user file
user data file
A user file is a file where users can set values, called user values --
that is variable's values that have been set by an :term:`operator`\ .
A user data file is a file where only the user datas are assigned.
Let's set user values in user files
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`
Here is a user file sample:
Let's set user values in user data files
Here is a user data file sample:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/config/03/config.yaml
:language: yaml
@ -265,6 +269,12 @@ This is where the ability to parameterize our variable comes in.
We can see line 11 and 12 that the params allow the domain name `address` variable to be set
with IPs.
.. glossary::
parameter
A parameter is a property of a variable that can refine its behavior
.. type-along:: One more variable
Let's create a `port` variable in the `http_proxy` family:
@ -304,20 +314,14 @@ Here is the new :file:`firefox/10-manual.yml` structure file:
Take a look at lines 14 to 17.
.. glossary::
parameter
A parameter is a property of a variable that can refine its behavior
.. keypoints:: Key points progress
**Keywords**
- we know how to define :term:`variable`\ s inside of a family
- we now know what a :term:`mandatory` variable is
- we kwow how to set a variable's user value (in a :term:`user file`)
- we have the big picture : the :term:`configuration`, which is (the structure files + the user files)
- we kwow how to set a variable's user value (in a :term:`user data file`)
- we have the big picture : the :term:`configuration`, which is (the structure files + the user data files)
- we can add :term:`parameter`\ s to variables to refine their behavior
**Progress**

1
docs/tutorial/tutorial.rst
View file

@ -1,7 +1,6 @@
The Firefox proxy: the manual configuration
=============================================
.. objectives:: Objectives
We will learn how to: FIXME

2
docs/variable.rst
View file

@ -8,7 +8,7 @@ Synopsis
variable
A variable is an abstract black box (container) paired with an associated symbolic name, wmost often an option configuration, hich contains some defined or undefined data setting referred to as a :term:`value`.
A variable is an abstract black box (container) paired with an associated symbolic name, most often an option configuration, hich contains some defined or undefined data setting referred to as a :term:`value`.
value