Expand and reformat "Commands and Shortcuts" section in "Workflow Editor" article

[banchan86]

Fixes #108. This PR expands and reformats the "Commands and Shortcuts" for improved readability. At the same time it adds some commonly used shortcuts that are missing. The list of changes:

• Rename commands to actions
  • For a visual language, actions might make more sense than commands
• Adopt pipe table
  • More established pattern for finding actions and keyboard shortcuts
  • Uses less space, especially if we want to add more shortcuts
• Shorten actions names
  • Uses imperative style (link instead of linking)
  • Drops articles (maybe a bit controversial but I feel including them is unnecessarily wordy)
• Split point-and-click actions from keyboard shortcuts
  • Easier to distinguish between them
  • A bit unsure about where to put keyboard modifiers that affect point-and-click actions, but for now I have opted to group them together with the Point-and-Click column
• Shorten and simplify sentences
  • I have kept most of the verbiage in the Point-and-Click column (maybe necessary for novices)
  • Reduced wording in the Keyboard Shortcuts column (fits established patterns, not necessary for more experienced people)
• Format content for consistency
  • Some of the actions make explicit reference to a panel while others did not, I have added a panel item to all
• Add some missing shortcuts

Online preview

[banchan86]

@RoboDoig requested you as a reviewer because I hear you're really fast at live demos 😄 Could you check if I missed any keyboard shortcuts or if you'd like to tweak the list?

[glopesdev]

@banchan86 This is definitely needed, thanks! I will review more carefully, but one thing that jumps to mind is having the keyboard shortcuts column to the side might make it simultaneously more confusing and less visible.

I wonder if we should just have one of these tab interfaces where people can pick which modality they want to consult (keyboard or mouse) and have a separate table for each? This might also make it possible to solve more cleanly your issue with key modifiers in the mouse interface.

Otherwise we can do like VS code and keep all the shortcuts in a handy PDF cheat sheet: keyboard-shortcuts-windows.pdf

[banchan86]

Adopted a tab layout to separate mouse controls from keyboard controls. With the separate tabs there are now some actions with no corresponding control (indicated by N/A), for the purpose of the review I have just kept them in there for now, but for the final edit we can remove them (or discuss if we want to add the shortcut/control to the editor). Also at some point we could point a reference to either this section or a pdf within the editor bonsai-rx/bonsai#2083.

[glopesdev]

@banchan86 I have literally just learned of this, but there are recommended guidelines for referring to keyboard shortcuts in documentation. I have tested the styling of the special tags and they do work in DocFX in both light and dark themes.

We may want to do a general pass through the documentation to replace all of the keyboard shortcut references to use this style as it makes the shortcuts stand out differently from code elements.

To make it easier to wrap keys with the <kbd> element, it is possible to bind the wrapWithAbbreviation command built into VS code into a shortcut, e.g. Alt+W.

[banchan86]

@glopesdev The suggested keyboard styling sounds great, thanks for finding it, and fixing up the style! I will revise this PR and will make a note to catch others that are littered throughout documentation.

[banchan86]

PR updated, I love the new style!

[banchan86]

Oh I just realized that with Bonsai 2.9 there are new shortcuts which have not been added yet, so pause on the review while I work on adding them.

Edit: I am also now discovering that some of them were changed (e.g., Ctrl>+N opens a new window instead of a new workflow) so I will need to re-check the keyboard shortcuts.

[banchan86]

Ok I updated the PR with the new actions and shortcuts for bonsai 2.9.

The list of actions and shortcuts are a bit long, especially on the mouse controls side, I was being comprehensive and wanted to make sure I had the same coverage for both mouse and keyboard controls, but we can drop some of them if they are really obvious ( stuff like pressing X to close a visualizer or window) or are covered in the article already.

Also for the same reason (length) i did not cover the follow controls but they can be added back in for completeness.

Save as workflow (extension) - Ctrl + Shift + S
Export Image - Ctrl + Shift + E
Copy as image - Ctrl + Shift + C
Start without debugging - Ctrl + F5

[banchan86]

Updated based on feedback from DCM!