Rewrite keyboardModifiers.adoc #875
Conversation
The main purpose of the page Language/Functions/USB/Keyboard/keyboardModifiers.adoc is to list the macros representing keys. Refocus the text accordingly.
Language/Functions/USB/Keyboard/keyboardModifiers.adoc contains a long list of macros corresponding to keys. Make this list easier to parse by organizing the keys into meaningful groups.
In Language/Functions/USB/Keyboard/keyboardModifiers.adoc, add
explanatory notes for keys with ambiguous names:
- KEY_{LEFT,RIGHT}_GUI are the OS logo keys, "command" on Mac
- KEY_{LEFT,RIGHT}_ALT is "option" on Mac
- KEY_RIGHT_ALT can be labeled "AltGr".
|
@per1234 Who should review this? |
|
Bump! 😉 Sorry for being pushy, but Keyboard 1.0.4 has been released right now (thanks @facchinm!). This release brings some user-visible features that should be documented: new keyboard layouts and new I am going to prepare a new pull request that brings the documentation of the Keyboard library up to date with release 1.0.4. As that pull request will add significant content to keyboardModifiers.adoc, it is going to conflict with this one. Of course, conflicts can always be resolved. However, it would be more convenient for me (read: less work) to have a prompt answer for this PR. This way I may avoid a conflict-rich rebase/merge. |
Apply changes suggested by @per1234 on pull-request review: - fix typo - use common conventions for key names and key combinations - reduce unnecessary verbosity. Co-authored-by: per1234 <accounts@perglass.com>
|
Thanks @per1234 for you prompt and thorough review! I agree with all your suggestions. I grouped them in a single commit that I just pushed. |
There was a problem hiding this comment.
Thanks so much for this valuable contribution @edgar-bonet!
This pull request is a substantial rewrite of Language/Functions/USB/Keyboard/keyboardModifiers.adoc:
The text has been rewritten in order to focus on the main subject of the page, i.e. the macros representing keys. The revised prose tries to answer the questions: What are these macros good for? How would one use them?
The long table has been split, with the keys grouped by key cluster (the physical groups of keys on the keyboard). This should make it easier to find any key one may have in mind.
Notes have been added to keys with potentially ambiguous names, such as
KEY_RIGHT_ALT, which on some keyboards is labeled “AltGr” or “⌥ option” rather than “Alt”.Point 2 is also groundwork for a future pull request: the master version of the Keyboard library adds quite a few more of these macros, which will have to be documented on the next release of the library. Adding the new macros to an already long table would make that table unwieldy.