Re: [PATCH] (icomplete-vertical-mode): Add support for affixations and, annotations

[Daniel Mendler <mail@daniel-mendler.de>]

On 5/24/21 1:39 AM, Juri Linkov wrote:
>> You may have seen the Marginalia package by Omar Antolín Camarena and
>> myself, where we add rich annotations to many commands using the
>> `annotation/affixation-function` (https://github.com/minad/marginalia).
>> We are doing manual alignment there.
> 
> This is valuable experience.  It looks like you render rich annotations
> depending on the available candidates, and reformat the output
> when the number of candidates and their sizes are changing,
> like the horizontal completions format in the default frontend
> tries to fit as many as possible completions on the same line.
> 
> But it seems this works only for limited cases like simple and short
> prefix/suffix strings.  I can't imagine how such design could handle
> multi-columnar rich annotations.

Do you mean we cannot handle something like a tabular layout where
annotations can be resized on the UI level. Indeed, Marginalia cannot do
that since the UIs don't support that. Marginalia is only a best effort
thing.

If we would want to support such multi-columnar data and present it as a
tablist in the frontend the `annotation-function/affixation-function`
must be greatly extended. From this POV I also don't see
`affixation-function` as a good and all-encompassing solution.

The annotation function should be allowed to return a plist of all
columns of annotations and at this point I agree with Dmitry, that the
columns should get semantic column names. Of course this should be
extensible, the data backend should be allowed to define arbitrary such
columns. And then the UI can render some of these semantic columns
specially (e.g. as Company is doing with company-kind). But I am not in
favor of extending the `completing-read` API with these `company-*`
extensions. If such a semantic annotation extension is added, it should
be non-namespaced ideally since it is not tied to the Company backend.

On 5/24/21 1:42 AM, Juri Linkov wrote:
>> https://lists.gnu.org/archive/html/emacs-devel/2021-04/msg01320.html
>
> And later your reply was that annotation-function is the old approach,
> and that the default completion frontend still doesn't use
> :company-kind. Any plans to add support for :company-kind to
> the default frontend?

As I argued above, I don't think such support should be added. I hope we
can find a better semantic annotation solution which encompasses
company-kind, prefixes, suffixes and arbitrary rich columnar data. The
question is how this should be done such that in the end the design does
not get too complicated.

João started this discussion since he was not happy with the design put
forward by the `affixation-function`. By adding support for arbitrary
backend extensions in the frontend we will go in exactly the opposite
direction, ending up with an even more chaotic API.

The question if the `affixation-function/annotation-function` should
work on a list of candidates or on a single candidate has also been
discussed here. This is more of a technical detail, but I also want to
stress the point made by Juri in the other mail, that the backend may
have to setup some "context" to compute the annotation data lazily. If
this setup can only be done once per redisplay of the currently visible
candidates, that is beneficial. We are also using that in Marginalia for
some buffer switching to the original window, such that annotations are
computed there. For example you want to see the values of the original
buffer in the annotations of the `describe-variable` command. Of course
the backend can also perform some caching to avoid such expenses. In the
"modern" incrementally automatically updating UIs like Icomplete, Ivy,
Vertico and Selectrum the annotations are only computed on a small
subset of candidates, so these costs don't matter so much. For the
default UI or other buffer-based UIs, the computation of all candidates
and all completions is usually manually triggered or delayed a bit such
that only a small subset of all candidates are computed, such that the
same argument applies as in the case of the Icomplete-style UIs.

Daniel