From 096925eba761723b41d4e30724f3592e8a87d204 Mon Sep 17 00:00:00 2001 From: gwen Date: Mon, 26 Jan 2026 09:36:25 +0100 Subject: [PATCH] modifs dynfam --- docs/tutorial/calculated.rst | 11 ++++++----- docs/tutorial/dynfam.rst | 27 ++++++++++++++++----------- 2 files changed, 22 insertions(+), 16 deletions(-) diff --git a/docs/tutorial/calculated.rst b/docs/tutorial/calculated.rst index 2626cdd89..18af20383 100644 --- a/docs/tutorial/calculated.rst +++ b/docs/tutorial/calculated.rst @@ -36,7 +36,7 @@ the :file:`10-manual.yml` and the :file:`20-manual.yml` structure file: :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/tree.html We will continue to complete the :file:`20-manual.yml` structure file, -with variables entirely equivalent to those found in the `http_proxy` family the :file:`10-manual.yml` structure file. +with variables entirely equivalent to those found in the `http_proxy` family from the :file:`10-manual.yml` structure file. Until now, we only had the `use_for_https` :ref:`boolean variable in this structure file `. Now we are going to define an address and a port in the `https_proxy` family: @@ -81,14 +81,14 @@ A default value calculated from another variable A contextualized default value is a default value that changes according to the overall context of the configuration. A contextualized default value can come from, as we see here, a copy of the value of another variable. -The dynamic setting of a default can be expressed this way: the default value is a pointer to another variable's value. +The dynamic setting of a default value can be expressed this way: the default value is a pointer to another variable's value. Here, the defaut value of `manual.https_proxy.address` points to the value of `manual.http_proxy.address`. This is the same thing for the default value of the `manual.https_proxy.port` variable, which points to the `manual.http_proxy.port` value. .. note:: In the following we will see that the `manual.https_proxy.address` type is `domainname`. - Indeed, the the default value inherits the type of the value it points to. + Indeed, this `domainname` type comes from the type of the variable it points to. Reminder: here is the HTTP :file:`firefox/10-manual.yml` structure file: @@ -149,7 +149,7 @@ And here is the :file:`firefox/20-manual.yml` structure file where the calculate ... We can see here that the `address` variable's default value is conditionned by the `__.http_proxy.address` variable's value. -The target variable is `http_proxy.address`. +The target variable is `manual.http_proxy.address`. .. note:: The `__.` notation means the parent path of the current subfamily path. @@ -228,8 +228,9 @@ We have this result: The `https_proxy` variable's value is indeed modified, but the default value is still a calculated value (so the default value is indeed the value of the variable `http_proxy.address`, i.e., `"http.proxy.net"`), while the value defined by the user is `https.proxy.net`. +The Rougial CLI always displays the default value of a variable, even if a value has been assigned to it, meaning the default value is not used. Here we see that the variable's default value is not changed, but rather its actual value. - + .. keypoints:: Key points progress **summary** diff --git a/docs/tutorial/dynfam.rst b/docs/tutorial/dynfam.rst index 95196ad16..16bf5ff52 100644 --- a/docs/tutorial/dynfam.rst +++ b/docs/tutorial/dynfam.rst @@ -34,7 +34,7 @@ Let's turn back to the firefox's configuration page: .. image:: images/soksv5.png We see that we need to handle the SOCKS configuration in addition to the HTTPS configuration. -Moreover, we can see that these two groups of variables are similar in the structure: +Moreover, we can see that these two groups of variables (also known as family) are similar in the structure: they both have a host and a port. There are two proxies that are to be configured : @@ -96,13 +96,16 @@ Now with identifiers, we have the ability to declare our families this way: dynamic: - HTTPS - SOCKS - + ... + address: description: "{{ identifier }} address" - + ... + port: description: "{{ identifier }} port" - + ... + .. index:: identifier .. type-along:: What is exactly an identifier? @@ -169,17 +172,19 @@ This identifier is a parameter that enables us to create two families named `htt description: "SOCKS Proxy" .. attention:: Be careful when choosing your identifiers items: pay attention that the family - that will be dynamically created has not been declared before in some other + names that will be dynamically created have not been declared before in some other YAML structure file. - + + Here the family name is: `"{{ identifier }}_proxy"`. + If you define a dynamically built family with the `https` item that will build a `https_proxy` family and if this familiy already exists, then rougail will raise a family/variable override warning. - When choosing a name, - - - rougail will put it in lowercase - - only ASCII and underscore ("`_`") characters are allowed. + When choosing a dynamically built family name, rougail will replace spaces, accents, uppercases... + by valid character and put all in lowercase. Only ASCII and underscore ("`_`") characters are allowed. + + As you can see here, the identifier is `HTTPS`, but the name clearly contains `https` (in lowercase). Here is our dynamically built familiy in situation in the :file:`firefox/20-manual.yml` structure file. @@ -396,5 +401,5 @@ The Rougail CLI outputs this: - We now know how to declare a dynamically built family, with setting its identifier. - we have a new use case for the `disabled` property. - We know how to disable a dynamically built family based on its identifier. + We know how to disable a dynamically built variable based on a familiy identifier.