16

Should keys represented with <kbd> tags be always uppercase?

In this edit to "Delete from cursor to end of line in vi" d$ was changed into D$. I thought the answer was incorrect since d and D commands are different in Vi; I had to read the edit note by AdminBee to understand the reason for the change, namely

Keys are labelled uppercase, so "uppercase D" should be "Shift"-"D" in tags.

Although it makes sense, I think it does more harm than good. I want to roll it back, but first I'd like to invite more opinions.

4
  • 1
    Isn't the capitalization critical here? The comments say "shift-D is a synonym for d$".
    – Jeff Schaller Mod
    Aug 3 at 15:21
  • 4
    Not all keyboards have uppercase letters, not even all physical keyboards. Aug 3 at 16:16
  • 1
    Following that reasoning, the suggested D $ should really be D shift-4, which would be very difficult to argue as a better idea than d $. Aug 4 at 0:34
  • 4
    @RayButterworth, but shift-4 gives the € sign... well, on my keyboard layout it does :) Especially for special characters one shouldn't assume their placement
    – ilkkachu
    Aug 4 at 7:59
15

In this case, definitely no. In particular, showing a command as DW is misleading; D already does something different than dw.

Also, vi is a terminal program, it doesn't see keypresses as such, only characters. It doesn't care if you use Caps Lock instead of Shift to get the uppercase D, so presenting the command as Shift+D is beside the point too.

I took the liberty of editing the answer. The original didn't have the <kbd> tags either.

That said, I would write ^D Ctrl-D Ctrl+D Ctrl+D and such with an uppercase D, because uppercase letters are somewhat easier to tell apart, and I think it's commonly understood that something like that doesn't involve Shift. Also I'm pretty sure Caps Lock doesn't usually affect that use.

(Of course someone could make weirder changes to their keymap, as in arrange for Ctrl+A to send a ^Z instead, but that's likely to be rather unusual.)

1
  • "I think it's commonly understood that something like that doesn't involve Shift". I agree, but there's one nit-picky technical complication though (anyone knowledgeable enough to run into it will quickly figure it out). [ctrl-U]0e3f can be used to enter Thailand's bhat currency sign, "฿", but an unshifted [ctrl-u] will (in VI) delete everything up to the current cursor. In that case: shift + ctrl-U should be used to make the required shift obvious. Aug 4 at 13:28
9

I agree with @ilkkachu's answer that in this case, the original typesetting of the answer using "code" formatting rather than "keystrokes" makes more sense, and my edit should probably have been to revert to that typesetting. Still, we need to find a consistent style on how to represent keystrokes.

I have the impression (but cannot back it up with statistical evidence) that a widely accepted convention - which in particular novices will have often seen - is that a key combination statement written as Ctrl+C means to press the "Control" key and then the "c" key without shift, and if a "Shift" key were needed, write this as Ctrl+Shift+C, and that this is the case because on many keyboards, the keys are labelled upper-case. So, I would vote in favor of this representation when expressing key combinations as used in keyboard shortcuts, but not when it comes to entering commands on text entry prompts as in vi or less.

A similar problem is the representation of "key strokes" vs. "key chords", i.e. how to distinguish a key combination where the keys have to be pressed simultaneously (or the later ones at least while the former ones are still down) from a combination where one of the keys has to be released before the later keys are pressed. One could think about using Ctrl-X to mean one thing and Ctrl+X to mean the other thing, but again a consensus is needed for which means which.

Or, we could opt to remove the keystroke typesetting altogether and adopt the notation used in the Emacs documentation (although - as also noted by @Quasimodo in a comment - it is not easy to understand for people inexperienced with Emacs, which likely make up a majority of possible readers).

5
  • 3
    §2: I also have that impression. I can see that Ctrl+X and Ctrl+Shift+X notation on Firefox and GIMP menu bars too. $3 I think the <kbd>Ctrl</kbd>+<kbd>X</kbd> suggestion harms readability, especially when there are lots of keys, and typing those tags are a true pain on itself. §4 I think Emacs' notation is the best, but certainly a bunch of people unacquainted with it would be confused (the "oh, C-x... that must be (shift) c hyphen x" sort of mistake).
    – Quasímodo
    Aug 4 at 20:04
  • 3
    About "key chords": <kbd> can be nested, see how it looks in one of my answers on SU. Aug 6 at 20:41
  • 1
    As a non-emacs user, what is the notation to which you're referring?
    – roaima
    Aug 10 at 11:21
  • 3
    @roaima the same notation as is used in bash’s readline documentation ;-). C-x for Ctrl+X, M-y for Meta+Y etc. Aug 12 at 10:14
  • 1
    My understanding and experience with most documentation I have seen for the purposes of distinguishing chords from sequences is that + and - are interchangeable and represent chords (e. g. Ctrl-A for screen's escape character, while , represents an unchorded sequence, e. g. Ctrl-A, d or ^A, d for the sequence to disconnect a screen session).
    – DopeGhoti
    Aug 16 at 14:27
8

Should keys represented with <kbd> tags be always uppercase?

No — they should probably represent the exact case that is needed for the function. Where it could be confusing (i vs I vs l vs L and o vs O vs 0), it might be worth a parenthetical to spell out the letter.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .