README

      _                   _
  ___| |__   _____      _(_)_ __   __ _
 / __| '_ \ / _ \ \ /\ / / | '_ \ / _` |
| (__| | | |  __/\ V  V /| | | | | (_| |
 \___|_| |_|\___| \_/\_/ |_|_| |_|\__, |
                                  |___/

libchewing - The intelligent phonetic input method library
  http://chewing.im/

[-] Summary

The Chewing (酷音) input method is an intelligent phonetic (Zhuyin/Bopomofo)
input method. It is one of the most popular input methods among Traditional
Chinese users.  Chewing was inspired by other proprietary intelligent Zhuyin
input methods under Microsoft Windows, namely, Wang-Xin by Eten, Microsoft New
Zhuyin, and Nature Zhuyin.

The Chewing core team extended their work and actively maintains the project
as full open source efforts.

Website: http://chewing.im/
Mailing lists:
  - Development: http://groups.google.com/group/chewing-devel
  - General: http://groups.google.com/group/chewing
Issue tracker: http://code.google.com/p/chewing/issues/list


[-] History

libchewing is derived from Chewing input method, a xcin module focusing on
intelligent phonetic (Bopomofo/Zhuyin) processing by Lu-chuan Kung (lckung)
and Kang-pen Chen (kpchen) sponsored by Tsan-sheng Hsu from Academia Sinica
during 1999-2001.  However, the original authors of Chewing dropped its
development, and Chewing was highly coupled with xcin, which prevents from
comprehensive applications.  There was a similar input method, bimsphone,
which was bundled in XCIN server. However, it did not provide a convenient
API for further development, either.


[-] Motivation

Jim Huang, et al. formed the Chewing core team and extended Kung and Chen's
work since 2002.  The chewing core team renamed the project as "new" chewing
to differentiate their work from the original.  Nevertheless, the English name
has remained "chewing", which is identified by various input method framework
as well.

In 2004, Chewing core team successfully ported the input method to several
platforms and framework along with community collaboration.


[-] Development Goal of libchewing

- Split logic and view.
- Support multiple operating systems, and input framework.
- Provide a universal API for input framework and further development.


[-] Status

1. System bridge integration

Chewing has been adopted by various input frameworks in Unix-like systems and
even Microsoft Windows.  On these systems, the chewing package is usually
split into two parts: libchewing, which handles the actual character selection
logic; and input framework interface for display and preference setting.

The active integration:
  - JMCCE
  - SCIM
  - standalone Microsoft Windows 32/64-bit (windows-chewing)
  - UIM
  - ibus
  - UCIMF
  - mozc
  - gcin/HIME
  - fcitx

The inactive one:
  - xcin
  - IIIMF
  - MacOS X (SpaceChewing)
  - Sun's Java Desktop System Input Method Framework
  - OpenVanilla Input Method Framework (previous than version 1.0)
  - OXIM

2. support phonetic keyboard layout
  - Hsu
  - IBM
  - Gin-Yieh
  - Eten
  - Eten 26 keys
  - Dvorak
  - Dvorak Hsu
  - HanYu PinYin
  - Taiwan Huayu Luomapinyin
  - MPS2 Pinyin

3. External and unmerged projects

libchewing provides straightforward API and design, which enables third-party
projects to deploy the innovative.  Here are the examples:

  * FreeArray: utilizing libchewing for selecting phrases of Array input
    method.
    https://github.com/shaform/libfreearray
    https://github.com/shaform/ibus-freearray

  * CitC (Chewing in the Cloud): extending cloud services for real-time
    training and phrase selection based on Chewing IM.
    https://code.google.com/p/citc/

  * KindleChewing: Chewing IM for Kindle DX device
    https://github.com/tjwei/KindleChewing

  * NTNU-Master Input Method: A Faster Chinese IM based on windows-chewing
    https://sites.google.com/site/ntnumaster001/


[-] Minimal Build Tools Requirement

The following tools are used to build libchewing. Not all tools are necessary
during building. For example, if the compiler you used is clang, gcc & Visual
Studio are not needed. The versions listed here is the minimal version known to
build libchewing. If any tools you use below this version, libchewing might not
be built.

Build tools:
- autoconf >= 2.67
- automake >= 1.11.6
- libtool >= 2.4.2
- cmake >= 2.8.8 (optional)

Toolchain / IDE:
- clang >= 3.2
- gcc >= 4.7.3
- Visual Studio Express 2012

Documentation tools:
- texinfo >= 4.12


[-] Continuous Integration (CI) Service

libchewing uses the following CI services:

- https://travis-ci.org/chewing/libchewing (testing)
- https://drone.io/github.com/chewing/libchewing (testing)
- https://coveralls.io/r/chewing/libchewing (coverage report)
- https://launchpad.net/~chewing/+archive/chewing (ubuntu PPA)


[-] Installation

# ./configure --prefix=/usr
  (If you checkout from GIT, make sure running ./autogen.sh
   before this.)
# make
# make install

see "INSTALL" for details.


[-] Cross-build

Example cross-build instructions:
# CC=arm-none-linux-gnueabi-gcc ./configure \
    --host=arm-none-linux-gnueabi \
    --disable-shared --enable-static
# make CC_FOR_BUILD=gcc


[-] Build on Windows with MinGW

To build libchewing on Windows, you need to setup MinGW and MSYS in your
system. The installer of MinGW and MSYS is in the following link:

http://sourceforge.net/projects/mingw/files/Installer/mingw-get-inst/

In "Select Components" during installing, please select the following items:

- MinGW Compiler Suite -> C Compiler
- MSYS Basic System

After installing, execute <MinGW directory>\msys\1.0\msys.bat (default is
C:\MinGW\msys\1.0\msys.bat) to enter MSYS shell.

If you get the source from the git repository you need additional step
to make the source buildable; use the following commands to install
necessary packages.

- mingw-get install automake
- mingw-get install autoconf
- mingw-get install libtool

Now you have the build environment for libchewing. However, you need to check
the line end of source code is LF instead of CR/LF before running autogen.sh.
The easily way to do this is using git:

- git config core.autocrlf input
- rm -rf *
- git reset --hard

Now you can run the following commands in MSYS shell to build libchewing:

If you get the source from the git repository, run:

- autogen.sh

Then

- configure
- make

If you run testchewing.exe (available after `make check') you will
find that testchewing.exe cannot print the correct string. This is
because testchewing.exe prints the UTF-8 string, while Windows cannot
print it to console.


[-] Build with CMake

libchewing supports cmake (http://www.cmake.org/) build system. You can use the
following command to build with cmake:

- cmake .
- make

cmake is also the preferred way to build libchewing on Windows platform due to
better Windows integrated. You can use the following command to create Visual
Studio project in 32-bits Windows platform:

- cmake . -G "Visual Studio 11"

or the following command to create Visual Studio project in 64-bits Windows
platform:

- cmake . -G "Visual Studio 11 Win64" (64-bits Windows)


[-] Usage

( modified from http://code.google.com/p/ibus/wiki/ChewingUserGuide )

Chewing guides the user to input Chinese by its pronunciation, in the form of
either Bopomofo/Zhuyin[1] or Hanyu pinyin[2], as well as Chinese punctuation
marks and normal and full shape number and English alphabets.

The following sections assume you are using the default configuration, that is,
with default/DaChen Bopomofo keyboard layout, on an en_US keyboard, and default
key-binding.

= Glossary =
Preedit buffer: The places for storing your typing before sending to the
applications (such as firefox) you are using.

Mode: Mode determines how Chewing reacts on keyboard input.

= Editing mode =
This mode is for normal Chinese character and punctuation typing. You are more
likely working on this mode.

In this mode, alpha-numberic and punctuation marks are interpreted as either
Bopomofo symbols or punctuation marks. If the symbols can form Chinese
characters, it will choose the most suitable character according to the
context in preedit buffer.

It is recommended that you enter the whole Chinese sentences, so Chewing can
do auto-correction for you.  If you like what you see, you can press Enter to
commit the characters in preedit buffer.

If something goes wrong, you can select the character by move your cursor
using {Left} or {Right}, then press {Down} to enter Candidate Selection mode
to choose words.

To prevent the auto-correction on certain phrase, you may press {Tab} to
break the auto-correction on the end of the sentence.

You can also remember the 2,3,4 words phrases by pressing {Ctrl-2}, {Ctrl-3},
and {Ctrl-4} on the end of the phrase.

Also note that Shift's behavior changes in this mode. Shift-(alpha number)
outputs corresponding Full shape Chinese symbols if "Easy symbol input" is
enabled; Or outputs corresponding number half shape lowercase English
alphabets if "Easy symbol input" is disabled.

Talking about inputing Chinese symbols, other then enable "Easy symbol input"
mode, you can also press {Ctrl-1} or {`} to open up a symbol selection dialog,
select the category, then use {Down} key to choose the symbols as you would do
for characters.

Key binding   API name                   Functionality
-----------   --------                   -------------
Caps Lock     chewing_handle_Capslock    Toggle Temporary English sub-mode
Down          chewing_handle_Down        Enter Candidate Selection mode
Shift-Space   chewing_handle_ShiftSpace  Toggle Half/Full Shape sub-mode
Enter         chewing_handle_Enter       Commit the content in preedit buffer
                                         to active application window
Tab           chewing_handle_Tab         Break the auto-correction.
Ctrl-1        chewing_handle_CtrlNum     Open symbol selection dialog
Ctrl-2        chewing_handle_CtrlNum     Remember 2-word phrase.
Ctrl-3        chewing_handle_CtrlNum     Remember 3-word phrase.
Ctrl-4        chewing_handle_CtrlNum     Remember 4-word phrase.

= Half/Full Shape sub-mode =

This sub-mode is for inputing half shape and full shape characters. Half shape
characters are essentially normal English characters; while the full shape
characters are full-width pretty symbols that resemble English characters.

Key binding   API name                   Functionality
-----------   --------                   -------------
Shift-Space   chewing_handle_ShiftSpace  Toggle Half/Full Shape sub-mode

= Temporary English sub-mode =

This sub-mode is for temporary English inputting.

Key binding   API name                   Functionality
-----------   --------                   -------------
Caps Lock     chewing_handle_Capslock    Toggle Temporary English sub-mode

= Candidate Selection mode =

This mode is for Choosing the candidate. Firstly, the longest phrases that fit
the pronunciation are shown, then the second shortest, till the single
characters. Pressing {Down} again to return to the longest phrases.

For example, after entering "w91o3g4". Pressing {Down} makes Chewing displays
3-word candidate "台北市"; pressing {Down} again makes Chewing displays 2-word
candidate "北市"; pressing {Down} again makes Chewing displays 1-word
candidates "市","是"; pressing {Down} again makes Chewing displays back the
3-word candidates "台北市";

Key binding   API name                   Functionality
-----------   --------                   -------------
Down          chewing_handle_Down        Next bunch of candidates in
                                         different length
Left          chewing_handle_Left        Previous page of candidates
Right         chewing_handle_Right       Next page of candidates
1, 2, ...0    chewing_handle_Default     Select 1st, 2nd, ... 10th candidate

= Bypass mode =

This mode is on whenever the preedit buffer is empty. This allows you to use
movement keys (such as cursor keys and page up/page down) and popular key
binding (Ctrl-A, Ctrl-S).

For the brief usage of libchewing APIs, please check the simplified example
implemented in file contrib/simple-select.c

*1 http://en.wikipedia.org/wiki/Bopomofo
*2 http://en.wikipedia.org/wiki/Pinyin


[-] License

GNU LGPL (Lesser General Public License).
See "COPYING" for details.


[-] Authors & Contact Information

See "AUTHORS" for details.