Re: Updating *Completions* as you type

[Spencer Baugh <sbaugh@janestreet.com>]

Juri Linkov <juri@linkov.net> writes:
>>>> (or
>>>>  (alist-get 'display-sort-function (alist-get category completion-category-overrides))
>>>>  (alist-get 'display-sort-function metadata)
>>>>  (alist-get 'display-sort-function (alist-get category completion-category-defaults))
>>>>  completions-sort)
>>>
>>> 1. display-buffer-overriding-action
>>> 2. display-buffer-alist
>>> 3. function call arguments that correspond to completion metadata
>>> 4. display-buffer-base-action
>>> 5. display-buffer-fallback-action
>>
>> A few points in favor of
>>
>>   (alist-get 'display-sort-function metadata)
>>   (alist-get 'display-sort-function (alist-get category completion-category-overrides))
>>
>> instead:
>>
>> - 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.

>>   That's not true with display-buffer.  The only configuration
>>   mechanism is display-buffer-alist.
>
> Actually several user options already exist for display-buffer such as
> display-comint-buffer-action and display-tex-shell-buffer-action.
> They cover a whole category of display-buffer calls that display
> all types of comint buffers, etc.  So these options correspond
> to completion categories, not to individual completion tables.

Interesting.

It looks like those user options configure a broad category, as you say,
and they do this by changing the ACTION function call argument in
various places.

So, those user options configure a broad category, and then more
specific configuration overrides that broad category.  I suppose that's
what I also suggest for completion sorting.

>> - Given that the user can still configure the display-sort-function, I
>>   don't see any use case where the user should override it.  (A buggy
>>   completion table that returns the wrong display-sort-function?  But
>>   that should just be fixed.)
>
> I don't understand how the user can configure the display-sort-function,
> please elaborate.

If a completion table specifies a display-sort-function in its metadata,
it should have a user option to configure that display-sort-function.

>> - display-buffer-alist is driven purely by buffer-match-p conditions, so
>>   there's a linear sequence of overriding.  The display-sort-function
>>   has two levels: the completion table and the completion category.
>>   Since the table is more specific than the category, it should override
>>   the category.
>
> Agreed.  But this means only one thing that a user option
> for an individual completion table should take precedence
> over completion-category-overrides.

Well, yes.  So then we agree that a user option for an individual
completion table, if it exists, should take precedence over
completion-category-overrides?  So then we're only disagreeing over
whether such options should exist?

>> - As a minor point, I, and many other Emacs users IME, find the
>>   display-buffer configuration to be complex and hard to use, so I don't
>>   think we should try to emulate it too much.
>
> What is an alternative?  A myriad of individual options?

For display-buffer configuration?  I'm not sure, I don't want to get
into it too much.

For completion sorting configuration, though, I'm not suggesting adding
many individual options.  I'm quite happy with the proposal of,
"categories can determine the display-sort-function, and then options
for individual completion tables will override that".

In that world, there would be a read-buffer-sort option - but it would
be nil by default, so the read-buffer completion table by default
wouldn't specify a display-sort-function.  And the user could configure
read-buffer completion sorting using completion-category-overrides
however they like; and if they set read-buffer-sort to something else,
then it will in turn override the category-based configuration.

These individual options would also provide a natural place to document
behavior like "if you configure the display-sort-function for buffer
completion to 'identity, then the buffer sort order will match
(buffer-list)".  But the user could still make use of that information
by configuring the category.

>> Alternatively, could we just add support for configuring the individual
>> table now, and add category-based configuration later?  We don't need to
>> add everything all at once, and that will give us valuable user
>> feedback.
>
> I see no need to add individual options as all.  Every completion table
> that significantly differs from other tables so that it needs a separate
> display-sort-function, could provide a separate category.  For example,
> there is a category 'buffer'.  If 'switch-to-buffer' needs another
> display-sort-function it could provide a category 'buffer-for-switching'.

That won't work with the scenario I described before with sorting
file-name completion by mtime, where changing the sorting requires also
changing the completion table.

Also, this would require adding a category for essentially every
completion table.  For example, I see that read-from-kill-ring specifies
a display-sort-function, currently set to 'identity.  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)))

instead of adding a category 'kill-ring and sticking that into
completion-category-defaults.