Should we use the <kbd> tag or not?

Question

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.

Answer 1

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

Answer 2

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.

Answer 3

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.

Answer 4

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).

Answer 5

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 Do¹.

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:

or at the default font size:

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.

---

¹ 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)

Answer 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>

Answer 7

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