#################################################################
#								#
#                   XCIN version 2.3.03 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@twcpro.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.  Because 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 INCOMPLETE 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  closer  to 
completion.   However, it  could  be  somewhat  risky  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  interested in  testing this version,  I certainly welcome you to
use it and send me bug reports if you encounter any problems.

    If anyone has comments or suggestions about my modification, please
mail to me.  I hope that everyone who is interested 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 encouraged me and 
suggested 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.03 
package.



<< What's New >>

This is a pre-release of xcin-2.4, which I intend that it will be a "stable"
version. It only contains the new features from <vvvv.bbs@bbs.cis.nctu.edu.tw>,
and this source is based on "xcin-2.3.02-3-21.src.rpm" from the "CLE-0.6"
distribution. Thanks to Platin to provide this source.

 1. patch from  <vvvv.bbs@bbs.cis.nctu.edu.tw>
        Add the XcinFix5.3 package.

 2. remove the crxvt part from the package.

 3. rewrite the configure scripts.

 4. remove some un-useful tools: et2bdf, et-tab to cin converter.

 5. fix problems of "tsa2rel" in Solaris system.

 6. the ".cin" tables like: 3-dayi.cin, array30.cin, liu5.cin and
    liu51.cin has been temperately removed because of the copyright
    issues.



<< 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 searching the rc_file remained
	in command line.  The rc_file has the structure 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 syntax analysis engine to prevent you
	from 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-definition.
	Selection-keys for duplicate Chinese characters.
	Quick-key definition.
	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 particular:
	Originally Ctrl+Alt+3 & Ctrl+Alt+6 are particular input-methods
	which cannot be altered.  In the future this restriction will
	be removed.  All input-methods will have unified operation 
	interface and the same ".cin" source file.

    Currently the definition and design of RXP is up-to-here.  We
are keeping on further programming.  I think that this is truly "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 functionality 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 functionality but only fix bugs or problems.  Hope
that this will be more stable for use.



<< The Structure >>

    As before, xcin-2.3.03 has the following structures:

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

2. xcin-2.3.03/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.03/input_tab/:
	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.

4. xcin-2.3.03/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.03/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.03/configure  program.
	Also, you can see that there is a Makefile.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
	In one of your search path. Default is `/usr/local/bin'

2. 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

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.  One 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 recommended.  It can cooperate 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. See for "xcin-2.3.03/script/config.help"
   for detailed description about the configuration.

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

4. As root, (you do not need to be 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.03/docs/Xfonts.HOWTO  to do
   fonts installation.

6. After installation, the make will generate xcin-2.3.03/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. Installation complete!  Now you can re-start 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 new to the xcin system, the following information
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  appears.  By default, crxvt
searches for "8x16" as its English font and "taipei15" as its Chinese
font.  If you  do not  have the "taipei15.pcf" font installed,  crxvt
would  display the error message  "crxvt: can't access font taipei15"
and quit.  In this case, you should provide a option to tell crxvt to
use some other fonts.  For example, if you have "taipeik20",  and you
want crxvt to use the 10x20 English font, you can use:

	crxvt -fnb5 taipeik20 -font 10x20 &

Besides 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
convention 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  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 every time 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 need to 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 on the Internet, they often recommend 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.



<< Feedback >>

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

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

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


    Enjoy!!

						Tung-Han Hsieh