family

docs/index.rst

@@ -84,6 +84,7 @@ Rougail
    :hidden:
 
    install
+   naming_convention
    
 .. rubric:: Index page
 

docs/naming_convention.rst

@@ -0,0 +1,44 @@
+.. _namingconvention:
+
+File naming convention
+==========================
+
+The structure files in a given folder
+---------------------------------------
+
+For the sake of clarity, we put the structure definitions in separate files.
+It's a good way to organize your rougail structures this way,
+in the real world we need separate files for different topics.
+
+For example some files like this:
+
+A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`firefox/10-manual.yml`
+
+::
+
+    .
+    └── firefox
+        ├── 00-proxy.yml
+        └── 10-manual.yml
+
+.. note:: We could of course could have put everything in one file.
+          Again, it is better to separate the structures in different files 
+          for reasons of ordering and clarity.
+
+Ordering your structure files
+--------------------------------
+
+The order in which files are loaded is important in Rougail. 
+In a given folder, files are loaded in alphabetical order.
+
+Furthermore, for better readability of the order in which files are 
+loaded into a folder, we have adopted a convention. 
+To facilitate classification, we have defined a standard notation for structure file names:
+
+::
+
+    XX-<name>.yml
+
+Where `XX` is a two digits integer, and `<name>` is a name that describes 
+the structure that is in this file. We advise you to adopt this convention as well.
+

docs/tutorial/family.rst

@@ -26,9 +26,9 @@ Group variables inside families
        git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
        git checkout v1.1_020
 
-.. type-along:: let's recap: we have this choice type variable 
+.. type-along:: let's recap how far we've come
 
-In the structure description file, we have:
+We have this choice type variable in its structure definition file:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
    :linenos:
@@ -57,6 +57,21 @@ In short, let's describe our `proxy_mode` variable like this:
 
    Proxy mode's settings
 
+Now we will define new variables, and other structure definitions.
+
+
+For the sake of clarity, we will put the structure definitions in separate files.
+
+Please have a look at the :ref:`file naming and organizing convention <namingconvention>`.
+
+Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make 
+a new structure file named :file:`firefox/10-manual.yml`::
+
+    .
+    └── firefox
+        ├── 00-proxy.yml
+        └── 10-manual.yml
+
 Creating a new family
 -----------------------
 
@@ -73,14 +88,6 @@ Let's create a family named `manual` which obviously corresponds to the proxy's
       description: Manual proxy configuration
       type: family
 
-.. note:: We wil define the variables, families, etc. in separate files for educational purposes.
-          It's also a good way to organize your rougail files in the real world. 
-
-          Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make 
-          a new structure file named :file:`firefox/10-manual.yml`\ .
-          We could of course could have put everything in one file.
-          It is better to separate the files for reasons of ordering and clarity.
-
 We can see that we have defined a :term:`family` here, and this family is *empty*
 (that is the family which is a container variable contains no variable yet).