+++ /dev/null
-/* -*- coding: utf-8; -*- */
-/*** @page m17nDBTutorial Tutorial for writing the m17n database
-
-This section contains tutorials for writing various database files of
-the m17n database.
-
-<ul>
-<li> @ref mdbTutorialIM "TutorialIM" -- Tutorial of input method
-</ul>
-*/
-/***
-
-@section mdbTutorialIM Tutorial of input method
-
-@subsection im-struct Structure of an input method file
-
-An input method is defined in a *.mim file with this format.
-
-@verbatim
-(input-method LANG NAME)
-
-(description (_ "DESCRIPTION"))
-
-(title "TITLE-STRING")
-
-(map
- (MAP-NAME
- (KEYSEQ MAP-ACTION MAP-ACTION ...) <- rule
- (KEYSEQ MAP-ACTION MAP-ACTION ...) <- rule
- ...)
- (MAP-NAME
- (KEYSEQ MAP-ACTION MAP-ACTION ...) <- rule
- (KEYSEQ MAP-ACTION MAP-ACTION ...) <- rule
- ...)
- ...)
-
-(state
- (STATE-NAME
- (MAP-NAME BRANCH-ACTION BRANCH-ACTION ...) <- branch
- ...)
- (STATE-NAME
- (MAP-NAME BRANCH-ACTION BRANCH-ACTION ...) <- branch
- ...)
- ...)
-@endverbatim
-Lowercase letters and parentheses are literals, so they must be
-written as they are. Uppercase letters represent arbitrary strings.
-
-KEYSEQ specifies a sequence of keys in this format:
-@verbatim
- (SYMBOLIC-KEY SYMBOLIC-KEY ...)
-@endverbatim
-where SYMBOLIC-KEY is the keysym value returned by the xev command.
-For instance
-@verbatim
- (n i)
-@endverbatim
-represents a key sequence of \<n\> and \<i\>.
-If all SYMBOLIC-KEYs are ASCII characters, you can use the short form
-@verbatim
- "ni"
-@endverbatim
-instead. Consult #mdbIM for Non-ASCII characters.
-
-Both MAP-ACTION and BRANCH-ACTION are a sequence of actions of this format:
-@verbatim
- (ACTION ARG ARG ...)
-@endverbatim
-The most common action is <span class="fragment">insert</span>, which is written as this:
-@verbatim
- (insert "TEXT")
-@endverbatim
-But as it is very frequently used, you can use the short form
-@verbatim
- "TEXT"
-@endverbatim
-If <span class="fragment">"TEXT"</span> contains only one character "C", you can write it as
-@verbatim
- (insert ?C)
-@endverbatim
-or even shorter as
-@verbatim
- ?C
-@endverbatim
-So the shortest notation for an action of inserting "a" is
-@verbatim
- ?a
-@endverbatim
-
-@subsection im-upcase Simple example of capslock
-
-Here is a simple example of an input method that works as CapsLock.
-
-@verbatim
-(input-method en capslock)
-(description (_ "Upcase all lowercase letters"))
-(title "a->A")
-(map
- (toupper ("a" "A") ("b" "B") ("c" "C") ("d" "D") ("e" "E")
- ("f" "F") ("g" "G") ("h" "H") ("i" "I") ("j" "J")
- ("k" "K") ("l" "L") ("m" "M") ("n" "N") ("o" "O")
- ("p" "P") ("q" "Q") ("r" "R") ("s" "S") ("t" "T")
- ("u" "U") ("v" "V") ("w" "W") ("x" "X") ("y" "Y")
- ("z" "Z")))
-(state
- (init (toupper)))
-@endverbatim
-
-When this input method is activated, it is in the initial condition of
-the first state (in this case, the only state <span class="fragment">init</span>). In the
-initial condition, no key is being processed and no action is
-suspended. When the input method receives a key event \<a\>, it
-searches branches in the current state for a rule that matches \<a\>
-and finds one in the map <span class="fragment">toupper</span>. Then it executes MAP-ACTIONs
-(in this case, just inserting "A" in the preedit buffer). After all
-MAP-ACTIONs have been executed, the input method shifts to the initial
-condition of the current state.
-
-The shift to <em>the initial condition of the first state</em> has a special
-meaning; it commits all characters in the preedit buffer then clears
-the preedit buffer.
-
-As a result, "A" is given to the application program.
-
-When a key event does not match with any rule in the current state,
-that event is unhandled and given back to the application program.
-
-Turkish users may want to extend the above example for "İ" (U+0130:
-LATIN CAPITAL LETTER I WITH DOT ABOVE). It seems that assigning the
-key sequence \<i\> \<i\> for that character is convenient. So, he
-will add this rule in <span class="fragment">toupper</span>.
-
-@verbatim
- ("ii" "İ")
-@endverbatim
-
-However, we already have the following rule:
-
-@verbatim
- ("i" "I")
-@endverbatim
-
-What will happen when a key event \<i\> is sent to the input method?
-
-No problem. When the input method receives \<i\>, it inserts "I" in the
-preedit buffer. It knows that there is another rule that may
-match the additional key event \<i\>. So, after inserting "I", it
-suspends the normal behavior of shifting to the initial condition, and
-waits for another key. Thus, the user sees "I" with underline, which
-indicates it is not yet committed.
-
-When the input method receives the next \<i\>, it cancels the effects
-done by the rule for the previous "i" (in this case, the preedit buffer is
-cleared), and executes MAP-ACTIONs of the rule for "ii". So, "İ" is
-inserted in the preedit buffer. This time, as there are no other rules
-that match with an additional key, it shifts to the initial condition
-of the current state, which leads to commit "İ".
-
-Then, what will happen when the next key event is \<a\> instead of \<i\>?
-
-No problem, either.
-
-The input method knows that there are no rules that match the \<i\> \<a\> key
-sequence. So, when it receives the next \<a\>, it executes the
-suspended behavior (i.e. shifting to the initial condition), which
-leads to commit "I". Then the input method tries to handle \<a\> in
-the current state, which leads to commit "A".
-
-So far, we have explained MAP-ACTION, but not
-BRANCH-ACTION. The format of BRANCH-ACTION is the same as that of MAP-ACTION.
-It is executed only after a matching rule has been determined and the
-corresponding MAP-ACTIONs have been executed. A typical use of
-BRANCH-ACTION is to shift to a different state.
-
-To see this effect, let us modify the current input method to upcase only
-word-initial letters (i.e. to capitalize). For that purpose,
-we modify the "init" state as this:
-
-@verbatim
- (init
- (toupper (shift non-upcase)))
-@endverbatim
-
-Here <span class="fragment">(shift non-upcase)</span> is an action to shift to the new state
-<span class="fragment">non-upcase</span>, which has two branches as below:
-
-@verbatim
- (non-upcase
- (lower)
- (nil (shift init)))
-@endverbatim
-
-The first branch is simple. We can define the new map <span class="fragment">lower</span> as the
-following to insert lowercase letters as they are.
-
-@verbatim
-(map
- ...
- (lower ("a" "a") ("b" "b") ("c" "c") ("d" "d") ("e" "e")
- ("f" "f") ("g" "g") ("h" "h") ("i" "i") ("j" "j")
- ("k" "k") ("l" "l") ("m" "m") ("n" "n") ("o" "o")
- ("p" "p") ("q" "q") ("r" "r") ("s" "s") ("t" "t")
- ("u" "u") ("v" "v") ("w" "w") ("x" "x") ("y" "y")
- ("z" "z")))
-@endverbatim
-
-The second branch has a special meaning. The map name <span class="fragment">nil</span> means
-that it matches with any key event that does not match any rules in the
-other maps in the current state. In addition, it does not
-consume any key event. We will show the full code of the new input
-method before explaining how it works.
-
-@verbatim
-(input-method en titlecase)
-(description (_ "Titlecase letters"))
-(title "abc->Abc")
-(map
- (toupper ("a" "A") ("b" "B") ("c" "C") ("d" "D") ("e" "E")
- ("f" "F") ("g" "G") ("h" "H") ("i" "I") ("j" "J")
- ("k" "K") ("l" "L") ("m" "M") ("n" "N") ("o" "O")
- ("p" "P") ("q" "Q") ("r" "R") ("s" "S") ("t" "T")
- ("u" "U") ("v" "V") ("w" "W") ("x" "X") ("y" "Y")
- ("z" "Z") ("ii" "İ"))
- (lower ("a" "a") ("b" "b") ("c" "c") ("d" "d") ("e" "e")
- ("f" "f") ("g" "g") ("h" "h") ("i" "i") ("j" "j")
- ("k" "k") ("l" "l") ("m" "m") ("n" "n") ("o" "o")
- ("p" "p") ("q" "q") ("r" "r") ("s" "s") ("t" "t")
- ("u" "u") ("v" "v") ("w" "w") ("x" "x") ("y" "y")
- ("z" "z")))
-(state
- (init
- (toupper (shift non-upcase)))
- (non-upcase
- (lower (commit))
- (nil (shift init))))
-@endverbatim
-
-Let's see what happens when the user types the key sequence \<a\> \<b\> \< \>.
-Upon \<a\>, "A" is committed and the state shifts to <span class="fragment">non-upcase</span>.
-So, the next \<b\> is handled in the <span class="fragment">non-upcase</span> state.
-As it matches a
-rule in the map <span class="fragment">lower</span>, "b" is inserted in the preedit buffer and it
-is committed explicitly by the "commit" command in BRANCH-ACTION. After
-that, the input method is still in the <span class="fragment">non-upcase</span> state. So the next \< \>
-is also handled in <span class="fragment">non-upcase</span>. For this time, no rule in this state
-matches it. Thus the branch <span class="fragment">(nil (shift init))</span> is selected and the
-state is shifted to <span class="fragment">init</span>. Please note that \< \> is not yet
-handled because the map <span class="fragment">nil</span> does not consume any key event.
-So, the input method tries to handle it in the <span class="fragment">init</span> state. Again no
-rule matches it. Therefore, that event is given back to the application
-program, which usually inserts a space for that.
-
-When you type "a quick blown fox" with this input method, you get "A
-Quick Blown Fox". OK, you find a typo in "blown", which should be
-"brown". To correct it, you probably move the cursor after "l" and type
-\<Backspace\> and \<r\>. However, if the current input method is still
-active, a capital "R" is inserted. It is not a sophisticated
-behavior.
-
-@subsection im-surrounding-text Example of utilizing surrounding text support
-
-To make the input method work well also in such a case, we must use
-"surrounding text support". It is a way to check characters around
-the inputting spot and delete them if necessary. Note that
-this facility is available only with Gtk+ applications and Qt
-applications. You cannot use it with applications that use XIM
-to communicate with an input method.
-
-Before explaining how to utilize "surrounding text support", you must
-understand how to use variables, arithmetic comparisons, and
-conditional actions.
-
-At first, any symbol (except for several preserved ones) used as ARG
-of an action is treated as a variable. For instance, the commands
-
-@verbatim
- (set X 32) (insert X)
-@endverbatim
-
-set the variable <span class="fragment">X</span> to integer value 32, then insert a character
-whose Unicode character code is 32 (i.e. SPACE).
-
-The second argument of the <span class="fragment">set</span> action can be an expression of this form:
-
-@verbatim
- (OPERAND ARG1 [ARG2])
-@endverbatim
-
-Both ARG1 and ARG2 can be an expression. So,
-
-@verbatim
- (set X (+ (* Y 32) Z))
-@endverbatim
-
-sets <span class="fragment">X</span> to the value of <span class="fragment">Y * 32 + Z</span>.
-
-We have the following arithmetic/bitwise OPERANDs (require two arguments):
-
-@verbatim
- + - * / & |
-@endverbatim
-
-these relational OPERANDs (require two arguments):
-
-@verbatim
- == <= >= < >
-@endverbatim
-
-and this logical OPERAND (requires one argument):
-
-@verbatim
- !
-@endverbatim
-
-For surrounding text support, we have these preserved variables:
-
-@verbatim
- @-0, @-N, @+N (N is a positive integer)
-@endverbatim
-
-The values of them are predefined as below and can not be altered.
-
-<ul>
-<li> <span class="fragment">@-0</span>
-
--1 if surrounding text is supported, -2 if not.
-
-<li> <span class="fragment">@-N</span>
-
-The Nth previous character in the preedit buffer. If there are only M
-(M<N) previous characters in it, the value is the (N-M)th previous
-character from the inputting spot.
-
-<li> <span class="fragment">@+N</span>
-
-The Nth following character in the preedit buffer. If there are only M
-(M<N) following characters in it, the value is the (N-M)th following
-character from the inputting spot.
-
-</ul>
-
-So, provided that you have this context:
-
-@verbatim
- ABC|def|GHI
-@endverbatim
-
-("def" is in the preedit buffer, two "|"s indicate borders between the
-preedit buffer and the surrounding text) and your current position in
-the preedit buffer is between "d" and "e", you get these values:
-
-@verbatim
- @-3 -- ?B
- @-2 -- ?C
- @-1 -- ?d
- @+1 -- ?e
- @+2 -- ?f
- @+3 -- ?G
-@endverbatim
-
-Next, you have to understand the conditional action of this form:
-
-@verbatim
- (cond
- (EXPR1 ACTION ACTION ...)
- (EXPR2 ACTION ACTION ...)
- ...)
-@endverbatim
-
-where EXPRn are expressions. When an input method executes this
-action, it resolves the values of EXPRn one by one from the first branch.
-If the value of EXPRn is resolved into nonzero, the corresponding
-actions are executed.
-
-Now you are ready to write a new version of the input method "Titlecase".
-
-@verbatim
-(input-method en titlecase2)
-(description (_ "Titlecase letters"))
-(title "abc->Abc")
-(map
- (toupper ("a" "A") ("b" "B") ("c" "C") ("d" "D") ("e" "E")
- ("f" "F") ("g" "G") ("h" "H") ("i" "I") ("j" "J")
- ("k" "K") ("l" "L") ("m" "M") ("n" "N") ("o" "O")
- ("p" "P") ("q" "Q") ("r" "R") ("s" "S") ("t" "T")
- ("u" "U") ("v" "V") ("w" "W") ("x" "X") ("y" "Y")
- ("z" "Z") ("ii" "İ")))
-(state
- (init
- (toupper
-
- ;; Now we have exactly one uppercase character in the preedit
- ;; buffer. So, "@-2" is the character just before the inputting
- ;; spot.
-
- (cond ((| (& (>= @-2 ?A) (<= @-2 ?Z))
- (& (>= @-2 ?a) (<= @-2 ?z))
- (= @-2 ?İ))
-
- ;; If the character before the inputting spot is A..Z,
- ;; a..z, or İ, remember the only character in the preedit
- ;; buffer in the variable X and delete it.
-
- (set X @-1) (delete @-)
-
- ;; Then insert the lowercase version of X.
-
- (cond ((= X ?İ) "i")
- (1 (set X (+ X 32)) (insert X))))))))
-@endverbatim
-
-The above example contains the new action <span class="fragment">delete</span>. So, it is time
-to explain more about the preedit buffer. The preedit buffer is a
-temporary place to store a sequence of characters. In this buffer,
-the input method keeps a position called the "current position". The
-current position exists between two characters, at the beginning of
-the buffer, or at the end of the buffer. The <span class="fragment">insert</span> action inserts
-characters before the current position. For instance, when your
-preedit buffer contains "ab.c" ("." indicates the current position),
-
-@verbatim
- (insert "xyz")
-@endverbatim
-
-changes the buffer to "abxyz.c".
-
-There are several predefined variables that represent a specific position in the
-preedit buffer. They are:
-
-<ul>
-<li> <span class="fragment">@@<, @=, @@></span>
-
-The first, current, and last positions.
-
-<li> <span class="fragment">@-, @+</span>
-
-The previous and the next positions.
-</ul>
-
-The format of the <span class="fragment">delete</span> action is this:
-
-@verbatim
- (delete POS)
-@endverbatim
-
-where POS is a predefined positional variable.
-The above action deletes the characters between POS and
-the current position. So, <span class="fragment">(delete @-)</span> deletes one character before
-the current position. The other examples of <span class="fragment">delete</span> include the followings:
-
-@verbatim
- (delete @+) ; delete the next character
- (delete @<) ; delete all the preceding characters in the buffer
- (delete @>) ; delete all the following characters in the buffer
-@endverbatim
-
-You can change the current position using the <span class="fragment">move</span> action as below:
-
-@verbatim
- (move @-) ; move the current position to the position before the
- previous character
- (move @<) ; move to the first position
-@endverbatim
-
-Other positional variables work similarly.
-
-Let's see how our new example works. Whatever a key event is, the
-input method is in its only state, <span class="fragment">init</span>. Since an event of a lower letter
-key is firstly handled by MAP-ACTIONs, every key is changed into the
-corresponding uppercase and put into the preedit buffer. Now this character
-can be accessed with <span class="fragment">@-1</span>.
-
-How can we tell whether the new character should be a lowercase or an
-uppercase? We can do so by checking the character before it, i.e.
-<span class="fragment">@-2</span>. BRANCH-ACTIONs in the <span class="fragment">init</span> state do the job.
-
-It first checks if the character <span class="fragment">@-2</span> is between A to Z, between
-a to z, or İ by the conditional below.
-
-@verbatim
- (cond ((| (& (>= @-2 ?A) (<= @-2 ?Z))
- (& (>= @-2 ?a) (<= @-2 ?z))
- (= @-2 ?İ))
-@endverbatim
-
-If not, there is nothing to do specially. If so, our new key should
-be changed back into lowercase. Since the uppercase character is
-already in the preedit buffer, we retrieve and remember it in the
-variable <span class="fragment">X</span> by
-
-@verbatim
- (set X @-1)
-@endverbatim
-
-and then delete that character by
-
-@verbatim
- (delete @-)
-@endverbatim
-
-Lastly we re-insert the character in its lowercase form. The
-problem here is that "İ" must be changed into "i", so we need another
-conditional. The first branch
-
-@verbatim
- ((= X ?İ) "i")
-@endverbatim
-
-means that "if the character remembered in X is 'İ', 'i' is inserted".
-
-The second branch
-
-@verbatim
- (1 (set X (+ X 32)) (insert X))
-@endverbatim
-
-starts with "1", which is always resolved into nonzero, so this branch
-is a catchall. Actions in this branch increase <span class="fragment">X</span> by 32, then
-insert <span class="fragment">X</span>. In other words, they change A...Z into a...z
-respectively and insert the resulting lowercase character into the
-preedit buffer. As the input method reaches the end of the
-BRANCH-ACTIONs, the character is commited.
-
-This new input method always checks the character before the current
-position, so "A Quick Blown Fox" will be successfully fixed to "A
-Quick Brown Fox" by the key sequence \<BackSpace\> \<r\>.
-
-
-*/
projects / m17n / m17n-docs.git / blobdiff