bug#70846: Imenu flatten

[Juri Linkov <juri@linkov.net>]

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

>> Ok, I could add display-sort-function directly to the imenu completing-read
>> that will depend on the value of display-sort-function.  Then there will be
>> no need to change the manual.
>
> Except we should then remove the reference to "menus", right?  Because
> if you do that, the customization of sorting order will affect both
> the menus and the completion, right?

Indeed, this will require removing the reference to the mouse menus.

But when I tried to use imenu-sort-function for sorting the completions,
I found a problem that makes such change impossible.

The problem is that the default value of imenu-sort-function is nil.
This means that by default the items on the mouse menu are unsorted.
But the completions are sorted, and we can't change this default
behavior.  Therefore, imenu-sort-function can't define how the
completions are sorted.  So this is just a documentation task
that is done in this patch:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: imenu-completion-sort.patch --]
[-- Type: text/x-diff, Size: 1825 bytes --]

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 01a1462044c..8ab5033795d 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -378,6 +378,10 @@ Imenu
 symbol @code{imenu--sort-by-name} as the value.  You can also
 define your own comparison function by writing Lisp code.
 
+  You can also customize how Imenu completions are sorted by changing
+the variable @code{completion-category-overrides} and setting its
+@code{display-sort-function} for the category @code{imenu}.
+
   If Eglot is activated for the current buffer's project
 (@pxref{Projects}) and the current buffer's major mode, Eglot provides
 its own facility for producing the buffer's index based on the
diff --git a/etc/NEWS b/etc/NEWS
index 8a2c8950fd8..19564062d9f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1046,6 +1046,11 @@ point is not in a comment or a string.  It is by default bound to
 It defines whether to flatten the list of sections in an imenu
 or show it nested.
 
++++
+*** Imenu completions now can be sorted.
+You can customize the option 'completion-category-overrides'
+and set 'display-sort-function' for the category 'imenu'.
+
 ** Which Function mode
 
 +++
diff --git a/lisp/imenu.el b/lisp/imenu.el
index 93a544ff550..f255dcc7148 100644
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -115,7 +115,10 @@ imenu-after-jump-hook
 (defcustom imenu-sort-function nil
   "The function to use for sorting the index mouse-menu.
 
-Affects only the mouse index menu.
+Affects only the mouse index menu.  If you want to change
+the sorting order of completions, you can customize
+the option `completion-category-overrides' and set
+`display-sort-function' for the category `imenu'.
 
 Set this to nil if you don't want any sorting (faster).
 The items in the menu are then presented in the order they were found