Info file: quail,    -*-Text-*-
produced by `texinfo-format-buffer'
from file `quail.texi'
using `texinfmt.el' version 2.32 of 19 November 1993.




File: quail, Node: Top, Up: (mule)

QUAIL -- Imputting methods of multilingual text
===============================================

Quail is a simple key-translation system which allows users to input any
multilingual text from normal ASCII keyboard.

We provide several quail-packages, each package corresponds to one
inputting methods.  For instance, the file lisp/quail/py.el provides a
package for inputting Chinese by PinYin.  lisp/quail/hangul.el provides
a package for inputting Korean.

* Menu:

* Usage of Quail::
* Structure of Quail::  For quail package writers.


File: quail, Node: Usage of Quail, Next: Structure of Quail, Up: Top

Usage of Quail
==============

You can load several packages at once but only the translation rules
defined in the current package are effective.  Quail-mode is toggled by
C-].  When you enter in quail-mode, the current package is shown at the
left of modeline as: `[xxxxx]' where xxxxx is the multilingual text for
the current package.  In quail-mode, M-s changes the current package
(normal completion is performed by hitting <SPC> or <TAB>).

In quail-mode, all graphic keys you type is translated according to the
rules of the current package.  Brief description about the rules and
key-bindings are shown by M-z.

While there are more than one candidates for what you type, the first
candidate is shown in buffer with underscore.  By M-n and M-p you can
select any other candidate.  M-i shows list of candidates (showing each
candidate with index number [two digits]).  You can select one also by
typing these digits.

Once you select a desired candidate, please just type a key for another
character.  The underscore moves to the next key automatically.  But, in
some packages (e.g. hangul), there are rules something like:
     	ab  -> A
     	aba -> B
     	b   -> C

In this case, if you type "abab", quail will enter "AA".  If what you
want is "BC", you must explicitly tell the division point of the
character by hitting <SPC>.  In this example, you should have typed
"aba<SPC>b".

Here's the summary of command keys:
     ------------------------------------------------------------
     C-]:	Exit from quail-mode.
     DEL:	Delete characters backward in quail-mode.
     M-i:	Show list of candidates.
     M-n:	Select next candidate.
     M-p:	Select previous candidate.
     M-s:	Select quail-package.
     M-z:	Show brief description of the current quail-pacakge.
     ------------------------------------------------------------


File: quail, Node: Structure of Quail, Prev: Usage of Quail, Up: Top

Structure of Quail
==================

#### NOT COMPLETED, NOT UPDATED ####

This section is intended to help emacslisper who try to debug or enhance
'quail' system.  The original code quail.el is located under the
directory mule/lisp/quail.el.

Quail serves as a front end processor for inputing multilingual text
from normal ASCII keyboard.  By defining a translation table which maps
ASCII string to multilingual string, you can input any text from ASCII
keyboard.

For the momemnt, translation table for Chinese inputing distributed with
X.V11R5/contrib/cxterm are supported in mule/lisp/quail/XXXX.el files.
You can use the system also for inputing various Korean/European
characters.

Quail system registers translation table in keymap of Emacs, thus table
lookup is done just by calling function `lookup-key', and new
registration is done just by calling function 'define-key'.  Keymap is
represented as a structured association list.  For instance, a
translation table of the form ("a" -> "A" or "a", "ab" -> "AB", "c" ->
"C") is represented as follows:

       (keymap . ((?a . (keymap . ((?\377 . '(0 "A" "a")
     			      (?b . (keymap . ((?\377 . '(0 "AB")))))))))
     	     (?c . (keymap . ((?\377 . '(0 "C")))))))

As you see, the final string of translation is registered under the tag
of ?\377.  Hence, the following program creates the map above.

     	(setq m (make-sparce-keymap))
     	(define-key m "a\377" '(0 "A" "a") t)
     	(define-key m "ab\377" '(0 "AB") t)
     	(define-key m "c\377" '(0 "C") t)

Each '0' means that the first candidate in the list is selected at
first.  In this case, according to your typing, buffer contents changes
as follows:

     	Type:	a	M-n	b	c	a	b
     	Buffer:	A	a	AB	ABc	ABca	ABcab
     	Uline:	-	-	--	  -	   -

where Uline shows which characters are displayed with underline.  While
underline is shown, we say that quail is in 'translation state'.  We
assumed that M-n is bound to `quail-next-candidate'.

The last argument of `define-key' 't' means that meta characters in the
key-string are processed as is (not as ESC + char), which is a Mule
specific facility.  Since keymaps can be nested, you can share one
keymap (say m) with two other keymaps (say m1 and m2) by:

     	(define-key m1 "x" m)
     	(define-key m2 "y" m)

This means the translation ("xa" -> "A" or "a", "xab" ->
"AB", "xac" -> "C") in map m1 and ("ya" -> "A" or "a", "yab"
-> "AB", "yac" -> "C") in m2.

We call a keymap which satisfies the description above as a 'quail-map'
here after.  Quail handles a quail-map with additional information as a '
quail-package'.  Each quail-package holds the following information as a
list:

  1. name (string [ASCII only]): Name of the package.

  2. prompt (string [any characters]): A string shown in mode-line as a
     name of quail mode.

  3. quail-map: A quail map described above.

  4. showkey (alist): An alist of character typed and corresponding
     string to be shown in echo area.  For instance, quail-package
     namede "ccdospy" has the following showkey:

           '((?a . "zh") (?f . "en") (?g ."eng") (?h . "ang") (?i . "ch") (?j . "an")
             (?k . "ao") (?l . "ai") (?s . "ong") (?u . "sh") (?y . "ing") (?v . "yu"))

     This says that if you type 'a', "zh" is shown in echo area.  If 'f'
     is followed by 'a', "zhen" is shown.

  5. document (string): A document shown by quail-help command.

  6. mode-map (keymap): A keymap to control quail mode.  This defaults
     to `quail-mode-default-map'.  Prefix character is restricted to ESC
     only, which means you can not define such key sequence as "\C-xi"
     in this map.  In addition, defining '!' through '~' are no use
     because those keys are overridden by `quail-self-insert-command'.

  7. nolearn (flag): A flag to control learning facility of quail.  If
     this flag is non-nil, quail does not remeber the last selection of
     candidate string for the later selection.

  8. deterministic (flag): A flag to specify that only one target string
     is defined in the quail-map for each key sequence (i.e. no
     alternative candidates).  If this flag is non-nil, quail
     automatically exit from the translation state when a target string
     for a key sequence is found.

All packages defined are in `quail-package-alist' (see document of
quail-define-package).

Users are recommended not to modify quail-map directly but to use
quail-defrule function (see document of quail-defrule).

You may find the example of defining quail package and defining
translation rule of the package in lisp/quail/latin.el

Quail system works as one of a minor mode so that it works under any
major modes.  But, the way of handling non-quail commands are very
different from that of the other minor modes.  All keys typed are eaten
by the system because, in quail mode, keys except for invoking quail
specific commands are bound to 'quail-non-quail-command.  The function,
at first, resets quail translation status (we'll explain it below),
then, checks the original binding of the key in local map or global map
and invokes the command bound to the key.

Quail keeps the current state of transformation with the following
variables:

   * `quail-overlay'

     Keep points of start and end of a string inserted by the system.
     The string is one of below.

   * `quail-current-key'

     A key string typed so far for the current translation.  When
     there's no translation for the key, this string is inserted in a
     buffer temporally.

   * `quail-current-str'

     A string translated from `quail-current-key'.  In addition,
     attribute region is set automatically around the sting inserted in
     a buffer.

