From 10a25b0cfe4d552effc07d17c4e36dcd80aac0ff Mon Sep 17 00:00:00 2001 From: gwen Date: Sun, 9 Feb 2025 11:20:36 +0100 Subject: [PATCH] dictionary -> structure file --- docs/dictionary.rst | 16 ++++++++-------- docs/gettingstarted.rst | 4 ++-- docs/library.rst | 24 ++++++++++++------------ docs/tutorial/preliminary.rst | 19 +++++++++---------- docs/tutorial/proxymode.rst | 2 +- docs/variable.rst | 22 +++++++++++----------- 6 files changed, 43 insertions(+), 44 deletions(-) diff --git a/docs/dictionary.rst b/docs/dictionary.rst index 8471b8216..5483dbfb1 100644 --- a/docs/dictionary.rst +++ b/docs/dictionary.rst @@ -1,16 +1,16 @@ -The dictionaries +The structure files ===================== -What do you mean by :term:`dictionary`? +What do you mean by :term:`structure file`? ------------------------------------------- -A :term:`dictionary` is a YAML file whose structure is described in this documentation page. +A :term:`structure file` is a YAML file whose structure is described in this documentation page. -A dictionary contains a set of variables loaded into :term:`Tiramisu`, usable at any time, especially in a :term:`templates`. +A structure file contains a set of variables loaded into :term:`Tiramisu`, usable at any time, especially in a :term:`templates`. -:term:`Families` and :term:`variables` can be defined in several dictionaries. These dictionaries are then aggregated. +:term:`Families` and :term:`variables` can be defined in several structure files. These structure files are then aggregated. -Dictionaries are loaded in the directory order defined by the `dictionaries_dir` configuration parameter. +Structure files are loaded in the directory order defined by the `dictionaries_dir` configuration parameter. Each directory is loaded one after the other. Inside these directories the YAML files will be classified in alphabetical order. @@ -21,11 +21,11 @@ It is also possible to :term:`redefine` elements to change the behavior of a fam The default namespace ------------------------- -The families and variables contained in these dictionaries are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace with the :term:`variable namespace ` parameter of the :doc:`configuration `. +The families and variables contained in these structure files are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace with the :term:`variable namespace ` parameter of the :doc:`configuration `. This namespace is a bit special, it can access variables in another namespace. -The extra dictionaries +The extra structure files --------------------------- An extra is a different namespace. The idea is to be able to classify the variables by theme. diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 57400212a..2c05609fd 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -27,7 +27,7 @@ What is a consistency handling system ? Here is the :xref:`tiramisu library`. In the Rougail scope, we call it :term:`variable`\ s and :term:`families`. -In Rougail, the families and variables are located in the :term:`structure files `. +In Rougail, the families and variables are located in the :term:`structure files `. The structure files --------------------- @@ -92,7 +92,7 @@ You can see that there is just a `version` specification. The variables ----------------- -Here is a :term:`structure file ` example with a variable into it: +Here is a :term:`structure file` example with a variable into it: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml :language: yaml diff --git a/docs/library.rst b/docs/library.rst index fba39d0be..162ec5bd3 100644 --- a/docs/library.rst +++ b/docs/library.rst @@ -14,14 +14,14 @@ To load the configuration you must import the `RougailConfig` class and set the RougailConfig['dictionaries_dir'] = ['dict'] -Let's convert a dictionary ------------------------------ +Let's convert a structure file +------------------------------- -As a reminder, a :term:`dictionary` is a set of instructions that will allow us to create :term:`families` and :term:`variables`. +As a reminder, a :term:`structure file` is a set of instructions that will allow us to create :term:`families` and :term:`variables`. -Let's start by creating a simple dictionary. +Let's start by creating a simple structure file. -Here is a first :file:`dict/00-base.yml` dictionary: +Here is a first :file:`dict/00-base.yml` structure file: .. code-block:: yaml @@ -68,8 +68,8 @@ The Rougail CLI can output a rather complete view of the dataset: .. image:: images/UserDataOutput.png -Let's convert an extra dictionary -------------------------------------- +Let's convert an extra structure file +--------------------------------------- .. index:: extras @@ -85,7 +85,7 @@ For example, here's how to add an `example` namespace: RougailConfig['extra_dictionaries']['example'] = ['extras/'] -Then let's create an extra :term:`dictionary` :file:`extras/00-base.yml`: +Then let's create an extra :term:`structure file` :file:`extras/00-base.yml`: .. code-block:: yaml :caption: the :file:`extras/00-base.yml` file content @@ -117,7 +117,7 @@ Let's execute `script.py`: Let's create a custom function ---------------------------------- -We create the complementary :term:`dictionary` named :file:`dict/01-function.yml` so that the `my_variable_jinja` variable is :term:`calculated`: +We create the complementary :term:`structure file` named :file:`dict/01-function.yml` so that the `my_variable_jinja` variable is :term:`calculated`: .. code-block:: yaml @@ -195,7 +195,7 @@ To add the new lipogram type in Rougail: >>> RougailConfig['custom_types']['lipogram'] = LipogramOption Now, we can use lipogram type. -Here is a :file:`dict/00-base.yml` dictionary: +Here is a :file:`dict/00-base.yml` structure file: .. code-block:: yaml @@ -219,7 +219,7 @@ Upgrade dictionnaries to upper version All dictionnaries has a format version number. When a new format version is proposed, it is possible to automatically convert the files to the new version. -We create a term:`dictionary` named :file:`dict/01-upgrade.yml` with version 1.0: +We create a term:`structure file` named :file:`dict/01-upgrade.yml` with version 1.0: .. code-block:: yaml @@ -240,7 +240,7 @@ We create a term:`dictionary` named :file:`dict/01-upgrade.yml` with version 1.0 >>> upgrade = RougailUpgrade() >>> upgrade.load_dictionaries('dict_converted') -The term:`dictionary` named :file:`dict_converted/01-upgrade.yml` is in version 1.1: +The term:`structure file` named :file:`dict_converted/01-upgrade.yml` is in version 1.1: .. code-block:: yaml diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 631ca9342..324b42bf9 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -5,8 +5,8 @@ Preliminaries We will learn how to: - - create a Rougail :term:`structure description file ` - - define a Rougail :term:`structure description file ` format version + - create a Rougail :term:`structure description file ` + - define a Rougail :term:`structure description file ` format version - define a Rougail :term:`variable` and set its :term:`value` .. prerequisites:: Prerequisites @@ -26,7 +26,7 @@ Preliminaries    │   └── struct.yml - Let's make a :file:`workplace` directory, with a :file:`firefox` subfolder. -- First, we wil make a :term:`structure file `, so let's create a :file:`struct.yml` file +- First, we wil make a :term:`structure file `, so let's create a :file:`struct.yml` file located in the :file:`firefox` subfolder. The structure file @@ -37,7 +37,7 @@ This is an empty Rougail dictionnary .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml :language: yaml :caption: An empty rougail dictionnary file with the version number only - :name: RougailDictionaryEmptyFile + :name: RougailStructVersion .. --- @@ -45,8 +45,7 @@ This is an empty Rougail dictionnary .. type-along:: a first variable - Let's put a variable in the Rougail :term:`structure description file ` - + Let's put a variable in the Rougail :term:`structure description file ` Defining a variable and its default value ---------------------------------------------- @@ -101,7 +100,7 @@ Then we just add a variable's description, which is a good practice. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml :language: yaml :caption: A Rougail dictionnary file with a variable and a description - :name: RougailDictionaryFirstVariableDescription + :name: RougailStructFirstVariableDescription .. --- @@ -144,7 +143,7 @@ So far we have only talked about the one that writes the structure files. It is integrator - An integrator in the Rougail logic is the person who writes the :term:`structure files `\ . + An integrator in the Rougail logic is the person who writes the :term:`structure files `\ . 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** @@ -159,7 +158,7 @@ Now we will talk about the one that defines the values. It is called the operato 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 of course type validated by the :term:`structure file definition `. + The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated by the :term:`structure file definition `. Values are mandatory ------------------------- @@ -309,7 +308,7 @@ We have the list of the possible (authorized) values: **Keywords** - - :term:`structure file `: structure description file + - :term:`structure file `: structure description file - :term:`variable`: an option's name which has a value - a variable's description - a variable's type diff --git a/docs/tutorial/proxymode.rst b/docs/tutorial/proxymode.rst index 4bfff6a2d..ce4ff4a6b 100644 --- a/docs/tutorial/proxymode.rst +++ b/docs/tutorial/proxymode.rst @@ -13,7 +13,7 @@ The `proxy` family .. type-along:: Reminders - - As a prerequisite we have an idea of what a :term:`structure file description ` is. + - As a prerequisite we have an idea of what a :term:`structure file description ` is. - We have a :file:`firefox` folder and we are putting all the structure description files in it. - We had at the :term:`structure description file ` diff --git a/docs/variable.rst b/docs/variable.rst index 3fa3b9c1b..62c3286d8 100644 --- a/docs/variable.rst +++ b/docs/variable.rst @@ -13,28 +13,28 @@ Synopsis value - A value is a variable's setting. - Variable can have a default value, that is a setting defined in the :term:`dictionary` structure, + A value is a variable's setting. + Variable can have a default value, that is a setting defined in the :term:`structure file`, or no value at all, then the value needs to be define later by the :term:`operator`. .. discussion:: Discussion - The variable is, by definition, strongly typed. - Rougail uses static type definition and even type inference. - Indeed, the constistency handling system heavyly relies on the type system definition. + The variable is, by definition, strongly typed. + Rougail uses static type definition and even type inference. + Indeed, the constistency handling system heavyly relies on the type system definition. Variables may only be able to store a specified data type. OK, variables are the containers for storing the values. It has something to do with typing. - + But consitency handling system is is not just about strong typing. It is more than that. Names ------ -Variable name +Variable name Variable's associated symbolic name. -.. seealso:: +.. seealso:: Have a look at the :ref:`convention on variable naming link `. @@ -161,7 +161,7 @@ Parameters * - **redefine** `boolean` - - It is possible to define a variable in one :term:`dictionary` and change its behavior in a second :term:`dictionary`. In this case you must explicitly redefine the variable. + - It is possible to define a variable in one :term:`structure file` and change its behavior in a second :term:`structure file`. In this case you must explicitly redefine the variable. **Default value**: `false` * - **exists** @@ -169,14 +169,14 @@ Parameters `boolean` - This attribute does two things: - - creates a variable if it does not exist in another :term:`dictionary` (otherwise do nothing), in this case the value of the attribute must be `true` + - creates a variable if it does not exist in another :term:`structure file` (otherwise do nothing), in this case the value of the attribute must be `true` - in conjunction with the `redefine` attribute set to `true`, only modifies the behavior if it is pre-existing, in which case the attribute's value must be `false`. **Default value**: `null` * - **test** `list` - - The `test` attribute is a special attribute that allows :term:`dictionary` designers to influence a test robot by specifying useful values to test. + - The `test` attribute is a special attribute that allows :term:`structure file` designers to influence a test robot by specifying useful values to test. Concretely, the content of this attribute is recorded in the `information` attribute of the corresponding `Tiramisu` option object.