@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
IM-DECLARATION ? DESCRIPTION ? VARIABLE-LIST ? COMMAND-LIST ?
TITLE MAP-LIST MACRO-LIST ? MODULE-LIST ? STATE-LIST
-IM-DECLARATION ::= '(' 'input-method' LANGUAGE NAME ')'
-DESCRIPTION ::= '(' 'description' MTEXT ')'
+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 [ VAR-DESCRIPTION | nil ] VALUE VALUE-CANDIDATE * ')'
+ '(' VAR-NAME [ MTEXT-OR-GETTEXT | nil ] VALUE VALUE-CANDIDATE * ')'
COMMAND-DECLARATION ::=
- '(' CMD-NAME [ CMD-DESCRIPTION | nil ] KEYSEQ * ')'
+ '(' 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
TITLE-TEXT ::= MTEXT
@endverbatim
-@c IM-DECLARATION
-
-...to be filled...
-
-@c DESCRIPTION
+@c IM-DECLARATION specifies the language and name of this input
+method.
-...to be filled...
+@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 VARIABLE-DECLARATION
+@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).
-...to be filled...
+@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
-
-...to be filled...
+@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.
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.
MAP-ACTION ::= ACTION
ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK
- | SHOW | HIDE | PUSHBACK | UNDO | SHIFT | CALL
- | SET | IF | '(' MACRO-NAME ')'
+ | 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
Number of handled keys at that moment.
-</ulL
+</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.
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 ')'
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 KEYSEQ to the event queue.
+The second form pushes back keys in @c KEYSEQ to the event queue.
+
+@verbatim
+POP ::= '(' 'pop' ')'
+@endverbatim
+
+This action pops the first key event that is not yet handled from the
+event queue.
@verbatim
UNDO :: = '(' 'undo' [ INTEGER | SYMBOL ] ')'
(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, the NUMth event to the last one are
-cancelled. If negative the last (- NUM) events are cancelled.
+(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
+UNHANDLE :: = '(unhandle)'
+@endverbatim
+
+This action commit the current preedit and return the last key as
+unhandled.
+
+@verbatim
SHIFT :: = '(' 'shift' STATE-NAME ')'
@endverbatim
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 ::= '(' 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
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