About uim-xim

uim package includes an XIM server named uim-xim.

XIM is a legacy protocol and has many severe restrictions.  However,
there are many software which support only XIM protocol to input text
especially in Japanese.  So, I had written uim-xim as a tentative
tool.

Currently, uim-xim has many defects.  Some of them can be fixed.  But
the real way to go is to discard XIM itself.

* We already have gtk immodule version of uim.
* Project to make fully pluggable input method for Qt is in progress.



Main defects of uim-xim

* It only support input method with language whose character is
  convertible into working encoding of the client application.

  In short, if the client application (such as OpenOffice.org,
  tgif...) is working with ja_JP.eucJP locale, you can use only
  Japanese input methods (anthy, prime, skk...).

  But if you use these client applications with UTF-8 locale (such as
  ja_JP.UTF-8), you can use all the available multi-linguistic input
  method, and switch them dynamically.



How to use uim-xim

(1) Invoke uim-xim.  You can choose default conversion engine with
    --engine=ENGINE option (replace ENGINE with anthy, prime, skk,
    tcode, tutcode...  You can get available engines with invoking
    uim-xim --list).  Also you can specify default conversion engine
    with writing ~/.uim as follows.

     (define default-im-name 'prime)

    Unless specifying with above two methods, preferred engine
    corresponding to working locale is used automatically.

(2) Set XMODIFIERS=@im=uim and invoke client.

(3) If you want to use candidate helper program other than default
    one, set UIM_CANDWIN_PROG. (* uim-helper-candwin-qt and
    uim-helper-candwin-xaw is not implemented yet.)

     sh:  UIM_CANDWIN_PROG=uim-helper-candwin-qt export UIM_CANDWIN_PROG
     csh: setenv UIM_CANDWIN_PROG uim-helper-candwin-qt

    If nothing specified and using GTK+, uim-helper-candwin-gtk
    becomes default.  Or if nothing specified and not using GTK+,
    candidate helper is not used.

(4) To change back-end conversion engines dynamically, use
    uim-im-switch application.



How to use extra modifier keys

uim supports 'Super' and 'Hyper' modifier keys for customized key
operations. Try following steps to enable the feature.

(1) map arbitrary keys to Super and Hyper keys
  xmodmap -e 'keycode 115 = Super_L'      # left Windows key
  xmodmap -e 'keycode 116 = Super_R'      # right Windows key
  xmodmap -e 'add mod3 = Super_L Super_R' # any mod number is OK

  xmodmap -e 'keycode 117 = Hyper_L'      # 'Application' key
  xmodmap -e 'add mod4 = Hyper_L'	  # any mod number is OK

(2) define your own key-bindings
  (define-key generic-cancel-key? "<Super>g")
  (define-key generic-return-key? "<Hyper>m")



Bypassing uim temporarily

uim has 'emergency key' feature to bypass uim temporarily.  This is
useful with some applications.  Or you can choose "default" conversion
engine with uim-im-switch to bypass language conversion.

(1) Set the environment variable as follows
  LIBUIM_ENABLE_EMERGENCY_KEY=1

(2) Press Shift + Backspace to disable/enable uim key processing. Key
    inputs are directly passed to applications while uim key
    processing is disabled by emergency key.



Internal Implementation

uim-xim processes all IM-related strings as UTF-8 for internal
reasons. When a XIM client application runs on an UTF-8 locale such as
ja_JP.UTF-8, the strings are converted as follows.

  * "foo" expresses a string encoded in foo.

uim-anthy (only for example)
   |
   v
"EUC-JP"
   |
   v
libuim (iconv(3))
   |
   v
"UTF-8"
   |
   v
uim-xim (XmbTextListToTextProperty)
   |
   v
"compound text"
   |
   v
XIM client


uim-xim also supports XIM clients working on non UTF-8 native locales
such as ja_JP.eucJP. When a client application runs on such locales,
some additional encoding conversion occurs as follows.

uim-anthy (only for example)
   |
   v
"EUC-JP"
   |
   v
libuim (iconv(3))
   |
   v
"UTF-8"
   |
   v
uim-xim (iconv(3))
   |
   v
"EUC-JP"
   |
   v
uim-xim (XmbTextListToTextProperty)
   |
   v
"compound text"
   |
   v
XIM client


In such case, uim-xim performs an additional conversion via UTF-8 to
process the strings in the implementation. But it is ensured that no
character code alteration will occur since the both 'native->UTF-8"
and 'UTF-8->native' conversions are performed by same converter
iconv(3). This results the string as accurate as the old
implementation which is dedicated to ja_JP.eucJP encoding as follows.

uim-anthy (only for example)
   |
   v
"EUC-JP"
   |
   v
libuim (iconv(3))
   |
   v
"EUC-JP"
   |
   v
uim-xim (XmbTextListToTextProperty)
   |
   v
"compound text"
   |
   v
XIM client


--
Yusuke TABATA
