9

EDIT

I have now accepted the answer at the, other question. When rejecting edits which go the wrong way, link to that question.

Overall, I have no plans of editing questions/answers to change the key notation. This settling is a guideline we can follow when accepting or rejecting suggested edits, and it's a way to avoid back-and-forth edits in this regard.


Please note, this is a proposal. I have no decision power. I'm just trying to settle this matter, because some edit proposals have been poping up to convert between the two, and we need to know whether to accept them or not.

2 or 3 weeks ago, I posted a question here asking "Should we use the kbd tag or not?".
It is time to settle the matter.

The voting was very important, and had it been a landslide there'd be nothing to discuss. But it seems somewhat close. The two most voted propositions, which I'll refer to as Yes (17) and Mostly Not (12), had a difference of 5 upvotes from a total of 29. I'm not a statistician, but I'm fairly confident that, with a pool as small as 29, a difference of 17% does not incur much confidence (in fact, see Dan's comment below).

Therefore, I find it important we take other factors into consideration.

Primarily, the majority of answers I've seen so far use backticks, not the <kbd> tag. This would seem to indicate most of our frequent answerers prefer the backticks. Obviously, they'd be the ones most affected by this. Imposing something they find inconvenient1 (even if not enforced tyrannically) is a bad idea.

Secondly, backticks are more concise to write and should be perfectly familiar to Emacs users.


Thus, I propose we adopt the Mostly Not option. Which says, in short:

Just use backticks, unless specifically referring to physical keyboard keys.

For instance:

M-1 is Alt+1 on your keyboard.


1: “They could just write their answers in Emacs“ is not an answer to this. People use Emacs in a bajillion different ways, don't expect anyone to use it the same way as you do.

| |
  • 2
    This question is a proposal. I'm in favor of the proposal (as I've said before). And not only for the reasons you give here, but also for the reasons I gave in the original thread - in particular, keeping it simple and coherent with Emacs's own notation, which is the same for keys and symbols. Do you need only an upvote for this, or do you need a separate answer supporting it? How is this proposal to be voted on/counted? – Drew Oct 19 '14 at 20:51
  • @Drew I didn't make a separate answer myself because I didn't want to imply this would be another vote. Feel free to make an answer in support. I'm just asking here to make sure there isn't a strong opposition. – Malabarba Oct 19 '14 at 21:13
  • I supported it just now, in my comment here (and in the previous thread). And I upvoted this "question". – Drew Oct 19 '14 at 22:21
  • 2
    Aside: based on a binomial test, there is no statistically significant difference between the yes and no votes (p = .46). In R: binom.test(17, 29, .5). – Dan Oct 21 '14 at 14:43
  • Info: We are still getting edits that change only the notation, replacing ... by <kbd>...</kbd>: 1, 2, 3. – Drew Oct 21 '14 at 19:57
  • 2
    Do we really need a formal policy for this? Who is supposed to enforce it anyway? – user227 Oct 21 '14 at 19:58
  • 3
    @lunaryorn I don't plan to make any edits either way. I just want a guideline I can follow when accepting/rejecting suggested edits. – Malabarba Oct 21 '14 at 20:06
  • 1
    I think you're using an argument about stats being non statistically significant the wrong way. You're right in saying 17-12 is not a scientific proof that the poll population prefers backticks. But it certainly doesn't indicate that it prefers it the other way. – Nikana Reklawyks Oct 22 '14 at 22:20
  • @Drew: If the problem we have is too many suggested edits changing nothing but notation, I suggest a policy of rejecting notation edits. I find it very different from a policy of prefering backticks. – Nikana Reklawyks Oct 22 '14 at 22:22
  • 1
    @NikanaReklawyks: It is not an argument for preferring one or the other. It is an argument for establishing a policy/convention sooner rather than later. OR, as you say, make clear to everyone that they needn't bother with such edits, and disallow them somehow (e.g., finding a way to avoid having people have to manually review & reject them). – Drew Oct 22 '14 at 22:32
7

the majority of answers I've seen so far use backticks, not the tag. This would seem to indicate most of our frequent answerers prefer the backticks.

I suspect "kbd tags are inconvenient to type" is the biggest reason for that.

I know some folks dislike kbd tags for other reasons, so it's not the only factor; but I do expect their usage would be much more prevalent if there was a common solution in place which made them simple to use.

It's also true, as you point out, that not everyone will use the site in the same way; however I suspect a combination of some common elisp (for those composing in emacs) and a common user script (for greasemonkey and similar, for those composing in a browser) could virtually eliminate the "inconvenience" issue for the majority of users.

(And for users who prefer the look of backticks, styling the kbd tags the same way could even be a user option.)

We don't have any such support libraries at present, but personally I'd be disappointed if we "banned" kbd tags in the meantime. i.e. I think any such decision would best be based on the desirability of the output -- and we can then determine whether we need to do something extra to make that output easy to achieve in practice.

If the driving motivation for a quick decision is "some edit proposals have been popping up to convert between the two, and we need to know whether to accept them or not", that's easy enough -- the original author should decide whether or not to accept (or keep) the edit. It's their answer; they can make the call.

| |
  • Firtly, sorry if I gave the wrong impression, but this is not a hasty decision. I opened that question 3 weeks ago, the suggested edits just reminded me it was still open. – Malabarba Oct 21 '14 at 8:14
  • 1
    Secondly, I understand your points on scripts and styling, but I just think it would be unwise to ask that of people. Scripts like those would have to be posted here at meta (they can't be anywhere on the main site) so a lot of people will never even see them. We need to aim for the path of least resistance, and then we can offer improvements on that. In my opinion, it's not wise choose a path that imposes inconvenience, and then offer ways to diminish that inconvenience. – Malabarba Oct 21 '14 at 8:22
5

Personally, I favor (and have been using) the approach @phils describes in this answer because I find that it leads to text that is very readable.

At the same time, I am very much in favor of settling on a standard notation, and I'd be willing to adopt the backtick notation if that is going to be the final decision.

However, I am posting an answer here because I'd like to suggest a small addition/modification to the backtick notation:

If we are going to use backticks, can we please separate units that logically belong together with whitespace? This is especially important for (a) longer sequences of keystrokes and (b) sequences that mix specific key bindings with text that needs to be entered, e.g., in the minibuffer.

Two examples:

  1. C-a C-SPC C-n M-w

    vs.

    C-a C-SPC C-n M-w

  2. C-x C-f ~ / . e m a c s RET

    vs.

    C-x C-f ~/.emacs RET

I find it very hard to parse long key sequences if individual units are not separated visually.

| |
  • 4
    Example 1 seems equally readable in both flavors to me. I find the 2nd version of example 2 much more readable than the first one. But as far as I understand, it doesn't separate keystrokes with whitespaces. But it is not really a problem, a command or a filepath is an atom, not a concatenation of keystrokes. By the way, in my opinion, C-x C-f ~/.emacs RET would be equally readable (aka with whitespace in the backticks). – T. Verron Oct 20 '14 at 12:39
  • 2
    FWIW, one of the main reasons for my approach (in the linked answer) is that it clearly differentiates between the two different types of input, and that distinction is of value to the reader because the two are inevitably used side-by-side on regular occasion. Anything which benefits readability is a good thing. The final example above is the way I usually write things in comments (where kbd tags are not available), as the best fall-back approach in those circumstances, so if we were to standardise on backticks (and I'm obviously against that), this would be my preferred approach. – phils Oct 21 '14 at 0:47
  • 3
    What @T.Verron said! When there is a real risk of confusion - and that is quite rare, one can always separate chars with whitespace. 99.9% of the time, something like C-x C-f ~/.emacs is perfectly understandable, and in any case where it might be confusing, it is simple (trivial) to use C-x C-f ~ / . e m a c s. But your second #2 is a good alternative in that tiny minority of cases where there might be some confusion. – Drew Oct 21 '14 at 18:55
  • 1
    To be clear, I like your second #2. It is a good convention, IMO. – Drew Oct 21 '14 at 19:52

You must log in to answer this question.

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