docs(naming-convention): clarify

docs/naming_convention.rst

@@ -1,10 +1,13 @@
-.. _namingconvention:
+Naming convention
+=====================
+
+.. _filenamingconvention:
 
 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,
@@ -26,7 +29,7 @@ A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`f
           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.
@@ -42,34 +45,28 @@ To facilitate classification, we have defined a standard notation for structure
 Where `XX` is a two digits integer followed by an hyphen, and `<name>` is a name that describes 
 the structure that is in this file. We advise you to adopt this convention as well.
 
-.. _filenamingconvention:
+File naming convention
+'''''''''''''''''''''''''''''
 
-Generic file naming policy
+The is no restriction to the `<name>` name part of file name. But it is preferable to only use
----------------------------
+lowercase ASCII letters, numbers and the `"_"` (undescore) character. 
 
-Here are our generic file naming conventions.
+.. _namingconvention:
 
-The regular expression that validates our file naming policy is:
+Variable and family naming convention
+---------------------------------------
+
+The name of a variable and a family must be chosen carefully.
+It is the path that will allow users to retrieve their defined values.
+An obscure name will cause confusion.
+
+By design, you cannot use just any character to name your variable.
+
+The regular expression that validates our variable and family naming policy is:
 
 .. code-block:: python
 
-    NAME_REGEXP = re.compile(r"^[a-z0-9_]*$")
+    re.compile(r"^[a-z0-9_]*$")
 
-You can see that it is preferable to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character. 
+You can see that it is mandatory to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character. 
 The snake case typographic convention is therefore used.
-
-Dynamically built family naming policy
-------------------------------------------
-
-Regarding the :ref:`dynamically built families <dynfam>` the file naming policy is slightly different.
-ASCII letters, numbers and the `"_"` (undescore) character are allowed, that is we allow uppercase characters.
-
-Why allowing uppercase letters for a dynamic familly? 
-Because we have choosed to write :term:`identifiers <identifier>` in uppercase.
-
-.. note:: The identifier is in uppercase, but the dynamic familly name is in lowercase. 
-          You can then choose the corresponding structure filenames in lowercase.
-
-.. seealso:: For more information about dynamic famillies, please have a look at the 
-             :ref:`dynamic family tutorial <dynfam>`   
-

docs/tutorial/dynfam.rst

@@ -180,7 +180,7 @@ This identifier is a parameter that enables us to create two families named `htt
                then rougail will raise a family/variable override warning.
                
                When choosing a dynamically built family name, rougail will replace spaces, accents, uppercases... 
-               by valid character and put all in lowercase. Only ASCII and underscore ("`_`") characters are allowed.
+               by valid character and put all in lowercase. Have a look at the :ref:`naming convention <namingconvention>`.
 
                As you can see here, the identifier is `HTTPS`, but the name clearly contains `https` (in lowercase).
 
@@ -273,9 +273,6 @@ We can see that the dynamically built families that have been created:
 
 and, as we expected, containing an address and a port.
 
-.. seealso:: Have a look at the :ref:`file naming convention <filenamingconvention>` 
-             In order to choose a proper name to a structure file or a dynamic familiy name.
-
 A conditional disabled variable with dynamic identifier
 --------------------------------------------------------
 

docs/tutorial/practice1.rst

@@ -51,6 +51,8 @@ What do we want to be implemented
 
 .. exercise:: Exercice
 
+    You need to think about:
+
     - choose a file name that respect the :ref:`file naming and organizing convention <namingconvention>`
     - define an appropriate variable name, have a look at our :ref:`file naming convention <filenamingconvention>`
     - the Firefox description is in negative mode, which is not a good practice for us, we rewrite it in positive mode
@@ -73,11 +75,11 @@ Please unroll the "Solution" widget to see our solution:
     - this variable is true by default,
     - this variable shall be :term:`disabled` if the `proxy_mode` variable is set to `"No proxy"`.
 
-.. 
+..
     %YAML 1.2
     ---
     version: 1.1
-    
+
     prompt_authentication:
       description: Prompt for authentication if password is saved
       default: true
@@ -94,8 +96,8 @@ What do we want to be implemented
 
 .. exercise:: Exercice
 
-    You need to think about: 
+    You need to think about:
-    
+
     - the choice of a file name that respect the :ref:`file naming and organizing convention <namingconvention>`
     - in order to define an appropriate variable name,
     - the `description` parameter will be the Firefox description,
@@ -109,7 +111,7 @@ Our solution
 .. type-along:: For those who follow the tutorial with the help of the git repository
 
     Now you need to checkout the :tutorial:`v1.1_131 <src/tag/v1.1_131/README.md>` version::
-     
+
           git switch --detach v1.1_131
 
 Please unroll the "Solution" widget to see our solution:
@@ -120,11 +122,11 @@ Please unroll the "Solution" widget to see our solution:
        :language: yaml
        :caption: The :file:`firefox/55-proxy_dns_socks5.yml` a Jinja conditional disabled boolean variable
 
-.. 
+..
     %YAML 1.2
     ---
     version: 1.1
-    
+
     proxy_dns_socks5:
       description: Use proxy DNS when using SOCKS v5
       default: false