Completions group metadata [was: master 431f8ff1e38: * lisp/imenu.el: Support more values for imenu-flatten (bug#70846)]

[Juri Linkov <juri@linkov.net>]

>>> - If completions-group is also non-nil, then group candidates according
>>>   to their prefix and trim the prefix in the group-function when
>>>   transforming candidates for display.
>>
>> The disadvantage of completions-group is its too wide coverage.
>> We should strive for more specific options where possible.
>
> Right.  The advantage, on the other hand, is that you can toggle
> completions-group on the fly in the minibuffer, either with
> toggle-option or with a dedicated command.  The wide coverage of
> completions-group means there's just one variable to toggle, always.

Interesting.  Then this requires such precedence (from high to low):

buffer-local value of completions-group -> metadata -> default-value
of completions-group

>> Or better: let's enable groups by category.  I don't know why we have
>> such a glaring omission that groups still can't be enabled by
>> category.  This should be simple to implement:
>
> Doesn't the group-function metadata entry give enough control already?

It's not easy for users to customize group-function metadata
by writing own group function.  Whereas with a boolean its easy
to toggle it in the Customization UI for completion-category-overrides.

> If a category or a specific completion table wants to disable grouping,
> it can simply avoid providing a group-function.  If it wants to enable
> grouping, then it does provide a group-function, and now it's up to the
> user's preferences which they express by setting completions-group.
> Maybe your suggestion yields more flexibility in some cases?

It makes sense to provide a group-function disabled by default
to help users just to enable it in completion-category-overrides
instead of writing it from scratch.