Merge remote-tracking branch 'origin/master' into develop

1 files changed, 115 insertions, 0 deletions

diff --git a/docs/tap_hold.md b/docs/tap_hold.md
index d206c10cc5..39fa84a9f3 100644
--- a/docs/tap_hold.md
+++ b/docs/tap_hold.md
@@ -126,6 +126,61 @@ The code which decides between the tap and hold actions of dual-role keys suppor
 
 Note that until the tap-or-hold decision completes (which happens when either the dual-role key is released, or the tapping term has expired, or the extra condition for the selected decision mode is satisfied), key events are delayed and not transmitted to the host immediately.  The default mode gives the most delay (if the dual-role key is held down, this mode always waits for the whole tapping term), and the other modes may give less delay when other keys are pressed, because the hold action may be selected earlier.
 
+### Default Mode
+Example sequence 1 (the `L` key is also mapped to `KC_RGHT` on layer 2):
+
+```
+             TAPPING_TERM
+  +---------------|--------------------+
+  | +-------------|-------+            |
+  | | LT(2, KC_A) |       |            |
+  | +-------------|-------+            |
+  |               | +--------------+   |
+  |               | | KC_L         |   |
+  |               | +--------------+   |
+  +---------------|--------------------+
+```
+The above sequence would send a `KC_RGHT`, since `LT(2, KC_A)` is held longer than the `TAPPING_TERM`.
+
+---
+
+Example sequence 2 (the `L` key is also mapped to `KC_RGHT` on layer 2):
+
+```
+                           TAPPING_TERM
+  +-----------------------------|------+
+  | +---------------+           |      |
+  | | LT(2, KC_A)   |           |      |
+  | +---------------+           |      |
+  |            +--------------+ |      |
+  |            | KC_L         | |      |
+  |            +--------------+ |      |
+  +-----------------------------|------+
+```
+The above sequence will not send `KC_RGHT` but `KC_A` `KC_L` instead, since `LT(2, KC_A)` is not held longer than the `TAPPING_TERM`.
+
+---
+
+Example sequence 3 (Mod Tap):
+
+```
+                         TAPPING_TERM
+  +---------------------------|--------+
+  | +-------------+           |        |
+  | | SFT_T(KC_A) |           |        |
+  | +-------------+           |        |
+  |       +--------------+    |        |
+  |       | KC_X         |    |        |
+  |       +--------------+    |        |
+  +---------------------------|--------+
+```
+Based previous examples, you might have expected the output of the above sequence to be `KC_A` `KC_X`
+since `SFT_T(KC_A)` is NOT held longer than the `TAPPING_TERM`.
+However, the actual output would be capital `X` (`SHIFT` + `x`) due to reasons
+explained under [Ignore Mod Tap Interrupt](#ignore-mod-tap-interrupt).
+
+
+
 ### Permissive Hold
 
 The “permissive hold” mode can be enabled for all dual-role keys by adding the corresponding option to `config.h`:
@@ -145,6 +200,18 @@ An example of a sequence which is affected by the “permissive hold” mode:
 - `KC_L` Up
 - `LT(2, KC_A)` Up
 
+```
+                         TAPPING_TERM   
+  +---------------------------|--------+
+  | +----------------------+  |        |
+  | | LT(2, KC_A)          |  |        |
+  | +----------------------+  |        |
+  |    +--------------+       |        |
+  |    | KC_L         |       |        |
+  |    +--------------+       |        |
+  +---------------------------|--------+
+```
+
 Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system.  With the `PERMISSIVE_HOLD` option enabled, the Layer Tap key is considered as a layer switch if another key is tapped, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2). We could describe this sequence as a “nested press” (the modified key's key down and key up events are “nested” between the dual-role key's key down and key up events).
 
 However, this slightly different sequence will not be affected by the “permissive hold” mode:
@@ -154,6 +221,18 @@ However, this slightly different sequence will not be affected by the “permiss
 - `LT(2, KC_A)` Up
 - `KC_L` Up
 
+```
+                         TAPPING_TERM   
+  +---------------------------|--------+
+  | +-------------+           |        |
+  | | LT(2, KC_A) |           |        |
+  | +-------------+           |        |
+  |       +--------------+    |        |
+  |       | KC_L         |    |        |
+  |       +--------------+    |        |
+  +---------------------------|--------+
+```
+
 In the sequence above the dual-role key is released before the other key is released, and if that happens within the tapping term, the “permissive hold” mode will still choose the tap action for the dual-role key, and the sequence will be registered as `al` by the host. We could describe this as a “rolling press” (the two keys' key down and key up events behave as if you were rolling a ball across the two keys, first pressing each key down in sequence and then releasing them in the same order).
 
 ?> The `PERMISSIVE_HOLD` option also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers both the “nested press” and “rolling press” sequences like shown above as a modifier hold, not the tap action.  If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `PERMISSIVE_HOLD` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host.
@@ -198,6 +277,18 @@ An example of a sequence which is affected by the “hold on other key press”
 - `LT(2, KC_A)` Up
 - `KC_L` Up
 
+```
+                         TAPPING_TERM
+  +---------------------------|--------+
+  | +-------------+           |        |
+  | | LT(2, KC_A) |           |        |
+  | +-------------+           |        |
+  |       +--------------+    |        |
+  |       | KC_L         |    |        |
+  |       +--------------+    |        |
+  +---------------------------|--------+
+```
+
 Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system.  With the `HOLD_ON_OTHER_KEY_PRESS` option enabled, the Layer Tap key is considered as a layer switch if another key is pressed, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2).
 
 ?> The `HOLD_ON_OTHER_KEY_PRESS` option also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers the “rolling press” sequence like shown above as a modifier hold, not the tap action.  If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `HOLD_ON_OTHER_KEY_PRESS` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host.
@@ -245,6 +336,18 @@ An example of a sequence which will be affected by the `IGNORE_MOD_TAP_INTERRUPT
 - `SFT_T(KC_A)` Up
 - `KC_X` Up
 
+```
+                         TAPPING_TERM
+  +---------------------------|--------+
+  | +-------------+           |        |
+  | | SFT_T(KC_A) |           |        |
+  | +-------------+           |        |
+  |       +--------------+    |        |
+  |       | KC_X         |    |        |
+  |       +--------------+    |        |
+  +---------------------------|--------+
+```
+
 Normally, this would send a capital `X` (`SHIFT`+`x`), even if the sequence is performed faster than the `TAPPING_TERM`.  However, if the `IGNORE_MOD_TAP_INTERRUPT` option is enabled, the `SFT_T(KC_A)` key must be held longer than the `TAPPING_TERM` to register the hold action.  A quick tap will output `ax` in this case, while a hold will still output a capital `X` (`SHIFT`+`x`).
 
 However, if the `HOLD_ON_OTHER_KEY_PRESS` option is enabled in addition to `IGNORE_MOD_TAP_INTERRUPT`, the above sequence will again send a capital `X` (`SHIFT`+`x`) even if performed faster that the `TAPPING_TERM`.  The difference from the default configuration is that by default the host will receive the key events only after the `SFT_T(KC_A)` key is released, but with the `HOLD_ON_OTHER_KEY_PRESS` option the host will start receiving key events when the `KC_X` key is pressed.
@@ -327,6 +430,18 @@ Holding and releasing a dual function key without pressing another key will resu
 
 For instance, holding and releasing `LT(2, KC_SPC)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPC` instead.
 
+```
+               TAPPING_TERM
+  +-----------------|------------------+
+  | +---------------|-------+          |
+  | | LT(2, KC_SPC) |       |          |
+  | +---------------|-------+          |
+  |                 |                  |
+  |                 |                  |
+  |                 |                  |
+  +-----------------|------------------+
+```
+
 For more granular control of this feature, you can add the following to your `config.h`:
 
 ```c