sync with development enhancements

docs/Button.md

@@ -86,32 +86,36 @@ In case of a Button with multiple values, each value has a separate `initial-val
 
 The `type` attribute of a button determine [[Button Activation|how the button will behave]], what it will do when pressed, turned or slid.
 
-# Button Representation
+## Set-Dataref
 
-(In the picture above, this refer to the pink part of the definition.)
+A button definition can have a `set-dataref` attribute that points at a Dataref name.
 
-The representation of a Button determine [[Button Representation|what and how the button will display]] on the deck device. This depends on the capabilities of the button on the deck: LED, image, coloured led button, sound...
+If present, Cockpitdecks will set the value of that dataref to the value of the button.
 
-The representation of a button is determined by *the presence of a special attribute in the definition of the button*.
+Here is example of use. If a button has a activation type of `updown` with let us say 3 stops, the value of the button can be 0, 1, or 2. Each time the user presses the button the value of the button cycles between those three values.
 
-For example, if a button definition contains an attribute named `annunciator`, the button representation will be an [[Annunciator]]. A button can only define one representation in its definition. Otherwise, a warning is reported and the button is ignored.
+```
+type: updown
+stops: 3
+set-dataref: toliss/NDmodeFO
+```
 
-# Notes for Button Designers
+If there is a `set-dataref` attribute, the current value of the dataref (`toliss/NDmodeFO`) in the simulator will be set to the value of the button: 0, 1, or 2.
 
-## Button Instantiation
+For some activations, the `set-dataref` attribute is a mandatory attribute.
 
-When a button is created, internal meta data are set first. Second, the Activation is installed and initialised. Third, the Representation is installed and initialized, as it may already use some activation information for rendering. Finally, the button is initialised. It will be rendered when the page that contains it is loaded on a deck.
+For some other activations that expects a command to be performed upon activation, the `set-dataref` attribute (or instruction) can be an *alternative* to the command. In other words, the commands that gets executed is very precisely the `set-dataref` instruction.
 
-## Button Validity
+# Button Representation
 
-Each button has a validity function that ensures that all necessary attributes are provided in its definition. If the activation of the button is not valid, its activation function will never be triggered, because of missing or misconfigurated parameters. If its representation is not valid, it will not be rendered on the deck.
+(In the picture above, this refer to the pink part of the definition.)
 
-If a button is not valid, a small red triangle appears in the lower right corner of the key icon if the button is capable of representing it. A small blue triangle appears in the lower right corner of the key icon if Cockpitdecks suspect the button is a placeholder.
+The representation of a Button determine [[Button Representation|what and how the button will display]] on the deck device. This depends on the capabilities of the button on the deck: LED, image, coloured led button, sound...
 
-## Button Description and Inspection
+The representation of a button is determined by *the presence of a special attribute in the definition of the button*. That attribute will determine how the button will be represented.
 
-Each button has an `describe()` method that prints in plain English what the button does and what it renders on the deck.
+For example, if a button definition contains an attribute named `annunciator`, the button representation will be an [[Annunciator]]. A button can only define one representation in its definition. Otherwise, a warning is reported and the button is ignored.
 
-Each button has an `inspect(what: str)` method that exposes internal values and state. The inspect method takes one parameter `what`  that determines what is displayed when invoked.
+Attributes related to the representation of the button are indented under the attributes that names the representation. This is done on purpose to clearly separate attributes dedicated to what the button does (activation), and how it provides feedback to the user (representation).
 
-These methods can be invoked from the [[Button Activations for Developers#Inspect|Inspect]] button activation.
+A Page of 32 buttons 4 rows of 8 buttons) can quickly become quite large and difficult to read. Fortunately, recall that a Page can include other Pages to structure the creation of a layout. For example, it might be advisable to create a « main » page with global settings, and include four sub-pages, one for each row on the deck.

docs/Button/Button Activation.md

@@ -314,11 +314,14 @@ Same as Encoder activation.
 
 # EncoderLongPush
 
+A combination of pushing and turning.
+
 ## Attributes
 
-| Attribute  | Definition                                                                                                                                                                                                                                                                                                                                                    |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `commands` | An EncoderLongPush has 4 commands:<br><br>1. First command  gets executed when encoder is turned clockwise<br>2. Second command gets executed when encoder is turned counterclockwise<br>3. Third command gets executed when encoder is turned clockwise *and pushed*<br>4. Fourth command gets executed when encoder is turned counterclockwise *and pushed* |
+| Attribute  | Definition                                                                                                                                                                                                                                                                                                                                                                |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `commands` | An EncoderLongPush has 4 commands:<br><br>1. First command  gets executed when encoder is turned clockwise<br>2. Second command gets executed when encoder is turned counterclockwise<br>3. Third command gets executed when encoder is first pushed, then turned clockwise<br>4. Fourth command gets executed when encoder is first pushed, then turned counterclockwise |
+|            |                                                                                                                                                                                                                                                                                                                                                                           |
 
 ## State Values
 

docs/Button/Button Attribute Default Values.md

@@ -19,23 +19,27 @@ This hierarchy is very important.
 
 As an example, let us find the value of the `label-color`.
 
-First, the button will perform a direct lookup in its attribute. If it finds a  `label-color` in its attribute, it will use it. If it does not find it, it will as its `default-label-color`. The button will then ask its parent entity for the `default-label-color`.
+First, the button will perform a direct lookup in its attribute. If it finds a  `label-color` in its attribute, it will use it. If it does not find it, it will ask for its `default-label-color`. The button will ask its *parent entity* for the `default-label-color`.
 
 So the Page will search for a `default-label-color` in its attributes. If it finds it, it will use it. If it does not find it, it ask its parent entity.
 
 The Deck will search for a `default-label-color` in its attributes. If it finds it, it will use it. If it does not find it, it ask its parent entity.
 
 Finally, the Cockpit will return a `default-label-color`. If there is no value for the `default-label-color`, Cockpitdecks will issue an error. It simply means that there is no default value for that attribute and that a value *must* be supplied by the user in the definition of the button.
 
-# Day / Night (or light / dark) Theme
+# Theme
 
-Cockpitdecks attempts to provide a day and a night *theme*. The attribute `cockpit` can be set to `day` (or `light`) or `night`(or `dark`).
+Cockpitdecks introduced the concept of color schemes or *Themes*. A theme is an additional parameter (string) that is added to the attribute name being looked up. Let us see in a practical example.
+
+## Day or Night Theme
+
+Cockpitdecks attempts to provide a day and a night *theme*. The attribute `cockpit` can be set to `day` (or `light`) or `night`(or `dark`) to specify which theme to use.
 
 ```yaml
 cockpit-theme: dark
 ```
 
-The effect is that in `night` (or `dark`) theme, default values prefixed with `dark-` will be favored. If no default value prefixed with `dark-` is found, the regular default value is fetched.
+The effect is that in `night` (or `dark`) theme, default values *prefixed* with `dark-` will be favored. If no default value prefixed with `dark-` is found, the regular default value is fetched.
 
 ## Example for label color
 
@@ -62,11 +66,11 @@ Sometimes, configuration values can be specified at different level for a given
 
 ## Cockpitdecks (Application), Cockpits
 
-At the highest level, a Cockpit will start with a set of default values provided in its code.
+At the highest level, a Cockpit will start with a set of default values provided in its internal code.
 
-It will then loads additional parameters in a global resource configuration file. That file is the same for ALL aircrafts. The config.yaml file is located in the home directory of Cockpitdecks software, in the *resources* folder.
+It will then loads additional parameters in a global resource configuration file. That file is the same for ALL aircrafts. The config.yaml file is located in the home directory of Cockpitdecks software, in the *resources* folder. It cannot be changed.
 
-Next, Cockpitdecks will look for an aircraft specific configuration file, in the  deckconfig folder of that aircraft. It will load the config.yaml file of that aircraft, and default values loaded from there will apply to that aircraft only.
+Next, Cockpitdecks will look for an aircraft specific configuration file, in the  deckconfig folder of that aircraft. It will load the config.yaml file of that aircraft, and default values loaded from there will apply to that aircraft only. That configuration file can be used for cockpit designer to specify their requirements and preferences.
 
 ## Decks and Layouts
 

docs/Button/Button Representations/Basic.md

@@ -14,6 +14,8 @@ An image file is loaded on the deck key if it is capable of displaying images.
 
 ## Attributes
 
+### frame
+
 ```yaml
 icon: isi
 frame:
@@ -128,15 +130,15 @@ None
 
 The selection of the text block must be performed by a **formula** and not a dataref.
 
-When a formula is present in the attributes of a button, it is always favored over a list of datarefs, even if the list contains only one dataref. (If there a button uses multiple datarefs and there is no formula, the value that is returned for that button is a diectionary of all dataref values.)
+When a formula is present in the attributes of a button, it is always favored over a list of datarefs, even if the list contains only one dataref. (If there a button uses multiple datarefs and there is no formula, the value that is returned for that button is a dictionary of all dataref values.)
 
 # Multi-Buttons
 
 See [[Multi-Buttons and Mosaic]].
 
 # LED
 
-`led: led
+`led: led`
 
 Turns a single LED light On or Off depending on the button's value.
 

docs/Button/Button Representations/Deck Specific.md

@@ -1,6 +1,7 @@
 # ColoredLed
 
 ColoredLed buttons are color capable led behind a transparent or mask button.
+
 They are either on or off, with a RGB color.
 
 ```
@@ -66,7 +67,7 @@ Larger screens can be used in two different ways:
 - As a whole, unique, larger display surface,
 - As a set of adjacent buttons covering the entire surface.
 
-In the later case, the specificity of the display is not apparent, and resulting buttons are treated as regular keys with iconic image display (with different sizes sometimes.)
+In the later case, the specificity of the display is not apparent, and resulting buttons are treated as regular keys with iconic image display (with different sizes sometimes.) This is called a [[Multi-Buttons and Mosaic|Mosaic]].
 
 When considered as a single larger display, it is difficult to remain generic since each display will have special size, location, and behavior. Cockpitdecks buttons assigned to those specific display are therefore also very specific.
 

docs/Button/Button Representations/Multi-Buttons and Mosaic.md

@@ -79,7 +79,7 @@ Here is an example of definition of a mosaic for the LoupedeckLive left screen.
 
 One Deck Type can define one or more mosaic for its large LCD displays. For example, a 800x100 pixel large LCD can propose a Mosaic of 4 x 200x100 pixels.
 
-If a user prefers an alternate Mosaic of 8 x 100x100 pixels, it is necessary to create another Deck Type, with another name, where the alternate mosaic is expressed, but this can be done.
+If a user prefers an alternate Mosaic of 8 x 100x100 pixels, it is necessary to create another Deck Type, with another name, where the alternate mosaic is expressed.
 
 The same device, whether physical or "virtual" (through a Web Deck), can be declined in several Deck Types to offer a modular representation to Cockpitdecks.
 
@@ -99,7 +99,7 @@ The same device, whether physical or "virtual" (through a Web Deck), can be decl
 
 The activation (`type`) must be `mosaic`. This activation transforms the swipe event into push events.
 
-The representation must be `mosaic`. THe representation collects the representation of each tile and compose the final image that is sent for display.
+The representation must be `mosaic`. The representation collects the representation of each tile and compose the final image that is sent for display.
 
 ## Tiles
 

docs/Button/Button Value.md

@@ -1,16 +1,16 @@
 A button builds its representation from its *value*. The *value* of the button is computed from one or more *dataref* values returned by X-Plane and/or from some *internal state variable* values.
 
-A Button can have 0, 1, or more than one value in the special case of [[Annunciator|annunciators]] or LargeButtons  (A LargeButton  can have two or more buttons represented inside.). Each annunciator part or each button inside a LargeButton has either 0, or 1 value.
+A Button can have 0, 1, or more than one value in the special case of [[Annunciator|annunciators]] or Mosaic  (A Mosaic  can have two or more buttons represented inside.). Each annunciator part or each button inside a Mosaic has either 0, or 1 value.
 
 Each value of a button is either None (no value) or a numeric value (which is most of the time a floating point number). If a button has several values, its value is either a list of values or a dictionary of all individual values, each individual value being None or a number.
 
-Activations and Representations of the button knows how to manage the different values contained in the annunciator or LargeButtons.
+Activations and Representations of the button knows how to manage the different values contained in the annunciator or Mosaic.
 
 # X-Plane Datarefs
 
 A *dataref* is the name of a value used by the X-Plane simulator.
 
-The value can be a string, integer, or float value, either a single value or an array of (same type of) values. A dataref has a name to access it. Names are organized in a folder-like structure (namespace using `/` separator). Some datarefs are read-only, some other can be written and modified.
+The value can be a string, integer, or float value, either a single value or an array of (same type of) values. A dataref has a name to access it. Names are organized in a folder-like structure (namespace using `/` separator). Some datarefs are read-only, some other can be written and modified. Names that start with `sim/` are reserved for the simulator internal use.
 
 #### Examples
 
@@ -20,11 +20,11 @@ The value can be a string, integer, or float value, either a single value or an
 
 There are thousands of datarefs in a running instance of X-Plane. Datarefs drive almost everything in the simulator.
 
-A dataref is always monitored. Its value is fetched from the simulator at regular interval (typically every second). When a dataref's value has changed, all buttons that depend on that dataref are notified to update their appearance.
+When used by a button in Cockpitdecks, the value of a dataref is monitored. Its value is fetched from the simulator at regular interval (typically every second). When a dataref's value has changed, all buttons that depend on that dataref are notified of the change to, for example, update their appearance.
 
-To explore datarefs, there is a handy X-Plane plugin called [DataRefTool](https://datareftool.com). There are also a few web pages that collect, report, and present them so that they can be searched.
+To explore datarefs available in the simulator, there is a handy X-Plane plugin called [DataRefTool](https://datareftool.com). There are also a few web pages that collect, report, and present them so that they can be searched. The plugin allow not only for inspection of datarefs, but also for inspection and discovery of *commands*, strings that can be submitted to the simulator to perform some action.
 
-For simplicity, Cockpitdecks assumes all individual dataref values are floating point numbers or strings (in which case it actually is a list of floating point values representing the ASCII code number of each character in the string.)
+For simplicity, Cockpitdecks assumes all individual dataref values are floating point numbers or strings.
 
 The reason for this is that as today, X-Plane UDP only returns floating point numeric values for requested datarefs.
 
@@ -89,7 +89,7 @@ Internal datarefs can be used as inter-button communication, to set a value in o
 
 # Button «Internal State» Attributes
 
-When a button cannot fetch its representation from X-Plane, it is possible to use some Cockpitdecks internal variables made available through the button *state*. Each button maintain its state, a few internal variables’that can be accessed in formula.
+When a button cannot fetch its representation from X-Plane, it is possible to use some Cockpitdecks internal variables made available through the button *state*. Each button maintain its state, a few internal variables that can be accessed in formula.
 
 Some state variables are generic, and available for almost every buttons, like for instance the number of time a button was activated. Other state variables are activation specific and listed in the [[Button Activation]] page under the activation being used, like for example, the number of times a encoder was turned clockwise.
 
@@ -100,7 +100,7 @@ Numeric internal values are accessible as `${state:variable-name}` in formula.
 ```
 
 ## Activation Attributes and Activation Value
-
+ 
 Most state attributes of a button come from the activation. Each activation has a specific set of state attributes. Among these state attributes, there is a more particular attribute, called the *activation value*, which is the most sensible value produced by the activation.
 
 ## Class Instance Attributes
@@ -233,6 +233,7 @@ formula: ${state:activation_count} 2 %
 ## Activation Value
 
 If a button does not reference a dataref, and has no formula, the activation value can be used if it is available.
+
 ## Multiple Button Values
 
 In case a button has multiple values, each value comes from a part of the button. Each part of the button is independent of other parts of the same button. Each part maintains its single value.