More documentation about configuring reedline keybindings

[chtenb]

I know this feature is very new and all, but I'm struggling to figure out how to change key bindings, so I would like to formally request more exhaustive material on this topic.

[elferherrera]

What would you like to known?

[chtenb]

Perhaps I'm just confused by several things, so I'm just gonna list some questions.

1. keybindings list gives a list of things related to keybindings, but it is unclear to me how this information maps onto the configuration examples. The types are events, edits. But in the examples you have event, send, edit, until.
2. Some thingies expect (named?) parameters, but what these parameters are and how they are named is not clear to me from the output of keybindings list.
3. In the default config the example keybindings all use lower case names for event stuff, but keybindings list uses PascalCase for things. This led me to believe they were different things. But in the documentation here it is used interchangably it seems. Nushell isn't case insensitive, is it?
4. The modes are not explained anywhere I believe. I'm a Vim user myself, but I don't know what this vi_normal and vi_insert is supposed to be. Looking at the output of keybindings default I can't see what the keybindings have to do with how vim works and neither do I understand why there is a difference between normal and insert. If anything a commandline is always in "insert" mode right?

[elferherrera]

Dont take it wrong, but it seems that you didnt read the documentation.

1. probably that could be a bit more clear
2. When they are named or not is explained here
   
   and here
   
3. that is explained here
   
4. That is a fair point. We dont explain the edit modes in Reedline. That can be extended

[chtenb]

Thanks for your reply.

2. When they are named or not is explained here

You are right. I actually read that, but didn't memorize it. When I started investigating all the possibilities using the keybindings command I didn't have this information on the top of my head anymore, and the keybindings output doesn't give any hints about this.

3. that is explained here

Interesting. This is the second time that I found myself reading over a quotation block. They are grayed out and apparently I unconsciously just skip over them and continue with the regular black text. I'm aware this might be subjective, but I would suggest to adjust the styling of these blocks to stand out more.

[fdncred]

In the default config the example keybindings all use lower case names for event stuff, but keybindings list uses PascalCase for things.

I agree with this point. When I wrote that I originally intended to override the results coming from reedline so that they matched what a user could put in a keybinding. I think we'd accept a PR that does that, although, word case doesn't matter. It can be pascal case, uppercase, lowercase, etc.

[chtenb]

Another thing I just found out to be very helpful is the keybinding listen command to track down how certain keypresses are interpreted by your terminal and which keypress are intercepted/captured by the environment. In my case I'm using the integrated terminal of VSCode which doesn't pass all keycombinations onto the terminal. Perhaps this command deserves a recommendation for troubleshooting in the keybinding configuration section.

[fdncred]

I "borrowed" that code from a crossterm example and it's super helpful because, like you say, all terminals don't see all keystrokes, which is why I added it moons ago. We'd accept a PR to illuminate the keybindings commands more.

[chtenb]

I opened a PR for the listen command: #364

I don't feel qualified to address the other things mentioned in the thread because I do not understand those fully myself.

[chtenb]

I openened a separate issue for the quotation blocks: #365

Open issues:

• Clarify how the keybindings list output relates to how you actually configure the keybindings in the config.nu file. (events, edits VS event, send, edit, until)
• Clarify what modes are for and what vi_normal and vi_insert are supposed to be. Their meaning is not immediately clear to a regular Vim user.
• Make casing consistent between docs and command output and default_config.nu.

[fdncred]

@chtenb should we close this now that your issues are landed?

[chtenb]

I see that the 2nd bullet from my previous post has been resolved by 95cf90c. I've marked it as such.
But I think the status of the 1st and 3rd bullets have not changed.

[fdncred]

the 3rd bullet on case is a non-issue because any case works for keybindings. I'm not sure what to do about your first bullet.

[chtenb]

As far as I'm concerned you can treat this issue as feedback from a new user about frictions and confusions in the experience of adopting a new tool. If you feel that the complaints are ungrounded or addressed adequately, feel free to close the issue.