Update documentation

README.md

@@ -240,27 +240,27 @@ If you want to check that everything builds before flashing your keyboard, you c
 tree $(nix build --no-link --print-out-paths) 2>/dev/null
 ```
 
-    /nix/store/zjfinbmavajq6xh492zdprhkhnfj4yyw-shajra-keyboards-ci
+    /nix/store/j47qlcp9yqlsma791zr6dadbys956wcx-shajra-keyboards-ci
     ├── build-ergodoxez-builtin-shajra-flash -> /nix/store/15knkvn4hkix0vn1dsyk9ffzqnkl32nk-ergodoxez-builtin-shajra-flash
     ├── build-ergodoxez-builtin-shajra-hex -> /nix/store/mrkig8c5jkhgchh3l3bsl8wj17jz77n7-ergodoxez-builtin-shajra.hex
     ├── build-ergodoxez-factory-flash -> /nix/store/kknpgd1japddjn8rl06n91x42ly7q4i8-ergodoxez-factory-flash
     ├── build-ergodoxez-factory-hex -> /nix/store/cyp9izs14157idkyrbp6j52ym98j6h9h-ergodoxez-factory.hex
-    ├── build-model01-builtin-shajra-flash -> /nix/store/835qi2zb9m0dala6x7gmkpmxlmgd97xx-model01-builtin-shajra-flash
-    ├── build-model01-builtin-shajra-hex -> /nix/store/416x1s5v5pdki043nhlr8jqf0waf8j0d-model01-builtin-shajra-hex
+    ├── build-model01-builtin-shajra-flash -> /nix/store/yhj7rq7kc65ylr96ywsfbqm532j0jldv-model01-builtin-shajra-flash
+    ├── build-model01-builtin-shajra-hex -> /nix/store/c93lf9xy6kiwjnifbg4v6q0bxsrr60n6-model01-builtin-shajra-hex
     ├── build-model01-factory-flash -> /nix/store/r7fcyzxqix123jagi9lvyzsvlg5qilr5-model01-factory-flash
     ├── build-model01-factory-hex -> /nix/store/gwxx9i59daqj1gq06biikvsyqv4a05rb-model01-factory-hex
-    ├── build-model100-builtin-shajra-flash -> /nix/store/0jp1x1zmz00wkwyi7q7jxcvz7k9pwh3q-model100-builtin-shajra-flash
-    ├── build-model100-builtin-shajra-hex -> /nix/store/my83qz6czp7rkvg82q091cdkk95dm1v4-model100-builtin-shajra-hex
+    ├── build-model100-builtin-shajra-flash -> /nix/store/g9bk5mwwj3ay01yh3a6rcmvsbbgrg1p9-model100-builtin-shajra-flash
+    ├── build-model100-builtin-shajra-hex -> /nix/store/c8ggagg9wrx77qvhy8zamnnlazfxmc23-model100-builtin-shajra-hex
     ├── build-model100-factory-flash -> /nix/store/lqq6jq9xyjb1sgnl0yjq9a1q6vlw6z0d-model100-factory-flash
     ├── build-model100-factory-hex -> /nix/store/a3197a8k04yzisrcxrszs6d7653krrp2-model100-factory-hex
     ├── build-moonlander-builtin-shajra-flash -> /nix/store/z19vx9vqz17lw69sg27p521yk31j1bmf-moonlander-builtin-shajra-flash
     ├── build-moonlander-builtin-shajra-hex -> /nix/store/hrajvgijrpk8zk5rs08l80ds2z67vdwz-moonlander-builtin-shajra.bin
     ├── build-moonlander-factory-flash -> /nix/store/z7bg73d94z645s2788vm6hw6hqc2400s-moonlander-factory-flash
     ├── build-moonlander-factory-hex -> /nix/store/r5d6hfhfg7ycpsag0l83mldmpv632rxi-moonlander-factory.bin
-    ├── flash-ergodoxez -> /nix/store/hc815q8svfsnfc9rizjhqqwz0fssr2cy-flash-ergodoxez
-    ├── flash-model01 -> /nix/store/xk8wp76hryfqc6gzrwkz7h2mj5yqx1hm-flash-model01
-    ├── flash-model100 -> /nix/store/1pkqq2hal1zzgmimmxvm645z2n0smvkx-flash-model100
-    ├── flash-moonlander -> /nix/store/qscisa57cqmcjaxgahdk5xni0074rzm0-flash-moonlander
+    ├── flash-ergodoxez -> /nix/store/2byk4n0k5yifvfm6lslm2kwj7wvbcakg-flash-ergodoxez
+    ├── flash-model01 -> /nix/store/52mgja2zy1zvc4z3daic46dkdq5b1f0n-flash-model01
+    ├── flash-model100 -> /nix/store/av7pxr8cns2r2v5al7snajhxkdxpbxzj-flash-model100
+    ├── flash-moonlander -> /nix/store/6w1fdilmdsrvqgllgw4s5n0mlvfwhvff-flash-moonlander
     └── licenses -> /nix/store/65nmw7i5vyfslc4dkqywc0miwffhv5y9-shajra-keyboards-licenses
 
     18 directories, 4 files

README.org

@@ -305,27 +305,27 @@ tree $(nix build --no-link --print-out-paths) 2>/dev/null
 
 #+results: nix-build
 #+begin_example
-/nix/store/zjfinbmavajq6xh492zdprhkhnfj4yyw-shajra-keyboards-ci
+/nix/store/j47qlcp9yqlsma791zr6dadbys956wcx-shajra-keyboards-ci
 ├── build-ergodoxez-builtin-shajra-flash -> /nix/store/15knkvn4hkix0vn1dsyk9ffzqnkl32nk-ergodoxez-builtin-shajra-flash
 ├── build-ergodoxez-builtin-shajra-hex -> /nix/store/mrkig8c5jkhgchh3l3bsl8wj17jz77n7-ergodoxez-builtin-shajra.hex
 ├── build-ergodoxez-factory-flash -> /nix/store/kknpgd1japddjn8rl06n91x42ly7q4i8-ergodoxez-factory-flash
 ├── build-ergodoxez-factory-hex -> /nix/store/cyp9izs14157idkyrbp6j52ym98j6h9h-ergodoxez-factory.hex
-├── build-model01-builtin-shajra-flash -> /nix/store/835qi2zb9m0dala6x7gmkpmxlmgd97xx-model01-builtin-shajra-flash
-├── build-model01-builtin-shajra-hex -> /nix/store/416x1s5v5pdki043nhlr8jqf0waf8j0d-model01-builtin-shajra-hex
+├── build-model01-builtin-shajra-flash -> /nix/store/yhj7rq7kc65ylr96ywsfbqm532j0jldv-model01-builtin-shajra-flash
+├── build-model01-builtin-shajra-hex -> /nix/store/c93lf9xy6kiwjnifbg4v6q0bxsrr60n6-model01-builtin-shajra-hex
 ├── build-model01-factory-flash -> /nix/store/r7fcyzxqix123jagi9lvyzsvlg5qilr5-model01-factory-flash
 ├── build-model01-factory-hex -> /nix/store/gwxx9i59daqj1gq06biikvsyqv4a05rb-model01-factory-hex
-├── build-model100-builtin-shajra-flash -> /nix/store/0jp1x1zmz00wkwyi7q7jxcvz7k9pwh3q-model100-builtin-shajra-flash
-├── build-model100-builtin-shajra-hex -> /nix/store/my83qz6czp7rkvg82q091cdkk95dm1v4-model100-builtin-shajra-hex
+├── build-model100-builtin-shajra-flash -> /nix/store/g9bk5mwwj3ay01yh3a6rcmvsbbgrg1p9-model100-builtin-shajra-flash
+├── build-model100-builtin-shajra-hex -> /nix/store/c8ggagg9wrx77qvhy8zamnnlazfxmc23-model100-builtin-shajra-hex
 ├── build-model100-factory-flash -> /nix/store/lqq6jq9xyjb1sgnl0yjq9a1q6vlw6z0d-model100-factory-flash
 ├── build-model100-factory-hex -> /nix/store/a3197a8k04yzisrcxrszs6d7653krrp2-model100-factory-hex
 ├── build-moonlander-builtin-shajra-flash -> /nix/store/z19vx9vqz17lw69sg27p521yk31j1bmf-moonlander-builtin-shajra-flash
 ├── build-moonlander-builtin-shajra-hex -> /nix/store/hrajvgijrpk8zk5rs08l80ds2z67vdwz-moonlander-builtin-shajra.bin
 ├── build-moonlander-factory-flash -> /nix/store/z7bg73d94z645s2788vm6hw6hqc2400s-moonlander-factory-flash
 ├── build-moonlander-factory-hex -> /nix/store/r5d6hfhfg7ycpsag0l83mldmpv632rxi-moonlander-factory.bin
-├── flash-ergodoxez -> /nix/store/hc815q8svfsnfc9rizjhqqwz0fssr2cy-flash-ergodoxez
-├── flash-model01 -> /nix/store/xk8wp76hryfqc6gzrwkz7h2mj5yqx1hm-flash-model01
-├── flash-model100 -> /nix/store/1pkqq2hal1zzgmimmxvm645z2n0smvkx-flash-model100
-├── flash-moonlander -> /nix/store/qscisa57cqmcjaxgahdk5xni0074rzm0-flash-moonlander
+├── flash-ergodoxez -> /nix/store/2byk4n0k5yifvfm6lslm2kwj7wvbcakg-flash-ergodoxez
+├── flash-model01 -> /nix/store/52mgja2zy1zvc4z3daic46dkdq5b1f0n-flash-model01
+├── flash-model100 -> /nix/store/av7pxr8cns2r2v5al7snajhxkdxpbxzj-flash-model100
+├── flash-moonlander -> /nix/store/6w1fdilmdsrvqgllgw4s5n0mlvfwhvff-flash-moonlander
 └── licenses -> /nix/store/65nmw7i5vyfslc4dkqywc0miwffhv5y9-shajra-keyboards-licenses
 
 18 directories, 4 files

doc/design.md

@@ -14,7 +14,7 @@
   - [Working around a problem with Mod-Tap and Qukeys](#sec-5-4)
   - [Mapping modifiers](#sec-5-5)
   - [More on `Alt Gr` and `Compose`](#altgr_and_compose)
-  - [A problem with `GUI` on Macs](#osm_right_gui)
+  - [A problem with `GUI + Enter` on Macs](#osm_right_gui)
   - [Mapping remaining non-modifiers](#sec-5-8)
   - [Mapping the Function layer](#sec-5-9)
   - [Media and Mouse layers](#sec-5-10)
@@ -208,17 +208,23 @@ Note that on GNU/Linux, `Shift+Right Alt` is often configured to be a [`Compose`
 
 Because they are similar in function, the `Alt Gr` and `Compose` keys are placed adjacent to one another in all “shajra” keymaps.
 
-## A problem with `GUI` on Macs<a id="osm_right_gui"></a>
+## A problem with `GUI + Enter` on Macs<a id="osm_right_gui"></a>
 
 On Linux systems, the `GUI` (`Windows` key) modifier isn't used by the operating system of applications, leaving it broadly available for user shortcuts. However, this isn't the case for Mac OS and various Mac applications, which assign shortcuts liberally to the `Command` key.
 
 The `Option` key on the Mac isn't available for user shortcuts either because applications use it as well, not to mention the complexity we already have with `Compose` and `Alt Gr` emulation.
 
 To avoid conflicts, we're forced to use the left `GUI` key for user shortcuts, which leaves the right `GUI` key for standard Mac shortcuts. Though we have a `GUI` key on both halves, they aren't the same in practice. Consequently, we lose some ergonomic benefits.
 
-This loss is apparent if we need both a `Left GUI + Enter` shortcut and a `Right GUI + Enter` shortcut. We can easily hit `Enter` with the `Left GUI` key depressed by the other hand. But `Right GUI` and `Enter` are both thumb-depressed keys on the right-hand split. We'd have to lift our hands from home position.
+This loss is apparent on the “shajra” keymap if we need both a `Left GUI + Enter` shortcut and a `Right GUI + Enter` shortcut. Perhaps some applications don't give us a choice. `Right GUI` and `Enter` are both thumb-depressed keys on the right-hand split. We'd have to lift our right hand from home position to use our fingers.
 
-We could shuffle shortcuts to avoid this particular conflict. But the “shajra” keymap offers a more general solution by providing a One-Shot Modifer (OSM) of the right `GUI` key on the function layer. It requires another keypress, but our hands don't need to leave home position.
+We could move some keys in our keymap to keep from lifting our fingers. But that would move the problem to another shortcut. Or we might have to sacrifice the ergonomics benefits of depressing modifiers with our thumbs. The “shajra” keymap offers a more general solution by providing a One-Shot Modifer (OSM) of the right `GUI` key on the function layer. It requires another keypress, but our hands don't need to leave home position.
+
+To hit the specific shortcut of `Right GUI + Enter`, you hold down the right `Function` modifier to tap the left `Function` key. That engages the OSM. You can then hit `Enter`. The OSM will stay engaged for a few seconds, and then the keyboard will return to its normal state.
+
+Hopefully, this is an agreeable solution for a specific scenario where you want both `Left GUI + Enter` and `Right GUI + Enter` shortcuts. This scenario is more likely on Macs, and even then, not for everyone.
+
+Another solution, not implemented, could be to put Mod-Tap modifiers on normal keys, but this can lead to subtle typos, especially when typing fast.
 
 ## Mapping remaining non-modifiers<a id="sec-5-8"></a>