radian-software / selectrum

🔔 Better solution for incremental narrowing in Emacs.
MIT License
737 stars 33 forks source link

Clearly explain Emacs completion ecosystem in README #274

Open raxod502 opened 3 years ago

raxod502 commented 3 years ago

On reading the comment by @alphapapa on Reddit, it became clear to me that the ecosystem of completion packages for Emacs has become very large and potentially difficult to navigate for the new user. I think this listing by @minad speaks for itself in terms of the number of different moving parts:

Completion packages (Builtin):

  • Default Emacs completion (no live completion, you have to press TAB)
  • Icomplete is a builtin on top of the default Emacs completion. It provides horizontal interactive completion. It is using the completing-read API.
  • Ido is an imho obsolete completion system, which I used for a long time. It does not play nice with the completing-read API and uses its own API. It only works for very few commands and seems to be unmaintained/abandoned in upstream.
  • Fido is a small mode based on Icomplete which configures Icomplete such that Icomplete behaves a bit more like Icomplete.

Completion packages (External):

  • Icomplete-Vertical is a small package adapting Icomplete such that options are presented vertically.
  • Ivy provides vertical completion, actions, filtering and sorting. Provides a rich API.
  • Selectrum provides vertical completion, stays within the confines of completing-read
  • The Mighty Helm: I don't know enough...

Filtering/Sorting packages:

  • Orderless provides filtering of candidates, can be plugged into the default completion system
  • Prescient provides sorting and filtering of candidates, can be plugged into the default completion system and Ivy, I think

Action packages:

  • Embark: Enhances commands with actions in the minibuffer. Embark can enhance Emacs builtin commands. Consult commands can also be enhanced and profit from Embark. This way Consult/Selectrum etc do not have to do anything action related. Actions are provided from outside.
  • Ivy: Provides actions for commands which configure them using ivy-read

Utility packages:

  • Counsel: Many utilities with actions based on ivy-read, works only with Ivy
  • Consult: Not as many utilities based on completing-read, provides consult-line, which is a Swiper-like search. Works with Selectrum, Icomplete, Ivy, ...
  • Swiper: Search which uses Ivy to narrow the list of candidate lines

@tarsius has remarked on Twitter that it's very helpful to see a coherent explanation of how a set of related packages compare to one another, and I think we have a great opportunity to do that here in the Selectrum README.

Currently, we just have a somewhat biased comparative listing of competing packages. I think it would be lovely to rewrite and expand this section to be less adversarial and also explain how different sets of these packages can be used together. This could also subsume the Complementary extensions section, so that we would have one coherent overview of the whole landscape---making it clear which packages are alternatives, and which ones are complementary. If we do a good job, it could probably be helpful to someone even if they decide not to use Selectrum.

tarsius commented 3 years ago

Unrelated, but just wanted to note that about an hour ago I actually started to switch over and I am loving it so far!

minad commented 3 years ago

@raxod502 I agree - it would be good to add a detailed overview and rewrite some sections in a less adversarial tone. The technical criticism stated in the readme should stay though.

I think it makes a lot of sense to recommend a set of related packages, such that it is clear to the user what is needed to get a rich experience - e.g. selectrum/icomplete-vertical+prescient/orderless+marginalia+consult+embark. Also stating that none of the additional packages is actually necessary and they can be added step by step as the user gets more comfortable or depending on custom preferences.