Investigate how to document keyboard and mouse gestures on macOS

[lassoan]

Check how Control/Command keyboard shortcuts are documented in other cross-platform software (Adobe, Microsoft, etc.) so that we document these differences in shortcuts similarly in Slicer.

Differences include:

• Control/Command key modifier is swapped on macOS compared to Windows and Linux
• Right-click on macOS is often available as Ctrl-Left-click
• There is no Alt key on macOS, it is often mapped to Option

[FatouBintou22]

In many cross-platform software programs, notably those from Adobe and Microsoft, keyboard shortcuts are generally documented to reflect the conventions of the respective operating systems, while maintaining consistency wherever possible.

• General information about keyboard shortcut documentation in Adobe products like Photoshop, Illustrator, InDesign:

1 Key Modifiers:

• Windows: Ctrl (Control) is commonly used as the primary modifier. For example, Ctrl+C for copy.
• macOS: Command (⌘) is typically the main modifier. For instance, Command+C for copy.

2 Right-Click:

• Windows: Right-clicking is standard and does not require an additional modifier.
• macOS: Right-clicking can be simulated by clicking with the Ctrl key held down or using two fingers to click on a trackpad.

3 Alt/Opt Key:

• Windows: The Alt key is often used as a modifier in keyboard shortcuts.
• macOS: The Alt key is usually mapped to the Option key. Alt+C on Windows might be equivalent to Option+C on macOS.

4 More about the default keyboard shortcuts: link here

• General information about keyboard shortcut documentation in Microsoft products such as Outlook, Teams, Excell:

1 Key Modifiers:

• Windows: Ctrl (Control) is commonly used as the primary modifier. For example, Ctrl+C for copy.
• macOS: On Microsoft products running on macOS, the Command key (⌘) is typically used as the main modifier.

2 Right-Click:

• Right-clicking is a standard action on both Windows and macOS and is often used to access context menus.

3 Alt/Opt Key:

• The Alt key is often used as a modifier in keyboard shortcuts on Windows.
• On macOS, the Alt key is equivalent to the Option key.

4 More about the default keyboard shortcuts:
General link here
Outlook link here
Note that all Microsoft keyboards are equipped to perform shortcuts in Windows and other Microsoft applications.

[lassoan]

Describe both Windows and Mac everywhere:

• Adobe products: https://helpx.adobe.com/photoshop/using/create-documents.html
• OnShape: https://cad.onshape.com/help/Content/shortcut_keys.htm
• Chrome: separate table for Windows&Linux, Mac - https://support.google.com/chrome/answer/157179?hl=en&co=GENIE.Platform%3DDesktop#zippy=

Only describe Control:

• Microsoft products: https://support.microsoft.com/en-us/topic/keyboard-shortcuts-f2302f54-02a3-a62b-36ef-74ee5a83cb87
• GIMP: https://docs.gimp.org/quickreference/gimp-keys-en.pdf
• Blender: https://docs.blender.org/manual/en/latest/interface/keymap/introduction.html

[pieper]

Visual studio code provides different cheatsheets for each OS:

https://code.visualstudio.com/docs/getstarted/tips-and-tricks#_keyboard-reference-sheets

For their online documentation it seems they embed a code snippet that dynamically changes the document based on what OS your browser is coming from:

https://github.com/microsoft/vscode-docs/blob/main/docs/getstarted/tips-and-tricks.md?plain=1#L80

If we think it's worth it we could do something similar with readthedocs.

[jcfr]

re: vscode documentation

They are indeed processing the kb(shortcut-identifier) to generate HTML as well as javascript dynamically updating the page based on the current user agent and the bindings organized in json files¹.

That said, after inspecting the microsoft/vscode-docs repository, it looks like the corresponding infrastructure is organized in a private project called microsoft/vscode-website²³

getstarted/keybindings#_basic-editing

https://code.visualstudio.com/dist/index.js

Footnotes

1. https://github.com/microsoft/vscode-docs/tree/main/build/keybindings ↩

2. https://github.com/microsoft/vscode-docs/tree/main?tab=readme-ov-file#publishing ↩

3. https://github.com/microsoft/vscode-docs/blob/f4abacbb8094f1991e2f754b77764bd317115909/gulpfile.js#L12 ↩