spacemacs/layers/+keyboard-layouts/bepo/README.org

#+TITLE: Bépo layer

#+CAPTION: logo

[[file:img/bepo.png]]

* Table of Contents                                         :TOC_4_gh:noexport:
 - [[#description][Description]]
 - [[#install][Install]]
   - [[#variables][Variables]]
   - [[#customization][Customization]]
 - [[#mapping][Mapping]]
 - [[#configurations][Configurations]]
 - [[#keybindings][Keybindings]]
 - [[#contributors][Contributors]]
 - [[#sources][Sources]]

* Description
This layer changes the key bindings in spacemacs to be compatible with the [[http://bepo.fr/][bepo]]
keyboard layout. =bepo= is a keyboard layout optimized for the French language.
This package first switch traditional ~hjkl~ movement keys with ~ctsr~, and then
try to correct the bugs introduced by these changes in other modes/packages.

[[file:img/keymap.png]]

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =bepo= to the existing =dotspacemacs-configuration-layers= list in this
file.

It is possible to customize the layer via some variables.

** Variables
This layer can be customized with two variables:
- bepo-set-enabled-configurations
- bepo-set-disabled-configurations

The first one is used to set the list of configurations to activate, and the
second one to prevent loading certain configurations. If the
=bepo-set-enabled-configurations= is nil, all configurations are loaded.
Otherwise, only the listed configurations are loaded. Any configuration listed
in =bepo-set-disabled-configurations= will never be loaded, whether it is in the
enabled list or not.

#+begin_src emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (bepo :variables bepo-set-disabled-configurations '(org magit))))
#+end_src

** Customization
It is possible to override or add bindings by defining in your own layer (or in
the =user-init=) some functions named =bepo/pre-config-<NAME>= and
=bepo/post-config-<NAME>=. They are respectively called just before and after
the actual configuration of keybindings. =<NAME>= is the name of the
configuration you want to customize, they are listed under [[Configurations]].

Note: If you define some of these functions in your own layer, be sure that the
=bepo= layer is placed after it in the =dotspacemacs-configuration-layers= list.

* Mapping
The mapping correction is the one proposed for vim on the official bepo [[http://bepo.fr/wiki/Vim#Principe][wiki]].
This layer tries to do the following changes when the following letters are used
for *doing a movement*:

- Map the movements keys under the right hand's fingers:
  - ~c → h~
  - ~t → j~
  - ~s → k~
  - ~r → l~

- Map lost functionalities back to some keys:
  - ~h → r~
  - ~j → t~
  - ~k → s~
  - ~l → c~

The equivalent remapping is also valid for uppercase letters, or ~CTRL+KEY~ when
they are used to represent a movement, or to keep the mnemonic between the
lower/upper-case consistent.

Some bepo keys are not used in traditional mapping, mainly because they are not
on the =en-us= keyboard layout. They are used as aliases for other shortcuts:

- Map unused ~é~ key as an alias of ~w~, more useful in vim mode:
  - ~é → w~
  - ~É → W~

- Map indentation on direct-access keys:
  - ~» → >~
  - ~« → <~

Some default configurations are also not optimal for vim, so the following
defaults are changed:

- Change =evil-escape= escape combination to something faster to type, while
  being nearly nonexistent in French or English words:
  - ~fd → gq~

- In =avy=, the key used to select words/lines are remapped to the 8 characters
  under the fingers:
  - ~a u i e t s r n~

- Add ~«~ and ~»~ as operators for =evil-surround=, surrounding text with the
  specified symbols.

In some cases the key remapping will not follow these conventions, mainly
because there are better alternatives, or because some moves don't make sense.

#+begin_verse
Example: In the =magit= status buffer, the ~c~ is used for =commit= by default,
but if we want to follow the conventions, it should be remapped to "move left".
As it is not useful to move left on =magit= because operations are done line by
line the ~c~ is not remapped.
#+end_verse

Note: One difference exists with the wiki version: the ~w~ is *not* remapped to
~C-w~ to avoid having to change its meaning in other modes. Spacemacs provides
already a ~SPC w~ key binding for working with windows.

* Configurations
The available configurations are:

- ace-window
- avy
- buffer-move
- comint-mode
- company
- elfeed
- evil
- evil-escape
- evil-surround
- evil-evilified-state
- evil-window
- eyebrowse
- flycheck-error-list
- helm
- helm-buffers
- helm-files
- helm-locate
- ivy
- magit
- neotree
- org
- ranger
- spacemacs

* Keybindings
This layer is using functions that /automatically/ remap keybindings in a lot of
modes, so it's difficult to list all the keybindings changes.

- You chose to use a different keyboard layout.
- You chose to use the dark side by using evil (because they have :cookie: obviously).
- You chose to use a layer trying to solve the induced mess.
- The price you have to pay is the absence of a keybindings list.

* Contributors
- Fabien Dubosson

* Sources
The bepo logo and the keymap image come from the [[http://bepo.fr/][bepo]] official website. They are
licensed under the [[http://creativecommons.org/licenses/by-sa/3.0/deed.en][CC-BY-SA]].