Add new `input-decode-map' keymap and use it for temrinal

escape sequences.
* keyboard.h (struct kboard): Add Vinput_decode_map.
Remove Vlocal_key_translation_map.
* keyboard.c (read_key_sequence): Add support for input-decode-map.
(init_kboard): Init input-decode-map.
Replace local-key-translation-map back with key-translation-map.
(syms_of_keyboard): Declare input-decode-map.
Remove local-key-translation-map.  Update docstrings.
(mark_kboards): Mark Vinput_decode_map.
Don't mark Vlocal_key_translation_map.
* keymap.c (Fdescribe_buffer_bindings): Describe input-decode-map.
Replace local-key-translation-map back with key-translation-map.
* term.c (term_get_fkeys_1, CONDITIONAL_REASSIGN):
Bind in input-decode-map rather than function-key-map.

5 files changed, 50 insertions, 41 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index d496ab84b19..1276c45af70 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2419,7 +2419,8 @@ kept.@refill
 
   The usual purpose of the terminal-specific library is to map the
 escape sequences used by the terminal's function keys onto more
-meaningful names, using @code{function-key-map}.  See the file
+meaningful names, using @code{input-decode-map} (or
+@code{function-key-map} before it).  See the file
 @file{term/lk201.el} for an example of how this is done.  Many function
 keys are mapped automatically according to the information in the
 Termcap data base; the terminal-specific library needs to map only the
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index eb10dfcbce3..2bd0de60f58 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1512,17 +1512,18 @@ specifies a list of keymaps to search in.  This argument is ignored if
   This section describes keymaps that are used during reading a key
 sequence, to translate certain event sequences into others.
 @code{read-key-sequence} checks every subsequence of the key sequence
-being read, as it is read, against @code{function-key-map} and then
-against @code{key-translation-map}.
+being read, as it is read, against @code{input-decode-map}, then
+@code{function-key-map}, and then against @code{key-translation-map}.
+
+@defvar input-decode-map
 
-@defvar function-key-map
 This variable holds a keymap that describes the character sequences sent
 by function keys on an ordinary character terminal.  This keymap has the
 same structure as other keymaps, but is used differently: it specifies
 translations to make while reading key sequences, rather than bindings
 for key sequences.
 
-If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
+If @code{input-decode-map} ``binds'' a key sequence @var{k} to a vector
 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
 key sequence, it is replaced with the events in @var{v}.
 
@@ -1530,50 +1531,49 @@ For example, VT100 terminals send @kbd{@key{ESC} O P} when the
 keypad @key{PF1} key is pressed.  Therefore, we want Emacs to translate
 that sequence of events into the single event @code{pf1}.  We accomplish
 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
-@code{function-key-map}, when using a VT100.
+@code{input-decode-map}, when using a VT100.
 
 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
 @key{ESC} O P}; later the function @code{read-key-sequence} translates
 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
 @code{[?\C-c pf1]}.
 
-Entries in @code{function-key-map} are ignored if they conflict with
-bindings made in the minor mode, local, or global keymaps.  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.
-
-The value of @code{function-key-map} is usually set up automatically
+The value of @code{input-decode-map} is usually set up automatically
 according to the terminal's Terminfo or Termcap entry, but sometimes
 those need help from terminal-specific Lisp files.  Emacs comes with
 terminal-specific files for many common terminals; their main purpose is
-to make entries in @code{function-key-map} beyond those that can be
+to make entries in @code{input-decode-map} beyond those that can be
 deduced from Termcap and Terminfo.  @xref{Terminal-Specific}.
 @end defvar
 
-@defvar key-translation-map
-This variable is another keymap used just like @code{function-key-map}
-to translate input events into other events.  It differs from
-@code{function-key-map} in two ways:
+@defvar function-key-map
 
-@itemize @bullet
-@item
-@code{key-translation-map} goes to work after @code{function-key-map} is
-finished; it receives the results of translation by
-@code{function-key-map}.
+This variable holds a keymap similar to @code{input-decode-map} except
+that it describes key sequences which should be translated to
+alternative interpretations that are usually preferred.  It applies
+after @code{input-decode-map} and before @code{key-translation-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
+Entries in @code{function-key-map} are ignored if they conflict with
+bindings made in the minor mode, local, or global keymaps.  I.e.
+the remapping only applies if the original key sequence would
+otherwise not have any binding.
+@end defvar
 
-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 this type of situation.
+@defvar key-translation-map
+This variable is another keymap used just like @code{input-decode-map}
+to translate input events into other events.  It differs from
+@code{input-decode-map} in that it goes to work after
+@code{function-key-map} is finished rather than before; it receives
+the results of translation by @code{function-key-map}.
+
+Just like @code{input-decode-map}, but unlike @code{function-key-map},
+this keymap is applied regardless of whether the input key-sequence
+has a normal binding.  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
+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
@@ -1581,7 +1581,8 @@ to @code{self-insert-command}.
 @end defvar
 
 @cindex key translation function
-You can use @code{function-key-map} or @code{key-translation-map} for
+You can use @code{input-decode-map}, @code{function-key-map}, or
+@code{key-translation-map} for
 more than simple aliases, by using a function, instead of a key
 sequence, as the ``translation'' of a key.  Then this function is called
 to compute the translation of that key.
diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi
index 5a5745b1b51..2e370f91238 100644
--- a/doc/lispref/maps.texi
+++ b/doc/lispref/maps.texi
@@ -113,7 +113,7 @@ The sparse keymap that displays the Special Props submenu of the Text
 Properties menu.
 
 @item function-key-map
-The keymap for translating keypad and function keys.@*
+The keymap for translating key sequences to preferred alternatives.@*
 If there are none, then it contains an empty sparse keymap.
 @xref{Translation Keymaps}.
 
@@ -151,6 +151,11 @@ A sparse keymap used by the @kbd{e} command of Info.
 @vindex Info-mode-map
 A sparse keymap containing Info commands.
 
+@item input-decode-map
+The keymap for translating keypad and function keys.@*
+If there are none, then it contains an empty sparse keymap.
+@xref{Translation Keymaps}.
+
 @item isearch-mode-map
 @vindex isearch-mode-map
 A keymap that defines the characters you can type within incremental
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 89b44a99353..68fba8d9774 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -279,7 +279,7 @@ trying the @samp{.elc} and @samp{.el} suffixes.
 @cindex Termcap
   The usual function of a terminal-specific library is to enable
 special keys to send sequences that Emacs can recognize.  It may also
-need to set or add to @code{function-key-map} if the Termcap or
+need to set or add to @code{input-decode-map} if the Termcap or
 Terminfo entry does not specify all the terminal's function keys.
 @xref{Terminal Input}.
 
diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi
index 4e9eaaff40e..c86b2383168 100644
--- a/doc/misc/viper.texi
+++ b/doc/misc/viper.texi
@@ -1745,7 +1745,8 @@ Setting this variable too high may slow down your typing.  Setting it too
 low may make it hard to type macros quickly enough.
 @item viper-translate-all-ESC-keysequences @code{t} on tty, @code{nil} on windowing display
 Normally, Viper lets Emacs translate only those ESC key sequences that are
-defined in the low-level key-translation-map or function-key-map, such as those
+defined in the low-level @code{input-decode-map}, @code{key-translation-map}
+or @code{function-key-map}, such as those
 emitted by the arrow and function keys. Other sequences, e.g., @kbd{\\e/}, are
 treated as @kbd{ESC} command followed by a @kbd{/}. This is good for people
 who type fast and tend to hit other characters right after they hit
@@ -2009,12 +2010,12 @@ not emit the right signals for Emacs to understand.  To let Emacs know about
 those keys, you will have to find out which key sequences they emit
 by typing @kbd{C-q} and then the key (you should switch to Emacs state
 first).  Then you can bind those sequences to their preferred forms using
-@code{function-key-map} as follows:
+@code{input-decode-map} as follows:
 
 @lisp
 (cond ((string= (getenv "TERM") "xterm")
-(define-key function-key-map "\e[192z" [f11])    ; L1
-(define-key function-key-map "\e[195z" [f14])    ; L4, Undo
+(define-key input-decode-map "\e[192z" [f11])    ; L1
+(define-key input-decode-map "\e[195z" [f14])    ; L4, Undo
 @end lisp
 
 The above illustrates how to do this for Xterm.  On VT100, you would have to
@@ -2206,6 +2207,7 @@ So much about Viper-specific bindings.
 Manual}, and the Emacs quick reference card for the general info on key
 bindings in Emacs.
 
+@vindex @code{input-decode-map}
 @vindex @code{function-key-map}
 @vindex @code{viper-vi-global-user-map}
 @vindex @code{viper-insert-global-user-map}