bug#70846: Imenu flatten

[Juri Linkov <juri@linkov.net>]

>> >> 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.
So the question remains: whether to document and how
the customization with 'completion-category-overrides' above?