rougail/docs/tutorial/preliminary.rst

Preliminaries
================

.. objectives:: Objectives

   We will learn how to:

   - create a Rougail :term:`dictionary` (the structure description file)
   - define a Rougail format version
   - define a Rougail :term:`variable` and set its :term:`value`

.. type-along:: Reminders

   We alread learned in other workshops how to:

   - define a Rougail :term:`dictionary`

     :ref:`Here is an empty Rougail dictionnary <RougailDictionaryEmptyFile>`

   - define a variable and its default value

     :ref:`Here is a first Rougail variable in a Rougail dictionnary <RougailDictionaryFirstVariable>`

   - define a variable with a description

     :ref:`Here is a Rougail variable with a description <RougailDictionaryFirstVariableDescription>`

   - define a variable with a description and a default value

     :ref:`Here is a Rougail variable with a description <RougailDictionaryFirstVariableDefault>`


The integrator role
----------------------

.. glossary::

    integrator

        An integrator in the Rougail logic is the person who writes the dictionaries.
        He has the responsibilité of the integration process, that is,
        defines the variables and the relationship between them, the variables that are allowed
        (or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency**
        of the variables.

        .. image:: images/integrator.png

.. important:: Note that there is a strong consistency, it means that the validation is done across
               the entire structure, not only with a schema (type) validation system.

The operator role
---------------------

.. glossary::

    operator

        An operator ih the Rougail logic is the person who gives :term:`value`\ s to the pre-defined variables,
        his responsabilities are to set variable values correctly.

        The user :term:`value`\ s, that is the values that have been set by the operator, are validated
        by the dictionary structure.

        .. image:: images/operator.png

The operator role corresponds to the :term:`tiramisu` settings:

.. image:: images/tiramisu_get_set.png

.. index:: questionary

But instead of coding in the end user developer way, the opterator will prefer using the Rougail CLI interface:

.. image:: images/QuestionaryChoice.png

.. index:: Rougail CLI

The Rougail CLI can output a rather complete view of the dataset:

.. image:: images/UserDataOutput.png

.. keypoints:: Progress keypoints

   - :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 integrator and operator role