docs(abstract): properties, ..

docs/concepts.rst

@@ -1,7 +1,18 @@
 Abstract presentation
 =========================
 
-Rougail, a powerful, free/open-source configuration language that combines declaration, data validation, and templating in a single, declarative syntax.
+Rougail, a powerful, free/open-source configuration manager and language that combines declaration, data validation, and templating in a single, declarative syntax.
+
+It will be useful to:
+
+- define variables (the structure) easily and their constraintes
+- loads those variables
+- generate variables documentation
+- loads variables' values
+- validate the variables and the overall consistency handling system
+- generate custom table views
+- export to different common format (YAML, Ansible, ...)
+- ...
 
 Why another configuration manager?
 -------------------------------------
@@ -24,32 +35,37 @@ At the time of the design of Rougail, there were structuring choices that define
 
 The steps in Rougail can be explain as follows:
 
-- loads the variable structure file
+- loads the variable structured data
 - loads the user data
-- reads, validates, exports the data
+- reads, validates, exports, document, ... the data
 
-Structure
+Structured data
-~~~~~~~~~
+~~~~~~~~~~~~~~~~~
+
+Structured data is also called Rougail format.
 
 .. glossary::
 
-   structure file
+   structured data
 
-       A structure file in the Rougail meaning is a YAML file that describes variables
+       A configuration-first DSL (domain-specific language) designed for describing variables, consistency
-       and their dependencies.
+       and describe the relationships between variables in a declarative style.
-       There can be a lot of structure files located in many different folders.
 
-       Rougail reads all the structure files and loads them into a single object
+       The language is a mix of YAML ans Jinja Templating.
-       that represents the whole :term:`context`.
+
+       It goes beyond traditional schema languages (like JSON Schema, OpenAPI, Cuelang)
+       by combinig type systems, powerful validation, consistency of the configuration and documentation.
+
+Structured data are commonly place in structure file.
 
 User data
-~~~~~~~~~
+~~~~~~~~~~
 
 .. glossary::
 
     user data
 
-        User datas, as opposed to structured datas, are datas that only concern the assignment of values
+        User datas, as opposed to structured data, are datas that only concern the assignment of values
         and not the consistency of the variables between them.
 
         The variable's values are also called **user values**.
@@ -68,22 +84,25 @@ Here a some user data examples:
 Output
 ~~~~~~~
 
+Structured and user data form a coherent configuration useful for different purpose.
+
+Output is here to define what kind of data we want.
+
 And some output examples:
 
-Ensuite on pourra définir sous quelle forme on veut recueillir l'information (Outputs) :
+- term:`Tiramisu` object
+- extract JSON
+- extract to Ansible inventory
+- documentation
+- custom table views
 
-- un objet Tiramisu
-- une extraction JSON
-- un export pour l'inventaire Ansible
-- de la documetation
-- ...
 .. list-table::
    :widths: 15 45
    :header-rows: 1
 
    * - Step
 
-   * - Structure
+   * - Structured data
 
    * - User data
 
@@ -94,27 +113,9 @@ What kind of actor?
 
 It's clear that Rougail can be used in many contexts.
 
-Here we'll define actor names. Obviously, these aren't the only possible actors. We're just defining the actors within the Rougail context. Choice your own actor name if you wish to personnalize in your specific context.
+Here we'll define actor names. Obviously, these aren't the only possible actors.
 
-.. list-table::
+We're just defining the actors within the Rougail context. Choice your own actor name if you wish to personnalize in your specific context.
-   :widths: 15 45
-   :header-rows: 1
-
-   * - Step
-     - Description
-     - Actor
-
-   * - Structure
-     - The actor who defines the structure
-     - Integrator
-
-   * - User data
-     - The actor who sets the values
-     - Operator
-
-   * - Output
-     - The actor who uses the variables with their values
-     - Operator
 
 .. glossary::
 
@@ -136,6 +137,26 @@ Here we'll define actor names. Obviously, these aren't the only possible actors.
         The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated.
         The type validation is driven by the definitions in the :term:`structure file <structure file>`.
 
+.. list-table::
+   :widths: 15 45
+   :header-rows: 1
+
+   * - Step
+     - Actor
+     - Description
+
+   * - Structured data
+     - Integrator
+     - The actor who defines the structure
+
+   * - User data
+     - Operator
+     - The actor who sets the values
+
+   * - Output
+     - Operator or integrator
+     - The actor who uses the variables with their values
+
 Variable lifetime
 ----------------------
 
@@ -154,13 +175,11 @@ The lifecycle of a variable includes the generic stages (like, in the Python lan
    :header-rows: 1
 
    * - Creation
-     - Initialization
      - Assignment
      - Reading
      - Destruction
 
    * - Variables are assigned a name and a type
-     - Their first value is assigned
      - The variable's value is modified
      - The variable's value is used
      - The variable terminates upon the destruction of the object
@@ -171,12 +190,12 @@ But other concepts are included in the lifecycle:
    :widths: 15 45
    :header-rows: 1
 
-   * - Documentation
+   * - Permission
-     - Permission
+     - Documentation
      - Specialization
 
-   * - Informations for variable documentation like description or help. Those informations are used to build documentation, changelog, ...
+   * - Properties describe access constraints
-     - Properties describe access constraints
+     - Informations for variable documentation like description or help. Those informations are used to build documentation, changelog, ...
      - Define usage, selection,...
 
 
@@ -188,23 +207,23 @@ But other concepts are included in the lifecycle:
      - Actor
      - Lifetime
 
-   * - Structure
+   * - Structured data
      - Integrator
-     - Creation + initialization
+     - Creation
 
    * - User data
      - Operator
-     - Assignment + permission
+     - Assignment and permission
 
    * - Output
-     - Operator
+     - Operator or integrator
-     - Reading + permission + documentation + specialization
+     - Reading, permission, documentation and specialization
 
-Mutability
+Variable mutability
----------------
+---------------------
 
-Structure
+Structured data
-~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~
 
 When the integrator define the structure, variable are mutable.
 
@@ -212,19 +231,15 @@ Even if the default behavior is to conflict when multiple declarations for the s
 
 It's possible to explicitly allow to unifying (combined) multiple variables declarations.
 
-There is no value, strictly speaking. It's a default value. As other parameter, the default value is explicitly mutable.
-
 User data
 ~~~~~~~~~~
 
 It's no more possible to modifying variable definition.
 
-The value is now mutable.
-
 Output
 ~~~~~~~
 
-Variable definition and value setting are immutable.
+Variable definition settings are immutable.
 
 .. list-table::
    :widths: 15 45
@@ -233,29 +248,39 @@ Variable definition and value setting are immutable.
    * - Step
      - Actor
      - Lifetime
-     - Variable mutation
+     - Variable mutability
-     - Value mutation
 
-   * - Structure
+   * - Structured data
      - Integrator
      - Creation + initialization
      - Mutable
-     - N/A
 
    * - User data
      - Operator
-     - Assignment + permission
+     - Assignment and permission
      - Immutable
-     - Mutable
 
    * - Output
-     - Operator
+     - Operator or integrator
-     - Reading + permission + documentation + specialization
+     - Reading, permission, documentation and specialization
-     - Immutable
      - Immutable
 
-Read write or read only mode
+Value access
------------------------------
+-------------
+
+In the `structured data` step, there is no value, strictly speaking. It's a default value.
+As other parameters, the default value is explicitly mutable.
+
+In the `user data` step, we can modify the values. That's precisely the purpose of this step.
+The configuration is said to be in `read write` mode.
+
+But at the `output` step, it is obviously no longer possible to modify the value.
+The configuration is said to be in `read only` mode.
+
+.. attention::
+   It is important not to confuse `value` and `calculated value`.
+   The result of a calculation can change over time.
+   In this case, the value does indeed correspond to the result of the calculation.
 
 .. list-table::
    :widths: 15 45
@@ -264,34 +289,63 @@ Read write or read only mode
    * - Step
      - Actor
      - Lifetime
-     - Variable mutation
+     - Variable mutability
-     - Value mutation
+     - Value
-     - Read/Write
 
-   * - Structure
+   * - Structured data
      - Integrator
      - Creation + initialization
      - Mutable
-     - N/A
+     - Mutable default value
-     - N/A
 
    * - User data
      - Operator
-     - Assignment + permission
+     - Assignment and permission
      - Immutable
-     - Mutable
      - Read write
 
    * - Output
-     - Operator
+     - Operator or integrator
-     - Reading + permission + documentation + specialization
+     - Reading, permission, documentation and specialization
-     - Immutable
      - Immutable
      - Read only
 
 Access control
 -----------------
 
+.. FIXME: duplicate from tutorial/properties.rst
+
+Access control is achieved through `properties`.
+
+
+.. glossary::
+
+   property
+
+       A property is a state (`disabled`, `mandatory`, `frozen`, `hidden`...)
+       of a family or a variable.
+       These properties change the usual behavior of a variable or family.
+
+The properties can be defined permanently or according to the result of a calculation.
+
+There is two main properties.
+
+Hidden variable
+~~~~~~~~~~~~~~~
+
+A `hidden` variable is a variable whose value cannot be modified by the operator.
+
+This could be an internal variable used by the integrator that is not supposed to change.
+
+Or a variable that only makes sense in a particular context. Therefore, this variable can be hidden and then unhidden depending on the context.
+
+Disabled variable
+~~~~~~~~~~~~~~~~~
+
+A `disabled` variable is a variable that will not be accessible to any of the actors (integrator and operator).
+
+This property is generally used dynamically to remove access to the variable depending on the context.
+
 .. list-table::
    :widths: 15 45
    :header-rows: 1
@@ -299,31 +353,27 @@ Access control
    * - Step
      - Actor
      - Lifetime
-     - Variable mutation
+     - Variable mutability
-     - Value mutation
+     - Value
-     - Read/Write
      - Access control
 
-   * - Structure
+   * - Structured data
      - Integrator
      - Creation + initialization
      - Mutable
-     - N/A
+     - Mutable default value
-     - N/A
      - N/A
 
    * - User data
      - Operator
-     - Assignment + permission
+     - Assignment and permission
      - Immutable
-     - Mutable
      - Read write
      - hidden + disabled
 
    * - Output
-     - Operator
+     - Operator or integrator
-     - Reading + permission + documentation + specialization
+     - Reading, permission, documentation and specialization
-     - Immutable
      - Immutable
      - Read only
      - disabled + mandatory

docs/structfile.rst

@@ -1,6 +1,20 @@
 The structure files
 =====================
 
+Definition
+------------
+
+.. glossary::
+
+   structure file
+
+       A structure file in the Rougail meaning is a YAML file that describes variables
+       and their dependencies.
+       There can be a lot of structure files located in many different folders.
+
+       Rougail reads all the structure files and loads them into a single object
+       that represents the whole :term:`context`.
+
 The header of a structure file
 -----------------------------------
 
@@ -39,10 +53,10 @@ The structured data
 
    structured data
    
-       We sometimes call "structured datas" the datas that are defined in the structure files,
+       We sometimes call "structured datas" the datas that are defined the structure,
        as opposed to :term:`user datas <user data>`\ .
-       For example when a value of a variable is defined in the structured datas, that is
+       For example when a value of a variable is defined in the structured datas
-       in a structured file, the assigned value's status is that the variable's value is a default value. 
+       the assigned value's status is that the variable's value is a default value. 
        If the assigned value of the variable is defined in a user data file, 
        it is an user assigned value.