This is PIG mode, Pinyin Input to Guobiao mode for Mule as well as Emacs users
to use Chinese PinYin as Chinese input.  This file addresses the installation
and usage information about the package.

Version: 1.1
Author:  Ping Zhou  zhou@okra.fnal.gov
Date:    November 16, 1992

Acknowledgment:
---------------
Part of the code are grabbed from ispell and hz2gb package with no or 
minimal change. PinYin table was converted from one file by Ed Lai.
Special thanks goes to Lu, YaYian (lu@rpi.edu) for the help in debugging the
package.

Features:
---------
The pig mode accepts multi-chracter CiZu input and flexible PinYin format.
e.g. Input for Ji4 Suan4 Ji1 (computer) can be Ji4 Suan4 Ji1, jsj, j-s-j,
ji1suan4ji1, ji-s-ji, etc. if the phrase is indeed in your dictionary.

In addition to its usage in Mule (Multi-lingual Emacs) or 8bit-capable Emacs
running in Cxterm window, it also provides a crude way of inputing and viewing
Zhong1 Wen2 in just plain Emacs.

Files:
------
readme			this file
pig-mode.el		main program
pig-mode.elc		byte-compiled version of pig-mode
ZiDian.gb		a PinYin ZiDian in GuoBiao format
CiDian.gb		a PinYin CiDian
ZiDian.el		ZiDian for pig-mode internal use
CiDian.el		CiDian for internal use

Installation:
-------------
1. Copy pig-mode.el, pig-mode.elc, ZiDian.el CiDian.el to any directories in
   your load path. Copy ZiDian.gb and CiDian.gb (or other CiDian you might want
   to use) to any directory of your choice for later editing.
   If you want to use this package inside a 7bit Emacs which cannot display
   Chinese chracters directly, you will also need a 16 point GB bitmap file,
    e.g. Fsong-16.cclib, which is available from many ftp sites. If you don't
   intend to use pig-mode with 7bit Emacs in any way, you don't need this file.
2. Define the variable Pig-PY-table-file to point to ZiDian.gb
                       Pig-CiDian-file to point to CiDian.gb
                       Pig-ZiDian to point to ZiDian.el
                       Pig-CiDian to point to CiDian.el
   in your Emacs initialization file, usually .emacs. e.g.
   (setq Pig-PY-table-file '~/zw/ZiDian.gb'
         Pig-CiDian-file '~/zw/CiDian.gb'
         Pig-ZiDian '~/zw/ZiDian.el'
         Pig-CiDian '~/zw/CiDian.el')
   For 7bit Emacs you also need
   (setq Pig-font-file '~/zw/Fsong-16.cclib').
   Substitute your choice of directories and filenames.
3. If you using it in a 8bit Emacs inside Cxterm, set Pig-8bit-capable to t
   using (setq Pig-8bit capable t).
4. Setup a way to load the code using either autoload or require.
   (autoload 'pig-mode)
   (autoload 'pig-word "pig-mode")
   (autoload 'pig-region "pig-mode")
   (autoload 'pig-buffer "pig-mode")
   or
   (require 'pig-mode)

Usage:
------
You can invoke the package either manually with the command
M-x pig-mode    in the buffer you are editing
or load it automatically with the variable auto-mode-alist, say
(setq auto-mode-alist (append auto-mode-alist '("\\.py" . pig-mode)))
The latter will load pig-mode whenever you edit a file with name *.py

There are two ways to run pig-mode, i.e. batch-mode or instant-mode. Pig-mode
is in batch-mode by default. In batch-mode you type in all the PinYin first,
then with command pig-region, which is bound to key sequence M-$ by default or
pig-buffer you convert all of them into GuoBiao. You can switch to batch-mode
using command pig-batch-mode (bound to \C-b). Personally I think this is
faster, and because of less distraction user can concentrate more on the
contents. However, a lot of time one does need to use instant-mode where you
convert each PinYin word to GuoBiao as you go along.

You can switch to instant-mode with pig-instant-mode command (bound to \C-i).
In instant mode space bar becomes a "hot key". Whenever space key is pressed
pig-mode begins to process the word before the point. Use \C-c(space) to enter
a space.

In any case, command pig-word (bound to M-tab) can used to convert one PinYin
word at or before the point.

You can use PinYin with tones, or without tones in which case all possible
HanZi will be shown. You can use 0 or 5 for Ching1 Sheng1. Use v as u: in
case of ambiguity.

Several ways can be used to input a CiZu:
As an example all following can be used for the input of Ji4 Suan4 Ji1
j-s-j j.s.j j-su-ji ji4-suan4-ji1 ji-suan4-ji jsj ji4suan4ji1
you can see there are more possibilities. The input is case insensitive.

It's thus important to keep in mind the order that this program checks your
PinYin input with ZiDian and/or CiDian.

If there are . or - present, or there are multipule tones present, it's
   exclusively treated as a CiZu. If it's not found in the CiDian, you have
   the option to add a new entry to your CiDian.
If there are no separators, and PinYin has one eding tone [0-5], then it's
   treated exclusively as a single character PinYin word.
If non of the above are true, i.e. pure English letters, treat each letter as
   an initial in a CiZu. If it's not fund in the CiDian, then look as one
   PinYin word .
You have a chance to retype your input for that word in all the above 
   ocassions.

Some of the symbols are bould to \C-c prefixed keys as there is no easy ways
for their input.
e.g. with \C-c. you get chinese period chacter (a small circle). 
Another non-standard way to do this is by PinYin juh (JuHao).
Do a \C-hm in pig-mode to see a list of other similar keys
One special case, with a prefix argument to \C-c< you get the symbol <<.
The same for > symbol.

In Mule, after you have converted all PinYin words into visible HanZi 
you can simply save it and all the HanZi will be in GuoBiao,
or you can use the command "M-x gb2hz-buffer" or "M-x gb2hz-region"
to convert GuoBiao into 7bit ascii chacters with HZ convention, which
can be directly used in mail and Usenet news.

In Emacs, they will be in 7bit GB automatically after they are processed,
so you will only need some ~{ or ~} to conform to HZ or ZW standard. Command
M-x pig-view-buffer and M-x pig-view-region can be used to read HZ-coded
texts. If you load this package before you enter Gnus you can toggle the
article you are reading inside the group of alt.chinese.text between English
text or Zhong1 Wen2 mode using the key "z". The usage of these Zhong1 Wen2
reading related command in plain Emacs, however, should only be used with
short buffers because it is very time consuming to convert and/or reading
those big Chinese characters.

********** Important Note ***************
If you have added new entries to your CiDian, you have to save the CiDian
 permanently using the command M-x pig-save-CiDian. Otherwise you will loose
 the entries for the new CiZu once you quit Emacs or Mule.
If you want a copy of your CiDian in the PinYin-GuoBiao format at any time
  use the command M-x pig-extract-CiDian.
Consequently there are two ways to build up a CiDian:
 either as you editing files by inputing unknown CiZu
 or edit the CiDian file directly and then use the command
 M-x pig-build-CiDian to convert it to the internal format.

If for any reason, you want to rebuild the PinYin ZiDian, command 
pig-build-ZiDian is just for that. The command read from the file defined 
by Pig-PY-table-file. Take a look at the file if you are interested.

Bug report:
-----------
If you find any bugs, or have any comments, suggestions on the program, 
or made improvements to the code, please send them to the author at
zhou@okra.fnal.gov
Thanks in advance.

Problems:
---------
If you have any trouble installing this package, send me a mail at the 
address listed at the beginning.

To do:
------
Dynamic order rearrangement of characters, do we want that ?

