Cluttered list of commands

[rouanth]

Good day! First of all, great work with kakoune; I've been a user of vim for three years and was quite fluent in it, but have abandoned it without regrets three hours after having learned about kakoune.

However, as a newcomer, I've spotted a number of problems that have significantly slowed down my transition, and so I intend to specify the issues I've experienced.

First and foremost, it's the lack any systematization in the list of commands, due to which I'm always lost when browsing it. For example, I've learned about the existence of :tmux-new-window only yesterday, which was two weeks after seeing kakoune for the first time.

Browsing of the available commands would be a lot easier if they were grouped somehow. While creating separate groups for "editing", "wrappers for external commands" etc. would slow down the access to common commands, I believe that grouping tmux-*, clang-*, iterm-*, jedi-*, go-* and others like that would only be beneficial.

For this, one could introduce the notion of a command mask that would group together the entries that match it. Let's say a mask clang exists. Then no command with clang in it would be in the list, only the group is shown. When there is clang in the prompt, the list of completions shows the entries in the group and not the mask.

The next problem is that it doesn't seem possible to scroll down the list of commands without <tab>. Given that, as per the aforementioned problem, there are lots of commands in the list, it makes browsing a chore. Even if bindings for scrolling exist, they're neither pageup and pagedown nor <c-f> and <c-b> and aren't specified anywhere I've looked.

[lenormf]

There has been requests for a way to get a list of commands in the past, but I'm not sure where that sits in terms of coherence with the rest of the editor (should there be a command? a default option? something else?).

Lately some commands have been renamed to help discoverability using fuzzy matching, but unfortunately this is not a silver bullet and reading scripts in the rc directory remains the best way yet, albeit cumbersome for regular users.

[lenormf]

I think the currently idiomatic way of discovering commands is to use the prompt, and let the fuzzy matcher return candidates.

One other possible implementation of the concept of groups has been merged recently in the shape of modules. To get a list of all the groups, type :require-module into the command prompt, and the editor will return functionality groups.

Could we close this issue, if we consider that the above address it?

[rouanth]

tl;dr: the module system is really nice and makes it much easier to scroll through the list of commands by hiding all the clang and jedi commands when writing Java, but there's still, I think, no viable substitute to reading that list command by command. Maybe this could be accepted and the further efforts could be directed at further easing the pain of such a task (for example, by writing the name of the module near the name of each command to know what subsystem it relates to? or at least in the description of the command?), or a place for documentation of rc files could be introduced (or at least a changelog, possibly a separate one, could mention the changes in them), or some kind of hierarchy could still be imposed on the commands…

---

Long version.

The module system is good for this purpose, but the discoverability issue as initially described is still present: in order to find tmux-repl-vertical, one has to assume that kakoune integrates with tmux and explicitly search for it. If run under tmux, the tmux module is removed from the completion options for require-module, so browsing through them would not lead one to discover the tmux integration.

Also, as far as I can tell, there's no comprehensive documentation for the various rc files (and not even a place for that), so unless the user knows what they want or is advanced enough to confidently read the rc files (which are not heavily documented), there's still no clear way to discover features that one wouldn't expect to find (or wouldn't know the name of).

As an example, when writing this, I browsed through the whole list of commands once again and, to my surprise, discovered send-text. That one is a great idea and a true game-changer (btw, thank you, whoever did this, now I'm going to use this constantly and tell all my kak-using friends about it)! And yet, I don't see how I could learn about it without scrolling through the list of commands. Rereading every rc file that is relevant to me periodically to see if there are new features seems impractical, and :doc changelog says nothing about tmux or send-text. And because I type tmux in the command prompt in order to invoke tmux commands (which I do fairly often), I never even saw send-text since it's not tmux-send-text (while, for some reason, there is x11-send-text when not under tmux).

So, I see only two realistic options for discovering nice things one didn't know about:

• Learn the kak scripting language and read the rc files; keep a local copy of the repository to be able to diff the rc files between the releases;
• Scroll through the list of commands from time to time, preferably with every file format that one is interested in (I, for one, didn't know until recently that kak has special commands for the diff filetype, and I encounter diffs all the time, I just didn't happen to do :diff when looking at a diff).