diff --git a/docs/tutorial/examples.rst b/docs/tutorial/examples.rst index 10e160662..1f7f49e5c 100644 --- a/docs/tutorial/examples.rst +++ b/docs/tutorial/examples.rst @@ -67,9 +67,6 @@ Let's give some usage examples of how to use our `no_proxy` variable: .. attention:: Note: the `examples` parameter does not specify default values. **It's just examples, it's not a setting**. -Here we can see that there are no default values set and as our variable is not :term:`mandatory`, -if we don't set values in the user data files as the `no_proxy` variable is :term:`multi`, the `no_proxy` value will be the empty list `[]`: - If we launch the Rougail CLI on user data: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/config.yml @@ -242,8 +239,17 @@ In the same way, this help `"Connections to localhost, 127.0.0.1/8 and ::1 are n -.. note:: The help section serves as supplementary documentation regarding the description parameter - and can be used in the various command-line tools that will have to deal with the variable when the `--help` option is called +.. type-along:: The difference between the `description` parameter and the `help` parameter + +The help section serves as supplementary documentation regarding the description parameter. +Please do not mix the `description` parameter and the `help` parameter's variable usage. + +A `description` allows you to describe the expected value(s) of a variable concisely and clearly. +The description can be long and detailed. + +A `help` helps to clarify any ambiguity about the variable's purpose. +It is designed to be clear precise and short, much like the help of some +command-line utility when you type the command with the `--help` or `-h` option. .. keypoints:: Key points diff --git a/docs/tutorial/multiple.rst b/docs/tutorial/multiple.rst index 9a5f44d91..d543958b5 100644 --- a/docs/tutorial/multiple.rst +++ b/docs/tutorial/multiple.rst @@ -4,7 +4,7 @@ Variable with multiple values .. objectives:: Objectives After creating another variable for the needs of our use case, we will introduce the concept of multiple type variable. - It is more or less some kind of a container variable. + It is more or less some kind of a container of variable's values. .. prerequisites:: Prerequisites @@ -50,25 +50,26 @@ Note that this variable has a :term:`disabled` property defined: variable: _.proxy_mode when_not: Automatic proxy configuration URL ... - + If the `proxy_mode` variable has the `"Automatic proxy configuration URL"` value, the `auto` variable is enabled. It is :term:`disabled` otherwise. Let's launch the Rougail CLI on this :term:`user data file `: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_110/config/03/config.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_110/config/02/config.yml :language: yaml - :caption: The :file:`config/03/config.yml` user data file + :caption: The :file:`config/02/config.yml` user data file .. --- proxy_mode: Automatic proxy configuration URL auto: https://auto.proxy.net/wpad.dat + no_proxy: 192.168.1.0/24 we have this output: .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_110/config/03/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_110/config/02/output_ro.html :class: output .. @@ -211,9 +212,12 @@ have a look at the `multi: true` parameter: What difference does it make? - Fist, note that the `no_proxy` variable is still a `domainname` type. + First, note that the `no_proxy` variable is still a `domainname` type. The type hasn't changed. +There's a big difference: now it is important to note that the values ​​of the variable +must be a list containing strings, and not a single string. +Therefore, the contents of the :term:`user data` file need to be changed. Now let's launch the Rougail CLI with the `no_proxy` variable containing a list: @@ -251,14 +255,10 @@ Now let's launch the Rougail CLI with the `no_proxy` variable containing a list: Now we have this output: .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_110/config/02/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_111/config/02/output_ro.html :class: output .. - ╭────────────── Caption ───────────────╮ - │ Variable Modified value │ - │ (⏳ Original default value) │ - ╰──────────────────────────────────────╯ Variables: ┣━━ 📓 Configure Proxy Access to the Internet: Automatic proxy configuration URL ◀ loaded from the YAML file "config/02/config.yml" (⏳ No proxy) ┣━━ 📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ loaded from the YAML file "config/02/config.yml"