New article: xkb tweaks

content/custom_xkb_tweaks.rst

@@ -0,0 +1,95 @@
+Creating own XKB tweaks
+@@@@@@@@@@@@@@@@@@@@@@@
+
+:slug: custom-xkb-tweaks
+:date: 2024-04-17 16:40
+:tags: lifehack, software, linux
+:category: technology
+:keywords: xkb, wayland, unprivileged tweaks
+:lang: en
+:translation: false
+:status: published
+
+Debugging this took me a bit too long, so I want to write about the caveat.
+
+My problem: My laptop does not have PageUp and PageDown keys, and many other
+keyboards I use have similar deficiencies. And I use various environments and
+various systems, some of which are shared with other people who don't need/want
+my tweaks. IOW: I want something generic, but it must be confined to my user –
+no system-wide daemon, no udev remapping. (I mostly ended up with these
+solutions when I searched for a way to remap keys on Wayland.)
+
+Requirements: xkbcommon implementation of XKB with utilities. It is quite
+common these days (duh…), but you could probably just compile this yourself if
+you don't have it.
+
+The tweaking
+============
+
+The `xkbcommon guide
+<https://xkbcommon.org/doc/current/user-configuration.html>`__ tells us that we
+can inspect the files in [#lazy]_ ``/usr/share/X11/xkb`` for the source files
+and just write our bits to ``~/.config/xkb/symbols/ledoian``. In particular, I
+added this snippet to remap keyboard brightness controls to PageUp/Down::
+
+    partial
+    xkb_symbols "qs" {
+        key <I238> {[ Prior ]};
+        key <I237> {[ Next ]};
+    };
+
+The key identifiers are taken e.g. from ``xkbcli interactive-wayland``.
+However, this is KcCGST [#kccgst-vs-rmlvo]_ description, but layouts are
+configured using RMLVO, so I need to define an option and tell what it should
+do. The guide wants me to create ``~/.config/xkb/rules/evdev`` with::
+
+    ! option = symbols
+      ledoian:qs    = +ledoian(qs)
+    ! include %S/evdev
+
+Now I just add ``ledoian:qs`` [#option-vs-symbol]_ to my keyboard configuration
+and… it does not work. For this, at all, but if I remap e.g. the L key, that
+gets applied. The problem? That included file says that the default keyboard
+model always includes ``inet(evdev)`` symbols. Those symbols set the default
+meaning of the keys, but since that got applied later, it overrides my tweak.
+
+Solution: first include, then add my option.
+
+How to debug: read stuff that ``xkbcli compile-keymap --verbose`` tells you
+(pass your config as ``--layout``, ``--variant``, ``--options``, …). At the top
+it says what it does::
+
+    xkbcommon: DEBUG: Include path added: /home/ledoian/.config/xkb
+    xkbcommon: DEBUG: Include path added: /usr/share/X11/xkb
+    xkbcommon: DEBUG: Compiling from RMLVO: rules 'evdev', model 'pc105', layout 'us', variant '(null)', options '(null)'
+    xkbcommon: DEBUG: Compiling from KcCGST: keycodes 'evdev+aliases(qwerty)', types 'complete', compat 'complete', symbols 'pc+us+inet(evdev)'
+
+My option would appear before the ``inet(evdev)`` part.
+
+A note about X11
+================
+
+X11 uses a separate implementation of XKB (the original one, in fact), which
+does _not_ look into the user directory, just the system ones. However, you can
+compile the keymap yourself using ``xkbcli compile-keymap [KEYMAP OPTIONS] >
+my_layout.xkb`` and load it into the X server with ``xkbcomp my_layout.xkb $DISPLAY``.
+
+-------
+
+.. [#lazy] This is not technically accurate, really the paths reference
+   ``$XDG_something`` variables. I am lazy and just copied my system, so YMMV
+   (probably won't, though).
+
+.. [#kccgst-vs-rmlvo] There are two levels of describing the keymap: the
+   lowlevel one is called KcCGST (short for keycodes, compat, geometry,
+   symbols, types) and is considered to be an implementation detail; the
+   user-facing one is RMLVO (rules, model, layout, variant, options) and that
+   is what you use in the configs, with ``setxkbmap`` &c.
+
+.. [#option-vs-symbol] While both this example and the `upstream
+   <https://www.freedesktop.org/wiki/Software/XKeyboardConfig/>`__ layouts name
+   the symbols and options similarly, I think they don't need to be related –
+   you should be able to put whatever you want in your options to the left of
+   ``=``, the right hand side is the name of the symbol file and if a
+   non-default layout from that file is used, its name is put in the
+   parentheses.