Search in functions and their descriptions

[irigone]

What I want?

Is there a way to search for a command by not only its name, but also by description? It would be very useful for everyone, especially new users, because some Emacs commands have a weird name that doesn't tell what it does and can't be easily searched if you only know what you want to do but don't know what command does this.

For example?

A good example for that is viper-mode. It's not obvious what viper-mode does by only looking at the name. When I didn't know about Viper and thought "hey, it would be nice if I could have Emacs emulate Vi because I really need N from Vi", I went on google and looked for Vi emulation in Emacs. But if Selectrum could look for what I need in the documentation, I would just M-x vi emacs and find out about Viper.

What alternatives have you considered and why are they not as good?

Emacs can do pretty much what I need out of the box with C-h d but I think a lot of people would prefer to have everything in the same place, e.g. in M-x and have a short description for every command instead of the whole thing. And the search sucks there, too, if I just look up "vi" there, it would start from view-file. In my opinion, it should put viper and evil at the top, because these commands have "vi" in the description as a separate word instead of a part of the word "view" or "visit", but I'm pretty sure you already know about the best ways to sort things better than me :/

Sorry for being an ESL, it's not my fault
Gomenasai for being a weaboo with an anime pfp

[clemera]

For these kind of things we have the wiki and recently @minad started the consult project which looks like a good place for the commands you suggested.

[irigone]

Thx, will ask there then

[minad]

@veronikazaglotova @clemera This sounds like you want richer descriptions for M-x? This could indeed be added to consult.

[clemera]

I think not only M-x but also interactive search through documentation of various other symbol categoires (commands, faces, functions, variables..). Embark does display documentation when you export the candidates to a separate buffer, see the embark-first-line-of-docstring function which might be of help.

[minad]

@clemera Sounds good. I added it to the wishlist for now.

[minad]

But @clemera - I wonder if this issue should not be reopened here. Would it not be possible to enhance the candidate display "after the fact" somehow in selectrum based on the category metadata? Otherwise we end up with the same situation as in counsel.el where we have to reimplement each and every command. I am thinking of some dynamic candidate transformer based on category. The enhancement could also come from an external package (like consult), but selectrum could offer such an api or already does?

I think it would be better if consult only adds commands which add somehow unique functionality, which is not yet present in another completion command. But as of now consult has for example consult-faces, which is still barebone but maybe shouldn't even be there.

[minad]

@clemera Would this be the correct function selectrum-highlight-candidates-function?

[minad]

It indeed is. I guess I can kick out consult-faces and replace this with a more general category-based-enhancer. (Edit: Only problem is that describe-faces is not giving me a category. Why do all things suck...Now I will end up with a classifier as embark again. M-x is at least giving me the command category.)

Some quick test:

(defun consult--category ()
  (completion-metadata-get
   (completion-metadata
    (buffer-substring-no-properties (field-beginning) (point))
    minibuffer-completion-table
    minibuffer-completion-predicate)
   'category))

(setq selectrum-highlight-candidates-function
      (lambda (&rest args)
        (message "HL %s %s" (consult--category) args)
        (apply #'selectrum-default-candidate-highlight-function args)))

[clemera]

Yes, sadly categories aren't reliable, that's why embark includes the classifier hook. selectrum-highlight-candidates-function could only be used to customize display, to include docstrings when matching against your input you would need to include them before filtering the candidates. It becomes a different command as you have a different candidate set, I'm not sure we can do something to improve this on a general level.

[minad]

It becomes a different command as you have a different candidate set, I'm not sure we can do something to improve this on a general level.

Indeed, just found that out too. I agree, we indeed need different commands. Only enriching the displays is possible using the highlight function. Independent of the proposal to filter based on documentation, maybe I will add some basic support for richer output to consult.

[okamsn]

@clemera @minad One thing I have wondered is whether it would be nice to treat annotations as match-able and use the actual-candidate property which describes the actual candidate.

Originally, the wiki command selectrum-info only used annotations, but I find it more usable when descriptions are part of the candidate.

I don't know how other UI's do it, but are there any downsides to just using the annotation features and then matching against them (especially with the more flexible affixation function) instead of trying to create a "display transformer" or whatever Ivy Rich does?

[minad]

@okamsn This is not possible using annotations which are computed lazily. And this is a good thing since we can do richer annotations and more expensive computations this way. There is really no way to do this except transforming all candidates, but annotations and transformations are fundamentally distinct.

[clemera]

annotations which are computed lazily.

This is currently not true for annotations added via metadata where we compute the annotations in one go, see selectrum--get-candidates-from-table. But I already mentioned elsewhere that it would probably good to only do this on display, too.

[minad]

This is currently not true for annotations added via metadata where we compute the annotations in one go, see selectrum--get-candidates-from-table. But I already mentioned elsewhere that it would probably good to only do this on display, too.

Ok, thank you for letting me know. Right now consult-annotate-mode uses the selectrum highlight function. For this one the laziness applies I hope? This is what I assumed. It would be nice if it would also work for the annotation-function metadata!

And for all other candidates provided by consult-* functions the annotations are computed already from the get go, so I don't rely on any laziness here.

[clemera]

Ok, thank you for letting me know. Right now consult-annotate-mode uses the selectrum highlight function. For this one the laziness applies I hope? This is what I assumed. It would be nice if it would also work for the annotation-function metadata!

Yes, and I agree on doing metadata lazily, too.

@okamsn I also thought about how to handle this use case, one possible workaround I see could be to to use embark-become to toggle between the candidate set and one which includes annotations.

[clemera]

@okamsn Or you could dynamically switch the candidate set similar to the files/files in project command on the wiki.