From 38cdfcb2128d5a7b2eb174faca0ef1e32f641e85 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Wed, 5 Apr 2023 11:31:15 +0300
Subject: [PATCH] ; Fix description of new 'keymap-*' functions

* doc/lispref/keymaps.texi (Prefix Keys): Fix example (bug#62673).
(Functions for Key Lookup): Clarify the possible values of KEYMAP
argument of 'keymap-lookup'.
(Active Keymaps): Fix typo in function name; add cross-reference.
---
 doc/lispref/keymaps.texi | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index fdab5075b94..6d07ad5be2c 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -768,8 +768,8 @@ prefix definition, and then by those from the global map.
   In the following example, we make @kbd{C-p} a prefix key in the local
 keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}.  Then
 the binding for @kbd{C-p C-f} is the function @code{find-file}, just
-like @kbd{C-x C-f}.  The key sequence @kbd{C-p 6} is not found in any
-active keymap.
+like @kbd{C-x C-f}.  By contrast, the key sequence @kbd{C-p 9} is not
+found in any active keymap.
 
 @example
 @group
@@ -778,15 +778,14 @@ active keymap.
 @end group
 @group
 (keymap-local-set "C-p" ctl-x-map)
-    @result{} nil
+    @result{} (keymap #^[nil nil keymap @dots{}
 @end group
 @group
-(keymap-binding "C-p C-f")
+(keymap-lookup nil "C-p C-f")
     @result{} find-file
 @end group
-
 @group
-(keymap-binding "C-p 6")
+(keymap-lookup nil "C-p 9")
     @result{} nil
 @end group
 @end example
@@ -883,7 +882,7 @@ Normally it ignores @code{overriding-local-map} and
 then it pays attention to them.  @var{position} can optionally be either
 an event position as returned by @code{event-start} or a buffer
 position, and may change the keymaps as described for
-@code{keymap-binding}.
+@code{keymap-lookup} (@pxref{Functions for Key Lookup, keymap-lookup}).
 @end defun
 
 @node Searching Keymaps
@@ -1308,7 +1307,11 @@ the second example.
 @end group
 @end example
 
-The @var{keymap} argument can also be a list of keymaps.
+The @var{keymap} argument can be @code{nil}, meaning to look up
+@var{key} in the current keymaps (as returned by
+@code{current-active-maps}, @pxref{Active Keymaps}); or it can be a
+keymap or a list of keymaps, meaning to look up @var{key} only in the
+specified keymaps.
 
 Unlike @code{read-key-sequence}, this function does not modify the
 specified events in ways that discard information (@pxref{Key Sequence
-- 
2.39.2