diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 03c185d74..e9cd900e4 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -6,8 +6,8 @@ Getting started We will learn how to: - create a :term:`structure description file ` - - add a :term:`structure file format version ` - - add a :term:`variable` and set its :term:`value` + - add a :term:`structure file ` format version in the structure file + - add a :term:`variable` in the structure file and set its default :term:`value` .. prerequisites:: Prerequisites @@ -36,13 +36,11 @@ Creating a structure file - First, we will create a :term:`structure file `, so let's create a :file:`00-proxy.yml` file located in the :file:`firefox` subfolder. -.. type-along:: An empty structure file - This is an empty Rougail :term:`structure description file: ` .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml :language: yaml - :caption: An empty rougail dictionnary file with the version number only + :caption: An empty rougail structure file with only the YAML header and the version number :name: RougailStructVersion .. @@ -51,16 +49,27 @@ This is an empty Rougail :term:`structure description file: ` :tutorial:`Download this file from the rougail-tutorials git repository ` +This `version` specification is just the rougail YAML's format version specification. +By now, we have an empty structure file with the format specification in it. + Let's add our first variable ------------------------------ -.. note:: A variable is defined at a minimum by its name. +.. type-along:: For those who follow the tutorial with the help of the git repository -A :term:`variable` in the :term:`structure description file ` + Now you need to checkout the `v1.1_001` version:: + + git checkout v1.1_001 + + +- A variable is defined at a minimum by its name. +- A :term:`variable` lives in the :term:`structure description file `. + +Here we define a variable named `proxy_mode`: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml :language: yaml - :caption: A Rougail structure file with only one variable + :caption: A Rougail structure file with only one variable in it :name: RougailDictionaryFirstVariableName .. @@ -69,14 +78,14 @@ A :term:`variable` in the :term:`structure description file ` :tutorial:`Download this file from the rougail-tutorials git repository ` -Let's run the Rougail CLI utility command: +Let's run the Rougail CLI utility command in a terminal: .. code-block:: text :class: terminal rougail -m firefox/ -we will actually have an error: +Well, we notice that we have an error: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/01/output_ro.html @@ -87,7 +96,7 @@ we will actually have an error: ┣━━ The following variables are mandatory but have no value: ┗━━ - proxy_mode -Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet. +It's because this first defined variable is :term:`mandatory` and needs to have a value set **but** there's no value yet. We can therefore deduce the fact that: @@ -105,13 +114,25 @@ Rougail waits for the `proxy_mode` configuration option's value to be set. A variable is mandatory when a value is required, that is, `None` **is not** a possible value. It **must** have a defined value. -.. seealso:: To go further, have a look at the :tiramisu:`mandatory option ` according to the definition of Tiramisu. +.. seealso:: To go further, have a look at the :tiramisu:`mandatory option ` + according to the :xref:`Tiramisu ` underlyning consistency system. + You will learn that it is actually possible to disable the mandatory property behavior, + but you need to declare it explicitely. + +Describe the variable +------------------------- -Let's add a variable's description, which is not mandatory but which is a good practice: +Let's add a variable's description, which is not mandatory but which is usually a good practice. + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_002` version:: + + git checkout v1.1_002 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_002/firefox/00-proxy.yml :language: yaml - :caption: A Rougail dictionnary file with a variable and a description + :caption: A Rougail structure file with a variable and a description :name: RougailStructFirstVariableDescription .. @@ -120,22 +141,45 @@ Let's add a variable's description, which is not mandatory but which is a good p :tutorial:`Download this file from the rougail-tutorials git repository ` -.. type-along:: how to set a value -- the default value +You have two way to define a variable's description: -We need to set a value to this `proxy_mode` variable. A first way to do it is *to set a value by default*. +- the verbose way: + + .. code-block:: yaml + + proxy_mode: + description: Configure Proxy Access to the Internet + + +- or the compact way, using the "`#`" YAML notation: + + .. code-block:: yaml + + proxy_mode: # Configure Proxy Access to the Internet + +Set a default value +--------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_003` version:: + + git checkout v1.1_003 + +We will learn different ways to set a value, the first way is setting a *default* value. .. glossary:: default value - A default value is a variable value that is predefined, that is, this value is placed + A default value is a variable value that is predefined, that's why this value is placed right in the structure file. -So let's define a variable with a description -- **and a default value** +Let's add a default value to this `proxy_mode` variable. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml :language: yaml - :caption: A rougail dictionnary file with a default value for the variable + :caption: A rougail structure file with a default value for the variable :name: RougailDictionaryVariableDefault .. @@ -144,12 +188,13 @@ So let's define a variable with a description -- **and a default value** :tutorial:`Download this file from the rougail-tutorials git repository ` -.. type-along:: how to set a value -- the assignment +.. admonition:: how to set a value -- the assignment - A default value has been set, great. Now how do I assign a value to a variable? + A default value has been set, great. This raises a question about what a normal value is. -The different rougail roles and the default values ------------------------------------------------------- + Now then how can I assign a normal value to a variable? + +.. type-along:: The different rougail roles and the default values So far we have only talked about the one that writes the :term:`structure files `\ . It's *role* is called the integrator's role. @@ -256,7 +301,7 @@ In our firefox use case, the real type of the `proxy_mode` variable will be now .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml :linenos: :language: yaml - :caption: The real :file:`firefox/proxy.yml` Rougail dictionnary file with a choice type + :caption: The real :file:`firefox/proxy.yml` Rougail structure file with a choice type :name: RougailDictionaryChoiceType .. @@ -339,7 +384,7 @@ We have the list of the possible (authorized) values: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml :linenos: :language: yaml - :caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a default value. + :caption: A Rougail structure file with a variable named `proxy_mode`, with a default value. ..