bug#74616: 30.0.92; tmm always displays the *Completions* buffer

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Daniel Mendler via Bug reports for GNU Emacs, the Swiss army knife of text editors]

The `tmm-add-prompt' function of tmm.el automatically displays the
*Completions* buffer by calling `minibuffer-completion-help'. If an
alternative minibuffer completion system like Icomplete or Vertico is
used, the *Completions* buffer is not needed since the candidates are
already displayed in the minibuffer. I propose to either detect these
alternative completion systems (e.g., by checking the value of the
completing-read-function and/or the mode variables) or to provide a new
customization variable `tmm-display-completions' which defaults to t but
can be set to nil to disable the call to `minibuffer-completion-help'. I
am happy to provide a patch for either of these approaches.

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Eli Zaretskii]

> Cc: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Sat, 30 Nov 2024 07:42:33 +0100
> From:  Daniel Mendler via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> The `tmm-add-prompt' function of tmm.el automatically displays the
> *Completions* buffer by calling `minibuffer-completion-help'. If an
> alternative minibuffer completion system like Icomplete or Vertico is
> used, the *Completions* buffer is not needed since the candidates are
> already displayed in the minibuffer. I propose to either detect these
> alternative completion systems (e.g., by checking the value of the
> completing-read-function and/or the mode variables) or to provide a new
> customization variable `tmm-display-completions' which defaults to t but
> can be set to nil to disable the call to `minibuffer-completion-help'. I
> am happy to provide a patch for either of these approaches.

I think the automatic detection is a better default behavior, but
maybe we could have a variable (not necessarily a defcustom) for users
who would like to have the old behavior.

Stefan, WDYT?

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Daniel Mendler via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: Stefan Monnier <monnier@iro.umontreal.ca>
>> Date: Sat, 30 Nov 2024 07:42:33 +0100
>> From:  Daniel Mendler via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> 
>> The `tmm-add-prompt' function of tmm.el automatically displays the
>> *Completions* buffer by calling `minibuffer-completion-help'. If an
>> alternative minibuffer completion system like Icomplete or Vertico is
>> used, the *Completions* buffer is not needed since the candidates are
>> already displayed in the minibuffer. I propose to either detect these
>> alternative completion systems (e.g., by checking the value of the
>> completing-read-function and/or the mode variables) or to provide a new
>> customization variable `tmm-display-completions' which defaults to t but
>> can be set to nil to disable the call to `minibuffer-completion-help'. I
>> am happy to provide a patch for either of these approaches.
>
> I think the automatic detection is a better default behavior, but
> maybe we could have a variable (not necessarily a defcustom) for users
> who would like to have the old behavior.

See also what I wrote on my ffap bug report. It may make sense to
provide some more general mechanism (auto detection, custom variable,
...) in minibuffer.el which could be used by tmm, ffap and other
packages. For example my GNU ELPA package Jinx faces the same problem -
if default completion is used, `minibuffer-completion-help' should be
called to display the candidates immediately, but not for other
completion UIs.

> Stefan, WDYT?

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> I think the automatic detection is a better default behavior, but
> maybe we could have a variable (not necessarily a defcustom) for users
> who would like to have the old behavior.
> Stefan, WDYT?

I often use the standard UI and I generally don't like this eagerness to
display *Completions*, so I'd either change the code not to auto-display
the buffer (what I have done locally) or at least offer a variable
for that.

So it seems like the war should have 3 settings: always show, never
show, and "guess" (tho maybe we can skip the "guess" option and let the
other completion UIs set the var to nil).


        Stefan

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Sean Whitton]

Hello,

On Sat 30 Nov 2024 at 01:55pm -05, Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" wrote:

> I often use the standard UI and I generally don't like this eagerness to
> display *Completions*, so I'd either change the code not to auto-display
> the buffer (what I have done locally) or at least offer a variable
> for that.

"eagerness to display *Completions*" made me think of this NEWS.30 entry
which is a stopgap compatibility fix that we'd like to improve:

    +++
    ** The "*Completions*" buffer now always accompanies 'icomplete-in-buffer'.
    Previously, it was not consistent whether the "*Completions*" buffer would
    appear when using 'icomplete-in-buffer'.  Now the "*Completions*" buffer
    and Icomplete's in-buffer display of possible completions always
    appear together.  If you would prefer to see only Icomplete's
    in-buffer display, and not the "*Completions*" buffer, you can add this
    to your init file:

        (advice-add 'completion-at-point :after #'minibuffer-hide-completions)

Possibly the resolution of this bug could help there, too.

-- 
Sean Whitton

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Daniel Mendler <mail@daniel-mendler.de>,  74616@debbugs.gnu.org
> Date: Sat, 30 Nov 2024 13:55:02 -0500
> 
> > I think the automatic detection is a better default behavior, but
> > maybe we could have a variable (not necessarily a defcustom) for users
> > who would like to have the old behavior.
> > Stefan, WDYT?
> 
> I often use the standard UI and I generally don't like this eagerness to
> display *Completions*, so I'd either change the code not to auto-display
> the buffer (what I have done locally) or at least offer a variable
> for that.
> 
> So it seems like the var should have 3 settings: always show, never
> show, and "guess" (tho maybe we can skip the "guess" option and let the
> other completion UIs set the var to nil).

Daniel, would you like to submit the patch with these changes?

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Daniel Mendler via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Cc: Daniel Mendler <mail@daniel-mendler.de>,  74616@debbugs.gnu.org
>> Date: Sat, 30 Nov 2024 13:55:02 -0500
>> 
>> > I think the automatic detection is a better default behavior, but
>> > maybe we could have a variable (not necessarily a defcustom) for users
>> > who would like to have the old behavior.
>> > Stefan, WDYT?
>> 
>> I often use the standard UI and I generally don't like this eagerness to
>> display *Completions*, so I'd either change the code not to auto-display
>> the buffer (what I have done locally) or at least offer a variable
>> for that.
>> 
>> So it seems like the var should have 3 settings: always show, never
>> show, and "guess" (tho maybe we can skip the "guess" option and let the
>> other completion UIs set the var to nil).
>
> Daniel, would you like to submit the patch with these changes?

So is the plan to add a completion metadata `eager-display' such that
completion tables can request immediate display? This completion
metadata can then be overridden by the user via
`completion-category-overrides'. The patch would include changes to tmm,
ffap-menu and imenu (obsoleting `imenu-eager-completion-buffer').

Daniel

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Eli Zaretskii]

> From: Daniel Mendler <mail@daniel-mendler.de>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  74616@debbugs.gnu.org
> Date: Sat, 07 Dec 2024 15:38:14 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Stefan Monnier <monnier@iro.umontreal.ca>
> >> Cc: Daniel Mendler <mail@daniel-mendler.de>,  74616@debbugs.gnu.org
> >> Date: Sat, 30 Nov 2024 13:55:02 -0500
> >> 
> >> > I think the automatic detection is a better default behavior, but
> >> > maybe we could have a variable (not necessarily a defcustom) for users
> >> > who would like to have the old behavior.
> >> > Stefan, WDYT?
> >> 
> >> I often use the standard UI and I generally don't like this eagerness to
> >> display *Completions*, so I'd either change the code not to auto-display
> >> the buffer (what I have done locally) or at least offer a variable
> >> for that.
> >> 
> >> So it seems like the var should have 3 settings: always show, never
> >> show, and "guess" (tho maybe we can skip the "guess" option and let the
> >> other completion UIs set the var to nil).
> >
> > Daniel, would you like to submit the patch with these changes?
> 
> So is the plan to add a completion metadata `eager-display' such that
> completion tables can request immediate display? This completion
> metadata can then be overridden by the user via
> `completion-category-overrides'. The patch would include changes to tmm,
> ffap-menu and imenu (obsoleting `imenu-eager-completion-buffer').

AFAIU, both Stefan and myself only commented on the more specific
change you suggested originally, not the more general one you
described in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74616#11

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Daniel Mendler via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Daniel Mendler <mail@daniel-mendler.de>
>> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  74616@debbugs.gnu.org
>> Date: Sat, 07 Dec 2024 15:38:14 +0100
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> >> Cc: Daniel Mendler <mail@daniel-mendler.de>,  74616@debbugs.gnu.org
>> >> Date: Sat, 30 Nov 2024 13:55:02 -0500
>> >> 
>> >> > I think the automatic detection is a better default behavior, but
>> >> > maybe we could have a variable (not necessarily a defcustom) for users
>> >> > who would like to have the old behavior.
>> >> > Stefan, WDYT?
>> >> 
>> >> I often use the standard UI and I generally don't like this eagerness to
>> >> display *Completions*, so I'd either change the code not to auto-display
>> >> the buffer (what I have done locally) or at least offer a variable
>> >> for that.
>> >> 
>> >> So it seems like the var should have 3 settings: always show, never
>> >> show, and "guess" (tho maybe we can skip the "guess" option and let the
>> >> other completion UIs set the var to nil).
>> >
>> > Daniel, would you like to submit the patch with these changes?
>> 
>> So is the plan to add a completion metadata `eager-display' such that
>> completion tables can request immediate display? This completion
>> metadata can then be overridden by the user via
>> `completion-category-overrides'. The patch would include changes to tmm,
>> ffap-menu and imenu (obsoleting `imenu-eager-completion-buffer').
>
> AFAIU, both Stefan and myself only commented on the more specific
> change you suggested originally, not the more general one you
> described in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74616#11

Okay, I see. Is there interest in a general solution for all the
scenarios, instead of replicating customization variables multiple
times? Then users like Stefan who don't like the eager display, or
completion UIs would only have to customize a single variable once.

If a customization variable is preferred over the completion metadata,
one could add a `minibuffer-eager-completion-help-function function
to minibuffer.el (please make suggestions for a better name):

(defcustom minibuffer-eager-completion-help-function #'minibuffer-completion-help
  "Can be set to `minibuffer-completion-help' to show the eager display,
to `ignore' to disable the eager display, or to a custom function which
performs auto detection."
  ...)

It would be used like this at the call sites (imenu, ffap, tmm):

(minibuffer-with-setup-hook
    minibuffer-eager-completion-help-function
  (completing-read ...))

Daniel

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> So is the plan to add a completion metadata `eager-display' such that
> completion tables can request immediate display? This completion
> metadata can then be overridden by the user via
> `completion-category-overrides'. The patch would include changes to tmm,
> ffap-menu and imenu (obsoleting `imenu-eager-completion-buffer').

That sounds good, except that in order for
`completion-category-overrides` to work reliably, the `eager-display`
should not be in the metadata but in `completion-category-defaults`.


        Stefan

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Daniel Mendler via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> So is the plan to add a completion metadata `eager-display' such that
>> completion tables can request immediate display? This completion
>> metadata can then be overridden by the user via
>> `completion-category-overrides'. The patch would include changes to tmm,
>> ffap-menu and imenu (obsoleting `imenu-eager-completion-buffer').
>
> That sounds good, except that in order for
> `completion-category-overrides` to work reliably, the `eager-display`
> should not be in the metadata but in `completion-category-defaults`.

Okay. Can you please clarify why you assume that overriding isn't
reliably possible if the metadata is specified directly? In
`completion-metadata-get' the `completion-category-defaults' and
`completion-category-overrides' take precedence over the completion
table metadata.

I attached a patch which adds a customization option
`completion-eager-display' and an `eager-display' completion table
metadata. The customization option can be set to nil (never), t (always)
or to auto, which means that the *Completions* buffer will only be shown
if the completion table requests eager display via the `eager-display'
metadata.

I updated ffap.el, tmm.el and imenu.el to take advantage of the new
`eager-display' metadata. I added completion categories where missing
such that overriding the metadata becomes possible. If desired, the
metadata can be moved to `completion-category-defaults' instead.

Daniel


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-customization-variable-completion-eager-display.patch --]
[-- Type: text/x-diff, Size: 14047 bytes --]

From 2a4f2c04a880c6a66207a0717f5ba79bbfe109ef Mon Sep 17 00:00:00 2001
From: Daniel Mendler <mail@daniel-mendler.de>
Date: Sun, 8 Dec 2024 20:05:07 +0100
Subject: [PATCH] New customization variable `completion-eager-display'

The customization option can be set to t or nil, to respectively
always or never show the *Completions* buffer eagerly at the
beginning of a completion session.  Furthermore the option can
be set to the value auto.  In this case the *Completions* buffer
will only be shown if requested by the completion table.
Completion tables can use the `eager-display' completion
metadata to do so.

* lisp/minibuffer.el (completion-eager-display): New
customization variable.
(completion-metadata): Update docstring, document the
new `eager-display' completion metadata.
(completion-extra-properties): Update docstring, document the
new `:eager-display' completion metadata.
(completing-read-default): Handle the `completion-eager-display'
customization variable and the `eager-display' completion
metadata.
(completion-table-with-metadata): New function to create
a completion table with metadata.
(minibuffer-complete-defaults, minibuffer-complete-history):
Use it.
* lisp/ffap.el (ffap-menu-ask): Add `ffap-menu' completion
category and `eager-display' completion metadata.  Use
`completion-table-with-metadata'.
* lisp/imenu.el (imenu-eager-completion-buffer): Correct
docstring, which had been inverted.
(imenu--completion-buffer): Add `eager-display' completion
metadata.  Use `completion-table-with-metadata'.
* lisp/tmm.el (tmm-prompt): Add `tmm' completion category and
`eager-display' completion metadata.  Use
`completion-table-with-metadata'.
(tmm-goto-completions): Ensure that a *Completions* buffer is
available.
(tmm--completion-table): Remove unused internal function.
---
 lisp/ffap.el       | 17 ++++++++-------
 lisp/imenu.el      | 40 ++++++++++++++++------------------
 lisp/minibuffer.el | 54 ++++++++++++++++++++++++++++++++++++----------
 lisp/tmm.el        | 38 ++++++++++++++++----------------
 4 files changed, 90 insertions(+), 59 deletions(-)

diff --git a/lisp/ffap.el b/lisp/ffap.el
index 6a4915fb5a3..c869e234140 100644
--- a/lisp/ffap.el
+++ b/lisp/ffap.el
@@ -1738,14 +1738,15 @@ ffap-menu-ask
 				    alist))))))
      ;; minibuffer with completion buffer:
      (t
-      (let ((minibuffer-setup-hook 'minibuffer-completion-help))
-	;; Bug: prompting may assume unique strings, no "".
-	(setq choice
-	      (completing-read
-	       (format-prompt title (car (car alist)))
-	       alist nil t
-	       ;; (cons (car (car alist)) 0)
-	       nil)))
+      ;; Bug: prompting may assume unique strings, no "".
+      (setq choice
+	    (completing-read
+	     (format-prompt title (car (car alist)))
+             (completion-table-with-metadata
+	      alist '((category . ffap-menu) (eager-display . t)))
+             nil t
+	     ;; (cons (car (car alist)) 0)
+	     nil))
       (sit-for 0)			; redraw original screen
       ;; Convert string to its entry, or else the default:
       (setq choice (or (assoc choice alist) (car alist)))))
diff --git a/lisp/imenu.el b/lisp/imenu.el
index 2d64970bfcf..ba1ba5fcd00 100644
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -100,7 +100,7 @@ imenu-use-popup-menu
                  (other :tag "Always" t)))
 
 (defcustom imenu-eager-completion-buffer t
-  "If non-nil, eagerly pop up the completion buffer."
+  "If nil, eagerly pop up the completion buffer."
   :type 'boolean
   :version "22.1")
 
@@ -767,27 +767,25 @@ imenu--completion-buffer
                          (imenu--in-alist name prepared-index-alist)
                          ;; Default to `name' if it's in the alist.
                          name))))
-    ;; Display the completion buffer.
     (minibuffer-with-setup-hook
-        (lambda ()
-          (setq-local minibuffer-allow-text-properties t)
-          (setq-local completion-extra-properties
-                      `( :category imenu
-                         ,@(when (eq imenu-flatten 'annotation)
-                             `(:annotation-function
-                               ,(lambda (s) (get-text-property
-                                             0 'imenu-section s))))
-                         ,@(when (eq imenu-flatten 'group)
-                             `(:group-function
-                               ,(lambda (s transform)
-                                  (if transform s
-                                    (get-text-property
-                                     0 'imenu-section s)))))))
-          (unless imenu-eager-completion-buffer
-            (minibuffer-completion-help)))
-      (setq name (completing-read prompt
-				  prepared-index-alist
-				  nil t nil 'imenu--history-list name)))
+        (lambda () (setq-local minibuffer-allow-text-properties t))
+      (setq name (completing-read
+                  prompt
+                  (completion-table-with-metadata
+		   prepared-index-alist
+                   `((category . imenu)
+                     (eager-display . ,(not imenu-eager-completion-buffer))
+                     ,@(when (eq imenu-flatten 'annotation)
+                         `((annotation-function
+                            . ,(lambda (s) (get-text-property
+                                            0 'imenu-section s)))))
+                     ,@(when (eq imenu-flatten 'group)
+                         `((group-function
+                            . ,(lambda (s transform)
+                                 (if transform s
+                                   (get-text-property
+                                    0 'imenu-section s))))))))
+		  nil t nil 'imenu--history-list name)))
 
     (when (stringp name)
       (or (get-text-property 0 'imenu-choice name)
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 405ee21cdb2..1dfe450a35c 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -138,6 +138,9 @@ completion-metadata
    of completions.  Can operate destructively.
 - `cycle-sort-function': function to sort entries when cycling.
    Works like `display-sort-function'.
+- `eager-display': non-nil to request eager display of the
+  completion candidates.  Can also be a function which is invoked
+  after minibuffer setup.
 The metadata of a completion table should be constant between two boundaries."
   (let ((metadata (if (functionp table)
                       (funcall table string pred 'metadata))))
@@ -277,6 +280,15 @@ completion-table-case-fold
     (let ((completion-ignore-case (not dont-fold)))
       (complete-with-action action table string pred))))
 
+(defun completion-table-with-metadata (table metadata)
+  "Return new completion TABLE with METADATA.
+METADATA should be an alist of completion metadata.  See
+`completion-metadata' for a list of supported metadata."
+  (lambda (string pred action)
+    (if (eq action 'metadata)
+        `(metadata . ,metadata)
+      (complete-with-action action table string pred))))
+
 (defun completion-table-subvert (table s1 s2)
   "Return a completion table from TABLE with S1 replaced by S2.
 The result is a completion table which completes strings of the
@@ -1031,6 +1043,18 @@ minibuffer--completion-prompt-end
 (defvar completion-show-inline-help t
   "If non-nil, print helpful inline messages during completion.")
 
+(defcustom completion-eager-display 'auto
+  "Display the *Completions* buffer eagerly.
+
+If the variable is set to t or nil, respectively show the *Completions*
+buffer always or never eagerly.  The value `auto' shows the
+*Completions* buffer eagerly only if requested by the completion
+command.  Completion tables can request eager display via the
+`eager-display' metadata."
+  :type '(choice (const :tag "Never show *Completions* eagerly" nil)
+                 (const :tag "Always show *Completions* eagerly" t)
+                 (const :tag "If requested by the completion command" auto)))
+
 (defcustom completion-auto-help t
   "Non-nil means automatically provide help for invalid completion input.
 If the value is t, the *Completions* buffer is displayed whenever completion
@@ -2493,6 +2517,8 @@ completion-extra-properties
 
 `:cycle-sort-function': Function to sort entries when cycling.
 
+`:eager-display': Show the *Completions* buffer eagerly.
+
 See more information about these functions above
 in `completion-metadata'.
 
@@ -4809,7 +4835,17 @@ completing-read-default
                 (setq-local minibuffer--require-match require-match)
                 (setq-local minibuffer--original-buffer buffer)
                 ;; Copy the value from original buffer to the minibuffer.
-                (setq-local completion-ignore-case c-i-c))
+                (setq-local completion-ignore-case c-i-c)
+                ;; Show the completion help eagerly if
+                ;; `completion-eager-display' is t or if eager display
+                ;; has been requested by the completion table.
+                (when completion-eager-display
+                  (let* ((md (completion-metadata
+                              initial-input collection predicate))
+                         (fun (completion-metadata-get md 'eager-display)))
+                    (when (or fun (eq completion-eager-display t))
+                      (funcall (if (functionp fun)
+                                   fun #'minibuffer-completion-help))))))
             (read-from-minibuffer prompt initial-input keymap
                                   nil hist def inherit-input-method))))
     (when (and (equal result "") def)
@@ -4999,11 +5035,9 @@ minibuffer-complete-history
            (lambda () (get-buffer-window "*Completions*" 0))))
       (completion-in-region
        (minibuffer--completion-prompt-end) (point-max)
-       (lambda (string pred action)
-         (if (eq action 'metadata)
-             '(metadata (display-sort-function . identity)
-                        (cycle-sort-function . identity))
-           (complete-with-action action completions string pred)))))))
+       (completion-table-with-metadata
+        completions '((display-sort-function . identity)
+                      (cycle-sort-function . identity)))))))
 
 (defun minibuffer-complete-defaults ()
   "Complete minibuffer defaults as far as possible.
@@ -5019,11 +5053,9 @@ minibuffer-complete-defaults
          (lambda () (get-buffer-window "*Completions*" 0))))
     (completion-in-region
      (minibuffer--completion-prompt-end) (point-max)
-     (lambda (string pred action)
-       (if (eq action 'metadata)
-           '(metadata (display-sort-function . identity)
-                      (cycle-sort-function . identity))
-         (complete-with-action action completions string pred))))))
+     (completion-table-with-metadata
+      completions '((display-sort-function . identity)
+                    (cycle-sort-function . identity))))))
 
 (define-key minibuffer-local-map [?\C-x up] 'minibuffer-complete-history)
 (define-key minibuffer-local-map [?\C-x down] 'minibuffer-complete-defaults)
diff --git a/lisp/tmm.el b/lisp/tmm.el
index 632e55e47a8..01912916a6d 100644
--- a/lisp/tmm.el
+++ b/lisp/tmm.el
@@ -119,12 +119,6 @@ tmm-inactive
   '((t :inherit shadow))
   "Face used for inactive menu items.")
 
-(defun tmm--completion-table (items)
-  (lambda (string pred action)
-    (if (eq action 'metadata)
-	'(metadata (display-sort-function . identity))
-      (complete-with-action action items string pred))))
-
 (defvar tmm--history nil)
 
 ;;;###autoload
@@ -222,19 +216,23 @@ tmm-prompt
              (setq out
                    (if default-item
                        (car (nth index-of-default tmm-km-list))
-                     (minibuffer-with-setup-hook #'tmm-add-prompt
-                       ;; tmm-km-list is reversed, because history
-                       ;; needs it in LIFO order.  But default list
-                       ;; needs it in non-reverse order, so that the
-                       ;; menu items are displayed by M-n as default
-                       ;; values in the order they are shown on
-                       ;; the menu bar.  So pass the DEFAULT arg the
-                       ;; reversed copy of the list.
-                       (completing-read-default
-                        (concat gl-str
-                                " (up/down to change, PgUp to menu): ")
-                        (tmm--completion-table tmm-km-list) nil t nil
-                        'tmm--history (reverse tmm--history)))))))
+                     ;; tmm-km-list is reversed, because history
+                     ;; needs it in LIFO order.  But default list
+                     ;; needs it in non-reverse order, so that the
+                     ;; menu items are displayed by M-n as default
+                     ;; values in the order they are shown on
+                     ;; the menu bar.  So pass the DEFAULT arg the
+                     ;; reversed copy of the list.
+                     (completing-read-default
+                      (concat gl-str
+                              " (up/down to change, PgUp to menu): ")
+                      (completion-table-with-metadata
+                       tmm-km-list '((category . tmm)
+                                     (eager-display . tmm-add-prompt)
+                                     (display-sort-function . identity)
+                                     (cycle-sort-function . identity)))
+                      nil t nil
+                      'tmm--history (reverse tmm--history))))))
       (if (and (stringp out) (string= "^" out))
           ;; A fake choice to please the destructuring later.
           (setq choice (cons out out))
@@ -458,6 +456,8 @@ tmm-shortcut
 (defun tmm-goto-completions ()
   "Jump to the completions buffer."
   (interactive)
+  (unless (get-buffer "*Completions*")
+    (minibuffer-completion-help))
   (setq tmm-c-prompt (buffer-substring (minibuffer-prompt-end) (point-max)))
   ;; Clear minibuffer old contents before using *Completions* buffer for
   ;; selection.
-- 
2.45.2

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> Okay. Can you please clarify why you assume that overriding isn't
> reliably possible if the metadata is specified directly?

Because `completion-category-overrides` works only if there's an
appropriate `category` to use.  If the `eager-display` info comes
straight from the metadata, there's no guarantee that there's
an associated `category` info that can be used.


        Stefan

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Daniel Mendler via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Okay. Can you please clarify why you assume that overriding isn't
>> reliably possible if the metadata is specified directly?
>
> Because `completion-category-overrides` works only if there's an
> appropriate `category` to use.  If the `eager-display` info comes
> straight from the metadata, there's no guarantee that there's
> an associated `category` info that can be used.

I've added both completion categories and eager-display. Please see the
attached patch. As soon as there is a completion category, overriding
will work. While the completion category is a necessary prerequisite to
support overriding, adding eager-display at either places should do.
Also note the addition of the completion-eager-display defcustom (with
values nil, t, auto), which will make it much easier to turn off eager
display globally.

Daniel

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Eli Zaretskii]

> From: Daniel Mendler <mail@daniel-mendler.de>
> Cc: Eli Zaretskii <eliz@gnu.org>,  74616@debbugs.gnu.org,  Juri Linkov
>  <juri@linkov.net>
> Date: Mon, 09 Dec 2024 15:44:08 +0100
> 
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
> 
> >> Okay. Can you please clarify why you assume that overriding isn't
> >> reliably possible if the metadata is specified directly?
> >
> > Because `completion-category-overrides` works only if there's an
> > appropriate `category` to use.  If the `eager-display` info comes
> > straight from the metadata, there's no guarantee that there's
> > an associated `category` info that can be used.
> 
> I've added both completion categories and eager-display. Please see the
> attached patch.

ENOPATCH

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Daniel Mendler via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Daniel Mendler <mail@daniel-mendler.de>
>> Cc: Eli Zaretskii <eliz@gnu.org>,  74616@debbugs.gnu.org,  Juri Linkov
>>  <juri@linkov.net>
>> Date: Mon, 09 Dec 2024 15:44:08 +0100
>> 
>> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> 
>> >> Okay. Can you please clarify why you assume that overriding isn't
>> >> reliably possible if the metadata is specified directly?
>> >
>> > Because `completion-category-overrides` works only if there's an
>> > appropriate `category` to use.  If the `eager-display` info comes
>> > straight from the metadata, there's no guarantee that there's
>> > an associated `category` info that can be used.
>> 
>> I've added both completion categories and eager-display. Please see the
>> attached patch.
>
> ENOPATCH

https://debbugs.gnu.org/cgi/bugreport.cgi?msg=35;bug=74616

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Juri Linkov]

> I attached a patch which adds a customization option
> `completion-eager-display' and an `eager-display' completion table
> metadata. The customization option can be set to nil (never), t (always)
> or to auto, which means that the *Completions* buffer will only be shown
> if the completion table requests eager display via the `eager-display'
> metadata.
>
> I updated ffap.el, tmm.el and imenu.el to take advantage of the new
> `eager-display' metadata. I added completion categories where missing
> such that overriding the metadata becomes possible. If desired, the
> metadata can be moved to `completion-category-defaults' instead.

Thanks, I tested everything, and it works nicely.

One small detail that could be added later is to extend
the customization type of `completion-category-overrides'
:value-type with `eager-display'.  Since currently
only programmatic use is supported.

Also tried to do:

  (add-to-list 'completion-category-overrides
               '(tmm (eager-display . nil)))

but after typing TAB it pops up the completion buffer
where all functionality is lost.  Is this because
`tmm-add-prompt' is called only for non-nil `eager-display'?

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Daniel Mendler via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Juri Linkov <juri@linkov.net> writes:

>> I attached a patch which adds a customization option
>> `completion-eager-display' and an `eager-display' completion table
>> metadata. The customization option can be set to nil (never), t (always)
>> or to auto, which means that the *Completions* buffer will only be shown
>> if the completion table requests eager display via the `eager-display'
>> metadata.
>>
>> I updated ffap.el, tmm.el and imenu.el to take advantage of the new
>> `eager-display' metadata. I added completion categories where missing
>> such that overriding the metadata becomes possible. If desired, the
>> metadata can be moved to `completion-category-defaults' instead.
>
> Thanks, I tested everything, and it works nicely.

Thanks for testing!

> One small detail that could be added later is to extend
> the customization type of `completion-category-overrides'
> :value-type with `eager-display'.  Since currently
> only programmatic use is supported.

Okay, I will add this to to custom type.

> Also tried to do:
>
>   (add-to-list 'completion-category-overrides
>                '(tmm (eager-display . nil)))
>
> but after typing TAB it pops up the completion buffer
> where all functionality is lost.  Is this because
> `tmm-add-prompt' is called only for non-nil `eager-display'?

I see. The keymap is not set up properly anymore if
`tmm-add-prompt' is disabled. I will add a fix.

Daniel

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Daniel Mendler via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

Juri Linkov <juri@linkov.net> writes:

>> I attached a patch which adds a customization option
>> `completion-eager-display' and an `eager-display' completion table
>> metadata. The customization option can be set to nil (never), t (always)
>> or to auto, which means that the *Completions* buffer will only be shown
>> if the completion table requests eager display via the `eager-display'
>> metadata.
>>
>> I updated ffap.el, tmm.el and imenu.el to take advantage of the new
>> `eager-display' metadata. I added completion categories where missing
>> such that overriding the metadata becomes possible. If desired, the
>> metadata can be moved to `completion-category-defaults' instead.
>
> Thanks, I tested everything, and it works nicely.
>
> One small detail that could be added later is to extend
> the customization type of `completion-category-overrides'
> :value-type with `eager-display'.  Since currently
> only programmatic use is supported.
>
> Also tried to do:
>
>   (add-to-list 'completion-category-overrides
>                '(tmm (eager-display . nil)))
>
> but after typing TAB it pops up the completion buffer
> where all functionality is lost.  Is this because
> `tmm-add-prompt' is called only for non-nil `eager-display'?

See the new patch which I've attached to this mail, with the two
improvements.

Daniel


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-customization-variable-completion-eager-display.patch --]
[-- Type: text/x-diff, Size: 14311 bytes --]

From 274bfcc7ddb64cd18b214d0884d985ebde2d6c70 Mon Sep 17 00:00:00 2001
From: Daniel Mendler <mail@daniel-mendler.de>
Date: Sun, 8 Dec 2024 20:05:07 +0100
Subject: [PATCH] New customization variable `completion-eager-display'

The customization option can be set to t or nil, to respectively
always or never show the *Completions* buffer eagerly at the
beginning of a completion session.  Furthermore the option can
be set to the value auto.  In this case the *Completions* buffer
will only be shown if requested by the completion table.
Completion tables can use the `eager-display' completion
metadata to do so.

* lisp/minibuffer.el (completion-eager-display): New
customization variable.
(completion-metadata): Update docstring, document the
new `eager-display' completion metadata.
(completion-extra-properties): Update docstring, document the
new `:eager-display' completion metadata.
(completion-category-overrides): Add `eager-display' to the
custom type specification.
(completing-read-default): Handle the `completion-eager-display'
customization variable and the `eager-display' completion
metadata.
(completion-table-with-metadata): New function to create
a completion table with metadata.
(minibuffer-complete-defaults, minibuffer-complete-history):
Use it.
* lisp/ffap.el (ffap-menu-ask): Add `ffap-menu' completion
category and `eager-display' completion metadata.  Use
`completion-table-with-metadata'.
* lisp/imenu.el (imenu-eager-completion-buffer): Correct
docstring, which had been inverted.
(imenu--completion-buffer): Add `eager-display' completion
metadata.  Use `completion-table-with-metadata'.
* lisp/tmm.el (tmm-prompt): Add `tmm' completion category and
`eager-display' completion metadata.  Use
`completion-table-with-metadata'.  Add keymap setup.
(tmm-add-prompt): Remove keymap setup.
(tmm-goto-completions): Call `tmm-add-prompt' to ensure that a
*Completions* buffer is shown.
(tmm--completion-table): Remove unused internal function.
---
 lisp/ffap.el       | 17 ++++++-------
 lisp/imenu.el      | 40 +++++++++++++++----------------
 lisp/minibuffer.el | 60 ++++++++++++++++++++++++++++++++++++----------
 lisp/tmm.el        | 19 ++++++++-------
 4 files changed, 86 insertions(+), 50 deletions(-)

diff --git a/lisp/ffap.el b/lisp/ffap.el
index 6a4915fb5a3..c869e234140 100644
--- a/lisp/ffap.el
+++ b/lisp/ffap.el
@@ -1738,14 +1738,15 @@ ffap-menu-ask
 				    alist))))))
      ;; minibuffer with completion buffer:
      (t
-      (let ((minibuffer-setup-hook 'minibuffer-completion-help))
-	;; Bug: prompting may assume unique strings, no "".
-	(setq choice
-	      (completing-read
-	       (format-prompt title (car (car alist)))
-	       alist nil t
-	       ;; (cons (car (car alist)) 0)
-	       nil)))
+      ;; Bug: prompting may assume unique strings, no "".
+      (setq choice
+	    (completing-read
+	     (format-prompt title (car (car alist)))
+             (completion-table-with-metadata
+	      alist '((category . ffap-menu) (eager-display . t)))
+             nil t
+	     ;; (cons (car (car alist)) 0)
+	     nil))
       (sit-for 0)			; redraw original screen
       ;; Convert string to its entry, or else the default:
       (setq choice (or (assoc choice alist) (car alist)))))
diff --git a/lisp/imenu.el b/lisp/imenu.el
index 2d64970bfcf..ba1ba5fcd00 100644
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -100,7 +100,7 @@ imenu-use-popup-menu
                  (other :tag "Always" t)))
 
 (defcustom imenu-eager-completion-buffer t
-  "If non-nil, eagerly pop up the completion buffer."
+  "If nil, eagerly pop up the completion buffer."
   :type 'boolean
   :version "22.1")
 
@@ -767,27 +767,25 @@ imenu--completion-buffer
                          (imenu--in-alist name prepared-index-alist)
                          ;; Default to `name' if it's in the alist.
                          name))))
-    ;; Display the completion buffer.
     (minibuffer-with-setup-hook
-        (lambda ()
-          (setq-local minibuffer-allow-text-properties t)
-          (setq-local completion-extra-properties
-                      `( :category imenu
-                         ,@(when (eq imenu-flatten 'annotation)
-                             `(:annotation-function
-                               ,(lambda (s) (get-text-property
-                                             0 'imenu-section s))))
-                         ,@(when (eq imenu-flatten 'group)
-                             `(:group-function
-                               ,(lambda (s transform)
-                                  (if transform s
-                                    (get-text-property
-                                     0 'imenu-section s)))))))
-          (unless imenu-eager-completion-buffer
-            (minibuffer-completion-help)))
-      (setq name (completing-read prompt
-				  prepared-index-alist
-				  nil t nil 'imenu--history-list name)))
+        (lambda () (setq-local minibuffer-allow-text-properties t))
+      (setq name (completing-read
+                  prompt
+                  (completion-table-with-metadata
+		   prepared-index-alist
+                   `((category . imenu)
+                     (eager-display . ,(not imenu-eager-completion-buffer))
+                     ,@(when (eq imenu-flatten 'annotation)
+                         `((annotation-function
+                            . ,(lambda (s) (get-text-property
+                                            0 'imenu-section s)))))
+                     ,@(when (eq imenu-flatten 'group)
+                         `((group-function
+                            . ,(lambda (s transform)
+                                 (if transform s
+                                   (get-text-property
+                                    0 'imenu-section s))))))))
+		  nil t nil 'imenu--history-list name)))
 
     (when (stringp name)
       (or (get-text-property 0 'imenu-choice name)
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 405ee21cdb2..b0fec75cd0a 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -138,6 +138,9 @@ completion-metadata
    of completions.  Can operate destructively.
 - `cycle-sort-function': function to sort entries when cycling.
    Works like `display-sort-function'.
+- `eager-display': non-nil to request eager display of the
+  completion candidates.  Can also be a function which is invoked
+  after minibuffer setup.
 The metadata of a completion table should be constant between two boundaries."
   (let ((metadata (if (functionp table)
                       (funcall table string pred 'metadata))))
@@ -277,6 +280,15 @@ completion-table-case-fold
     (let ((completion-ignore-case (not dont-fold)))
       (complete-with-action action table string pred))))
 
+(defun completion-table-with-metadata (table metadata)
+  "Return new completion TABLE with METADATA.
+METADATA should be an alist of completion metadata.  See
+`completion-metadata' for a list of supported metadata."
+  (lambda (string pred action)
+    (if (eq action 'metadata)
+        `(metadata . ,metadata)
+      (complete-with-action action table string pred))))
+
 (defun completion-table-subvert (table s1 s2)
   "Return a completion table from TABLE with S1 replaced by S2.
 The result is a completion table which completes strings of the
@@ -1031,6 +1043,18 @@ minibuffer--completion-prompt-end
 (defvar completion-show-inline-help t
   "If non-nil, print helpful inline messages during completion.")
 
+(defcustom completion-eager-display 'auto
+  "Display the *Completions* buffer eagerly.
+
+If the variable is set to t or nil, respectively show the *Completions*
+buffer always or never eagerly.  The value `auto' shows the
+*Completions* buffer eagerly only if requested by the completion
+command.  Completion tables can request eager display via the
+`eager-display' metadata."
+  :type '(choice (const :tag "Never show *Completions* eagerly" nil)
+                 (const :tag "Always show *Completions* eagerly" t)
+                 (const :tag "If requested by the completion command" auto)))
+
 (defcustom completion-auto-help t
   "Non-nil means automatically provide help for invalid completion input.
 If the value is t, the *Completions* buffer is displayed whenever completion
@@ -1247,7 +1271,11 @@ completion-category-overrides
            (cons :tag "Completion Affixation"
                  (const :tag "Select one value from the menu."
                         affixation-function)
-                 (choice (function :tag "Custom function"))))))
+                 (choice (function :tag "Custom function")))
+           (cons :tag "Eager display"
+                 (const :tag "Select one value from the menu."
+                        eager-display)
+                 boolean))))
 
 (defun completion--category-override (category tag)
   (or (assq tag (cdr (assq category completion-category-overrides)))
@@ -2493,6 +2521,8 @@ completion-extra-properties
 
 `:cycle-sort-function': Function to sort entries when cycling.
 
+`:eager-display': Show the *Completions* buffer eagerly.
+
 See more information about these functions above
 in `completion-metadata'.
 
@@ -4809,7 +4839,17 @@ completing-read-default
                 (setq-local minibuffer--require-match require-match)
                 (setq-local minibuffer--original-buffer buffer)
                 ;; Copy the value from original buffer to the minibuffer.
-                (setq-local completion-ignore-case c-i-c))
+                (setq-local completion-ignore-case c-i-c)
+                ;; Show the completion help eagerly if
+                ;; `completion-eager-display' is t or if eager display
+                ;; has been requested by the completion table.
+                (when completion-eager-display
+                  (let* ((md (completion-metadata
+                              initial-input collection predicate))
+                         (fun (completion-metadata-get md 'eager-display)))
+                    (when (or fun (eq completion-eager-display t))
+                      (funcall (if (functionp fun)
+                                   fun #'minibuffer-completion-help))))))
             (read-from-minibuffer prompt initial-input keymap
                                   nil hist def inherit-input-method))))
     (when (and (equal result "") def)
@@ -4999,11 +5039,9 @@ minibuffer-complete-history
            (lambda () (get-buffer-window "*Completions*" 0))))
       (completion-in-region
        (minibuffer--completion-prompt-end) (point-max)
-       (lambda (string pred action)
-         (if (eq action 'metadata)
-             '(metadata (display-sort-function . identity)
-                        (cycle-sort-function . identity))
-           (complete-with-action action completions string pred)))))))
+       (completion-table-with-metadata
+        completions '((display-sort-function . identity)
+                      (cycle-sort-function . identity)))))))
 
 (defun minibuffer-complete-defaults ()
   "Complete minibuffer defaults as far as possible.
@@ -5019,11 +5057,9 @@ minibuffer-complete-defaults
          (lambda () (get-buffer-window "*Completions*" 0))))
     (completion-in-region
      (minibuffer--completion-prompt-end) (point-max)
-     (lambda (string pred action)
-       (if (eq action 'metadata)
-           '(metadata (display-sort-function . identity)
-                      (cycle-sort-function . identity))
-         (complete-with-action action completions string pred))))))
+     (completion-table-with-metadata
+      completions '((display-sort-function . identity)
+                    (cycle-sort-function . identity))))))
 
 (define-key minibuffer-local-map [?\C-x up] 'minibuffer-complete-history)
 (define-key minibuffer-local-map [?\C-x down] 'minibuffer-complete-defaults)
diff --git a/lisp/tmm.el b/lisp/tmm.el
index 632e55e47a8..45afbe4a3c2 100644
--- a/lisp/tmm.el
+++ b/lisp/tmm.el
@@ -119,12 +119,6 @@ tmm-inactive
   '((t :inherit shadow))
   "Face used for inactive menu items.")
 
-(defun tmm--completion-table (items)
-  (lambda (string pred action)
-    (if (eq action 'metadata)
-	'(metadata (display-sort-function . identity))
-      (complete-with-action action items string pred))))
-
 (defvar tmm--history nil)
 
 ;;;###autoload
@@ -222,7 +216,9 @@ tmm-prompt
              (setq out
                    (if default-item
                        (car (nth index-of-default tmm-km-list))
-                     (minibuffer-with-setup-hook #'tmm-add-prompt
+                     (minibuffer-with-setup-hook
+                         (lambda ()
+                           (setq tmm-old-mb-map (tmm-define-keys t)))
                        ;; tmm-km-list is reversed, because history
                        ;; needs it in LIFO order.  But default list
                        ;; needs it in non-reverse order, so that the
@@ -233,7 +229,12 @@ tmm-prompt
                        (completing-read-default
                         (concat gl-str
                                 " (up/down to change, PgUp to menu): ")
-                        (tmm--completion-table tmm-km-list) nil t nil
+                        (completion-table-with-metadata
+                         tmm-km-list '((category . tmm)
+                                       (eager-display . tmm-add-prompt)
+                                       (display-sort-function . identity)
+                                       (cycle-sort-function . identity)))
+                        nil t nil
                         'tmm--history (reverse tmm--history)))))))
       (if (and (stringp out) (string= "^" out))
           ;; A fake choice to please the destructuring later.
@@ -402,7 +403,6 @@ tmm-remove-inactive-mouse-face
 (defun tmm-add-prompt ()
   (unless tmm-c-prompt
     (error "No active menu entries"))
-  (setq tmm-old-mb-map (tmm-define-keys t))
   (or tmm-completion-prompt
       (add-hook 'completion-setup-hook
                 #'tmm-completion-delete-prompt 'append))
@@ -458,6 +458,7 @@ tmm-shortcut
 (defun tmm-goto-completions ()
   "Jump to the completions buffer."
   (interactive)
+  (tmm-add-prompt)
   (setq tmm-c-prompt (buffer-substring (minibuffer-prompt-end) (point-max)))
   ;; Clear minibuffer old contents before using *Completions* buffer for
   ;; selection.
-- 
2.45.2

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Eli Zaretskii]

> From: Daniel Mendler <mail@daniel-mendler.de>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  Eli Zaretskii
>  <eliz@gnu.org>,  74616@debbugs.gnu.org
> Date: Mon, 09 Dec 2024 20:28:06 +0100
> 
> Juri Linkov <juri@linkov.net> writes:
> 
> > One small detail that could be added later is to extend
> > the customization type of `completion-category-overrides'
> > :value-type with `eager-display'.  Since currently
> > only programmatic use is supported.
> 
> Okay, I will add this to to custom type.

Please also add a :version tag.

The doc string of the defcustom could also be improved.  I think the
first line should say

  Whether completion commands should display *Completions* buffer eagerly.

Also, the part about requesting the eager display via the
`eager-display' metadata should probably be expanded, because it's too
terse to be useful.  I would also suggest to explain what "eagerly"
means in this ciontext.

Thanks.

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Eli Zaretskii]

> From: Daniel Mendler <mail@daniel-mendler.de>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  Eli Zaretskii
>  <eliz@gnu.org>,  74616@debbugs.gnu.org
> Date: Mon, 09 Dec 2024 20:52:25 +0100
> 
> See the new patch which I've attached to this mail, with the two
> improvements.

Does this deserve a NEWS entry?

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Eli Zaretskii]

> Cc: 74616@debbugs.gnu.org, monnier@iro.umontreal.ca, juri@linkov.net
> Date: Mon, 09 Dec 2024 22:06:48 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> 
> Please also add a :version tag.
> 
> The doc string of the defcustom could also be improved.  I think the
> first line should say
> 
>   Whether completion commands should display *Completions* buffer eagerly.
> 
> Also, the part about requesting the eager display via the
> `eager-display' metadata should probably be expanded, because it's too
> terse to be useful.  I would also suggest to explain what "eagerly"
> means in this ciontext.

Oh, and please also mention the bug number in the commit log message.

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Daniel Mendler via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Daniel Mendler <mail@daniel-mendler.de>
>> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  Eli Zaretskii
>>  <eliz@gnu.org>,  74616@debbugs.gnu.org
>> Date: Mon, 09 Dec 2024 20:52:25 +0100
>> 
>> See the new patch which I've attached to this mail, with the two
>> improvements.
>
> Does this deserve a NEWS entry?

I've added a :version tag to the defcustom and expanded the docstring.
Furthermore the commit message includes the bug numbers and there is a
NEWS entry. See the updated patch attached to this mail.

Daniel


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-customization-variable-completion-eager-display.patch --]
[-- Type: text/x-diff, Size: 15403 bytes --]

From b3293d0a25ef718409a3180793cb0aaa30aa4c86 Mon Sep 17 00:00:00 2001
From: Daniel Mendler <mail@daniel-mendler.de>
Date: Sun, 8 Dec 2024 20:05:07 +0100
Subject: [PATCH] New customization variable `completion-eager-display'

The customization option can be set to t or nil, to respectively
always or never show the *Completions* buffer eagerly at the
beginning of a completion session.  Furthermore the option can
be set to the value auto.  In this case the *Completions* buffer
will only be shown if requested by the completion table.
Completion tables can use the `eager-display' completion
metadata to do so. (Bug#74616, Bug#74617)

* lisp/minibuffer.el (completion-eager-display): New
customization variable.
(completion-metadata): Update docstring, document the
new `eager-display' completion metadata.
(completion-extra-properties): Update docstring, document the
new `:eager-display' completion metadata.
(completion-category-overrides): Add `eager-display' to the
custom type specification.
(completing-read-default): Handle the `completion-eager-display'
customization variable and the `eager-display' completion
metadata.
(completion-table-with-metadata): New function to create
a completion table with metadata.
(minibuffer-complete-defaults, minibuffer-complete-history):
Use it.
* lisp/ffap.el (ffap-menu-ask): Add `ffap-menu' completion
category and `eager-display' completion metadata.  Use
`completion-table-with-metadata'.
* lisp/imenu.el (imenu-eager-completion-buffer): Correct
docstring, which had been inverted.
(imenu--completion-buffer): Add `eager-display' completion
metadata.  Use `completion-table-with-metadata'.
* lisp/tmm.el (tmm-prompt): Add `tmm' completion category and
`eager-display' completion metadata.  Use
`completion-table-with-metadata'.  Add keymap setup.
(tmm-add-prompt): Remove keymap setup.
(tmm-goto-completions): Call `tmm-add-prompt' to ensure that a
*Completions* buffer is shown.
(tmm--completion-table): Remove unused internal function.
* etc/NEWS: Announce the change.
---
 etc/NEWS           |  8 ++++++
 lisp/ffap.el       | 17 ++++++------
 lisp/imenu.el      | 40 +++++++++++++--------------
 lisp/minibuffer.el | 67 +++++++++++++++++++++++++++++++++++++---------
 lisp/tmm.el        | 19 ++++++-------
 5 files changed, 101 insertions(+), 50 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 3efce149dbf..043e55edf3e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -96,6 +96,14 @@ files and features.
 
 ** Minibuffer and Completions
 
++++
+*** New user option 'completion-eager-display'.
+This option configures whether completion commands should display
+the *Completions* buffer immediately.  When the variable is set to t all
+completion commands show *Completions* immediately, respectively nil
+disables the eager display for all commands. The default setting auto
+enables eager completion only if requested by the command.
+
 +++
 *** New user option 'completion-pcm-leading-wildcard'.
 This option configures how the partial-completion style does completion.
diff --git a/lisp/ffap.el b/lisp/ffap.el
index 6a4915fb5a3..c869e234140 100644
--- a/lisp/ffap.el
+++ b/lisp/ffap.el
@@ -1738,14 +1738,15 @@ ffap-menu-ask
 				    alist))))))
      ;; minibuffer with completion buffer:
      (t
-      (let ((minibuffer-setup-hook 'minibuffer-completion-help))
-	;; Bug: prompting may assume unique strings, no "".
-	(setq choice
-	      (completing-read
-	       (format-prompt title (car (car alist)))
-	       alist nil t
-	       ;; (cons (car (car alist)) 0)
-	       nil)))
+      ;; Bug: prompting may assume unique strings, no "".
+      (setq choice
+	    (completing-read
+	     (format-prompt title (car (car alist)))
+             (completion-table-with-metadata
+	      alist '((category . ffap-menu) (eager-display . t)))
+             nil t
+	     ;; (cons (car (car alist)) 0)
+	     nil))
       (sit-for 0)			; redraw original screen
       ;; Convert string to its entry, or else the default:
       (setq choice (or (assoc choice alist) (car alist)))))
diff --git a/lisp/imenu.el b/lisp/imenu.el
index 2d64970bfcf..ba1ba5fcd00 100644
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -100,7 +100,7 @@ imenu-use-popup-menu
                  (other :tag "Always" t)))
 
 (defcustom imenu-eager-completion-buffer t
-  "If non-nil, eagerly pop up the completion buffer."
+  "If nil, eagerly pop up the completion buffer."
   :type 'boolean
   :version "22.1")
 
@@ -767,27 +767,25 @@ imenu--completion-buffer
                          (imenu--in-alist name prepared-index-alist)
                          ;; Default to `name' if it's in the alist.
                          name))))
-    ;; Display the completion buffer.
     (minibuffer-with-setup-hook
-        (lambda ()
-          (setq-local minibuffer-allow-text-properties t)
-          (setq-local completion-extra-properties
-                      `( :category imenu
-                         ,@(when (eq imenu-flatten 'annotation)
-                             `(:annotation-function
-                               ,(lambda (s) (get-text-property
-                                             0 'imenu-section s))))
-                         ,@(when (eq imenu-flatten 'group)
-                             `(:group-function
-                               ,(lambda (s transform)
-                                  (if transform s
-                                    (get-text-property
-                                     0 'imenu-section s)))))))
-          (unless imenu-eager-completion-buffer
-            (minibuffer-completion-help)))
-      (setq name (completing-read prompt
-				  prepared-index-alist
-				  nil t nil 'imenu--history-list name)))
+        (lambda () (setq-local minibuffer-allow-text-properties t))
+      (setq name (completing-read
+                  prompt
+                  (completion-table-with-metadata
+		   prepared-index-alist
+                   `((category . imenu)
+                     (eager-display . ,(not imenu-eager-completion-buffer))
+                     ,@(when (eq imenu-flatten 'annotation)
+                         `((annotation-function
+                            . ,(lambda (s) (get-text-property
+                                            0 'imenu-section s)))))
+                     ,@(when (eq imenu-flatten 'group)
+                         `((group-function
+                            . ,(lambda (s transform)
+                                 (if transform s
+                                   (get-text-property
+                                    0 'imenu-section s))))))))
+		  nil t nil 'imenu--history-list name)))
 
     (when (stringp name)
       (or (get-text-property 0 'imenu-choice name)
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 405ee21cdb2..71b77683bb5 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -138,6 +138,9 @@ completion-metadata
    of completions.  Can operate destructively.
 - `cycle-sort-function': function to sort entries when cycling.
    Works like `display-sort-function'.
+- `eager-display': non-nil to request eager display of the
+  completion candidates.  Can also be a function which is invoked
+  after minibuffer setup.
 The metadata of a completion table should be constant between two boundaries."
   (let ((metadata (if (functionp table)
                       (funcall table string pred 'metadata))))
@@ -277,6 +280,15 @@ completion-table-case-fold
     (let ((completion-ignore-case (not dont-fold)))
       (complete-with-action action table string pred))))
 
+(defun completion-table-with-metadata (table metadata)
+  "Return new completion TABLE with METADATA.
+METADATA should be an alist of completion metadata.  See
+`completion-metadata' for a list of supported metadata."
+  (lambda (string pred action)
+    (if (eq action 'metadata)
+        `(metadata . ,metadata)
+      (complete-with-action action table string pred))))
+
 (defun completion-table-subvert (table s1 s2)
   "Return a completion table from TABLE with S1 replaced by S2.
 The result is a completion table which completes strings of the
@@ -1031,6 +1043,25 @@ minibuffer--completion-prompt-end
 (defvar completion-show-inline-help t
   "If non-nil, print helpful inline messages during completion.")
 
+(defcustom completion-eager-display 'auto
+  "Whether completion commands should display *Completions* buffer eagerly.
+
+If the variable is set to t, completion commands show the *Completions*
+buffer always immediately.  Setting the variable to nil disables the
+eager *Completions* display for all commands.
+
+For the value `auto', completion commands show the *Completions* buffer
+immediately only if requested by the completion command.  Completion
+tables can request eager display via the `eager-display' metadata.
+
+See also the variables `completion-category-overrides' and
+`completion-extra-properties' for the `eager-display' completion
+metadata."
+  :type '(choice (const :tag "Never show *Completions* eagerly" nil)
+                 (const :tag "Always show *Completions* eagerly" t)
+                 (const :tag "If requested by the completion command" auto))
+  :version "31.1")
+
 (defcustom completion-auto-help t
   "Non-nil means automatically provide help for invalid completion input.
 If the value is t, the *Completions* buffer is displayed whenever completion
@@ -1247,7 +1278,11 @@ completion-category-overrides
            (cons :tag "Completion Affixation"
                  (const :tag "Select one value from the menu."
                         affixation-function)
-                 (choice (function :tag "Custom function"))))))
+                 (choice (function :tag "Custom function")))
+           (cons :tag "Eager display"
+                 (const :tag "Select one value from the menu."
+                        eager-display)
+                 boolean))))
 
 (defun completion--category-override (category tag)
   (or (assq tag (cdr (assq category completion-category-overrides)))
@@ -2493,6 +2528,8 @@ completion-extra-properties
 
 `:cycle-sort-function': Function to sort entries when cycling.
 
+`:eager-display': Show the *Completions* buffer eagerly.
+
 See more information about these functions above
 in `completion-metadata'.
 
@@ -4809,7 +4846,17 @@ completing-read-default
                 (setq-local minibuffer--require-match require-match)
                 (setq-local minibuffer--original-buffer buffer)
                 ;; Copy the value from original buffer to the minibuffer.
-                (setq-local completion-ignore-case c-i-c))
+                (setq-local completion-ignore-case c-i-c)
+                ;; Show the completion help eagerly if
+                ;; `completion-eager-display' is t or if eager display
+                ;; has been requested by the completion table.
+                (when completion-eager-display
+                  (let* ((md (completion-metadata
+                              initial-input collection predicate))
+                         (fun (completion-metadata-get md 'eager-display)))
+                    (when (or fun (eq completion-eager-display t))
+                      (funcall (if (functionp fun)
+                                   fun #'minibuffer-completion-help))))))
             (read-from-minibuffer prompt initial-input keymap
                                   nil hist def inherit-input-method))))
     (when (and (equal result "") def)
@@ -4999,11 +5046,9 @@ minibuffer-complete-history
            (lambda () (get-buffer-window "*Completions*" 0))))
       (completion-in-region
        (minibuffer--completion-prompt-end) (point-max)
-       (lambda (string pred action)
-         (if (eq action 'metadata)
-             '(metadata (display-sort-function . identity)
-                        (cycle-sort-function . identity))
-           (complete-with-action action completions string pred)))))))
+       (completion-table-with-metadata
+        completions '((display-sort-function . identity)
+                      (cycle-sort-function . identity)))))))
 
 (defun minibuffer-complete-defaults ()
   "Complete minibuffer defaults as far as possible.
@@ -5019,11 +5064,9 @@ minibuffer-complete-defaults
          (lambda () (get-buffer-window "*Completions*" 0))))
     (completion-in-region
      (minibuffer--completion-prompt-end) (point-max)
-     (lambda (string pred action)
-       (if (eq action 'metadata)
-           '(metadata (display-sort-function . identity)
-                      (cycle-sort-function . identity))
-         (complete-with-action action completions string pred))))))
+     (completion-table-with-metadata
+      completions '((display-sort-function . identity)
+                    (cycle-sort-function . identity))))))
 
 (define-key minibuffer-local-map [?\C-x up] 'minibuffer-complete-history)
 (define-key minibuffer-local-map [?\C-x down] 'minibuffer-complete-defaults)
diff --git a/lisp/tmm.el b/lisp/tmm.el
index 632e55e47a8..45afbe4a3c2 100644
--- a/lisp/tmm.el
+++ b/lisp/tmm.el
@@ -119,12 +119,6 @@ tmm-inactive
   '((t :inherit shadow))
   "Face used for inactive menu items.")
 
-(defun tmm--completion-table (items)
-  (lambda (string pred action)
-    (if (eq action 'metadata)
-	'(metadata (display-sort-function . identity))
-      (complete-with-action action items string pred))))
-
 (defvar tmm--history nil)
 
 ;;;###autoload
@@ -222,7 +216,9 @@ tmm-prompt
              (setq out
                    (if default-item
                        (car (nth index-of-default tmm-km-list))
-                     (minibuffer-with-setup-hook #'tmm-add-prompt
+                     (minibuffer-with-setup-hook
+                         (lambda ()
+                           (setq tmm-old-mb-map (tmm-define-keys t)))
                        ;; tmm-km-list is reversed, because history
                        ;; needs it in LIFO order.  But default list
                        ;; needs it in non-reverse order, so that the
@@ -233,7 +229,12 @@ tmm-prompt
                        (completing-read-default
                         (concat gl-str
                                 " (up/down to change, PgUp to menu): ")
-                        (tmm--completion-table tmm-km-list) nil t nil
+                        (completion-table-with-metadata
+                         tmm-km-list '((category . tmm)
+                                       (eager-display . tmm-add-prompt)
+                                       (display-sort-function . identity)
+                                       (cycle-sort-function . identity)))
+                        nil t nil
                         'tmm--history (reverse tmm--history)))))))
       (if (and (stringp out) (string= "^" out))
           ;; A fake choice to please the destructuring later.
@@ -402,7 +403,6 @@ tmm-remove-inactive-mouse-face
 (defun tmm-add-prompt ()
   (unless tmm-c-prompt
     (error "No active menu entries"))
-  (setq tmm-old-mb-map (tmm-define-keys t))
   (or tmm-completion-prompt
       (add-hook 'completion-setup-hook
                 #'tmm-completion-delete-prompt 'append))
@@ -458,6 +458,7 @@ tmm-shortcut
 (defun tmm-goto-completions ()
   "Jump to the completions buffer."
   (interactive)
+  (tmm-add-prompt)
   (setq tmm-c-prompt (buffer-substring (minibuffer-prompt-end) (point-max)))
   ;; Clear minibuffer old contents before using *Completions* buffer for
   ;; selection.
-- 
2.45.2

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Juri Linkov]

> See the new patch which I've attached to this mail, with the two
> improvements.

Thanks, I confirm that now everything works nicely.

BTW, after customizing 'completion-eager-display' to t, its behavior
looks like the option 'icomplete-show-matches-on-no-input', and reminds
the plans to implement the updating *Completions* as you type.
So `eager-display' could be the first step for implementing
`eager-update' as well.

bug#74616: 30.0.92; tmm always displays the *Completions* buffer

[Eli Zaretskii]

> From: Daniel Mendler <mail@daniel-mendler.de>
> Cc: juri@linkov.net,  monnier@iro.umontreal.ca,  74616@debbugs.gnu.org
> Date: Mon, 09 Dec 2024 21:32:49 +0100
> 
> > Does this deserve a NEWS entry?
> 
> I've added a :version tag to the defcustom and expanded the docstring.
> Furthermore the commit message includes the bug numbers and there is a
> NEWS entry. See the updated patch attached to this mail.

Thanks.  This LGTM (but let's leave some time for others to chime in),
with the following nit:

> ++++
> +*** New user option 'completion-eager-display'.
> +This option configures whether completion commands should display
> +the *Completions* buffer immediately.  When the variable is set to t all
> +completion commands show *Completions* immediately, respectively nil
> +disables the eager display for all commands. The default setting auto
                                              ^^
Two spaces there, please.