Fix typos + polish

readme.md

@@ -6,17 +6,16 @@ It is ported from my QMK configuration, which in turn is heavily inspired by Man
 
 ## Key features
 
-- clean keymap config + unicode support using
+- clean keymap config + easy unicode setup using helper macros from
   [zmk-nodefree-config](https://github.com/urob/zmk-nodefree-config)
-- home-row mods on base layer (with the [perfect configuration](#timeless-homerow-mods),
+- home-row mods on base layer (with the perfect ["timeless" configuration](#timeless-homerow-mods));
-  sticky mods on `Nav` and `Num` layers
+  sticky mods on other layers
 - most symbols can be accessed from the base layer via combos
 - sticky shift on right thumb, double-tap activates caps-word
 - backspace morphs into delete when shifted
-- full numpad-layer with arithmetic operators (`=` via combo) and `Esc`, `Enter`, `Tab`
-  on left hand (can be numlocked via `W + P` combo, ideal for data entry and
-  right-handed mouse)
 - "Greek" layer for mathematical typesetting
+- full numpad-layer with arithmetic operators and `Esc`, `Tab`, `Enter` --- ideal for
+  "data entry" (aka Sudoku :)) and right-handed mouse use, can be numlocked via combo
 
 ![](img/keymap.png)
 
@@ -24,60 +23,61 @@ It is ported from my QMK configuration, which in turn is heavily inspired by Man
 
 Homerow mods [are great](https://precondition.github.io/home-row-mods). But they can
 require some finicky timings: In the most naive version, in order to produce a "mod"
-they must be held longer than `tapping-term-ms`. While in order to produce a "tap", they
+they must be held longer than `tapping-term-ms`. On the other hand, in order to produce
-must be held less than `tapping-term-ms`. This requires very consistent typing speeds
+a "tap", they must be held less than `tapping-term-ms`. This requires very consistent
-that, alas, I do not possess. Hence my quest for a "timeless" HRM configuration. Here's
+typing speeds that, alas, I do not possess. Hence my quest for a "timeless" HRM
-what I have ended up with.
+configuration.
+
+Here's what I have ended up with: A "timeless"[^1] HRM setup with virtually no misfires and
+yet a fluent typing experience with mostly no delays.
 
 Let's suppose for a moment we set `tapping-term-ms` to something ridiculously large, say
 5 seconds. This makes the configuration "timeless". But obviously it creates two
 undesired side-effects: (1) In order to get a "mod" we now have to hold the HRM keys for
 something that feels eternity. (2) In normal typing, when tapping keys, there can be
-long delays between the press of a key and the time it appears on the screen.
+long delays between the press of a key and the time it appears on the screen. Enter my
-Enter my two favorite configuration options:
+two favorite configuration options:
 * To alleviate the first side-effect, I use ZMK's `balanced` flavor, which will produce
   a "hold" if another key is both pressed and released within the tapping-term. Because
-  that is exactly what I normally do with HRMs, there is virtually never a need to wait past my
+  that is exactly what I normally do with HRMs, there is virtually never a need to wait
-  long tapping term (see below for two exceptions).
+  past my long tapping term (see below for two exceptions).
 * To alleviate the typing delay, I use the `global-quick-tap` property, which will
-  immediately resolve HRMs as "tap" when they are pressed
+  immediately resolve HRMs as "tap" when they are pressed shortly *after* another key
-  shortly *after* another key has been tapped. This all but completely
+  has been tapped. This all but completely eliminates the delay when typing. 
-  eliminates the delay when typing. 
 
-This almost perfect, but there's still a few rough edges:
+This is almost perfect, but there's still a few rough edges:
 
 * While rolling keys quickly, I sometimes unintentionally end up with "nested" key
   sequences: `key 1` down, `key 2` down and up, `key 1` up. Given the `balanced` flavor,
   this would falsely register `key 1` as a mod. To prevent this, I use ZMK's "positional
-  hold-tap" feature to force HRMs to always resolved as "tap" when the *next* key
+  hold-tap" feature to force HRMs to always resolve as "tap" when the *next* key is on
-  is on the same side of the keyboard. Problem solved.
+  the same side of the keyboard. Problem solved.
-* In the official ZMK version for positional hold-taps, the check whether the next key
+* ... or at least almost. The official ZMK version for positional-hold-taps performs the
-  is on the same side of the keyboard is done upon *key press*. This is not
+  check whether the next key is on the same side of the keyboard upon *key
-  ideal, because it prevents combining two modifiers on the same hand. To fix this, I
+  press*. This is not ideal, because it prevents combining two modifiers on the same
-  use a small patch that delays the
+  hand. To fix this, I use a small patch that delays the positional-hold-tap decision
-  positional-hold-tap decision until *key release*. This way, multiple mods can be
+  until *key release*. This way, multiple mods can be combined, while I still get the
-  combined, while I still get the benefits of positional-hold-taps when tapping keys. 
+  benefit from positional-hold-taps when tapping keys. There is no PR yet (I am still in
-  There is no PR yet (I am still in an
+  an early testing stage), but if you want to try, this is the [testing
-  early testing stage), but if you want to try, this is the [testing
   branch](https://github.com/urob/zmk/tree/positional-hold-tap-on-release).
 * So far, nothing of the configuration depends on the duration of `tapping-term-ms`. In
   practice, there are two reasons why I don't set it to eternity:
-    1. Sometimes, in rare circumstances, I want to combine a mod with a shortcut-key *on
+    1. Sometimes, in rare circumstances, I want to use a mod with a key *on
-       the same hand* (e.g., when the other hand uses a mouse). Our positional hold-tap
+       the same hand* (e.g., when using the mouse with the other hand). My positional
-       configuration prevents this *within* the tapping term. By setting the tapping
+       hold-tap configuration prevents this *within* the tapping term. By setting the
-       term to something large but not crazy large (I use 280ms), I can use same-hand
+       tapping term to something large but not crazy large (I use 280ms), I can still
-       `mod` + `shortcut` by by holding the mod just for a a while before pressing the
+       use same-hand `mod` + `key` shortcuts by holding the mod for just a little while
-       shortcut-key.
+       before tapping the shortcut-key.
     2. Sometimes, I want to press a modifier without another key (e.g., on Windows,
-       tapping the `Win` key opens the search menu). Since the `balanced` flavour only
+       tapping the `Win` key opens the search menu). Because the `balanced` flavour only
-       kicks in when another key is pressed, this again requires waiting past
+       kicks in when another key is pressed, this also requires waiting past
        `tapping-term-ms`.
 
 Here's my configuration (I use a bunch of [helper
 macros](https://github.com/urob/zmk-nodefree-config) to simplify the syntax, but they
 are not necessary):
 
-```
+```C++
 /* use helper macros to define left and right hand keys */
 #include "../zmk-nodefree-config/keypos_def/keypos_36keys.h"                // keyposition helpers
 #define KEYS_L LT0 LT1 LT2 LT3 LT4 LM0 LM1 LM2 LM3 LM4 LB0 LB1 LB2 LB3 LB4  // left-hand keys
@@ -101,13 +101,13 @@ ZMK_BEHAVIOR(hmr, hold_tap,
     quick-tap-ms = <175>;                // double tapping same key allows for repeating
     global-quick-tap-ms = <150>;         // without PR #1387 use global-quick-tap instead
     bindings = <&kp>, <&kp>;
-    hold-trigger-key-positions = <KEYS_LT THUMBS>;  // include right-hand HRMs for chording
+    hold-trigger-key-positions = <KEYS_L THUMBS>;
 )
 ```
 One last note, the configuration above uses some syntactic sugar introduced in [PR
 #1387](https://github.com/zmkfirmware/zmk/pull/1387), which decouples the
 `quick-tap-ms` timeout from the `global-quick-tap-ms` timeout. Without the PR, one
-can replace `global-quick-tap-ms = <280>` with `global-quick-tap` for a
+can replace `global-quick-tap-ms = <150>` with `global-quick-tap` for a
 similar effect (`global-quick-tap` will use the regular `quick-tap-ms` timeout in this
 case).
 
@@ -133,3 +133,10 @@ and (2) make them easy to remember. Specifically:
 - shortcuts for cut (on `X + D`), copy, and paste on the left-hand side for right-handed
   mouse usage
 
+[^1]: I call it "timeless", because the large tapping-term makes the behavior
+  insensitive to the precise timings. One may say that there is still the `global-quick-tap`
+  timeout in the background. However, with the combination of a large tapping-term and
+  positional-hold-taps, the behavior is *not* actually sensitive to the
+  `global-quick-tap` timing: All it does is to reduce the *delay* in typing. That is, the
+  occasional slow key press past the `global-quick-tap` timeout will *not* result in a
+  misfire, but merely in delay between key input and the time it shows up on the screen.