#################################################################
#								#
#                   XCIN version 2.3.02 Package.		#
#								#
#     Modified from  xcin-2.1d.tar.gz  package.			#
#              (by: Edward Der-Hua Liu, Taiwan)			#
#	       with  XcinFix-4  improvement.		      	#
#	       (by: Suei-Jeng Wang <vvvv.bbs@cis.nctu.edu.tw>)	#
#	       with new experimental codes.			#
#	       (by: Tung-Han Hsieh  (Nov., 1997)		#
#								#
#		by  Tung-Han Hsieh  (Nov., 1997)		#
#		    Physics Dept., National Taiwan University.	#
#		    Email: thhsieh@twclx.phys.ntu.edu.tw	#
#								#
#################################################################


<< Thank You >>

    Thanks to Mr. Edward Der-Hua Liu and others who developed the xcin
system.  With the wonderful program, we can do a lot of operation with
Chinese under  X-window in the UN*X world.  As time goes on, more  and 
more  people use it,  and more and more comments appear.  The  package
upgraded  with  time but it seems that  the  install  process  is  not 
convenient  and  self-consistent.  These  confuse  a  lot  of  people, 
especially for new users in the UN*X world. We often see the `Big FAQs' 
about  xcin  such  as `how  can  I install the Chinese  fonts' or `the 
cj2cin  command  not  found' or `the  crxvt  terminal is too big!!' or 
something  appears  in  the newsgroup again and again.  In  fact, such 
problems  are easy to modify.  Beasuse I really like this program  and 
feel that I may do something to improve this package, so I try my best 
to  re-write  the  Makefiles  and  auto-configuration programs of this 
package to try  to  solve  these troubles.  This comes the  `xcin-2.3' 
project. 

    First of all, why does not  this version be "2.1e" or "2.2",  but
directly jump to "2.3"?  Well, I think, and really treat this version
to be a jump from the previous version "2.1d".  Because from now  on,
I will get into the source code of the xcin system and try my best to
improve it as good as possible.  This may sound funny, but I name  it
to be version  "2.3.XX"  which means that  this  is  an  experimental 
version. Just like Linux kernel, there are three parts of the version:
the Major version number, Minor version number, and patch levels. For
odd minor version number, it means that it is an experimental release
and MAY BE UNCOMPLETE OR UNSTABLE.  On the other hand, for even minor
version number, it means that it is a  stable and  complete  release. 

    In the version "2.3" series, I will try to add some new  features
into xcin and re-write the whole source code, step by step.  I should
claim that any patch levels of version 2.3 are still not complete for
me.  But with higher patch level, the system will be more  closer  to 
the  complete version.  So, this  may  be  your  risk  to  use  these 
incomplete versions.  If you are not sure that you can  take care  of
all the incident events caused by the bugs  of this  version,  please
DON'T use this version but use version "2.1" series.  However, if you
are interesting in testing this version, I will welcome you to use it 
and send the bug reports to me.

    If anyone has comments or suggents about my modification,  please
mail to me.  I hope that everyone who is interesting in improving the
xcin package could work together. I believe that with our works, this
package will have much more progress in the near future.

    Finally,  I should thank to everyone who used to encourage me and
suggest me to do this project.  This time, I should especially thanks
to  Suei-Jeng Wang  <vvvv.bbs@cis.nctu.edu.tw>.  With  his  effort on
the XcinFix series from the original xcin-2.1b,  the xcin  system has
got  more  powerful, more  flexible, and more usable.  Thanks for his 
contributions on the  XcinFix-4.4  of this  package.  Also, I  should  
thank  to  Y.C. Tao  (Ivan)  <r5541029@ms.cc.ntu.edu.tw>  and  PA
<pa@freebsd.ee.ntu.edu.tw> for their beta testing on FreeBSD, and for
the  new  patches to fix bugs in the previous versions.  And finally, 
thank you very much for your using and supporting for this xcin-2.3.02 
package.



<< What's New >>

     This version does not contain any new features than the previous
version.  It only contain various patches provided by other users  to
fix some problems.  The changes include

 1. patch from  <hamster.bbs@cis.nctu.edu.tw>:
	This patch improves Phrase Phonetic input-method such that it
	will operate more likely to the Natural input-method found in
	M$ world.

 2. patch from  Chia-liang Kao  <clkao@tc.neto.net>:
	This patch fix a memory allocation bug in tsin.c file.

 3. patch from  <pa@freebsd.ee.ntu.edu.tw>
	This patch fix cj2cin.c and ar2cin.c files such that they will
	convert more "correct" Changjei and Array30 input-method tables.

 4. patch from  <weijr.bbs@sob.m7.ntu.edu.tw>
	This patch fix the pho1st file to modify the Phonetic input-
	method for some perticular keyboard mapping.

 5. Small changes on configure file to allow the additional font 
	installation. Now if you get Chinese fonts from other means
	and want the installation procedure to install it automatically,
	you can just place the fonts into  xcin-2.3.02/fonts/  directory,
	and run "configure" to choose "F" (Font), then after installation
	the fonts will be copied into correct directory.


(PS. I have heard that the FreeBSD users are going to port free Chinese
     fonts from various origins.  So, the interested people can go to
     the FreeBSD BBS board or news groups for more information.)

    For other minor changes of this version, you can refer to 
docs/ChangeLog file for more details.


<< To Do >>

    New xcin is under developing which is called "Redesigning Xcin Project".
The RXP is defined as following:

 1. Default-dir & User-dir:
	The dirs contain the system & data files which are needed to run
	xcin.  New xcin will only search files in User-dir & Default-dir.
	Currently Default-dir is /usr/local/lib/xcin/, and the User-dir 
	is $HOME/.xcin/ .  The User-dir is needed and will be constructed
	if xcin cannot find it when start up.  This will provide more
	flexible configuration for various users.

 2. Resource file:
	New xcin will not use $HOME/.Xresource or $HOME/.Xdefault for
	rc_files.  Instead, it has a xcinrc file placed in User-dir. This
	file will make xcin highly configurable and easy for use.  With
	this, the complex command line options in original xcin will 
	disappear.  Only the options for seaching the rc_file remained
	in command line.  The rc_file has the structer like this:

	XCIN_DEFAULTDIR = "/usr/local/lib/xcin"
	XCIN_FGCOLOR = "White"
	XCIN_HIDE = YES
	PHRASE = "sample.phr"
	.................
	.................
	CINPUT {
		NAME = "Boshiamy"
		AUTO_SELECT = YES
		AUTO_UPWORD = YES
		BEAP_MODE = 1
		..............
	}
	CINPUT {
		..............
		..............
	}

	New xcin will provide a sentax analysis engine to prevent you
	for incorrect setting in rc_file.  Note that the variable name
	appeared in the above example may be changed in the future.

 3. The environment variable:
	New xcin will support several environment variable for global
	settings.

 4. Three operation modes:
	a. xcin:  
		Start xcin for Chinese input normally.

	b. xcin -c <filename>.cin:
		cin2tab mode.  This will convert .cin file to .tab files.

	c. xcin -p <filename>.cin:
		phin2phr mode.  This will convert .phin file to .phr files.

 5. New cin2tab function:
	This include new .cin file format.  Original .cin format includes
	%NoBosh and some others.  These will be removed in the new style.
	In the future .cin file will only contain:

	Chinese name of the input-method.
	English name of the input-method.
	Key-defination.
	Selection-keys for duplicate Chinese characters.
	Quick-key defination.
	Input-method code to Chinese character mapping table.

	and all the other features will be moved to the rc_file for 
	flexible configuration.  The original converted .tab & .tab.rev
	files will be combined to only one file: .tab, and .tab.quick
	file remains for quick-key definition.

 6. New phin2phr function:
	This contains common phrase definition for xcin.  All phrase
	will appear with Shift+Alt+??, where ?? may contain one or two
	keys.  Other phrase with no key-binding will be used for 
	Auto-Selection mode.  In the new version, the phrase resource
	file will be defined with ".phin" extension, just analogies
	to ".cin" extension.  And the converted file will have ".phr"
	extension, just analogies to ".tab" extension.

 7. No Input-Method is perticular:
	Originally Ctrl+Alt+3 & Ctrl+Alt+6 are perticular input-methods
	which cannot be altered.  In the future this restriction will
	be removed.  All input-method will have unified operation 
	interface and the same ".cin" source file.

    Currently the definition and desinging of RXP is up-to-here.  We
are keeping on further programing.  I think that this is truely "jump"
of xcin.  Now we have the code supporting these, but they are very very
alpha and the version number begins with "alpha-<date>", not belong to
"2.3.??".  One day if the functionarity of RXP is compatible with current
xcin, its version number will come back to "2.3.XX" series and will be 
released for beta testing.  For the original one, I think that I will not
do new improvement in functionarity but only fix bugs or problems.  Hope
that this will be more stable for use.



<< The Structer >>

    As before, the xcin-2.3.02 has the following structers:

1. xcin-2.3.02/configure:
	The auto-configuration program.  It uses other tools in the
	xcin-2.1d/scripts directory.  This  time you don't see  the 
	main Makefile here.  It will be generated by this program.

2. xcin-2.3.02/xcin/:
        There contains  the  xcin Chinese-input  server, and  other
	important tables and utilities such as cin2tab,  tsintools,
	cli_xcin.o and others which should be used to run the  xcin
	system.

3. xcin-2.3.02/crxvt/:
        The xcin client, a modified X-window rxvt terminal.  There
        are  also some  resource files in the `xcin-2.1c/crxvt/rc'
        directory.

4. xcin-2.3.02/input_tabs/:
	There contains several `.cin' input-method tables provided
	by XcinFix4-4.  In the `source' directory, we also provide  
	the  programs to convert the ETen input-method tables  for
	xcin.

5. xcin-2.3.02/fonts/: 
	In the source sub-directory, we provide the `et2bdf' program 
	to convert the ETen fonts for xcin.

6. xcin-2.3.02/doc/:
        There are a set of documentations.  Now we provide the  on
	line manual pages, Chinese howto documentations, and other
	older documents.

7. xcin-2.3.02/script/:
	There contains other shell-scripts to help others to setup
	the  xcin  system.  You should not call them by  yourself. 
	They should be called by the xcin-2.3.02/configure  program.
	Also, you can see that there is a Makfile.in file.  It  is 
	the main frame of the original main Makefile of xcin-2.1c.


    After installation, the xcin package will be in the following file
systems:

1. Main binary: xcin, crxvt
	In one of your seach path. Default is `/usr/local/bin'

2. Fonts: English fonts(vga*), Chinese fonts(et*, taipei*, ...)
	By default, the  English  fonts  will be in  the
	`/usr/X11/lib/fonts/misc' directory. The Chinese
	fonts will be in the '/usr/X11/lib/fonts/chinese'
	directory.

3. Tables, Utilities and Documentations:
	There includes all the Chinese-input-method tables,
	tsin  input-method tables, keyboard mapping tables,
	and  some  utilities  such  as  cli_xcin.o, et2bdf, 
	cin2tab, tsin utilities, and others.  By  defaults,
	they  will  be installed  to `/usr/local/lib/xcin'.
	The   documentations    will   be   installed   to 
	`/usr/local/lib/xcin/doc'.



<< To Install >>

    Because in this  version, one can decide freely what  he/she  want
to install and what  he/she doesn't want just by changing the settings
in the configuration program, so there may be a problem that `At least
what  should  I  choose to  "yes" such that I can have a complete xcin
 system?'  Well, the answer depends on what you actually need.  But at 
least you should have the following installed:

1. Binaries: xcin, crxvt.

2. Chinese fonts: at least one 8x16 font.

And others are up-to-you.  In this  version  we  don't  provide  the 
Chinese font anymore.  So you should download it from ftp sites  for
complete usage of xcin system.  Of course, you can  add  others  you 
need in to the  system, such as other Chinese input-method tables or 
fonts.  On way is to convert them from the ETen system, and in  this 
case you should have one ETen system installed. The other way is try 
to get them from the internet.  As I know,  the Chinese fonts can be 
found from the following ftp sites:

	ftp://linux.cis.nctu.edu.tw
	ftp://nctuccca.edu.tw

or other sites.  The package "XCIN ANYWHERE" by  

	weijr.bbs@bbs.ntu.edu.tw
or
	weijr.bbs@bbs.sob.org

is recommand.  It can co-operate with  xcin to provide Chinese-input 
ability to ANY X-applications, as the author claims.  Please contact
the author for more details.


    To install the xcin package, go through the following steps:

1. Read this document README carefully.

2. Run the program:

	configure

   to begin the installation process.  You can type

	configure -help

   to see the options of this program:

   Usage:  configure [-help] [-prefix=PREFIX] [-exec-prefix=PREFIX]
                     [-X-include-prefix=PREFIX] [-X-lib-prefix=PREFIX]
                     [-X-font-prefix=PREFIX]

           -help:  Print this message.
           -prefix:  Prefix dir of the /bin, /xcin, /man dirs.
           -bin-prefix:  Prefix dir of the /bin dir.
           -x-include-prefix:  Prefix dir of the /X11/Xlib.h include dir.
           -x-lib-prefix:  Prefix dir of the /libX11* lib dir.
           -x-font-prefix:  Prefix dir of the X-win .pcf fonts.

3. In you really need, you can make changes of the Makefiles and the
   config.status, install.status by hand to suit your requirement.

4. To be the root, (you do not need to under the X-window environment),
   type:

	make
	make install

5. Note that in this you should get the Chinese fonts by yourself.
   Try to download it from the ftp sites as mentioned above, and 
   follow the instructions of  xcin-2.3.02/docs/Xfonts.HOWTO  to do
   fonts installation.

6. After installation, the make will generate xcin-2.3.02/filelist file.
   It is a list of files what the installation has installed in your
   system.  

7. Edit your  /etc/XF86Config, add your Chinese font path into  the
   Section "Files".

8. Install completely! Now you can re-start the X-window, and enjoy.


    If you want to make additional changes or want to re-compile the 
package, be sure to type  `make clean' before `make; make install'.



<< Quick Start >>

    If you are a new user for the xcin system, the following informa-
tion may help you to get the idea to run the system. For more details,
please refers to

	man xcin
	man crxvt
	man cin2tab

and the xcin.HOWTO, cin2tab.HOWTO, Xfonts.HOWTO, Boshiamy.HOWTO.


    Now you have finished the installation, and re-start the X-window.
you can now open a xterm, and execute the following command:

	crxvt &

Then  you  will  see a  rxvt like terminal appeared.  By default, the 
crxvt  will search for 8x16 as its English font, and the taipei15  as
its Chinese font.  If you don't have the taipei15.pcf font, you  will 
see an error message as "crxvt: can't access font taipei15"  appeared 
and  the  execution  fails, then  you should provide a option to tell 
crxvt  to  find  the other fonts to use.  For example, if you have  a 
taipeik20, and you want crxvt to use the 10x20 English font, you  can 
use:

	crxvt -fnb5 taipeik20 -font 10x20 &

Beside these, there are still a lot of options for crxvt, and you can
see the `man crxvt' for the detailed description about those options.

    Now you can start the xcin.  Just type

	xcin &

then  you  see some messages appeared. In this version, we follow the
convension of XcinFix4.4, in default the xcin window will not hide. You
can  provide the -hidden 1 option to start xcin to enable the  hidden
function.  By pressing Ctrl+Space,  you  can  switch  it  between the 
Chinese/English input mode.  If  you enable the hidden function, xcin
will  appear  only  when it is in the Chinese input mode.  Note  that  
only the xcin client can use xcin, i.e., only when the crxvt  becomes 
the  foreground,  then you can press Ctrl+Space to switch it into the 
Chinese  input  mode because currently you only have crxvt to be  the 
client of xcin.

    Similarly, by  default  the  xcin use the hku-ch15 as its Chinese  
font and the 8x16 as its English  font.  If you don't have this font, 
you can type:

	xcin -fnb5 taipeik24 -font 12x24 &
			     ^^^^^(Note that this option name has been changed!)
to use the taipeik24 font.  By default, xcin will have the pho-input-
method (Ctrl+Alt+3) and the  tsin-input-method (Ctrl+Alt+6).  If  you
want to use other input-methods, such as cj-input-method, you can use
the command:

	xcin -in1 cj.tab &

Then in addition to the  pho-input-method, there will be a  cj-input-
method as you press Ctrl+Alt+1.

    Finally, you can integrate the xcin & crxvt to your X-win system.
For  example, you may complain that everytime you should type such  a
complicated command to start the xcin & crxvt.  In fact, you can  add
these  commands into your Window Manager source file such that  every
time you enter the X-window, the Window Manager will start them auto-
matically.  For  example, if you use fvwm95-2, you can add two  lines
in  the  $HOME/.fvwm2rc95  files  in  the  `AddToFunc "InitFunction"'
section:

+         Exec crxvt -fnb5 taipeik20 -font 10x20 &
+         Exec xcin -in1 cj.tab -fnb5 taipeik24 &

and then re-start the X-window.  All will be OK!


    If you want to type Chinese words directly under the crxvt  shell
prompt, you should execute some commands before doing this:

For bash:  (in the $HOME/.profile or /etc/profile)
    set convert-meta off
    set output-meta on
    stty pass8
    stty cs8 -istrip
    export LC_CTYPE=ISO-8859-1

For csh or tcsh:  (in the $HOME/.cshrc or /etc/csh.cshrc or /etc/csh.login)
    stty pass8
    stty cs8 -istrip
    setenv LC_CTYPE ISO-8859-1

Note: In  some FAQs in the internet, they often recommand that  you 
      should also set the environment variable `LANG=C'.  But after
      some  test I find that if  you set the `LANG=C' variable, the
      `man' and `elm' will work a little funny.  In fact, you don't
      need to set `LANG=C' and the Chinese typing directly under the 
      crxvt shell prompt still works fine.


    If you need additional information, please refer to the documents
installed with xcin package and the corresponding man pages.



<< Feed Back >>

    I hope that these changes actually make the xcin package nicer.
If  you  have any comments or suggestions, it is welcome to mail to:

	Tung-Han Hsieh <thhsieh@twclx.phys.ntu.edu.tw>

	Suei-Jeng Wang <vvvv.bbs@cis.nctu.edu.tw>


    Enjoy!!

						Tung-Han Hsieh
