              CANNA Version 3.6, a Japanese input system

                             Canna Project
		     http://canna.sourceforge.jp/

0. Preface

       This file describes the introduction of Canna.  For
  installation of Canna or changes from the previous versions of
  Canna, see the file `INSTALL' or `CHANGES.jp' respectively. (Sorry,
  but `INSTALL' and `README' may not be updated compared to the files
  written in Japanese.  Also sorry that `CHANGES' is provided only in
  Japanese.)

1. Overview

       This directory includes files which are source codes for a
  Japanese input system named Canna.  Canna provides a unified user
  interface for Japanese input.

  *Note:  Canna was called Iroha among developers of Canna
          previously. 

       There exists a commonly usable Japanese input system called
  Wnn.  Canna gives an alternative Japanese input system.

       Canna is based on a client-server model for kana-to-kanji
  conversion, that is, an application program which uses a Japanese
  input system communicates with a kana-to-kanji conversion server,
  which is a separate process from the application program.  Canna has
  several features as follows:

  1) Based on client-server model kana-to-kanji conversion
  2) Supporting automatic kana-to-kanji conversion
  3) Providing a unified user interface to input Japanese
  4) Supporting customization by users
  5) Based on lisp language customization
  6) A mechanism to add a suitable part of speech to each registered
     words by users
  7) Providing a library which supports a unified user interface
  8) Maintenance tools for conversion dictionaries
  9) A customizing tool which supports easy customization
 10) Supporting Nemacs(Mule), kinput2 and uum

       Below, we would like to describe details of Canna's features.

2. Features of Canna

2.1 Based on client-server model kana-to-kanji conversion

       Canna converts kana to kanji based on a client-server model.
  That is, an application program communicates with a kana-to-kanji
  conversion server to achieve Japanese input.

2.2 Supporting automatic kana-to-kanji conversion

       Canna is the first free Japanese input system which supports
  automatic kana-to-kanji conversion which based on client-server
  model.  Generally, it is not easy to operate Japanese with automatic
  kana-to-kanji conversion in PC environment.  However, Canna makes it
  easier for supporting better user interface which extended their
  generally(unautomatically) conversion.

2.3 Providing a unified user interface to input Japanese

       Developers of Canna used to use Egg on Nemacs when we had to
  input Japanese.  Egg was very harmonious with Nemacs and its user
  interface was convenient.

  *Note: Nemacs is a Japanese version of Emacs.  Egg is an interface
         between Nemacs and Wnn.  Egg provides a user interface by
         itself.

       On the other hand, if we had to input Japanese without Nemacs,
  for example, to input Japanese in command line of shell, we were not
  able to use Egg because Egg was usable only in Emacs environment.
  On the other hand, there is also a Japanese input system for TTYs
  called Uum, Uum has a different user interface from Egg and we did
  not become accustomed with it.

       Especially in using X clients, we were eager to use Egg's user
  interface to use them.  We found a lot of good tools on the X window
  system such as xmh and xcalendar.  Our desire was to localize those
  clients into our national language and to operate them with Egg's
  user interface.

<<Let's create another Egg by ourselves>>

       Thus, we decided to create an Egg like system and to provide it
  in a library.  This is the Canna.  Now, Canna provides more features
  than Egg.  Canna can be used in Emacs, in X environments, and also
  on TTYs.

2.4 Supporting customization by users

       As well as key binding, it is possible to customize
  romaji-to-kana conversion rules, status describing strings,
  dictionaries, etc.  A customization is described in a customization
  file.  A customization file can be shared among applications using
  Canna.

2.5 Based on lisp language customization

       Canna used to use a simple syntax for a customization file.
  But once a new function is introduced to the syntax of the
  customization file, old application programs will have to be
  re-written to incorporate the new rules and conditions of Canna.

       According to use new customization syntax based on lisp
  language, it is possible to ignore the descriptions which old
  version's Canna cannot understand.  With new syntax, you can get
  version of Canna or connected server, and it is also possible to
  customize on conditions of these versions.

2.6 A mechanism to add a suitable part of speech to each registered
    words by users

       When we made our own user interface, we added one new idea into
  the word registration part of Canna.

       In kana-to-kanji conversion system, more detailed parts of
  speech are used than what are used in school grammars.  Canna uses
  almost 400 parts of speech.  On the other hand, it might be almost
  impossible and unkind to ask users what kind of a part of speech
  must be used for the registered word.

       In Canna, we made a new mechanism to add a suitable part of
  speech to registered words.  Canna shows several sentences using
  newly registered word, and ask user the usage is correct or not.
  Asking several questions to user helps Canna to decide what part of
  speech is suitable for the newly registered word.

2.7 Providing a library which supports a unified user interface

       A user-interface library is provided.  With this library,
  programmers can easily add a Japanese input system with unified user
  interface to application programs.

       This library has higher-level functions than those Wnn's
  high-level library has, and interpretation of each input key is also
  processed inside of this library.

       An interface to this library is simple.  Giving input key to
  this library returns several pieces of information to display
  pre-edit status.  Interpretations of key functions are hidden inside
  of this library, and it is not necessary for application programs to
  be conscious of them.

       This library meets the case of treating inputs from several
  windows.  By giving context identifiers which correspond to each
  window with key inputs to this library makes it possible to process
  plural kana-to-kanji conversion concurrently in a process.

2.8 Maintenance tools for conversion dictionaries

       Canna provides more than ten tools to maintain kana-to-kanji
  conversion dictionaries.  Using these tools, you can do the
  following things.

   - Conversion between text format dictionaries and binary format
     ones.
   - Creating, deleting, listing, renaming dictionaries by remote
     operation
   - Uploading and downloading dictionaries
   - Adding/deleting items to/from a dictionary by a batch procedure

2.9 A customizing tool which supports easy customization

       In place of editing a customization file directly, it is
  possible to set up customization by using a customizing tool.

2.10 Supporting Nemacs(Mule), kinput2 and uum

       Canna provides a patch for Nemacs(Mule), which makes
  Nemacs(Mule) possible to input Japanese in Canna's unified user
  interface.  And, after Mule 0.9.5, the distribution of Mule includes
  interface to Canna.

       If kinput2 use Canna as kana-to-kanji conversion engine,
  application programs which use kinput can use Canna's unified user
  interface to input Japanese

       Additionally, Canna supports a patch for uum, which makes
  possible to input Japanese in Canna on TTYs.  For uum, see
  canuum/README.jp.  (Sorry, but canuum/README.jp is in Japanese.)

3.  Contents of Canna

       Canna contains the following things.

   - Kana-to-kanji conversion server (cannaserver)
   - User interface library (libcanna.a, libcanna.so.1)
   - Remote version of dictionary accessing library (libRKC.a)
   - Local version of dictionary accessing library (libRK.a)
   - Maintenance tools for conversion dictionaries
   - Patch files for uum of Canna version
   - A sample program

4. Documents

       Under this directory, there are several documents.  Most of
  them are in Japanese.

  1) Document of Canna (in Japanese)

       The document is in jlatex format and is in doc/man/guide.
  This document describes the general comments of how to use Canna.

  2) Documents for commands

       The documents are in man macro format of roff and are in the
  respective directory.  Source codes are also available in same
  directory.  Japanese documents have suffix .jmn, and English have
  .man.

  3) Documents for application interface library

       The documents are in man macro format of roff and are in
  lib/canna and lib/RK.

  4) Document for kana-to-kanji conversion protocol (in Japanese)

       The document is in jlatex format and is in doc/intern.  Canna
  has the protocol versions 1.0, 1.1, 2.0, 2.1, 3.0 and 3.2.  The
  document of the protocol version 1.0 and 1.1 is the file
  proto12.tex.  Other version's document is protocol.tex.

  5) Document for lisp language of customization file (in Japanese)

       The document is in jlatex format and is in doc/lisp as
  canlisp.tex.

  6) Document for uum of Canna version

       The notes is in text file format and is in canuum as README.jp.

  7) Other Documents

       The documents are in jlatex format and are in doc/misc.

5. Bugs

       Canna have some bugs as follows:

  (1) Canuum doesn't run on Solaris 2.1.

  (2) Canuum doesn't run on SunOS 4.2 with compiler gcc.

  (3) On SONY NEWS, the terminal mode on pseudo tty is different which
      make by canuum.

  (4) No English documents as follows:
        canuum/canuum.man

  (5) When using automatic kana-to-kanji conversion, you sometimes can
      not convert correctly.

  (6) On Solaris 2.3, you will have some cores.

  (7) When you compile, you will have a warning message "Undefined row
      vectors: BM".  Don't worry it.


6. Acknowledgements

  see README.ja.

/* Copyright (c) 2003 Canna Project. All rights reserved.
 *
 * Permission to use, copy, modify, distribute and sell this software
 * and its documentation for any purpose is hereby granted without
 * fee, provided that the above copyright notice appear in all copies
 * and that both that copyright notice and this permission notice
 * appear in supporting documentation, and that the name of the
 * author and contributors not be used in advertising or publicity
 * pertaining to distribution of the software without specific, written
 * prior permission.  The author and contributors no representations
 * about the suitability of this software for any purpose.  It is
 * provided "as is" without express or implied warranty.
 *
 * THE AUTHOR AND CONTRIBUTORS DISCLAIMS ALL WARRANTIES WITH REGARD TO
 * THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS, IN NO EVENT SHALL THE AUTHOR AND CONTRIBUTORS BE LIABLE FOR
 * ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
 * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
 * CONTRACT, NEGLIGENCE OR OTHER TORTUOUS ACTION, ARISING OUT OF OR IN
 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 
 */

/* Copyright 1994 NEC Corporation, Tokyo, Japan.
 *
 * Permission to use, copy, modify, distribute and sell this software
 * and its documentation for any purpose is hereby granted without
 * fee, provided that the above copyright notice appear in all copies
 * and that both that copyright notice and this permission notice
 * appear in supporting documentation, and that the name of NEC
 * Corporation not be used in advertising or publicity pertaining to
 * distribution of the software without specific, written prior
 * permission.  NEC Corporation makes no representations about the
 * suitability of this software for any purpose.  It is provided "as
 * is" without express or implied warranty.
 *
 * NEC CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN 
 * NO EVENT SHALL NEC CORPORATION BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF 
 * USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR 
 * OTHER TORTUOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 
 * PERFORMANCE OF THIS SOFTWARE. 
 */

($Id: README,v 1.6 2003/09/25 15:24:31 aida_s Exp $)
