search

mawww / kakoune

mawww's experiment for a better code editor
http://kakoune.org
The Unlicense
9.87k stars 712 forks source link

Make shortcuts more discoverable #2356

Open maximbaz opened 6 years ago

maximbaz commented 6 years ago

I would like the shortcuts to be more discoverable via kakoune itself, without digging into docs or wiki.

The way Sublime Text, Visual Studio Code and probably many others approach this is the following:

  1. Add all available commands to the prompt (:)
  2. Show current mapping of this command in the help message of the selected command.

Suppose I want to execute "jump backward in jump list" command, but I forgot the shortcut for it. Currently I'm out of luck, I have to open Wiki and search for this, but of course when I'm working the time is valuable so it's just faster to manually navigate to where I want to navigate. This doesn't help me learn kakoune, next time I need "jump backwards" I will again have no time to search for the shortcut.

Instead, I wish I could execute this via :jump-backward-in-jump-list command. First of all, it is easily discoverable, even if I don't know exactly what I'm looking for, typing :jump or :back will find it. Secondly, as soon as a command is focused, kakoune shows help message for this command. If you could put a shortcut for this command in that help message, I will see it, and maybe I will remember it 😉

maximbaz commented 6 years ago

After I saw some comments about this ticket on IRC, I want to clarify: this is not about making commands discoverable, to learn kakoune and its features users should read documentation. This is about shortcuts discoverability, about hotkeys. I know that there is a way to jump backwards, but I don't remember that it is assigned to <c-o>.

The scenario is: I don't have time to dig into docs, I just want to execute this command, so I imagine opening prompt (because this is where other commands live), typing :back, seeing :jump-backward-in-jump-list, focusing it, making a notice of its shortcut <c-o> in the appeared help box and pressing Enter to run it.

I saw #2358, I don't think having different commands live in different places is a good idea, prompt already allows to search and execute some commands, I just want the built-in commands to also appear there.

Delapouite commented 6 years ago

The root of the issue lays in vim/kakoune design choices where in my opinion there's a false dichotomy between "normal 1 letter command tightly bound to a keyboard key" and "prompt command with a human long name". The division in these two distinct groups is somehow arbitrary. For instance, this problem surfaced recently to have the "rotate-selection-contents-backward" (aka <a-(>) capability in the editor, when disruptive changes had to be made in several keys.

On this side, the emacs approach handles your case better. Everything is a function (with a long name) and can be documented/discovered/classify easily as spacemacs proved with its famous<space> key revealing a tree of logic submenus. (or commands fuzzy finder as you suggest)

mawww commented 6 years ago

I think design.asciidoc is relevant here. Introducing names for the normal mode commands means introducing a new indirection (key -> command), the distinction between normal mode commands and the command language is relatively well defined in my view, with few keys that violate the "normal mode is for text/selection manipulation" principle (ga comes to mind).

To help discoverability, I think improving the documentation system so that one can easily search through it and get suggestions would be a reasonable direction that would solve most of the problems.

That said, I do agree there are some advantages towards introducing named keys, but I dont think it would make sense to merge them with the prompt commands, as they fundamuntally work differently (they dont arguments as a list of string for example). The biggest advantage I see is making scripts much easier to read (s : <select-matches>, <a-(> : <rotate-left>, C : <copy-on-next-line>). They would be more discoverable by name.

There is always some tension between the minimalism of having 'key == command' and the self documenting nature of 'key == mapping to a command'. I have sided with the minimalist side so far, which has its own merits (making it hard to add a new built-in key is a strong advantage, Kakoune has far too much built-in normal mode commands already), once you know the command its always the same in scripts and when using interactively...

maximbaz commented 6 years ago

Thanks, now I realize that there are conceptual differences between prompt commands and shortcuts, so it's not a good idea to merge them in :. @alexherbo2 also brought up a good point that : is not accessible for insert-mode shortcuts.

What do you think about #2358? It proposes to have a new trigger (such as F1) that will open a similar to current prompt menu, only filled with existing commands that are relevant for the current context.

Should I close this in favor of #2358?