From 6e0d445832f65e722b639bb4afc86ebeb3421efb Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Sun, 3 Dec 2023 12:27:43 -0500 Subject: [PATCH] doc/README: update for the forthcoming xkb layout --- doc/README | 101 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 75 insertions(+), 26 deletions(-) diff --git a/doc/README b/doc/README index 6f7e68c..bd80336 100644 --- 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 . 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 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 + 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 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. -- 2.43.2