Styling of Ctrl+ (^) keystrokes in documentation (upper-case or not?)

[reagle]

The Quick Reference Guide has inconsistent casing. Ordinary keys are case sensitive, but control keys are always capitalized? For example: 'g^C' . Not sure why?

[anjakefala]

It was an aesthetic choice, to go with the Shift+ aesthetic. I felt that it allowed the user to better see the connection between e.g. Shift+D and Ctrl+D. It is also a style convention I noticed other publications following.

Quick example: https://support.microsoft.com/en-us/office/keyboard-shortcuts-in-word-95ef89dd-7142-4b50-afb2-f762f663ceb2

[reagle]

Please re-open. The MS resource is consistent, visidata resources are not.

On Visidata, case is sensitive when distinguishing between j and J, but not for any character coming after ctrl.

It should be:

J, shift+J, ctrl+J, ctrl+shift+J (or all the "j"s could be lower case)

or

j, J, ^j, ^J

[saulpw]

There has been an evolution, and over time we seem to be settling on this as the standard:

• j
• Shift+J
• Ctrl+J
• Alt+J
• Ctrl+Alt+J

I understand that the first one is different, but this is consistent with Microsoft's documentation that @anjakefala linked to. J by itself is ambiguous, which is why we are moving to j and Shift+J.

VisiData resources are inconsistent because they have been written over the course of years, and with shifting aesthetics, and to make them all consistent takes time and effort. For example, the quick reference guide is just the manpage, and the manpage is difficult to update, especially when it comes to making things nicely formatted. e.g. it seemed good to me that the H J K L slide commands all fit on a single line, because there's very little content there; it's just slide in different directions. But Shift+H Shift+J Shift+K Shift+L breaks that formatting and makes the whole line more cumbersome and less readable. I think it's reasonable to be moving to the consistent form above, and that means the manpage will become a lot less compact, which I guess is fine overall; most people just search for keywords anyway. And probably the manpage will be less important once there is a searchable command palette as you've been asking for. And if we are going to update the manpage significantly, it also deserves a reworking to make it easier to update, which would be a much bigger lift too. So we haven't made a dedicated effort to it, just moving to the newer formats as we write or update docs.

Are you interested in helping migrate the manpage, or update other places you've noticed these discrepancies? That would be really helpful, and I would definitely send you a foil VisiData sticker for the effort :)

[reagle]

BTW @anjakefala, I'm trying to create an Anki deck for visidata keyboard shortcuts.

[reagle]

I might be able help. Yesterday, I tested converting the cheat sheet into an Anki deck, and based on the experience worked on the manpage today. I _think_ I have the shortcuts: - in unambiguous comma-delimited sequences with special keys spelled out: <kbd>z,Shift+Y</kbd> yank - they are tagged with their type visidata::row::editing - they are broken into "basic" and "advanced" TSVs. https://reagle.org/joseph/2023/03/visidata-commands-mnemonics-basic.tsv https://reagle.org/joseph/2023/03/visidata-commands-mnemonics-advanced.tsv This format could be convert to "unix style" (e.g., `zY`) programmatically, for use in the manpage if that's desired. (Though I'm obviously missing subsection and other comments, and no doubt have bugs and such.) Ideally, this data would be extractable from the source code and used to generate documentation programmatically. Or perhaps in a TSV/markdown/RestructureText document that can generate a manpage or other documentation? I use markdown/pandoc, but I'm not familiar with any of this app/docs toolchain stuff. —Joseph

[saulpw]

This is useful, and I agree, I'd love to figure out how to unify this and the HelpSheet of commands at z Ctrl+H. Maybe we can just take your descriptions as the helpstr for the commands and write a short script to generate? I've been thinking that the helpstrings for the commands can be expanded, to a few sentences even, and we can have them show up in the sidebar as you use the upcoming command search tool (and they're also in the menu already, of course).

[reagle]

My help strings are from the man page. My time was spent on organizing and translating the key sequences into standard format. (Also, adding a few mnemonics.) I think that’ll suffice for the SRL deck. Could you point me to the code with the help strings and shortcuts? Or are they spread throughout the code?

[saulpw]

Ah okay. We should unify the manpage and helpstrings then too, as part of the eventual manpage effort.

To list the commands, use git grep Command, and you can further grep by longname or even keystroke. Is the only problem with the keystrokes on z Ctrl+H that they aren't separated with anything? I'm open to changing the internal keystrokes spec for 3.0, we could maybe even hack something together to allow both formats for plugins. If we changed the internal keystrokes for all commands to be space separated, then we could generate these .tsvs from a list of the commands by tag, would that work?

[reagle]

I was looking around at style guides and see lots of variations, and then lots of inconsistencies in implementation. (And I find little about how to do key sequences in Windows-style.) I was also looking at the visidata source for guidance, but I'm confused there too. In this example I think Alt+h is the default binding (with lowercase "h") but Ctrl+H is added (with a capital "H")?

visidata/menu.py

510	BaseSheet.addCommand('Alt+h', 'menu-help', 'pressMenu("Help")', '')
511	BaseSheet.bindkey('Ctrl+H', 'menu-help')

I'm most familiar with Sublime Text's keybinding syntax, which is fairly well specified and I use weekly. I decided that's what I'm going to use for the Anki deck for now.

I'm going to work through the deck this week, add mnemonics and tweaks where apt.

If it becomes possible to have a TSV of extracted specifications from the code, I might be of help on a documentation workflow (I'm somewhat familiar with pandoc) that makes generating up-to-date documentation easier. (I don't know if Sphynx can do that...?)

[reagle]

I defer to you, of course. I think the zen of python applies nicely to specifying key sequences; simple, explicit, and singular is easiest for newbies like myself. (That is, whatever vd uses, all the documentation uses too. So please don't bother with sublime syntax on my behalf.) BTW: the cheat sheet is inconsistent (Ctrl-q and Ctrl-B); the tutorial using caps for shift sequences (Shift-F) and lower for other modified keys (Control-h), but it is at least consistent in this. 😄

[saulpw]

Well, we can appeal to @jsvine to apply a consistent keybinding style to his cheat sheet and tutorial, and he may decide to follow along (or not).

[jsvine]

Thanks for flagging! Cheat sheet updated and should now be consistently Ctrl-[lowercase].

[saulpw]

Just FYI, @jsvine, VisiData is standardizing on Ctrl+[uppercase]. One of @reagle's complaints here was that our documentation was inconsistent with the tutorial and cheat sheet.

If we all want to come together and embrace something different, I'm not entirely opposed. I've settled on Ctrl+X for some reasons probably similar to Microsoft's, but Microsoft is not exactly known for their taste, so maybe we can choose a different tack. (more work at this point though).

[jsvine]

Ah, I see. Thanks for the clarification! I'm personally of the other persuasion — that the lowercase version removes potential ambiguity about whether the user is expected to also press Shift. I don't mind VisiData taking another direction, but will probably keep the independent tutorial's approach as-is.

[ryanprior]

Emacs keybinding style for docs and tutorials would be j, J, C-j, C-J, etc. You don't call out shift explicitly, you capitalize the letter or not, even when combined with modifier keys. Maybe irrelevant here but a data point in any case.

[reagle]

That’s a nice system indeed: https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Sequences.html