From c361629b63a13163b4e44782dc330c5e72a001ac Mon Sep 17 00:00:00 2001
From: gwen <gwenaelremond@free.fr>
Date: Mon, 21 Oct 2024 15:03:34 +0200
Subject: [PATCH] update slides and def

---
 docs/tutorial/index.rst       |  5 ++---
 docs/tutorial/preliminary.rst | 24 +++++++++++++++++-------
 docs/variable.rst             | 11 +++++++++--
 3 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst
index 90461bc37..78155e02e 100644
--- a/docs/tutorial/index.rst
+++ b/docs/tutorial/index.rst
@@ -1,7 +1,7 @@
 Tutorial with a real world sample
 =====================================
 
-Here's the demo. We're gonna start with a use case that comes from the real world.
+Here's a quite well supplied tutorial, we're gonna start with a use case that comes from the real world.
 
 .. demo:: Demo: configuring (the setting of) your favorite web browser
 
@@ -15,14 +15,13 @@ More precisely, this tutorial aims at reproducing this Mozilla Firefox settings
           We are just going to handle some of the firefox configuration settings
           with Rougail.
 
-
 Presentation of the firefox configuration variables
 -----------------------------------------------------------
 
 Let's dive into the configuration validation use case,
 that is the values entered by the user that have to be validated.
 
-At first glance we have a choice between five variables:
+At first glance we have a selection of five options configuration values that we need to fill in:
 
 .. image:: images/firefox_01.png
 
diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst
index b5a80420e..1c3681aa6 100644
--- a/docs/tutorial/preliminary.rst
+++ b/docs/tutorial/preliminary.rst
@@ -1,15 +1,17 @@
 Preliminaries
 ================
 
-.. prerequisites:: Prerequisistes
+.. objectives:: Objectives
 
-   You need to know how to:
+   We will learn how to:
 
-   - create a Rougail :term:`dictionary`
+   - create a Rougail :term:`dictionary` (the structure description file)
    - define a Rougail format version
-   - define a Rougail :term:`variable`
+   - define a Rougail :term:`variable` and set its :term:`value`
 
-.. type-along:: Workshop
+.. type-along:: Reminders
+
+   We alread learned in other workshops how to:
 
    - define a Rougail :term:`dictionary`
 
@@ -53,10 +55,10 @@ The operator role
 
     operator
 
-        An operator ih the Rougail logic is the person who gives values to the pre-defined variables,
+        An operator ih the Rougail logic is the person who gives :term:`value`\ s to the pre-defined variables,
         his responsabilities are to set variable values correctly.
 
-        The :term:`user values`, that is the values that have been set by the operator, are validated
+        The user :term:`value`\ s, that is the values that have been set by the operator, are validated
         by the dictionary structure.
 
         .. image:: images/operator.png
@@ -76,3 +78,11 @@ But instead of coding in the end user developer way, the opterator will prefer u
 The Rougail CLI can output a rather complete view of the dataset:
 
 .. image:: images/UserDataOutput.png
+
+.. keypoints:: Progress keypoints
+
+   - :term:`dictionary`: structure description file
+   - :term:`variable`: an option's name wich has a value
+   - a variable's description
+   - a variable's default value
+   - the integrator and operator role
diff --git a/docs/variable.rst b/docs/variable.rst
index 1eab898dc..51c18e3e5 100644
--- a/docs/variable.rst
+++ b/docs/variable.rst
@@ -9,9 +9,16 @@ Synopsis
    variable
    variables
 
-        A variable is an abstract black box (container) paired with an associated symbolic name, which contains some defined or undefined quantity of data referred to as a `value`.
+        A variable is an abstract black box (container) paired with an associated symbolic name, wmost often an option configuration, hich contains some defined or undefined data setting referred to as a :term:`value`.
 
-.. discussion:: This definition, makes a heavy use of data typing.
+   value
+
+        A variable can have a default value, that is a option configuration setting in the :term:`dictionary` structure,
+        or no value at all, then the value needs to be define by the :term:`operator`.
+
+.. discussion:: Discussion
+
+                This definition makes a heavy use of data typing.
                 Indeed, depending on the type system definition of the constistency handling system used, variables may only be able to store a specified data type.
                 OK, variables are the containers for storing the values. It has something to do with typing.
                 But this is not just about typing.