Differences between revisions 57 and 107 (spanning 50 versions)
Revision 57 as of 2022-05-22 06:28:01
Size: 10920
Editor: OsamuAoki
Comment: Add and reorganize some info under Tips (consistent color)
Revision 107 as of 2022-05-29 07:34:16
Size: 26419
Editor: OsamuAoki
Comment: Markup consistency No-` etc.
Deletions are marked like this. Additions are marked like this.
Line 14: Line 14:
== Keyboard configuration ==

To configure the keyboard, you have to install DebianPkg:keyboard-configuration. The package DebianPkg:console-setup is also needed.
See [[https://www.debian.org/doc/manuals/debian-reference/ch08.en.html#_the_keyboard_input|"The keyboard input" in debian-reference]], too.

== Basic keyboard configuration (Kernel and X) ==

To configure the keyboard for Linux kernel and X, you have to install DebianPkg:keyboard-configuration. The package DebianPkg:console-setup is also needed.
Line 26: Line 28:
As usual, it will prompt you for the ''model'' of keyboard (what the keyboard ''*is*''), and then for the keyboard ''layout'' (what the keys should ''*do*''). Use this tool to change your keyboard map, e. g. from ''QWERTY'' to ''QWERTZ'' or to ''Dvorak'', or for non-English layouts.  1. Menu for '''Keyboard model''' (what the keyboard '''*is*''') is presented. If not sure, choose:
   * "Generic 104-key PC" for US-type keyboard with "Windows-key"
   * "Generic 105-key PC" for ISO-type keyboard with "Windows-key" (and JIS-type keyboard with "Windows-key")
   * "Generic 104-key PC" or "Generic 105-key PC" can be chosen as above for smaller keyboard on laptop/note PC.
 2. Menu for '''Country of origin for the keyboard''' is presented. If not sure for this, choose:
   * "English (US)" for "QWERTY"-keyboard
   * "German" for "QWERTZ"-keyboard
   * "French" for "AZERTY"-keyboard
   * "Japanese" for "QWERTY"-keyboard with extra keys aimed for Japanese.
 3. Menu for '''Keyboard layout''' (what the keys should '''*do*''') is presented. If not sure for this, choose:
   * "English (US)" for plain layout (English)
   * "English (intl., with AltGr dead keys)" to have access to accented characters etc.
   * "Default" for plain layout (German, French)
   * "Japanese" for plain layout (Japanese)
   * "Dvorak" etc. if you want.
Line 35: Line 51:
== Modern keyboard configuration (input method) == The Linux kernel and the X Window System process keyboard inputs independently. The '''{{{keyboard-configuration}}}''' package take care their configuration.

For the X Window System, keyboard inputs are processed by the X Window System using [[https://en.wikipedia.org/wiki/X_keyboard_extension|X keyboard Extension (XKB)]]. The resulting keyboard data are passed to the X applications through X connection with [[https://en.wikipedia.org/wiki/X_Input_Method|X Input method (XIM)]] protocol.

== Modern keyboard configuration (IM) ==
Line 39: Line 59:
The installation of the input method framework package such as DebianPkg:ibus (or DebianPkg:fcitx5) together with associated packages enables to support all languages.

When any of the input method framework packages are installed and activated, the X Window based keyboard configuration settings are ignored.
The installation of the input method (IM) framework package such as DebianPkg:ibus (or DebianPkg:fcitx5) together with associated packages enables to support all languages.

For the modern GUI system, keyboard inputs are processed by IM using IM engines. For GTK and QT applications, the resulting keyboard data are passed to them through [[https://en.wikipedia.org/wiki/D-Bus|D-Bus]] communication. For X applications, the resulting keyboard data are passed to them through X connection with [[https://en.wikipedia.org/wiki/X_Input_Method|X Input method (XIM)]] protocol. If the GUI system is [[Wayland]], xwayland facilitates X connection for X applications.

(Please don't get confused by IM and XIM.)
Line 45: Line 67:
For non-GNOME system, the stand alone GUI configuration command '''{{{ibus-setup}}}''' can set up the input methods for DebianPkg:ibus. Under those desktop environments, menu entry of their keyboard configuration utility or pop-up menu entry offered by clicking the associated tray icon may start '''{{{ibus-setup}}}''' for you. For KDE, this menu is '''{{{System_settings -> Hardware -> Input_devices/keyboard}}}'''. For non-GNOME system, the stand alone GUI configuration command '''{{{ibus-setup}}}''' can set up IM framework for DebianPkg:ibus. Under those desktop environments, menu entry of their keyboard configuration utility or pop-up menu entry offered by clicking the associated tray icon may start '''{{{ibus-setup}}}''' for you.

For KDE, configuration of '''ibus''' is '''{{{System_settings -> Hardware -> Input_devices/keyboard}}}'''. Tray icon is available as '''kimpanel''' in DebianPkg:plasma-widgets-addons package.

See [[I18n/ibus]] and [[I18n/Fcitx5]] for more.
Line 49: Line 75:
People who wish to set up a single keyboard input environment for multiple (European) languages without the input method framework should consider following configuration strategy.

 * If the input method package is installed, deactivate it by executing '''{{{im-config -n none}}}'''.
There are 2 strategies for the multi-language keyboard configuration. Mixing these 2 strategies for keyboard input will create unmanageable system. So please don't do mix.

=== Old fashioned strategy ===

People who wish to set up a single keyboard input environment for multiple (European) languages in old fashioned way without the IM framework should consider following configuration strategy.

 * If an IM framework package is installed, deactivate it by executing '''{{{im-config -n none}}}'''.
Line 53: Line 83:
 * Select the desirable keyboard layout. E.g., English (US International AltGr Unicode combining,alternative)

People who wish to set up multiple dynamically-switchable keyboard input environments for multiple languages should consider following configuration strategy.

 * Install input method framework package such as DebianPkg:ibus
 * (optional) Install pertinent input method engine package such as DebianPkg:ibus-anthy
 * Activate desirable input engine by adding it from menu such as '''{{{Settings -> Keyboard --> Input Sources}}}'''.
 * Switch among input methods with by pressing '''{{{GUI-SPACE}}}'''.

Please note that the input method framework such as DebianPkg:ibus provides functionality to enter many Unicode characters for European languages without additional engine packages after the proper GUI based configuration.
 * Select the desirable keyboard layout. E.g., English (US International AltGr Unicode combining, alternative)
 * (optional) Set up the keyboard behavior using [[https://en.wikipedia.org/wiki/X_keyboard_extension|X keyboard Extension (XKB)]].
     * This configuration may be done by X startup code configured by the GUI environment or '''{{{xkbcomp}}}''' call in {{{~/.xsession}}}.
 * X applications communicate with the X server for the keyboard input through X connection with [[https://en.wikipedia.org/wiki/X_Input_Method|X Input Method (XIM)]] protocol.

This is offered as backward compatibility.

=== Modern strategy ===

People who wish to set up multiple dynamically-switchable keyboard input environments in modern way for multiple languages should consider following configuration strategy.

 * Install input method (IM) framework package such as DebianPkg:ibus
 * (optional) Install pertinent IM engine package such as DebianPkg:ibus-anthy
 * Activate desirable IM engine/keyboard layout by adding it from menu such as '''{{{Settings -> Keyboard -> Input Sources}}}''' and configure them.
 * Switch among IM engines/keyboard layout with by pressing '''{{{GUI-SPACE}}}'''.
 * X applications communicate with the IM daemon server such as '''ibus-daemon''' identified by '''{{{XMODIFIERS}}}''' for the keyboard input with [[https://en.wikipedia.org/wiki/X_Input_Method|X Input Method (XIM)]] protocol.
 * GTK applications communicate with the IM such as DebianPkg:ibus with library specified by '''{{{GTK_IM_MODULE}}}''' for the keyboard input through [[https://en.wikipedia.org/wiki/D-Bus|D-Bus]] communication.
 * QT applications communicate with the IM such as DebianPkg:ibus with library specified by '''{{{QT_IM_MODULE}}}''' for the keyboard input through [[https://en.wikipedia.org/wiki/D-Bus|D-Bus]] communication.

Please note that the IM framework such as DebianPkg:ibus provides its internal functionality equivalent of [[https://en.wikipedia.org/wiki/X_keyboard_extension|X keyboard Extension (XKB)]] to enter many Unicode characters for European languages without additional engine packages and its configuration is available in '''{{{GNOME Tweaks}}}''' program under '''{{{Keyboard & Mouse -> Additional Layout Options}}}'''. See [[#How_to_dynamically_manage_input_source_settings_from_the_command_line|below for the non-GUI method to set these]].

This is offered as future direction.

See "[[#IM and XIM|IM and XIM]]" for cares required to use IM smoothly.
Line 73: Line 117:

# Consult the keyboard(5) manual page.
# Consult the keyboard(5) and xkeyboard-config(7) manual page.
Line 80: Line 123:
Line 92: Line 134:
 * [[DebianMan:7/xkeyboard-config|xkeyboard-config(7)]] man page.
Line 149: Line 192:
=== How to dynamically activate X Window settings ===

If the input method framework is not active, you can switch the keyboard layout of X Window system from the terminal, e. g.:
{{{
 $ sudo setupcon -k -f
}}}

=== How to dynamically activate X Window settings (old fashioned strategy) ===

If the IM framework is not active, you can switch the keyboard layout of X Window system from the terminal, e. g.:
Line 169: Line 216:
=== How to dynamically manage GNOME input source settings ===

For GNOME, you can check the current input source setting from the command line using:
{{{
=== How to dynamically manage input source settings from the command line (modern strategy) ===

Input source settings can be dynamically managed using '''{{{gsettings}}}''', '''{{{dconf}}}''', or '''{{{dconf-editor}}}''' commands. Here, '''{{{gsettings}}}''' command is the platform independent wrapper of Linux specific '''{{{dconf}}}''' command and '''{{{dconf-editor}}}''' is a GUI program.

The current input source setting and the current XKB input source can be obtained from the command line. For example:
{{{
 $ gsettings get org.gnome.desktop.input-sources sources
[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]
Line 174: Line 225:
}}}

For GNOME, you can reset it from the command line, if necessary, using:
{{{
 $ gsettings reset org.gnome.desktop.input-sources xkb-options
}}}

For GNOME, you can create a custom keyboard shortcut to select a particular input source by assigning command to '''{{{Settings -> Keyboard -> Keyboard Shortcuts}}}'''. E.g. the following will select the first input source:
['lv3:ralt_switch', 'compose:rwin']
}}}

or

{{{
 $ dconf read /org/gnome/desktop/input-sources/sources
[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]
 $ dconf read /org/gnome/desktop/input-sources/xkb-options
['lv3:ralt_switch', 'compose:rwin']
}}}

These can be updated to a certain values. For example:
{{{
 $ gsettings set org.gnome.desktop.input-sources sources "[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]"
 $ gsettings set org.gnome.desktop.input-sources xkb-options "['lv3:ralt_switch', 'compose:rwin']"
}}}

or

{{{
 $ dconf write /org/gnome/desktop/input-sources/sources "[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]"
 $ dconf write /org/gnome/desktop/input-sources/xkb-options "['lv3:ralt_switch', 'compose:rwin']"
}}}

These can be reset by using '''{{{gsettings reset ...}}}''' or '''{{{dconf reset ...}}}'''.

=== How to create a custom keyboard shortcut to select a particular input source ===

For GNOME, you can create a custom keyboard shortcut to select a particular input source deterministically by assigning command to '''{{{Settings -> Keyboard -> Keyboard Shortcuts}}}''' (instead of using '''{{{Super-SPACE}}}''' toggle). E.g. As explained [[https://osamuaoki.github.io/en/2021/01/15/debian-usability/#keyboard-shortcut-customization-gnome-settings|elsewhare]], the following command will select the first input source:
Line 188: Line 261:
== How to switch a keyboard layout in X11 / graphical desktop environment or ttyX console ==

=== GNOME ===

The keyboard layout can be changed on '''{{{Settings -> Keyboard -> Input Sources}}}''' (or '''{{{Settings -> Region & Languages -> Input Sources}}}'''). One can also change it via CLI using dconf/gsettings by adding keys to '''{{{/org/gnome/desktop/input-sources/sources}}}'''.

For releases older than Stretch, these layouts include minority languages and dialects, as well as very specific configurations, and are hidden by default in the GUI.
=== Keyboard configuration for backspace/delete and terminal type ===

The good review of the complicated situation over the keyboard configuration for backspace/delete and terminal type is available in {{{/usr/share/doc/xterm/README.Debian}}}.

Debian default keymap for xterm is DEC VT 220 like terminal behavior which is consistent with the Linux virtual console. This frees CTRL-H from backspace action and allows us to use CTRL-H for other purposes in programs such as Vim.

=== How to use kitty terminal with IM ===

GPU based terminal emulator DebianPkg:kitty doesn't use X, GTK, nor QT library but uses Wayland library. In order to activate IM to enter some characters for Chinese or Japanese, you need to follow {{{/usr/share/doc/kitty/README.Debian}}}.

== Overview of keyboard input ==

Here is an overview of the keyboard input situation on Debian.

In order to avoid confusion, both simpler historic situation and more complicated current situation are described below.

=== Historic situation over the keyboard input ===

Before the introduction of [[Wayland]] support to Debain, situation over the keyboard input can be summarized as follows:

 * GUI environment was provided only by the X system.
 * For Linux virtual console, its keyboard input is handled by Linux kernel. See '''{{{keymap}}}(5)'''.
 * For X environment without IM, its keyboard input is handled by X server by calling low level call to Linux kernel and using its own keymap. See '''{{{X}}}(7)''' and '''{{{xmodmap}}}(1)'''.
   * This was good enough for typing many accented (non-ASCII) characters using [[https://en.wikipedia.org/wiki/Dead_key|dead key]], [[https://en.wikipedia.org/wiki/AltGr_key|AltGr key]], [[https://en.wikipedia.org/wiki/Compose_key|Compose_key]].
     * This configuration may be done by X startup code configured by the GUI environment or '''{{{xkbcomp}}}''' call in {{{~/.xsession}}}.
 * For X environment with IM, its keyboard input is handled by IM. See [[I18n/ibus]] and [[I18n/Fcitx5]].
   * System environment is configured by a hook script provided by DebianPkg:im-config which sets up environment variables and runs daemon as a part of X start-up.
     * '''{{{XMODIFIERS}}}''' typically set to ''@im=<input-method>'' to enable a particular IM.
       * Daemon for IM serving XIM protocol is started by the hook script.
     * '''{{{GTK_IMMODULE}}}''' (or similar) typically set to ''<input-method>'' to enable a particular IM for application using GTK2/GTK3.
       * Required input modules such as DebianPkg:ibus-gtk3 and DebianPkg:ibus-gtk need to be installed.
     * '''{{{QT_IMMODULE}}}''' (or similar) typically set to ''<input-method>'' to enable a particular IM for application using QT4/QT5.
       * Required input modules such as DebianPkg:ibus-qt4 and DebianPkg:libqt5gui5 need to be installed.
   * This allows us to type not only many accented characters but also Chinese and Japanese characters.
   * Setups of environment variables different from what the default ones provided by DebianPkg:im-config are not recommended nor supported. Those random tips seen on the web are usually meant to be workaround for temporary breakage only. If you see any one of '''{{{XMODIFIERS=@im=none}}}''', '''{{{GTK_IM_MODULE=xim}}}''' or '''{{{QT_IM_MODULE=xim}}}''' for your program's running environment, you are in trouble.

=== Current situation over the keyboard input (as of 2022) ===

The introduction of the [[Wayland]] support to Debian changed situation over the keyboard input. (Other changes such as introduction of systemd and GTK4 happened, too.)

Since the [[Wayland]] support is the on-going activity, please refer to the wiki.debian.org page of [[Wayland]] for the latest situation and details.

Current (May 2022) situation of Debian 10 buster/stable and Debian 11/bookworm/testing over the keyboard input can be summarized as follows:

 * GUI environment are provided by the X system or by the Wayland system.
 * For Linux virtual console, its keyboard input is handled by Linux kernel. See '''{{{keymap}}}(5)'''.
 * For X environment without IM, its keyboard input is handled by X server by calling low level call to Linux kernel and using its own keymap. See '''{{{X}}}(7)''' and '''{{{xmodmap}}}(1)'''.
   * This is good enough for typing many accented (non-ASCII) characters using [[https://en.wikipedia.org/wiki/Dead_key|dead key]], [[https://en.wikipedia.org/wiki/AltGr_key|AltGr key]], [[https://en.wikipedia.org/wiki/Compose_key|Compose_key]].
     * This configuration may be done by X startup code configured by the GUI environment or '''{{{xkbcomp}}}''' call in {{{~/.xsession}}}.
 * For Wayland environment, pure X applications are still supported by [[https://wiki.debian.org/Wayland#Xwayland|Xwayland]] but [[https://wiki.debian.org/Wayland#Xresources_won.27t_load|Xresources are intentionally ignored]]. This means that the '''{{{xkbcomp}}}''' call in {{{~/.xsession}}} is ignored. X applications use XIM to get keyboard input.
 * For Wayland environment, non-X applications need to be configured properly with IM with the graphics library.
 * For any environment with IM, its keyboard input is handled by IM. See [[I18n/ibus]] and [[I18n/Fcitx5]].
   * System environment is configured by a hook script provided by DebianPkg:im-config which sets up environment variables and runs daemon as a part of X start-up and desktop initialization. Some desktop systems such as GNOME override this setup by DebianPkg:im-config.
     * '''{{{XMODIFIERS}}}''' typically set to ''@im=<input-method>'' to enable a particular IM.
       * Daemon for IM serving XIM protocol is started by the hook script.
     * '''{{{GTK_IMMODULE}}}''' (or similar) typically set to ''<input-method>'' to enable a particular IM for application using GTK2/GTK3/GTK4.
       * Required input modules such as DebianPkg:ibus-gtk4, DebianPkg:ibus-gtk3 and DebianPkg:ibus-gtk need to be installed.
     * '''{{{QT_IMMODULE}}}''' (or similar) typically set to ''<input-method>'' to enable a particular IM for application using QT5.
       * Required input module such as DebianPkg:libqt5gui5 needs to be installed.
   * This allows us to type not only many accented characters but also Chinese and Japanese characters under X and Wayland environments.
   * Setups of environment variables different from what the default ones provided by DebianPkg:im-config are not recommended nor supported. Those random tips seen on the web are usually meant to be workaround for temporary breakage only. If you see any one of '''{{{XMODIFIERS=@im=none}}}''', '''{{{GTK_IM_MODULE=xim}}}''' or '''{{{QT_IM_MODULE=xim}}}''' for your program's running environment, you are in trouble.

== Troubleshooting ==

=== Changing IM configuration ===

In order to avoid problem caused by library caching etc., you should reboot system when you make changes to the input method (IM) framework configuration. (Restarting Desktop session may be sufficient for most cases but reboot is safer.)

=== IM and XIM ===

Here is a hints for input method (IM) framework and [[https://en.wikipedia.org/wiki/X_Input_Method|XIM]] protocol issue.

==== IM framework activated case ====

When IM framework such as '''ibus''' is installed and activated, pure X applications (X clients which was designed to get keyboard inputs from X server through X connection with [[https://en.wikipedia.org/wiki/X_Input_Method|XIM]]) protocol) such as DebianPkg:xterm and DebianPkg:rxvt-unicode don't talk to the X server directly for keyboard inputs. The IM framework such as '''ibus''' handles actual keyboard inputs and pass processed data to X clients using XIM protocol from its daemon such as '''ibus-daemon''', instead.

Unfortunately, the combination of '''ibus''' and X clients is buggy for some (rare) keyboard sequences to input non-ASCII characters. There have been persistent bugs around this combination as discussed in [[https://bugzilla.redhat.com/show_bug.cgi?id=2013610|Red Hat Bugzilla – Bug 2013610]] and elesewhere.

Let's stay in a safe zone as much as possible.

Properly configured GTK and QT programs with DebianPkg:im-config don't use XIM protocol to communicate with '''ibus-daemon''' and are immune to these annoying bugs of this combination.

For terminal emulators, please use any modern ones which use via GTK or QT:

 * DebianPkg:gnome-console ('''{{{kgx}}}'''(1) command)
 * DebianPkg:gnome-terminal
 * DebianPkg:Konsole
 * DebianPkg:xfce4-terminal
 * DebianPkg:lxterminal
 * ...

For '''emacs''', please consider to use DebianPkg:emacs-nox in modern terminal emulators or DebianPkg:emacs-gtk. (I.e., please avoid DebianPkg:emacs-lucid if '''ibus''' is activated. DebianPkg:emacs-gtk bugs seem to be resolved.)

For programs such as DebianPkg:gitk, please consider to avoid typing problematic sequence for non-ASCII characters as much.

==== IM framework disabled case ====

If you don't need modern functionality of the IM framework such as '''ibus''', you can make X clients talk directly to the X server configured with [[https://en.wikipedia.org/wiki/X_keyboard_extension|X keyboard Extension (XKB)]] by disabling '''ibus''' as:,

{{{
 $ im-config -n none
}}}

This workaround may not work on some desktop environments if they override '''{{{im-config}}}'''. Notably, GNOME may fall into this type.

=== Japanese 109 keyboard ===

For Japanese PC keyboard, you select the keyboard model to be "{{{Generic 105-key PC}}}" and the keyboard variety per country to be "{{{Japanese"/"日本語}}}". So you should have:
{{{
XKBMODEL="pc105"
XKBLAYOUT="ja"
}}}
(Let's not worry twisted country and language name issue.)

The question is the keyboard layout variant.
 * Selecting "{{{Japanese}}}" / "{{{日本語}}}" will set {{{XKBVARIANT=""}}}
 * Selecting "{{{Japanese - Japanese (OADG 109A)}}}" / "{{{日本語 - 日本語 (OADG 109A)}}}" will set {{{XKBVARIANT="OADG109A"}}}

You probably have a modern Japanese PC keyboard manufactured after 2000 which has newer OADG 109A type markings on keytops. Even for such case, it is probably good idea to select simple "{{{Japanese}}}" / "{{{日本語}}}" layout, you should consider to set:
{{{
XKBVARIANT=""
}}}

This is because of practical benefit of easier access to "{{{~}}}". The subtle differences of these variants are:
 * {{{XKBVARIANT=""}}} setting produces "{{{~}}}" for "shift-{{{0}}}". (The older OADG 109 keytop of "shift-{{{0}}}" was marked as "{{{~}}}")
 * {{{XKBVARIANT="OADG109A"}}} setting produces "{{{0}}}" for "shift-{{{0}}}". (The newer OADG 109A keytop of "shift-{{{0}}}" is not marked)
 * Both settings produce "{{{~}}}" for "shift-{{{^}}}". (The older OADG 109 keytop of "shift-{{{^}}}" wasn't marked. The newer OADG 109A keytop of "shift-{{{^}}}" is marked as "{{{~}}}")

As for the reason why 105-key and not 109-key, 4 extra keys used solely for Japanese input doesn't seem to be accounted since they don't affect key mappings.

As for the history over OADG 109 to OADG 109A, please see [[https://ja.wikipedia.org/wiki/JIS%E3%82%AD%E3%83%BC%E3%83%9C%E3%83%BC%E3%83%89|JISキーボード]].

=== Very old GNOME (currently not an issue @2022) ===

The keyboard layout was changed on '''{{{Settings -> Region & Languages -> Input Sources}}}'''. For releases older than Stretch (initially released @2018), these layouts include minority languages and dialects, as well as very specific configurations, and were hidden by default in the GUI for Stretch (during its testng?).

One can set it via CLI using dconf/gsettings by adding keys to '''{{{/org/gnome/desktop/input-sources/sources}}}'''.
Line 203: Line 406:
=== KDE ===

KDE does this via System_settings/Hardware/Input_devices/keyboard - Most people doing dual languages will simply select the correct keyboard model and then go to the layout tab and select English(US International AltGr Unicode combining,alternative ).

Use your favorite desktop keyboard layout switcher applet.


== Troubleshooting ==

If changes to {{{/etc/default/keyboard}}} do not apply after restarting, it is possible that the changes are being overridden by gsettings. For instance, if XKBOPTIONS set in {{{/etc/default/keyboard}}} are not working, check using:
{{{
 $ gsettings get org.gnome.desktop.input-sources xkb-options
}}}
and reset if necessary:
{{{
 $ gsettings reset org.gnome.desktop.input-sources xkb-options
}}}

IBus can also sometimes override settings from {{{/etc/default/keyboard}}}. The keyboard setup dialog in GNOME 3 will modify IBus's configuration directly, but for users of other X environments, you can use the {{{ibus-setup}}} command to modify the settings for IBus. To force it to defer to the settings from {{{/etc/default/keyboard}}}, run {{{ibus-setup}}}, go to the ''Advanced'' tab, and check ''Use system keyboard layout''.
Line 223: Line 407:
 CategoryPortal | CategoryHardware CategoryPortal | CategoryHardware

Translation(s): English - Français - Italiano - Português (Brasil) - Русский


Portal/IDB/icon-wiki-portal.png

Debian wiki keyboard portal. This portal covers all aspects of configuring keyboards on Debian.

See "The keyboard input" in debian-reference, too.

Basic keyboard configuration (Kernel and X)

To configure the keyboard for Linux kernel and X, you have to install keyboard-configuration. The package console-setup is also needed.

The keyboard settings are stored in /etc/default/keyboard file provided by the keyboard-configuration package. Other packages use this to configure both the Linux kernel and the X Window system to realize consistent keyboard experiences under the Linux console and the X Window system.

You can change your keyboard settings using:

 # dpkg-reconfigure keyboard-configuration
 # service keyboard-setup restart
  1. Menu for Keyboard model (what the keyboard *is*) is presented. If not sure, choose:

    • "Generic 104-key PC" for US-type keyboard with "Windows-key"
    • "Generic 105-key PC" for ISO-type keyboard with "Windows-key" (and JIS-type keyboard with "Windows-key")
    • "Generic 104-key PC" or "Generic 105-key PC" can be chosen as above for smaller keyboard on laptop/note PC.
  2. Menu for Country of origin for the keyboard is presented. If not sure for this, choose:

    • "English (US)" for "QWERTY"-keyboard
    • "German" for "QWERTZ"-keyboard
    • "French" for "AZERTY"-keyboard
    • "Japanese" for "QWERTY"-keyboard with extra keys aimed for Japanese.
  3. Menu for Keyboard layout (what the keys should *do*) is presented. If not sure for this, choose:

    • "English (US)" for plain layout (English)
    • "English (intl., with ?AltGr dead keys)" to have access to accented characters etc.

    • "Default" for plain layout (German, French)
    • "Japanese" for plain layout (Japanese)
    • "Dvorak" etc. if you want.

To apply new settings, restarting the keyboard-setup service should suffice, otherwise you can try to restart kernel input system via udev:

 # udevadm trigger --subsystem-match=input --action=change

or reboot the whole OS.

The Linux kernel and the X Window System process keyboard inputs independently. The keyboard-configuration package take care their configuration.

For the X Window System, keyboard inputs are processed by the X Window System using X keyboard Extension (XKB). The resulting keyboard data are passed to the X applications through X connection with X Input method (XIM) protocol.

Modern keyboard configuration (IM)

The simple keyboard input mechanism realized by the above configuration can't support some languages, such as Chinese and Japanese, properly.

The installation of the input method (IM) framework package such as ibus (or fcitx5) together with associated packages enables to support all languages.

For the modern GUI system, keyboard inputs are processed by IM using IM engines. For GTK and QT applications, the resulting keyboard data are passed to them through D-Bus communication. For X applications, the resulting keyboard data are passed to them through X connection with X Input method (XIM) protocol. If the GUI system is Wayland, xwayland facilitates X connection for X applications.

(Please don't get confused by IM and XIM.)

For GNOME system (the default Debian Desktop environment), ibus package is automatically installed and activated. The keyboard input needs to be configured from its GUI Settings -> Keyboard for basic configurations. For more complicated configuration such as swapping CapsLock and Ctrl, you need to install gnome-tweak and use it.

For non-GNOME system, the stand alone GUI configuration command ibus-setup can set up IM framework for ibus. Under those desktop environments, menu entry of their keyboard configuration utility or pop-up menu entry offered by clicking the associated tray icon may start ibus-setup for you.

For KDE, configuration of ibus is System_settings -> Hardware -> Input_devices/keyboard. Tray icon is available as kimpanel in plasma-widgets-addons package.

See I18n/ibus and I18n/Fcitx5 for more.

Multi-language keyboard configuration strategy

There are 2 strategies for the multi-language keyboard configuration. Mixing these 2 strategies for keyboard input will create unmanageable system. So please don't do mix.

Old fashioned strategy

People who wish to set up a single keyboard input environment for multiple (European) languages in old fashioned way without the IM framework should consider following configuration strategy.

  • If an IM framework package is installed, deactivate it by executing im-config -n none.

  • Select the correct keyboard model. (US/ISO)
  • Select the desirable keyboard layout. E.g., English (US International ?AltGr Unicode combining, alternative)

  • (optional) Set up the keyboard behavior using X keyboard Extension (XKB).

    • This configuration may be done by X startup code configured by the GUI environment or xkbcomp call in ~/.xsession.

  • X applications communicate with the X server for the keyboard input through X connection with X Input Method (XIM) protocol.

This is offered as backward compatibility.

Modern strategy

People who wish to set up multiple dynamically-switchable keyboard input environments in modern way for multiple languages should consider following configuration strategy.

  • Install input method (IM) framework package such as ibus

  • (optional) Install pertinent IM engine package such as ibus-anthy

  • Activate desirable IM engine/keyboard layout by adding it from menu such as Settings -> Keyboard -> Input Sources and configure them.

  • Switch among IM engines/keyboard layout with by pressing GUI-SPACE.

  • X applications communicate with the IM daemon server such as ibus-daemon identified by XMODIFIERS for the keyboard input with X Input Method (XIM) protocol.

  • GTK applications communicate with the IM such as ibus with library specified by GTK_IM_MODULE for the keyboard input through D-Bus communication.

  • QT applications communicate with the IM such as ibus with library specified by QT_IM_MODULE for the keyboard input through D-Bus communication.

Please note that the IM framework such as ibus provides its internal functionality equivalent of X keyboard Extension (XKB) to enter many Unicode characters for European languages without additional engine packages and its configuration is available in GNOME Tweaks program under Keyboard & Mouse -> Additional Layout Options. See below for the non-GUI method to set these.

This is offered as future direction.

See "IM and XIM" for cares required to use IM smoothly.

Keyboard configuration Tips

Manual configuration of keyboard

You can edit /etc/default/keyboard manually instead of running dpkg-reconfigure keyboard-configuration.

Here's an example:

# KEYBOARD CONFIGURATION FILE
# Consult the keyboard(5) and xkeyboard-config(7) manual page.

XKBMODEL="pc105"
XKBLAYOUT="us,de,fr,ua,ru"
XKBVARIANT=""
XKBOPTIONS="grp:alt_shift_toggle"
BACKSPACE="guess"
  • XKBMODEL is a keyboard model variable (look at a /usr/share/X11/xkb/rules/base.lst (plain text) or /usr/share/X11/xkb/rules/base.xml (XML) for a full list);

  • XKBLAYOUT variable contains a list of used layouts;
  • "grp:alt_shift_toggle" sets a layout switching key combination (<Alt>+<Shift>).

Under the X environment, this keyboard layout setting in /etc/default/keyboard can be overridden by executing something like "setxkbmap us,ru -option grp:ctrl_shift_toggle" in the X startup configuration file ~/.xsessionrc . Please note that this is effective only for the X environment and the modern GUI environment may not be running under X environment.

See also:

How to set keyboard layout in initramfs

The appropriate section of /etc/initramfs-tools/initramfs.conf needs to be changed to have a localized keyboard layout at boot time:

#
# KEYMAP: [ y | n ]
#
# Load a keymap during the initramfs stage.
#

KEYMAP=y

Apply changes:

 # update-initramfs -u

How to enable USB keyboard in initramfs

The initramfs-tools must include the usbhid module and its dependencies for USB keyboard support at boot time. Either the configuration file /etc/initramfs-tools/conf.d/driver-policy must include most modules, or they will have to be specified in another file:

#
# MODULES: [ most | netboot | dep | list ]
#
# most - Add most filesystem and all harddrive drivers.
#
# dep - Try and guess which modules to load.
#
# netboot - Add the base modules, network modules, but skip block devices.
#
# list - Only include modules from the 'additional modules' list
#

MODULES=most

If the configuration above was not set to include most modules, then the necessary modules have to be specified in the file /etc/initramfs-tools/modules:

# USB keyboard at boot
usbcore
uhci_hcd
ehci_hcd
usbhid

Apply changes:

 # update-initramfs -u

How to dynamically activate Linux console settings

In order to activate changed settings in /etc/default/keyboard without reboot, run setupcon(1).

 $ sudo setupcon -k -f

How to dynamically activate X Window settings (old fashioned strategy)

If the IM framework is not active, you can switch the keyboard layout of X Window system from the terminal, e. g.:

 $ setxkbmap de
 $ setxkbmap fr
 $ setxkbmap us

Of special interest for keyboard hardware with us layout might be the altgr-intl variant (this provides a simple AltGr mapping for many umlauts and special symbols):

 $ setxkbmap -rules evdev -model evdev -layout us -variant altgr-intl

or

 $ setxkbmap -model pc105 -layout us -variant altgr-intl

To configure a simple key for toggling between multiple configured keyboard layouts, see Option XkbOptions in Section InputClass somewhere within the xorg config file collection (see [SOLVED] Setxkbmap .xinitrc).

How to dynamically manage input source settings from the command line (modern strategy)

Input source settings can be dynamically managed using gsettings, dconf, or dconf-editor commands. Here, gsettings command is the platform independent wrapper of Linux specific dconf command and dconf-editor is a GUI program.

The current input source setting and the current XKB input source can be obtained from the command line. For example:

 $ gsettings get org.gnome.desktop.input-sources sources
[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]
 $ gsettings get org.gnome.desktop.input-sources xkb-options
['lv3:ralt_switch', 'compose:rwin']

or

 $ dconf read /org/gnome/desktop/input-sources/sources
[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]
 $ dconf read /org/gnome/desktop/input-sources/xkb-options
['lv3:ralt_switch', 'compose:rwin']

These can be updated to a certain values. For example:

 $ gsettings set org.gnome.desktop.input-sources sources "[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]"
 $ gsettings set org.gnome.desktop.input-sources xkb-options "['lv3:ralt_switch', 'compose:rwin']"

or

 $ dconf write /org/gnome/desktop/input-sources/sources "[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]"
 $ dconf write /org/gnome/desktop/input-sources/xkb-options "['lv3:ralt_switch', 'compose:rwin']"

These can be reset by using gsettings reset ... or dconf reset ....

How to create a custom keyboard shortcut to select a particular input source

For GNOME, you can create a custom keyboard shortcut to select a particular input source deterministically by assigning command to Settings -> Keyboard -> Keyboard Shortcuts (instead of using Super-SPACE toggle). E.g. As explained elsewhare, the following command will select the first input source:

gdbus call --session --dest org.gnome.Shell --object-path /org/gnome/Shell --method org.gnome.Shell.Eval  "imports.ui.status.keyboard.getInputSourceManager().inputSources[1].activate()"

Keyboard configuration for backspace/delete and terminal type

The good review of the complicated situation over the keyboard configuration for backspace/delete and terminal type is available in /usr/share/doc/xterm/README.Debian.

Debian default keymap for xterm is DEC VT 220 like terminal behavior which is consistent with the Linux virtual console. This frees CTRL-H from backspace action and allows us to use CTRL-H for other purposes in programs such as Vim.

How to use kitty terminal with IM

GPU based terminal emulator kitty doesn't use X, GTK, nor QT library but uses Wayland library. In order to activate IM to enter some characters for Chinese or Japanese, you need to follow /usr/share/doc/kitty/README.Debian.

Overview of keyboard input

Here is an overview of the keyboard input situation on Debian.

In order to avoid confusion, both simpler historic situation and more complicated current situation are described below.

Historic situation over the keyboard input

Before the introduction of Wayland support to Debain, situation over the keyboard input can be summarized as follows:

  • GUI environment was provided only by the X system.
  • For Linux virtual console, its keyboard input is handled by Linux kernel. See keymap(5).

  • For X environment without IM, its keyboard input is handled by X server by calling low level call to Linux kernel and using its own keymap. See X(7) and xmodmap(1).

    • This was good enough for typing many accented (non-ASCII) characters using dead key, AltGr key, Compose_key.

      • This configuration may be done by X startup code configured by the GUI environment or xkbcomp call in ~/.xsession.

  • For X environment with IM, its keyboard input is handled by IM. See I18n/ibus and I18n/Fcitx5.

    • System environment is configured by a hook script provided by im-config which sets up environment variables and runs daemon as a part of X start-up.

      • XMODIFIERS typically set to @im=<input-method> to enable a particular IM.

        • Daemon for IM serving XIM protocol is started by the hook script.
      • GTK_IMMODULE (or similar) typically set to <input-method> to enable a particular IM for application using GTK2/GTK3.

      • QT_IMMODULE (or similar) typically set to <input-method> to enable a particular IM for application using QT4/QT5.

    • This allows us to type not only many accented characters but also Chinese and Japanese characters.
    • Setups of environment variables different from what the default ones provided by im-config are not recommended nor supported. Those random tips seen on the web are usually meant to be workaround for temporary breakage only. If you see any one of XMODIFIERS=@im=none, GTK_IM_MODULE=xim or QT_IM_MODULE=xim for your program's running environment, you are in trouble.

Current situation over the keyboard input (as of 2022)

The introduction of the Wayland support to Debian changed situation over the keyboard input. (Other changes such as introduction of systemd and GTK4 happened, too.)

Since the Wayland support is the on-going activity, please refer to the wiki.debian.org page of Wayland for the latest situation and details.

Current (May 2022) situation of Debian 10 buster/stable and Debian 11/bookworm/testing over the keyboard input can be summarized as follows:

  • GUI environment are provided by the X system or by the Wayland system.
  • For Linux virtual console, its keyboard input is handled by Linux kernel. See keymap(5).

  • For X environment without IM, its keyboard input is handled by X server by calling low level call to Linux kernel and using its own keymap. See X(7) and xmodmap(1).

    • This is good enough for typing many accented (non-ASCII) characters using dead key, AltGr key, Compose_key.

      • This configuration may be done by X startup code configured by the GUI environment or xkbcomp call in ~/.xsession.

  • For Wayland environment, pure X applications are still supported by Xwayland but Xresources are intentionally ignored. This means that the xkbcomp call in ~/.xsession is ignored. X applications use XIM to get keyboard input.

  • For Wayland environment, non-X applications need to be configured properly with IM with the graphics library.
  • For any environment with IM, its keyboard input is handled by IM. See I18n/ibus and I18n/Fcitx5.

    • System environment is configured by a hook script provided by im-config which sets up environment variables and runs daemon as a part of X start-up and desktop initialization. Some desktop systems such as GNOME override this setup by im-config.

      • XMODIFIERS typically set to @im=<input-method> to enable a particular IM.

        • Daemon for IM serving XIM protocol is started by the hook script.
      • GTK_IMMODULE (or similar) typically set to <input-method> to enable a particular IM for application using GTK2/GTK3/GTK4.

      • QT_IMMODULE (or similar) typically set to <input-method> to enable a particular IM for application using QT5.

        • Required input module such as libqt5gui5 needs to be installed.

    • This allows us to type not only many accented characters but also Chinese and Japanese characters under X and Wayland environments.
    • Setups of environment variables different from what the default ones provided by im-config are not recommended nor supported. Those random tips seen on the web are usually meant to be workaround for temporary breakage only. If you see any one of XMODIFIERS=@im=none, GTK_IM_MODULE=xim or QT_IM_MODULE=xim for your program's running environment, you are in trouble.

Troubleshooting

Changing IM configuration

In order to avoid problem caused by library caching etc., you should reboot system when you make changes to the input method (IM) framework configuration. (Restarting Desktop session may be sufficient for most cases but reboot is safer.)

IM and XIM

Here is a hints for input method (IM) framework and XIM protocol issue.

IM framework activated case

When IM framework such as ibus is installed and activated, pure X applications (X clients which was designed to get keyboard inputs from X server through X connection with XIM) protocol) such as xterm and rxvt-unicode don't talk to the X server directly for keyboard inputs. The IM framework such as ibus handles actual keyboard inputs and pass processed data to X clients using XIM protocol from its daemon such as ibus-daemon, instead.

Unfortunately, the combination of ibus and X clients is buggy for some (rare) keyboard sequences to input non-ASCII characters. There have been persistent bugs around this combination as discussed in Red Hat Bugzilla – Bug 2013610 and elesewhere.

Let's stay in a safe zone as much as possible.

Properly configured GTK and QT programs with im-config don't use XIM protocol to communicate with ibus-daemon and are immune to these annoying bugs of this combination.

For terminal emulators, please use any modern ones which use via GTK or QT:

For emacs, please consider to use emacs-nox in modern terminal emulators or emacs-gtk. (I.e., please avoid emacs-lucid if ibus is activated. emacs-gtk bugs seem to be resolved.)

For programs such as gitk, please consider to avoid typing problematic sequence for non-ASCII characters as much.

IM framework disabled case

If you don't need modern functionality of the IM framework such as ibus, you can make X clients talk directly to the X server configured with X keyboard Extension (XKB) by disabling ibus as:,

 $ im-config -n none

This workaround may not work on some desktop environments if they override im-config. Notably, GNOME may fall into this type.

Japanese 109 keyboard

For Japanese PC keyboard, you select the keyboard model to be "Generic 105-key PC" and the keyboard variety per country to be "Japanese"/"日本語". So you should have:

XKBMODEL="pc105"
XKBLAYOUT="ja"

(Let's not worry twisted country and language name issue.)

The question is the keyboard layout variant.

  • Selecting "Japanese" / "日本語" will set XKBVARIANT=""

  • Selecting "Japanese - Japanese (OADG 109A)" / "日本語 - 日本語 (OADG 109A)" will set XKBVARIANT="OADG109A"

You probably have a modern Japanese PC keyboard manufactured after 2000 which has newer OADG 109A type markings on keytops. Even for such case, it is probably good idea to select simple "Japanese" / "日本語" layout, you should consider to set:

XKBVARIANT=""

This is because of practical benefit of easier access to "~". The subtle differences of these variants are:

  • XKBVARIANT="" setting produces "~" for "shift-0". (The older OADG 109 keytop of "shift-0" was marked as "~")

  • XKBVARIANT="OADG109A" setting produces "0" for "shift-0". (The newer OADG 109A keytop of "shift-0" is not marked)

  • Both settings produce "~" for "shift-^". (The older OADG 109 keytop of "shift-^" wasn't marked. The newer OADG 109A keytop of "shift-^" is marked as "~")

As for the reason why 105-key and not 109-key, 4 extra keys used solely for Japanese input doesn't seem to be accounted since they don't affect key mappings.

As for the history over OADG 109 to OADG 109A, please see JISキーボード.

Very old GNOME (currently not an issue @2022)

The keyboard layout was changed on Settings -> Region & Languages -> Input Sources. For releases older than Stretch (initially released @2018), these layouts include minority languages and dialects, as well as very specific configurations, and were hidden by default in the GUI for Stretch (during its testng?).

One can set it via CLI using dconf/gsettings by adding keys to /org/gnome/desktop/input-sources/sources.

The only way to make them visible is to enable the corresponding setting in gconf:

 $ gsettings set org.gnome.desktop.input-sources show-all-sources true

For more information on this issue see https://bugzilla.gnome.org/show_bug.cgi?id=682240.


CategoryPortal | CategoryHardware