-/* Copyright (C) 2003, 2004
+/* Copyright (C) 2003, 2004, 2005
National Institute of Advanced Industrial Science and Technology (AIST)
Registration Number H15PRO112
See the end for copying conditions. */
@section im-format SYNTAX and SEMANTICS
-The following data format defines an input method. The driver loads
-a definition from a file, a stream, etc. A definitions is converted
+The following data format defines an input method. The driver loads a
+definition from a file, a stream, etc. The definition is converted
into the form of plist in the driver.
@verbatim
-INPUT-METHOD ::= TITLE MAP-LIST MACRO-LIST ? MODULE-LIST ? STATE-LIST
-
-TITLE ::= '(' 'title' MTEXT ')'
+INPUT-METHOD ::=
+ IM-DECLARATION ? DESCRIPTION ? VARIABLE-LIST ? COMMAND-LIST ?
+ TITLE MAP-LIST MACRO-LIST ? MODULE-LIST ? STATE-LIST
+
+IM-DECLARATION ::= '(' 'input-method' LANGUAGE NAME [ VERSION ] ')'
+DESCRIPTION ::= '(' 'description' [ MTEXT-OR-GETTEXT | nil] ')'
+VARIABLE-LIST ::= '(' 'variable' VARIABLE-DECLARATION * ')'
+COMMAND-LIST ::= '(' 'command' COMMAND-DECLARATION * ')'
+TITLE ::= '(' 'title' TITLE-TEXT ')'
+
+VARIABLE-DECLARATION ::=
+ '(' VAR-NAME [ MTEXT-OR-GETTEXT | nil ] VALUE VALUE-CANDIDATE * ')'
+
+COMMAND-DECLARATION ::=
+ '(' CMD-NAME [ MTEXT-OR-GETTEXT | nil ] KEYSEQ * ')'
+
+MTEXT-OR-GETTEXT ::=
+ [ MTEXT | '(' '_' MTEXT ')']
+
+LANGUAGE ::= SYMBOL
+NAME ::= SYMBOL
+VERSION ::= MTEXT
+IM-DESCRIPTION ::= MTEXT
+VAR-NAME ::= SYMBOL
+VAR-DESCRIPTION ::= MTEXT
+VALUE ::= MTEXT | SYMBOL | INTEGER
+VALUE-CANDIDATE ::= VALUE | '(' RANGE-FROM RANGE-TO ')'
+RANGE-FROM ::= INTEGER
+RANGE-TO ::= INTEGER
+CMD-NAME ::= SYMBOL
+CMD-DESCRIPTION ::= MTEXT
+TITLE-TEXT ::= MTEXT
@endverbatim
-@c MTEXT is a text displayed on the screen when this input method is
-active.
+@c IM-DECLARATION specifies the language and name of this input
+method.
+
+@c VERSION specifies the required minimum version number of the m17n
+library. The format is is "XX.YY.ZZ" where XX is a major version
+number, YY is a minor version number, and ZZ is a patch level.
+
+@c DESCRIPTION specifies the description text of this input method by
+MTEXT-OR-GETTEXT. It it takes the second form, the text is translated
+according to the current locale by "gettext" (if the translation is
+provided).
+
+@c VARIABLE-DECLARATION declares a variable used in this input method.
+If a variable must be initialized to the default value, or is to be
+customized by a user, it must be declared here.
+
+@c COMMAND-DECLARATION declares a command used in this input method.
+If a command must be bound to the default key sequence, or is to be
+customized by a user, it must be declared here.
+
+@c TITLE-TEXT is a text displayed on the screen when this input method
+is active.
@verbatim
MAP-LIST ::= '(' 'map' MAP * ')'
contain Latin-1 characters.
@c SYMBOL in the definition of @c KEYSEQ must be the return value of
-the minput_event_to_key () function.
+the minput_event_to_key () function. Under the X window system, you
+can quickly check the value using the @c xev command. For example,
+the return key, the backspace key, and the 0 key on the keypad are
+represented as @c (Return) , @c (BackSpace) , and @c (KP_0)
+respectively. If the shift, control, meta, alt, super, and hyper
+modifiers are used, they are represented by the S- , C- , M- , A- , s-
+, and H- prefixes respectively in this oreder. Thus, "return with
+shift with meta with hyper" is @c (S-M-H-Return) . Note that "a with
+shift" .. "z with shift" are represented simply as A .. Z . Thus "a
+with shift with meta with hyper" is @c (M-H-A) .
@c INTEGER in the definition of @c KEYSEQ must be a valid character
code.
@verbatim
MAP-ACTION ::= ACTION
-ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK |
- | SHOW | HIDE | PUSHBACK | UNDO | SHIFT | CALL
- | SET | IF | '(' MACRO-NAME ')'
+ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK
+ | SHOW | HIDE | PUSHBACK | POP | UNDO | UNHANDLE | SHIFT | CALL
+ | SET | IF | COND | '(' MACRO-NAME ')'
PREDEFINED-SYMBOL ::=
- '@<' | '@=' | '@>' | '@-' | '@+' | '@[' | '@]'
+ '@0' | '@1' | '@2' | '@3' | '@4'
+ | '@5' | '@6' | '@7' | '@8' | '@9'
+ | '@<' | '@=' | '@>' | '@-' | '@+' | '@[' | '@]'
+ | '@@'
+ | '@-N' | '@+N'
@endverbatim
@verbatim
MACRO-LIST ::= '(' 'macro' MACRO * ')'
@verbatim
STATE-LIST ::= '(' 'state' STATE * ')'
-STATE ::= '(' STATE-NAME BRANCH * ')'
+STATE ::= '(' STATE-NAME [ STATE-TITLE-TEXT ] BRANCH * ')'
STATE-NAME ::= SYMBOL
+STATE-TITLE-TEXT ::= MTEXT
+
BRANCH ::= '(' MAP-NAME BRANCH-ACTION * ')'
| '(' nil BRANCH-ACTION * ')'
| '(' t BRANCH-ACTION * ')'
@endverbatim
-In the first form of @c BRANCH, @c MAP-NAME must be an item that appears
-in @c MAP. In this case, if a key sequence matching one of @c
+The optional @c STATE-TITLE-TEXT specifies a title text displayed on
+the screen when the input method is in this state. If @c
+STATE-TITLE-TEXT is omitted, @c TITLE-TEXT is used.
+
+In the first form of @c BRANCH, @c MAP-NAME must be an item that
+appears in @c MAP. In this case, if a key sequence matching one of @c
KEYSEQs of @c MAP-NAME is typed, @c BRANCH-ACTIONs are executed.
In the second form of @c BRANCH, @c BRANCH-ACTIONs are executed if a
key sequence that doesn't match any of @c Branch's of the current
state is typed.
-In the third form of @c BRANCH, @c BRANCH-ACTIONs are executed if we
-shift to the current state after handling all typed keys. If the
-current state is the initial state, @c BRANCH-ACTIONs are executed
-just after an input context of the input method is created.
+In the third form of @c BRANCH, @c BRANCH-ACTIONs are executed when
+shifted to the current state. If the current state is the initial
+state, @c BRANCH-ACTIONs are executed also when an input context of
+the input method is created.
@verbatim
BRANCH-ACTION ::= ACTION
Each @c PREDEFINED-SYMBOL has a special meaning when used as a marker.
<ul>
+<li> @c @@0, @c @@1, @c @@2, @c @@3, @c @@4, @c @@5, @c @@6, @c @@7, @c @@8, @c @@9
+
+The 0th, 1st, 2nd, ... 9th position respectively.
+
<li> @c @@<, @c @@=, @c @@>
The first, the current, and the last position.
The previous and the next position where a candidate list changes.
</ul>
-Each @c PREDEFINED-SYMBOL has a special meaning when used as a candidate
+Some of the @c PREDEFINED-SYMBOL has a special meaning when used as a candidate
index in the @c SELECT action.
<ul>
+
<li> @c @@<, @c @@=, @c @@>
The first, the current, and the last candidate of the current candidate group.
candidate index as the current one.
</ul>
+And, this also has a special meaning.
+
+<ul>
+<li> @c @@@
+
+Number of handled keys at that moment.
+
+</ul>
+
+These are for supporting surround text handling.
+
+<ul>
+<li> @c @@-N
+
+Here, @c N is a positive integer. The value is a character at Nth
+previous position from the current caret of the surrounding text.
+When this is used as the argument of @c delete action, it specifies
+how many preceding characters in the surround text to delete.
+
+<li> @c @@+N
+
+Here, @c N is a positive integer. The value is a character at Nth
+next position from the current caret of the surrounding text.
+When this is used as the argument of @c delete action, it specifies
+how many following characters in the surround text to delete.
+</ul>
+
The arguments and the behavior of each action are listed below.
@verbatim
This action treats @c SYMBOL as a marker, and sets its position to the
current position. @c SYMBOL must not be a @c PREDEFINED-SYMBOL.
+@verbatim
+PUSHBACK :: = '(' 'pushback' INTEGER ')'
+ | '(' 'pushback' KEYSEQ ')'
+@endverbatim
+
+The first form pushes back the latest @c INTEGER number of key events
+to the event queue if @c INTEGER is positive, and pushes back all key
+events if @c INTEGER is zero.
+
+The second form pushes back keys in @c KEYSEQ to the event queue.
@verbatim
-PUSHBACK :: = '(pushback INTEGER)'
+POP ::= '(' 'pop' ')'
@endverbatim
-This action pushes back the latest key events to the event queue.
+This action pops the first key event that is not yet handled from the
+event queue.
+
+@verbatim
+UNDO :: = '(' 'undo' [ INTEGER | SYMBOL ] ')'
+@endverbatim
+
+If there's no argument, this action cancels the last two key events
+(i.e. the one that invoked this command, and the previous one).
+
+If there's an integer argument NUM, it must be positive or negative
+(not zero). If positive, from the NUMth to the last events are
+canceled. If negative the last (- NUM) events are canceled.
+
+If there's a symbol argument, it must be resolved to an integer number
+and the number is treated as the actual argument as above.
@verbatim
-UNDO :: = '(undo)'
+UNHANDLE :: = '(unhandle)'
@endverbatim
-This action cancels the last key event.
+This action commit the current preedit and return the last key as
+unhandled.
@verbatim
SHIFT :: = '(' 'shift' STATE-NAME ')'
represents a list of actions to take.
@verbatim
-SET ::= '(' OPERAND SYMBOL1 [ INTEGER | SYMBOL2 ] ')'
+SET ::= '(' CMD SYMBOL1 EXPRESSION ')'
+
+CMD ::= 'set' | 'add' | 'sub' | 'mul' | 'div'
+
+EXPRESSION ::= INTEGER | SYMBOL2 | '(' OPERAND EXPRESSION * ')'
+
+OPERAND ::= '+' | '-' | '*' | '/' | '|' | '&' | '!'
+ | '=' | '<' | '>' | '<=' | '>='
-OPERAND ::= 'set' | 'add' | 'sub' | 'mul' | 'div'
@endverbatim
This action treats @c SYMBOL1 and @c SYMBOL2 as variables and sets the
value of @c SYMBOL1 as below.
-If @c OPERAND is 'set', it sets the value of @c SYMBOL1 to @c INTEGER or the
-value of @c SYMBOL2.
+If @c CMD is 'set', it sets the value of @c SYMBOL1 to the value of @c
+EXPRESSION.
-If @c OPERAND is 'add', it increments the value of @c SYMBOL1 by @c INTEGER
-or the value of @c SYMBOL2.
+If @c CMD is 'add', it increments the value of @c SYMBOL1 by the value
+of @c EXPRESSION.
-If @c OPERAND is 'sub', it decrements the value of @c SYMBOL1 by @c INTEGER
-or the value of @c SYMBOL2.
+If @c CMD is 'sub', it decrements the value of @c SYMBOL1 by the value
+of @c EXPRESSION.
-If @c OPERAND is 'mul', it multiplies the value of @c SYMBOL1 by @c INTEGER
-or the value of @c SYMBOL2.
+If @c CMD is 'mul', it multiplies the value of @c SYMBOL1 by the value
+of @c EXPRESSION.
-If @c OPERAND is 'div', it divides the value of @c SYMBOL1 by @c INTEGER or
-the value of @c SYMBOL2.
+If @c CMD is 'div', it divides the value of @c SYMBOL1 by the value of
+@c EXPRESSION.
@verbatim
-IF ::= '(' 'if' CONDITION ACTION-LIST1 ACTION-LIST2 * ')'
+IF ::= '(' CONDITION ACTION-LIST1 ACTION-LIST2 ')'
-CONDITION ::= '(' OPERAND VAL1 VAL2 ')'
+CONDITION ::= [ '=' | '<' | '>' | '<=' | '>=' ] EXPRESSION1 EXPRESSION2
ACTION-LIST1 ::= '(' ACTION * ')'
ACTION-LIST2 ::= '(' ACTION * ')'
-
-OPERAND ::= '=' '<' '>'
-
-VAL1 ::= [ INTEGER1 | SYMBOL1 ]
-
-VAL2 ::= [ INTEGER2 | SYMBOL2 ]
@endverbatim
This action performs actions in @c ACTION-LIST1 if @c CONDITION is
@c SYMBOL1 and @c SYMBOL2 are treated as variables.
+@verbatim
+COND ::= '(' 'cond' [ '(' EXPRESSION ACTION * ') ] * ')'
+@endverbatim
+
+This action performs the first action @c ACTION whose corresponding
+@c EXPRESSION has nonzero value.
+
@ifnot FOR-MAN
@section im-example1 EXAMPLE 1
This is a very simple example for inputting Latin characters with
diacritical marks (acute and cedilla). For instance, when you type:
@verbatim
- Comme'die-Franc,ais, chic,,
+ Comme'die-Franc,aise, chic,,
@endverbatim
you will get this:
@if FOR-HTML
@verbatim
- Commédie-Français, chic,
+ Commédie-Française, chic,
@endverbatim
@endif
@if FOR-LATEX
@latexonly
-\hskip5mm\texttt{\footnotesize Comm\'{e}die-Fran\c{c}ais, chic,}
+\hskip5mm\texttt{\footnotesize Comm\'{e}die-Fran\c{c}aise, chic,}
@endlatexonly
@endif
@section im-example2 EXAMPLE 2
This example is for inputting Unicode characters by typing C-u
-(Control-u) followed by four hexadecimal numbers. For instance, when
+(Control-u) followed by four hexadecimal digits. For instance, when
you type ("^u" means Control-u):
@verbatim
^u2190^u2191^u2192^u2193
*/
/*
-Copyright (C) 2003, 2004
+Copyright (C) 2003, 2004, 2005
National Institute of Advanced Industrial Science and Technology (AIST)
Registration Number H15PRO112
You should have received a copy of the GNU Lesser General Public
License along with the m17n library; if not, write to the Free
-Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
-02111-1307, USA.
+Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+Boston, MA 02110-1301, USA.
*/
/* Local Variables: */
projects / m17n / m17n-db.git / blobdiff