From ebdeeec3af369e68d630ef67d4e37e8aa0efeb14 Mon Sep 17 00:00:00 2001
From: gwen <gwenaelremond@free.fr>
Date: Sat, 20 Jun 2026 22:09:33 +0200
Subject: [PATCH] docs(tutorial): modes

ready for proofreading
---
 docs/configuration.rst        |  6 +--
 docs/structured_data/mode.rst |  2 +
 docs/tutorial/document.rst    |  2 +
 docs/tutorial/modes.rst       | 70 +++++++++++++++++++++++++++++++----
 4 files changed, 67 insertions(+), 13 deletions(-)

diff --git a/docs/configuration.rst b/docs/configuration.rst
index ee6f724d6..cc96b7a45 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -50,11 +50,7 @@ The `auto_freeze` property is only applied until a specific variable becomes `Tr
 Modes
 ~~~~~~~~
 
-.. glossary::
-
-   mode
-   
-       A mode is a solution that allows a variable or a family to be categorized. It can be used, for example, to define a level of expertise or a particular context.
+A mode is a solution that allows a variable or a family to be categorized. It can be used, for example, to define a level of expertise or a particular context. Have a look at the :term:`mode definition <mode>` for further details.
    
 Modes are customizable in Rougail.
 
diff --git a/docs/structured_data/mode.rst b/docs/structured_data/mode.rst
index 41378320e..953ed7c16 100644
--- a/docs/structured_data/mode.rst
+++ b/docs/structured_data/mode.rst
@@ -1,3 +1,5 @@
+.. _structured_data_mode:
+
 Mode
 ====
 
diff --git a/docs/tutorial/document.rst b/docs/tutorial/document.rst
index 3e04bef46..663b6ac0e 100644
--- a/docs/tutorial/document.rst
+++ b/docs/tutorial/document.rst
@@ -1,3 +1,5 @@
+.. _documented_variable:
+
 A full documented variable 
 ==============================
 
diff --git a/docs/tutorial/modes.rst b/docs/tutorial/modes.rst
index 95e07802f..0923cd0f6 100644
--- a/docs/tutorial/modes.rst
+++ b/docs/tutorial/modes.rst
@@ -1,6 +1,12 @@
 Modes
 =========
 
+.. objectives:: Objectives
+
+   For information on the concept we will be using in this section, please refer to
+   the definition of the :term:`mode` in the documentation, 
+   and you can read all the :ref:`description of the modes in the structuring data point of view <structured_data_mode>`.
+
 .. prerequisites:: Prerequisites
 
     - We assume that Rougail's library is :ref:`installed <installation>` on your computer.
@@ -22,15 +28,63 @@ Modes
 A variable in avanced mode
 ---------------------------
 
-on les déclare en CLI `--modes_level basic standard advanced`
+To specify the various possible modes, we must declare them on the command line
+with the `--modes_level` command line option:
 
-c'est un paramètre à définir sur la famille, 
-`mode: advanced`
+.. raw:: html
+   :class: terminal
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_150/config/01/cmd_ro.txt
 
-aujourd'hui je m'en sert pour filtrer les variables que je veux dans ma doc
-Une doc sans les variables avancées qui sera plus courte et une seconde complète.
-Tu peux expliquer comme ça et on réfléchira au concept plus tard.
+..
+    rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/01/config.yml
 
 
-à part ça je ne me souviens pas bien de l'usage à l'époque de créole.
-C'est quand on était dans l'éditeur Créole, on avait un mode basique (boulet) et une mode expert
+Next, we can set a mode parameter with a value from the list: `basic`, `standard`, `advanced`.
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_150/firefox/55-proxy_dns_socks5.yml
+   :language: yaml
+   :caption: The `proxy_dns_socks5` variable in the :file:`firefox/55-proxy_dns_socks5.yml` file
+
+..
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    proxy_dns_socks5:
+      description: Use proxy DNS when using SOCKS v5
+      mode: advanced
+      default: false
+      disabled:
+        jinja: |-
+          {{ _.manual.socks_proxy.version is propertyerror or _.manual.socks_proxy.version == 'v4' }}
+        return_type: boolean
+        description: |-
+          if "_.manual.socks_proxy.version" is accessible and equals "v4"
+    ...
+
+Here, we have set the mode to `advanced` for the `proxy_dns_socks5` variable
+because we want to classify it as a variable intended for use by advanced users.
+
+.. questions:: What is it actually used for? 
+
+   Well, to begin with, reading the structure file provides a clear piece of information:
+   this variable is intended to be manipulated by an experienced user.
+
+Furthermore, if you integrate Rougail as a library into your business applications,
+you will have access to different types of views corresponding to each mode.
+
+A useful application within Rougail itself involves filtering the display of certain 
+variables when generating documentation, based on the mode.
+
+In our case, this makes it possible to generate documentation for standard users
+where the `proxy_dns_socks5` won't be present,
+and a different, more detailed documentation for advanced users
+where the `proxy_dns_socks5` will be explained in detail.
+
+.. seealso:: Look at the :ref:`different ways to document a variable with Rougail <documented_variable>`
+             in this tutorial.
+
+.. keypoints:: let's review the key points
+
+    We have seen the benefits of assigning modes to a variable to define 
+    documentations targeted at specific users.