docs(tutorial): modes

ready for proofreading

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.
 

docs/structured_data/mode.rst

@@ -1,3 +1,5 @@
+.. _structured_data_mode:
+
 Mode
 ====
 

docs/tutorial/document.rst

@@ -1,3 +1,5 @@
+.. _documented_variable:
+
 A full documented variable 
 ==============================
 

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.