From fbc0744f611a1c3d2bf1b4d1cffa004fc69a61c4 Mon Sep 17 00:00:00 2001
From: gwen <gwenaelremond@free.fr>
Date: Mon, 21 Oct 2024 18:28:34 +0200
Subject: [PATCH] keypoints

---
 docs/conf.py                  |  1 +
 docs/tutorial/index.rst       |  9 +++--
 docs/tutorial/preliminary.rst | 64 +++++++++++++++++++++++++++++++----
 3 files changed, 64 insertions(+), 10 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 6863a4141..26553f0dd 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -54,6 +54,7 @@ xref_links.update(links)
 " :source:`v1.1_010/firefox/00-proxy.yml` "
 extlinks = {'source': ('https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/%s',
                        'source: %s'),
+            'tiramisu': ('https://tiramisu.readthedocs.io/en/latest/%s', 'tiramisu: %s'),
             }
 #---- options for HTML output ----
 default_role = "code"
diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst
index 0a0699634..11ebe4d9d 100644
--- a/docs/tutorial/index.rst
+++ b/docs/tutorial/index.rst
@@ -3,18 +3,21 @@ Tutorial with a real world sample
 
 Here's a quite well supplied tutorial, we're gonna start with a use case that comes from the real world.
 
-.. demo:: Configuring (the setting of) your favorite web browser
+.. objectives:: Configuring (the setting of) your favorite web browser
 
     This tutorial will show you an example of Rougail use based on the
     "how to set a proxy" in the `Mozilla Firefox <https://www.mozilla.org/en-US/firefox/new/>`_ browser
     use case.
 
-More precisely, this tutorial aims at reproducing this Mozilla Firefox settings page:
+More precisely, this tutorial aims at reproducing :term:`variable`\ s (that is, configuration options) behind this Mozilla Firefox settings page:
 
-.. note:: We are not coding a firefox plugin here.
+.. image:: images/firefox.png
+
+.. attention:: We are not coding a firefox plugin here.
           We are just going to handle some of the firefox configuration settings
           with Rougail.
 
+
 Presentation of the firefox configuration variables
 -----------------------------------------------------------
 
diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst
index 07cc119be..21cf8cc2c 100644
--- a/docs/tutorial/preliminary.rst
+++ b/docs/tutorial/preliminary.rst
@@ -27,7 +27,42 @@ Preliminaries
 
    - define a variable with a description and a default value
 
-     :ref:`Here is a Rougail variable with a description <RougailDictionaryFirstVariableDefault>`
+     :ref:`Here is a Rougail variable with a default value <RougailDictionaryFirstVariableDefault>`
+
+Values are mandatory
+-------------------------
+
+If, like in this situation:
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
+   :linenos:
+   :language: yaml
+   :caption: The :file:`config/01/config.yaml` rougail dictionnary file, with no default value set.
+   :name: RougailDictionaryNoDefaultUseCase
+
+In this situation there are no default value set. The rougail CLI will output an error :
+
+.. code-block:: shell
+   :caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` rougail dictionnary file
+
+   foo@bar:~$ rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml
+
+
+.. raw:: html
+
+   <pre>
+
+.. raw:: html
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/01/output_ro.html
+
+.. raw:: html
+
+   </pre>
+
+Rougail waits for a value to be set, that's why.
+
+
+.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` Tiramisu's definition.
 
 
 The integrator role
@@ -73,10 +108,25 @@ The Rougail CLI can output a rather complete view of the dataset:
 
 .. image:: images/UserDataOutput.png
 
-.. keypoints:: Progress keypoints
+.. keypoints:: Key points progress
+
+    **Keywords**
+
+    - :term:`dictionary`: structure description file
+    - :term:`variable`: an option's name which has a value
+    - a variable's description
+    - a variable's default value
+    - the :term:`integrator` and :term:`operator` roles
+    - a mandatory option value
+
+
+    To sum up, we have arrived here
+
+    **Structure definition file**
+
+    .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_005/firefox/00-proxy.yml
+       :linenos:
+       :language: yaml
+       :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value.
+       :name: RougailDictionaryDefaultVariabletUseCase
 
-   - :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 :term:`integrator` and :term:`operator` role