(Translating Input): Only non-prefix bindings in `key-translation-map'

override actual key bindings.  Warn about possible indirect effect of
actual key bindings on non-prefix bindings in `key-translation-map'.

1 files changed, 10 insertions, 4 deletions

diff --git a/lispref/os.texi b/lispref/os.texi
index 3e1b93339a..42a0613bfe 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -1686,12 +1686,18 @@ finished; it receives the results of translation by
 @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.
+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}.