bug#70846: Imenu flatten

[Juri Linkov]

>> This patch revives the feature existed in the initial version of imenu.el,
>> but that was unfortunately removed later.
>>
>> When comparing it with the version in breadcrumb-jump that was discussed in
>> https://lists.gnu.org/archive/html/emacs-devel/2023-12/msg00278.html
>> the advantage of this version is that it doesn't use 'cl-loop':
>
> Thanks.  If this is installed, I think it needs a NEWS entry.

So now pushed with a NEWS entry, and also with changes in the manual.

BTW, the manual says in (info "(emacs) Imenu"):

     You can customize the way the menus are sorted by setting the
  variable ‘imenu-sort-function’.  By default, names are ordered as they
  occur in the buffer; if you want alphabetic sorting, use the symbol
  ‘imenu--sort-by-name’ as the value.  You can also define your own
  comparison function by writing Lisp code.

But imenu-sort-function affects only the mouse popup menu.

To be able to customize sorting of imenu completion candidates
in the minibuffer, another patch is needed that sets a category
for sorting customization:

diff --git a/lisp/imenu.el b/lisp/imenu.el
index f628936cedc..5671b49cdf4 100644
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -733,10 +740,12 @@ imenu--completion-buffer
                          (imenu--in-alist name prepared-index-alist)
                          ;; Default to `name' if it's in the alist.
                          name))))
-    (let ((minibuffer-setup-hook minibuffer-setup-hook))
-      ;; Display the completion buffer.
-      (if (not imenu-eager-completion-buffer)
-         (add-hook 'minibuffer-setup-hook 'minibuffer-completion-help))
+    ;; Display the completion buffer.
+    (minibuffer-with-setup-hook
+        (lambda ()
+          (setq-local completion-extra-properties '(:category imenu))
+          (unless imenu-eager-completion-buffer
+            (minibuffer-completion-help)))
       (setq name (completing-read prompt
                                  prepared-index-alist
                                  nil t nil 'imenu--history-list name)))