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

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

[sbaugh]

[-- Attachment #1: Type: text/plain, Size: 5023 bytes --]

Tags: patch


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.


In GNU Emacs 29.0.92 (build 2, x86_64-pc-linux-gnu, X toolkit, cairo
 version 1.16.0, Xaw3d scroll bars) of 2023-07-01 built on earth
Repository revision: b179926388ee76f7b3304535a7189f89bd7c7f8c
Repository branch: emacs-29
Windowing system distributor 'The X.Org Foundation', version 11.0.12014000
System Description: NixOS 22.11 (Raccoon)

Configured using:
 'configure --with-x-toolkit=lucid --with-tree-sitter CC=gcc
 PKG_CONFIG=pkg-config
 PKG_CONFIG_PATH=/nix/store/va9r2bdg56jc6qizpm6dyb97lnxfrhsy-file-5.44/lib/pkgconfig:/nix/store/2jinas874l3zqnprvniqjk8yb1mmikz3-ncurses-6.4-dev/lib/pkgconfig:/nix/store/0z5wasald7dmipjpbx8kw31pj0kzjxpg-libxml2-2.10.3-dev/lib/pkgconfig:/nix/store/qgqsyg7gmqy3fz6shvzhcc7m7pkfw2ig-zlib-1.2.13-dev/lib/pkgconfig:/nix/store/998srgfg7b1i0yfbpqcykmy8znadjq04-gnutls-3.8.0-dev/lib/pkgconfig:/nix/store/d5sfvi0cvg8zkvg4qahxlj1822i47knj-nettle-3.8.1-dev/lib/pkgconfig:/nix/store/8s5by4sa822nnqfnxj41clqhn39ys2av-gmp-with-cxx-6.2.1-dev/lib/pkgconfig:/nix/store/22hqhw3rkv97mamdy4s4d754bnavpw3r-jansson-2.14/lib/pkgconfig:/nix/store/vddrjv0wnknv73njnwzj3in0467dk9qa-harfbuzz-7.0.0-dev/lib/pkgconfig:/nix/store/vgasd5zjsvdvq3w7ik13sfyyj1n0m5v7-graphite2-1.3.14/lib/pkgconfig:/nix/store/l8d014vy8n42sp6r6j3wjqldylcyvqyk-dbus-1.14.4-dev/lib/pkgconfig:/nix/store/gqvyvc9ckzijwcw641v6qgg7fz8z63mc-expat-2.5.0-dev/lib/pkgconfig:/nix/store/dvgpj4kwxp5pxhax93zqv80b4ql8xwla-libselinux-3.3-dev/lib/pkgconfig:/nix/store/2gm71c7yljswz2yz3i6125nx2rwkg9n6-systemd-252.5-dev/lib/pkgconfig:/nix/store/2gm71c7yljswz2yz3i6125nx2rwkg9n6-systemd-252.5-dev/share/pkgconfig:/nix/store/1p3dv53skl06k4fin8dsravd96ayljia-libXaw-1.0.14-dev/lib/pkgconfig:/nix/store/vrx9hvcqqp8iyfx2dr1p1ih202myi4z7-libXmu-1.1.3-dev/lib/pkgconfig:/nix/store/q2sjb83p9kh7j653237wr5xzsdc17sgj-libX11-1.8.4-dev/lib/pkgconfig:/nix/store/9d1fbfvijywjsxh5b060qy5dd01cqbrs-xorgproto-2021.5/share/pkgconfig:/nix/store/rr353rjxy36vvakib4cyajjj2r3gqw5x-libxcb-1.14-dev/lib/pkgconfig:/nix/store/ij7494rz9pphaslcs288mkyrvj6k7vl4-libXt-1.2.1-dev/lib/pkgconfig:/nix/store/sp4f99w0gwv5mgfr1gr9j75z83v2fp4x-libSM-1.2.3-dev/lib/pkgconfig:/nix/store/23wcgigbj2kjxq214agc4hhgs7x9f4w0-libICE-1.0.10-dev/lib/pkgconfig:/nix/store/pzlc01k3n6512frzjcsrrs31dzrx6fhc-Xaw3d-1.6.3/lib/pkgconfig:/nix/store/p9q8bgh0qav78niqxjbrnzg8x8cwnmbn-cairo-1.16.0-dev/lib/pkgconfig:/nix/store/6bdds6632r9fp7mrh27qxjv90d7lzh0y-fontconfig-2.14.0-dev/lib/pkgconfig:/nix/store/ybd7brnb5kavanvz40mg2p5pmgnczi85-freetype-2.12.1-dev/lib/pkgconfig:/nix/store/abs0rlwm6jh4l1k831fvqggpgfrs91pv-bzip2-1.0.8-dev/lib/pkgconfig:/nix/store/84r63sb6w4l1y1ab3vmk3xg84is027y2-brotli-1.0.9-dev/lib/pkgconfig:/nix/store/463cn57ci7xxwr28c1d68zwbr001ka8h-libpng-apng-1.6.39-dev/lib/pkgconfig:/nix/store/hncbn4imig9h0nacd2j40by7br4d64c3-pixman-0.42.2/lib/pkgconfig:/nix/store/f5blw2z7jr4h2qkzfdmjkwak142353rq-libXext-1.3.4-dev/lib/pkgconfig:/nix/store/jhxfmh0lh0dkk11fpys8350w8hk7ljf7-libXau-1.0.9-dev/lib/pkgconfig:/nix/store/slpgdz4ha0w6y2c25n0ljda4536p9yi4-libXrender-0.9.10-dev/lib/pkgconfig:/nix/store/9qzw3zscs3b4gc97bsaq991iifgz4977-xcb-util-0.4.0-dev/lib/pkgconfig:/nix/store/152gsygyjagsirvdg3icmz4px39wddwj-glib-2.74.5-dev/lib/pkgconfig:/nix/store/4j08mgygxhi9y3957hbwqn1bg02va18y-libffi-3.4.4-dev/lib/pkgconfig:/nix/store/fqwihpqn2wmhjqw251w1r7dyw659abrh-libGL-1.6.0-dev/lib/pkgconfig:/nix/store/y7fpp50b5l7l4g5hk76w2mm2p8jhrwyg-libglvnd-1.6.0-dev/lib/pkgconfig:/nix/store/vwhy21hpsp8b4har28fv9sl4wf1xxxf2-libXpm-3.5.15-dev/lib/pkgconfig:/nix/store/dra1y7qr8clxdssfx5s1grbg2lvg5ifd-libjpeg-turbo-2.1.4-dev/lib/pkgconfig:/nix/store/mgv2qfkir2w084vwlk5ss6pq2x6gh7n3-libtiff-4.5.0-dev/lib/pkgconfig:/nix/store/zfrjyd3s96gzdvnmdw9i3n7mqqcipx3l-xz-5.4.1-dev/lib/pkgconfig:/nix/store/nkk74d97ywap31s3gcnw2a20r23mxyb3-librsvg-2.55.1-dev/lib/pkgconfig:/nix/store/k6ksm1l6b217wcjjx0klkjibc4jns7nh-gdk-pixbuf-2.42.10-dev/lib/pkgconfig:/nix/store/nhz6cbjxjdnbvv06jpmds8vv30fzlhk2-m17n-lib-1.8.0/lib/pkgconfig:/nix/store/3kfnq6nrh0kbcjv4yy2v2srcl2r9f8hj-libotf-0.9.16-dev/lib/pkgconfig:/nix/store/i1h2yf133m4rfzgfgl0zdxjxniyy6kvg-sqlite-3.40.1-dev/lib/pkgconfig:/nix/store/ckvyb7jxzmnvp1pjhm7y871zxwv4m9xq-libwebp-1.3.0/lib/pkgconfig:/nix/store/8mdyxvz3r70b99bpc8z8b81j7lspl8nf-tree-sitter-0.20.7/lib/pkgconfig
 CXX=g++ TREE_SITTER_LIBS=-ltree-sitter'


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Mention-minibuffer-next-completion-in-completion-hel.patch --]
[-- Type: text/patch, Size: 2205 bytes --]

From c361966508e2da159b5e65c37dff7f78e87b3445 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.
---
 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"))))))
 
 (add-hook 'completion-setup-hook #'completion-setup-function)
-- 
2.40.1

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

[Eli Zaretskii]

> 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.

Also, what about updating the documentation?

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

[sbaugh]

[-- Attachment #1: Type: text/plain, Size: 2781 bytes --]

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:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Mention-minibuffer-next-completion-in-completion-hel.patch --]
[-- Type: text/x-patch, Size: 2551 bytes --]

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


[-- Attachment #3: Type: text/plain, Size: 186 bytes --]


> 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.

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

[Eli Zaretskii]

> From: sbaugh@catern.com
> Date: Sun, 02 Jul 2023 19:14:06 +0000 (UTC)
> Cc: 64425@debbugs.gnu.org
> 
> > 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:

OK, I think.

> > 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.

I don't see the additional bindings documented anywhere.
And neither can I find any reference to
minibuffer-{next,previous,choose}-completion.  What did I miss?

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

[Spencer Baugh]

Eli Zaretskii <eliz@gnu.org> writes:
>> From: sbaugh@catern.com
>> Date: Sun, 02 Jul 2023 19:14:06 +0000 (UTC)
>> Cc: 64425@debbugs.gnu.org
>> 
>> > 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:
>
> OK, I think.
>
>> > 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.
>
> I don't see the additional bindings documented anywhere.
> And neither can I find any reference to
> minibuffer-{next,previous,choose}-completion.  What did I miss?

(info "(emacs) Completion Commands") documents M-<DOWN>, M-<UP>,
M-<RET>.

How about this?

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 9bf4da67644..517a6262522 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -393,7 +393,7 @@ Completion Commands
 @vindex minibuffer-completion-auto-choose
 @item M-@key{DOWN}
 @itemx M-@key{UP}
-While in the minibuffer, these keys navigate through the completions
+These keys navigate through the completions
 displayed in the completions buffer.  When
 @code{minibuffer-completion-auto-choose} is non-@code{nil} (which is
 the default), using these commands also inserts the current completion
@@ -410,7 +410,7 @@ Completion Commands
 @itemx @key{prior}
 Typing @kbd{M-v}, while in the minibuffer, selects the window showing
 the completion list (@code{switch-to-completions}).  This paves the
-way for using the commands below.  @key{PageUp}, @key{prior} and
+way for also using the commands below.  @key{PageUp}, @key{prior} and
 @kbd{M-g M-c} does the same.  You can also select the window in other
 ways (@pxref{Windows}).
 

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

[Eli Zaretskii]

> From: Spencer Baugh <sbaugh@janestreet.com>
> Cc: sbaugh@catern.com,  64425@debbugs.gnu.org
> Date: Mon, 03 Jul 2023 08:53:11 -0400
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> >> From: sbaugh@catern.com
> >> Date: Sun, 02 Jul 2023 19:14:06 +0000 (UTC)
> >> Cc: 64425@debbugs.gnu.org
> >> 
> >> > 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:
> >
> > OK, I think.
> >
> >> > 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.
> >
> > I don't see the additional bindings documented anywhere.
> > And neither can I find any reference to
> > minibuffer-{next,previous,choose}-completion.  What did I miss?
> 
> (info "(emacs) Completion Commands") documents M-<DOWN>, M-<UP>,
> M-<RET>.

Ugh, not indexed, and the command names aren't even mentioned...  How
are people supposed to find them?  Now fixed.

> How about this?
> 
> diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
> index 9bf4da67644..517a6262522 100644
> --- a/doc/emacs/mini.texi
> +++ b/doc/emacs/mini.texi
> @@ -393,7 +393,7 @@ Completion Commands
>  @vindex minibuffer-completion-auto-choose
>  @item M-@key{DOWN}
>  @itemx M-@key{UP}
> -While in the minibuffer, these keys navigate through the completions
> +These keys navigate through the completions

I don't understand this change: do you mean that these keys are
available not only in the minibuffer?

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

[Eli Zaretskii]

> Date: Mon, 03 Jul 2023 13:19:27 +0000 (UTC)
> From: Spencer Baugh <sbaugh@catern.com>
> Cc: Spencer Baugh <sbaugh@janestreet.com>, 64425@debbugs.gnu.org
> 
>  > diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi 
>  > index 9bf4da67644..517a6262522 100644 
>  > --- a/doc/emacs/mini.texi 
>  > +++ b/doc/emacs/mini.texi 
>  > @@ -393,7 +393,7 @@ Completion Commands 
>  >  @vindex minibuffer-completion-auto-choose 
>  >  @item M-@key{DOWN} 
>  >  @itemx M-@key{UP} 
>  > -While in the minibuffer, these keys navigate through the completions 
>  > +These keys navigate through the completions 
> 
>  I don't understand this change: do you mean that these keys are 
>  available not only in the minibuffer? 
> 
> Yes, my change adds bindings for them also in the completions buffer. So they can be used identically
> in both places.

Then the manual should say "in the minibuffer and in the completions
buffer".

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

[Spencer Baugh]

[-- Attachment #1: Type: text/plain, Size: 1123 bytes --]

On Mon, Jul 3, 2023, 09:27 Eli Zaretskii <eliz@gnu.org> wrote:

> > Date: Mon, 03 Jul 2023 13:19:27 +0000 (UTC)
> > From: Spencer Baugh <sbaugh@catern.com>
> > Cc: Spencer Baugh <sbaugh@janestreet.com>, 64425@debbugs.gnu.org
> >
> >  > diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
> >  > index 9bf4da67644..517a6262522 100644
> >  > --- a/doc/emacs/mini.texi
> >  > +++ b/doc/emacs/mini.texi
> >  > @@ -393,7 +393,7 @@ Completion Commands
> >  >  @vindex minibuffer-completion-auto-choose
> >  >  @item M-@key{DOWN}
> >  >  @itemx M-@key{UP}
> >  > -While in the minibuffer, these keys navigate through the completions
> >  > +These keys navigate through the completions
> >
> >  I don't understand this change: do you mean that these keys are
> >  available not only in the minibuffer?
> >
> > Yes, my change adds bindings for them also in the completions buffer. So
> they can be used identically
> > in both places.
>
> Then the manual should say "in the minibuffer and in the completions
> buffer
>

They are also available in regular buffers after triggering
completion-at-point. Should we note that too?

>

[-- Attachment #2: Type: text/html, Size: 2028 bytes --]

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

[Eli Zaretskii]

> From: Spencer Baugh <sbaugh@janestreet.com>
> Date: Mon, 3 Jul 2023 09:31:11 -0400
> Cc: Spencer Baugh <sbaugh@catern.com>, 64425@debbugs.gnu.org
> 
> On Mon, Jul 3, 2023, 09:27 Eli Zaretskii <eliz@gnu.org> wrote:
> 
>  > Date: Mon, 03 Jul 2023 13:19:27 +0000 (UTC)
>  > From: Spencer Baugh <sbaugh@catern.com>
>  > Cc: Spencer Baugh <sbaugh@janestreet.com>, 64425@debbugs.gnu.org
>  > 
>  >  > diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi 
>  >  > index 9bf4da67644..517a6262522 100644 
>  >  > --- a/doc/emacs/mini.texi 
>  >  > +++ b/doc/emacs/mini.texi 
>  >  > @@ -393,7 +393,7 @@ Completion Commands 
>  >  >  @vindex minibuffer-completion-auto-choose 
>  >  >  @item M-@key{DOWN} 
>  >  >  @itemx M-@key{UP} 
>  >  > -While in the minibuffer, these keys navigate through the completions 
>  >  > +These keys navigate through the completions 
>  > 
>  >  I don't understand this change: do you mean that these keys are 
>  >  available not only in the minibuffer? 
>  > 
>  > Yes, my change adds bindings for them also in the completions buffer. So they can be used
>  identically
>  > in both places.
> 
>  Then the manual should say "in the minibuffer and in the completions
>  buffer
> 
> They are also available in regular buffers after triggering completion-at-point. Should we note that too?

Yes, but in another place, where completion-at-point is documented.

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

[Spencer Baugh]

[-- Attachment #1: Type: text/plain, Size: 1622 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Spencer Baugh <sbaugh@janestreet.com>
>> Date: Mon, 3 Jul 2023 09:31:11 -0400
>> Cc: Spencer Baugh <sbaugh@catern.com>, 64425@debbugs.gnu.org
>> 
>> On Mon, Jul 3, 2023, 09:27 Eli Zaretskii <eliz@gnu.org> wrote:
>> 
>>  > Date: Mon, 03 Jul 2023 13:19:27 +0000 (UTC)
>>  > From: Spencer Baugh <sbaugh@catern.com>
>>  > Cc: Spencer Baugh <sbaugh@janestreet.com>, 64425@debbugs.gnu.org
>>  > 
>>  >  > diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi 
>>  >  > index 9bf4da67644..517a6262522 100644 
>>  >  > --- a/doc/emacs/mini.texi 
>>  >  > +++ b/doc/emacs/mini.texi 
>>  >  > @@ -393,7 +393,7 @@ Completion Commands 
>>  >  >  @vindex minibuffer-completion-auto-choose 
>>  >  >  @item M-@key{DOWN} 
>>  >  >  @itemx M-@key{UP} 
>>  >  > -While in the minibuffer, these keys navigate through the completions 
>>  >  > +These keys navigate through the completions 
>>  > 
>>  >  I don't understand this change: do you mean that these keys are 
>>  >  available not only in the minibuffer? 
>>  > 
>>  > Yes, my change adds bindings for them also in the completions buffer. So they can be used
>>  identically
>>  > in both places.
>> 
>>  Then the manual should say "in the minibuffer and in the completions
>>  buffer
>> 
>> They are also available in regular buffers after triggering completion-at-point. Should we note that too?
>
> Yes, but in another place, where completion-at-point is documented.

OK, fair enough.  Actually, that part is already done, in (info "(emacs)
Symbol Completion").

So revised patch updating the minibuffer completion documentation:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Mention-minibuffer-next-completion-in-completion-hel.patch --]
[-- Type: text/x-patch, Size: 4203 bytes --]

From 7c6bc1fc940252b65f2d63c98ff2d53f02699091 Mon Sep 17 00:00:00 2001
From: Spencer Baugh <sbaugh@janestreet.com>
Date: Mon, 3 Jul 2023 09:59:04 -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.

* doc/emacs/mini.texi (Completion Commands): Document new bindings.
* 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)
---
 doc/emacs/mini.texi | 12 ++++++------
 lisp/simple.el      | 15 ++++++++++-----
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 9bf4da67644..8281c8cb9d4 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -393,11 +393,11 @@ Completion Commands
 @vindex minibuffer-completion-auto-choose
 @item M-@key{DOWN}
 @itemx M-@key{UP}
-While in the minibuffer, these keys navigate through the completions
-displayed in the completions buffer.  When
-@code{minibuffer-completion-auto-choose} is non-@code{nil} (which is
-the default), using these commands also inserts the current completion
-candidate into the minibuffer.  If
+While in the minibuffer or in the completion list buffer, these keys
+navigate through the completions displayed in the completion list
+buffer.  When @code{minibuffer-completion-auto-choose} is
+non-@code{nil} (which is the default), using these commands also
+inserts the current completion candidate into the minibuffer.  If
 @code{minibuffer-completion-auto-choose} is @code{nil}, you can use
 the @kbd{M-@key{RET}} command to insert the completion candidates into
 the minibuffer.  By default, that exits the minibuffer, but with a
@@ -410,7 +410,7 @@ Completion Commands
 @itemx @key{prior}
 Typing @kbd{M-v}, while in the minibuffer, selects the window showing
 the completion list (@code{switch-to-completions}).  This paves the
-way for using the commands below.  @key{PageUp}, @key{prior} and
+way for also using the commands below.  @key{PageUp}, @key{prior} and
 @kbd{M-g M-c} does the same.  You can also select the window in other
 ways (@pxref{Windows}).
 
diff --git a/lisp/simple.el b/lisp/simple.el
index b6efb06fc27..3513bb82293 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -9670,6 +9670,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)
@@ -10064,11 +10067,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.39.3

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

[Eli Zaretskii]

> From: Spencer Baugh <sbaugh@janestreet.com>
> Cc: sbaugh@catern.com,  64425@debbugs.gnu.org
> Date: Mon, 03 Jul 2023 10:00:01 -0400
> 
> >> They are also available in regular buffers after triggering completion-at-point. Should we note that too?
> >
> > Yes, but in another place, where completion-at-point is documented.
> 
> OK, fair enough.  Actually, that part is already done, in (info "(emacs)
> Symbol Completion").
> 
> So revised patch updating the minibuffer completion documentation:

Thanks, this LGTM, but please don't use 'kbd' in simple.el.  With that
change, we can install this, I think.

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

[Spencer Baugh]

[-- Attachment #1: Type: text/plain, Size: 671 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Spencer Baugh <sbaugh@janestreet.com>
>> Cc: sbaugh@catern.com,  64425@debbugs.gnu.org
>> Date: Mon, 03 Jul 2023 10:00:01 -0400
>> 
>> >> They are also available in regular buffers after triggering completion-at-point. Should we note that too?
>> >
>> > Yes, but in another place, where completion-at-point is documented.
>> 
>> OK, fair enough.  Actually, that part is already done, in (info "(emacs)
>> Symbol Completion").
>> 
>> So revised patch updating the minibuffer completion documentation:
>
> Thanks, this LGTM, but please don't use 'kbd' in simple.el.  With that
> change, we can install this, I think.

Fixed.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Mention-minibuffer-next-completion-in-completion-hel.patch --]
[-- Type: text/x-patch, Size: 3637 bytes --]

From 6724728e4b9608b98052b6690f659a355b2865e6 Mon Sep 17 00:00:00 2001
From: Spencer Baugh <sbaugh@janestreet.com>
Date: Mon, 3 Jul 2023 09:59:04 -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.

* doc/emacs/mini.texi (Completion Commands): Document new bindings.
* 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)
---
 doc/emacs/mini.texi |  4 ++--
 lisp/simple.el      | 15 ++++++++++-----
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index a760ad19f2d..1080c3b6d27 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -399,7 +399,7 @@ Completion Commands
 @findex minibuffer-choose-completion
 @item M-@key{DOWN}
 @itemx M-@key{UP}
-While in the minibuffer, @kbd{M-@key{DOWN}}
+While in the minibuffer or in the completion list buffer, @kbd{M-@key{DOWN}}
 (@code{minibuffer-next-completion} and @kbd{M-@key{UP}}
 (@code{minibuffer-previous-completion}) navigate through the
 completions and displayed in the completions buffer.  When
@@ -419,7 +419,7 @@ Completion Commands
 @itemx @key{prior}
 Typing @kbd{M-v}, while in the minibuffer, selects the window showing
 the completion list (@code{switch-to-completions}).  This paves the
-way for using the commands below.  @key{PageUp}, @key{prior} and
+way for also using the commands below.  @key{PageUp}, @key{prior} and
 @kbd{M-g M-c} does the same.  You can also select the window in other
 ways (@pxref{Windows}).
 
diff --git a/lisp/simple.el b/lisp/simple.el
index 406f1008df3..2b1a015f517 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 [M-up] 'minibuffer-previous-completion)
+    (define-key map [M-down] 'minibuffer-next-completion)
+    (define-key map "\M-\r" '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.39.3

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

[Eli Zaretskii]

> From: Spencer Baugh <sbaugh@janestreet.com>
> Cc: sbaugh@catern.com,  64425@debbugs.gnu.org
> Date: Thu, 06 Jul 2023 09:00:24 -0400
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Spencer Baugh <sbaugh@janestreet.com>
> >> Cc: sbaugh@catern.com,  64425@debbugs.gnu.org
> >> Date: Mon, 03 Jul 2023 10:00:01 -0400
> >> 
> >> >> They are also available in regular buffers after triggering completion-at-point. Should we note that too?
> >> >
> >> > Yes, but in another place, where completion-at-point is documented.
> >> 
> >> OK, fair enough.  Actually, that part is already done, in (info "(emacs)
> >> Symbol Completion").
> >> 
> >> So revised patch updating the minibuffer completion documentation:
> >
> > Thanks, this LGTM, but please don't use 'kbd' in simple.el.  With that
> > change, we can install this, I think.
> 
> Fixed.

Thanks, installed on the master branch, and closing the bug.

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

[Eli Zaretskii]

> Date: Sat, 08 Jul 2023 11:36:44 +0000 (UTC)
> From: Spencer Baugh <sbaugh@catern.com>
> Cc: Spencer Baugh <sbaugh@janestreet.com>, 64425-done@debbugs.gnu.org
> 
> What about on emacs-29? Since this documents a feature new in that release.

It isn't only a documentation change.  It requires changes in key
bindings and in simple.el.  Sorry, too late for that.