doomemacs/modules/input/layout/README.org

#+title:    :input layout
#+subtitle: auie,ctsrnm is the superior home row
#+created:  Jun 29, 2020
#+since:    21.12.0

* Description :unfold:
This module provides barebones support for using Doom with non-qwerty keyboard
layouts.

** Maintainers
- [[doom-user:][@gagbo]] ([[kbd:][+bepo]])

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +azerty ::
  Remap keybinds to accommodate the [[https://en.wikipedia.org/wiki/AZERTY][Azerty keyboard layout]].
- +bepo ::
  Remap keybinds to accommodate the [[https://en.wikipedia.org/wiki/B%C3%89PO][BÉPO keyboard layout]] (version 1.1, in
  particular).

** Packages
/This module doesn't install any packages./

** TODO Hacks
#+begin_quote
 🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

/This module has no external requirements./

* TODO Usage
#+begin_quote
 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Bépo
Support for the bépo layout includes:
- Setting Avy keys to the correct home row keys
- Changing navigation keys to [[kbd:][c]], [[kbd:][t]], [[kbd:][s]], and [[kbd:][r]]
  + old [[kbd:][t]] is mapped to [[kbd:][j]]
  + old [[kbd:][s]] is mapped to [[kbd:][k]] (i.e. staging in the magit status buffer is done with
    [[kbd:][k]])
  + See [[*Configuration][Configuration]] to see where old [[kbd:][c]] and [[kbd:][r]] functions
    are remapped
- Bind [[kbd:][<>]] functions to [[kbd:][«»]] keys when possible
- Bind [[kbd:][[]]] functions to [[kbd:][()]] keys when possible (the "unimpaired-like" bindings)
- Bind [[kbd:][é]] key to [[kbd:][w]] functions when possible
- Bind [[kbd:][è]] key to useful functions when possible
- Bind [[kbd:][`~]] functions to [[kbd:][$#]] keys when possible

*** Easymotion
If you use [[doom-package:][evil-easymotion]], then all the bindings that were on [[kbd:][gs]] have been
moved to [[kbd:][gé]].

In short : [[kbd:][g s j]] -> [[kbd:][g é t]] (~evilem-motion-next-line~). And so on.

*** Leaving mnemonics alone when possible
Exchanging [[kbd:][h]]/[[kbd:][j]]/[[kbd:][k]]/[[kbd:][l]] to [[kbd:][c]]/[[kbd:][t]]/[[kbd:][s]]/[[kbd:][r]] has the effect of destroying a few mnemonics: the
change operator becomes [[kbd:][l]] for example, or the window split becomes [[kbd:][SPC é k]].

The module tries to limit those changes to the minimum, especially in special
buffers. A concrete example is magit.

As the =magit: project= buffer (obtained with ~M-x magit-status~) does not need
left-right navigation, keys [[kbd:][c]], [[kbd:][r]], [[kbd:][h]], and [[kbd:][l]] keep their "expected" bindings, while
[[kbd:][t]], [[kbd:][s]], [[kbd:][j]], and [[kbd:][k]] are flipped:
- checking the log from a magit buffer is still on [[kbd:][l]]
- staging a file/region has been moved to [[kbd:][k]]

*** Possible contributions
**** Avoid [[kbd:][g]] and [[kbd:][z]] to be used too often
A nice addition in the future might be to have all the normal mode bindings that
start with [[kbd:][g]] start with [[kbd:][,]] instead to avoid the curl on these common bindings.
This is *not* implemented for the time being.

The same thing could be done to [[kbd:][z]], potentially using [[kbd:][à]] instead.

**** Proper minor mode
Also, implementing all those changes as a minor we could flip on and off would
help with adoption

**** Put "word" text objects to é instead of w
"inside word" and "around word" are [[kbd:][iw]] and [[kbd:][aw]], which use the very poorly rated [[kbd:][w]]
key in the bépo layout. Finding a way to use [[kbd:][é]] or even [[kbd:][è]] more for these would be
a welcome change

*** Org-mode
[[doom-package:][evil-org]] allows to define ~evil-org-movement-bindings~ to automatically map
movement bindings on non-hjkl keys. It maps automatically keys to [[kbd:][C-c]] and [[kbd:][C-r]] in
normal and insert states though, and it's not really user friendly in Emacs to
remap those.

Therefore, in ~org-mode~:
- ~org-shiftright~ is bound to [[kbd:][C-»]]
- ~org-shiftleft~ is bound to [[kbd:][C-«]]

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Bépo
=+layout-bepo-cr-rotation-style= controls whether:
- =qwerty-c= functions are mapped on =bépo-l= key, and =qwerty-r= functions on
  =bépo-h= key (~'ergodis~), or
- =qwerty-c= functions are mapped on =bépo-h= key, and =qwerty-r= functions on
  =bépo-l= key (~'strict~)
 
~'strict~ would be the logical choice but the [[kbd:][c]] functions are used more often
than the [[kbd:][r]] ones so [[https://bepo.fr/wiki/Vim#Principe][Ergodis]] advises to actually put all the [[kbd:][c]] functions on the
key that does not need a curl.

* Troubleshooting
[[doom-report:][Report an issue?]]

** Outstanding issues (contributions welcome)
*** Bépo
- In [[doom-package:][eshell]], the key [[kbd:][c]] is still bound to ~evil-collection-eshell-evil-change~ in
  normal mode.
  
** How to investigate an issue ?
If a key is misbehaving, use ~M-x describe-key~ ([[kbd:][C-h k]] or [[kbd:][SPC h k]] or [[kbd:][F1 k]]) to
see the command bound to the key, and more importantly in which keymap it is
bound.

You should ignore all ~evil-collection-*-backup-map~ keymaps, as they are
artifacts from ~evil-collection-translate-key~ and those maps are actually not
active.

Most likely the solution is to call one of the "key rotation" functions on the
relevant keymaps.

** How to deactivate the new bindings and go back to the old ones ?
If you are learning a new layout you might want to go back to tho old one to
"get work done". Sadly the only way is to comment out the module, run ~$ doom
sync~ and restart emacs.

Restoring the session [[kbd:][SPC q l]] by default helps to lower the impact of the
restart.

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote