im-config for Debian Osamu Aoki <osamu@debian.org>
=======================================================================
! Basic design of im-config
=======================================================================
1. If an reasonable and single set of input method packages is
installed, im-config activates it dynamically adjusted for all users
by default. (recommended situation)
2. If several reasonable sets of input method packages are installed,
im-config activates the most reasonable one dynamically for all
users by default. (The locale, desktop system and other factors
are taken into account.)
3. It provides a reasonably simple GUI configuration menu which may have
been turned off on some system by the default. You can always start
this simple GUI configuration menu by executing "im-config" from the
console shell prompt. This shell script is internationalized via
gettext.sh. Selected user configuration can override the system
default configuration. Menu should normally show only available
input methods on the system.
4. im-config package consists of 4 parts:
1) System start-up hook scripts and helper scripts
* /etc/X11/Xsession.d/70im-config_launch --- (hook for X)
- Set environment variables
- Set /usr/bin/im-launch to $STARTUP to start daemon/GUI later
* /etc/profile.d/im-config_wayland.sh --- (hook for wayland)
- Set environment variables
(source /etc/X11/Xsession.d/70im-config_launch
with "$IM_CONFIG_PHASE" = 1)
* /etc/xdg/autostart/im-launch.desktop --- (hook for wayland)
- "exec env IM_CONFIG_CHECK_ENV=1 im-launch" to start
daemon/GUI
2) Configuration files for the system start-up
* ~/.xinputrc --- (user specific)
* /etc/X11/xinit/xinputrc --- (system wide for root)
* /usr/share/im-config/data/*.rc --- (IM specific preset values)
3) GUI configuration program to set up configuration files
* /usr/bin/im-config
This program also provides stable CUI API for other programs
to interact nicely with im-config
* /usr/share/im-config/data/*.conf --- (IM specific preset values)
4) Configuration files for the im-config default settings
* /etc/default/im-config
5. Both user specific and system wide configuration files for the
im-config package are sourced as POSIX shell scripts to perform 2
different tasks:
* Set Environment variables: called with "$IM_CONFIG_PHASE" = 1
* XMODIFIERS --- for XIM protocol
* GTK_IM_MODULE --- for GTK library
* QT_IM_MODULE --- for QT library
* ...
* Start daemon and GUI programs: called with "$IM_CONFIG_PHASE" = 2
* daemon --- provide XIM / dbus server
* GUI programs --- tray program etc.
If these configuration files are generated by the GUI/CUI im-config
program, they gave 3 lines like:
---
# im-config(8) generated on Sun, 30 Mar 2014 02:45:02 +0900
run_im ibus
# im-config signature: d57688c8151277a0c25d15aa0523da6b -
---
run_im function looks for corresponding file to its argument "ibus",
which is /usr/share/im-config/data/21_ibus.rc , and source it.
The shell comment line contains signature to allow detection of
manual modifications by /usr/bin/im-config which offers the menu
configuration system. The menu configuration system honors such
changes.
=======================================================================
! How To Configure Input Method with im-config
=======================================================================
If you wish to override system default,
For user configuration ~/.xinputrc, execute as:
$ im-config
For system wide /etc/X11/xinit/xinputrc, execute as:
$ sudo im-config
For system default:
$ sudo -e /etc/default/im-config
Under current GNOME3, type im-config after pressing SUPER(Windows)-key
does the trick of starting the im-config GUI program.
The default input method (IM) mode of im-config was simple but is a bit
complicated now. Let me explain by going through its historical
evolution.
The IM_CONFIG_DEFAULT_MODE=auto choose the highest priority available
IM.
The IM_CONFIG_DEFAULT_MODE=none choose none of the available IM.
So the initial default IM mode choices were: auto, none
Since people setting CJKV locale environment may want auto mode while
people setting non-CJKV locale environment may want none mode, the
locale environment dependent automatic default IM mode
IM_CONFIG_DEFAULT_MODE=cjkv was added to choose auto or none based on
LANG environment variable value dynamically. Actual locales which
qualify are defined in CJKV_LOCALES variable.
With this, the default IM mode choices were: cjkv, auto, none
Since modern DEs such as GNOME (both classic X and new wayland)
integrate ibus as IM while providing panel GUI in its own desktop
environment, im-config hook scripts needs to be disabled for ibus on
such DEs. Such DEs to keep hands off are defined in DESKTOP_SETUP_IBUS
variable in the /etc/default/im-config.
DESKTOP_SETUP_IBUS='GNOME'
The locale dependent package priority order override for auto mode is
provided via IM_CONFIG_PREFERRED_RULE variable in the
/etc/default/im-config.
For example:
IM_CONFIG_PREFERRED_RULE='zh_CN,fcitx5'
This means for zh_CN.* locale (LC_CTYPE), fcitx5 is chosen as the first
choice over normal ibus if both are installed. In order to keep package
priority of ibus over other IMs for DEs which integrate ibus tightly to
DE, DEs specified by DESKTOP_SETUP_IBUS (namely real GNOME) are excluded
to reorder using IM_CONFIG_PREFERRED_RULE.
Please note CJKV_LOCALES, DESKTOP_SETUP_IBUS, and
IM_CONFIG_PREFERRED_RULE can have multiple values. Some values can be
preceded by "-" to indicate exclusion. Please make sure to separate
them with ":" (colon).
=======================================================================
! How all these fit together
=======================================================================
Initialization system for the activated IM choice:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ibus fcitx5, uim, SCIM
Desktop
GNOME desktop hooks im-config hooks
MATE im-config hooks im-config hooks
UKUI im-config hooks im-config hooks
Unity im-config hooks im-config hooks
KDE im-config hooks im-config hooks
LXQt im-config hooks im-config hooks
XFCE im-config hooks im-config hooks
-- This is set by 21_ibus.rc file using DESKTOP_SETUP_IBUS
defined in the /etc/default/im-config.
Even if "ibus" is activated under GNOME desktop in the above, im-config
hook script written for "ibus" does nothing and leaves initialization to
desktop hooks. (GNOME desktop's internal start up code takes care
starting and setting of ibus.)
IM package activation priority order for auto mode:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Chinese (zh_*) Non-Chinese
Desktop
GNOME ibus -> fcitx5 ibus -> fcitx5
MATE fcitx5 -> ibus ibus -> fcitx5
UKUI fcitx5 -> ibus ibus -> fcitx5
Unity fcitx5 -> ibus ibus -> fcitx5
KDE fcitx5 -> ibus ibus -> fcitx5
LXQt fcitx5 -> ibus ibus -> fcitx5
XFCE fcitx5 -> ibus ibus -> fcitx5
Here, the higher priority IM is listed on the left side.
-- This is set by automatic_im function of xinputrc.common file
using DESKTOP_SETUP_IBUS and IM_CONFIG_PREFERRED_RULE
defined in the /etc/default/im-config.
cjkv mode behavior (currently not used by default by any distro):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Debian Ubuntu Debian/Ubuntu
en/fr/... en/fr/... zh/ja/...
Desktop
GNOME none auto* auto*
MATE none auto auto
UKUI none auto auto
Unity none auto auto
KDE none auto auto
LXQt none auto auto
XFCE none auto auto
-- This is set by CJKV_LOCALES, CJKV_DEFAULT_DESKTOP
in mode_cjkv function of xinputrc.common file
none mode meaning:
~~~~~~~~~~~~~~~~~~
Do nothing for IM by im-config hooks and leave IM to desktop hooks
=======================================================================
! New input method support
=======================================================================
If you are interested to add a new input method support, please send me a
start up code as *.rc and its matching *.conf for /usr/share/im-config/data
by reporting to the BTS of the im-config package using reportbug(1).
*.rc files contain the start up code for the input method. It contains 2
parts:
IM_CONFIG_PHASE = 1 : export required environment variables to the programs
launched via /etc/X11/Xsession.d/70im-config_launch for X and
launched via /etc/profile.d/im-config_wayland.sh for wayland
IM_CONFIG_PHASE = 2 : daemon/GUI start up code called from im-launch
* via setting $STARTUP in /etc/X11/Xsession.d/70im-config_launch
for classic X system.
* via /etc/xdg/autostart/im-launch.desktop for wayland system
which is active only under wayland system.
*.conf files contain the definition of following variables and functions:
Variables:
IM_CONFIG_SHORT Short description of the im-config configuration.
IM_CONFIG_LONG Long description of the im-config configuration.
Sctipts are encouraged to use following internal variables.
IM_CONFIG_LC_CTYPE Practically LC_CTYPE/LANG
IM_CONFIG_CURRENT_DESKTOP Practically XDG_CURRENT_DESKTOP
Functions:
package_menu
return true if required packages exist for menu listing level: 00-89
package_auto
return true if required packages exist for auto selection level: 10-79
package_menu and package_auto use package_status function which returns true if
the package given in its argument is installed.
To test your proposed change, download the latest source by:
$ git clone --branch devel \
https://salsa.debian.org/input-method-team/im-config.git
Here, the "devel" branch is meant for everyone to commit changes. "master",
"upstream", and "pristine-tar" branches are used to record the uploaded
package by the maintainer with:
$ gbp import-dsc --pristine-tar ../im-config*.dsc
After above operation, I merge "master" branch to "devel" branch for
my easy tracking of changes on the gitk screen.
If you have debmake installed, you can make Debian package from "devel" branch
with:
$ make package
(I may move to use dgit workflow soon.)
=======================================================================
! Note on source structure
=======================================================================
This im-config package consists of 2 parts:
* run time -- hook & desktop
* configuration time -- im-config (GUI/CUI)
Here are summary of each file usages.
RUNTIME CONFIG
hook & desktop im-config
share/xinputrc.common.in INCLUDED INCLUDED
share/im-config.common NOT-INCLUDED INCLUDED
data/*.rc (contents) used not used
data/*.rc (file name) used used
data/*.conf (package_auto) used used
data/*.conf (others) not used used
-- Osamu Aoki <osamu@debian.org>, Sun, 19 Jul 2020 12:00:00 +0000
# vim: set tw=72 sts=4 sw=4 ai si et:
4abc3f2d20