Re: Rebinding international characters

[Luc Teirlinck]

Stefan Monnier wrote:

   The interaction between function-key-map, key-translation-map and normal
   maps is pretty subtle.  Just writing text that gives some vague idea of
   what's happening but without giving you false expectations is
   very difficult.  This is because there are conflicting goals.

Yes but that is no reason not to correct the particular inaccurate
statement that caused confusion in this case.

There is something else with the "subtle" interaction that is quite
peculiar.  `function-key-map' gets applied before `key-translation-map'.
Hence, `function-key-map' overrides `key-translation-map' which
overrides regular keybindings which override `function-key-map'.
Circular overriding is not exactly ideal.  I guess that this does not
produce the problems one would expect it to, because
(from `(elisp)Translating Input'):
     
     The intent is that the character sequences that function keys
     send should not have command bindings in their own right--but if
     they do, the ordinary bindings take priority.

As long as that intent is followed, the fact that regular keybindings
override `function-key-map' is irrelevant and the circular overriding
does not matter.  However, I believe that we should warn in the Elisp
manual about some of the potential paradoxes that can result from
circular overriding.  (This is done in the proposed patch below.)

I propose the following patches to keymap.c and os.texi.

===File ~/keymap.c-diff=====================================
*** keymap.c    31 Jul 2004 10:53:36 -0500      1.292
--- keymap.c    04 Aug 2004 21:35:56 -0500      
***************
*** 3751,3757 ****
    DEFVAR_LISP ("key-translation-map", &Vkey_translation_map,
               doc: /* Keymap of key translations that can override keymaps.
  This keymap works like `function-key-map', but comes after that,
! and applies even for keys that have ordinary bindings.  */);
    Vkey_translation_map = Qnil;
  
    staticpro (&Vmouse_events);
--- 3751,3757 ----
    DEFVAR_LISP ("key-translation-map", &Vkey_translation_map,
               doc: /* Keymap of key translations that can override keymaps.
  This keymap works like `function-key-map', but comes after that,
! and its non-prefix bindings override ordinary bindings.  */);
    Vkey_translation_map = Qnil;
  
    staticpro (&Vmouse_events);
============================================================

===File ~/os.texi-diff======================================
*** os.texi     06 Jul 2004 19:55:59 -0500      1.64
--- os.texi     04 Aug 2004 21:07:58 -0500      
***************
*** 1686,1697 ****
  @code{function-key-map}.
  
  @item
! @code{key-translation-map} overrides actual key bindings.  For example,
! if @kbd{C-x f} has a binding in @code{key-translation-map}, that
! translation takes effect even though @kbd{C-x f} also has a key binding
! in the global map.
  @end itemize
  
  The intent of @code{key-translation-map} is for users to map one
  character set to another, including ordinary characters normally bound
  to @code{self-insert-command}.
--- 1686,1703 ----
  @code{function-key-map}.
  
  @item
! Non-prefix bindings in @code{key-translation-map} override actual key
! bindings.  For example, if @kbd{C-x f} has a non-prefix binding in
! @code{key-translation-map}, that translation takes effect even though
! @kbd{C-x f} also has a key binding in the global map.
  @end itemize
  
+ Note however that actual key bindings can have an effect on
+ @code{key-translation-map}, even though they are overridden by it.
+ Indeed, actual key bindings override @code{function-key-map} and thus
+ may alter the key sequence that @code{key-translation-map} receives.
+ Clearly, it is better to avoid to avoid this type of situation.
+ 
  The intent of @code{key-translation-map} is for users to map one
  character set to another, including ordinary characters normally bound
  to @code{self-insert-command}.
============================================================