text corrections

docs/Button.md

@@ -1,4 +1,5 @@
 A *button* is the general term for a key, knob, rotary encoder, slider cursor, or even touch surface on a deck. On a given deck, each element that can be pressed, turned, or slid is a *button*.
+
 The *Button Definition* is a list of parameters that describe what the button will do when it is manipulated and how it will be represented on the deck if the deck can some how represent the state of that button. Here is an example of button definition:
 
 ```
@@ -16,9 +17,13 @@ buttons:
       animation-speed: 2.0
 ```
 
-The following section describe common button definition attributes.
-The button *Activation* page describes attributes specific to what a button will trigger or do when used.
-The button *Representation* page describes attributes specific to the *rendering* of the button on the deck.
+The above definition creates a button named MATER WARNING, that will be placed at position 2 on the deck. The button can be pushed, and when pushed, it will trigger the command `sim/annunciator/clear_master_warning`. The button will display the status of the `AirbusFBW/MasterWarn` value in the simulator. The button is an animation. If the value in the simulator is true (i.e. not zero), the animation will run and display a blinking red text message. The text will blink at a rate of 2 seconds. If the value is false, the button will not display anything.
+
+The following section describe button definition attributes that are common to all buttons, what ever they do and represent.
+
+The button *Activation* page describes attributes specific to *what a button will trigger or do* when used.
+
+The button *Representation* page describes attributes specific to the *feedback* given by the button on the deck, be it an iconic image to display, a led to turn on or off, or a sound to emit.
 
 # Button (Common) Attributes
 
@@ -53,16 +58,16 @@ The label of a button is a short reminder of what the button does. The text of t
 Note: The Button *Label* should not be confused with Button Text. The Label exist for all buttons, and is displayed according to its attributes if the underlying button is capable. The text of the label is defined as a button attribute and is static (cannot be changed dynamically).
 The Button *Text* is a text that is part of the Button representation.
 
-#### Label Color
+### Label Color
 See [[Cockpitdeck Resources#Colors|Colors]].
 
-#### Label Font
+### Label Font
 See [[Cockpitdeck Resources#Fonts|Fonts]].
 
-#### Label Size
+### Label Size
 In pixels. Internally, Cockpitdecks uses 256 × 256 pixel images.
 
-#### Label Position
+### Label Position
 The position of the label is a 2 letter code:
 1. l, c, or r for left, center, or right-justified on the image (horizontal alignment),
 2. t, m, or b, for top, middle, or bottom of the image (vertical alignment).
@@ -78,10 +83,12 @@ The button options parameter is a string of comma separated options. An option i
 Options are, by nature, not indispensable to the button’s activation or rendering but rather add to it to alter behaviour or appearance.
 
 # Button Value
+
 A Button has a value that is maintained and used mainly for representation.
 Please head [[Button Value|here]] for details about a button's value computation.
 
 ## Button Initial Value
+
 A Button can force its first, initial value to set its startup or original state.
 
 ```
@@ -92,9 +99,10 @@ This value is assigned as the button's current value on startup.
 In case of a Button with multiple values, each value has a independant `initial-value` attribute in its own attribute section.
 
 # Button State
+
 Each button maintain its internal state: How many times it is pressed, released, turned clockwise or counter-clockwise, what is it current value, its previous, or last value. State information can be used by Button designer to control the button behavior and its representation.
 
-1. activation_count (number of time button was pressed.)
+1. activation_count (number of time button was «used»)
 2. current_value
 3. previous_value
 

docs/Cockpit.md

@@ -1,15 +1,21 @@
-The Cockpit is the container entity of Cockpitdecks. *For a given aircraft*, it locates deck definitions, loads them and prepares each deck for use with X-Plane.
+The Cockpit is the main container entity of Cockpitdecks.
+
+*For a given aircraft*, it locates deck definitions, loads them and prepares each deck for use with X-Plane. If aircraft is changed in X-Plane, Cockpitdecks is notified and loads the newly loaded aircraft definitions, if any.
 
 # Aircraft Configuration
 
-Decks are particular to an aircraft. Cockpitdeck will look for a folder named `deckconfig` in the X-Plane folder of that aircraft.
+Decks are particular to one aircraft. Cockpitdeck will look for a folder named `deckconfig` in the X-Plane folder of that aircraft. If none is found, it will load a default page, with defaults actions on each deck available to it.
 
-Cockpidecks will first look for a file named `config.yaml` in the `deckconfig` folder. In that file, Cockpitdecks will find all decks connected to the system and available to it. It will also find a few global parameters.
+If a `deckconfig` folder is found in the folder of the aircraft currently used, Cockpidecks will first look for a file named `config.yaml`. In that file, Cockpitdecks will find all decks connected to the system and available to it. It will also find a set of global parameters.
 
 Cockpidecks will also look for a file named `secret.yaml` in the `deckconfig` folder. In that file, Cockpitdeck will find information such as the serial numbers of the deck devices used. Serial numbers are needed to distinguish all decks of a similar type.
 
 Configuration files for decks are all Yaml-formatted files.
 
+# Deckconfig Folder
+
+Here is the overall structure of the files in the `deckconfig` folder.
+
 ```
 XPlaneAircraftFolder
   (...)
@@ -38,17 +44,19 @@ XPlaneAircraftFolder
 ```
 
 The  `deckconfig` folder contains the following files and sub-folders:
-### Resources
+## Resources
 Resources are fonts, icons, other images, wallpapers, documentation, and texts used and related to that aircraft.
-#### Icons
+### Icons
 Folder containing all icon images for that aircraft. Images should be in JPEG or PNG format. Typical icon size is 256 × 256 pixels, RGB(A). Icons are named after their file name without the extension.
-#### Fonts
+### Fonts
 Folder containing specific fonts used for that aircraft.
 Typical fonts include standard, formal font like DIN, icon fonts like FontAwesome or WeatherIcon font, or fancier font like 7-bar LED fonts. Fonts are named by their file name without extension for TrueType fonts. Open Type Fonts need to supply their extension `.otf`.
-#### Docs
+### Docs
 Docs folder may contain documentation files, like explanatory images, and descriptive texts. Simpler text or markdown files are preferred.
-### Layout Folders
-Newt to the the above *resources* folder, there will be one folder per Layout for a deck.
+## Layout Folders
+
+Next to the the above *resources* folder, there will be one folder per Layout for a deck.
+
 [[Layout|Layout folders]] are explained separately.
 
 # Config.yaml File
@@ -106,6 +114,7 @@ A list of deck structure, one per [[Deck|deck]].
 Yaml allow for other attributes in the file. They are ignored by Cockpitdecks. You may include other attributes like aircraft name, ICAO code, descriptions, notes, even change log of your file.
 
 # Secret.yaml File
+
 The secret.yaml file contains the serial numbers of your connected decks.
 If you have more than one deck of the same type (i.e. two Streamdecks, two X-TouchMini, etc.) this file is mandatory to distinguish between the two physical devices. Otherwise, it is optional.
 
@@ -130,7 +139,9 @@ Under the Deck is the Layout. This allow to change a few parameters for each lay
 Under the Layout is the Page, to control page-level specificities, like, for exemple, a specific background color or texture for a special page.
 
 That's it. At the "lowest" level, at the Button level, there are no default global values, just the values the button will use.
-![[hierarchy.png]]
+
+![[hierarchy.png|200]]
+
 This hierarchical organisation is exploited in [[Button Attribute Default Values|default value lookups]].
 
 ## Resources Folder
@@ -164,7 +175,7 @@ This file defines icon fonts. Icon fonts are fonts that are used to display icon
 Defines a few constants that should never be changed. Change at your own risk.
 
 
-> [!ABSTRACT]
+> [!SUMMARY]
 > In summary, a Cockpit is defined for a given X-Plane aircraft.
 > A Cockpit contains one or more Decks. Each Deck represent a physical deck device used to interact with X-Plane. A Deck is assigned a Layout. A Layout is a collection of Pages. Each Page defines what knobs and buttons on the physical deck do, when they are turned or pushed, and what information they displays in return (through images or LEDs), information extracted from X-Plane data and behavior.
 > 

docs/Deck.md

@@ -13,6 +13,7 @@ Each [[Page]]  define the set of buttons on the deck device, what each button do
 In addition to the Pages it contains, a Deck defines deck-level attributes, such as the overall brightness of the device, or how to fill unused or undefined buttons.
 
 # Definition
+
 Decks are declared in the `config.yaml` file in the `deckconfig` folder in the `decks` attribute. The `decks` attributes contains one or more decks as defined by the following attributes:
 
 ## Deck Attributes
@@ -41,7 +42,9 @@ Optional. Default page name in layout. Default to `index`.
 > [!NOTE] The type of Deck defines the "device driver" that will be used to talk to the deck. If a new model of deck appears in the future, it will be necessary to design its "device driver" for Cockpitdecks to use it.
 
 # Deck Layout
-For a given aircraft, a deck has a Layout. The [[Layout]] of a deck is a collection of [[Page|Pages]] that will be used and displayed on the deck device.
+
+For a given aircraft, a deck has a Layout. The [[Layout]] of a deck is a collection of [[Page|Pages]] that will be used and displayed on the deck device for that aircraft.
+
 A Layout is a folder in the `deckconfig` folder.
 
 ```

docs/Extending/New Interactions.md

@@ -2,7 +2,7 @@
 # Core Button
 
 The core [[Button]] class is designed to isolate deck key specifics in two attribute classes:
-1. Activation, that represents the user's interection with the deck, and
+1. Activation, that represents the user's interaction with the deck, and
 2. Representation, that expresses what the deck communicates back to the user.
 
 In addition to these two attributes, the core Button class holds, keeps and maintains a set of other global, generic attributes made available to the two governing attributes.

docs/Layout.md

@@ -1,6 +1,6 @@
 For a given deck, a Layout is a collection of *Pages* that will be displayed on that deck.
 A Layout is a folder, inside the `deckconfig` main folder.
-The Layout is named and addessed by the name of the folder.
+The Layout is named and addressed by the name of the folder.
 
 Layouts were created to cope with different deck models. If you have a set of 30 commands, you can display them all on a 32 key deck. But you have to make two pages of buttons on a 16 key deck. Same button definitions, but two *layouts*.
 
@@ -15,7 +15,7 @@ The Layout folder contains the following files:
 ```
 
 # Config.yaml
-The `config.yaml` file inside a layout folder defines Layout-level attributes.
+The `config.yaml` file inside a layout folder defines Layout-level attributes. The file is optional.
 
 ```
 # This is at layout level
@@ -47,7 +47,7 @@ Optional. Default page name in layout.
 The default value of some attributes (like font, colors, and sizes) is fetched at the Cockpit level if they are not specified at the Layout level.
 
 # Pages
-Other files in the folder are considered as [[Page|Pages]] in the layout.
+Other files in the folder are considered to be [[Page|Pages]] in the layout.
 
 # Default Layout
-If a deck has no layout specified, Cockpitdeck will generate one with one default page that will display a logo image on the deck and use the first available push button to toggle X-Plane Map On or Off.
+If a deck has no layout specified, Cockpitdeck will generate one with one default page that will display a logo image on the deck (if it isi capable of displaying images...) and use the first available push button to toggle X-Plane Map On or Off.

docs/Page.md

@@ -1,7 +1,9 @@
 A Page is a collection of button definitions that will be installed and used on the deck at a given moment.
-A deck displays one Page of buttons and allow end-users to press them to trigger actions. Actions to be performed are defined in the button definition, together with the appearance of the button on the deck. Actions are constrained by the type of push button or encoder. A push button cannot be rotated. The appearance of the button is also constrained by the ability of the deck: Image icon, LED, colored LED, or, sometimes, no display at all.
+
+A deck displays one Page of buttons and allow end-users to press those buttons to trigger actions. Actions to be performed when a button is manipulated are defined in the button definition, together with the appearance of the button on the deck. Actions are constrained by the type of push button or encoder. A push button cannot be rotated. The appearance of the button is also constrained by the feedback ability of the deck: Image icon, LED, colored LED, or, sometimes, no display at all.
 
 ## Attributes
+
 A Page contains the following attributes:
 
 ```
@@ -36,8 +38,10 @@ Whether to fill unused keys with a default button definition as a placeholder.
 The default value of some attributes (like font, colors, and sizes) is fetched at the Layout level if they are not specified at the Page level.
 
 # Buttons
+
 The `buttons` attributes contains all [[Button|button definitions]].
 
 # Default Page
-If no Page is found in the Layout folder, Cockpit deck will create a default page which consists of a logo displayed on the deck (if the deck is capable of displaying images).
+
+If no Page is found in the Layout folder, Cockpit deck will create a default page which consists of a logo displayed on the deck (if the deck is capable of displaying images...).
 The first available button will be programmed to toggle the X-Plane Map On or Off.