From 42835386107af88b65b5205f47d6b4e232e4cf9a Mon Sep 17 00:00:00 2001
From: "jmding@gmail.com" <jmding@gmail.com>
Date: Sun, 12 Sep 2021 15:31:31 +0000
Subject: [PATCH] add explanation to hold-tap documentation

---
 docs/docs/behaviors/hold-tap.md | 40 +++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/docs/behaviors/hold-tap.md b/docs/docs/behaviors/hold-tap.md
index 6817c602..a9ca5b0b 100644
--- a/docs/docs/behaviors/hold-tap.md
+++ b/docs/docs/behaviors/hold-tap.md
@@ -95,6 +95,46 @@ This example configures a hold-tap that works well for homerow mods:
 
 If this config does not work for you, try the flavor "balanced" with a medium `tapping-term-ms` such as 200ms.
 
+#### Conditional hold-tap and `hold-enabler-keys`
+
+Including `hold-enabler-keys` in your hold-tap behavior definition turns on conditional hold-tap. This causes the hold-tap behavior to only be allowed to produce a hold behavior if the next key pressed is one of the `hold-enabler-keys`. For example, with the following configuration:
+
+```
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+
+/ {
+	behaviors {
+		cht: conditional_hold_tap {
+			compatible = "zmk,behavior-hold-tap";
+			label = "CONDITIONAL_HOLD_TAP";
+			#binding-cells = <2>;
+			flavor = "hold-preferred";
+			tapping-term-ms = <400>;
+			quick-tap-ms = <200>;
+			bindings = <&kp>, <&kp>;
+			hold-enabler-keys = <1>;    // <---[[the W key]]
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+		default_layer {
+			bindings = <
+				&cht LEFT_SHIFT Q        &kp W        &kp E
+			>;
+		};
+	};
+};
+```
+
+The sequence `(cht_down, W_down, W_up, E_down, E_up, cht_up)` produces `WE`, because the conditional hold-tap **IS** permitted to produce a hold behavior, because the next key pressed (the W key in position 1) **IS** one of the hold-enabler-keys.
+
+Meanwhile, the sequence `(cht_down, E_down, E_up, W_down, W_up cht_up)` produces `qew`, because the conditional hold-tap is **NOT** permitted to produce a hold behavior, because the next key pressed (the E key in position 2) is **NOT** one of the hold-enabler-keys.
+
+Conditional hold-taps can be useful with home-row modifiers for example. By setting `hold-enabler-keys` to include only the keys controlled by the opposite hand, conditional hold-taps can prevent one-handed "rolls" from accidentally triggering hold behaviors.
+
 #### Comparison to QMK
 
 The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting in QMK. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`.