Expand documentation

readme.md

@@ -4,7 +4,7 @@ This is my personal [ZMK firmware](https://github.com/zmkfirmware/zmk/) configur
 It consists of a 34-keys base layout that is re-used for various boards, including my
 Corneish Zen and an Advantage 360 pro.
 
-## *Key* features
+## Highlights
 
 - clean keymap + unicode setup using helper macros from
   [zmk-nodefree-config](https://github.com/urob/zmk-nodefree-config)
@@ -13,21 +13,14 @@ Corneish Zen and an Advantage 360 pro.
   larger boards by padding it via a modular structure of "extra keys"
 - ["timer-less" homerow mods](#timeless-homerow-mods) 
 - combos replacing the symbol layer
-- a smart-layer implementation for ZMK that automatically toggles the numbers
+- smart numbers and smart mouse layers that automatically toggle off when done
-  layer
+- sticky shift on right thumb, double-tap (or shift + tap)[^1] activates caps-word
-- long-pressing the arrow-cluster yields home, end, begin/end of document, and
+- arrow-cluster doubles as <kbd>home</kbd>, <kbd>end</kbd>, <kbd>begin/end of
-  fwd/bwd-delete words
+  document</kbd> on long-press
-- sticky shift on right thumb, double-tap (or shift + tap)[^1] activates
+- more intuitive shift-actions: <kbd>, ;</kbd>, <kbd>. :</kbd> and <kbd>? !</kbd>
-  caps-word
-- <kbd>shift</kbd> + <kbd>,</kbd> morphs into <kbd>;</kbd>  and
-  <kbd>shift</kbd> + <kbd>.</kbd> morphs into <kbd>;</kbd> (freeing up the
-  right pinky for <kbd>? / !</kbd>)
-- <kbd>shift</kbd> + <kbd>ctrl</kbd> + <kbd>,</kbd> morphs into <kbd><</kbd>
-  and <kbd>shift</kbd> + <kbd>ctrl</kbd> + <kbd>.</kbd> morphs into
-  <kbd>></kbd>
 - <kbd>shift</kbd> + <kbd>space</kbd> morphs into <kbd>dot</kbd> →
   <kbd>space</kbd> → <kbd>sticky-shift</kbd>
-- "Greek" layer for mathematical typesetting (activated via sticky-layer combo)
+- "Greek" layer for mathematical typesetting (activated as sticky-layer via a combo)
 - modified Github Actions workflow that recognizes git-submodules
 - automated
   [build-scripts](https://github.com/urob/zmk-config/tree/main/scripts#readme)
@@ -147,14 +140,19 @@ PRs, you might find this [ZMK-centric introduction to
 Git](https://gist.github.com/urob/68a1e206b2356a01b876ed02d3f542c7) helpful.
 
 
-## Combo setup
+## Using combos instead of a symbol layer
 
-My layout makes heavy use of combos. Thanks to `global-quick-tap` for combos
+I am a big fan of combos for all sort of things. In terms of comfort, I much prefer them
-(introduced in above mentioned PR #1387), combo misfires are rare, even when
+over accessing layers that involve lateral thumb movements to be activated, especially
-rolling keys. Most of my combos are bind to symbols, replacing the usual
+when switching between different layers in rapid succession.
-symbols layer seen on many sub-40 keyboard layouts. The combos are designed so
+
-as to put the most used symbols in easy-to-access locations while also making
+One common concern about overloading the layout with combos is that they lead to
-them easy to remember. Specifically:
+misfires. Fortunately, the above-mentioned PR #1387, also adds a `global-quick-tap` option 
+for combos, which in my experience all but completely eliminates the problem -- even
+when rolling keys on the home row!
+
+My combo layout aims place the most used symbols in easy-to-access
+locations while also making them easy to remember. Specifically:
 
 - the top vertical-combo row matches the symbols on a standard numbers row
   (except `+` and `&` being swapped)
@@ -162,37 +160,70 @@ them easy to remember. Specifically:
   aligns with superscript `^`; minus `-` aligns with `+`; division `/` aligns
   with multiplication `*`; logical-or `|` aligns with logical-and `&`)
 - parenthesis, braces, brackets are set up symmetrically as horizontal combos
-- cut (on `X + D`), copy, and paste are on the left side for one-handed mouse
+- left-hand side combos for `tap`, `esc`, `enter`, `cut` (on <kbd>X</kbd> + <kbd>D</kbd>),
-  use
+  `copy` and `paste` that go well with right-handed mouse usage
-- `L + Y` activates Greek layer for the next key press, `L + U + Y` activates the shifted
+- <kbd>L</kbd> + <kbd>Y</kbd> switches to the Greek layer for a single key
-  Greek layer the next key
+  press, <kbd>L</kbd> + <kbd>U</kbd> + <kbd>Y</kbd> activates one-shot shift in
-- `tap`, `esc`, `enter` are on horizontal combos
+  addition
+- <kbd>W</kbd> + <kbd>P</kbd> activates the smart mouse layer
 
-## Experimental changes
+## Smart layers and other gimmicks
 
-- I recently reduced my core layout to 34 keys. Backspace and Delete are now on
+##### Numword
-  my Navigation-layer. To make room for these keys, I have added hold-taps to
+
-  the arrow cluster, which now double as Home/End and Beginning/End of
+Inspired by Jonas Hietala's
-  document. I really like the new navigation cluster and will likely keep it in
-  one way or another
-- Inspired by Jonas Hietala's
 [Numword](https://www.jonashietala.se/blog/2021/06/03/the-t-34-keyboard-layout/#where-are-the-digits)
 for QMK, I implemented my own version of [Smart-layers for
 ZMK](https://github.com/zmkfirmware/zmk/pull/1451). It is triggered via a
-    single tap on my Num-key (holding the key will activate the num layer as
+single tap on "Smart-Num". Numword continues to be activated as long as I
-    usual without triggering Numword). Similar to Capsword, Numword continues
+type numbers, and deactivates automatically on any other keypress (holding it activates 
-    to be activated as long as I type numbers, and deactivates automatically on
+a non-sticky num layer).
-    any other keypress. I found that I use Numword for most of my numbers
+
-    typing. For single digits, it effectively is a sticky-layer, but
+After using Numword for about 6 months now, I have been overall very happy with it. When
-    importantly I can also use it for multiple digits. The only case where it
+typing single digits, it effectively is a sticky-layer but with the added advantage that 
-    doesn't deactivate automatically is where immediately after a digit I would
+I can also use it to type multiple digits. 
-    type any of the letters on which my numpad is located (WFPRSTXCD), which is
+
-    rare, but does happen. For these cases I have a CANCEL key on my Nav layer
+The main downside is that if a sequence of numbers is *immediately* followed by any of the
-    that cancels both Numword and Capsword.
+letters on which my numpad is located (WFPRSTXCD), then the automatic deactivation won't
-- Since the switch to 34 keys, I freed up the tap-position on my left-most
+work. But this is rare -- most number sequences are terminated by `space`, `return` or some form
-  thumb key. For now I added a secondary Bspc, but I am still searching for a
+of punctuation/delimination. To deal with the rare cases where they aren't, there is a 
-  better use. (I tried adding Repeat here but I found that it doesn't work well
+`CANCEL` key on the navigation-layer that deactivates Numword, Capsword and Smart-mouse.
-  adjacent to space, which requires to much lateral thumb-movements)
+
+##### Smart-Mouse
+
+Similarly to Numword, I have a smart-mouse layer (activated by comboing
+<kbd>W</kbd> + <kbd>P</kbd>), which replaces the navigation cluster with
+scroll and mouse-movements, and replaces the right thumbs with mouse buttons.
+Pressing any other key automatically deactivates the layer.
+
+##### Capsword
+
+My right thumb triggers three variations of shift: Tapping yields
+sticky-shift (used to capitalize alphas), holding activates a regular shift, and
+double-tapping (or equivalently shift + tap) activates ZMK's Caps-word behavior.
+
+One minor technical detail: While it would be possible to implement the double-tap functionality
+as a tap-dance, this would add a delay when using single taps. To avoid the delays, I 
+instead implemented the double-tap functionality as a mod-morph.
+
+##### Multi-purpose Navigation cluster
+
+To economize on keys, I am using hold-taps on my navigation cluster, which yield `home`, `end`,
+`begin/end of document`, and `delete word forward/backward` on long-presses.
+
+##### Swapper
+
+I am using [Nick Conway](https://github.com/nickconway)'s fantastic
+[tri-state](https://github.com/zmkfirmware/zmk/pull/1366) behavior for a
+one-handed Alt-Tab switcher (`PWin` and `NWin`).
+
+##### Repeat
+
+I recently switched to 25g-chocs on one of my keyboards. I already was a big fan of 
+combos prior to that (even with heavy MX-switches). But with the light chocs, I find 
+that I can now even use them for regular typing. While I haven't yet tried placing alphas 
+on combos, I am currently experimenting with a `repeat` combo on my home row that I 
+use to make writing double-letter words more fun.
 
 ## Issues and workarounds
 
@@ -202,22 +233,29 @@ any functionality (to the contrary, I found that ZMK supports many features
 natively that would require complex user-space implementations in QMK). Below
 are a few remaining issues:
 
-- ZMK does not yet support tap-only combos
+- ZMK does not yet support "tap-only" combos
-  ([#544](https://github.com/zmkfirmware/zmk/issues/544)). Workaround: pause
+  ([#544](https://github.com/zmkfirmware/zmk/issues/544)). As a workaround, one
-  briefly when chording multiple HRMs together on positions that otherwise would trigger
+  can pause briefly when chording multiple HRMs together on positions that
-  a combo.
+  otherwise would trigger a combo. But this is at the top of my ZMK-wishlist.
-- OS sleep is not yet implemented ([#1077](https://github.com/zmkfirmware/zmk/issues/1077)).
+- Another item on my wishlist are adaptive keys
-  Workaround: use sleep-macro instead.
+  ([#1624](https://github.com/zmkfirmware/zmk/issues/1624)). This would open
-- `&bootloader` doesn't work with Planck_rev6
+  the door for things like <kbd>space</kbd><kbd>space</kbd> becoming
-  ([#1086](https://github.com/zmkfirmware/zmk/issues/1086)). Workaround: Manually press
+  <kbd>.</kbd><kbd>space</kbd><kbd>sticky-shift</kbd>. (Using tap-dance isn't
-  reset-button.
+  really an option here due to the delay it adds)
+- A minor thing is that ZMK doesn't yet support any keys on the
+  desktop-user-page; e.g., OS sleep
+  ([#1077](https://github.com/zmkfirmware/zmk/issues/1077),
+  [#1535](https://github.com/zmkfirmware/zmk/issues/1535))
+- Very minor: `&bootloader` doesn't work with stm32 boards like the Planck
+  ([#1086](https://github.com/zmkfirmware/zmk/issues/1086))
 
 [^1]: Really what's happening is that `Shift` + my right home-thumb morph into
   caps-word. This gives me two separate ways of activating it: (1) Holding the
   homerow-mod shift on my left index-finger and then pressing my right home-thumb, which
   is my new preferred way. Or, (2) double-tapping the right home-thumb, which also works
   because the first tap yields sticky-shift, activating the mod-morph upon the second
-  tap.
+  tap. But even when only activating via double-tapping, this implementation is advantageous
+  compared to using tap-dance as it does not create any delay when single-tapping the key.
 
 [^2]: I call it "timer-less", because the large tapping-term makes the behavior
   insensitive to the precise timings. One may say that there is still the