10

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?

Community
  • 1
Håkon Hægland
  • 3,608
  • 1
  • 20
  • 51
  • 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 07 '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 08 '15 at 15:01

1 Answers1

13

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.

glucas
  • 20,175
  • 1
  • 51
  • 83
  • 3
    Here is some more information about the origin of this style: http://www.emacswiki.org/emacs/EmacsDocumentationNotation, https://lists.gnu.org/archive/html/help-gnu-emacs/2012-03/msg00390.html, https://groups.google.com/forum/#!topic/gnu.emacs.help/DkNywy950Y0 – Håkon Hægland Mar 08 '15 at 05:40