From: Juri Linkov <juri@linkov.net>
Date: Tue, 14 May 2024 06:55:52 +0000 (+0300)
Subject: Add documentation about sorting Imenu completions (bug#70846)
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=aefd0f0b582be45db6e719a5d5648a8f59111d16;p=emacs.git

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 01a1462044c..8ab5033795d 100644
--- 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 0ffbb9a69c6..118aa976c4a 100644
--- 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 3b9b77bb4fc..16eeb68c0e1 100644
--- 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