Re: Updating *Completions* as you type

[sbaugh]

Juri Linkov <juri@linkov.net> writes:
>>>>>> - Again, the user is still able to configure the display-sort-function
>>>>>>   by configuring the individual completion table.
>>>>>
>>>>> Does this mean that every individual completion table should have
>>>>> a separate user option?
>>>>
>>>> No: only the completion tables which specify a display-sort-function in
>>>> their metadata.  All such completion tables should have a user option to
>>>> configure that display-sort-function.
>>>
>>> How then users could change the sorting order for individual tables
>>> that don't specify a display-sort-function to use an order different
>>> from completions-sort?
>>
>> They can use the category if the table specifies one.
>>
>> If the table neither specifies a category nor provides a table-specific
>> option, the display sort function for that table isn't currently
>> configurable.  Which I think we're both fine with?
>
> I think we should gradually add a category to most completion tables
> to make them completely configurable, not just with display-sort-function,
> but with all possible metadata.
>
> Adding a category resembles a long-lasting and still ongoing process of
> adding specific minibuffer history as a symbol to the HIST argument
> of different calls of read-from-minibuffer.

Agreed.

>>> The problem is that we can't distinguish two cases:
>>>
>>> 1. when display-sort-function is hard-coded in metadata
>>>    by the author of the completion table;
>>> 2. when display-sort-function in metadata
>>>    gets the value from the user option.
>>
>> I think we should just eliminate any instances of case 1.
>
> I don't think this is realistic to add an individual option in all cases.

That's not necessary.  We could also do possibility C that I described
before:

>> C.
>> - Remove display-sort-function from the metadata
>> - add the 'read-kill category to the metadata
>> - add 'read-kill to completion-category-defaults
>> (diff is 3 lines)

That seems simple and straightforward.

>>>> If we wanted to make that configurable, it seems much easier to just do
>>>>
>>>>           (if (eq action 'metadata)
>>>>               ;; Keep sorted by recency
>>>> -             '(metadata (display-sort-function . identity))
>>>> +             `(metadata (display-sort-function . 
>>>> ,read-from-kill-ring-sort))
>>>>             (complete-with-action action completions string pred)))
>>>
>>> This is an incomplete patch, there should be also a dozen of lines
>>> with defcustom, its docstring, the version number and a list
>>> of choices, etc.  And all this for a very small percent of users
>>> who would like to change this order.  This is too wasteful.
>>> It would be much more efficient to allow doing the same
>>> by customizing completion-category-overrides.
>>
>> The docstring and list of choices for read-from-kill-ring-sort are
>> something we want anyway - we would like to document that 'identity for
>> read-for-kill-ring keeps the kill ring sorted by recency, for example.
>> I see no better place to document that.
>>
>> The version number is also something we want anyway: if we just add a
>> category to read-from-kill-ring in Emacs 30, this will work only in
>> Emacs 30 and not in Emacs 29, and there's no way for a user to know that
>> other than by reading NEWS.
>
> I don't think such unnecessary defcustoms should be added lightly,
> even documentation is of no help for such obvious things as 'identity'
> that intuitively is understandable as keeping the original order.

Identity obviously keeps the original order, but what is the original
order?  That is not documented anywhere and I don't think it's
intuitive.  The user can always just try it and see, but that's a poor
substitute for documentation.

>> For such tables, I see three good possibilities (in order of my own
>> preference):
>>
>> A.
>> - Add read-from-kill-ring-sort defaulting to identity (with docstring)
>> (diff is 1 line + defcustom)
>>
>> B.
>> - Add read-from-kill-ring-sort defaulting to nil (with docstring)
>> - add the 'read-kill category to the metadata
>> - add 'read-kill to completion-category-defaults
>> (diff is 3 lines + defcustom)
>>
>> C.
>> - Remove display-sort-function from the metadata
>> - add the 'read-kill category to the metadata
>> - add 'read-kill to completion-category-defaults
>> (diff is 3 lines)
>>
>> If you really don't want the defcustom and associated documentation, I'm
>> OK with C.
>>
>> The option which I think is not good is:
>>
>> D.
>> - add the 'read-kill category to the metadata
>> - make completion-category-overrides take precedence over what is
>>   specified in the table metadata
>>
>> (diff is 1 line)
>>
>> This is a slightly smaller diff than option C, but I think it's a
>> fundamentally worse approach than C, because in the rare cases where we
>> do want an individual option for the table, we won't have a way for that
>> option to take precedence over the broader category-based configuration.
>
> I still don't understand why do you worry about this precedence when
> the user option completion-category-overrides is nil by default.
>
> Could you describe a use cases when such precedence might become a problem?

If some table needs an individual option (because the sorting needs to
affect the completion generation), but the table shares a category with
other tables, then that individual option will be overridden by the
category configuration.

For example, project-prompt-project-name allows one to complete over
project names.  If I wanted to sort its completions by some detail of
the underlying project (how recently the git repo was updated, maybe),
that would require the table to change behavior.  So it would need an
individual option.

However, project-prompt-project-name uses the same category as
project-find-file.  So if the user configured sorting for
project-find-file, it will override the table-specific option for
project-prompt-project-name.

I suppose another option is to simply declare that every table has to
have a unique category.  That would make "category" a misnomer though.