scim: A C repository from arteme

Source-derived documentation for developers is provided separately, courtesy
of doxygen.  Look for scim-doc-$(VERSION).tar.gz on our website for download
or browse online at http://oss.leggewie.org/scim/

To compile scim from svn, be sure to run the bootstrap script in the toplevel
directory first.  To prepare a new tarball for release, adjust the values of
the AC_INIT, SCIM_*_VERSION, SCIM_CURRENT and SCIM_REVISION variables in
configure.ac as necessary.  Then run
"./bootstrap && ./configure && make dist && make docs".

The main program of SCIM is named scim. The usage of scim is:

  scim [option]...

  The options are: 
    -l, --list            List all of available modules.
    -f, --frontend name   Uses specified FrontEnd module.
    -c, --config name     Uses specified Config module.
    -e, --engines name    Load specified set of input method engines.
    -ne,--no-engines name Do not load those set of engines.
    -d, --daemon          Run scim as a daemon.
    --no-socket           Do not try to start a SCIM SocketFrontEnd daemon.
    -h, --help            Show this help message.

By default, scim will use x11 frontend module and simple 
config module if they are available, unless you specify the module names.

And if --no-socket option is not used, scim will try to start a separated
daemon with SocketFrontEnd to provide the service, and X11 FrontEnd will
try to connect to this service daemon.

TIPS of X11 FrontEnd:
=====================

* You can drag input window, lookup window by pressing down right mouse button.
* export GDK_USE_XFT=1 before running scim to let scim use Anti-Aliased font.
* Font and color of preedit, status and lookup area can be changed in config file.

TIPS of Socket FrontEnd, IMEngine and Config module:
==================================================

*********** Notice ************
From 1.0.0, scim will make use of SocketFrontEnd to construct a single user
client/server input method environment automatically. Unless you use --no-socket
option when starting scim.
*******************************

Socket FrontEnd/IMEngine/Config module is useless under X11 environment. It's only
useful to work with GTK2 SCIM IM Module.

The purpose of Socket FrontEnd is to listen and accept request
on a local/inet socket. Socket IMEngine and Config module serve as clients of 
Socket FrontEnd.

The default socket address is local:/tmp/scim-socket-frontend, the prefix local:
indicates that it's a unix/local socket. If you want to create a inet socket, use
inet: prefix, e.g. inet:localhost:12345, 12345 is the port number.

Use following command to start scim daemon to listen a socket:

$ scim -f socket -c simple -ne socket -d

To specify a different address, you can do:

$ SCIM_SOCKET_ADDRESS=inet:localhost:12345 scim -f socket -c simple -ne socket -d

the option "-ne socket" tells scim does not load Socket IMEngine IM module, because
there is no Socket FrontEnd running yet.

Then to use this scim to serve another scim, you can do like this:

$ SCIM_SOCKET_ADDRESS=inet:localhost:12345 scim -f x11 -c socket -e socket -d

(This command starts a SCIM X11 XIM server which only forward request between
X11 and the previous started SCIM Socket FrontEnd.)

The option "-e socket" tells scim only uses Socket IMEngine IM module. Other module
should not be loaded directly, because they will be accessed via Socket FrontEnd by
Socket IMEngine IM module. -c socket tells scim to load configuration from remote
Socket FrontEnd instead of local config file.

Or if you want to use GTK2 IM Module within a GTK2/GNOME2 application, you can:

$ export SCIM_SOCKET_ADDRESS=inet:localhost:12345
$ testgtk

Then you can use SCIM directly within testgtk, by right clicking on an entry widget
and selecting SCIM input method.

By default, GTK2 SCIM IM Module will only use Socket IMEngine/Config modules, if
you want to load other modules directly, you may set the environment variables,
e.g.:

$ export GTK_IM_SCIM_CONFIG_MODULE=simple
$ export GTK_IM_SCIM_IMENGINE_MODULES=table

In case you do not understand how Socket FrontEnd/IMEngine module work, here is a
simple diagram to explain it:

+--------+
|IMEngine|
|Mod 1   |--+
+--------+  |
            |
+--------+  |  +--------+    inet          +--------+  +--------+
|IMEngine|  |  |Socket  | +--------+       |Socket  |  |X11     | /-----\
|Mod 2   |--+--+        |-|a socket| <- -> |IMEngine|--|        |-| X11 |<->app
+--------+  |  |FrontEnd| +--------+       |Module  |  |FrontEnd| \-----/
   .        |  +--------+    local         +--------+  +--------+
   .        |
   .        |
+--------+  |
|IMEngine|  |
|Mod n   |--+
+--------+

Then you see, IMEngine Modules 1 to n (like pinyin, table, rawcode etc.) with
Socket FrontEnd together act as a socket daemon (like apache), Socket IMEngine
Module with X11 FrontEnd act as a client. All requests from application
will first be sent to X11 FrontEnd, then transfered to Socket FrontEnd via
Socket IMEngine IM Module, then those requests will be proceeded by the real
IMEngine Modules (1 to n), all reply will be sent back to application via
the same route.


Have fun!

James Su <suzhe@tsinghua.org.cn>
Rolf Leggewie <foss@rolf.leggewie.biz>
arteme/scim
