Add documentation about sorting Imenu completions (bug#70846)

* doc/emacs/programs.texi (Imenu): Document how Imenu completions
can be sorted.

* lisp/imenu.el (imenu-sort-function): Explain in the docstring
how to sort Imenu completions.

(cherry picked from commit 407b88333bec69faba2d9d0a889a556e01247a76)

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 01a1462044c84ca405a83e0a90cc5ffe289bee0a..8ab5033795dc6dd18d7681b9fd7f09a781488f5f 100644 (file)
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -378,6 +378,10 @@ they occur in the buffer; if you want alphabetic sorting, use the
 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 0ffbb9a69c6c28962f464e171c804d53d24e135f..118aa976c4a2edfdc2352e2928c42ae6c7f50fc5 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1144,6 +1144,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 3b9b77bb4fcf4b2500e0498c4f41d3dbc7c59fae..16eeb68c0e1912129944db9d291182d5b1dcda99 100644 (file)
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -115,7 +115,10 @@ Useful things to use here include `reposition-window', `recenter', and
 (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