misc text corrections

devleaks · Nov 7, 2024 · 134e8a7 · 134e8a7
1 parent 7aef69f
commit 134e8a7
Show file tree

Hide file tree

Showing 5 changed files with 56 additions and 16 deletions.
diff --git a/docs/Cockpit.md b/docs/Cockpit.md
@@ -134,4 +134,4 @@ Next to the the above *resources* folder, there will be one folder per Layout fo
 
 # Decks
 
-One of the most important attributes in the main configuration file is the `decks` attribute which defnies all [[cockpitdecks-docs/docs/Deck|decks]] available to Cockpitdecks.
+One of the most important attributes in the main configuration file is the `decks` attribute which defnies all [[Deck|decks]] available to Cockpitdecks.
diff --git a/docs/Concepts.md b/docs/Concepts.md
@@ -1 +1,5 @@
-The following page describe the components of Cockpitdecks and its vocabulary.
+The following page describe the key components of Cockpitdecks and its vocabulary.
+
+# Glossary
+
+[[Glossary|Here]].
diff --git a/docs/Extending/Reference/Glossary.md b/docs/Extending/Reference/Glossary.md
@@ -16,16 +16,32 @@ In Cockpitdecks, a Layout is a collection of pages that can be displayed on a de
 
 Cockpitdecks is the name of the application used to control decks connected to a computer.
 
+# Cockpit
+
+The Cockpit is the main entity of Cockpitdecks that controls most parts of the application, from the start to its termination.
+
 # Activation
 
+An Activation is an action that is executed when interaction occurs on a deck.
+
 # Representation
 
+A Representation is an abstraction of an instruction sent to a deck to change its appearance. It can be turning a LED light on or off, playing a sound, or dynamically generating an iconic image and sending it for display on a deck key.
+
 # Simulator
 
 ## Simulator Data
 
+A Simulator Data is a variable value kept and modified in the simulator. Cockpitdecks expressed interest in receiving a notification when the value of the variable changes. The variable is accessed by its name.
+
 ## Simulator Instruction
 
+A Simulator Instruction is something the simulator software understand to perform an action. Cockpitdecks generate instructions and submit them to the simulation sofwtware for execution.
+
+## Simulator Events
+
+See below.
+
 # Event
 
 An Event is created to notify Cockpitdecks that something occurred.

diff --git a/docs/Installation.md b/docs/Installation.md
@@ -12,7 +12,7 @@ Therefore, Cockpitdecks will work better with the latest production release of X
 
 Same occurs with aircrafts. Aircrafts are pieces of software that are regularly updated. It is a good practice to include the X-Plane and aircraft version information as comments in the `deckconfig` files, to precise which version of X-Plane or an aircraft is required to run properly.
 
-As a practical example, X-Plane recently opened access to internal data through a new channel: [A Web REST API access](https://developer.x-plane.com/article/x-plane-web-api/). This is offered in X-Plane release 12.1.1 or newer. Immediately, Cockpitdecks has taken benefit from this new, simplified mean to access internal values.
+As a practical example, X-Plane recently opened access to internal data through a new channel: [A Web REST API access](https://developer.x-plane.com/article/x-plane-web-api/). This is offered in X-Plane release 12.1.1 or newer. Immediately, Cockpitdecks has taken benefit from this new, simplified mean to access simulator values.
 
 It is good practice to maintain the software you use to the latest, production version. Cockpitdecks is no exception to this advise.
 
@@ -32,7 +32,7 @@ In particular, the X-Plane Cockpitdecks Helper plugin uses and requires the late
 Create a new python environment and activate it. In that environment, issue the pip install command:
 
 ```sh
-pip install 'cockpitdecks[weather,streamdeck] @ git+https://github.com/devleaks/cockpitdecks.git'
+pip install 'cockpitdecks[weather,demoext,streamdeck] @ git+https://github.com/devleaks/cockpitdecks.git'
 ```
 
 ### Cockpitdecks Extension Packages
@@ -45,14 +45,16 @@ Valid installable extension packages (between the `[` `]`, comma separated, no s
 | `streamdeck`  | For Elgato Stream Deck devices                                                                                                                                                      |
 | `loupedeck`   | For Loupedeck LoupedeckLive, LoupedeckLive.s and Loupedeck CT devices                                                                                                               |
 | `xtouchmini`  | For Berhinger X-Touch Mini devices                                                                                                                                                  |
-| `demoext`     | Add a few Loupedeck and Stream Deck+ demo extensions                                                                                                                                |
-| `development` | For developer only, add testing packages and python types                                                                                                                           |
+| `demoext`     | Add a few Loupedeck and Stream Deck+ demo extensions. Recommended.                                                                                                                  |
+| `development` | For Cockpitdecks developer only, adds testing packages and python types. Useless if you do not develop Cockpitdecks software.                                                       |
 
 ## Install Cockpitdecks Helper Plugin
 
 > [!WARNING] Cockpitdecks X-Plane Helper Plugin
 > You can do this step later, but some functions will not work or be available inside Cockpitdecks.
 
+### Why an Additional Plugin?
+
 X-Plane UDP has some shortcomings that prevent some operations with decks.
 
 To circumvent this, Cockpitdecks provides a small python plugin called the Cockpitdecks Helper plugin, that need to be installed into X-Plane. The Cockpitdecks Helper plugin will execute some instructions on behalf of the Cockpitdecks application. Cockpitdecks Helper plugin just need to be installed and will provide its services to Cockpitdecks.
@@ -61,25 +63,25 @@ If not installed, some of the commands inside Cockpitdecks will work properly.
 
 Cockpitdecks Helper plugin is an _in-process_ plugin, running inside X-Plane, while Cockpitdecks is an _out-of-process_ executable running independently of X-Plane.
 
-### Why an Additional Plugin?
+Here are the functions the Cockpitdecks Plugin offers to complement X-Plane UDP access.
 
 #### Long command execution
 
 Some commands cannot be executed directly through UDP. For exemples, commands that have a *start* and an *end* cannot be started or ended though UDP. It is an X-Plane UDP limitation.
 
-To execute long press commands, the **Cockpitdecks Helper** plugin needs to be installed in XPPython3 PythonPlugins folder.
+To execute long press commands, the **Cockpitdecks Helper** plugin needs to be installed in XPPython3 `PythonPlugins` folder.
 
 #### String Datarefs
 
-X-Plane UDP only allows to fetch dataref values one by one. Retrieving a string is a tedious process Bea cause each individual character has to be fetched.
+X-Plane UDP only allows to fetch dataref values one by one. Retrieving a string is a tedious process because each character has to be fetched individually.
 
-To collect string-typed datarefs, the **Cockpitdecks Helper** plugin needs to be installed in XPPython3 PythonPlugins folder. It collects the entire string and then broadcasts it as a whole string, not individual characters.
+To collect string-typed datarefs, the **Cockpitdecks Helper** plugin needs to be installed in XPPython3 `PythonPlugins` folder. It collects the entire string and then broadcasts it as a whole string, not individual characters.
 
 See [[String Datarefs]] for details about this.
 
 ### Cockpitdecks Helper Plugin Installation
 
-Cockpitdecks Helper Plugin is written in the python language. So it needs the [XPPython3](https://xppython3.readthedocs.io/) X-Plane plugin installed. XPPython3 plugin allow for execution of python code inside X-Plane.
+Cockpitdecks Helper Plugin is written in the python language. So it needs the [XPPython3](https://xppython3.readthedocs.io/) X-Plane plugin installed. XPPython3 plugin allow for execution of python code *inside* X-Plane.
 
 Cockpitdecks XPPython3 plugin is located in the
 

diff --git a/docs/Usage.md b/docs/Usage.md
@@ -96,14 +96,30 @@ Make sure the configuration file is setup. When everything is run on the same co
 cockpitdecks-cli
 ```
 
+If you defined a personal environment file:
+
+```sh
+cockpitdecks-cli --env myenv.yaml
+```
+
 Cockpitdecks will immediately start in demonstration mode and listen for X-Plane interaction. If Cockpitdecks detects that X-Plane is running, finds that an aircraft is loaded, and that a Cockpitdecks `deckconfig` folder exists in the folder of that aircraft, Cockpitdecks will load that configuration.
 
 If no configuration is found, Cockpitdecks will listen and interpret X-Plane data but will not load a new configuration.
 
-This mode is fully automatic. If X-Plane is stoped or later restarted, Cockpitdecks will notice it and either wait idle that X-Plane is started, and if X-Plane is running, Cockpitdecks will attempt to load the aircraft configuration, if any.
+This mode is fully automatic. If X-Plane is stopped or later restarted, Cockpitdecks will notice it and either wait idle that X-Plane is started, and if X-Plane is running, Cockpitdecks will attempt to load the aircraft configuration, if any.
 
 Cockpitdecks always attempts to load the current aircraft `deckconfig` configuration, if present. Similarly, the XPPython3 plugin, if installed, will load the corresponding new configuration as well.
 
+## Forced Configuration
+
+May be thhe aircraft loaded in X-Plane has no Cockpitdecks configuration but still, a configuration need to be loaded. The command-line interface can help:
+
+```sh
+cockpitdecks-cli --env myenv.yaml folder-where-there-is-a-config --fixed
+```
+
+The above command will look for a `deckconfig` folder in the folder supplied on the command line. The `--fixed` flag indicates that Cockpitdecks should not try to load another configuration in case the folder loaded (the one supplied on the command line) and the folder of the aircraft used in the simulator do not match.
+
 ## Cockpidecks and X-Plane Run on Different Computer
 
 In this case, it is not possible for Cockpitdecks to locate aircraft configuration files since they probably are on the remote computer. A set of configuration file will need to be supplied to Cockpitdecks on the command line to start with. (If no folder is supplied, Cockpitdecks will start in demonstration mode. See above.)
@@ -112,7 +128,7 @@ In this case, it is not possible for Cockpitdecks to locate aircraft configurati
 cockpitdecks-cli aircrafts/A21N --fixed
 ```
 
-Cockpitdecks will start and load the configuration in `aircrafts/A21N/deckcockpit`. Cockpitdecks will attempt to connect to X-Plane.
+Cockpitdecks will start and load the configuration in `aircrafts/A21N/deckconfig`, then Cockpitdecks will attempt to connect to X-Plane.
 
 The optional `--fixed` flag ensure that Cockpitdecks will not reload a new aircraft if it detects the aircraft in X-Plane has changed or does not correspond to the aircraft currently being used.
 
@@ -140,12 +156,14 @@ To report an issue with Cockpitdecks, you should always include the `XPPython3.l
 
 The level of information produced in the file is controlled by the logging level parameter. (info=some information and warnings, debug=a lot of information for debugging purpose, your XPPython3.log file may grow quite large.) The parameter is available at the global plugin level (the entire plugin will report all messages), or can be set at a Cockpitdecks internal module level to pin point issues.
 
-Cockpitdecks is *stateless*. If we except internal statistics, Cockpitdecks does not maintain any state variable of a situation. Therefore, at any time, it is possible to stop and restart it. Should a problem persists, please file an issue on github with necessary information to reproduce it.
+Cockpitdecks is *stateless*. If we except its internal statistics, Cockpitdecks does not maintain any state variable of a situation. Therefore, at any time, it is possible to stop and restart it. Should a problem persists, please file an issue on github with necessary information to reproduce it.
 
 # Termination
 
-Cockpitdecks is designed to terminates cleanly. All requested datarefs monitoring are cancelled, connections are closed, all threads are terminated and joined cleanly. However, it may sometimes take a few seconds before a thread terminates. For example, if a thread is meant to run every 30 seconds, it may be necessary to wait a full 30 seconds before the thread notices the termination request and quits. Longer threads (above 30 seconds or a minute) check periodically for termination request. Cockpitdecks should always terminate cleanly.
+To terminate Cockpitdecks, press **a single** ++ctrl+c++ to stop Cockpitdecks client application.
+
+Cockpitdecks is designed to terminates cleanly. All requested datarefs monitoring are cancelled, connections are closed, all threads are terminated and joined cleanly. However, it may sometimes take a few seconds before a thread terminates. For example, if a thread is meant to run every 30 seconds, it may be necessary to wait a full 30 seconds before the thread notices the termination request and quits. Longer threads (above 30 seconds or a minute) check periodically for termination request. Cockpitdecks should always terminate cleanly to release resources it controls from the simulator.
 
 If necessary, there is an [[Button Activations for Developers#Stop|activation]] that can be assigned to a button to stop Cockpitdecks.
 
-If necessary, pressing ++ctrl+c++ several time in the main window will stop Cockpitdecks completely right away.
+If necessary, or blocked, pressing ++ctrl+c++ several time in the main window will stop Cockpitdecks completely right away.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -134,4 +134,4 @@ Next to the the above resources folder, there will be one folder per Layout fo

		# Decks

		One of the most important attributes in the main configuration file is the `decks` attribute which defnies all [[cockpitdecks-docs/docs/Deck\|decks]] available to Cockpitdecks.
		One of the most important attributes in the main configuration file is the `decks` attribute which defnies all [[Deck\|decks]] available to Cockpitdecks.