Clarity and structure improvements in the shortcuts documentations

content/preferences-settings/shortcuts.md

@@ -46,21 +46,35 @@ If you have an external controller, you can trigger discrete actions by pressing
 
 # anatomy of a shortcut
 
-Shortcuts can consist of up to three key/button presses **of the same key/button** (in a quick sequence).
-So, for example, `E`, `E + E` and `E + E + E` are all valid shortcuts to trigger discrete actions, as well as `E + left-click`, `E + right-click` or `E + E + left-click`.
+The simplest shortcut consists of just one key press (e.g., `E`).
+The same key can be repeated up to three times, so also `E + E` and `E + E + E` are valid, and distinct, shortcuts.
+You can further extend a shortcut with up to three clicks of the same mouse button. So, `E + E + left-click` or `E + right-click + right-click` are also valid shortcuts.
+Finally, if your fingers are very nimble and you really need to go there, you can add either or both of the mouse buttons that you haven't incorporated yet. So, also `E + left-click + middle-click` and `E + E + right-click + right-click + right-click + left-click + middle-click` are valid shortcuts.
+Hence, the most complex shortcut can consist of 8 key/button presses:
+* Three key presses of the same `key`, followed by
+* Three presses of any mouse button, followed by
+* 1 press of each remaining mouse button.
 
-On the contrary, `E + A` is not a valid shortcut, and darktable will interpret it as a two different shortcuts: `E` followed by `A`.
+Your shortcut can include one or more modifiers (`Shift`, `Ctrl` and `Alt`). In this case, the modifier(s) have to be held down while executing the remainder of the shortcut. So, `Ctrl + E + E` means holding down `Ctrl` while pressing `E` twice in a rapid sequence.
 
-Your shortcut can include one or more modifiers (`Shift`, `Ctrl/Cmd` and `Alt/Option`). In this case, the modifier(s) have to be held down while executing the remainder of the shortcut. So, `Ctrl + E + E` means holding down `Ctrl` while pressing `E` twice in a rapid sequence.
+---
+
+**Note:**
+If you are a MacOs user, your shortcuts will use `Cmd` instead of `Ctrl` and `Option` instead of `Alt`.
+
+---
 
 If you are defining a continuous shortcut, then the movement part of the shortcut must be executed while the last key, mouse or controller button is held down.
 
 For example, the shortcut `E + E + pan`, can be activated by pressing `E` twice, holding down `E` on the second press and moving the mouse horizontally. While you are holding down `E`, moving the mouse horizontally will adjust the value associated with the shortcut's action. As you release the `E` key, moving the mouse horizontally will just move the mouse on the screen.
 
+**Triggering multiple shortcuts at once.** Note that `E + A` is not a valid shortcut, and darktable will interpret it as a two different shortcuts: `E` followed by `A`. This is by design, as the system allows one to trigger multiple continuous shortcuts at once.
+For example, if both `E + scroll` and `A + scroll` are mapped to a slider (or if you have fallbacks enabled), then scrolling with the mouse while holding down both `E` and `A` will move both sliders. If you have a series of keys assigned to nodes in a curve (e.g, tone equalizer) this allows you to move multiple nodes in parallel.
+
 **Shortcuts must be unique within a view.**
 A single action may have multiple shortcuts but a single shortcut can only be linked to one action in a given darktable view -- you can't chain actions together except by applying a preset or style. You can, however, set up a single shortcut that does one thing in the lighttable view, say, and another in the darkroom view.
 
-**Additional modifiers.** As mentioned above, the only valid modifiers are the Shift, Ctrl/Cmd and Alt/Option keys on the keyboard. You can define additional keys (or device buttons) as modifiers by assigning keys/buttons to the "global/modifier" action. However, these will merely function as extra Ctrl, Alt or Shift keys -- you cannot create "new" modifiers.
+**Additional modifiers.** As mentioned above, the only valid modifiers are the `Shift`, `Ctrl` and `Alt` keys on the keyboard. You can define additional keys (or device buttons) as modifiers by assigning keys/buttons to the "global/modifier" action. However, these will merely function as extra `Ctrl`, `Alt` or `Shift` keys -- you cannot create "new" modifiers.
 
 ## defining continuous shortcuts
 
@@ -182,7 +196,7 @@ For example, the predefined shortcut `Tab` triggers the action `globals/panels/a
 
 Actions in the "views" section can only be executed from the specified darktable view. As with global actions, most do not have specific _elements_ as they are used to perform one-off operations.
 
-For example, the predefined shortcut `Ctrl/Cmd + B` triggers the action `views/darktable/guide lines/toggle`, which toggles guide lines in the darktable view.
+For example, the predefined shortcut `Ctrl + B` triggers the action `views/darktable/guide lines/toggle`, which toggles guide lines in the darktable view.
 
 ## actions on modules