doc/README

   1 == Overview ==
   2
   3 This package contains files that can be used to alter your keyboard
   4 layout in the system console, within X.org, or anywhere else that
   5 uses xkb (for example, most Wayland compositors):
   6
   7   * Your physical "Alt" keys act like "Ctrl" keys
   8   * Your physical "Ctrl" keys act like "Alt" keys
   9   * Your physical "Caps Lock" key acts like the "Alt" key
  10
  11 In other words, we put those keys where they lived on the space-cadet
  12 keyboard <https://en.wikipedia.org/wiki/Space-cadet_keyboard>. This
  13 makes Emacs (and any readline-based application) easier to use, I
  14 promise.
  15
  16 (The console map probably only works on i386 qwerty keyboards, because
  17 that's all I have.)
  18
  19 The files:
  20
  21 1. src/console.map
  22
  23    This affects the Linux system console and virtual terminals; that
  24    is, the things that you switch between with Ctrl-Alt-FN, and the
  25    thing that you're looking at before you start your graphical
  26    desktop environment. The console.map file is input for the
  27    "loadkeys" utility that is part of KBD project
  28    <http://kbd-project.org/> and is provided by sys-apps/kbd on
  29    Gentoo.
  30
  31 2. src/Xmodmap
  32
  33    This affects the X.org system, and your graphical terminals. It
  34    should be fed into the "xmodmap" utility that is part of X.org
  35    and which is provided by x11-apps/xmodmap on Gentoo.
  36
  37 3. src/xkb/symbols/emacs-keys
  38
  39    This is an xkb <https://xkbcommon.org/> keyboard layout file and it
  40    affects anything that uses libxkbcommon for keyboard support. That
  41    of course includes X11 itself, but the main reason this file exists
  42    is to support Wayland. Under X11, the Xmodmap file is easier.
  43
  44
  45 == Installation ==
  46
  47 The build system installs each of these files to $(datadir)/emacs-keys.
  48
  49 The console.map and Xmodmap files can be loaded directly from that
  50 location; for example,
  51
  52   $ loadkeys /usr/share/emacs-keys/console.map
  53   $ xmodmap /usr/share/emacs-keys/Xmodmap
  54
  55 But you probably don't want to do that every time you log in.
  56
  57 === Xmodmap ===
  58
  59 For the Xmodmap file, you would typically add something like the
  60 following to your ~/.xinitrc,
  61
  62   emacsmodmap=/usr/share/emacs-keys/Xmodmap
  63   if [ -f $emacsmodmap ]; then
  64     xmodmap $emacsmodmap
  65     xmodmap $emacsmodmap
  66   fi
  67
  68 The call to xmodmap doesn't work unless you do it twice, and don't ask
  69 me why.
  70
  71 === console.map ===
  72
  73 If you're lucky enough to use OpenRC, the console map can be loaded
  74 automatically. OpenRC starts a "keymaps" service at boot time. The
  75 configuration file for that service is usually located at
  76 /etc/conf.d/keymaps, and if you set, for example,
  77
  78   extended_keymaps="/usr/share/emacs-keys/console.map"
  79
  80 in there, then OpenRC will load the emacs keymap on top of your
  81 default one when the system boots.
  82
  83 Systemd can probably do this too, but you're on your own there.
  84
  85 === xkb ===
  86
  87 The xkb layout needs to be installed where libxkbcommon will look for
  88 it. Rather than muck with system paths, we assume that you'll be
  89 configuring the keyboard for only one user (i.e. you). The per-user
  90 xkb configuration typically goes in $XDG_CONFIG_HOME/xkb, and the
  91 variable $XDG_CONFIG_HOME defaults to ~/.config in your home
  92 directory. Your ultimate goal is therefore to make the
  93 xkb/symbol/emacs-keys file available under ~/.config.
  94
  95 The best way to do this is with a symlink:
  96
  97   $ ln -s /usr/share/emacs-keys/xkb/ ~/.config/
  98
  99 Now, to use it, all you have to do is tell whatever program you're
 100 using to use the "emacs-keys" xkb_layout. For example, the Sway window
 101 manager can be configured with,
 102
 103   input type:keyboard {
 104     xkb_layout "emacs-keys"
 105   }
 106
 107 Other programs are configured similarly.