Mercurial > hg > xemacs-beta

comparison man/mule/quail.texi @ 70:131b0175ea99 r20-0b30

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r20-0b30
author cvs
date Mon, 13 Aug 2007 09:02:59 +0200
parents
children
comparison
equal deleted inserted replaced
69:804d1389bcd6 70:131b0175ea99
1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../info/quail
3 @settitle QUAIL -- Imputting methods of multilingual text
4
5 @titlepage
6 @sp 6
7 @center @titlefont{QUAIL -- Imputting methods of multilingual text}
8 @sp 4
9 @center Version 2.0
10 @sp 5
11 @center Ken'ichi HANDA
12 @center handa@@etl.go.jp
13 @page
14
15 @end titlepage
16
17 @node Top, , , (mule)
18 @section QUAIL -- Imputting methods of multilingual text
19
20 Quail is a simple key-translation system which allows users
21 to input any multilingual text from normal ASCII keyboard.
22
23 We provide several quail-packages, each package corresponds
24 to one inputting methods. For instance, the file
25 lisp/quail/py.el provides a package for inputting Chinese by
26 PinYin. lisp/quail/hangul.el provides a package for
27 inputting Korean.
28
29 @menu
30 * Usage of Quail::
31 * Structure of Quail:: For quail package writers.
32 @end menu
33
34 @node Usage of Quail, Structure of Quail, , Top
35 @section Usage of Quail
36
37 You can load several packages at once but only the
38 translation rules defined in the current package are
39 effective. Quail-mode is toggled by C-]. When you enter in
40 quail-mode, the current package is shown at the left of modeline as:
41 @quotation
42 @code{[xxxxx]}
43 @end quotation
44 where xxxxx is the multilingual text for the current
45 package. In quail-mode, M-s changes the current package
46 (normal completion is performed by hitting <SPC> or <TAB>).
47
48 In quail-mode, all graphic keys you type is translated
49 according to the rules of the current package. Brief
50 description about the rules and key-bindings are shown by
51 M-z.
52
53 While there are more than one candidates for what you type,
54 the first candidate is shown in buffer with underscore. By
55 M-n and M-p you can select any other candidate. M-i shows
56 list of candidates (showing each candidate with index number
57 [two digits]). You can select one also by typing these
58 digits.
59
60 Once you select a desired candidate, please just type a key
61 for another character. The underscore moves to the next key
62 automatically. But, in some packages (e.g. hangul),
63 there are rules something like:
64 @example
65 ab -> A
66 aba -> B
67 b -> C
68 @end example
69
70 In this case, if you type "abab", quail will enter "AA". If
71 what you want is "BC", you must explicitly tell the division
72 point of the character by hitting <SPC>. In this example,
73 you should have typed "aba<SPC>b".
74
75 Here's the summary of command keys:
76 @example
77 ------------------------------------------------------------
78 C-]: Exit from quail-mode.
79 DEL: Delete characters backward in quail-mode.
80 M-i: Show list of candidates.
81 M-n: Select next candidate.
82 M-p: Select previous candidate.
83 M-s: Select quail-package.
84 M-z: Show brief description of the current quail-pacakge.
85 ------------------------------------------------------------
86 @end example
87
88 @node Structure of Quail, , Usage of Quail, Top
89 @section Structure of Quail
90
91 #### NOT COMPLETED, NOT UPDATED ####
92
93 This section is intended to help emacslisper who try to
94 debug or enhance 'quail' system. The original code quail.el
95 is located under the directory mule/lisp/quail.el.
96
97 Quail serves as a front end processor for inputing
98 multilingual text from normal ASCII keyboard. By defining a
99 translation table which maps ASCII string to multilingual
100 string, you can input any text from ASCII keyboard.
101
102 For the momemnt, translation table for Chinese inputing
103 distributed with X.V11R5/contrib/cxterm are supported in
104 mule/lisp/quail/XXXX.el files. You can use the system also
105 for inputing various Korean/European characters.
106
107 Quail system registers translation table in keymap of Emacs,
108 thus table lookup is done just by calling function
109 @code{lookup-key}, and new registration is done just by calling
110 function 'define-key'. Keymap is represented as a
111 structured association list. For instance, a translation
112 table of the form ("a" -> "A" or "a", "ab" -> "AB", "c" ->
113 "C") is represented as follows:
114
115 @example
116 (keymap . ((?a . (keymap . ((?\377 . '(0 "A" "a")
117 (?b . (keymap . ((?\377 . '(0 "AB")))))))))
118 (?c . (keymap . ((?\377 . '(0 "C")))))))
119 @end example
120
121 As you see, the final string of translation is registered
122 under the tag of ?\377. Hence, the following program
123 creates the map above.
124
125 @example
126 (setq m (make-sparce-keymap))
127 (define-key m "a\377" '(0 "A" "a") t)
128 (define-key m "ab\377" '(0 "AB") t)
129 (define-key m "c\377" '(0 "C") t)
130 @end example
131
132 Each '0' means that the first candidate in the list is
133 selected at first. In this case, according to your typing,
134 buffer contents changes as follows:
135
136 @example
137 Type: a M-n b c a b
138 Buffer: A a AB ABc ABca ABcab
139 Uline: - - -- - -
140 @end example
141
142 where Uline shows which characters are displayed with
143 underline. While underline is shown, we say that quail is
144 in 'translation state'. We assumed that M-n is bound to
145 @code{quail-next-candidate}.
146
147 The last argument of @code{define-key} 't' means that meta
148 characters in the key-string are processed as is (not as ESC
149 + char), which is a Mule specific facility. Since keymaps
150 can be nested, you can share one keymap (say m) with two
151 other keymaps (say m1 and m2) by:
152
153 @example
154 (define-key m1 "x" m)
155 (define-key m2 "y" m)
156 @end example
157
158 This means the translation ("xa" -> "A" or "a", "xab" ->
159 "AB", "xac" -> "C") in map m1 and ("ya" -> "A" or "a", "yab"
160 -> "AB", "yac" -> "C") in m2.
161
162 We call a keymap which satisfies the description above as a
163 'quail-map' here after. Quail handles a quail-map with
164 additional information as a 'quail-package'. Each
165 quail-package holds the following information as a list:
166
167 @enumerate
168 @item
169 name (string [ASCII only]): Name of the package.
170
171 @item
172 prompt (string [any characters]):
173 A string shown in mode-line as a name of quail mode.
174
175 @item
176 quail-map: A quail map described above.
177
178 @item
179 showkey (alist):
180 An alist of character typed and corresponding string to be shown in echo
181 area. For instance, quail-package namede "ccdospy" has the following
182 showkey:
183
184 @example
185 '((?a . "zh") (?f . "en") (?g ."eng") (?h . "ang") (?i . "ch") (?j . "an")
186 (?k . "ao") (?l . "ai") (?s . "ong") (?u . "sh") (?y . "ing") (?v . "yu"))
187 @end example
188
189 This says that if you type 'a', "zh" is shown in echo area.
190 If 'f' is followed by 'a', "zhen" is shown.
191
192 @item
193 document (string): A document shown by quail-help command.
194
195 @item
196 mode-map (keymap):
197 A keymap to control quail mode. This defaults to
198 @code{quail-mode-default-map}. Prefix character is restricted to ESC only,
199 which means you can not define such key sequence as "\C-xi" in this map.
200 In addition, defining '!' through '~' are no use because those keys are
201 overridden by @code{quail-self-insert-command}.
202
203 @item
204 nolearn (flag):
205 A flag to control learning facility of quail. If this flag is non-nil,
206 quail does not remeber the last selection of candidate string for the
207 later selection.
208
209 @item
210 deterministic (flag):
211 A flag to specify that only one target string is defined in the
212 quail-map for each key sequence (i.e. no alternative candidates). If
213 this flag is non-nil, quail automatically exit from the translation
214 state when a target string for a key sequence is found.
215 @end enumerate
216
217 All packages defined are in @code{quail-package-alist} (see
218 document of quail-define-package).
219
220 Users are recommended not to modify quail-map directly but
221 to use quail-defrule function (see document of quail-defrule).
222
223 You may find the example of defining quail package and
224 defining translation rule of the package in
225 lisp/quail/latin.el
226
227 Quail system works as one of a minor mode so that it works
228 under any major modes. But, the way of handling non-quail
229 commands are very different from that of the other minor
230 modes. All keys typed are eaten by the system because, in
231 quail mode, keys except for invoking quail specific commands
232 are bound to 'quail-non-quail-command. The function, at
233 first, resets quail translation status (we'll explain it
234 below), then, checks the original binding of the key in
235 local map or global map and invokes the command bound to the
236 key.
237
238 Quail keeps the current state of transformation with the
239 following variables:
240
241 @itemize
242 @item @code{quail-overlay}
243
244 Keep points of start and end of a string inserted by
245 the system. The string is one of below.
246
247 @item @code{quail-current-key}
248
249 A key string typed so far for the current translation.
250 When there's no translation for the key, this string
251 is inserted in a buffer temporally.
252
253 @item @code{quail-current-str}
254
255 A string translated from @code{quail-current-key}. In addition,
256 attribute region is set automatically around the sting inserted in a
257 buffer.
258 @end itemize
259
260 @contents
261 @bye