Improve key rendering in documentation

[neiljp]

There are a few improvements we can make in the script which generates docs/hotkeys.md; some of the same changes could be added to the rendering of keys in the help menu too.

• space-separated keys (page up/down) are rendered as separate keys in hotkeys.md - they should be one key
• we may wish to capitalize or otherwise rename some keys, from those understood by urwid to how they should be rendered
• in particularly we should consider adding extra symbol text to some keys, eg. ←, ↑, →, ↓ (left ←?)
• we might discuss this, but it can be useful to show P as shift+p (or even shift+P?) [noted in docs: New user tutorial #221 #922]

Other ideas are welcome :)

update First two points fixed by d65cbee from #1479,

[Ezio-Sarthak]

Apart from the 2nd checkbox (which I don't seem to follow clearly), other improvements seem to be reasonable. I'd happy to push a PR for this :)

EDIT:
@mkp6781 This is related to your work on script generate_hotkeys.py. Are you planning to take this up? (Apologies for wrong mention before 😅)

[neiljp]

The second checkbox is a simpler version of the third really, namely if urwid only generates tab but we wished to output Tab; the third point might have us adding a tab representation, if that's appropriate, or as indicated there, extra arrow keys.

[Ezio-Sarthak]

Makes sense. I seem to have resolved the first part by a one-liner change :)
We might discuss the 4th aspect, as you said, in CZO (others too) in any case 👍

[Ezio-Sarthak]

The second checkbox is a simpler version of the third really, namely if urwid only generates tab but we wished to output Tab; the third point might have us adding a tab representation, if that's appropriate, or as indicated there, extra arrow keys.

So, potentially something like help_keys, in addition to regular keys parameter in KEY_BINDINGS ?
(help_keys being stored to display in UI, and regular keys for internal operations?)

[neiljp]

Yes, one approach could be to have an extra field, but then we risk having them getting out of sync. I think when discussing this on the stream with @mkp6781 I suggested having a general lookup table for rendering (just hokeys.md, or help too) - that avoids the synchronization issue with another layer of indirection (https://en.wikipedia.org/wiki/Fundamental_theorem_of_software_engineering)

[neiljp]

Regarding the fourth point, the webapp takes the shift + <uppercase visual of key> approach, though I think there was definitely a time when this was not the case. For hotkeys.md that seems pretty useful, but it seems less obvious within the application since the text is less styled and more obvious? (though of course then we'd have different representations which could be confusing)

[Ezio-Sarthak]

@zulipbot add "further discussion required"

[mkp6781]

* space-separated keys (page up/down) are rendered as separate keys in `hotkeys.md` - they should be one key

Just to clarify. Is this only regarding page up/down or in general. Before having the automation script, most of the space separated keys were rendered separately apart from maybe one or two(like Alt Enter).

[mkp6781]

@mkp6781 Are you planning to take this up?

You can go ahead with it @Ezio-Sarthak. 👍🏼

[klfoulk16]

Regarding the fourth point, I've updated the getting started tutorial to use shift p (in a row with no plus)...shall I update it to include the plus? I feel like previously we didn't use that but now I see all of the hotkeys have that plus.

Are we planning to use this method for all uppercase hotkeys? Originally I know we were discussing P because p and P look similar, but s and S (narrowing) also have the same issue.