xkb2kbdlua

Export a keymap from xkeyboard-config format using libxkbcommon into Arcan's keyboard.lua format. Some functionality is only supported with a modified keyboard.lua available in this repository.

This essentially moves part of the policy from libxkbcommon used in some Arcan's platforms to Lua, and makes it hackable. However, not all functionality present in libxkbcommon is currently supported.

Usage

./xkb2kbdlua -r rules -m model -l layout -v variant -o options -- export xkbcommon keyboard layout to Arcan's keyboard.lua format.
Defaults: -r "" -m "pc105" -l "ua(winkeys)" -v "" -o "grp:caps_toggle,compose:ralt,grp_led:scroll"

Extra options:
	-c locale	Export XCompose data for the specified locale.
	-C filename	Export XCompose data from the specified file. Requires -c argument as well.
	-s	Read the keymap from stdin in the serialized format instead of using RMLVO options.
	-R	Read the mappings from xkb_mod_mask_t to arcan modifiers from command line.
	-T	Dump the builtin mappings from xkb_mod_mask_t to arcan modifiers.
	-n filename	Output the lua keymap to the specified file.

For multi-layout keymaps, use a modified keyboard.lua bundled in this repository, and use -n option to specify the output file name.

You can use the tester appl to test the functionality.

$ make # requires libxkbcommon and xkeyboard-data.
$ ./xkb2kbdlua -l "us,fr" -n English_French
$ cp English_French.lua ./tester/devmaps/keyboard/
$ cp keyboard.lua ./tester/builtin/
$ arcan ./tester English_French.lua

Note that the mapping of XKB modifier masks to Arcan ones is hardcoded, though it specifies a relatively sensible policy. Feel free to replace with what suits your needs.

XCompose and dead key support

xkb2kbdlua can convert compose rulesets in standard XCompose format.

• Use -c <locale> argument to include a compose ruleset for the specified locale. You can have a look in /usr/share/X11/locale/ for a locale with a ruleset useful for your purposes. When converting a ruleset for a specific locale, ~/.XCompose file is also loaded if it is present.
• Use -C <filename> to load compose rules from a file. Note that the -c <locale> argument is mandatory in this case.

For dead key support, you should use a compose ruleset that includes them, e.g. from the en_US.UTF-8 locale.

You can find more details in the libxkbcommon documentation.

$ ./xkb2kbdlua -l "us" -c en_US.UTF-8            # include a large ruleset for Latin script based languages.
$ ./xkb2kbdlua -l "us" -C xcrules -c en_US.UTF-8 # include a ruleset from `xcrules` file.
$ ./xkb2kbdlua -l "us" -C XCompose.custom        # will not work due to missing `-c` argument.

Exported rulesets can be used with the keyboard.lua script from this repository. You should call KEYBOARD:compose_feed(iotbl) after calling KEYBOARD:patch(iotbl) in your appl to drive the compose state machine, it will automatically set iotbl.utf8 field. Note that various appls expect KEYBOARD:patch() to be idempotent, so hiding compose mechanism there would not work. You can find an example of how to use compose input in the tester appl.

Bugs are possible, as default tables are prohibitively large for comprehensive testing.

Troubleshooting

• Missing mapping for mask ... warning: add the necessary mapping of XKB modifier mask to the Arcan one into init_mappings function.

Missing and untested functionality:

• Feedback (audio/video) into the window manager.
• Dead keys support, Compose key (durden integration).
• Per-window keyboard layouts.
• Switching keyboard layouts using Ctrl+Shift, Alt+Shift is a bit brittle and requires improvements.
• Mapping of XKB to Arcan modifier masks needs to be improved.
• Not planned: Information about preserve keyword in the xkeyboard serialized keymap is not exposed via libxkbcommon APIs, and currently can be extracted only via parsing the serialized keymap. This limits what kind of keybinding can be successfully exported.
• Untested: sending the original serialized xkbcommon keymap to X11/Wayland clients.