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.

Greg Hendershott
  • 1,483
  • 12
  • 17

1 Answers1

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.

Greg Hendershott
  • 1,483
  • 12
  • 17
  • 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 Jun 07 '22 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 Jun 07 '22 at 22:57
  • Yes, it turns out to be just the very old story about escaping an escape character. – Greg Hendershott Jun 08 '22 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. – Greg Hendershott Jun 08 '22 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 Jun 08 '22 at 13:52
  • What an unfortunate design decision. Having to spell every contraction like `can\\='t` or `function\\='s` makes the documentation in the source code even less readable. Or am I missing something? – Vladimir Panteleev Oct 01 '22 at 18:42