5

Bleeding edge Emacs is starting to complain about certain uses of ' in doc strings. I am trying to resolve these.

As a typical example, in a doc string I might include an example:

(defun my-mode-indent-function (&optional _whole-exp)
  "Indent.

To extend, use your Emacs init file to

    (put SYMBOL 'my-mode-indent-function INDENT)

Where SYMBOL is blah blah blah and INDENT is blah blah blah."
 ___)

Although this has worked fine "forever", starting recently on master for Emacs 29.0.50, byte compiling complains:

foo.el:123:2: Error: defun `my-mode-indent-function' docstring has wrong usage of unescaped single quotes (use \= or different quoting)

That is, it doesn't like the ' in 'my-mode-indent-function.

I am trying to follow the hint in the error message -- (use \= or different quoting) -- but with no joy.

The following avoids the error but the doc string shows ='my-mode-indent:

(put SYMBOL \='my-mode-indent-function INDENT)

The following still produces the error:

(put SYMBOL \'my-mode-indent-function INDENT)

Of course I could use the full quote form everywhere -- but that would be the doc formatting tail wagging the desired real-world example dog:

(put SYMBOL (quote my-mode-indent-function) INDENT)

What is \= and where can I learn more about it? It seems to be one of those things that's tricky to search for; I can't find more information anywhere.

1 Answer 1

5

From scrounging the commit history it seems that this "escape" or "literal" prefix is not \= -- instead it is \\=.

So in my example of doc string text

(put SYMBOL 'my-mode-indent-function INDENT)

the solution is

(put SYMBOL \\='my-mode-indent-function INDENT)

That displays as desired and avoids the new byte compiler error.

Probably the new error message string needs to change from "\\=" to "\\\\=" so that it prints the hint more correctly/helpfully?


Update: I found the documentation under Substituting Key Bindings in Documentation:

\=

quotes the following character and is discarded; thus, \=` puts ` into the output, \=\[ puts \[ into the output, and \=\= puts \= into the output.

Please note: Each \ must be doubled when written in a string in Emacs Lisp.

6
  • 1
    Yes, the escape sequence within the string is the two-character pair \=; but in order to put that sequence into a string using the double-quoted read syntax for strings, the backslash needs to be escaped with another backslash.
    – phils
    Commented Jun 7, 2022 at 22:54
  • Exactly like \(...\) in a regexp (string) defines a group, but to write that regexp in the double-quoted read syntax for strings you use "\\(...\\)"
    – phils
    Commented Jun 7, 2022 at 22:57
  • Yes, it turns out to be just the very old story about escaping an escape character. Commented Jun 8, 2022 at 12:55
  • Well, maybe also an old question: Is it better to document these things from the point of view of the code consuming them (it's "\"), or, from the POV of people authoring (who will always be writing "\\")? The linked doc section does the former... but there's a "Please note" to clarify, so that's fine. I was just confused starting from the new error message's hint... but eventually it led me to the right answer, so that's fine, too. Commented Jun 8, 2022 at 13:03
  • For consistency I think it needs to be as it is. It may seem arguable for docstrings, but you couldn't possibly document strings in general with the assumption that they are in string read syntax, because users can enter them interactively (consider the regexp example again). It's a point of confusion for sure, but I think it would be so in any case.
    – phils
    Commented Jun 8, 2022 at 13:52

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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