preliminary : fist page ok

docs/tutorial/preliminary.rst

@@ -151,7 +151,7 @@ You have two way to define a variable's description:
         description: Configure Proxy Access to the Internet
 
 
-- or the compact way, using the "`#`" YAML notation:
+- or a short-hand way, setting the description using the "`#`" YAML comment notation:
 
   .. code-block:: yaml
 
@@ -188,6 +188,44 @@ Let's add a default value to this `proxy_mode` variable.
 
 :tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_003/firefox/00-proxy.yml>`
 
+.. glossary::
+
+    short-hand notation
+    
+        A short-hand notation in rougail is the ability to define a variable in 
+        a short-hand way, there are several example: 
+        
+        - a default value: 
+        
+        .. code-block:: yaml
+        
+            my_var: true 
+            
+        instead of:
+        
+        .. code-block:: yaml
+        
+            my_var:
+              default: true
+
+        - a quick description: 
+
+        .. code-block:: yaml
+                
+            proxy_mode:  # Configure Proxy Access to the Internet
+        
+        instead of: 
+
+        
+        .. code-block:: yaml
+        
+            proxy_mode:
+              description: Configure Proxy Access to the Internet
+
+        There are some other short-hand ways with rougail that you may encounter 
+        as you read the rougail's documentation and tutorial.
+
+
 .. admonition:: how to set a value -- the assignment
 
     A default value has been set, great. This raises a question about what a normal value is.
@@ -207,9 +245,9 @@ The one who writes the structure file plays the *role* of the *integrator*.
         He has the responsibility of the integration process, that is,
         he defines the variables and the relationship between them, the variables that are allowed
         (or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency**
-        of the organisation of the variables beteen them.
+        of the organisation of the variables between them.
 
-Now we will talk about the one that defines the values. It is called the operator.
+Now we will talk about the one that defines the values. His role is called the operator role.
 
 .. glossary::
 
@@ -230,7 +268,7 @@ he is responsible of other files called the :term:`user data files <user data fi
     user datas
 
         User datas, as opposed to structured datas, are datas that only concern the assignment of values
-        and not the consistency of the variables.
+        and not the consistency of the variables between them.
 
         The variable's values are also called **user values**. 
         
@@ -241,7 +279,7 @@ he is responsible of other files called the :term:`user data files <user data fi
 
 .. exercise:: Folder structure update
 
-    Now we add a :file:`config/config.yml` file in our project::
+    Now we add a user data file named :file:`config/config.yml` in our project::
 
         rougail-tutorials
         ├── firefox