dynfam and identifier

docs/tutorial/dynfam.rst

@@ -1,3 +1,4 @@
+.. _dynfam:
 
 A dynamic family
 ================
@@ -13,25 +14,28 @@ A dynamic family
 
 .. image:: images/soksv5.png
 
-In fact we shall not only handle the HTTPS configuration but the SOCKS configuration too.
+We see that we need to handle the SOCKS configuration in addition to the HTTPs configuration.
-And we can see that these two group of variables are very similar: 
+Moreover, we can see that these two group of variables are very similar: 
-they both have two variables, that is a host and a port.
+they both have a host and a port.
 
 Creating a generic family
 ----------------------------
 
+
 There are two proxies that are to be configured : 
 
 - the HTTP proxy
 - the SOCKS proxy
 
 It's not the place here to describe what the HTTP and SOCKS protocols are. 
-The interesting point is that : 
+The interesting point here is that they are very similar in our firefox's configuration.
 
-- they are similar in terms of our firefox's configuration
+With Rougail, we can create some kind of a model of family. 
-- we can use a generic family declaration mode in this use case (we call this genericity "dynamic creation")
+we can use a generic family declaration mode in this use case. 
+We call this genericity family a "dynamic creation" because as we will see below, 
+these families exist at the very moment we define their identifiers.
 
-Instead of doing something like this: 
+what we could do with our current knowledge: 
 
 .. code-block:: yaml
 
@@ -47,11 +51,6 @@ Instead of doing something like this:
        description: HTTPS Port
        ...
 
-And this:
-
-
-.. code-block:: yaml
-
    sock_proxy:
      description: SOCKS Proxy
      ...
@@ -64,7 +63,7 @@ And this:
        description: SOCKS Port
        ...
 
-With Rougail we have the ability to say this:
+With Rougail we have the ability to declare our families this way:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_037/firefox/20-manual.yml
    :language: yaml
@@ -73,9 +72,46 @@ With Rougail we have the ability to say this:
 What is an identifier?
 -------------------------
 
-We define what we call an :term:`identifier`, which is a local variable, used only for creating 
+If you know a YAML declaration tool named Ansible, 
-multiple families at one time (that is, being more generic in our declaration style). 
+the variable used to iterate over multiple values in a task is called an **`item`**.
-This is this syntax that allows the declaration of multiple families at one time:
+
+It is used in the context of a loop. For example:
+
+.. code-block:: yaml
+
+   - name: Loop example with 'item'
+     ansible.builtin.debug:
+       msg: "The current value is {{ item }}"
+     loop:
+       - value1
+       - value2
+       - value3
+
+This code will output: 
+
+.. code-block:: text
+
+   The current value is value1
+   The current value is value2
+   The current value is value3
+
+In the Rougail context, we name this item an identifier because it is an item 
+that allow us to define dynamically family names.
+
+.. glossary::
+
+   identifier
+
+      In the :ref:`dynamic family creation field <dynfam>` we call an identifier
+      an item that defines a family name. An item is a variable on which an iteration 
+      on keywords will be carried out. 
+
+      An :term:`identifier` is a local variable, used only for creating multiple 
+      iterations, used for creating multiple families in only one declaration.
+
+      It allows us to declare very similar families in a more generic way.
+
+Here is the syntax we are using that allows the declaration of multiple families at one time:
 
 .. code-block:: yaml
 
@@ -85,17 +121,66 @@ This is this syntax that allows the declaration of multiple families at one time
       - HTTPS
       - SOCKS
 
-This identifier is a parameter that enables us to create two families named `https_proxy` and `socks_proxy`.
+This identifier is a parameter that enables us to create two families named `https_proxy` and `socks_proxy`:
 
-.. note:: The declaration syntax is a :term:`jinja` templating syntax, which is commonly used 
-          in the python coding field.
 
-So yes, we have gained in genericity but we have lost in readability, you would say.
+
+.. code-block:: yaml
+
+  https_proxy:
+    description: "HTTPS Proxy"
+
+  socks_proxy:
+    description: "SOCKS Proxy"
+
+.. note:: The declaration syntax used is the :term:`Jinja <jinja>` templating syntax, 
+          Jinja which is widely used in python.
+
+.. attention:: Be careful when choosing your identifiers items: the family 
+               that will be dynamically created shall not exist already.
+
+               If you define a dynamic family with the `https` item that will 
+               build a `https_proxy` family and if this familiy already exist,
+               then rougail will raise a warning.
+
+
+Besides, when we launch the rougail command line, we can have a look at the concrete variables here:
+
+.. code-block:: text
+
+    rougail -m structfile/proxy.yml -u yaml --yaml.filename userdata/proxy.yml
+    ╭─────────────────── Caption ────────────────────╮
+    │ Variable              Default value            │
+    │ Unmodifiable variable Modified value           │
+    │                       (Original default value) │
+    ╰────────────────────────────────────────────────╯
+    Variables:
+    ┗━━ 📂 Manual proxy configuration
+        ┣━━ 📂 HTTP Proxy
+        ┃   ┣━━ 📓 HTTP address: ... (loaded from the YAML file "userdata/proxy.yml")
+        ┃   ┗━━ 📓 HTTP Port: ... (8080 - loaded from the YAML file "userdata/proxy.yml")
+        ┣━━ 📓 Also use this proxy for HTTPS: true
+        ┣━━ 📂 HTTPS Proxy
+        ┃   ┣━━ 📓 HTTPS address: ...
+        ┃   ┗━━ 📓 HTTPS port: ...
+        ┗━━ 📂 SOCKS Proxy
+            ┣━━ 📓 SOCKS address: ...
+            ┗━━ 📓 SOCKS port: ...
+
+We can see that the dynamic family has created: 
+
+- an `HTTPS Proxy` family
+- a `SOCKS Proxy` family
+
+as we wanted.
+
+
+A conditional hidden familiy
+--------------------------------
+
+Yes we have gained in genericity but we have lost in readability, you would say.
 But we haven't just been generic. We now have the ability to create conditional hidden family
 (and not only conditionnal hidden variables like we did earlier).
 
-A conditional hidden family with jinja
-------------------------------------------
-