docs(tutorial-190-sequence): homogeneous elements sequence

docs/format_content/family.rst

@@ -223,6 +223,8 @@ This will dynamically create two families:
 
    You can have a look at the tutorial with a real world sample :doc:`dynamically built family <../tutorial/dynamic>`
 
+.. _sequence_family:
+
 Sequence of homogeneous elements
 ---------------------------------------
 

docs/tutorial/sequence.rst

@@ -3,7 +3,8 @@ Homogeneous elements sequence
 
 .. objectives:: Objectives
 
-   We are going to discuss a new Rougail type, the sequence of homogeneous elements. 
+   We are going to discuss a new Rougail type, :term:`the sequence of homogeneous elements <sequence>`
+   which we will call, more concisely, a :term:`sequence`. It's a rather unusual :term:`family`.
 
 .. prerequisites:: Prerequisites
 
@@ -23,11 +24,127 @@ Homogeneous elements sequence
        git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
        git switch --detach 1.1_190
 
-A family with sequence of homogeneous elements type
+As a reminder, we are now talking about the Firefox add-on called 
---------------------------------------------------------
+`Foxy Proxy <https://addons.mozilla.org/en-US/firefox/addon/foxyproxy-standard/>`_ use case,
+here is the Foxy Proxy widget:
 
-FIXME
+.. image:: images/foxyproxy.png
+
+A family with sequence type
+------------------------------
+
+.. note:: To be precise, we should say: a :term:`family with a sequence of homogeneous elements type <sequence>`.
+
+Our request here is to have a list of homogeneous objects.
+Indeed, if we click on "Add proxy" in our Foxy Proxy widget, we will need to specify:
+
+- a proxy type
+- a color
+
+(and also enter some other values).
+And this applies to each proxy we will define.
+
+Here is the structure file associated with this use case:
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_190/foxyproxy/00-foxyproxy.yml
+   :language: yaml
+   :caption: The FoxyProxy structure file :file:`foxyproxy/00-foxyproxy.yml` with the `proxies` sequence variable
+
+..
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    proxies:
+      description: Proxy configuration
+      type: sequence
+
+      title:
+        description: Title or Description
+        mandatory: false
+
+      color:  # Color
+    ...
+
+Unsurprisingly, the way to assign the `sequence` type is done with the help of the `type` parameter.
+We see here that `proxies` is a family because it contains the variables `title` and `color`.
+
+The :term:`sequence` type ensures that in the `proxies` family, if a proxy type is specified, then an associated color will also be specified.
+Let's launch the Rougail CLI on this structured data:
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_190/config/02/config.yml
+   :language: yaml
+   :caption: A :file:`config/02/config.yml` user data file with the `proxies` sequence
+
+..
+    ---
+    foxyproxy:
+      proxies:
+        - title: My company
+          color: '#66cc66'
+
+We can see in the :term:`user data` YAML file that the `proxies` value is a list of mappings.
+
+Which we could write in JSON like this:
+
+        .. code-block:: json
+
+           [
+                {
+                  "title": "My company",
+                  "color": "#66cc66"
+                }
+           ]
+
+So we can clearly see in the JSON that if there's a `title` key, then there will also be a `color` key.
+
+This is guaranteed by our :term:`sequence` type.
+
+.. raw:: html
+   :class: terminal
+   :url: 
+
+..
+    rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/02/config.yml
+
+And the Rougail output is:
+
+.. raw:: html
+  :class: output 
+  :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_190/config/02/output_ro.html
+
+..
+    Variables:
+    ┣━━ 📂 firefox (Firefox)
+    ┃   ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): No proxy
+    ┃   ┗━━ 📂 dns_over_https (DNS over HTTPS)
+    ┃       ┗━━ 📓 enable_dns_over_https (Enable DNS over HTTPS): false
+    ┗━━ 📂 foxyproxy (FoxyProxy)
+        ┗━━ 📂 proxies (Proxy configuration)
+            ┗━━ 📂 title (Title or Description)
+                ┣━━ 📓 title (Title or Description): My company ◀ loaded from the 
+                ┃   YAML file "config/02/config.yml"
+                ┗━━ 📓 color (Color): #66cc66 ◀ loaded from the YAML file 
+                    "config/02/config.yml"
+                    
+FIXME: je ne comprends pas bien pourquoi on a title qui est une espèce de multi à elle seule dans le output 
+
+::
+
+            ┗━━ 📂 title (Title or Description)
+                ┣━━ 📓 title (Title or Description): My company ◀ loaded from the 
+                ┃   YAML file "config/02/config.yml"
+                ┗━━ 📓 color (Color): #66cc66 ◀ loaded from the YAML file 
+                    "config/02/config.yml"
                     
 
+.. seealso::
+
+   You can have a look at the Rougail format pages :ref:`Sequence of homogeneous elements <sequence_family>`
+
+
+.. keypoints:: let's review the key points
+
+   We saw a :term:`sequence` type family.