explicit link

docs/gettingstarted.rst

@@ -15,7 +15,7 @@ What is a consistency handling system ?
 
    Tiramisu
 
-        |Tiramisu| is a consistency handling system that was initially designed
+        |Tiramisu| is a consistency handling system that has initially been designed
         in the configuration management scope. To put it more simply,
         this library is generally used to handle configuration options.
 
@@ -44,16 +44,16 @@ The dictionaries
 
 .. image:: images/schema.png
 
-The main advantage is that declaring variables and writing consistency is a simple
+The main advantage is that declaring variables and writing consistency is as simple
-as writing YAML. It is not necessary to write :term:`Tiramisu` code.
+as writing YAML. With Rougail it is not necessary to write :term:`Tiramisu` code any more.
 It simplifies a lot of things.
 
-And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative mode.
+And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative mode (that is, in a YAML file).
 
 Once the dictionaries are loaded by Rougail, we find all the power of the :term:`Tiramisu` configuration management tool.
 
-The dictionaries YAML format
+The YAML dictionaries format
----------------------------------
+-----------------------------
 
 Before getting started with Rougail we need to learn the specifics of the YAML dictionaries file format (as well as some templating concepts).
 
@@ -78,14 +78,13 @@ The variables
 variable
 
     Here is a second definition of a :term:`variable`: it is a declaration unit that represents a business domain metaphor,
-
+    the most common example is that a variable that represents a configuration option
-    the most common example is that a variable represents a configuration option
     in a application, but a variable represents something more that a configuration option.
     It provides a business domain specific representation unit.
 
-.. note:: dictionaries can just define a list of variables, but we will see that
+.. note:: Dictionaries can just define a list of variables, but we will see that
           we can specify a lot more. We can define variables **and** their relations,
-          and the consistency between them.
+          **and** the consistency between them.
 
 In the next step, we will explain through a tutorial how to construct a list of variables.
 
@@ -176,7 +175,7 @@ Let's continuing on our "Hello world" theme and add a :term:`family` container.
         description: Somebody to say hello
         default: rougail
 
-Here, we have a family named `world`. 
+Here, we have a family named `world`.
 This family contains a variable named `name`
 
 Again, let's validate this YAML file against Rougail's API:
@@ -188,5 +187,5 @@ Again, let's validate this YAML file against Rougail's API:
 We then have the output:
 
 .. code-block:: python
-        
+
     {'rougail.world.name': 'rougail'}

docs/library.rst

@@ -3,7 +3,8 @@
 
 Rougail is a configuration management library that allows you to load variables in a simple and convenient way.
 
-In the following examples, we will use a specific configuration of Rougail. You will find all the options to :doc:`customize the directories structure used <configuration>`.
+In the following examples, we will use a specific configuration of Rougail.
+You will find all the configuraiton options in :doc:`configuration`.
 
 To load the configuration you must import the `RougailConfig` class and set the `dictionaries_dir` values:
 
@@ -31,16 +32,16 @@ Here is a first :file:`dict/00-base.yml` dictionary:
 
 Then, let's create the :term:`Tiramisu` objects via the following script:
 
-.. code-block:: python 
+.. code-block:: python
     :caption: the `script.py` file content
-   
+
     from rougail import Rougail, RougailConfig
 
     RougailConfig['dictionaries_dir'] = ['dict']
     rougail = Rougail()
     config = rougail.get_config()
     print(config.value.get())
- 
+
 Let's execute `script.py`:
 
 .. code-block:: bash
@@ -76,9 +77,9 @@ Then let's create an extra :term:`dictionary` :file:`extras/00-base.yml`:
 
 Then, let's create the :term:`Tiramisu` objects via the following :file:`script.py` script:
 
-.. code-block:: python 
+.. code-block:: python
-    :caption: the :file:`script.py` file content 
+    :caption: the :file:`script.py` file content
-    
+
     from rougail import Rougail, RougailConfig
 
     RougailConfig['dictionaries_dir'] = ['dict']
@@ -105,21 +106,21 @@ We create the complementary :term:`dictionary` named :file:`dict/01-function.yml
     version: '1.0'
     my_variable_jinja:
       type: "string"
-      default:    
+      default:
         type: jinja
         jinja: "{{ return_no() }}"
 
 Then let's define the :func:`return_no` function in :file:`functions.py`:
 
-.. code-block:: python 
+.. code-block:: python
    :caption: the :file:`functions.py` content
-   
+
    def return_no():
        return 'no'
 
 Then, let's create the :term:`Tiramisu` objects via the following script:
 
-.. code-block:: python 
+.. code-block:: python
     :caption: the `script.py` file content
 
     from rougail import Rougail, RougailConfig

docs/tutorial.rst

@@ -271,9 +271,12 @@ Let's look at what happens if we try to access the `rougail.proxy.manual` variab
 We have an error (with the message defined in the Jinja template):
 
 
-.. code-block:: python
+.. code-block:: shell
+
+    tiramisu.error.PropertiesOptionError: cannot access to
+    optiondescription "Manual proxy configuration" because
+    has property "disabled" (the mode proxy is not manual)
 
-    tiramisu.error.PropertiesOptionError: cannot access to optiondescription "Manual proxy configuration" because has property "disabled" (the mode proxy is not manual)
 
 Let's configure the proxy in manual mode
 
@@ -291,7 +294,7 @@ We can see that the returned variables does have the desired values:
      'rougail.proxy.manual.http_proxy.port': '8080',
      'rougail.proxy.manual.use_for_https': True}
 
-Let's set the `read_only` mode:
+Let's set the `read_only` mode and have a look at the configuration again:
 
 .. code-block:: python
 
@@ -307,7 +310,7 @@ Let's set the `read_only` mode:
 In the `read_only` mode, we can see that the HTTPS configuration appears.
 
 .. note:: We can see that `rougail.proxy.manual.http_proxy` values have been copied
-          in `rougail.proxy.manual.ssl_proxy` too...
+          in `rougail.proxy.manual.ssl_proxy` too.
 
 Changing values programmatically
 --------------------------------------