8

In the Emacs Lisp documentation, I often come across quoted symbols like `buffer-file-name' inside docstrings. The intersting thing here is the style of quoting, by surrounding the symbol name with a backtick and a quote. I was curious where this style came from. According to this answer it could be related to a limited character set.

Another thing to notice is that these quoted symbols have syntax highlighting in emacs-lisp-mode, whereas symbols quoted with only single quotes, for example, 'buffer-file-name', does not get any syntax highlighting.

So this indicates that the backtick-quote syntax has to be a well-known convention in Emacs. But after googling the documentation, I could not find it mentioned anywhere. In the Emacs Lisp manual there is a section named "Tips for Documentation Strings"; it says

When a documentation string refers to a Lisp symbol, write it as it would be printed (which usually means in lower case), with single-quotes around it.

but it does not mention the style of quoting.

Type C-h f thing-at-point RET and then click the link to the source code to see some more examples of the quoting style:

(defun thing-at-point (thing &optional no-properties) "Return the
THING at point. THING should be a symbol specifying a type of
syntactic entity. Possibilities include `symbol', `list', `sexp',
`defun', `filename', `url', `email', `word', `sentence', `whitespace',
`line', `number', and `page'.

When the optional argument NO-PROPERTIES is non-nil, strip text
properties from the return value.

See the file `thingatpt.el' for documentation on how to define a
symbol as a valid THING."

So all this gives an indication that one should use the backtick-quote style to quote symbols, but is this style documented anywhere?

  • 1
    Are you more interested in locating documentation on `quoted-symbols', or do you want to know what they're for? If the latter, it's for cross-referencing purposes: you can click on those symbols in the help buffer, and it will take you to the corresponding help buffer for the symbol on which you clicked. – Dan Mar 7 '15 at 21:49
  • 1
    A side note, if you are using a font with unicode characters, you could modify the display table to use better characters for the quotes. Alternatively, you could use font-lock to recognise the special case of `symbol'. – Lindydancer Mar 8 '15 at 15:01
11

The convention is documented in the section you already referenced (Tips for Documentation Strings). The purpose of the quotes is mentioned, and examples are provided:

 Help mode automatically creates a hyperlink when a documentation
 string uses a symbol name inside single quotes ... For example, if
 you write

      This function sets the variable `buffer-file-name'.

It sounds like the thing you are curious about is why single quotes in this context really means

`this' 

rather than

'this'

This representation of left and right quote characters using the ASCII backtick (grave accent) and single quote (apostrophe) appears to have been a common UNIX convention at one point, and as such I suspect it wasn't worth explaining further when the Emacs manual was written.

According to this post, the old X Window System fonts and term fonts made these symbols look more like true quotes.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.