im-config for Debian                     Osamu Aoki <osamu@debian.org>

NOTE: This source code is managed using dgit-maint-merge strategy.

=======================================================================
!	Basic design of im-config framework
=======================================================================

1.  If an reasonable and single set of input method (IM) packages is
    installed, im-config framework activates desirable IM dynamically
    adjusted for all users by default. (recommended situation)

2.  If several reasonable sets of IM packages are installed, im-config
    framework activates the most reasonable one dynamically for all
    users by default.  (The locale setting, desktop environment (DE)
    choice and other factors are taken into account.)

3.  The im-config framework provides a reasonably simple GUI
    configuration menu program as the im-config command. You can always
    start this GUI configuration menu by executing "im-config" from the
    console shell prompt.  This command can be started from the GUI
    menu, too.  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.  Evolution history of im-config configuration mechanism

    It was simpler when only the classic X11 DE on sysV-init was its
    target and no autostarted GUI programs were addressed.

    Then, in order to keep setting up of environment variables for GUI
    programs at 70-priority while moving the starting of daemons to
    90-priority, the delayed execution is enabled by using $STARTUP
    value.

    In order to use single configuration file such as 21_ibus.rc in
    /usr/share/im-config/data/ used both for setting IM environment
    variables and for starting daemon, following variables are used.

      * "$IM_CONFIG_PHASE" = 1 for IM environment variable setting
      * "$IM_CONFIG_PHASE" = 2 for daemon program starting

    In order to avoid conflict with user selected set up, many checks
    are added to make this complicated and convoluted.

    Lastly, modification to support wayland and systemd systems made
    im-config framework to call 70im-config_launch multiple times.

    (I recall this bad coding stile was motivated to get easier freeze
    exception by changing fewer lines.)

    With 0.59 release, multiple calls to 70im-config_launch is removed
    and evaluated how to address https://bugs.debian.org/1052005.

    The conclusion is stop doing anything for wayland as mentioned in
    README.Debian.

    Start-up process parses several hook configuration files.

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

        This call sets: IM_CONFIG_ENTRY=xsession

    If im-config package is removed but not yet purged, this
    70im-config_launch script exists and may cause trouble.  So run this
    only when im-launch exists (im-config package is installed).

    If any of the following IM activation related variables are set,
    this 70im-config_launch script keeps its hands off.
      * "$XMODIFIERS"
      * "$GTK_IM_MODULE"
      * "$QT_IM_MODULE"
      * "$CLUTTER_IM_MODULE"
      * "$SDL_IM_MODULE"
    Otherwise:
      - Set $IM_CONFIG_PHASE" = 1
      - Source share/im-config_setting
      - Set environment variables

    Update $STARTUP for im-launch stared in 99x11-common_start

    **  /etc/11/Xsession.d/99x11-common_start
      - This calls im-launch via $STARTUP
      - Set "$IM_CONFIG_PHASE" = 2 in im-launch
      - Source share/im-config_setting
      - Start IM daemon

    Here, im-launch is very careful.  It checks if any of the IM
    activation related variables are changed. If it detects changes then
    it doesn't start IM daemon.

**  /etc/profile.d/im-config_wayland.sh
**  /etc/xdg/autostart/im-launch.desktop

    Disabled by making these as place holder files
      * GNOME on Wayland needed these but no more.
      * KDE on Wayland doesn't need these.
      * Others, recommend manual configuration

5. 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)

6. GUI configuration program to set up configuration files
     * /usr/bin/im-config
       This program provides stable GUI API for other programs
       to interact nicely with im-config framework
     * /etc/default/im-config
       - Configuration files for the im-config default settings
     * /usr/share/im-config/data/*.conf
       - IM specific preset values selected by menu

7.  Both user specific and system wide configuration files for the
    im-config package via common im-config_setting 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 GNOME, 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'

=======================================================================
!	Extra features used by previous Ubuntu defaults
=======================================================================

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
=======================================================================

none mode meaning:
~~~~~~~~~~~~~~~~~~

    Do nothing for IM by im-config hooks and leave IM to desktop hooks.
    If im-config interfare with new highly integrated desktop or any
    fancy custom set up, this is what you want to set up.

auto mode meaning:
~~~~~~~~~~~~~~~~~~

    This mode is default mode as installed.

Initialization system for the activated IM choice:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

                    ibus                fcitx5, uim, SCIM
    Desktop
    GNOME           NONE                im-config hooks
    MATE            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

Here, "NONE" means im-config framework does nothing for setting up IM
and leave such configuration to GNOME.

Although GNOME sets up itself for ibus, you can use fcitx5, too.
When set of ibus IM packages are not installed and set of fcitx5 IM
packages are installed as IM framework, fcitx5 accepts setting for ibus
to allow keyborad input.

Listing of GNOME in "$DESKTOP_SETUP_IBUS" defined in
/etc/default/im-config set GNOME for NONE via code in 21_ibus.rc.

If your Desktop becomes as integrated as GNOME, set im-config setting to
"none".

IM package activation priority order for auto mode:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

                    Chinese (zh_*)       Non-Chinese
    Desktop
    GNOME           NONE                 NONE
    MATE            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 echo_auto_selected_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            NONE            NONE
    MATE            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 echo_cjkv_selected_im function of xinputrc.common file

 -- This will be removed soon.


=======================================================================
!	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
    * launched 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 as IM framework
 * configuration time   -- im-config (GUI/CUI) command

Here are summary of each file usages.

                                RUNTIME             CONFIG
                                hook & desktop      im-config
                                as IM framework     command

share/initializer               INCLUDED            INCLUDED
share/xinputrc.common.in        INCLUDED            INCLUDED
share/im-config.common          NOT-INCLUDED        INCLUDED
share/im-config_setting         INCLUDED            not-used
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>,  Mon Mar  2 03:19:14 PM UTC 2026

# vim: set tw=72 sts=4 sw=4 ai si et:
