Inconsistencies in keyboard shortcut formatting

[benboeck]

Hello,
writing a new TLDR client I noticed inconsistencies in the way keyboard shortcuts are formatted.

I am willing to go through the tedious task of preparing a pull request unifying them but want to ask for your agreement on a common style first:

---

Using a Ctrl shortcut as example, different formats include the following and more:

• CTRL + K vs. Ctrl + K ("CTRL" in caps or not?)
• CTRL + K vs. CTRL-K (minus sign, no space)
• CTRL + K vs. CTRL + k (lower case "k")
• CTRL + K vs. CTRL + K (format as code or not?)
• Exotics like <CTRL-K>

The same goes for many other keyboard buttons such as Alt, Tab, Enter and so on.

Some examples of different styles in descriptions:

1. common/batch (most used style)
   • Execute commands from standard input (press Ctrl + D when finished):
2. osx/caffeinate (no code formatting, no space, minus sign):
   • Prevent from sleeping until you type Ctrl-C:
3. common/sl (no code formatting)
   • Let the user exit (CTRL + C):

Some examples of different styles in commands:

1. common/micro (most used style)
   • Ctrl + K
2. common/most (angular brackets, minus sign, no space)
   • <CTRL-x> o
3. common/vimdiff (notice the lower case "w")
   • Ctrl + w {{h|l|k|j}}

---

Proposal (aligned with currently most used styles):

1. Use "Ctrl" instead of "CTRL"
2. Use Ctrl instead of no code formatting (use code formatting)
3. Use Ctrl + K instead of other formats (use plus sign, use spaces)
4. Use Ctrl + X, O instead of <CTRL-x> o
5. Use Ctrl + X instead of Ctrl + x (use upper case)
6. Use Ctrl + A / Ctrl + B instead of Ctrl + A/Ctrl + B(spaces around "/" look nicer - this is my personal opinion and currently NOT the most used form)

• Would you agree to some or all of these proposals?
• Would you be willing to accept a pull request unifying the styles?

Thank you,
kind regards

Ben

[waldyrious]

Hi @benboeck. Many thanks for this research and proposal. I am not home at the moment but I'll make sure to reply in detail in the next couple days.

[benboeck]

Hello @waldyrious, thank you for your reply, looking forward to it.

[jedahan]

Hey @benboeck everything about your proposal looks great to me, except the capital letter - it makes me think I need to press Ctrl + Shift + x when i see Ctrl + X. Might just be me, but +1 to making everything more consistent. (and this is really a nit and I'd rather see things get better than bikeshed forever so feel free to ignore).

[benboeck]

Hi @jedahan, I agree with you, this was also my initial reaction. I refrained from proposing a change for the following reasons:

• Looking at the data the Ctrl + X style happens to be the most used one; it would mean a lot more changes to implement (and review!) to switch to Ctrl + x.
• If you are supposed to enter an upper case letter, it says Ctrl + Shift + X.
• It could be easier on the eyes.

That said, I could also totally live with Ctrl + x, provided there will not be any Ctrl + X but only Ctrl + Shift + x.
I could submit the changes if requested (especially looking at the poor reviewers).

[jedahan]

Ctrl + X certainly is easier for me to read, and if it is easier to migrate first to Ctrl + X and Ctrl + Shift + X we can always revisit later if we feel strongly about Ctrl + x. A question to think about:
are we catering to new or experienced commandline users, or rather, which do we care about most? Are people new to the CLI confused by the x/X distinction, or is it a red herring? I can ask a few friends of mine who have taught in and our of schools, workshops, universities, and see if it is a papercut or not.

For the sake of moving things forward, I like your original proposal for now, unless reviewers are excited about lowercase, we can revisit it another time.

[benboeck]

As discussed, I am undecided on CTRL + X vs. CTRL + x - just tell me which way to go and I would prepare the PR if you are willing to review/accept it.

That said, there are other questions, especially in commands (not descriptions) such as:

common/vim:

• <Esc>:wq<Enter>

and common/ed:

• a<Enter>{{text_to_insert}}<Enter>.

How would you want to deal with these?

Proposal:
7) Use Ctrl + X for cases where the Ctrl key is a modifier, stick with <Ctrl> if the button is to be pressed on its own.

[agnivade]

We had discussed this before. We had honed down on a format. But I believe in some pages, this has strayed from the decided convention.

[waldyrious]

We had discussed this before. We had honed down on a format. But I believe in some pages, this has strayed from the decided convention.

Indeed -- that was why I wanted to set out some time to address this properly. There are related PRs/discussions at #1354 and #1356.

After reviewing @benboeck's proposal more carefully, I agree with everything in it. It's actually perfectly in line with what had been previously discussed.

By the way, since we now have a separate style guide, it probably makes sense to include this convention there.
So I'd suggest that we only mark this issue as resolved once (1) the pages are harmonized with regards to the keyboard shortcuts; and (2) the convention is described in the style guide.
Hopefully that would make it easier to keep the standard moving forward.

A question to think about:
are we catering to new or experienced commandline users, or rather, which do we care about most? Are people new to the CLI confused by the x/X distinction, or is it a red herring?

I think the real question is related, but somewhat different: are we focusing on clarity or compactness? This is valid and useful for both beginners and experienced CLI users. IMO, the answer has got to be a balance, as both are primary goals of the project; but in this case, including Shift does not add up too many characters, while it makes it clear exactly which keys are actually to be pressed. I'm strongly in favor of the explicit convention, for that reason. But of course, I'm open to be convinced of the contrary :)

Finally, regarding the use of < -- I believe It would be more consistent if we stuck to using + to signify simultaneous presses, and , for sequential ones.
That said, for tools with command modes like vim, less or man, it might be a bit too busy (and actually less readable) to show Esc, :, W, Q, Enter instead of <Esc>:wq<Enter>. I would not be opposed to using this convention as a compact representation for command sequences of more than 3 keys, where the whole sequence is concatenated without spaces or other combinator characters, < and > are used to separate the special keys from regular keys.
Does this make sense to you guys?

[agnivade]

Ah thanks for digging up the issue @waldyrious !

Yes, seems reasonable. So anything less than 3 keys, we explicitly mention Shift. If there are more, we just write the upper or lower case to clarify.

Thanks for taking it up.

[benboeck]

Hello @waldyrious and @jedahan,
thank you very much for your feedback.

I sway towards Ctrl + k vs. Ctrl + K like @jedahan said. What do you think?

Thinking about consistency and the differences between the two use cases (one key combination vs. a number of key combinations and button presses), what about agreeing on just one style (see 2 and 3):

1. For key combinations:
   1. Use a plus sign + surrounded by spaces.
   2. Start special keys with a capital letter, then lower case letters (example: Ctrl).
   3. Use lower case letters for other keys (example: <Ctrl + k>) <-- This is new and a larger change, do you agree?
2. Key combinations (where two or more Keys should be pressed together) are ALWAYS marked by a beginning/trailing <...>. <-- This would also be a larger change to a number of pages, do you agree?
   • Example: <Ctrl + Alt + Del>
   • This adds consistency and also makes it clear and easy to understand that the keys should be pressed together.
   • It would also work for key combinations without special keys. I don't have an example ready but theoretically, there might be combinations such as <a + b>.
3. Special keys to be pressed on their own (no combination) are also always surrounded by <...> (example: <Esc>:wq<Enter>)
   • This is for the tools mentioned by @waldyrious such as vim.

What do you think?
If I have some hours left on the weekend I could try and go through with it - but the PR would be a pain to review.

Thanks, Ben

[jedahan]

1.i, 1.ii , 3 lgtm. How about we make a minimal amount of changes + a linter for the changes, then propose style improvements incrementally. If we have okay tooling, it should be okay instead of making a ton of changes all at once.

[benboeck]

Hello. great proposal,

• 1.i, 1.ii and 3: OK, I will try and fix the current deviations over the weekend.
• Should I also go for a few 3 instances like commons/most <CTRL-x> o which would become <CTRL + X> o?

This should make future linting easier.

[jedahan]

Yeah that would be nice to move us closer to unified until we figure out exactly where <> is best balanced

[waldyrious]

@benboeck I'm afraid your new comment is not clear to me. It seems as if you're making a number of changes to the initial proposal, whose motivation I can't discern clearly, as well as introducing some new concepts that are ambiguous due to overlapping terminology. In contrast, your initial exposition was crystal clear, so I'm sure we can communicate about this effectively. Would you please take a shot at editing your comment to hopefully make it reflect your thoughts more clearly?

Sorry if my confusion is not clear to you 😅 if so, let me know and I'll try to make a more thorough exposition of what's confusing me.