From db741eb055b39f7d59abee8cc35abd36209b78a9 Mon Sep 17 00:00:00 2001
From: Josh Klar <josh@klar.sh>
Date: Mon, 5 Nov 2018 21:33:42 -0800
Subject: [PATCH] Add some documentation
---
docs/tapdance.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 61 insertions(+)
create mode 100644 docs/tapdance.md
diff --git a/docs/tapdance.md b/docs/tapdance.md
new file mode 100644
index 0000000..0f79078
--- /dev/null
+++ b/docs/tapdance.md
@@ -0,0 +1,61 @@
+# Tap Dance
+
+Tap dance is a way to allow a single physical key to work as multple logical
+keys / actions without using layers. With basic tap dance, you can trigger these
+"nested" keys or macros through a series of taps of the physical key within a
+given timeout.
+
+The resulting "logical" action works just like any other key - it can be pressed
+and immediately released, or it can be held. For example, let's take a key
+`KC.TD(KC.A, KC.B)`. If the tap dance key is tapped and released once quickly,
+the letter "a" will be sent. If it is tapped and released twice quickly, the
+letter "b" will be sent. If it is tapped once and held, the letter "a" will be
+held down until the tap dance key is released. If it is tapped and released once
+quickly, then tapped and held (both actions within the timeout window), the
+letter "b" will be held down until the tap dance key is released.
+
+To use this, you may want to define a `tap_time` value in your keyboard
+configuration. This is an integer in milliseconds, and defaults to `300`.
+
+You'll then want to create a sequence of keys using `KC.TD(KC.SOMETHING,
+KC.SOMETHING_ELSE, MAYBE_THIS_IS_A_MACRO, WHATEVER_YO)`, and place it in your
+keymap somewhere. The only limits on how many keys can go in the sequence are,
+theoretically, the amount of RAM your MCU/board has, and how fast you can mash
+the physical key. Here's your chance to use all that button-mash video game
+experience you've built up over the years.
+
+**NOTE**: Currently our basic tap dance implementation has some limitations that
+are planned to be worked around "eventually", but for now are noteworthy:
+
+- The behavior of momentary layer switching within a tap dance sequence is
+ currently "undefined" at best, and will probably crash your keyboard. For now,
+ we strongly recommend avoiding `KC.MO` (or any other layer switch keys that
+ use momentary switch behavior - `KC.LM`, `KC.LT`, and `KC.TT`)
+
+- Super fancy stuff like sending a keypress only when the leader key is released
+ (perhaps based on how long the leader key was held) is **unsupported** - an
+ example usecase might be "tap for Home, hold for Shift"
+
+Here's an example of all this in action:
+
+```python
+# user_keymaps/some_silly_example.py
+from kmk.boards.klarank import Firmware
+from kmk.keycodes import KC
+from kmk.macros.simple import send_string
+
+keyboard = Firmware()
+
+keyboard.tap_time = 750
+
+EXAMPLE_TD = KC.TD(
+ KC.A, # Tap once for "a"
+ KC.B, # Tap twice for "b"
+ # Tap three times to send a raw string via macro
+ send_string('macros in a tap dance? I think yes'),
+ # Tap four times to toggle layer index 1
+ KC.TG(1),
+)
+
+keyboard.keymap = [[ ...., EXAMPLE_TD, ....], ....]
+```