How to quote symbols in a documentation string?

Question

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?

Answer 1

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.