rougail/docs/tutorial/index.rst

.. _tutorial:

Tutorial with a real world sample
=====================================

Here is a fairly complete tutorial, it is a use case that comes from the real world.
At the end of the tutorial you will have a good understanding of rougail.

.. objectives:: Objectives

    Configuring (the setting of) your favorite web browser.

    This tutorial will show you an example of Rougail use based on the
    *how to set a proxy* in the `Mozilla Firefox <https://www.mozilla.org/en-US/firefox/new/>`_ browser
    use case.

More precisely, this tutorial aims at reproducing :term:`variable`\ s behind this Mozilla Firefox settings page:

.. image:: images/firefox.png

We'll call the variables **configuration options** since that's what the variables represent in this use case.

.. attention:: We are not coding a firefox plugin here.
          We are just going to handle some of the firefox configuration settings
          with Rougail. We are just validating them. 
          
          The configuration option values entered by the user have to be:

          - validated
          - consitent
          - conform

Let's dive into this **configuration options validation** use case.

Presentation of the firefox configuration options 
--------------------------------------------------

At first glance we can see that we have a selection of five configuration options that we need to fill in, they are highlighted here in this screenshot:

.. image:: images/firefox_01.png

We'll learn in this tutorial how to set the values of the configuration options in a clean way with the Rougail library. 

.. prerequisites:: Important advice

   It is advisable to follow this tutorial with the help of the corresponding :tutorial:`Rougail git repository tutorial <src/branch/1.1>`.
   You can instead copy/paste or download the different file contents that are explained in this tutorial step and save the files to your computer.
   However, if you use the git rougail tutorial repository, you will have all the necessary files distributed in the correct tree structure, 
   which is in our opinion much more practical.
   
   ::
   
       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials/src/branch/1.1

.. toctree::
   :titlesonly:
   :caption: The firefox tutorial

   preliminary
   choice
   family
   domainname
   disabled
   boolean
   dynfam
   calculation