modifs

docs/gettingstarted.rst

@@ -65,6 +65,18 @@ The structure files
        Rougail reads all the structure files and loads them into a single object
        that represents the whole :term:`context`.
 
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
+   :language: yaml
+   :caption: An empty Rougail structure file.
+   :name: RougailStructureFirstVariableDescription
+
+..
+    %YAML 1.2
+    ---
+    version: 1.1
+    ...
+
 .. figure:: images/schema.png
    :alt: The Rougail process
    :align: center
@@ -96,30 +108,51 @@ The variables
 -----------------
 
 Here is a :term:`structure file` example with only a variable **variable** named `proxy_mode`
-A variable can be defined with no default value at all.
+A variable can be defined without other informations.
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
+   :language: yaml
+   :caption: A Rougail structure file with a variable named `proxy_mode`, with a description.
+   :name: RougailStructureFirstVariable
+
+..
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    proxy_mode:
+    ...
+
+But it's better to describe this variable:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml
    :language: yaml
-   :caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a description.
+   :caption: A Rougail structure file with a variable named `proxy_mode`, with a description.
-   :name: RougailDictionaryFirstVariableDescription
+   :name: RougailStructureFirstVariableDescription
 
 ..
+    %YAML 1.2
     ---
-    proxy_mode:
+    version: 1.1
-      description: Configure Proxy Access to the Internet
+
+    proxy_mode:  # Configure Proxy Access to the Internet
+    ...
+
 
 The same with a default value:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/00-proxy.yml
    :language: yaml
-   :caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a default value.
+   :caption: A Rougail structure file with a variable named `proxy_mode`, with a default value.
-   :name: RougailDictionaryFirstVariableDefault
+   :name: RougailStructureFirstVariableDefault
 
 ..
+    %YAML 1.2
     ---
-    proxy_mode:
+    version: 1.1
-      description: Configure Proxy Access to the Internet
+    
-      default: No proxy
+    proxy_mode: No proxy  # Configure Proxy Access to the Internet
+    ...
 
 variable
 

docs/index.rst

@@ -30,7 +30,7 @@ Rougail
 
 .. image:: images/logo.png
 
-- is a `delicious cooked dish <https://fr.wikipedia.org/wiki/Rougail>`_ from the Mauritius  and Reunion Islands,
+- is a `delicious cooked dish <https://fr.wikipedia.org/wiki/Rougail>`_ from the Mauritius and Reunion Islands,
 
 - it is also a `Python <https://www.python.org/>`_ library  which enables us to conveniently load application :term:`variable`\ s in a simple `YAML <https://yaml.org/>`_ format in such a way that the end user consumer can handle them consistently (that is, against an user-defined consistency).
 

docs/tutorial/index.rst

@@ -49,4 +49,3 @@ At first glance we can see that we have a selection of five configuration option
    boolean
    dynfam
    calculation
-

docs/tutorial/preliminary.rst

@@ -22,7 +22,7 @@ Making a structure file
 
         workplace
         ├── firefox
-        │   └── struct.yml
+        │   └── struct.yml
 
 - Let's make a :file:`workplace` directory, with a :file:`firefox` subfolder.
 - First, we wil make a :term:`structure file <structure file>`, so let's create a :file:`struct.yml` file
@@ -42,13 +42,15 @@ This is an empty Rougail structure description file.
     version: 1.1
 
 
-Defining a variable and its default value
+Let's create our first variable
 ----------------------------------------------
 
 .. type-along:: a first variable
 
     Let's put a variable in the Rougail :term:`structure description file <structure file>`
 
+A variable is defined at a minimum by its name.
+
 This is a first Rougail variable in a Rougail dictionnary:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
@@ -65,7 +67,7 @@ This is a first Rougail variable in a Rougail dictionnary:
 .. code-block:: text
    :class: terminal
    
-    rougail -v 1.1 -m firefox/
+    rougail -m firefox/
 
 we will actually have an error: 
 
@@ -78,6 +80,8 @@ we will actually have an error:
     ┣━━ The following variables are mandatory but have no value:
     ┗━━   - proxy_mode
 
+.. FIXME on parle ici de l'option --cli.read_write ??
+
 Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet.
 
 We can therefore deduce this result:
@@ -104,8 +108,7 @@ Let's add a variable's description, which is not mandatory but which is a good p
 
 .. 
     ---
-    proxy_mode:
+    proxy_mode:  # Configure Proxy Access to the Internet
-      description: Configure Proxy Access to the Internet
 
 .. type-along:: how to set a value -- the default value
 
@@ -120,16 +123,14 @@ We need to set a value to this `proxy_mode` variable. A first way to do it is *t
 
 So let's define a variable with a description -- **and a default value**
 
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/a1969abccd5e10872d4eb901a26fa16007c9fb1d/firefox/00-proxy.yml
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/00-proxy.yml
     :language: yaml
     :caption: A rougail dictionnary file with a default value for the variable
     :name: RougailDictionaryVariableDefault
 
 ..
     ---
-    proxy_mode:
+    proxy_mode: No proxy  # Configure Proxy Access to the Internet
-      description: Configure Proxy Access to the Internet
-      default: No proxy
 
 
 .. type-along:: how to set a value -- the assignment
@@ -187,7 +188,7 @@ he is responsible of other files called the :term:`user data file`\ s.
 
         workplace
         ├── firefox
-        │   ├── struct.yml
+        │   ├── struct.yml
         └── config
             └── config.yml
 
@@ -196,7 +197,7 @@ he is responsible of other files called the :term:`user data file`\ s.
 So for example if the integrator has not set any default value in his structure file, 
 the operator can do it like this:
 
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/config/02/config.yaml
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/config/02/config.yaml
    :language: yaml
    :caption: A Rougail user datas file :file:`config/config.yml`, with a default value set.
    :name: RougailConfigDefaultValue
@@ -264,7 +265,6 @@ In our firefox use case, the real type of the `proxy_mode` variable will be now
     ---
     proxy_mode:
       description: Configure Proxy Access to the Internet
-      type: choice
       choices:
         - No proxy
         - Auto-detect proxy settings for this network
@@ -349,7 +349,6 @@ We have the list of the possible (authorized) values:
     ---
     proxy_mode:
       description: Configure Proxy Access to the Internet
-      type: choice
       choices:
         - No proxy
         - Auto-detect proxy settings for this network

docs/tutorial/proxymode.rst

@@ -1,5 +1,5 @@
-Let's dive in
+Group variables inside families
-====================
+=================================
 
 .. objectives:: Objectives
 
@@ -28,7 +28,6 @@ In the structure description file, we have:
     ---
     proxy_mode:
       description: Configure Proxy Access to the Internet
-      type: choice
       choices:
         - No proxy
         - Auto-detect proxy settings for this network
@@ -292,7 +291,7 @@ Let's create a `port` variable in the `http_proxy` family:
 
 Here is the new :file:`firefox/10-manual.yml` structure file:
 
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_026/firefox/10-manual.yml
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/firefox/10-manual.yml
    :language: yaml
    :caption: A rougail structure description file with a hierarchy.
    :name: RogailPortVariable