doc/README: update for the forthcoming xkb layout

diff --git a/doc/README b/doc/README
index 6f7e68c02eb310b23b1cae51027f092680818c3e..bd8033694c268ef71d25ab9fedc172c7d265d13e 100644 (file)
--- a/doc/README
+++ b/doc/README
@@ -1,18 +1,20 @@
 == Overview ==
 
-This package contains two files that can be used to alter your
-keyboard layout, either in the system console or within X.org (or
-both):
+This package contains files that can be used to alter your keyboard
+layout in the system console, within X.org, or anywhere else that
+uses xkb (for example, most Wayland compositors):
 
-  * Your physical "Alt" keys act like "Ctrl" keys.
-  * Your physical "Ctrl" keys act like "Alt" keys.
-  * Your physical "Caps Lock" key acts like the "Alt" key.
+  * Your physical "Alt" keys act like "Ctrl" keys
+  * Your physical "Ctrl" keys act like "Alt" keys
+  * Your physical "Caps Lock" key acts like the "Alt" key
 
-This makes emacs (and any readline-based application) easier to use, I
+In other words, we put those keys where they lived on the space-cadet
+keyboard <https://en.wikipedia.org/wiki/Space-cadet_keyboard>. This
+makes Emacs (and any readline-based application) easier to use, I
 promise.
 
-The console map probably only works on i386 qwerty keyboards, because
-that's all I have.
+(The console map probably only works on i386 qwerty keyboards, because
+that's all I have.)
 
 The files:
 
@@ -20,10 +22,11 @@ The files:
 
    This affects the Linux system console and virtual terminals; that
    is, the things that you switch between with Ctrl-Alt-FN, and the
-   thing that you're looking at before you start X.org. The console.map
-   file is input for the "loadkeys" utility that is part of KBD
-   project <http://kbd-project.org/> and is provided by sys-apps/kbd
-   on Gentoo.
+   thing that you're looking at before you start your graphical
+   desktop environment. The console.map file is input for the
+   "loadkeys" utility that is part of KBD project
+   <http://kbd-project.org/> and is provided by sys-apps/kbd on
+   Gentoo.
 
 2. src/Xmodmap
 
@@ -31,33 +34,79 @@ The files:
    should be fed into the "xmodmap" utility that is part of X.org
    and which is provided by x11-apps/xmodmap on Gentoo.
 
+3. src/xkb/symbols/emacs-keys
+
+   This is an xkb <https://xkbcommon.org/> keyboard layout file and it
+   affects anything that uses libxkbcommon for keyboard support. That
+   of course includes X11 itself, but the main reason this file exists
+   is to support Wayland. Under X11, the Xmodmap file is easier.
+
 
 == Installation ==
 
-Either of those files can be loaded manually regardless of where they
-live; for example,
+The build system install each of these files to $(datadir)/emacs-keys.
+
+The console.map and Xmodmap files can be loaded directly from that
+location; for example,
+
+  $ loadkeys /usr/share/emacs-keys/console.map
+  $ xmodmap /usr/share/emacs-keys/Xmodmap
 
-  $ loadkeys /path/to/console.map
-  $ xmodmap /path/to/Xmodmap
+But you probably don't want to do that every time you log in.
 
-The build system will install these files to $(datadir)/emacs-keys by
-default. For the Xmodmap file, that's about as good as it gets. To use
-it, you will typically add something like the following to your
-~/.xinitrc,
+=== Xmodmap ===
+
+For the Xmodmap file, you would typically add something like the
+following to your ~/.xinitrc,
 
   emacsmodmap=/usr/share/emacs-keys/Xmodmap
   if [ -f $emacsmodmap ]; then
-    # It doesn't work unless you do it twice, don't ask me why.
     xmodmap $emacsmodmap
     xmodmap $emacsmodmap
   fi
 
-The console map on the other hand can be loaded by OpenRC, which
-starts a "keymaps" service at boot time. The configuration file for
-that service is usually located at /etc/conf.d/keymaps, and if you
-set, for example,
+The call to xmodmap doesn't work unless you do it twice, and don't ask
+me why.
+
+=== console.map ===
+
+If you're lucky enough to use OpenRC, the console map can be loaded
+automatically. OpenRC starts a "keymaps" service at boot time. The
+configuration file for that service is usually located at
+/etc/conf.d/keymaps, and if you set, for example,
 
   extended_keymaps="/usr/share/emacs-keys/console.map"
 
 in there, then OpenRC will load the emacs keymap on top of your
 default one when the system boots.
+
+Systemd can probably do this too, but you're on your own there.
+
+=== xkb ===
+
+The xkb layout needs to be installed where libxkbcommon will look for
+it. Rather than muck with system paths, we assume that you'll be
+configuring the keyboard for only one user (i.e. you). The per-user
+xkb configuration typically goes in $XDG_CONFIG_HOME/xkb, and the
+variable $XDG_CONFIG_HOME defaults to ~/.config in your home
+directory. Your ultimate goal is therefore to make the
+xkb/symbol/emacs-keys file available under ~/.config.
+
+The best way to do this is with a symlink:
+
+  $ mkdir -p ~/.config/xkb/symbols
+  $ ln -s /usr/share/emacs-keys/xkb/symbols/emacs-keys \
+          ~/.config/xkb/symbols/
+
+The name of the symlink and the "symbols" directory that contains it
+are important.
+
+Now, to use it, all you have to do is tell whatever program you're
+using to use the "emacs-keys" xkb_layout. For example, the Sway window
+manager can be configured with,
+
+  input type:keyboard {
+    xkb_layout "emacs-keys"
+  }
+
+Other programs are configured similarly.