Difference between revisions of "Discoverability"

From WikEmacs
Jump to navigation Jump to search
(discoverability page: what helps to discover keybindings and commands)
 
(Which-key is on GNU ELPA)
 
(13 intermediate revisions by one other user not shown)
Line 4: Line 4:
  
 
Emacs by default is built around this idea of discoverability. It is self-documented. See '''C-h ?'''.
 
Emacs by default is built around this idea of discoverability. It is self-documented. See '''C-h ?'''.
 +
 +
It has helpful menus. You can make your way into [[org-mode]] or [[Dired]] with the menus.
 +
 +
== Ido - Interactively do things ==
 +
 +
[[ido]] gives interactivity to work with buffers and files. See also [[ivy]].
 +
 +
== Smex - extended M-x ==
 +
 +
[[Smex]] provides a convenient interface to your recently and most frequently used commands.
  
 
== Emacs 25 ==
 
== Emacs 25 ==
  
 
Emacs 25 comes with even better introspection (see [http://www.wilfred.me.uk/blog/2016/02/20/coming-in-emacs-25-1-even-better-introspection/ this article]).
 
Emacs 25 comes with even better introspection (see [http://www.wilfred.me.uk/blog/2016/02/20/coming-in-emacs-25-1-even-better-introspection/ this article]).
 +
 +
= Packages =
 +
 +
== Which-key (and guide-key) ==
 +
 +
You start a shortcut but you're unsure ? You want to know what are the other shortcuts available in the current major mode ? Or even global shortcuts ? You can discover all this with [https://github.com/justbur/emacs-which-key#additional-commands which-key].
 +
 +
Once you have installed it (it's in GNU [[ELPA]]), activate it with '''M-x which-key-mode''', start a keybinding (say "C-c") but don't finish it and wait for 1s (the default): now which-key will open a pop-up that lists all keybindings that follow "C-c".
 +
 +
This packages improves on [https://github.com/kai2nenobu/guide-key guide-key] in a few ways: It has pages to scroll through instead of taking up your whole screen, more options, and the ability to see all the "top-level" bindings.
 +
 +
However, it requires at least Emacs version 24.4, whereas guide-key is compatible with earlier versions.
 +
 +
 +
[[File:which-key-bottom.png]]
 +
 +
 +
== Helpful ==
 +
 +
[[Helpful]] is an alternative to the built-in Emacs help that provides much more contextual information.
 +
 +
[[File:Helpful.png]]
 +
 +
It is available in Melpa and Melpa Stable.
 +
 +
== Discover-my-major ==
 +
 +
This packages provides a function that does that: list all keybindings with their meaning for the current major mode. [https://github.com/steckerhalter/discover-my-major Discover-my-major] is in [[melpa]].
 +
 +
 +
=== Discover.el ===
 +
 +
The latter builds on [https://github.com/mickeynp/discover.el discover.el], a work by Mickeynp (from [https://www.masteringemacs.org/article/discoverel-discover-emacs-context-menus the mastering emacs blog]), which is in turned based on and inspired by [[Magit]]'s great popup system. However, discover.el is a bit outdated (it didn't update with the improvements of Magit) and less featurefull than Hydras. But it's easy to use and to write your own discoverable commands too. See how it's used to help discover Dired, "search-forward" (C-s) or [https://github.com/zenozeng/yafolding.el#discover-commands-with-a-context-menu yafolding].
 +
 +
 +
== Hydra ==
 +
 +
An [https://github.com/abo-abo/hydra/ Hydra] is a great package by abo-abo that "can be used to tie related commands into a family of short bindings with a common prefix - a Hydra."
 +
 +
You can pick hydras around (see the wiki on github). Some of them "just" group keybindings together, others provide a full list of a mode to help discoverability (for example, [https://github.com/abo-abo/hydra/wiki/Ibuffer the ibuffer Hydra] can be called immediately when we enter [[ibuffer]] mode and show all keybindings).
 +
 +
Hydras are also very easy to write. This is a simple one:
 +
 +
<source lang="lisp">
 +
(defhydra hydra-zoom (global-map "<f2>")
 +
  "zoom"
 +
  ("g" text-scale-increase "in")
 +
  ("l" text-scale-decrease "out"))
 +
</source>
 +
 +
This is the screenshot of a more complete one:
 +
 +
[[File:hydra-buffer.png]]
 +
 +
== Hercules, joining which-key-mode and Hydras ==
 +
 +
[https://gitlab.com/jjzmajic/hercules.el Hercules] is a new mode that groups related commands, as with which-key-mode, and sequentially with no prefix keys, as with hydras, but it does that automatically. We don't have to copy hydras in our init files, they are created on the fly.
 +
 +
= See also =
 +
 +
* [[Magit]] and its great pop-up system
 +
* [[https://github.com/emacs-helm/helm-descbinds helm-descbinds]] to make the currently active keybindings searchable with [[helm]].
 +
 +
 +
[[Category:Beginner]]
 +
[[Category:Convenience]]
 +
[[Category:Workflow]]
 +
[[Category:Text_Editing]]

Latest revision as of 19:13, 14 March 2022

This page will try to list emacs' features and packages that help in auto discoverability. So if you don't know much about emacs' keybindings, commands, i.e., potential, you can have the information come to you and you just have to let you guide.

Emacs builtins

Emacs by default is built around this idea of discoverability. It is self-documented. See C-h ?.

It has helpful menus. You can make your way into org-mode or Dired with the menus.

Ido - Interactively do things

ido gives interactivity to work with buffers and files. See also ivy.

Smex - extended M-x

Smex provides a convenient interface to your recently and most frequently used commands.

Emacs 25

Emacs 25 comes with even better introspection (see this article).

Packages

Which-key (and guide-key)

You start a shortcut but you're unsure ? You want to know what are the other shortcuts available in the current major mode ? Or even global shortcuts ? You can discover all this with which-key.

Once you have installed it (it's in GNU ELPA), activate it with M-x which-key-mode, start a keybinding (say "C-c") but don't finish it and wait for 1s (the default): now which-key will open a pop-up that lists all keybindings that follow "C-c".

This packages improves on guide-key in a few ways: It has pages to scroll through instead of taking up your whole screen, more options, and the ability to see all the "top-level" bindings.

However, it requires at least Emacs version 24.4, whereas guide-key is compatible with earlier versions.


Which-key-bottom.png


Helpful

Helpful is an alternative to the built-in Emacs help that provides much more contextual information.

Helpful.png

It is available in Melpa and Melpa Stable.

Discover-my-major

This packages provides a function that does that: list all keybindings with their meaning for the current major mode. Discover-my-major is in melpa.


Discover.el

The latter builds on discover.el, a work by Mickeynp (from the mastering emacs blog), which is in turned based on and inspired by Magit's great popup system. However, discover.el is a bit outdated (it didn't update with the improvements of Magit) and less featurefull than Hydras. But it's easy to use and to write your own discoverable commands too. See how it's used to help discover Dired, "search-forward" (C-s) or yafolding.


Hydra

An Hydra is a great package by abo-abo that "can be used to tie related commands into a family of short bindings with a common prefix - a Hydra."

You can pick hydras around (see the wiki on github). Some of them "just" group keybindings together, others provide a full list of a mode to help discoverability (for example, the ibuffer Hydra can be called immediately when we enter ibuffer mode and show all keybindings).

Hydras are also very easy to write. This is a simple one:

(defhydra hydra-zoom (global-map "<f2>")
  "zoom"
  ("g" text-scale-increase "in")
  ("l" text-scale-decrease "out"))

This is the screenshot of a more complete one:

Hydra-buffer.png

Hercules, joining which-key-mode and Hydras

Hercules is a new mode that groups related commands, as with which-key-mode, and sequentially with no prefix keys, as with hydras, but it does that automatically. We don't have to copy hydras in our init files, they are created on the fly.

See also