bug#70846: Imenu flatten

[Eli Zaretskii <eliz@gnu.org>]

> From: Juri Linkov <juri@linkov.net>
> Cc: 70846@debbugs.gnu.org
> Date: Sun, 12 May 2024 09:55:38 +0300
> 
> >> >> 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.
> >>
> >> The "menus" above are pertaining only to popup menus,
> >> and the variable ‘imenu-sort-function’ can't be used
> >> to change the sorting order of Imenu completion candidates.
> >> Only the following customization changes this order:
> >>
> >>   (add-to-list 'completion-category-overrides
> >>                '(imenu (display-sort-function . identity)))
> >>
> >> Using this setting is especially essential for Imenu
> >> on a PDF document with doc-view.el to keep the order
> >> of chapters for the table of contents.
> >>
> >> But I have no idea how to document this customization.
> >
> > Now I'm confused: I thought the change you installed was supposed to
> > make sure the completion candidates are sorted using the same sort
> > order as determined by imenu-sort-function.  If not, then what did
> > your change do in this matter?
> 
> Completions can be sorted only by 'display-sort-function'.
> There is no other way to sort completions.

Then what did the change you installed do wrt sorting of candidates?

> So the question remains: whether to document and how
> the customization with 'completion-category-overrides' above?

I cannot answer that unless I understand what we just installed and
why.