From 935b33d28e9236b5dbac08997bb6ac7c0b76266f Mon Sep 17 00:00:00 2001 From: gwen Date: Mon, 5 May 2025 21:39:32 +0200 Subject: [PATCH] modifs --- docs/tutorial/preliminary.rst | 28 ++++++++++++++------------- docs/tutorial/proxymode.rst | 36 +++++++++++++++++++---------------- docs/tutorial/tutorial.rst | 1 - docs/variable.rst | 2 +- 4 files changed, 36 insertions(+), 31 deletions(-) diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 49d73d7e4..1143c49dd 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -6,7 +6,7 @@ Preliminaries We will learn how to: - create a Rougail :term:`structure description file ` - - define a Rougail :term:`structure description file ` format version + - define a Rougail :term:`structure file format version ` - 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 `. + 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 `. 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. diff --git a/docs/tutorial/proxymode.rst b/docs/tutorial/proxymode.rst index fe6ed43c7..e584e7277 100644 --- a/docs/tutorial/proxymode.rst +++ b/docs/tutorial/proxymode.rst @@ -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** diff --git a/docs/tutorial/tutorial.rst b/docs/tutorial/tutorial.rst index 25b04709a..ee849d771 100644 --- a/docs/tutorial/tutorial.rst +++ b/docs/tutorial/tutorial.rst @@ -1,7 +1,6 @@ The Firefox proxy: the manual configuration ============================================= - .. objectives:: Objectives We will learn how to: FIXME diff --git a/docs/variable.rst b/docs/variable.rst index d02fdac8c..53d3bb0ca 100644 --- a/docs/variable.rst +++ b/docs/variable.rst @@ -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