[SCIM] Re: [m17n-lib:00106] Re: SCIM help for M17N input methods (was: Custom Keyboard Layout Editor/Interpreter for SCIM)

[Kenichi Handa]

Zhe Su <james.su@gmail.com> writes:
>   Such approach is good, but too complicated to be implemented in
> current scim-m17n and scim. So for short term solution, is it possible
> to just give a plain text help including the URL to the real help
> webpage.

Sorry for the late response on this matter.

I'm going to implement these new API's (the detail is
attached at the tail).  I'd like to hear your opinions.

(1) For getting a description text of an input method

See minput_get_description () below.

(2) For customizing input keys

I'm going to allow to specify a pseudo input key (instead of
the current realy key (key sequence)) in *.mim file.  I'll
name such a key as "input method command", and make it
customizable by using the functions minput_get_command_keys
() and minput_set_command_keys ().

For instance, currently several m17n input methods contains
this kind of code:

 (change-candidate
  ((Left) (select @-))
  ((Right) (select @+))
  ((Up) (select @[))
  ((Down) (select @])))

I'd like to change it to something like this:

 (change-candidate
  (prev-candidate (select @-))
  (next-candidate (select @+))
  (prev-candidate-group (select @[))
  (next-candidate-group (select @])))

Here, prev-candidate, next-candidate, ... are the input
method commands.  I'll make m17n-db to provide the default
definition of them as this:

(prev-candidate
 ((Left) (C-B))  <- list of assigned keys
 "Previous candidate" <- brief description
 "Select the previous candidate" <- defailed description
 )

Then, by using minput_get_command_keys () to retrieve that
information and minput_set_command_keys to update the list
of assigned keys, we can make a GUI for customizing command
keys.

Each input method can have its own command definitions that
are used only in that input method.  For instance, in
ja-anthy.mim:

 (convert-to-katakana 
  ("K")
  "Convert to katakana"
  "Convert the preedit text to Katakana")
 (convert-to-hiragana
  ("H")
  "Convert to hiragana"
  "Convert the preedit text to Hiragana"))

It may be good if this kind of information can be shared
among the other input methods (not those of m17n-lib).

(3) For customizing the behaviour of an input method

It is good to reflect a users preference on the behaviour of
input method.  For instance, in CJK input methods, one may
prefer FULLWIDTH COMMA (U+FF0C) and FULLWIDTH FULLSTOP
(U+FF0E) to IDEOGRAPHIC COMMA (U+3001) and IDEOGRAPHIC
FULLSTOP (U+3002).

For such a case, I'm going to allow to have this kind of
specification in *.mim file.

 (punctuation-mode
  (0 "IDEOGRAPHIC"
     "Use IDEOGRAPHIC COMMA and FULLSTOP (U+3001, U+3002)")
  (1 "FULLWIDTH"
     "Use FULLWIDTH COMMA and FULLSTOP (U+FF0C, U+FF0E)")
  (2 "ASCII"
     "Use ASCII COMMA and FULLSTOP"))

Then minput_get_variables () and minput_set_variable () can
be used to customize it.

(4) For loading and saving the customization.

It's upto users of m17n-lib (e.g. SCIM and UIM) how to save
and load the above customization, but
minput_load_customization and minput_save_customization may
be convenient.

---
Ken'ichi HANDA
handa@m17n.org


/***en
    @brief Key of a text property for detailed description.

    The symbol #M_details is a managing key usually used for a text
    property whose value is an M-text that contains detailed
    description.  */
MSymbol M_details;

/***en
    @brief Get description text of an input method

    The minput_get_description () function returns an M-text briefly
    describing the input method specified by $LANG and $NAME.  It may
    have a text property #M_details whose value is an M-text
    describing the input method in more detail.

    @return
    If the specified input method has a description text, a pointer to
    #MText is returned.  A caller have to free it by m17n_object_unref ().
    If the input method does not have a description text, NULL is
    returned.  */

MText *
minput_get_description (MSymbol lang, MSymbol name)
{
  /* ... */
}

/***en
    @brief Get information about input method commands

    The minput_get_command_keys () function returns information about
    input method commands of the input method specified by $LANG and
    $NAME.  An input method command is a pseudo key event to which
    actual input keys or input key sequences are assigned.

    If both $LANG and $NAME are #Mnil, this function returns
    information about global input method commands used by all input
    methods consistently; i.e. the same command is used for the same
    purpose in all input methods (e.g. for selecting a candidate).

    The return value is a plist (#MPlist) whose keys are symbols
    representing a command, and values are COMMAND-PLIST, a plist
    defining that command.  Each definition contains a description
    text and one or more input key sequences assigned to the command
    by elements of the following format.

    If a key is #Mplist, the value is a plist whose keys are #Msymbol
    and values are symbols representing input keys.  This sequence of
    input keys are currently assigned to the command.  COMMAND-PLIST
    may have multiple elements of this format.  In that case, all key
    sequences are assigned to the command.

    If a key is #Mtext, the value is an M-text describing the meaning
    of the command briefly.  This M-text may have a text property
    #M_details whose value is an M-text describing the command in more
    detail.

    @return
    If there are commands (per input-method or globally), a pointer to
    #MPlist is returned.  As the plist is kept in the library, a
    caller must not modify or free it.  If there are no command, NULL
    is returned.  */

MPlist *
minput_get_command_keys (MSymbol lang, MSymbol name)
{
  /* ... */
}

/***en
    @brief Assign input keys to an input method command

    The minput_set_command_keys () function assigns input keys $KEYS
    to an input method command $COMMAND for the input method specified
    by $LANG and $NAME.  If both $LANG and $NAME are #Mnil, the input
    keys are assigned to the global command.

    An element of $KEYS has $Mplist as key and KEYSEQ-PLIST as value.
    KEYSEQ-PLIST is a plist representing a key sequence to be assigned
    to the command.  An element of KEYSEQ-PLIST has $Msymbol as key
    and a symbol of input key as value.

    This assignment is reflected in a newly opened input method.

    @return
    If the operation was successful, 0 is returned.  Otherwise -1 is
    returned, and #merror_code is set to #MERROR_IM.  */

int
minput_set_command_keys (MSymbol lang, MSymbol name,
			 MSymbol command, MPlist *keys)
{
  /* ... */
}

/***en
    @brief Get a list of variables of an input method

    The minput_get_variables () function returns a plist (#MPlist) of
    variables used to control the behaviour of the input method
    specified by $LANG and $NAME.  Keys of the plist are symbols
    representing the variables and values are plists carrying the
    information about the corresponding variable in this format.

    If a key of the plist is #Mtext, the value is an M-text describing
    the variable briefly.  This M-text may have a text property
    #M_details whose value is an M-text describing the variable in
    more detail.

    If a key of the plist is #Mplist, the value is VALUE-PLIST, a
    plist of possible values of the variable.

    Each element of VALUE-PLIST has key #Minteger or #Mtext by turns.

    If the key is #Minteger, the value is one of possible integer
    values of the variable.

    If the key is #Mtext, the value is an M-text describing the
    meaning of the value specified in the previous element.  This
    M-text may have a text property #M_details whose value is an
    M-text describing the value in more detail.

    In short, the returned plist has this form ('X:Y' means X is a key
    and Y is a value, and '(...)' means a plist):
@verbatim
    (VAR1-NAME:(mtext:VAR1-DESCRIPTION
                plist:(integer:VAL1 
                       mtext:VAL1-DESCRIPTION
                       integer:VAL2
                       mtext:VAL2-DESCRIPTION
                       ...))
     VAR2-NAME:...
     ...)
@endverbatim

    @return
    If the input method uses some variable, a pointer to #MPlist is
    returned.  As the plist is kept in the library, a caller must not
    modify nor free it.  If the input method does not use any
    variable, NULL is returned.  */

MPlist *
minput_get_variables (MSymbol lang, MSymbol name)
{
  /* ... */
}

/***en
    @brief Set the initial value of an input method variable

    The minput_set_variable () function sets the initial value of
    input method variable $VARIABLE to $VALUE for the input method
    specified by $LANG and $NAME.

    By default, the initial value is 0.

    This setting is reflected to a newly opened input method.

    @return
    If the operation was successful, 0 is returned.  Otherwise -1 is
    returned, and #merror_code is set to #MERROR_IM.  */

int
minput_set_variable (MSymbol lang, MSymbol name, MSymbol variable, int value)
{
  /* ... */
}

/***en
    @brief Load customization information of input methods

    The minput_load_customization () function loads customization
    information of input methods from M-text $MT.

    @return
    If the operation was successful, 0 is returned.  Otherwise -1 is
    returned, and #merror_code is set to #MERROR_IM.  */

int
minput_load_customization (MText *mt)
{
  /* ... */
}

/***en
    @brief Save customization information of input methods

    The minput_save_customization () function return an M-text that
    contains customization information of input methods.  The M-text
    is valid as an argument to minput_load_customization ().

    @return
    If there exists customization information, a pointer to #MText is
    returned.  Otherwise, NULL is returned.
*/

MText *
minput_save_customization (void)
{
  /* ... */
}