bug#70846: Imenu flatten

[Eli Zaretskii <eliz@gnu.org>]

> From: Juri Linkov <juri@linkov.net>
> Cc: 70846@debbugs.gnu.org
> Date: Fri, 10 May 2024 19:45:37 +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.
> >>
> >> 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:
> >
> > I agree that it is better to sort the same way in both cases, so
> > changes to do that are welcome.
> 
> So now pushed.
> 
> > But please also amend the text in the manual to say so, because
> > currently it only talks about "menus", which could arguably be
> > interpreted as pertaining only to popup menus.
> 
> 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?