jinja page ok

docs/tutorial/jinja.rst

@@ -32,6 +32,44 @@ Playing with Jinja
        git switch --detach v1.1_070
 
 
+.. type-along:: preliminary thoughts about calculation
+
+Let's reason on the previous HTTPS proxy configuration's manual mode settings:
+
+.. code-block:: yaml
+
+      use_for_https:
+        default: true
+
+      https_proxy:
+        type: family
+        description: HTTPS Proxy
+        hidden:
+          variable: _.use_for_https
+
+We see here that the `https_proxy` family is hidden 
+depending on the value of another variable. This is what we saw previously, 
+how to hide a variable.
+
+We will code the same behavior in a somehow different way: 
+
+.. code-block:: yaml
+
+      https_proxy':
+        description: HTTPS Proxy
+        hidden:
+          jinja: |-
+            {% if _.use_for_https %}
+              HTTPS is same has HTTP
+            {% endif %}
+
+This code has the same result and yes, it's done in a more complicated way.
+We have replaced this simple `hidden` property variable parameter by 
+a Jinja parameter. The hidden process is done by a calculation. 
+
+The fact is that it has same result, but it opens more possibilities,
+this is what we are going to work on in this section.
+
 .. glossary::
 
    calculation
@@ -68,7 +106,7 @@ Here is our structure file:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_070/firefox/20-manual.yml
    :language: yaml 
-   :caption: The :file:`firefox/20-manual.yml` structure file with some `jinja` code in the `hidden` property
+   :caption: The :file:`firefox/20-manual.yml` structure file with some Jinja code in the `hidden` property
 
 ..
     %YAML 1.2
@@ -224,18 +262,38 @@ And in addition notice that we also have a warning:
 This warning is an alert. It tells us that the `https_proxy.address` variable is unreachable
 (because it is hidden) and that this variable's setting **is not used** in the current :term:`configuration`.
 
-.. type-along:: Launching the Rougail CLI in the :term:`read write mode`
+The `--cli.root manual.https_proxy` Rougail CLI parameter enables us to focus on the problem,
+The root here is the `manual.https_proxy` family.
 
-What is interesting here is to launch the Rougail CLI in the :term:`read write mode`:
+.. note:: Running the Rougail CLI command  with a root parameter means that 
+          only data concerning the root family will appear in the command output.
+
+let's launch the Rougail CLI with this parameter:
+
+.. raw:: html 
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_070/config/02/cmd_root.txt
+   :class: terminal
+
+.. 
+    rougail -m firefox/ -u yaml -yf config/02/config.yml --cli.root manual.https_proxy
+
+It gives us this partial, but much more readable output:
+
+.. raw:: html
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_070/config/02/output_root.html
+   :class: output
+
+.. type-along:: Launching the Rougail CLI in the :term:`read write mode` 
+
+Let's launch the Rougail CLI in :term:`read write mode` and with the `--cli.root manual.https_proxy` root parameter.
 
-FIXME
 .. code-block:: bash
    :class: terminal 
 
     rougail -m firefox/ --cli.root manual.https_proxy -u yaml \
-            -yf config/01/config.yml --cli.read_write
+            -yf config/02/config.yml --cli.read_write
 
-Then we have an error:
+This time we don't have only a warning as in the `RO` mode. In the `RW` mode, we have an error:
 
 .. code-block:: bash
 
@@ -246,44 +304,6 @@ Then we have an error:
 .. note:: Note that we can see the "HTTPS is same has HTTP" string (the one that was present in the Jinja code) 
           as an explanation inside the error message.
 
-.. type-along:: Without calculation
-
-Let's reason on the previous HTTPS proxy configuration's manual mode settings:
-
-.. code-block:: yaml
-
-      use_for_https:
-        default: true
-
-      https_proxy:
-        type: family
-        description: HTTPS Proxy
-        hidden:
-          variable: _.use_for_https
-
-We see here that the `https_proxy` family is hidden 
-depending on the value of another variable. This is what we saw before, 
-how to hide a variable.
-
-Now we can code the same behavior in a somehow different way: 
-
-.. code-block:: yaml
-
-      https_proxy':
-        description: HTTPS Proxy
-        hidden:
-          jinja: |-
-            {% if _.use_for_https %}
-              HTTPS is same has HTTP
-            {% endif %}
-
-This code has the same result and yes, it's done in a more complicated way.
-We have replaced this simple `hidden` property variable parameter by 
-a Jinja parameter. The hidden process is done by a calculation. 
-
-The fact is that it has same result, but it opens more possibilities,
-we will see them later.
-
 Jinja with a description
 -----------------------------
 
@@ -293,14 +313,14 @@ Jinja with a description
      
           git switch --detach v1.1_071
 
-It is preferable to include a description related to the Jinja calcuation. 
+It is preferable to include a description related to the Jinja calculation. 
 That allows the calculation performed by the Jinja code to be understood rapidely 
 without having to read the code itself. 
 This is useful for the :term:`integrators <integrator>` who review these :term:`structure files <structure file>`.
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_071/firefox/20-manual.yml
    :language: yaml 
-   :caption: The :file:`firefox/20-manual.yml` structure file with a description added to the `Jinja` code
+   :caption: The :file:`firefox/20-manual.yml` structure file with a description added to the Jinja code
 
 ..
     %YAML 1.2
@@ -492,8 +512,8 @@ Jinja could returns a boolean
      
           git switch --detach v1.1_073
 
-So far, we have used a Jinja expression that could have a `True` value, 
+So far, we have used a Jinja expression that could have a `true` value, 
-otherwise it returned nothing (i.e., None, that is a `False` value):
+otherwise it returned nothing (i.e., None, that is a `false` value):
 
 .. code-block:: jinja
 
@@ -545,7 +565,7 @@ You can directly use any value in a conditional:
     else:
         print("Falsy")
 
-.. type-along:: Jinja calcuation without truthiness
+.. type-along:: Jinja calcluation without truthiness
 
 This is truthiness capability is entirely possible with Rougail 
 but, in programming language theory, 
@@ -625,7 +645,7 @@ we add a `return_type` parameter in the `hiden` property:
 
     If no text is returned by the Jinja calculation, what about the error message (in case of an error)?
 
-    In case of an error, it is the jinja's description that will appear. 
+    In case of an error, it is the Jinja's description that will appear. 
     
     In our example: `in HTTPS case if "_.use_for_https" is set to "true"`
 
@@ -637,15 +657,15 @@ we add a `return_type` parameter in the `hiden` property:
    **progress**
       
    - calculation with a Jinja type calculation: we can hide a family
-   - we know how to describe a calcuation
+   - we know how to describe a calculation
-   - we know how to output some documentation (in markdown or in html) of the :term:`configuration`
+   - we know how to output some documentation (markdown HTML) of the :term:`configuration`
    - we can calculate with a dynamic family identifer
-   - we can set an explicit boolean jinja expression in a jinja calcuation
+   - we can set an explicit boolean Jinja expression in a Jinja calculation
 
    **keywords**
    
-   - Jinja type calcuation for a hidden property
+   - Jinja type calculation for a hidden property
-   - Jinja calcuation's description
+   - Jinja calculation's description
    - identifier type parameter
    
    Here we have come to the possibility of making any kind of calculations based on the state of the :term:`configuration`.