How does XKB actually work?

BertMv · 2024-01-09 14:00:34

I have ordered some custom keycaps with a layout that is customised to my needs; so I need a (system-wide) custom keyboard layout. Since I am using Wayland (Plasma) I cannot use xmodmap (right?). I have been reading the arch wiki topic on XKB and went through the first few pages of google finds on "linux create custom keyboard layout", but after almost 3 weeks I must confess I am unable to wrap my head around how XKB works. The files in /urs/share/X11/xkb/ are not very intuitive nor self-documenting. I get some of the general way it all seems to work, but the details elude me. Can anyone either explain to me like I'm 5 how I would go about creating a custom keyboard layout (preferably in the xdg base directory) based of e.g. the standard us layout. If there is a tutorial or article somewhere that explains all the workings of xkb in detail (files, keywords etc.) that would help as well.

Some of the things I do not get are the keywords like "partial", "hidden", "! layout" etc. While some articles (and the wiki) do mention them, it seems I lack some basic knowledge which is assumed the reader has?

While I primarily want to make a custom layout, if I can get my head around the whole of xkb I would like to take a shot at writing an editor, since that is sorely missing right now.

Trilby · 2024-01-09 14:54:09

I agree documentation for the details of this is sorely lacking - and I am not equipped to directly help with that. However, I can note that using wayland doesn't change much. Everything about writing / editing layouts is identical in X11 and wayland, the only difference is that under X11 you can set your preferred layout via environment variable or via Xorg configuration; in wayland you set it also via environment variable, or in some cases your compositor may have a configuration for it. Using the environment variable approach seems much better to me as it will then apply in all cases (including switching compositors and / or back to X11).

I have my own custom layout which I set in my shell profile before starting my compositor:

export XKB_DEFAULT_LAYOUT=us-custom

In my case, my custom layout is only a very minimal revision to the base US layout to turn a "PrtSc" key into a modifier:

$ cat .xkb/symbols/us-custom 
default partial alphanumeric_keys modifier_keys
xkb_symbols "basic" {
    include "us"
    name[Group1]= "English (US, Custom)";

    key <PRSC> { [ Hyper_L ] };
    modifier_map Mod5 { Hyper_L };
};

The content of that custom file was arrived at after much flailing, frustration, and guess-and-check as I also can see no logic in these layout files' syntax.

Note that if there are good tools for modifying these layout files for X11, you could run one under X (or XWayalnd) to generate a layout file, then just specify that layout via the environment variable.

Last edited by Trilby (2024-01-09 14:56:07)

BertMv · 2024-01-09 15:01:34

Thanks for your snippet. Every little piece of info helps. And I'm glad I am not alone in my failure to understand the syntax. I was starting to feel stupid ;p

seth · 2024-01-09 15:17:12

explain to me like I'm 5

You ought to be in bed by now, young man.

--

"partial" is never a thing, it's gonna be "partial alphanumeric_keys" or so what leaves other blocks (function, keypad, modifiers) alone.
hidden is for stuff that only gets included
Neither is reelvant to write a custom layout.

I've never seen "! layout" - example?

BertMv · 2024-01-15 09:30:58

@seth: "! layout" can be found e.g. in /usr/share/X11/xkb/rules/evdev but that is unimportant now.

I managed to get a custom layout working, although the way I done it isn't very elegant. The problem seems to be that XKB really doesn't allow for custom user layouts. Because if you add a new layout to $XDG_CONFIG_HOME/xkb/symbols you also need to add that layout to /usr/share/X11/rules/evdev.xml which means changing a system file. I suppose one could copy that file to $XDG_CONFIG_HOME but if the system file ever changes in an update, you'd need to copy over those changes again, so that isn't very future/fool-proof.

In the end I simply copied /usr/share/X11/xkb/symbols/us to $XDG_CONFIG_HOME/xkb/symbols/us and altered that file but keeping the name. Still working out some details on the changes (extra modifier keys for one), but got most of it working.

EDIT: After some fooling around, it seems $XDG_CONFIG_HOME/xkb/rules/evdev.xl does not overwrite the one in /usr but actually appends it! I am unable to find any documentation on this but it solves at least one problem. Mentioning it here for any future strugglers like me.

Last edited by BertMv (2024-01-15 11:19:57)

seth · 2024-01-15 09:41:40

Ok, but that's a ruleset, not an actual layout.
And the "!" indicates a comment.

Because if you add a new layout to $XDG_CONFIG_HOME/xkb/symbols you also need to add that layout to /usr/share/X11/rules/evdev.xml

No? But you'll most likely have to to get your desktop GUI to list it, yes.

You can just add a layout and select that w/ an xorg config rule or setxkbmap.

BertMv · 2024-01-15 10:25:39

While I agree that rulesets and GUI are not stricktly needed, it would be nice if I could add my keyboard to it and distribute it to my friends. This was a very illuminating read: https://danijozsef.medium.com/the-bazaa … 2de59a1f9a

seth · 2024-01-15 14:10:14

…but Gnome just uses the rule file /usr/share/X11/xkb/rules/evdev. Period. It uses just that. Fuck XKBRULES. If it is a configurable setting, it’s not documented in any Google-indexed location.
In fact, Gnome uses its own XKb settings

XKBRULES in /etc/default/keyboard is a debian/ubuntu thing, it will probably not work at all on arch or anywhere else.
Also nothing in /usr/share/X11/xkb is relevant to the console keyboard at all - it's a copletely different system and the keymaps are inside /usr/share/kbd/keymaps and

md5sum /usr/share/X11/xkb/rules/{base,evdev}.xml

So evdev.xml does stuff the console can't do but base.xml does. O – K

systemd writes xkb & console stuff into /etc/vconsole.conf and I assume debians /etc/default/keyboard will try to do something similar, but derive xkb and console keymaps from a single variable.
Good luck with that indeed.

https://man.archlinux.org/man/extra/xor … .en#XkbDir
Of course that won't do jack squat if gnome uses an own table from its registry, but that's more a gnome than xkb issue.

I've not read it but it's linked in the english wikipedia: https://medium.com/@damko/a-simple-humb … 1ad5e13450

BertMv · 2024-01-15 14:17:47

Thanks for those links! For now I got most of the stuff I want working and gonna take a break from this issue for a few days. This is giving me a headache. Who would have thought such a basic piece of hardware like a keyboard would be so complicated to understand. lol

Arch Linux

#1 2024-01-09 14:00:34

How does XKB actually work?

#2 2024-01-09 14:54:09

Re: How does XKB actually work?

#3 2024-01-09 15:01:34

Re: How does XKB actually work?

#4 2024-01-09 15:17:12

Re: How does XKB actually work?

#5 2024-01-15 09:30:58

Re: How does XKB actually work?

#6 2024-01-15 09:41:40

Re: How does XKB actually work?

#7 2024-01-15 10:25:39

Re: How does XKB actually work?

#8 2024-01-15 14:10:14

Re: How does XKB actually work?

#9 2024-01-15 14:17:47

Re: How does XKB actually work?

Board footer