type definition

docs/tutorial/customtype.rst

@@ -3,8 +3,8 @@ Custom type
 
 .. objectives:: Objectives
 
-    In this sections we are going to learn how to create custom types. 
+    In this sections we are going to learn how to create custom types with Rougail. 
-    In short, a custom type is nothing more than a kind of family template.
+    In short, a custom type is nothing more than a kind of a template for a family.
     
 .. prerequisites:: Prerequisites
 
@@ -32,17 +32,22 @@ This feature is essential for having a truly adaptable tool.
 
 .. note:: It is actually possible to add types, 
           but that involves adding predefined types to the :term:`tiramisu` underlying consistency library itself,
-          and that’s a different matter altogether. There is a simpler way to do this.
+          and that’s a different matter altogether. There is a simpler way to achieve this: the Rougail type definition.
           
-More simply, it's possible in Rougail to create custom types, much like defining families.
+It is possible in Rougail to create custom types in a very simple way, it is much like defining families.
 
-Our folder structure will be expanded a bit:
+Now our folder structure will be expanded a bit:
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/tree.html
    
 Notice that we have now a new :file:`types` folder in our tree structure.
-This is where we place our new `proxy` type definition.
+This is where we will place our new `proxy` type definition.
+
+.. note:: Choosing the :file:`types/proxy/00_type.yml` file name is not mandatory. 
+          You can name this folder whatever you want.
+          It is simply a good practice to separate structure files from type definition files. 
+          We will see later on how to indicate to Rougail that a file contains a type declaration.
 
 In accordance with our :ref:`naming policy <namingconvention>`, we have created a file named :file:`00_type.yml`
 inside the `proxy` folder. 
@@ -74,14 +79,14 @@ Let's examine this more closely this :file:`types/proxy/00_type.yml` type defini
           variable: __.http_proxy.port
     ...
     
-The new type named `proxy` is declared.  
+The new type named `proxy` is declared the same way we declare a family.  
 It's more or less like a family declaration except it will be used as a type definition.
 
 .. questions:: How do we use a new type?
 
-    Very simply. In the usual way: we will use the `type` parameter.
+    Very simply. In the usual way: we will add a `type` parameter in our family declaration.
 
-Here, we will declare that a family is of type `proxy` as follows:
+Let's declare that a family is of type `proxy` as follows:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/firefox/10-manual.yml
    :language: yaml 
@@ -109,19 +114,22 @@ Here, we will declare that a family is of type `proxy` as follows:
           default: 8080
     ...
 
-We can see that the type declared for the `http_proxy` family is `type: proxy`. Very simple.
+We can see that the type declared for the `http_proxy` family is `type: proxy`.
-For example in the `address` it is not necessary to specify the `domainname` type nor the `allow_ip` parameter:
+It's perfectly natural in the rougail style.
+
+Now in the `address` family it is not necessary to specify the `domainname` type nor the `allow_ip` parameter:
 
 .. code-block:: yaml
    :caption: We can omit this now due to the type definition
    
-      description: HTTP address
+   description: HTTP address
-	      type: domainname
+   type: domainname
-	      params:
+   params:
-	        allow_ip: true
+     allow_ip: true
 
-So we have declared our new type. How do we make it available? Well, the Rougail CLI has a `--types` type declaration command line option.
+But if we use our new type we need to declare it to Rougail in order to make it available.
-Let's launch the rougail CLI:
+The Rougail CLI has a `--types` type declaration command line option for this purpose.
+Let's launch the rougail CLI with this command line parameter:
 
 .. raw:: html 
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/cmd_ro.txt
@@ -129,15 +137,62 @@ Let's launch the rougail CLI:
 
 The CLI output is entirely standard and does not specifically mention the call to a new type. 
 The result is the same as usual, as if the type declaration were omitted, which is what we want.
-We want the same behavior.
+We want the same behavior as usual.
 
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/output_ro.html
    :class: output
 
+The type definition adds nothing to the structural logic. It's just a very convenient way to save time when writing structure files.
+
+HTTPS and SOCKS Proxy
+-----------------------
+
+.. type-along:: For those who follow the tutorial with the help of the git repository
+
+    Now you need to checkout the `v1.1_081` version::
+     
+          git switch --detach v1.1_081
+
+With this use of a type, it is possible to define our HTTPS and SOCKS Proxy in a much more conscious way:
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_081/firefox/20-manual.yml
+   :language: yaml 
+   :caption: The :file:`firefox/20-manual.yml` structure file with less code due to the `proxy` type definition
+
+..
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    manual:
+
+      use_for_https: true  # Also use this proxy for HTTPS
+
+      https_proxy:
+        description: HTTPS Proxy
+        type: proxy
+        hidden:
+          variable: _.use_for_https
+
+      socks_proxy:
+        description: SOCKS Proxy
+        type: proxy
+
+        version:
+          description: SOCKS host version used by proxy
+          choices:
+            - v4
+            - v5
+          default: v5
+    ...
+
 
 .. keypoints:: Key points
 
    - type declaration
    - type usage 
+   - more conscious family definition
+   - the very practical aspects of type declaration
    
+   We have seen how the definition of type, used effectively, allows for a new expressiveness.

docs/tutorial/jinja.rst

@@ -588,7 +588,7 @@ Here is a Jinja code that return a boolean value:
     {{ my_identifier == 'HTTPS' and _.use_for_https }}
 
 And in order to declare explicitly the use of this explicit non-truthiness pratice, 
-we add a `return_type` parameter in the `hiden` property:
+we add a `return_type` parameter in the `hidden` property:
 
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_073/firefox/20-manual.yml
@@ -640,7 +640,6 @@ we add a `return_type` parameter in the `hiden` property:
             when: HTTPS
     ...
 
-
 .. questions:: What about the error message?
 
     If no text is returned by the Jinja calculation, what about the error message (in case of an error)?