How to use XIM patch for GNU/Emacs20

I will show you an example about how to input Japanese by XIM.
If you intend to input different language, you can basically follow these ways,
but you might need more information.
In the following sections, "$" and "%" represents shell prompt, which requires you
to type them in general.
I assume you're using Emacs20.7, but you can apply the patch to Emacs20.4, 20.5 and 20.6.

You need the followings to input Japanese into Emacs by XIM.
* To apply the patch
* (OS)locale
* X font (e.g. k14 font)
* XIM server (e.g. kinput2)
* XMODIFIERS environment value
* Kana-Kanji conversion server (e.g. cannaserver)
* Emacs fontset setting
* Emacs lisp setting


* To apply the patch
First of all, you need to get emacs-20.7.tar.gz, and unpack it as follows,
$ tar zxvf emacs-20.7.tar.gz
Note: You don't need leim-20.7.tar.gz for XIM input. It doesn't matter for XIM.
To apply the XIM patch as follows,
$ cd emacs-20.7; patch -p1 < emacs20-xim-20000713.diff
After applying the patch, compile emacs-20.7 as usual.


* (OS)locale
XIM is dependent on (OS)locale, while Emacs itself is independent.
Unfortunately, there are various Japanese locale names, such as ja_JP.eucJP(mostly standard).
You might be able to check the Japanese locale on your system as follows,
$ locale -a | grep ja
If you have an appropriate locale or you are familiar with locale, you can skip this section.
It is beyond this document to describe how to install a new locale, but I can give you some hints.
This patch doesn't require a complete locale, because the implementation of this patch
doesn't use wide-char, 
This implies a 'fake' locale below could work.
$ cd /usr/share/locale; ln -s C ja
Please note this kludge depends on the locale implementation of your system.

Note:
I will show some OS specific information.
Debian GNU/Linux:
If you use glibc2.0.x, you need to install "libwcsmbs".
If you use glibc2.1.x, you need "locale-ja" package.
The 'fake' locale above could work with glibc, although it's not recommended.

Other GNU/Linux:
You might need a Japanese locale such as "locale-ja".
In general, if you use a Japanese distribution, you don't have anything to do.

FreeBSD:
The standard distribution contains "ja_JP.EUC" locale in libxpg4,
but it requires you to link 'libxpg4' library to Emacs. 
The easiest way is to set LD_PRELOAD environment value to use libxpg4.
(Example: $ LD_PRELOAD=libxpg4.so.2.0 ./emacs)
I heard the latest FreeBSD has libc including Japanese locale.
I didn't verify it by myself, but if it is true, you don't need anything to do.

Solaris7(Japanese version):
You can use this patch with no effort.

Solaris8:
You need an additional patch.
Please read README file.


* X font (e.g. k14 font)
You need X font, for example, k14 font for Japanese-Kanji.
You can check whether Japanese fonts are installed on your system as follows,
$ xlsfonts | grep jisx


* XIM server (e.g. kinput2)
You need an XIM server to use this patch.
There are several XIM servers.
It is beyond this document to describe how to install XIM server.
XIM server and Kana-Kanji conversion server may be one process, such as ATOK8 for Solaris.
If so, skip the Kana-Kanji conversion server section below.


* XMODIFIERS environment value
If you have only one XIM server, skip this section(maybe).
If you have multiple XIM servers running, you need to specify one by XMODIFIERS
environment value as follows,
$ XMODIFIERS='@im=kinput2'; export XMODIFIERS  (sh)
$ export XMODIFIERS='@im=kinput2'  (bash)
% setenv XMODIFIERS '@im=kinput2'  (csh)
If you use the other XIM server than kinput2, read the document to know what to specify.
Note: You could know it by xlsatoms command.


* Kana-Kanji conversion server (e.g. cannaserver)
Kana-Kanji conversion server is also required.
It is also beyond this document to describe how to install Kana-Kanji conversion server.
Note:
I recommend you to check whether simple XIM programs work or not.
For example, you can get simple programs from the following URLs.
http://www.ainet.or.jp/~inoue/im/sample/xim1.c
http://www.ainet.or.jp/~inoue/im/sample/xim3.c
You can compile and execute it as follows,
$ cc -o xim1 xim1.c -I/usr/X11R6/include -L/usr/X11R6/lib -lX11
$ LANG=ja_JP.eucJP ./xim1  (sh, bash)
% env LANG=ja_JP.eucJP ./xim1  (csh)
If they work, all you have to do is to take care of only Emacs settings.
If they don't work, you have to check your environment again before touching Emacs.


* Emacs fontset setting
Before trying XIM input, I suggest you to verify your Emacs fontset setting.
If fontset setting is wrong, the output would be corrupted, even if you succeed to input Japanese.
If you are not familiar with Emacs fontset, you can follow the instruction below.
Get "Emacs" file from http://www.ainet.or.jp/~inoue/emacs/samples/Emacs.
Copy "Emacs" to your home directory.
Restart emacs.
Check it, e.g. M-x (view-hello-file), and you will see Japanese characters in the buffer.


* Emacs lisp setting
I recommend you to add the following settings in your ~/.emacs.el(~/.emacs).
(set-language-environment "Japanese")
(set-keyboard-coding-system 'euc-japan)
Needless to say, they are dependent on your language and encoding-method specified by the (OS)locale.


Now, try it.
Don't forget to use an appropriate locale, i.e. to set LANG environment variable.
Some examples.
$ LANG=ja_JP.eucJP emacs (sh, bash)
% env LANG=ja_JP.eucJP emacs (csh)
In kinput2 case, shift-space is the standard key combination to toggle Japanese input.

Note:
LC_ALL and LC_CTYPE environment variables make effects over LANG.
(more precisely, LANG is used as fallback value.)
Please check it, e.g. locale -a | grep LC, if something wrong occurs.
