bug#64425: [PATCH] Mention minibuffer-next-completion in completion-help

[sbaugh]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: sbaugh@catern.com
>> Date: Sun, 02 Jul 2023 16:31:21 +0000 (UTC)
>> 
>> * lisp/simple.el (completion-list-mode-map): Bind
>> minibuffer-{next,previous,choose}-completion.
>> (completion-setup-function): Mention bindings for
>> minibuffer-{next,previous,choose}-completion.
>> ---
>>  lisp/simple.el | 7 +++++--
>>  1 file changed, 5 insertions(+), 2 deletions(-)
>> 
>> diff --git a/lisp/simple.el b/lisp/simple.el
>> index 406f1008df3..59e1311eb2b 100644
>> --- a/lisp/simple.el
>> +++ b/lisp/simple.el
>> @@ -9697,6 +9697,9 @@ completion-list-mode-map
>>      (define-key map [right] 'next-completion)
>>      (define-key map [?\t] 'next-completion)
>>      (define-key map [backtab] 'previous-completion)
>> +    (define-key map (kbd "M-<up>") 'minibuffer-previous-completion)
>> +    (define-key map (kbd "M-<down>") 'minibuffer-next-completion)
>> +    (define-key map (kbd "M-RET") 'minibuffer-choose-completion)
>>      (define-key map "z" 'kill-current-buffer)
>>      (define-key map "n" 'next-completion)
>>      (define-key map "p" 'previous-completion)
>> @@ -10093,8 +10096,8 @@ completion-setup-function
>>      (goto-char (point-min))
>>      (if (display-mouse-p)
>>          (insert "Click on a completion to select it.\n"))
>> -    (insert (substitute-command-keys
>> -             "In this buffer, type \\[choose-completion] to \
>> +        (insert (substitute-command-keys
>> +             "Type \\[minibuffer-next-completion] and 
>> \\[minibuffer-previous-completion] to change completion, and 
>> \\[minibuffer-choose-completion] to \
>>  select the completion near point.\n\n"))))))
>
> Isn't this text too long for a single screen line?  If so, it will
> cause an annoying "jumping" of the mode line.

Good point, how about this wording:

diff --git a/lisp/simple.el b/lisp/simple.el
index 406f1008df3..26944f1f72d 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -10091,11 +10094,13 @@ completion-setup-function
       ;; Maybe insert help string.
       (when completion-show-help
        (goto-char (point-min))
-       (if (display-mouse-p)
-           (insert "Click on a completion to select it.\n"))
-       (insert (substitute-command-keys
-                "In this buffer, type \\[choose-completion] to \
-select the completion near point.\n\n"))))))
+        (insert (substitute-command-keys
+                (if (display-mouse-p)
+                    "Click or type \\[minibuffer-choose-completion] on a 
completion to select it.\n"
+                   "Type \\[minibuffer-choose-completion] on a completion to 
select it.\n")))
+        (insert (substitute-command-keys
+                "Type \\[minibuffer-next-completion] or 
\\[minibuffer-previous-completion] \
+to move point between completions.\n\n"))))))
 
 (add-hook 'completion-setup-hook #'completion-setup-function)
 
Associated patch:

>From d551dd05ce14fbc950b98965e456bdac253650d0 Mon Sep 17 00:00:00 2001
From: Spencer Baugh <sbaugh@catern.com>
Date: Sun, 2 Jul 2023 12:30:00 -0400
Subject: [PATCH] Mention minibuffer-next-completion in completion-help

Now that it's not necessary to switch to the *Completions* buffer to
switch between and choose completions, we should make that clear in
the help text.  Let's also make the bindings uniform both in and
outside the *Completions* buffer so users don't have to think about
the difference.

In working with new users, they've assumed that since the help text in
*Completions* says "Click on a completion to select it", that that's
the only way to select a completion.  This text should help clarify
that.

* lisp/simple.el (completion-list-mode-map): Bind
minibuffer-{next,previous,choose}-completion.
(completion-setup-function): Mention bindings for
minibuffer-{next,previous,choose}-completion. (Bug#64425)
---
 lisp/simple.el | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/lisp/simple.el b/lisp/simple.el
index 406f1008df3..26944f1f72d 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -9697,6 +9697,9 @@ completion-list-mode-map
     (define-key map [right] 'next-completion)
     (define-key map [?\t] 'next-completion)
     (define-key map [backtab] 'previous-completion)
+    (define-key map (kbd "M-<up>") 'minibuffer-previous-completion)
+    (define-key map (kbd "M-<down>") 'minibuffer-next-completion)
+    (define-key map (kbd "M-RET") 'minibuffer-choose-completion)
     (define-key map "z" 'kill-current-buffer)
     (define-key map "n" 'next-completion)
     (define-key map "p" 'previous-completion)
@@ -10091,11 +10094,13 @@ completion-setup-function
       ;; Maybe insert help string.
       (when completion-show-help
        (goto-char (point-min))
-       (if (display-mouse-p)
-           (insert "Click on a completion to select it.\n"))
-       (insert (substitute-command-keys
-                "In this buffer, type \\[choose-completion] to \
-select the completion near point.\n\n"))))))
+        (insert (substitute-command-keys
+                (if (display-mouse-p)
+                    "Click or type \\[minibuffer-choose-completion] on a 
completion to select it.\n"
+                   "Type \\[minibuffer-choose-completion] on a completion to 
select it.\n")))
+        (insert (substitute-command-keys
+                "Type \\[minibuffer-next-completion] or 
\\[minibuffer-previous-completion] \
+to move point between completions.\n\n"))))))
 
 (add-hook 'completion-setup-hook #'completion-setup-function)
 
-- 
2.41.0

> Also, what about updating the documentation?

All the other relevant documentation that I know about has already been
updated to mention minibuffer-{next,previous,choose}-completion.