Re: Updating *Completions* as you type

[Spencer Baugh <sbaugh@catern.com>]

Juri Linkov <juri@linkov.net> writes:

>>> 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.
>
> Removing display-sort-function is still less safe
> than just adding a category.

Why do you say that?

The reason that comes to mind is that there are replacement completion
UIs which will need to explicitly add support for the category.  So
removing display-sort-function will affect them immediately, when they
might not yet have support for getting display-sort-function from
completion-category-defaults.

That is true.

But that actually suggests a further argument in this direction: if we
use user options which change the display-sort-function in the table
metadata, we'll have support for all completion UIs out of the box.

That seems really desirable!  So maybe we do want a solution like A
where we add a user option?  Since that user option will work for all
completion UIs.

Announcing "you can now customize the sorting order of a bunch of
completing-read-based things in this new way" but having that new way
only work for the default completion UI is a bit sad, although of course
they can support the new way eventually.

>> 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.
>
> In these rare cases when the default order is not intuitive,
> this can be explained in the docstring of the command that uses
> 'completing-read', e.g. in the docstring of 'read-from-kill-ring'.

Hm, I do think the wording on that would be a bit tricky.  Since
*actually* the default behavior today is alphabetical sorting.  We would
want to say "if completions-sort is nil, read-buffer completions are in
buffer-list order".

I guess it's not too bad, but we also need to document the category
symbol.  And perhaps the version it was added in.  All together it still
seems to me that it would be better to just mention
'read-from-kill-ring-sort' in the docstring of 'read-from-kill-ring'.

>>> 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.
>
> Agreed, this is a problem.
>
>> 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.
>
> Or an individual subcategory.
>
>> 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 believe they should use two different subcategories, e.g.
> 'project-file' and 'project-name'.

I agree, but...

>> I suppose another option is to simply declare that every table has to
>> have a unique category.  That would make "category" a misnomer though.
>
> Even such subcategories as 'project-name' make sense to use in other
> possible cases when reading a project name.

...if the project-name category is used for other tables too, but the
option is supposed to be specific to an individual completion table,
then we have the same problem again.