doc(path): define relative path

docs/relative_path.rst

@@ -1,50 +0,0 @@
-:orphan:
-
-on a un path relatif, `_` ou `__` 
-
-
-https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_091~1..v1.1_091
-
-
-::
-
-    manual:
-
-      use_for_https: true  # Also use this proxy for HTTPS
-
-      "{{ identifier }}_proxy":
-        description: "{{ identifier }} Proxy"
-        dynamic:
-          - HTTPS
-          - SOCKS
-        hidden:
-          jinja: |
-            {% if my_identifier == 'HTTPS' and _.use_for_https %}
-            HTTPS is same has HTTP
-            {% endif %}
-          params:
-            my_identifier:
-              type: identifier
-          description: |
-            in HTTPS case if "manual.use_for_https" is set to True
-
-        address:
-          description: "{{ identifier }} address"
-          default:
-            variable: __.http_proxy.address
-
-        port:
-          description: "{{ identifier }} port"
-          default:
-            variable: __.http_proxy.port
-
-        version:
-          description: SOCKS host version used by proxy
-          choices:
-            - v4
-            - v5
-          default: v5
-          disabled:
-            type: identifier
-            when: 'HTTPS'
-

docs/structured_data/path.rst

@@ -0,0 +1,63 @@
+Full or relative path
+=====================
+
+To access a variable, it is necessary to know which family or subfamily it belongs to.
+
+Let's create some variables to illustrate the point.
+
+.. code-block:: yaml
+
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    my_family:  # A family
+
+      my_sub_family:  # A family inside an other family
+
+        my_first_variable:  # My first variable
+
+        my_second_variable:  # My second variable
+
+      my_third_variable:  # My third variable
+
+    my_forth_variable:  # My forth variable
+    ...
+
+So we have three variables.
+
+Here full path are:
+
+- my_family.my_sub_family.my_first_variable
+- my_family.my_sub_family.my_second_variable
+- my_family.my_third_variable
+- my_forth_variable
+
+But in calculation it's often better to use :term:`relative path`.
+
+.. glossary::
+
+   relative path
+
+        In a calculation definition, a relative path defines the location of a variable relative to the family of the variable where the parameter is calculated.
+        Instead of starting from the root, it uses references like _. (current family), __. (parent family), ___. (sub parent family) and so on.
+
+        Relative paths are shorter and portable across custom type.
+
+Now define :term:`relative path` from the `my_first_variable` variable:
+
+- _.my_second_variable
+- __.my_third_variable
+- ___.my_third_variable
+
+From the `my_third_variable`:
+
+- _.my_sub_family.my_first_variable
+- _.my_sub_family.my_second_variable
+- __.my_third_variable
+
+Finally from `my_forth_variable`:
+
+- _.my_family.my_sub_family.my_first_variable
+- _.my_family.my_sub_family.my_second_variable
+- _.my_family.my_third_variable

docs/tutorial/calculated.rst

@@ -160,7 +160,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 `manual.http_proxy.address`. 
 
-.. note:: The `__.` notation means the parent path of the current subfamily path.
+.. note:: The `__.` is a :term:`relative path` notation and means the parent path of the current subfamily path.
           
           In the python quasi algorithmic notation we could say that:  
           

docs/tutorial/nullable.rst

@@ -183,12 +183,16 @@ For the `disabled` property to trigger, the condition `when: null` must appear,
 pointing to the `_.address` variable, that is the `socks_proxy.address` variable.
 
 
-.. note:: The `_.` notation means the current path (of the current family).
+.. note:: The `_.` is a :term:`relative path` notation and means the current path (of the current family).
 
-          As we are in the `socks_proxy` family, we can say::
+          In the python quasi algorithmic notation we could say that:  
+          
+          .. code-block:: python
 
               _.address == socks_proxy.address
 
+          This is true only because in our use case `socks_proxy` is located on the root path.
+
 .. keypoints:: Key points
 
    As one of the main objectives of Rougail is to determine if a variable has a value, 

docs/tutorial/properties.rst

@@ -265,7 +265,7 @@ will be used to dynamically enable or disable our `manual` family.
 We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value.
 The target variable is `_.proxy_mode`.
 
-.. note:: The `_.` notation means the current path of the family you're currently in.
+.. note:: The `_.` is a :term:`relative path` notation and means the current path of the family you're currently in.
 
           In the python quasi algorithmic notation we could say that: