[] Ideas to improve key binding discoverability

[rswgnu]

At the bottom right of the screen where you show the last command-name invoked, it would be nice to see the key sequence pressed as well, in the same form as you need to give it to the bindkey command. Then one could easily make the associations between key presses and commands and modify from there.

As things stand now, with key bindings spread all throughout the code, I had to grep for addCommand and other terms to find them all, paste them into a document and examine them, as I don't find the organization of the bindings on ^H all that helpful. For example, immediately after learning how to select rows, I expect to find how to filter to just selected rows, but I found that rather buried in the help.

Then I found: visidata/dev/commands.tsv which I think is a better representation and should be available from a help key as well.

Personally, in a mini initial help, I would highlight movement within a sheet and across sheets, selecting/unselecting, filtering/unfiltering, hiding/unhiding columns and rows, and displaying aggregations (describe and histogram commands). If you just emphasize that, people could get started exploring and using visidata much faster, I believe.

[rswgnu]

Another way to look at what basic operations to summarize first is to think in database terms. How do I select rows, project against columns and join/merge two tables. Most anyone who works with tabular data should be familiar with such concepts and want to understand how to do them in visidata when they look at the most basic help for it.

These also tend to be clusters of operations you'd want to be able to do with a mouse, e.g. selecting the rows that match to one or more field values clicked upon with the mouse. Thinking the mouse commands through could significantly upgrade the point-and-click data wrangling capabilities of visidata without having to master a plethora of keyboard commands, which would come later.

[anjakefala]

Thanks for the feedback @rswgnu!

I am investing in improving our local documentation, and I will keep your thoughts in this issue in mind for that.

As things stand now, with key bindings spread all throughout the code, I had to grep for addCommand and other terms to find them all, paste them into a document and examine them, as I don't find the organization of the bindings on ^H all that helpful.

I am curious if you find z Ctrl+H helpful? It is not organised, but it contains the longnames. You could search for select in the longname column to find all the commands that operate on selected rows. The docstrings are also located in there.

I added a link to @jsvine's cheat sheet for VisiData. It will appear on the website's list of references when we next deploy it. I think it addresses one of your concerns about having a curated smaller list of commands that can get a user quickly started. I am also curious if you saw his tutorial? If you did, what did you find that was missing? Maybe I can close the gaps.

I am going to close this for now because improving our docs is already an ongoing priority, but please feel free to continue providing feedback here.

[rswgnu]

Thanks for the feedback @rswgnu!

I am investing in improving our local documentation, and I will keep your thoughts in this issue in mind for that.

As things stand now, with key bindings spread all throughout the code, I had to grep for addCommand and other terms to find them all, paste them into a document and examine them, as I don't find the organization of the bindings on ^H all that helpful.

I am curious if you find z Ctrl+H helpful? It is not organised, but it contains the longnames. You could search for select in the longname column to find all the commands that operate on selected rows. The docstrings are also located in there.

Yes, that command is very helpful. If you could add a character-by-character interactive search (C-s in Emacs), then finding things there would be even easier. I would think about how you could allow people to add and remove key bindings there and then have them written to an automatically maintained section of a user's .visidatarc file. That would really simplify a bit of customizatoin.

I added a link to @jsvine's cheat sheet for VisiData.

The cheetsheet was simple, direct and well-organized. I think that would be much better as the file to display when ^H is pressed or maybe something similar. A table-based layout would be good too.

It will appear on the website's list of references when we next deploy it. I think it addresses one of your concerns about having a curated smaller list of commands that can get a user quickly started. I am also curious if you saw his tutorial? If you did, what did you find that was missing? Maybe I can close the gaps.

What I have seen of the tutorial is good. What if ^H were laid out with sections that mirrored those of the tutorial, with keys/commands summarized under each. Each section would also be a hyperlink to the associated tutorial section. That would quickly increase usage of the tutorial. I really think you should make ^H a prefix key and ^H^H would show the same basic help as ^H does now and then you'd have an array of help keys available for other doc refs including the manual/book.

I am going to close this for now because improving our docs is already an ongoing priority, but please feel free to continue providing feedback here.

In another message I summarized what I thought were the key types of operations to focus on in the initial help screen.

[rswgnu]

I would recommend expanding on the key binding section in the Book of VisiData, clearly documenting a few things, some of which are already done but for completeness:

1. Show an example of unbinding a global command
2. Show an example of unbinding a prefix key.
3. Show an example of unbinding a sheet command.
4. Show an example of binding a global command
5. Show an example of binding a sheet command
6. Show an example of binding a command using different types of prefix keys: ESC, Control-z, ALT-a.
7. Show how to rebind the ^H key and use it as a prefix where desired.

And explain any complexities therein, e.g. how are Control-arrow keys bound, how does one find the strings for different keystrokes?

[saulpw]

Hi @rswgnu, thanks for your feedback and for outlining the work that you'd like to be done. It would be great if you could put together a blog post on this topic that we could link to, particularly explaining what you've learned about how to configure VisiData to be more intuitive for Emacs users. I'm sure there are many Emacs users who would appreciate it!

[rswgnu]

I will publish the key binding setup and an updated, textual form of the cheatsheet when they are suitable for use by others.

[rswgnu]

We need a way to display what a key is bound to. Although you echo commands in the status line, if the command changes sheets, the echo is only visible after quitting the new sheet, so not very helpful.