From a112547f91d8b4131ed01a05f15f22aa18b85a49 Mon Sep 17 00:00:00 2001
From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Thu, 25 Jul 2019 11:52:59 +0200
Subject: [PATCH] Clarify in the manual when to use function-key-map

* doc/misc/efaq.texi (No Escape key):
* doc/emacs/msdos-xtra.texi (MS-DOS Keyboard): Change back to
function-key-map from local-function-key-map, because these
bindings apply to all terminals.

* doc/lispref/keymaps.texi (Translation Keymaps): Clarify in what
circumstances you may still want to use function-key-map.
---
 doc/emacs/msdos-xtra.texi | 2 +-
 doc/lispref/keymaps.texi  | 5 +++--
 doc/misc/efaq.texi        | 4 ++--
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/doc/emacs/msdos-xtra.texi b/doc/emacs/msdos-xtra.texi
index 32cdcd4f9db..e0d3bcd4093 100644
--- a/doc/emacs/msdos-xtra.texi
+++ b/doc/emacs/msdos-xtra.texi
@@ -105,7 +105,7 @@ following line into your @file{_emacs} file:
 
 @smallexample
 ;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.}
-(define-key local-function-key-map [kp-enter] [?\C-j])
+(define-key function-key-map [kp-enter] [?\C-j])
 @end smallexample
 
 @node MS-DOS Mouse
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 6ad665a9502..b8eed0a501c 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1614,8 +1614,9 @@ 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.
 
-@code{local-function-key-map} inherits from @code{function-key-map},
-but the latter should not be used directly.
+@code{local-function-key-map} inherits from @code{function-key-map}.
+The latter should only be altered if you want the binding to apply in
+all terminals, so using the former is almost always preferred.
 @end defvar
 
 @defvar key-translation-map
diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index fcc8e9f11ed..8fd3bf3a45e 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -3890,7 +3890,7 @@ The only way to affect the behavior of keys within Emacs is through
 @code{local-function-key-map} map.  For instance,
 
 @lisp
-(define-key local-function-key-map [M-@key{TAB}] [?\M-\t])
+(define-key function-key-map [M-@key{TAB}] [?\M-\t])
 @end lisp
 
 @noindent
@@ -4099,7 +4099,7 @@ generates @key{ESC}.  If not, the following form can be used to bind it:
 
 @lisp
 ;; F11 is the documented ESC replacement on DEC terminals.
-(define-key local-function-key-map [f11] [?\e])
+(define-key function-key-map [f11] [?\e])
 @end lisp
 
 @node Compose Character
-- 
2.39.2