4

I've seen the following warning from the Emacs 29 compiler:

In s-format:
s.el:614:2: Warning: docstring has wrong usage of unescaped single quotes (use
    \= or different quoting)

I haven't been able to find this documented. Can anyone help?

(EDIT: I am specifically trying to find out when/why it was decided to be a compiler level event.)

Drew
  • 75,699
  • 9
  • 109
  • 225
ocodo
  • 1,202
  • 11
  • 20

2 Answers2

4

Documentation is:

  • C-hig (elisp)Keys in Documentation
  • C-hig (elisp)Text Quoting Style

In short, the text-quoting-style feature introduced in Emacs 25 made it impossible to use certain characters in docstrings (most notably the normal ascii apostrophes which are so very prevalent in lisp) without escaping them with \= (which is "\\=" in the double-quoted read syntax for strings), as otherwise they are liable to be replaced by different quote characters at render time.

So to write a docstring containing an apostrope, you must use this:

"\\='"

instead of simply

"'"

It's a compiler warning because it very likely indicates that the docstring displays invalid lisp code. (Some people have argued for it to be relegated to checkdoc, but that would dramatically limit the number of people who notice these bugs, so I suspect it'll remain a byte-compilation warning.)

If you're seeing these in third-party packages, submit bug reports.

Tangentially, you can ensure you're never affected by such bugs by using the old-style docstring rendering, by setting text-quoting-style to grave.

phils
  • 48,657
  • 3
  • 76
  • 115
  • 1
    Thank you, I was more interested to know when the warning became a compiler level event. (marking correct due to the original wording of the question.) – ocodo Aug 13 '22 at 03:48
  • 2
    It became a byte-compilation warning in Emacs 29 (unstable at time of writing, but I think the warning is likely to remain as such for stable releases). Search for `\=` in the NEWS file. – phils Aug 13 '22 at 03:57
4

From Emacs 29 etc/NEWS

(slightly paraphrased)

Byte compilation will now warn about some quoting mistakes in docstrings. When writing code that contains the ' character (APOSTROPHE), that quote character has to be escaped to avoid Emacs displaying it as ’ (LEFT SINGLE QUOTATION MARK), which would make code examples like this invalid:

(setq foo '(1 2 3))

Emacs will now warn during byte compilation if it sees something like that, and also warn about when using RIGHT/LEFT SINGLE QUOTATION MARK directly. In both these cases, if these characters should really be present in the docstring, they should be quoted with \=

Refer to Phil's answer and https://emacsdocs.org/docs/elisp/Keys-in-Documentation for extended usage info for \=

ocodo
  • 1,202
  • 11
  • 20