This the the README file of xcin 2.5
------------------------------------

A. Introduction:

XCIN is an XIM (X Input Method) server which is widely used in Taiwan to
perform Chinese input under X Window system. It is originally developed
by Edward Der-Hua Liu and many other programmers in early days; while now
it is supported by the XCIN Project (http://xcin.linux.org.tw). 

The current release of XCIN is xcin-2.5 series, which makes a big jump 
from the old releases (e.g., xcin-2.3 and older versions). The whole 
program structer is redesigned, the various input methods are modulized, 
the custumization is more flexible, and the core system is more stable and 
solid. The XIM protocol is also supported starting from this series (although 
several XIM patches for old versions have already appeared before xcin-2.5). 
The supports is not completed (currently it only supports the "Root" input
style), and still under development and improvement.

The goal of XCIN is to serve as a general Input Method server for various
kinds of people, not only for people in Taiwan (who mainly use the Big5 
encoding), but also for people in MainLand China (who mainly use the GB 
encoding). So we have tried to design it as much independent of the encoding 
as possible. We also hope that the supports of XIM protocol can help to 
solve the long standing Chinese-input problem completely.

Any suggestion or feedback are welcomed. You can contact the XCIN Project
Team through the xcin mailing-list: xcin@linux.org.tw.


B. Installation:

You should have a completed locale environment to install xcin-2.5. Currently
Linux with glibc-2.0.7 or newer versions and FreeBSD-3.0 or newer releases
are tested and OK. But for Linux, the plateform with glibc-2.1.x or newer
are highly recommanded. For details about how to install the locale 
environments (especially for zh_TW.Big5 and zh_CN.GB2312) are covered in

	ftp://xcin.linux.org.tw/pub/xcin/i18n/i18n_tool.tar.gz

Besides this, you should have the following libraries for installation:

1. Berkeley DB2:  For glibc-2.1.x, this library is already included. If you
	don't have it, you can find one in

	http://www.sleepycat.com

2. GNU gettext:  This is only needed for internationalized message output.

3. libtabe:  For the first release xcin-2.5.0, the libtabe is included in
	the xcin source tree. But from the 2.5.1 and later, this library
	is maintained saparately, and you should install it before installing
	xcin. It is obtained in

	ftp://xcin.linux.org.tw/pub/xcin/libtabe


The xcin stable releases are available in

	ftp://xcin.linux.org.tw/pub/xcin/xcin

while the under-development packages are available in

	ftp://xcin.linux.org.tw/pub/xcin/xcin/devel

The installation procedure is straightforward. Commonly speaking, you only
need to un-tar the package tarball, change into the directory "xcin-2.5", 
and excute the following commands:

	./configure --prefix=<installation distinct path> \
		    --with-extra-prefix=<extra lib prefix path you have>
	make
	make install

and all will be OK. You can run "./configure --help" for more detailed
command arguement description.

Finally, you can custumize the xcin configuration through editing the xcin
configuration file, commonly installed in <prefix>/etc/xcinrc. The detailed
description of the configuration file will be covered in "xcin-2.5/doc/Usage"
file. General speaking, it uses the Lisp/Scheme language format, and is 
devided into three parts:

	1. Global settings.
	2. Locale specific global settings, one section for one locale.
	3. Detailed settings for each Input Method, one section for one IM.


C. Quick Start:

Before starting, you have to set the locale for use. Here we take "zh_TW.Big5"
for example:

	LC_CTYPE=zh_TW.Big5; export LC_CTYPE
	xcin &

If xcin starts without error, it will print the following message:

===========================================================================
XCIN (Chinese XIM server) version xcin <version number>.
(module ver: <version number>, syscin ver: <version number>).
(use "-h" option for help)

xcin: XIM server "xcin" locale "zh_TW.Big5" transport "X/" inp_style "Root".
===========================================================================

Please note carefully for the last line. It contains important information
to start XIM clients. In the above example, the XIM server name is set to
"xcin", the input style is set to "Root", and the locale, of course, is set
to "zh_TW.Big5". Hence, if your XIM client cannot automatically search the
XIM server, you should explicitly specify the XIM server name and input
style to the client. To set the XIM server name, you might use the XIM client
command line arguement or resource file for setting, or more generally, you
can set it through the environment variable:

	XMODIFIERS="@im=xcin"; export XMODIFIERS
			^^^^ (this is the XIM server name)

and then you can run any XIM client and use xcin to input Chinese. The input 
style might be set through the command line arguement of the client, or the
client can determine it automatically.

By default, xcin will not handle any input from keyboard unless you press
one of the "trigger keys". These trigger keys are configurable in xcinrc
file. When you press one, for example, "ctrl+space", you will see the contents
of the xcin window changes, and all your keyboard input will be handled and
composed by xcin. Of course, to type Chinese characters, you have to be
familiar with one of the supported Chinese Input Method. :-))

Enjoy!


Tung-Han Hsieh  <thhsieh@linux.org.tw>
Physics Department of National Taiwan University, R.O.C.
XCIN Team.  <mailing-list:  xcin@linux.org.tw>
            <www:           http://xcin.linux.org.tw>
            <ftp:           ftp://xcin.linux.org.tw/pub/xcin>

