bug#70846: Imenu flatten

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: 70846@debbugs.gnu.org
> Date: Mon, 13 May 2024 09:57:43 +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?
> >>
> >> It allows the users to customize the sorting order of
> >> completion candidates displayed by 'imenu'.
> >
> > And the only way to customize that is via add-to-list as above?  IOW,
> > without the change you installed, even the add-to-list method would
> > not have worked?
> 
> Yes, there was no way to customize sorting of Imenu completion candidates.
> 
> 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?