bug#70846: Imenu flatten

[Juri Linkov]

>> 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.