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:
