(or emacs irrelevant)

More productive describe-variable

I refer to counsel-describe-variable here, which you can get from the MELPA counsel package, or from Github. If you're not familiar, counsel contains specialized functions using ivy-mode completion. Being specialized means that you can do more than usual, for instance here are the exit points of counsel-describe-variable:

  • RET calls describe-variable: a plain describe-variable with ivy-mode on looks like counsel-describe-variable, but has only this exit point.
  • C-. calls counsel-find-symbol: jump to symbol declaration.
  • C-, calls counsel--info-lookup-symbol: jump to symbol reference in *Info*.

These can also be extended by binding new commands in counsel-describe-map.

I'll just describe one useful scenario that happened just now. I was working on a checkdoc.el change and was testing it with avy.el. And I got a few style warnings for this code, which I got from a contributor (thanks for the code btw):

(defvar avy-translate-char-function #'identity
  "Function to translate user input key. This can be useful for
adding mirror key. E.g. one can make SPACE an alternative of 'a',
by adding:

\(setq avy-translate-char-function
      (lambda (c) (if (= c 32) ?a c)))

to allow typing SPACE instead of character 'a' to jump to the location
highlighted by 'a'.")

One of the warnings that avy-translate-char-function should be quoted while inside the docstring like so:


Of course that wouldn't play well with setq, so I wanted to see if any other variables that end in -function provide an example of use like here, and, if so, how they quote.

This is my personal configuration:

(global-set-key (kbd "<f1> v") 'counsel-describe-variable)

So I did <f1> v function$ to describe a variable that ends with function. Here, $ is a part of a regular expression, which should be a priority to learn if you want to be a (not just) Emacs Power User.

And now the key part: instead of pressing RET to describe just the current candidate, I repeatedly press C-M-n (ivy-next-line-and-call). After each C-M-n, the next candidate will be selected and the *Help* window will be updated.

With this trick I was able to skim through the 346 matches in seconds. The conclusion was that an example isn't usually provided, with nnmail-expiry-wait-function being an exemption. In the end, I decided not to provide such an explicit example and shorten the doc to this:

(defvar avy-translate-char-function #'identity
  "Function to translate user input key into another key.
For example, to make SPC do the same as ?a, use
\(lambda (c) (if (= c 32) ?a c)).")