Skip to content

Commit 3cc8062

Browse files
cmeissnergmzabos
cmeissner
and
gmzabos
authored
New article about xkb layouts (#119)
* New article about xkb layouts * Update 2023-09-25-custom-keyboard-layouts-with-xkb.md * fix failures in spelling and grammar --------- Co-authored-by: Gerald-Markus Zabos <[email protected]>
1 parent 59cc1f5 commit 3cc8062

File tree

6 files changed

+168
-0
lines changed

6 files changed

+168
-0
lines changed

‎.pyspelling.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
matrix:
2+
- name: Article Markdowns
3+
aspell:
4+
lang: en
5+
d: en_US
6+
sources:
7+
- _posts/2023-09-25-custom-keyboard-layouts-with-xkb.md

‎_posts/2022-02-07-custom-keyboard-layout.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,13 @@ title: Custom Keyboard Layouts on Ubuntu
44
subtitle: How to define and install a custom keyboard layout
55
author: cmeissner
66
tags: [custom keyboard layout, keyboard layout, keyboard variant, ubuntu]
7+
last-update: 2023-09-14
78
---
89

10+
{: .box-warning}
11+
There is a updated version on how to make keyboard layouts available and especially safe against `xkeyboard-config` package upgrades.
12+
Please have a look at [Custom Keyboard Layouts with xkb](../2023-09-25-custom-keyboard-layouts-with-xkb).
13+
914
As a developer I prefer to use the us intl. keyboard layout as many symboles are positioned better than on the german keyboard layout.
1015
But on the other side I also have to write texts in german and I need to have access to all german umlauts and symboles. Unfortunately there is no layout that suited in all details to my daily needs. Here comes the ability to define a custom keyboard layout in account.
1116

‎_posts/2023-09-16-custom-keyboard-layouts-with-xkb.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
layout: post
3+
title: Custom Keyboard Layouts with xkb
4+
subtitle: How to define and install a custom keyboard layout
5+
author: cmeissner
6+
tags: [custom keyboard layout, keyboard layout, keyboard variant, ubuntu, fedora, X11, xkb, Wayland]
7+
---
8+
9+
There are different reasons why the definition of custom keyboard layouts can become necessary.
10+
11+
1. A developer prefers to use us intl. Keyboard layout because of the intuitive positioned symbols needed for writing code
12+
2. A writer who is writing texts in more than one language (e.g. English, German, Italian) and doesn’t want to switch between different layout but want able to use all the special characters in each language
13+
14+
There are probably a number of other reasons, but we the examples shown above should be enough.
15+
16+
## xkeyboard configuration
17+
18+
In modern Linux distributions the `xkb` facility is a core component for defining and providing keyboard layouts, variants and many more. This guide will show how to reach the goal of defining a custom layout and make it available in `gnome-settings` app.
19+
20+
### xkb system configuration
21+
22+
The configuration for `xkb` can be found in `/usr/share/X11/xkb`. There are two subdirectories we are interested in.
23+
24+
1. `symbols`, here you find keyboard layout definitions
25+
2. `rules`, provides files for mapping a definition to a configuration
26+
27+
{: .note-warning}
28+
In our former article ([Custom Keyboard Layouts on Ubuntu](../2022-02-07-custom-keyboard-layout)) we did our changes within these directories. This procedure is not that good, as custom changes will be reverted on each `xkeyboard-config` package upgrade.
29+
30+
The following text will focus on how to configure `xkb` with custom keyboard layouts and make them per user or globally available and upgrade safe.
31+
32+
### xkb user configuration
33+
34+
Locating `xkb` configurations is done in `libxkbcommon` and this library walks through a set of directories to find configurations. These search paths make it possible to make configurations either per user or globally available. The following paths will be searched in the given order.
35+
36+
1. `$XDG_CONFIG_HOME/xkb/`, or `$HOME/.config/xkb/` if the `$XDG_CONFIG_HOME` is not defined
37+
2. `$HOME/.xkb/`
38+
3. `$XKB_CONFIG_EXTRA_PATH/xkb` if `$XKB_CONFIG_EXTRA_PATH` is defined, otherwise `<sysconfdir>/xkb` (mostly this is /etc/xkb)
39+
4. `$XKB_CONFIG_ROOT/X11/xkb` if `$XKB_CONFIG_ROOT` is defined, otherwise `<datadir>/X11/xkb/` (mostly this is /usr/share/X11/xkb)
40+
41+
We will show how to create your custom layout with option 1). To make your layout machine globally available, you can create the discussed files and directories in the base mentioned in option 3).
42+
43+
## creating you layout
44+
45+
To cover all the use cases mentioned above, we derive our layout from layout `us` variant `alt-intl` as this combination offers most of the keys a US Intl keyboard has. It also defines the needed German umlauts. But it does not define a key combo for e.g. the umlaut ß and also a key combo for the paragraph sign and cent sign was missing.
46+
47+
We also need a ``` sign to write Italian letters with an accent. To achieve this, we put the backtick as a dead key in our layout.
48+
49+
Create a file in `~/.config/xkb/symbols` (e.g. `codeaffen`).
50+
51+
<!-- markdownlint-disable MD033 -->
52+
{% highlight text linenos %}
53+
{% raw %}
54+
partial alphanumeric_keys
55+
xkb_symbols "usde" {
56+
57+
include "us(alt-intl)"
58+
59+
key <TLDE> { [ dead_grave, asciitilde, section, plusminus ] };
60+
key <AC02> { [ s, S, ssharp, U1E9E ] };
61+
key <AB03> { [ c, C, cent, copyright ] };
62+
63+
include "level3(ralt_switch)"
64+
65+
};
66+
{% endraw %}
67+
{% endhighlight %}
68+
<!-- markdownlint-enable MD033 -->
69+
70+
1. We define our layout within the `xkb_symbols` section
71+
2. Foremost, we include the layout `us(alt-intl)` which works well for us so far, and we don’t want to define all the keys again
72+
3. We define the tilde key to work as `backtick` (dead key) and `tilde` (/w shift). In combination with `ralt` we define the `section` key and the `plusminus` key (/w shift)
73+
4. We define the s key to work as `sS` and `ß` and upper umlaut ß (/w shift)
74+
5. We define the c key to work as `cC` and in combination with `ralt` the cent sign and the copyright sign (/w shift)
75+
6. Last, we also include the `level3(ralt_switch)` section which defines the `ralt` key to switch between the `altgr` layer of defined keys
76+
77+
## adding an option
78+
79+
To make your layout an option, you need to create a `evdev` file in `~/.config/xkb/rules` with the following content.
80+
81+
```evdev
82+
! option = symbols
83+
codeaffen:usde = +codeaffen(usde)
84+
85+
! include %S/evdev
86+
```
87+
88+
1. We work on `option = symbols` section in `evdev` file
89+
2. We define an option in `symbols` section to map `codeaffen:usde` to `usde` section in `symbols/codeaffen`
90+
3. Last, we include the default `evdev` file. If you miss this line it can happen that you can log in in Gnome but the session will crash
91+
92+
## make layout discoverable
93+
94+
To make your layouts discoverable, tools rely on `evdev.xml` file. To add your custom layout, we need to create a `evdev.xml` file in `~/.config/xkb/rules` directory as followed.
95+
96+
<!-- markdownlint-disable MD033 -->
97+
{% highlight xml linenos %}
98+
{% raw %}
99+
<?xml version="1.0" encoding="UTF-8"?>
100+
<!DOCTYPE xkbConfigRegistry SYSTEM "xkb.dtd">
101+
<xkbConfigRegistry version="1.1">
102+
<layoutList>
103+
<layout>
104+
<configItem>
105+
<name>codeaffen</name>
106+
<shortDescription>usde</shortDescription>
107+
<description>English (US, codeaffen custom keymap)</description>
108+
<countryList>
109+
<iso3166Id>US</iso3166Id>
110+
<iso3166Id>DE</iso3166Id>
111+
</countryList>
112+
<languageList>
113+
<iso639Id>eng</iso639Id>
114+
<iso639Id>deu</iso639Id>
115+
</languageList>
116+
</configItem>
117+
</layout>
118+
</layoutList>
119+
</xkbConfigRegistry>
120+
{% endraw %}
121+
{% endhighlight %}
122+
<!-- markdownlint-enable MD033 -->
123+
124+
1. We defined a new layout named `codeaffen`. This will map to the definition file created before
125+
2. We also define a short description `usde`. The short description will be shown in the layout switch tray icon (if more than on layout is configured)
126+
3. The description will be shown in the configuration dialog (e.g. in Gnome, Tray chooser)
127+
4. We bound the layout to all languages with ISO ID `eng` and `deu` as well as countries with ISO ID `US` and `DE`
128+
129+
![Keyboard Layout Tray Chooser](../assets/img/select_keyboard_layout_tray.png){:.mx-auto.d-block :}
130+
131+
## set up your keyboard
132+
133+
{: .box-note}
134+
**Note:** It can be necessary to logout and relogin to make the layout available.
135+
136+
Now you can select your newly defined layout in the configuration dialog.
137+
138+
![Select your keyboard layout](../assets/img/select_keyboard_layout_fedora.png){:.mx-auto.d-block :}
139+
140+
From now on, you can use all the defined key combos as you would normally do.
141+
142+
## last thoughts
143+
144+
### Gnome
145+
146+
To use the `View Keyboard Layout` option in `Gnome` it to get a picture of your desired keyboard layout, you need to make your symbols file also in the system directory available. A symlink is absolutely enough and upgrade safe.
147+
148+
```shell
149+
sudo ln -s ~/.config/xkb/symbols/codeaffen /usr/share/X11/xkb/symbols
150+
```
151+
152+
If the file is not accessible from the system path, you will either get an empty window (Fedora 38) or an error message (e.g. Ubuntu 22.04).
153+
154+
### localectl
155+
156+
An in that way configured custom layout is not accessible for `localectl` as this tool only opens a single file from `/usr/share/X11/xkb/rules`. A [bug report](https://github.com/systemd/systemd/issues/29178){:target="_blank"} was opened in `systemd` project.

‎assets/img/select_keyboard_layout_fedora.png‎

83.3 KB
Loading

‎assets/img/select_keyboard_layout_tray.png‎

32.7 KB
Loading

‎assets/img/view_keyboard_layout.png‎

64.2 KB
Loading

0 commit comments

Comments
 (0)