From b0b9af8175766eb83839c3ef140199fdd2db0cc1 Mon Sep 17 00:00:00 2001 From: Trilowy <49493635+trilowy@users.noreply.github.com> Date: Mon, 2 Sep 2024 15:06:13 +0200 Subject: [PATCH] docs: one page explanation --- README.md | 293 +++++++++++++++++++++------ img/angle_mod.svg | 138 +++++++++++++ img/{kanata => }/fn.svg | 0 img/{kanata => }/hrm.svg | 0 img/index.html | 21 +- img/kanata/all_ergo.svg | 297 ---------------------------- img/kanata/angle_mod.svg | 237 ---------------------- img/kanata/no_angle_mod.svg | 237 ---------------------- img/{kanata => }/layer_taps.svg | 0 img/{kanata => }/navigation.svg | 0 img/{kanata => }/numpad.svg | 0 img/{kanata => }/numrow.svg | 0 img/{kanata => }/symbols.svg | 0 img/{kanata => }/vim_navigation.svg | 0 kanata/README.md | 202 +------------------ 15 files changed, 379 insertions(+), 1046 deletions(-) create mode 100644 img/angle_mod.svg rename img/{kanata => }/fn.svg (100%) rename img/{kanata => }/hrm.svg (100%) delete mode 100644 img/kanata/all_ergo.svg delete mode 100644 img/kanata/angle_mod.svg delete mode 100644 img/kanata/no_angle_mod.svg rename img/{kanata => }/layer_taps.svg (100%) rename img/{kanata => }/navigation.svg (100%) rename img/{kanata => }/numpad.svg (100%) rename img/{kanata => }/numrow.svg (100%) rename img/{kanata => }/symbols.svg (100%) rename img/{kanata => }/vim_navigation.svg (100%) diff --git a/README.md b/README.md index 323baed..ddd78d4 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,256 @@ -Arsenik -================================================================================ +

Arsenik

-Configure your keyboard (even if it is not programmable) with a -beginner-friendly, simplified [Miryoku]-like approach to minimize finger -movements! +
+ ★ Ergonomics for any keyboard! ★ +
+ +
+ +
+ Configure your keyboard — even if it is not programmable — with a + beginner-friendly approach to minimize finger movements! +
+ +
![base, navigation and sym layers on a 33-key keyboard](img/all.svg) *Note: The keyboard layout presented here in the illustration is Qwerty but it works with other layouts as well — e.g. Azerty, Qwertz, Ergo‑L, Bépo…* -**Bring the keys to your fingers, rather than moving your fingers to the keys -with layer-taps!** +-------------------------------------------------------------------------------- -- A long press on the Return key brings up the Symbol -layer in blue, where all programming symbols are arranged for comfort and -efficiency. -- A long press on the Space bar brings up the Navigation -layer in orange, with a numpad, cursor navigation (ESDF) and one-hand -shortcuts. -This is how modern ergonomic keyboards work — e.g. [Planck], [Atreus], [Corne], -[Ferris]… The goal here is to propose an approach that works with any keyboard, -including your laptop’s. +Table of contents +-------------------------------------------------------------------------------- -*Note: You might benefit the most of Arsenik if you are [touch typing].* +- [Philosophy](#philosophy) +- [Features](#pick-your-poison) + 1. [Angle mod](#1-angle-mod) + 2. [Mod-taps](#2-supercharge-your-thumbs-with-mod-taps) + 3. [Symbols layer](#3-symbols-layer) + 4. [Navigation layer](#4-navigation-layer) + 5. [Keyboard layout](#5-keyboard-layout) + 6. [Extra customization](#bonus-spice-it-up) +- [Installation](#installation) +- [Why “Arsenik”?](#why-arsenik) +- [Join the community](#join-the-community) -Modular Approach +Philosophy -------------------------------------------------------------------------------- -Enable Arsenik features from the following options: -- [angle mod]: permuts the extra ISO keyboard key on the down left to ease the -angle on your left wrist when typing -- 3 home row mods (HRM) per hand for Ctrl, Alt, -Super (if pressed: output a letter on the home row, if held: acts as -a modifier) -- 3 layer-tap keys under the thumbs: Alt (or Shift in -HRM)/Backspace, Navigation/Space, -Symbol/Return -- symbol layer: have all programmation characters at most one key away from your -fingers -- num row or num pad -- navigation layer like in arrow cluster or Vim-like - -*Note: these features are explained in more details in the -[Arsenik Kanata page](kanata).* - - -Main Benefits +**Bring the keys to your fingers, rather than moving your fingers to the keys.** + +Not sure if you should buy that expensive ergonomic keyboard? + +Download a ready-to-use Arsenik configuration for [Kanata], and enjoy on your +regular keyboard features that were normally only accessible to programmable +keyboard. + +*Note: You might benefit the most of Arsenik if you are [touch typing].* + + +Pick Your Poison! -------------------------------------------------------------------------------- -- Shift, Backspace, Return under the thumbs! -- all numbers and programming symbols in the comfortable 3×10 zone (close to the -home row) -- symmetrical modifiers on the home row -- easier left-hand shortcuts -- works with any keyboard +Choose which Arsenik features to use from the following options: -Unlike Miryoku which requires 6 thumb keys, Arsenik has been designed to work -with standard ANSI/ISO/laptop keyboards, leveraging the spacebar and the two -Alt/Cmd keys. + +### 1. Angle mod + +On an ISO keyboard, it permuts the extra down left key to ease the angle on your +left wrist when typing. + +![Angle mod](./img/angle_mod.svg) + + +### 2. Supercharge your thumbs with mod-taps + +#### First: layer-taps + +If you’re new to mod-taps, we suggest to start by adding the “layer-tap” option +where only the thumbs are affected: + +- the left thumb key remains a Cmd or Alt key when held, +but emits a Backspace when tapped; +- the right thumb key brings the Symbols layer when held (in blue) +— where all programming symbols are arranged for comfort and efficiency — and +emits Return when tapped; +- the spacebar brings the Navigation layer when held (in orange). + +![alt, navigation and sym layers under the thumbs](./img/layer_taps.svg) + +Having Backspace and Enter under the thumbs is enough to +reduce the pinky fatigue very significantly. And using the Symbols +and Navigation layers further reduces hand and finger movements. + + +#### Next level: enable the Home Row Mods + +When you are familiar with mod-taps, it’s time to enable them on the home row +with the “HRM” variants: + +- FDS and JKL become Ctrl, Alt, +Super when held long enough; +- the left thumb key can now emit a Shift rather than Alt +when held. + +![home row mods on SDF keys](./img/hrm.svg) + +This is a very basic variant of the [Miryoku] principle: one layer on each +thumb key, and symmetrical modifiers on the home row. + + +### 3. Symbols layer + +For the Symbols layer you can keep AltGr as-is. It is +useful for keyboard layouts that rely heavily on the AltGr key. + +But the real fun (especially for programmers) happens when we enable the “One +Dead Key” (= 1DK) programmation layer! + +![1dk symbols layer on a 33-key keyboard](./img/symbols.svg) + + +#### Num row >> Num pad + +If enabled, in Symbols mode, pressing the left thumb key brings up +the NumRow layer: + +- all digits are on the home row, in the order you already know +- the upper row helps with Shift-digit shortcuts +- the lower row has dash, comma, dot and slash signs to help with number / date +inputs +- Space becomes a narrow no-break space for layouts that supports it + +![NumRow layer on a 33-key keyboard](./img/numrow.svg) + +Even on keyboards that *do* have a physical number row, this `NumRow`layer can +be interesting to use in order to minimize finger movements furthermore. + + +### 4. Navigation layer + +A basic Navigation layer has an arrow cluster on the left hand to +move around and a num pad on the right hand. + +![navigation layer on a 33-key keyboard](./img/navigation.svg) + +#### A superpowered Vim-friendly mod + +For those who like to move the cursor with HJKL in all app, with any +keyboard layout, it is possible to enable a Vim-like Navigation +layer. + +It also has: +- super-comfortable Tab and Shift-Tab +- mouse emulation: previous / next and mouse scroll + +![Vim navigation layer on a 33-key keyboard](./img/vim_navigation.svg) + +This Navigation layer has a few empty slots on purpose, so you can +add our own keys or layers. + +NumPad and Fn toggle these layers, they stay active +without holding the key until escaped with Alt or AltGr. + +![NumPad layer on a 33-key keyboard](./img/numpad.svg) +

+ NumPad layer toggled +

+ +![Fn layer on a 33-key keyboard](./img/fn.svg) +

+ Fn layer toggled +

+ +### 5. Keyboard layout + +Choose your keyboard layout among the available ones for Arsenik to work +properly. + +If your layout is not on this list, feel free to open an issue or upvote an +existing one. + +Here is some specifities for some supported layouts: + +
+Azerty + +By using the 1dk Symbols layer, you won’t have access to the +€ sign in AltGr. You might want to remap it elsewhere, or +not using the 1dk Symbols layer. +
+ +
+Bépo + +By using the 1dk Symbols layer, you won’t have access to the +characters in AltGr. You might want to remap some of them elsewhere, +or not using the 1dk Symbols layer. +
+ +
+Optimot + +Do not enable angle mod for Optimot as it is already in angle mod with its +driver. + +By using the 1dk Symbols layer, you won’t have access to the +characters in AltGr. You might want to remap some of them elsewhere, +or not using the 1dk Symbols layer. +
+ + +### Bonus: Spice It Up + +From there, you can edit the configuration to match your liking, even contribute +to Arsenik! + +The 300 ms delay before a key becomes a modifier has been chosen to be easy for +beginners. Once used to mod-taps, you may want to reduce it so keyboard +shortcuts can be done more quickly. + +In the NumRow layer, you can edit the dk1 to +dk5 shortcuts to put whatever seams useful to you, a lot of available +keys are defined in [Kanata source code][Kanata keys]. + +In the Navigation layer, you can put a command on top of the +P key (in Qwerty), e.g. for an application launcher. + +Note that Kanata can also use the laptop’s trackpoint buttons (e.g. ThinkPad) +as two additional thumb keys. :-) Installation -------------------------------------------------------------------------------- -Start right now with the keyboard you already have, and install -[Kanata with Arsenik configuration](kanata). +Adjusting to compact keyboard layouts isn’t easy, but Arsenik is designed for +a step-by-step approach: + +- load `kanata.kbd` with Kanata ([installation instructions](kanata)) +- enable each feature by un-commenting the related line (a commented line starts +with `;;`), you must enable one and only one line per feature +- live-reload the configuration with Space+Backspace +(requires the feature layer-taps enabled) If you have a programmable keyboard you might want to take a look at the [QMK](qmk) version of Arsenik (work in progress). -Other desktop implementations (kmonad, keyd…) would be nice to see as well. +Other desktop implementations (kmonad, keyd, Karabiner…) would be nice to see as +well. -Related Projects +Why “Arsenik”? -------------------------------------------------------------------------------- +33 keys layout: the 33rd element of the periodic table. + +Unlike Miryoku which requires 6 thumb keys, Arsenik has been designed to work +with standard ANSI/ISO/laptop keyboards, leveraging the spacebar and the two +Alt/Cmd keys. + ### Inspiration - [Miryoku] for the main idea of using modifiers on the home row and layer @@ -107,31 +280,23 @@ AltGr layer at all (e.g. QWERTY, Colemak, Workman…), or an optimized AltGr lay - [Miryoku]: 36 keys, 6 layers - [Seniply]: 34 keys, 6 layers, no layer-taps (“Callum-style”) -### Join the community + +Join the community +-------------------------------------------------------------------------------- French-speaking users may join the [Ergo-L Discord server] which hosts a -channel to talk about Arsenik. +channel to talk about Arsenik, keyboard, layouts and many more. Feel free to open an issue and/or a pull request if you encounter a bug or want to enhance the Arsenik experience! -TODO --------------------------------------------------------------------------------- - -- KMonad / Karabiner support -- sample QMK / ZMK implementations for common keyboards - - +[Kanata]: https://github.com/jtroo/kanata [Miryoku]: https://github.com/manna-harbour/miryoku -[Planck]: https://olkb.com/collections/planck -[Atreus]: https://atreus.technomancy.us -[Corne]: https://github.com/foostan/crkbd -[Ferris]: https://github.com/pierrechevalier83/ferris [touch typing]: https://en.wikipedia.org/wiki/Touch_typing -[angle mod]: https://colemakmods.github.io/ergonomic-mods/angle.html [Lafayette]: https://qwerty-lafayette.org/42 [Ergo-L]: https://ergol.org +[Kanata keys]: https://github.com/jtroo/kanata/blob/main/parser/src/keys/mod.rs#L159 [Extend]: https://dreymar.colemak.org/layers-extend.html [Neo]: https://neo-layout.org [Shaka34]: https://github.com/lobre/shaka34 diff --git a/img/angle_mod.svg b/img/angle_mod.svg new file mode 100644 index 0000000..c98cf2d --- /dev/null +++ b/img/angle_mod.svg @@ -0,0 +1,138 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Z + + + + X + + + + C + + + + V + + + + B + + + + + + + + + + + + < + > + + + + + ➤ + + + + + + + + + < + > + + + + diff --git a/img/kanata/fn.svg b/img/fn.svg similarity index 100% rename from img/kanata/fn.svg rename to img/fn.svg diff --git a/img/kanata/hrm.svg b/img/hrm.svg similarity index 100% rename from img/kanata/hrm.svg rename to img/hrm.svg diff --git a/img/index.html b/img/index.html index 85febfe..4021fc1 100644 --- a/img/index.html +++ b/img/index.html @@ -25,35 +25,32 @@

Arsenik Kanata

-

No angle mod

- -

Angle mod

- +

Layer-taps

- +

HRM

- +

1dk Symbols

- +

NumRow

- +

Navigation

- +

Vim Navigation

- +

Vim NumPad

- +

Vim Fn

- +

QMK

diff --git a/img/kanata/all_ergo.svg b/img/kanata/all_ergo.svg deleted file mode 100644 index b86174e..0000000 --- a/img/kanata/all_ergo.svg +++ /dev/null @@ -1,297 +0,0 @@ - - - - - - - - - Q - ↹ - ^ - - - - W - ⇱ - < - - - - E - ↑ - > - - - - R - ⇲ - $ - - - - T - ⇞ - % - - - - - - Y - / - @ - - - - U - 7 - & - - - - I - 8 - * - - - - O - 9 - ' - - - - P - ` - - - - - - - - - A - all - { - - - - - S - ⌘ - ← - ( - - - - - D - ⌥ - ↓ - ) - - - - - F - ⌃ - → - } - - - - G - ⇟ - = - - - - - - H - - - \ - - - - - J - ⌃ - 4 - + - - - - - K - ⌥ - 5 - - - - - - - L - ⌘ - 6 - / - - - - ; - : - 0 - " - - - - - - - - - - Z - undo - ~ - - - - - - X - cut - [ - - - - - - C - copy - ] - - - - - - V - paste - _ - - - - - - B - ⇤ - # - - - - - - - N - , - | - - - - M - 1 - ! - - - - , - < - 2 - ; - - - - . - > - 3 - : - - - - / - ? - . - ? - - - - - - - - - shift - ⌦ - ⌫ - - - - - nav - - - - - sym - ⎋ - ⏎ - - - - diff --git a/img/kanata/angle_mod.svg b/img/kanata/angle_mod.svg deleted file mode 100644 index 19d80a3..0000000 --- a/img/kanata/angle_mod.svg +++ /dev/null @@ -1,237 +0,0 @@ - - - - - - - - - Q - - - - W - - - - E - - - - R - - - - T - - - - - - Y - - - - U - - - - I - - - - O - - - - P - - - - - - - - - A - - - - S - - - - D - - - - F - - - - G - - - - - - H - - - - J - - - - K - - - - L - - - - ; - : - - - - - - - - - - Z - - - - - - X - - - - - - C - - - - - - V - - - - - - B - - - - - - \ - | - - - - - N - - - - M - - - - , - < - - - - . - > - - - - / - ? - - - - - - - - Alt - - - - - - - AltGr - - - - diff --git a/img/kanata/no_angle_mod.svg b/img/kanata/no_angle_mod.svg deleted file mode 100644 index 8a083da..0000000 --- a/img/kanata/no_angle_mod.svg +++ /dev/null @@ -1,237 +0,0 @@ - - - - - - - - - Q - - - - W - - - - E - - - - R - - - - T - - - - - - Y - - - - U - - - - I - - - - O - - - - P - - - - - - - - - A - - - - S - - - - D - - - - F - - - - G - - - - - - H - - - - J - - - - K - - - - L - - - - ; - : - - - - - - - - \ - | - - - - - - Z - - - - - - X - - - - - - C - - - - - - V - - - - - - B - - - - - - - N - - - - M - - - - , - < - - - - . - > - - - - / - ? - - - - - - - - Alt - - - - - - - AltGr - - - - diff --git a/img/kanata/layer_taps.svg b/img/layer_taps.svg similarity index 100% rename from img/kanata/layer_taps.svg rename to img/layer_taps.svg diff --git a/img/kanata/navigation.svg b/img/navigation.svg similarity index 100% rename from img/kanata/navigation.svg rename to img/navigation.svg diff --git a/img/kanata/numpad.svg b/img/numpad.svg similarity index 100% rename from img/kanata/numpad.svg rename to img/numpad.svg diff --git a/img/kanata/numrow.svg b/img/numrow.svg similarity index 100% rename from img/kanata/numrow.svg rename to img/numrow.svg diff --git a/img/kanata/symbols.svg b/img/symbols.svg similarity index 100% rename from img/kanata/symbols.svg rename to img/symbols.svg diff --git a/img/kanata/vim_navigation.svg b/img/vim_navigation.svg similarity index 100% rename from img/kanata/vim_navigation.svg rename to img/vim_navigation.svg diff --git a/kanata/README.md b/kanata/README.md index 227b2e9..a1b286c 100644 --- a/kanata/README.md +++ b/kanata/README.md @@ -1,8 +1,6 @@ Arsenik Kanata ================================================================================ -![base, navigation and sym layers on a 33-key keyboard](../img/kanata/all_ergo.svg) - Installation -------------------------------------------------------------------------------- @@ -21,6 +19,9 @@ fixes some weird bugs like C and V inversion. *Note: this tip is tested for the version 1.6.1 of Kanata, in later version the `winIOv2` version might be the default one.* + +Put the `kanata_winIOv2.exe` in the Kanata Arsenik folder, run it and you’re +good to go!
@@ -92,202 +93,5 @@ the current user logs in - `systemctl --user status kanata.service` to check if `kanata` is running
- -Pick Your Poison! --------------------------------------------------------------------------------- - -Adjusting to compact keyboard layouts isn’t easy, but Arsenik is designed for -a step-by-step approach: - -- load `kanata.kbd` with Kanata (installation instructions upward) -- enable each feature by un-commenting the related line (a commented line starts -with `;;`), you must enable one and only one line per feature -- live-reload the configuration with Space+Backspace -(requires the feature layer-taps enabled) - - -### 1. Angle mod - -If you have an ISO keyboard, you might give a try to angle mod to ease the angle -on your left wrist when typing. - -It permuts the extra ISO keyboard key on the down left of the keyboard, -illustrated by the following: - -![No angle mod](../img/kanata/no_angle_mod.svg) -

- No angle mod -

- -![With angle mod](../img/kanata/angle_mod.svg) -

- With angle mod -

- -This option is enabled by default when you download Arsenik but can be disabled. - - -### 2. Supercharge your thumbs with mod-taps - -#### First: layer-taps - -If you’re new to mod-taps, we suggest to start by adding the “layer-tap” option -where only the thumbs are affected: - -- the left thumb key remains a Cmd or Alt key when held, -but emits a Backspace when tapped; -- the right thumb key brings the Symbols layer when held (similar to -an AltGr key), and emits Return when tapped; -- the spacebar brings the Navigation layer when held. - -![alt, navigation and sym layers under the thumbs](../img/kanata/layer_taps.svg) - -Having Backspace and Enter under the thumbs is enough to -reduce the pinky fatigue very significantly. And using the Symbol -and Navigation layer further reduces hand and finger movements. - - -#### Next level: enable the Home Row Mods - -When you are familiar with mod-taps, it’s time to enable them on the home row -with the “HRM” variants: - -- FDS and JKL become Ctrl, Alt, -Super when held long enough; -- the left thumb key can now emit a Shift rather than Alt -when held. - -![home row mods on SDF keys](../img/kanata/hrm.svg) - -This is a very basic variant of the [Miryoku] principle: one layer on each -thumb key, and symmetrical modifiers on the home row. - - -#### Spice it up - -The 300 ms delay before a key becomes a modifier has been chosen to be easy for -beginners. Once used to mod-taps, you may want to reduce it so keyboard -shortcuts can be done more quickly. - - -### 3. Symbols layer - -For the Symbols layer you can keep AltGr as-is. It is useful for -keyboard layouts that rely heavily on the AltGr key. - -But the real fun (especially for programmers) happens when we enable the “One -Dead Key” (= 1dk) programmation layer! - -![1dk symbols layer on a 33-key keyboard](../img/kanata/symbols.svg) - -#### Num row >> Num pad - -If enabled, in `Symbols` mode, pressing the left thumb key brings up the -`NumRow` layer: - -- all digits are on the home row, in the order you already know -- the upper row helps with Shift-digit shortcuts -- the lower row has dash, comma, dot and slash signs to help with number / date -inputs -- Space becomes a narrow no-break space for layouts that supports it - -![NumRow layer on a 33-key keyboard](../img/kanata/numrow.svg) - -Even on keyboards that *do* have a physical number row, this `NumRow`layer can -be interesting to use in order to minimize finger movements furthermore. And it -makes it easier to mix symbols with numbers (e.g. to type `[0]`). - - -### 4. Navigation layer - -A basic `Navigation` layer has an arrow cluster on the left hand to move around -and a num pad on the right hand. - -![navigation layer on a 33-key keyboard](../img/kanata/navigation.svg) - -#### A superpowered Vim-friendly mod - -For those who like to move the cursor with HJKL in all app, with any -keyboard layout, it is possible to enable a Vim-like `Navigation` layer. - -It also has: -- super-comfortable Tab and Shift-Tab -- mouse emulation: previous / next and mouse scroll - -![Vim navigation layer on a 33-key keyboard](../img/kanata/vim_navigation.svg) - -This `Navigation` layer has a few empty slots on purpose, so you can add our own -keys or layers. - -`NumPad` and `Fn` toggle these layers, they stay active without holding the key -until escaped with Alt or AltGr. - -![NumPad layer on a 33-key keyboard](../img/kanata/numpad.svg) -

- NumPad layer toggled -

- -![Fn layer on a 33-key keyboard](../img/kanata/fn.svg) -

- Fn layer toggled -

- -### 5. Keyboard layout - -Choose your keyboard layout among the available ones for Arsenik to work -properly. - -If your layout is not on this list, feel free to open an issue or upvote an -existing one. - -Here is some specifities for some supported layouts: - -
-Azerty - -By using the 1dk `Symbols` layer, you won’t have access to the € sign -in AltGr. You might want to remap it elsewhere, or not using the 1dk -`Symbols` layer. -
- -
-Bépo - -By using the 1dk `Symbols` layer, you won’t have access to the characters in -AltGr. You might want to remap some of them elsewhere, or not using -the 1dk `Symbols` layer. -
- -
-Optimot - -Do not enable angle mod for Optimot as it is already in angle mod with its -driver. - -By using the 1dk `Symbols` layer, you won’t have access to the characters in -AltGr. You might want to remap some of them elsewhere, or not using -the 1dk `Symbols` layer. -
- - -Extra Personalization --------------------------------------------------------------------------------- - -From there, you can edit the configuration to match your liking, even contribute -to Arsenik! - -In the `NumRow` layer, you can edit the `dk1` to `dk5` shortcuts to put whatever -seams useful to you (media buttons for example), a lot of available keys are -defined in [Kanata source code][Kanata keys]. - -In the `Navigation` layer, you can put a command on top of the P key -(in Qwerty), e.g. for an application launcher. - -Note that Kanata can also use the laptop’s trackpoint buttons (e.g. ThinkPad) -as two additional thumb keys. :-) - - [Download Arsenik]: https://github.com/OneDeadKey/arsenik/releases [Download Kanata]: https://github.com/jtroo/kanata/releases -[Miryoku]: https://github.com/manna-harbour/miryoku -[Kanata keys]: https://github.com/jtroo/kanata/blob/main/parser/src/keys/mod.rs#L159