=============================================================================
==                                                                         == 
== im-config for Debian                     Osamu Aoki <osamu@debian.org>  ==
==                                                           (2026-07-06)  == 
=============================================================================

The im-config package is for X11-based system.  It does nothing under
Wayland-based system and can be removed safely.

This is updated note for version 1.0 on the im-config package.

The GUI command UI of im-config is cleaned but kept it functionality
unchanged.

The CLI command options of im-config have been completely changed. (I
don't expect user to use them except for the debugging.  So normal user
should not worry about this.)

-----------------------------------------------------------------------------
== How keyboard inputs are processed                                       ==
-----------------------------------------------------------------------------

Here is roughly how keyboard inputs are processed.

    Keyboard        UI panel    Configuration          Application
    |                  ^ |           |                      ^    ^
    v                  | v           v                      |    |
    Linux kernel -> Input method engine (IME) -+-> Gtk, Qt -+    |
                       | ^                     |                 |
                       | |                     +-> X11, Wayland -+
                       v |
                    IME plugin (ibus-mozc, ...)

See more at "The keyboard input" for the general introduction.
    https://www.debian.org/doc/manuals/debian-reference/ch08#_the_keyboard_input

Please note that the backend display server technology used on popular
Debian GUI environments (GNOME, KDE, ...) is migrating from the X11 one
to the Wayland one.

-----------------------------------------------------------------------------
== What is im-config                                                       ==
-----------------------------------------------------------------------------

The focus of this im-config package is configuration of classic
X11-based GUI environments for the text input of non-latin1 characters
(Indic, Chinese, Arabic, Japanese, Korean, Vietnamese, Thai, ...).

New Wayland-based GUI environments is out of scope for im-config.
(See "REFERENCE INFORMATION" below for Wayland IM configuration.)

-----------------------------------------------------------------------------
== im-config on X11                                                        ==
-----------------------------------------------------------------------------

The im-config package enables the best input method on the system as
default without any user actions on X11-based desktop environments. 

If the highest priority IM program is IBus and the DE is GNOME on X11,
this im-config does nothing and leave everything to GNOME on X11.

If you want to disable im-config and manually set up IM without any
interference from im-config, set im-config command to "none" or
uninstall it. 

-----------------------------------------------------------------------------
== How to setup IBus as IME on X11                                         ==
-----------------------------------------------------------------------------

Install pertinent IME plugin packages for the localized text input with IBus.

  * Japanese IME: ibus-mozc
  * Korean IME:   ibus-hangul 
  * Thai IME:     ibus-libthai
  * Chinese IME:  ibus-chewing, ibus-libpinyin, ibus-pinyin, ...
  * Others IME:   ibus-m17n               (indic, arabic,...)
  * See https://wiki.debian.org/I18n/ibus

This installation pulls in the ibus package by its package dependency.

Installed IME plugins need to be activated by using configuration tool:

  * `ibus-setup` (from a command line or GUI menu.)
  * GNOME Settings (from "Add Input Source")
  * Any other UI available on your DE

IBus daemon for the X11 application run under the X11 is started from

  * /etc/X11/Xsession.d/70im-config_launch

This normally launch daemon program.

For IBus under GNOME, its environment and its daemon is set from the
user session:
  * /usr/lib/systemd/user/org.freedesktop.IBus.session.GNOME.service
    (thus "run_im ibus" becomes effectively "run_im none" for GNOME to
    avoid conflicts)

-----------------------------------------------------------------------------
== Verbose execution                                                       ==
-----------------------------------------------------------------------------

Verbose logging under systemd is possible by uncommenting as
`IM_CONFIG_VERBOSE="true"` in /etc/default/im-config.

See "journalctl -b --user -t im-config"    (reportbug runs this)

Please use verbose log for reporting bug.

=============================================================================
=============================================================================
== REFERENCE INFORMATION (Wayland, Fcitx5, ...)                            ==
=============================================================================
=============================================================================

-----------------------------------------------------------------------------
== im-config on Wayland                                                    ==
-----------------------------------------------------------------------------

The im-config package does nothing for Wayland-based system and can be
removed safely.

-----------------------------------------------------------------------------
== How to setup IBus as IME on Wayland                                     ==
-----------------------------------------------------------------------------

Install pertinent IME plugin packages for the localized text input with
IBus.

    (This part is the same as the above X11 case)

IBus daemon for the classic X application run under the xwayland is
started from
  * /etc/xdg/Xwayland-session.d/10-ibus-x11

Although the Wayland core protocol doesn't even support the input of
accented characters, popular Wayland Compositors, such as Mutter for
<F3>GNOME or KWin for KDE implement extension protocols such as the
text-input-unstable-v3 for the text input.

If your application is build with the latest GTK or Qt libraries, there
is no need to set environment variables manually.

See "current Wayland protocols and their support status"
  * https://absurdlysuspicious.github.io/wayland-protocols-table/ )

For IBus under GNOME, its environment and its daemon is set from the
user session:
  * /usr/lib/systemd/user/org.freedesktop.IBus.session.GNOME.service

If you ever need to set environment variables manually for programs
using xwayland or for the backward compatibility using XMODIFIERS etc.,
create a file such as "~/.config/environment.d/50-input-method.conf "to
set them.  Please note this accepts only value assignments. See
environment.d(5). See upstream resources:

  * https://github.com/ibus/ibus/wiki/WaylandDesktop

Here are key environment variables set for IBus automatically set by
GNOME on Wayland and thier purpose.

  * `GTK_IM_MODULE` (not set)
  * `CLUTTER_IM_MODULE` (not set)
  * `QT_IM_MODULE=ibus` (for programs build with older Qt)
  * `QT_IM_MODULES=wayland,ibus` (for programs build with newer Qt)
  * `XMODIFIES=@im=ibus` (for xwayland)

Here are references to the historical input method support for Wayland.

  * Wayland and input methods
      https://dorotac.eu/posts/input_method/ (2020)
  * State of input method
      https://dorotac.eu/posts/input_broken/ (2024)
  * Wayland input method project post-mortem
      https://dorotac.eu/posts/im-finished/ (2026)

If you are on other DE which doesn't support IM as much as GNOME, you
need to configure:
 * user's environment variables
 * start up of the daemon program for IME
 * start up of the GUI panel program for the configuration of IME

-----------------------------------------------------------------------------
== Use of Fcitx in place of IBus                                           ==
-----------------------------------------------------------------------------

Fcitx (version 5) supports IBus compatible protocol.  So it can be used
as an alternative to IBus.

Install pertinent IME plugin packages for the localized text input with Fcitx5.
Fcitx5 is popular with Chinese users.

  * Chinese IME:  fcitx5-chinese-addons ...

See Debian and upstream resources:

  * https://wiki.debian.org/I18n/Fcitx5
  * https://fcitx-im.org/wiki/Using_Fcitx_5_on_Wayland

-----------------------------------------------------------------------------
== Backend display server identification of im-config                      ==
-----------------------------------------------------------------------------

Identify the display server technology using the "XDG_SESSION_TYPE"
environment variable to be "x11" or not.

-----------------------------------------------------------------------------
== Desktop environment identification of im-config                         ==
-----------------------------------------------------------------------------

Due to some historical complications and backward compatibility support
needs, this im-config uses IM_CONFIG_CURRENT_DESKTOP generated mainly
from XDG_CURRENT_DESKTOP defined in the "Desktop Entry Specification"
since its version 1.2.

  * https://specifications.freedesktop.org/menu/latest/onlyshowin-registry.html

I see following XDG_CURRENT_DESKTOP values in the source code of session
packages but actual DE identification should use verbose logging
outputs.

    * budgie-session       GNOME
    * cinnamon-session     ?????    (cinnamon or X-Cinnamon)
    * gnome-flashback      GNOME-Flashback:GNOME
    * gnome-session        GNOME
    * lxqt-session         LXQt
    * lxsession            LXDE     (this code mentions Lubuntu migration,
                                     and has example with qt/platform=lxqt)
    * mate-session-manager MATE
    * plasma-workspace     KDE
    * xfce4-session        XFCE

 -- Osamu Aoki <osamu@debian.org>,  Mon, 06 Jul 2026 14:54:50 +0000
# vim: set tw=72 ai si et:
