26

NOTE: Before commenting here, please see May we settle on using backticks for key descriptions?


When describing key bindings, should it be preferable to use C-x instead of C-x? That is, use the <kbd> tag instead of backticks.

I've rephrased this question so we can discuss it in the answers. Any opinions and such can go in the comments and we can adapt the answers accordingly.

People can up vote the one they agree with, and in a couple of weeks we can check the number of up votes and disregard the down votes.

  • I think kbd won the voting, and should've won the green mark. @Drew: I say it because its number of votes is higher than the number of votes of the other option, which is the way voting usually goes. – Nikana Reklawyks Oct 22 '14 at 22:18
  • @NikanaReklawyks: How do you figure that? I'd say it's 25 to 6 in favor of ..., and kbd loses: 11 for Jon E + 11 for Gilles + 3 for mine = 25; versus 6 for Phils. The 16 for Malabarba don't count either way, as his answer just lists both pros & cons - it does not clearly opt for one or the other. And the 6 for Asmeurer don't count either - that answer is independent of the choice. But if you read all of the comments everywhere, I'd say it is closer than 25 to 6. – Drew Oct 22 '14 at 22:28
  • @NikanaReklawyks: I think the voting on this is unclear. There is a lot of other stuff in the posts & comments. Hard to boil all of that down. I particularly think that itsjeyd's ... examples (other page) should be considered. My 1st choice would be #2b, then #2a/#1a - not #1b. We should start a new vote, with just those options plus one or more <kbd> options: maybe allow 2 votes per person (1st & 2nd choice). Separate any discussion, arguments, examples, etc. from the candidates and their votes. – Drew Oct 22 '14 at 22:42
  • @Drew: The way you say to count, you're counting many same persons' votes twice or more (as more answers defend one view, and a single more upvoted answer goes with the other). Votes (usually) consider the one most voted-for candidate to be the winner, in this case, Malabarba's. I think Malabarbas's answer is in favor of <kbd> (it's first line goes "kbd is useful because ..."). I do agree we should have a proper vote on this (and then, reject all edits on this sole matter). – Nikana Reklawyks Oct 22 '14 at 22:45
  • @NikanaReklawyks: Yes & no. If 3 "answers" argue in favor of one approach, and 3 people vote for only one of those answers each, then those 3 votes should be added together. Interpreting the "votes" here is deeply flawed. The "answers" voted for are themselves not exclusive proposals one way or the other but mixes, together with mixes of arguments. What should be done is what I just proposed: have a real vote, and separate (a) the 4 or 8 or N clear notation candidates to be voted on from (b) posts that discuss pros & cons etc. What we have so far is useless, in terms of "counting". – Drew Oct 23 '14 at 2:15
  • @NikanaReklawyks: I personally favor one or two of the notations that have been proposed, but I think what gets decided on should serve only as a guide, and we should let users denote key sequences however they like. Edits for clarity are fine. Edits from one notation style to another should be proscribed or discouraged. IOW, let's decide on what we think is best, but let's not insist on it, and let's discourage notational edit wars. – Drew Oct 23 '14 at 2:19
  • @NikanaReklawyks: We should also avoid adopting any notation for which we have not yet found solutions wrt (a) difficulty writing or (b) inability to use everywhere, including in comments. If <kbd>...</kbd> is to be used for more than the occasional physical keyboard key representation, then SE first needs to provide technical solutions that make it really easy to use. It makes little sense to adopt something that is unusable in some contexts or that will be ignored by most users because of its difficulty. – Drew Oct 23 '14 at 2:24
  • @NikanaReklawyks See meta.emacs.stackexchange.com/q/160/50 for the reasoning behind the current accepted answer. Statistically speaking, the vote was a tie, so others factors were weighed in. – Malabarba Dec 2 '14 at 19:02
19

I've never much liked the <kbd> notation either as an author or a reader. Many sites (notably Apple.SE) use them extensively and I can definitely understand the allure. But it should only be used when it increases the readability of a post. Examples:

You need to be in Text mode: M-x text-mode. (On your Mac, M-x is option + x.)

If you map Caps Lock to Ctrl in your OS, you'll find it much easier to type C- chords.

How can I bind a command to F5? I tried M-x global-set-key RET F5 RET and now when I press F the 5x5 puzzle is invoked. What am I doing wrong?

Since Emacs uses keyboard chords extensively and since there are so many variations of how the keys are labeled on keyboards, I'd suggest that M- and C- are generally the least ambiguous ways to express the concept. Unless the context of a post is specific keys on a specific keyboard, resist the temptation to use <kbd>...</kbd>.

  • 2
    Maybe this is again a formatting issue. If <kbd> could be rendered in such a way that it doesn't stand out as much but still renders distinctly from monospace, I think it would be worth having. – asmeurer Sep 24 '14 at 17:19
  • 6
    @asmeurer: I'm not so sure. I purposely picked examples that require specific keystrokes. I've bound C-x C-m to execute-extended-command, so when I read documentation, I mentally (and subconsciously, now) translate M-x into Ctrl+x Ctrl+m when I type. Using images of keys, especially when the image does not match what's on my keyboard, breaks the abstraction. I'd also argue for using the Emacs manual's conventions unless there's a compelling reason not to. – Jon Ericson Sep 24 '14 at 17:30
23

The <kbd> tags are useful because they differentiate from inline code. That's good for the following reasons:

  • Of the following two sentences, I find the second reads better.

    1. "Hitting C-t invokes transpose-chars but C-x C-t calls transpose-lines.
    2. "Hitting C-t invokes transpose-chars but C-x C-t calls transpose-lines.
  • They work as eye guides. Again, refering to the sentences above, I find it a breeze to run my eyes through the second sentence.

  • Code tags are slightly overburneded already. At other SE sites they are used not only for code, but sometimes for package names and directory names.

  • They also look pretty. This is completely subjective, of course. Do people agree or disagree with this?

Problems

  • It's a pain to type.

  • Its appearance might not be consistent throughout browsers.

  • Is it platform-dependent? Here (chrome on linux), the text is reasonably sized, but the text in the kbd blocks is too small to be deciphered "in a breeze". – T. Verron Sep 24 '14 at 14:01
  • 6
    I also find it harder to read. It would help if the kbd element was restyled with a larger, fixed width font. That way it would more closely resemble the appearance in the info reader, so giving the benefit of familiarity. – dcorking Sep 24 '14 at 14:38
  • 2
    Both good points. Styling the appearance might be possible before the site goes live, that would also address any inconsistencies. At the moment, it's an issue. – Malabarba Sep 24 '14 at 14:42
  • It is much better to mirror the Emacs convention, which applies equally to keys, symbols, etc. Info and doc strings should point the way. – Drew Sep 26 '14 at 4:06
  • @Drew what do you mean by that? Are you talking about the C- and M- conventions? I'm not arguing about that. – Malabarba Sep 26 '14 at 6:26
  • @Malabarba: No, I meant only that Info doc and doc strings enclose key sequences and symbol names (functions, variables, faces,...) in ` and '. And here we would do similarly, but with ` replacing ' at the end. – Drew Sep 26 '14 at 21:46
  • 2
    Granted, "It's a pain to type", but that's not a big deal, and easily dealt with if you compose your answers in Emacs. "Its appearance might not be consistent throughout browsers" is a non-argument -- the appearance of anything on the web may not be consistent between browsers. – phils Oct 1 '14 at 7:39
  • 1
    Using such a mix (key sequences as raised blocks; code as simply shaded) is not only inconvenient. It is also ugly, IMO. There is no good reason to adopt it, IMO. Keep it simple and convenient, and coherent with Emacs notation. – Drew Oct 8 '14 at 2:19
18

I don't think the kbd tag is appropriate for Emacs key sequences, but it's admittedly a gray area. I use kbd for actual keys, for example Ctrl+X. But for Emacs key sequences, there is a standard notation: C-x.

In posts that are about the conversion between keyboard keys and Emacs key sequences (the joys of key-translation-map, function-key-map, etc.), distinguishing between keyboard keys like Return and Emacs key sequences like return or RET through typesetting is useful. Admittedly, this isn't a common scenario.

I think it would be good to standardize on either code or <kbd> on this site. But <kbd> isn't obviously the right choice.

  • 3
    <kbd>C-x</kbd> looks better than <kbd>C</kbd>+<kbd>x</kbd>, and imho it does a good job at setting key sequences apart from other inline code. Edit: Oh, great, apparently tags don't work in comments, or did I do anything wrong? – lunaryorn Sep 24 '14 at 12:40
  • 6
    @lunaryorn Apparently indeed, the <kbd> tag doesn't work in comments, which may be a good argument not to use it at all. – T. Verron Sep 24 '14 at 13:59
  • ...which is yet another reason not to adopt it for the general notation (for keys or command etc. names). – Drew Sep 26 '14 at 4:04
  • @lunaryron Definitely agree that having them joined is more clear than separate. And I do like them, since they stand out slightly more, but they do have their downsides – Jonathan Leech-Pepin Sep 26 '14 at 13:15
9

Whichever we use, we should definitely prefer to use C rather than Ctrl, M rather than Meta or Esc, and S rather than Shift. We should also use the dash notation: C-x rather than C+x or some similar (C-x also looks bad to me).

  • 6
    Absolutely. We have no reason to diverge from Emacs notation (and every reason not to). – Malabarba Sep 24 '14 at 16:17
  • 1
    Definitely keep to the C,M,S,s,H notation as opposed to the long forms. Unless in a situation where ellaborating what the abbreviations mean and are usually bound do (particularly for super and hyper). – Jonathan Leech-Pepin Sep 26 '14 at 13:17
7

I've tried it various ways over time, and settled on the approach whereby each (potentially-modified) key in a command key sequence is written in standard Emacs notation and wrapped in <kbd> markup, and anything else the user types (commonly at a prompt) is wrapped in backticks.

This distinguishes the command key sequences from other typed text, which I feel makes for the most easily-comprehensible output.

Any concerns about the difficulty of entering the markup would seem to be virtually moot in a forum where every single person writing an answer uses Emacs, given that modern web browsers have extensions to allow you to edit textareas in your editor of choice. Providing some common support elisp for users seems like a Thing We Can Do1.

I agree that the kbd tags should be styled for readability. FWIW, my user style sheet for SO/SE uses the following:

kbd {
  background-color: #e9e9e9 !important;
  border: 1px solid #999999 !important;
  font-weight: bold !important;
  font-family: Courier New, Fixed, monospace !important;
  font-size: 9pt !important;
}

which for me, renders like so:
enter image description here

or at the default font size:
enter image description here

The following is an example from SO:


So first, check to see if you have an existing file.

C-hv user-init-file RET

By default it will show you a file path ending in /.emacs (even if that file doesn't exist), but on the (unlikely, in your case) offchance that it ends in /.emacs.el or /.emacs.d/init.el then it would mean that you have an existing init file at that location.

Load that file with the appropriate one of the following:

  • C-xC-f ~/.emacs RET
  • C-xC-f ~/.emacs.el RET
  • C-xC-f ~/.emacs.d/init.el RET

Or you could load it regardless of where it was with:
M-: (find-file user-init-file) RET

Then you can simply add that line of code to the file:

(setq visible-bell 1)

Save the file:

C-xC-s

And the next time you start Emacs, it will use that setting.

You can also evaluate the setting immediately by typing C-xC-e with the cursor after the closing parenthesis.


1 For starters, a minor modification of Malabarba's answer to I want to have the <kbd> tags for my blog written in org-mode gives us:

(defun my-insert-kbd (key)
  ;; Based on https://emacs.stackexchange.com/a/2208/454
  "Ask for a key then insert its description using <kbd> markup.
Will work in org-mode or in any mode that accepts plain html."
  (interactive "kType key sequence: ")
  (let* ((is-org-mode (derived-mode-p 'org-mode))
         (output (if is-org-mode
                     "@@html:<kbd>%s</kbd>@@"
                   "<kbd>%s</kbd>")))
    (if (not (equal key "\r")) ;; empty key
        (insert
         (format output
                 (mapconcat 'identity
                            (split-string (help-key-description key nil))
                            "</kbd><kbd>")))
      (insert (format output ""))
      (forward-char (if is-org-mode -8 -6)))))

(global-set-key (kbd "C-c k") 'my-insert-kbd)
  • This is indeed much better than the default. – T. Verron Oct 6 '14 at 11:35
  • No, this is worse. It is better to use the same notation (convention) that Emacs itself uses, which treats key sequences and inline code (command names, sexps in general) the same way. In Emacs, that means backquote...quote. In SE it should mean backquote...backquote. C-x C-f ~/.emacs RET. If really not clear enough from the context, you can add spaces to indicate separate keys: C-x C-f ~ / . e m a c s RET. – Drew Oct 8 '14 at 2:11
  • 1
    I don't follow that, Drew. Emacs doesn't use any quoting notation for key sequences. e.g. if you view the help for a command, the relevant key sequence is not quoted (whereas functions and variables are). There's nothing to make me think that we must use backquotes around keystrokes in order to be consistent with the Emacs representation. To my mind the only critical thing is that we use the standard Emacs notation for key chords, and using <kbd> does not preclude that. – phils Oct 8 '14 at 3:46
  • 1
    FWIW, I feel that my approach retains the notation that Emacs uses and improves the clarity of that notation for the reader. That seems to me like nothing but a good thing. I don't believe it in any way detracts from the reader's ability to subsequently comprehend the same bindings as displayed within Emacs. – phils Oct 8 '14 at 4:07
6
  1. I agree with what Jon Ericson said.

  2. I will add this:

    Keys, command and other function names, option and other variable names, face names, and all the rest should use the same notation. Just as they do in the Emacs doc (not the printed manual, but doc strings and in-Emacs Info).

    On SE sites, this means backticks (aka backquotes).

    And you can freely use * and ** with backticks for emphasis:

    • C-u C-x 8 RET
    • C-uN, where N is a non-negative integer...

    We should use the same, simple notation because (a) it is clearer and (b) that is what Emacs itself does. That helps users learn to read and write Emacs doc, to express things the way Emacs does. It is a longstanding, conventional notation for Emacs.

    [It would be handy if we could just paste standard `...' text from Emacs here, without having to manually change the ' to a backquote (either in Emacs, before copying or here, after pasting). That would be so much better for quoting stuff from doc strings, manuals, etc.]


A difficulty with backquotes is to include a backquote inside. You can use multiple backquotes as delimiters; if you use n+1 backquotes as the delimiter then you can have up to n backquotes inside. If the first or last character is a backquote, put a space before/after it (spaces at the edge of code blocks are ignored). For example, to write C-`, use

``C-` ``

You can also use the HTML tag <code>, which can be combined with other markup: C-u N is

<code>C-u *N*</code>
  • Doesn't C-` do the trick (double-backtick and ensure the included backtick does not touch the closing double-backtick)? ref meta.stackexchange.com/questions/55437/… – Jonathan Leech-Pepin Sep 26 '14 at 13:19
  • I like the idea of emphasis and italics within the code segments to emphasize. It distinguishes from functions/variables, would allow for sequences likes **M-x**eshell with the typed command separate from the keystroke. Although apparently this doesn't work in comments either. – Jonathan Leech-Pepin Sep 26 '14 at 13:24
  • In the Markdown variant used on Stack Exchange, to put a backtick in a backtick code block, use double-backtick as the code block delimiter. This is documented if you follow the “Need More Detail?” link in the editing help (that's actually the original Markdown documentation, which SE has somewhat deviated from, but not on that point). So ``C-` ``. You can also use <code>…</code>, which allows you to use <strong> and <em> inside. – Gilles Sep 26 '14 at 17:04
  • @Gilles - OK. I thought I had tried that, but maybe not. – Drew Sep 26 '14 at 19:53
  • @Gilles: Doesn't work for me. I tried to write ` ...', or even just an isolated ` , and did not succeed. I tried ``` `` , for instance, following your model for C-` . – Drew Sep 26 '14 at 21:48
0

<kbd> looks great, and if the styling can be improved it will look better, but having just typed my other answer, it's a huge pain to type. If an answer has a decent number of key actions in it, it becomes much more difficult to type correctly (vs using `). If it's possible to simplify this somehow, we should do so.

  • It is a pain to type. You cannot use it in a comment. Unless you apply it to command etc. names also, you diverge from the simple notation used by Emacs itself (and which we should be teaching users to recognize and employ). And no, it does not look great. – Drew Sep 26 '14 at 4:08
  • 1
    I like how it looks (and have not had issues with display where I've looked at it), but it being inconsistent across browsers is a downside. If there were a simple way to include and differentiate key commands from other commands (to stand out when reading through) it would be useful. – Jonathan Leech-Pepin Sep 26 '14 at 13:19
  • 1
    Well it looks great modulo some styling changes which I'm sure can be made for the final site. – asmeurer Sep 26 '14 at 17:23
  • Dunno what an up or down vote on this answer means. I guess it means that one agrees or disagrees with everything said. I disagree that it looks great (it looks awful - quite distracting). But I agree that it is a "huge pain to type". – Drew Oct 8 '14 at 2:23

You must log in to answer this question.

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