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
-as writing YAML. It is not necessary to write :term:`Tiramisu` code.
+The main advantage is that declaring variables and writing consistency is as simple
+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 represents a configuration option
+    the most common example is that a variable that 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.
 

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:
 

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
 --------------------------------------