master 2970dbaa32: Document `keymap-lookup' in the lipsref manual

[Lars Ingebrigtsen]

branch: master
commit 2970dbaa32e6b33189973ce814b1b327bbbb15fa
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Document `keymap-lookup' in the lipsref manual
    
    * doc/lispref/keymaps.texi (Functions for Key Lookup): Document
    `keymap-lookup' instead of `lookup-key' (bug#52820).
---
 doc/lispref/keymaps.texi | 39 ++++++++++++++++++++++++---------------
 1 file changed, 24 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 0aa7eaa149..11cad3957e 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1183,22 +1183,18 @@ macro, a symbol that leads to one of them, or 
@code{nil}.
 
   Here are the functions and variables pertaining to key lookup.
 
-@defun lookup-key keymap key &optional accept-defaults
+@defun keymap-lookup keymap key &optional accept-defaults no-remap position
 This function returns the definition of @var{key} in @var{keymap}.  All
 the other functions described in this chapter that look up keys use
-@code{lookup-key}.  Here are examples:
+@code{keymap-lookup}.  Here are examples:
 
 @example
 @group
-(lookup-key (current-global-map) "\C-x\C-f")
+(keymap-lookup (current-global-map) "C-x C-f")
     @result{} find-file
 @end group
 @group
-(lookup-key (current-global-map) (kbd "C-x C-f"))
-    @result{} find-file
-@end group
-@group
-(lookup-key (current-global-map) "\C-x\C-f12345")
+(keymap-lookup (current-global-map) "C-x C-f 1 2 3 4 5")
     @result{} 2
 @end group
 @end example
@@ -1209,9 +1205,9 @@ and have extra events at the end that do not fit into a 
single key
 sequence.  Then the value is a number, the number of events at the front
 of @var{key} that compose a complete key.
 
-If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
+If @var{accept-defaults} is non-@code{nil}, then @code{keymap-lookup}
 considers default bindings as well as bindings for the specific events
-in @var{key}.  Otherwise, @code{lookup-key} reports only bindings for
+in @var{key}.  Otherwise, @code{keymap-lookup} reports only bindings for
 the specific sequence @var{key}, ignoring default bindings except when
 you explicitly ask about them.  (To do this, supply @code{t} as an
 element of @var{key}; see @ref{Format of Keymaps}.)
@@ -1224,11 +1220,11 @@ the second example.
 
 @example
 @group
-(lookup-key (current-global-map) "\M-f")
+(keymap-lookup (current-global-map) "M-f")
     @result{} forward-word
 @end group
 @group
-(lookup-key (current-global-map) "\ef")
+(keymap-lookup (current-global-map) "ESC f")
     @result{} forward-word
 @end group
 @end example
@@ -1239,6 +1235,19 @@ Unlike @code{read-key-sequence}, this function does not 
modify the
 specified events in ways that discard information (@pxref{Key Sequence
 Input}).  In particular, it does not convert letters to lower case and
 it does not change drag events to clicks.
+
+Like the normal command loop, @code{keymap-lookup} will remap the
+command resulting from looking up @var{key} by looking up the command
+in the current keymaps.  However, if the optional third argument
+@var{no-remap} is non-@code{nil}, @code{keymap-lookup} returns the
+unmapped command.
+
+If the optional argument @var{position} is non-@code{nil}, it
+specifies a mouse position as returned by @code{event-start} and
+@code{event-end}, and the lookup occurs in the keymaps associated with
+it instead of @var{key}.  It can also be a number or marker, in which
+case the keymap properties at the specified buffer position instead of
+point are used.
 @end defun
 
 @deffn Command undefined
@@ -1251,7 +1260,7 @@ This function returns the binding for @var{key} in the 
current
 local keymap, or @code{nil} if it is undefined there.
 
 The argument @var{accept-defaults} controls checking for default bindings,
-as in @code{lookup-key} (above).
+as in @code{keymap-lookup} (above).
 @end defun
 
 @defun keymap-global-binding key &optional accept-defaults
@@ -1259,7 +1268,7 @@ This function returns the binding for command @var{key} 
in the
 current global keymap, or @code{nil} if it is undefined there.
 
 The argument @var{accept-defaults} controls checking for default bindings,
-as in @code{lookup-key} (above).
+as in @code{keymap-lookup} (above).
 @end defun
 
 @defun minor-mode-key-binding key &optional accept-defaults
@@ -1276,7 +1285,7 @@ modes are omitted, since they would be completely 
shadowed.  Similarly,
 the list omits non-prefix bindings that follow prefix bindings.
 
 The argument @var{accept-defaults} controls checking for default
-bindings, as in @code{lookup-key} (above).
+bindings, as in @code{keymap-lookup} (above).
 @end defun
 
 @defopt meta-prefix-char