FORMATS/IM.txt

   1 /* Copyright (C) 2003, 2004
   2      National Institute of Advanced Industrial Science and Technology (AIST)
   3      Registration Number H15PRO112
   4    See the end for copying conditions.  */
   5
   6 /***en
   7
   8 @page mdbIM Input Method
   9
  10 @section im-description DESCRIPTION
  11
  12 The m17n library provides a driver for input methods that are
  13 dynamically loadable from the m17n database (see @ref m17nInputMethod
  14 @latexonly (P.\pageref{group__m17nInputMethod}) @endlatexonly).
  15
  16 This section describes the data format that defines those input
  17 methods.
  18
  19 @section im-format SYNTAX and SEMANTICS
  20
  21 The following data format defines an input method.  The driver loads
  22 a definition from a file, a stream, etc.  A definitions is converted
  23 into the form of plist in the driver.
  24
  25 @verbatim
  26 INPUT-METHOD ::= TITLE MAP-LIST MACRO-LIST ? MODULE-LIST ? STATE-LIST
  27
  28 TITLE ::= '(' 'title' MTEXT ')'
  29 @endverbatim
  30
  31 @c MTEXT is a text displayed on the screen when this input method is
  32 active.
  33
  34 @verbatim
  35 MAP-LIST ::= '(' 'map' MAP * ')'
  36
  37 MAP ::= '(' MAP-NAME RULE * ')'
  38
  39 MAP-NAME ::= SYMBOL
  40
  41 RULE ::= '(' KEYSEQ MAP-ACTION * ')'
  42
  43 KEYSEQ ::= MTEXT | '(' [ SYMBOL | INTEGER ] * ')'
  44 @endverbatim
  45
  46 @c SYMBOL in the definitions of @c MAP-NAME must not be @c t nor @c
  47 nil.
  48
  49 @c MTEXT in the definition of @c KEYSEQ consists of characters that
  50 can be generated by a keyboard.  Therefore @c MTEXT usually contains
  51 only ASCII characters.  However, if the input method is intended to be
  52 used, for instance, with a West European keyboard, @c MTEXT may
  53 contain Latin-1 characters.
  54
  55 @c SYMBOL in the definition of @c KEYSEQ must be the return value of
  56 the minput_event_to_key () function.
  57
  58 @c INTEGER in the definition of @c KEYSEQ must be a valid character
  59 code.
  60
  61 @verbatim
  62 MAP-ACTION ::= ACTION
  63
  64 ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK |
  65            | SHOW | HIDE | PUSHBACK | UNDO | SHIFT | CALL
  66            | SET | IF | '(' MACRO-NAME ')'
  67
  68 PREDEFINED-SYMBOL ::=
  69     '@<' | '@=' | '@>' | '@-' | '@+' | '@[' | '@]'
  70 @endverbatim
  71 @verbatim
  72 MACRO-LIST ::= '(' 'macro' MACRO * ')'
  73
  74 MACRO ::= '(' MACRO-NAME MACRO-ACTION * ')'
  75
  76 MACRO-NAME ::= SYMBOL
  77
  78 MACRO-ACTION ::= ACTION
  79 @endverbatim
  80 @verbatim
  81 MODULE-LIST ::= '(' 'module' MODULE * ')'
  82
  83 MODULE ::= '(' MODULE-NAME FUNCTION * ')'
  84
  85 MODULE-NAME ::= SYMBOL
  86
  87 FUNCTION ::= SYMBOL
  88 @endverbatim
  89
  90 Each @c MODULE declares the name of external module (i.e. dynamic
  91 library) and function names exported by the module.  If a @c FUNCTION has
  92 name "init", it is called with only the default arguments (see the
  93 section about @c CALL) when an input context is created for the input
  94 method.  If a @c FUNCTION has name "fini", it is called with only the
  95 default arguments when an input context is destroyed.
  96
  97 @verbatim
  98 STATE-LIST ::= '(' 'state' STATE * ')'
  99
 100 STATE ::= '(' STATE-NAME BRANCH * ')'
 101
 102 STATE-NAME ::= SYMBOL
 103
 104 BRANCH ::= '(' MAP-NAME BRANCH-ACTION * ')'
 105            | '(' nil BRANCH-ACTION * ')'
 106            | '(' t BRANCH-ACTION * ')'
 107 @endverbatim
 108
 109 In the first form of @c BRANCH, @c MAP-NAME must be an item that appears
 110 in @c MAP.  In this case, if a key sequence matching one of @c
 111 KEYSEQs of @c MAP-NAME is typed, @c BRANCH-ACTIONs are executed.
 112
 113 In the second form of @c BRANCH, @c BRANCH-ACTIONs are executed if a
 114 key sequence that doesn't match any of @c Branch's of the current
 115 state is typed.
 116
 117 In the third form of @c BRANCH, @c BRANCH-ACTIONs are executed if we
 118 shift to the current state after handling all typed keys.  If the
 119 current state is the initial state, @c BRANCH-ACTIONs are executed
 120 just after an input context of the input method is created.
 121
 122 @verbatim
 123 BRANCH-ACTION ::= ACTION
 124 @endverbatim
 125
 126 An input method has the following two lists of symbols.
 127
 128 <ul>
 129 <li> marker list
 130
 131 A marker is a symbol indicating a character position in the preediting
 132 text.  The @c MARK action assigns a position to a marker.  The
 133 position of a marker is referred by the @c MOVE and the @c DELETE actions.
 134
 135 <li> variable list
 136
 137 A variable is a symbol associated with an integer value.  The value of
 138 a variable is set by the @c SET action, and is referred by the @c SET,
 139 the @c INSERT, and the @c IF actions.  All variables are implicitly
 140 initialized to zero.
 141
 142 </ul>
 143
 144 Each @c PREDEFINED-SYMBOL has a special meaning when used as a marker.
 145
 146 <ul>
 147 <li> @c @@<, @c @@=, @c @@>
 148
 149 The first, the current, and the last position.
 150
 151 <li> @c @@-, @c @@+
 152
 153 The previous and the next position.
 154
 155 <li> @c @@[, @c @@]
 156
 157 The previous and the next position where a candidate list changes.
 158 </ul>
 159
 160 Each @c PREDEFINED-SYMBOL has a special meaning when used as a candidate
 161 index in the @c SELECT action.
 162
 163 <ul>
 164 <li> @c @@<, @c @@=, @c @@>
 165
 166 The first, the current, and the last candidate of the current candidate group.
 167
 168 <li> @c @@-
 169
 170 The previous candidate.  If the current candidate is the first one in
 171 the current candidate group, then it means the last candidate in the
 172 previous candidate group.
 173
 174 <li> @c @@+
 175
 176 The next candidate.  If the current candidate is the last one in the
 177 current candidate group, then it means the first candidate in the next
 178 candidate group.
 179
 180 <li> @c @@[, @c @@]
 181
 182 The candidate in the previous and the next candidate group having the same
 183 candidate index as the current one.
 184 </ul>
 185
 186 The arguments and the behavior of each action are listed below.
 187
 188 @verbatim
 189 INSERT ::= '(' 'insert' MTEXT ')'
 190            | MTEXT
 191            | INTEGER
 192            | '(' 'insert' SYMBOL ')'
 193            | '(' 'insert' '(' CANDIDATES * ')' ')'
 194            | '(' CANDIDATES * ')'
 195
 196 CANDIDATES ::= MTEXT | '(' MTEXT * ')'
 197 @endverbatim
 198
 199 The first and second forms insert @c MTEXT before the current position.
 200
 201 The third form inserts the character @c INTEGER before the current
 202 position.
 203
 204 The fourth form treats @c SYMBOL as a variable, and inserts its value
 205 (if it is a valid character code) before the current position.
 206
 207 In the fifth and sixth forms, each @c CANDIDATES represents a
 208 candidate group, and each element of @c CANDIDATES represents a
 209 candidate, i.e. if @c CANDIDATES is an M-text, the candidates are the
 210 characters in the M-text; if @c CANDIDATES is a list of M-texts, the
 211 candidates are the M-texts in the list.
 212
 213 These forms insert the first candidate before the current position.
 214 The inserted string is associated with the list of candidates and
 215 the information indicating the currently selected candidate.
 216
 217 The marker positions affected by the insertion are automatically relocated.
 218
 219 @verbatim
 220 DELETE ::= '(' 'delete' SYMBOL ')'
 221            | '(' 'delete' INTEGER ')'
 222 @endverbatim
 223
 224 The first form treats @c SYMBOL as a marker, and deletes characters
 225 between the current position and the marker position.
 226
 227 The second form treats @c INTEGER as a character position, and deletes
 228 characters between the current position and the character position.
 229
 230 The marker positions affected by the deletion are automatically relocated.
 231
 232 @verbatim
 233 SELECT ::= '(' 'select' PREDEFINED-SYMBOL ')'
 234            | '(' 'select' INTEGER ')'
 235 @endverbatim
 236
 237 This action first checks if the character just before the current position
 238 belongs to a string that is associated with a candidate list.  If it is,
 239 the action replaces that string with a candidate specified by the
 240 argument.
 241
 242 The first form treats @c PREDEFINED-SYMBOL as a candidate index (as
 243 described above) that specifies a new candidate in the candidate list.
 244
 245 The second form treats @c INTEGER as a candidate index that specifies a
 246 new candidate in the candidate list.
 247
 248 @verbatim
 249 SHOW ::= '(show)'
 250 @endverbatim
 251
 252 This actions instructs the input method driver to display a candidate
 253 list associated with the string before the current position.
 254
 255 @verbatim
 256 HIDE ::= '(hide)'
 257 @endverbatim
 258
 259 This action instructs the input method driver to hide the currently
 260 displayed candidate list.
 261
 262 @verbatim
 263 MOVE ::= '(' 'move' SYMBOL ')'
 264          | '(' 'move' INTEGER ')'
 265 @endverbatim
 266
 267 The first form treats @c SYMBOL as a marker, and makes the marker
 268 position be the new current position.
 269
 270 The second form treats @c INTEGER as a character position, and makes
 271 that position be the new current position.
 272
 273 @verbatim
 274 MARK ::= '(' 'mark' SYMBOL ')'
 275 @endverbatim
 276
 277 This action treats @c SYMBOL as a marker, and sets its position to the
 278 current position.  @c SYMBOL must not be a @c PREDEFINED-SYMBOL.
 279
 280
 281 @verbatim
 282 PUSHBACK :: = '(pushback INTEGER)'
 283 @endverbatim
 284
 285 This action pushes back the latest key events to the event queue.
 286
 287 @verbatim
 288 UNDO :: = '(undo)'
 289 @endverbatim
 290
 291 This action cancels the last key event.
 292
 293 @verbatim
 294 SHIFT :: = '(' 'shift' STATE-NAME ')'
 295 @endverbatim
 296
 297 This action shifts the current state to @c STATE-NAME.  @c
 298 STATE-NAME must appear in @c STATE-LIST.
 299
 300 @verbatim
 301 CALL ::= '(' 'call' MODULE-NAME FUNCTION ARG * ')'
 302
 303 ARG ::= INTEGER | SYMBOL | MTEXT | PLIST
 304 @endverbatim
 305
 306 This action calls the function @c FUNCTION of external module @c
 307 MODULE-NAME.  @c MODULE-NAME and @c FUNCTION must appear in @c
 308 MODULE-LIST.
 309
 310 The function is called with an argument of the type (#MPlist *).  The
 311 key of the first element is #Mt and its value is a pointer to an
 312 object of the type #MInputContext.  The key of the second element is
 313 #Msymbol and its value is the current state name.  @c ARGs are used as
 314 the value of the third and later elements.  Their keys are determined
 315 automatically; if an @c ARG is an integer, the corresponding key is
 316 #Minteger; if an @c ARG is a symbol, the corresponding key is
 317 #Msymbol, etc.
 318
 319 The function must return NULL or a value of the type (#MPlist *) that
 320 represents a list of actions to take.
 321
 322 @verbatim
 323 SET ::= '(' OPERAND SYMBOL1 [ INTEGER | SYMBOL2 ] ')'
 324
 325 OPERAND ::= 'set' | 'add' | 'sub' | 'mul' | 'div'
 326 @endverbatim
 327
 328 This action treats @c SYMBOL1 and @c SYMBOL2 as variables and sets the
 329 value of @c SYMBOL1 as below.
 330
 331 If @c OPERAND is 'set', it sets the value of @c SYMBOL1 to @c INTEGER or the
 332 value of @c SYMBOL2.
 333
 334 If @c OPERAND is 'add', it increments the value of @c SYMBOL1 by @c INTEGER
 335 or the value of @c SYMBOL2.
 336
 337 If @c OPERAND is 'sub', it decrements the value of @c SYMBOL1 by @c INTEGER
 338 or the value of @c SYMBOL2.
 339
 340 If @c OPERAND is 'mul', it multiplies the value of @c SYMBOL1 by @c INTEGER
 341 or the value of @c SYMBOL2.
 342
 343 If @c OPERAND is 'div', it divides the value of @c SYMBOL1 by @c INTEGER or
 344 the value of @c SYMBOL2.
 345
 346 @verbatim
 347 IF ::= '(' 'if' CONDITION ACTION-LIST1 ACTION-LIST2 * ')'
 348
 349 CONDITION ::= '(' OPERAND VAL1 VAL2 ')'
 350
 351 ACTION-LIST1 ::= '(' ACTION * ')'
 352
 353 ACTION-LIST2 ::= '(' ACTION * ')'
 354
 355 OPERAND ::= '=' '<' '>'
 356
 357 VAL1 ::= [ INTEGER1 | SYMBOL1 ]
 358
 359 VAL2 ::= [ INTEGER2 | SYMBOL2 ]
 360 @endverbatim
 361
 362 This action performs actions in @c ACTION-LIST1 if @c CONDITION is
 363 true, and performs @c ACTION-LIST2 (if any) otherwise.
 364
 365 @c SYMBOL1 and @c SYMBOL2 are treated as variables.
 366
 367 @ifnot FOR-MAN
 368
 369 @section im-example1 EXAMPLE 1
 370
 371 This is a very simple example for inputting Latin characters with
 372 diacritical marks (acute and cedilla).  For instance, when you type:
 373 @verbatim
 374     Comme'die-Franc,ais, chic,,
 375 @endverbatim
 376 you will get this:
 377 @if FOR-HTML
 378 @verbatim
 379     Commédie-Français, chic,
 380 @endverbatim
 381 @endif
 382 @if FOR-LATEX
 383 @latexonly
 384 \hskip5mm\texttt{\footnotesize Comm\'{e}die-Fran\c{c}ais, chic,}
 385 @endlatexonly
 386 @endif
 387
 388 The definition of the input method is very simple as below, and it is
 389 quite straight forward to extend it to cover all Latin characters.
 390
 391 @if FOR-HTML
 392 @verbatim
 393 (title "latin-postfix")
 394 (map
 395  (trans
 396   ("a'" ?á) ("e'" ?é) ("i'" ?í) ("o'" ?ó) ("u'" ?ú) ("c," ?ç)
 397   ("A'" ?Á) ("E'" ?É) ("I'" ?Í) ("O'" ?Ó) ("U'" ?Ú) ("C," ?Ç)
 398   ("a''" "a'") ("e''" "e'") ("i''" "i'") ("o''" "o'") ("u''" "u'")
 399   ("c,," "c,")
 400   ("A''" "A'") ("E''" "E'") ("I''" "I'") ("O''" "O'") ("U''" "U'")
 401   ("C,," "C,")))
 402 (state
 403  (init
 404   (trans)))
 405 @endverbatim
 406 @endif
 407 @if FOR-LATEX
 408 @latexonly
 409 \texttt{\footnotesize
 410 \hskip2mm(title "latin-postfix")\\
 411 \hskip2mm(map\\
 412 \hskip4mm (trans\\
 413 \hskip6mm  ("a'" ?\'{a}) ("e'" ?\'{e}) ("i'" ?\'{i}) ("o'" ?\'{o})
 414 ("u'" ?\'{u}) ("c," ?\c{c})\\
 415 \hskip6mm  ("A'" ?\'{A}) ("E'" ?\'{E}) ("I'" ?\'{I}) ("O'" ?\'{O})
 416 ("U'" ?\'{U}) ("C," ?\c{C})\\
 417 \hskip6mm  ("a''" "a'") ("e''" "e'") ("i''" "i'") ("o''" "o'") ("u''" "u'")\\
 418 \hskip6mm  ("c,," "c,")\\
 419 \hskip6mm  ("A''" "A'") ("E''" "E'") ("I''" "I'") ("O''" "O'") ("U''" "U'")\\
 420 \hskip6mm  ("C,," "C,")))\\
 421 \hskip2mm(state\\
 422 \hskip4mm (init\\
 423 \hskip6mm  (trans)))}
 424 @endlatexonly
 425 @endif
 426
 427 @section im-example2 EXAMPLE 2
 428
 429 This example is for inputting Unicode characters by typing C-u
 430 (Control-u) followed by four hexadecimal numbers.  For instance, when
 431 you type ("^u" means Control-u):
 432 @verbatim
 433     ^u2190^u2191^u2192^u2193
 434 @endverbatim
 435 you will get this (Unicode arrow symbols):
 436 @verbatim
 437     ←↑→↓
 438 @endverbatim
 439
 440 The definition utilizes @c SET and @c IF commands as below:
 441 @verbatim
 442 (title "UNICODE")
 443 (map
 444  (starter
 445   ((C-U) "U+"))
 446  (hex
 447   ("0" ?0) ("1" ?1) ... ("9" ?9) ("a" ?A) ("b" ?B) ... ("f" ?F)))
 448 (state
 449  (init
 450   (starter (set code 0) (set count 0) (shift unicode)))
 451  (unicode
 452   (hex (set this @-)
 453        (< this ?A
 454           ((sub this 48))
 455           ((sub this 55)))
 456        (mul code 16) (add code this)
 457        (add count 1)
 458        (= count 4
 459           ((delete @<) (insert code) (shift init))))))
 460 @endverbatim
 461
 462 @section im-example3 EXAMPLE 3
 463
 464 This example is for inputting Chinese characters by typing PinYin key
 465 sequence.
 466 @if FOR-HTML
 467 For instance, when you type:
 468 @verbatim
 469     nihaobei2jing2
 470 @endverbatim
 471 you will get:
 472 @verbatim
 473     你好北京
 474 @endverbatim
 475
 476 The definition utilizes @c CANDIDATE and @c SELECT commands as below.
 477 Note that this is just an example, and it ignores such important key
 478 as Backspace.
 479
 480 @verbatim
 481 (title "拼")
 482
 483 (map
 484  ;; The initial character of Pinyin.
 485  (starter
 486   ("a") ("b") ... ("h") ("j") ... ("t") ("w") ("x") ("y") ("z"))
 487
 488  ;; Big table of Pinyin vs the corresponding Chinese characters.
 489  (pinyin
 490   ...
 491   ("bei" ("被北备背悲辈杯倍贝碑" ...))
 492   ("hao" ("好号毫豪浩耗皓嚎昊郝" ...))
 493   ("jing" ("经京精境警竟静惊景敬" ...))
 494   ("ni" ("你呢尼泥逆倪匿拟腻妮" ...))
 495   ...)
 496  ;; Typing 1, 2, ..., 0 selects the 0th, 1st, ..., 9th candidate.
 497  (choose
 498   ("1" (select 0)) ("2" (select 1)) ... ("9" (select 8)) ("0" (select 9))))
 499
 500 (state
 501  (init
 502   ;; When an initial character of Pinyin is typed, re-handle it in
 503   ;; "main" state.  Anything else is just produced as is.
 504   (starter (show) (pushback 1) (shift main)))
 505
 506  (main
 507   ;; When a complete Pinyin sequence is typed, shift to "select" state
 508   ;; to allow users to select one from the candidates.
 509   (pinyin (shift select))
 510
 511   ;; When anything else is typed, produce the current candidate (if
 512   ;; any), and re-handle the last input in "init" state.
 513   (nil (hide) (shift init)))
 514
 515  (select
 516   ;; When a number is typed, select the corresponding canidate,
 517   ;; produce it, and shift to "init" state.
 518   (choose (hide) (shift init))
 519
 520   ;; When anything else is typed, produce the current candidate,
 521   ;; and re-handle the last input in "init" state.
 522   (nil (hide) (shift init))))
 523 @endverbatim
 524
 525 @elseif FOR-LATEX
 526 @latexonly
 527 \begin{center}
 528 \fbox{This example is readable only in the documentation of HTML version.}
 529 \end{center}
 530 @endlatexonly
 531 @endif
 532
 533 @endif
 534
 535 @section im-seealso SEE ALSO
 536
 537 @ref mim-list "Input Methods provided by the m17n database",
 538 @ref mdbGeneral "mdbGeneral(5)"
 539 */
 540
 541 /*
 542 Copyright (C) 2003, 2004
 543   National Institute of Advanced Industrial Science and Technology (AIST)
 544   Registration Number H15PRO112
 545
 546 This file is part of the m17n database; a sub-part of the m17n
 547 library.
 548
 549 The m17n library is free software; you can redistribute it and/or
 550 modify it under the terms of the GNU Lesser General Public License
 551 as published by the Free Software Foundation; either version 2.1 of
 552 the License, or (at your option) any later version.
 553
 554 The m17n library is distributed in the hope that it will be useful,
 555 but WITHOUT ANY WARRANTY; without even the implied warranty of
 556 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 557 Lesser General Public License for more details.
 558
 559 You should have received a copy of the GNU Lesser General Public
 560 License along with the m17n library; if not, write to the Free
 561 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 562 02111-1307, USA.
 563 */
 564
 565 /* Local Variables: */
 566 /* coding: utf-8 */
 567 /* End: */