An ivy-hydra using the default ivy minibuffer bindings

[hmelman]

I had a hard time learning the ivy minibuffer bindings. They weren't obvious to me and I found the help text confusing. I tried using ivy-hydra but that just confused me more. Then I realize that it used different bindings from the ivy-minibuffer-map defaults which explained my confusion. I created this hydra that used the default bindings. I've been using for well over a year. The help text really helped me learn the ivy defaults. May I suggest this as the default hydra for ivy or perhaps as inspiration for better help text in the default case.

;;; Ivy Hydra
;; replace the ivy-hydra with this learning one
;; uses regular ivy-mode keybindings to provide cleaner help and aid learning
(defhydra hydra-ivy (:hint nil
                     :color pink)
"

Navigation:
_C-n_/_C-p_ next/previous  _M-<_/_M->_ begin/end  _C-v_/_M-v_ scroll up/down
_C-'_ select with avy

Use current selection to:
_RET_,_C-m_ default action  _M-o_ choose from actions
_C-M-j_ use current input not selection

Do action with current selection and loop to choose more items:
_C-M-m_ default action  _C-M-o_ choose action
_C-M-n_/_C-M-p_ default action and select next/previous

Insert into input field:
_TAB_ complete input as far as possible
_C-j_ or _TAB_ _TAB_ complete directory and search or complete filename and do action
_M-n_/_M-p_ history next/previous  _M-i_ selection  _M-j_ word-at-point
_C-r_ reverse search history  _C-s_ next line or last from history if empty 

Other operations with current candidates:
_S-SPC_ restrict to current matches  _M-w_ saves selections to kill ring
_C-c C-o_ open candidates in ivy-occur buffer

Other:
_c_ toggle calling  _M-c_ toggle case folding  _M-r_ toggle regexp
_C-c C-s_ rotate sort function if multiple defined
_C-c C-a_ toggle user configured ignore lists
_C-M-a_ change default action from list for this session
"
  ;; Navigation
  ("M-<" ivy-beginning-of-buffer)
  ("C-n" ivy-next-line)
  ("C-p" ivy-previous-line)
  ("M->" ivy-end-of-buffer)
  ("C-v" ivy-scroll-up-command)
  ("M-v" ivy-scroll-down-command)
  ;; Single selection, action, exit
  ("RET" ivy-done :exit t)
  ("C-m" ivy-done :exit t)
  ("M-o" ivy-dispatching-done :exit t)
  ("C-j" ivy-alt-done :exit t)
  ("TAB" ivy-partial-or-done :exit t)
  ("C-M-j" ivy-immediate-done :exit t)
  ("C-'" ivy-avy :exit nil)
  ;; Multiple selections, actions, no exit
  ("C-M-m" ivy-call)
  ("C-M-o" ivy-dispatching-call)
  ("C-M-n" ivy-next-line-and-call)
  ("C-M-p" ivy-previous-line-and-call)
  ;; alter input
  ("M-n" ivy-next-history-element)
  ("M-p" ivy-previous-history-element)
  ("M-i" ivy-insert-current)
  ("M-j" ivy-yank-word)
  ("S-SPC" ivy-restrict-to-matches)
  ("C-r" ivy-reverse-i-search)
  ("C-s" ivy-next-line-or-history)
  ;; other
  ("M-w" ivy-kill-ring-save)
  ;; non-standard utilities
  ("c" ivy-toggle-calling)
  ("M-c" ivy-toggle-case-fold)
  ("M-r" ivy-toggle-regexp-quote)
  ("C-c C-s" ivy-rotate-sort)
  ("C-c C-a" ivy-toggle-ignore)
  ("C-M-a" ivy-read-action)
  ("C-c C-o" ivy-occur :exit t)
)

[abo-abo]

They weren't obvious to me and I found the help text confusing

I don't get it, you found doc/ivy-help.org confusing?

Because that's the help text that you get when you press C-h m or <f1> m during an Ivy completion session.

The intention of C-h m (doc/ivy-help.org) is to help the beginners, please PR to improve it if you find it lacking.

The intention of C-o (hydra-ivy/body) is to be a non-intrusive prefix (i.e. it can't occupy more than 5 lines or so) and help power users.

[hmelman]

Part of it is that I think they should serve different purposes. The help text is something you read when you first use ivy to learn what it does. My hydra is a reference to use when trying to internalize the key bindings and quickly lookup uncommonly used ones over the following weeks or more. My hydra fits in 27 lines which all fits on the screen at once for me, the help text is 138 lines and in org format, which as a non-org user adds some visual noise with ~, = and :: and with keys, commands and descriptions. I wanted a quicker reference.

The basics of C-n/C-p and RET I got immediately. The uses only slightly more advanced than that took me a bit. Entering a directory (C-j not TAB), choosing a name that wasn't in the list (C-M-j), understanding how a non-trivial pattern worked, (en/dis)abling calling, etc. Some of it was that there's a lot of new and unfamiliar terminology (pattern, input, candidate, action, done, alt-done, partial, call, dispatching).

So even in the "Key bindings for navigation" section there's the key, the command name and the description. While all of these are for basic navigation in, what as a beginner I'd call "the ivy list" the command names use various terminology (next-line, scroll-up-command, beginning-of-buffer) and the descriptions use different terms (candidate, page) and it's the (to me more confusing) terms in the command names that were highlighted. My hydra above avoids all that and fits all of these on one line:

C-n/C-p next/previous  M-</M-> begin/end  C-v/M-v scroll up/down

Part of it is that the help term action is necessarily abstract from the command that invoked it (open a file, select a buffer, run dired, etc.) Then adding the idea of "multiple actions" was a bit of a leap. If I got here via C-x C-f why do I want to do anything other than open a file? So instead of help text like "RET to open the file", I see "(=ivy done=) - exit with the current action" As an ivy beginner that was a (small) hurdle.

And I found the (highlighted) command names confusing. ivy-done performs the default action and exits, but "done" doesn't say that to me. If I want to choose a different action the command doesn't have the word "action", just "dispatching", ok. If I want to enter a directory and get a new completions list that's called ivy-alt-done, nothing mentioning directory or completions. Doing the default action on the input not the selection is called ivy-immediate-done, again not mentioning input, selection or action. While I realize ivy is too mature to change the command names, as an ivy beginner, names like these would have helped me a lot:

Current	More Explicit
ivy-done	ivy-do-action-and-exit
ivy-dispatching-done	ivy-choose-action-and-exit
ivy-alt-done	ivy-enter-directory
ivy-partial-or-done	ivy-complete-input-or-exit
ivy-immediate-done	ivy-do-action-on-input-and-exit
ivy-call	ivy-do-action
ivy-next-line-and-call	ivy-next-line-and-do-action
ivy-previous-line-and-call	ivy-previous-line-and-do-action
ivy-dispatching-call	ivy-choose-action

So in a sense I found, my hydra's short help text was a quick way to see the keys mapped to more explicit command names without having to scroll through five pages of help text.

In the same vein it took me a long time to internalize that ivy-occur saved the current completion session to a new buffer, because to me occur is an emacs command that's like grepping the current buffer. I'd expect a name more like ivy-save-completions-to-buffer. My hydra help text on this "open candidates in ivy-occur buffer" captured enough to remind me that it saved to a new buffer and to teach me that ivy's terminoloy for this includes the word "occur".

[abo-abo]

My hydra fits in 27 lines which all fits on the screen at once for me, the help text is 138 lines and in org format, which as a non-org user adds some visual noise with ~, = and :: and with keys, commands and descriptions.

The visual noise is now less pronounced.

C-n/C-p next/previous M- begin/end C-v/M-v scroll up/down

Maybe we can add this to ivy-help.org.

names like these would have helped me a lot:

I agree that the names could be better, but we have to stick with them now, many packages and user configs depend on them.

So in a sense I found, my hydra's short help text was a quick way to see the keys mapped to more explicit command names without having to scroll through five pages of help text.

The idea with the help text is not to scroll through it, but to search through it with swiper.

I think your hydra is useful, and some ideas from it can be used to improve the existing hydra and ivy-help.org. But maybe it's a better idea to publish your hydra as a separate package from your own repository. It's already the case that ivy-hydra is a separate package on MELPA; and Spacemacs provides its own version of ivy-hydra. Maybe your version will be picked up by popular Emacs configs like Spacemacs as one of the alternatives.

[hmelman]

The visual noise is now less pronounced.

Definitely an improvement.

But maybe it's a better idea to publish your hydra as a separate package from your own repository. It's already the case that ivy-hydra is a separate package on MELPA; and Spacemacs provides its own version of ivy-hydra. Maybe your version will be picked up by popular Emacs configs like Spacemacs as one of the alternatives.

Perhaps. Currently my config isn't on github and I've yet to create a package for distribution.

I think your hydra is useful, and some ideas from it can be used to improve the existing hydra and ivy-help.org.

I played a little with using my hydra text as the basis for a Quick Reference section in ivy-help.org between Help and Basic Operations though I'm not completely happy with it. It feels like a duplication of stuff in the rest of the help buffer and Hydra's faces for keys are a big help in making them jump out and enables putting multiple bindings on a single line.

I realized that unlike other C-h m help text, this help isn't passed through substitute-command-keys to show the current key bindings. This feels like a bug.