question: 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.

[benboeck]

Hi @waldyrious you are correct I proposed changes to the original proposal but in discussion with @jedahan they were reduced back to (almost like original proposal):

• Use a plus sign + surrounded by spaces.
• Start special keys with a capital letter, then lower case letters (example: Ctrl).
• Special keys to be pressed on their own (no combination) are also always surrounded by <...> (example: <Esc>:wq<Enter>)
  • Original proposal said: leave those alone but I found <CTRL-x> o and proposed <CTRL + X> o <-- update from original proposal

I would go through the existing pages and try to update deviations from the above rules if this is OK with you.

Other possible changes could then be discussed and would be easier to introduce once the deviations are gone.

[waldyrious]

Sounds great, @benboeck. The changes in your latest comment would be very welcome, and later changes can be discussed in due time. Looking forward to the PR.

[agnivade]

Hi @benboeck - any updates on this ?

[sbrl]

Hey! I think I missed this issue.

I'd vote for the option that looks like Ctrl + Shift + x Ctrl + x.

[Managor]

I would like to restart the discussion in this thread.
The current style guide talks about key presses in the following manner

    When documenting keycaps or a keyboard shortcut for a utility, make it stand out in the description:

    If it is not translatable, enclose it with backticks (i.e. Print the last lines of a given file and keep reading it until `Ctrl + C`:)
    If it is translatable, enclose it with double angled brackets inside a placeholder (i.e. :wq{{<<Enter>>}}).

I assume this is only for the description and not for the command itself. I don't know any pages where this is used in the description. I know in tmux.md and vim.md angle brackets are used to indicate keypresses. I think we need a uniform syntax for keypresses. For starters we need to decide on the syntax for special keys (angle brackets <> are probably good), then we need something to differentiate if keys are pressed together or separately. I personally would for example describe "Expand glob" feature of bash with Ctrl+x, * but I think that's not sufficient for tldr pages.

tldr:

• Need syntax for special keys (angle brackets probably suffice)
• Need syntax for keys pressed together
• Need syntax for keys pressed one after another
• Looking for other syntax needs