Backslash-escaped brackets in string literals

Backslash-escaped brackets in string literals

[Mattias Engdegård]

[-- Attachment #1: Type: text/plain, Size: 1230 bytes --]

The manual contains the advice:

   • If a line in a documentation string begins with an
     open-parenthesis, write a backslash before the open-parenthesis,
     like this:

          The argument FOO can be either a number
          \(a buffer position) or a string (a file name).

     This prevents the open-parenthesis from being treated as the start
     of a defun (*note Defuns: (emacs)Defuns.).

First of all, is this still true? I rarely bother escaping brackets in doc strings and it doesn't seem to cause any editing confusion. For example, beginning-of-defun doesn't seem to be fooled by a '(' in column 1 inside a doc string.
(I do escape the (fn ...) annotation, probably out of superstition.)

Moreover, these backslashes appear a bit everywhere (not just doc strings), not only at bol, and not only before an opening bracket. They make reading and editing the text a bit more difficult. More importantly, they are a constant source of potential mistakes, especially in regexps.

I have a tool to scan for all of them (using the help-echo annotation by emacs-lisp-mode), but it would be much more useful if we were to remove all existing occurrences. A list of all red backslashes attached.


[-- Attachment #2: miscape.log --]
[-- Type: application/octet-stream, Size: 13421 bytes --]

-*- compilation -*-

lisp/registry.el:224:65: Ineffective string escape `\('
lisp/registry.el:226:58: Ineffective string escape `\('
lisp/registry.el:328:49: Ineffective string escape `\('
lisp/subr.el:3937:66: Ineffective string escape `\('
lisp/subr.el:4027:36: Ineffective string escape `\('
lisp/subr.el:4035:16: Ineffective string escape `\('
lisp/subr.el:4037:58: Ineffective string escape `\('
lisp/gnus/gnus-registry.el:244:26: Ineffective string escape `\('
lisp/gnus/gnus-registry.el:244:36: Ineffective string escape `\('
lisp/gnus/nntp.el:140:4: Ineffective string escape `\('
lisp/gnus/message.el:372:10: Ineffective string escape `\('
lisp/gnus/gnus-art.el:5943:44: Ineffective string escape `\('
lisp/gnus/gnus.el:2256:55: Ineffective string escape `\('
lisp/gnus/gnus-group.el:444:39: Ineffective string escape `\('
lisp/gnus/spam-stat.el:450:39: Ineffective string escape `\('
lisp/gnus/spam-stat.el:487:49: Ineffective string escape `\('
lisp/gnus/gnus-bookmark.el:121:22: Ineffective string escape `\('
lisp/gnus/gnus-bookmark.el:134:22: Ineffective string escape `\('
lisp/gnus/gnus-bookmark.el:795:55: Ineffective string escape `\('
lisp/foldout.el:249:23: Ineffective string escape `\('
lisp/net/tramp.el:117:13: Ineffective string escape `\('
lisp/net/tramp.el:491:39: Ineffective string escape `\('
lisp/net/tramp.el:1097:11: Ineffective string escape `\('
lisp/net/tramp.el:1172:31: Ineffective string escape `\('
lisp/net/dbus.el:1153:19: Ineffective string escape `\('
lisp/net/quickurl.el:209:3: Ineffective string escape `\('
lisp/net/nsm.el:374:37: Ineffective string escape `\#'
lisp/net/nsm.el:471:43: Ineffective string escape `\#'
lisp/net/nsm.el:606:63: Ineffective string escape `\#'
lisp/net/sasl-digest.el:57:38: Ineffective string escape `\('
lisp/net/ange-ftp.el:659:28: Ineffective string escape `\('
lisp/net/zeroconf.el:197:3: Ineffective string escape `\('
lisp/net/gnutls.el:128:12: Ineffective string escape `\('
lisp/eshell/esh-util.el:231:28: Ineffective string escape `\('
lisp/htmlfontify.el:1158:45: Ineffective string escape `\('
lisp/htmlfontify.el:1615:33: Ineffective string escape `\('
lisp/htmlfontify.el:1644:33: Ineffective string escape `\('
lisp/obsolete/iswitchb.el:387:15: Ineffective string escape `\('
lisp/obsolete/iswitchb.el:1396:21: Ineffective string escape `\*'
lisp/obsolete/old-whitespace.el:386:18: Ineffective string escape `\('
lisp/obsolete/old-whitespace.el:386:52: Ineffective string escape `\)'
lisp/obsolete/old-whitespace.el:387:19: Ineffective string escape `\('
lisp/obsolete/old-whitespace.el:387:53: Ineffective string escape `\)'
lisp/obsolete/old-whitespace.el:388:22: Ineffective string escape `\('
lisp/obsolete/old-whitespace.el:388:75: Ineffective string escape `\)'
lisp/obsolete/old-whitespace.el:389:30: Ineffective string escape `\('
lisp/obsolete/old-whitespace.el:389:65: Ineffective string escape `\)'
lisp/obsolete/vi.el:1228:34: Ineffective string escape `\''
lisp/obsolete/vi.el:1228:44: Ineffective string escape `\''
lisp/obsolete/rcompile.el:92:7: Ineffective string escape `\)'
lisp/obsolete/rcompile.el:92:28: Ineffective string escape `\('
lisp/obsolete/rcompile.el:92:34: Ineffective string escape `\)'
lisp/obsolete/pgg-pgp.el:43:32: Ineffective string escape `\('
lisp/obsolete/vip.el:83:18: Ineffective string escape `\)'
lisp/obsolete/vip.el:1513:26: Ineffective string escape `\('
lisp/obsolete/vip.el:1513:28: Ineffective string escape `\['
lisp/obsolete/vip.el:1722:38: Ineffective string escape `\('
lisp/obsolete/vip.el:1722:42: Ineffective string escape `\)'
lisp/obsolete/vip.el:1733:38: Ineffective string escape `\('
lisp/obsolete/vip.el:1733:42: Ineffective string escape `\)'
lisp/obsolete/vip.el:1744:33: Ineffective string escape `\('
lisp/obsolete/vip.el:1744:37: Ineffective string escape `\)'
lisp/obsolete/vip.el:2165:18: Ineffective string escape `\('
lisp/obsolete/vip.el:2165:46: Ineffective string escape `\)'
lisp/obsolete/vip.el:2671:42: Ineffective string escape `\('
lisp/obsolete/vip.el:2671:57: Ineffective string escape `\)'
lisp/obsolete/pgg-pgp5.el:58:32: Ineffective string escape `\('
lisp/format.el:516:12: Ineffective string escape `\('
lisp/format.el:577:40: Ineffective string escape `\('
lisp/format.el:599:47: Ineffective string escape `\('
lisp/format.el:614:52: Ineffective string escape `\('
lisp/format.el:824:28: Ineffective string escape `\('
lisp/format.el:859:18: Ineffective string escape `\('
lisp/format.el:867:23: Ineffective string escape `\('
lisp/format.el:867:37: Ineffective string escape `\('
lisp/nxml/xmltok.el:114:23: Ineffective string escape `\('
lisp/nxml/xmltok.el:127:13: Ineffective string escape `\('
lisp/nxml/nxml-parse.el:91:18: Ineffective string escape `\('
lisp/nxml/rng-valid.el:228:47: Ineffective string escape `\('
lisp/nxml/rng-cmpct.el:244:24: Ineffective string escape `\('
lisp/textmodes/reftex.el:2374:39: Ineffective string escape `\('
lisp/textmodes/fill.el:1138:32: Ineffective string escape `\('
lisp/textmodes/ispell.el:602:58: Ineffective string escape `\('
lisp/textmodes/enriched.el:170:24: Ineffective string escape `\('
lisp/textmodes/enriched.el:450:17: Ineffective string escape `\('
lisp/textmodes/tex-mode.el:287:37: Ineffective string escape `\('
lisp/textmodes/tex-mode.el:288:49: Ineffective string escape `\('
lisp/files.el:269:7: Ineffective string escape `\('
lisp/files.el:3540:51: Ineffective string escape `\('
lisp/org/ox.el:1762:22: Ineffective string escape `\('
lisp/org/org.el:11413:14: Ineffective string escape `\['
lisp/org/org.el:11414:14: Ineffective string escape `\['
lisp/org/org-list.el:2014:16: Ineffective string escape `\('
lisp/org/org-list.el:2014:36: Ineffective string escape `\('
lisp/org/org-list.el:2014:45: Ineffective string escape `\('
lisp/org/org-list.el:2797:17: Ineffective string escape `\('
lisp/org/org-element.el:4895:2: Ineffective string escape `\['
lisp/org/ol.el:848:30: Ineffective string escape `\]'
lisp/mail/rmail.el:316:8: Ineffective string escape `\('
lisp/mail/feedmail.el:638:24: Ineffective string escape `\('
lisp/mail/rmailedit.el:375:2: Ineffective string escape `\('
lisp/emulation/viper-macs.el:330:56: Ineffective string escape `\('
lisp/emulation/viper-util.el:1170:54: Ineffective string escape `\('
lisp/emulation/viper-mous.el:338:31: Ineffective string escape `\('
lisp/jka-cmpr-hook.el:291:17: Ineffective string escape `\('
lisp/jka-cmpr-hook.el:326:17: Ineffective string escape `\('
lisp/jka-cmpr-hook.el:341:17: Ineffective string escape `\('
lisp/follow.el:1699:41: Ineffective string escape `\('
lisp/image-dired.el:370:5: Ineffective string escape `\('
lisp/cedet/semantic/decorate/mode.el:48:19: Ineffective string escape `\('
lisp/comint.el:2771:31: Ineffective string escape `\('
lisp/char-fold.el:214:17: Ineffective string escape `\('
lisp/char-fold.el:225:5: Ineffective string escape `\('
lisp/help.el:889:10: Ineffective string escape `\('
lisp/hi-lock.el:365:10: Ineffective string escape `\('
lisp/vc/ediff-ptch.el:92:49: Ineffective string escape `\('
lisp/vc/vc-rcs.el:1129:7: Ineffective string escape `\('
lisp/vc/vc-rcs.el:1130:61: Ineffective string escape `\('
lisp/vc/vc-rcs.el:1133:42: Ineffective string escape `\('
lisp/vc/diff-mode.el:887:6: Ineffective string escape `\('
lisp/vc/ediff-util.el:1806:46: Ineffective string escape `\('
lisp/vc/ediff-util.el:2370:43: Ineffective string escape `\('
lisp/vc/ediff-wind.el:207:13: Ineffective string escape `\('
lisp/vc/ediff-wind.el:207:34: Ineffective string escape `\('
lisp/vc/vc-cvs.el:846:3: Ineffective string escape `\('
lisp/ps-print.el:1668:52: Ineffective string escape `\('
lisp/select.el:288:24: Ineffective string escape `\('
lisp/select.el:325:55: Ineffective string escape `\('
lisp/desktop.el:955:3: Ineffective string escape `\('
lisp/newcomment.el:1120:10: Ineffective string escape `\('
lisp/vcursor.el:575:55: Ineffective string escape `\('
lisp/woman.el:691:41: Ineffective string escape `\('
lisp/dired-aux.el:955:32: Ineffective string escape `\('
lisp/type-break.el:667:65: Ineffective string escape `\('
lisp/isearch.el:258:26: Ineffective string escape `\('
lisp/isearch.el:2825:33: Ineffective string escape `\('
lisp/view.el:452:21: Ineffective string escape `\('
lisp/erc/erc.el:261:26: Ineffective string escape `\('
lisp/erc/erc.el:267:26: Ineffective string escape `\('
lisp/erc/erc.el:268:3: Ineffective string escape `\('
lisp/erc/erc.el:275:26: Ineffective string escape `\('
lisp/erc/erc.el:276:3: Ineffective string escape `\('
lisp/erc/erc.el:2553:26: Ineffective string escape `\('
lisp/font-lock.el:1041:26: Ineffective string escape `\('
lisp/auth-source.el:334:33: Ineffective string escape `\('
lisp/auth-source.el:828:15: Ineffective string escape `\('
lisp/auth-source.el:830:7: Ineffective string escape `\('
lisp/progmodes/elisp-mode.el:1166:41: Ineffective string escape `\('
lisp/progmodes/elisp-mode.el:1346:48: Ineffective string escape `\('
lisp/progmodes/idlwave.el:4284:9: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:245:12: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:280:25: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:532:22: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:534:38: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:536:28: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:543:26: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:551:42: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:558:23: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:562:32: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:563:52: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:592:15: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:600:36: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:635:22: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:649:22: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:1621:8: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:1659:23: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:1660:29: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:1661:6: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:1817:52: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:2003:42: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:2059:10: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:2076:23: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:2076:30: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:2140:23: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:2140:44: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:2186:6: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:2188:23: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:2192:22: Ineffective string escape `\('
lisp/progmodes/antlr-mode.el:2233:35: Ineffective string escape `\('
lisp/progmodes/sql.el:675:15: Ineffective string escape `\('
lisp/progmodes/cc-cmds.el:66:20: Ineffective string escape `\('
lisp/progmodes/cc-langs.el:494:12: Ineffective string escape `\('
lisp/progmodes/cc-langs.el:533:61: Ineffective string escape `\('
lisp/progmodes/cc-langs.el:1569:62: Ineffective string escape `\('
lisp/progmodes/idlw-shell.el:710:37: Ineffective string escape `\('
lisp/progmodes/idlw-shell.el:3172:29: Ineffective string escape `\('
lisp/progmodes/idlw-shell.el:3172:45: Ineffective string escape `\('
lisp/progmodes/cmacexp.el:159:42: Ineffective string escape `\('
lisp/international/mule-cmds.el:2460:41: Ineffective string escape `\('
lisp/international/quail.el:961:8: Ineffective string escape `\('
lisp/international/quail.el:2881:51: Ineffective string escape `\('
lisp/emacs-lisp/timer.el:181:13: Ineffective string escape `\('
lisp/emacs-lisp/check-declare.el:137:37: Ineffective string escape `\('
lisp/emacs-lisp/map-ynp.el:47:40: Ineffective string escape `\('
lisp/emacs-lisp/map-ynp.el:59:40: Ineffective string escape `\('
lisp/emacs-lisp/ert-x.el:191:51: Ineffective string escape `\('
lisp/emacs-lisp/shadow.el:71:52: Ineffective string escape `\('
lisp/emacs-lisp/shadow.el:73:54: Ineffective string escape `\('
lisp/emacs-lisp/subr-x.el:172:50: Ineffective string escape `\('
lisp/emacs-lisp/subr-x.el:173:6: Ineffective string escape `\('
lisp/emacs-lisp/bytecomp.el:534:7: Ineffective string escape `\('
test/lisp/textmodes/conf-mode-tests.el:165:14: Ineffective string escape `\['
test/lisp/help-fns-tests.el:59:39: Ineffective string escape `\.'
test/lisp/help-fns-tests.el:64:51: Ineffective string escape `\.'
test/lisp/help-fns-tests.el:69:51: Ineffective string escape `\.'
test/lisp/help-fns-tests.el:74:56: Ineffective string escape `\.'
test/lisp/help-fns-tests.el:80:59: Ineffective string escape `\.'
test/lisp/simple-tests.el:430:20: Ineffective string escape `\c'
test/lisp/ibuffer-tests.el:85:41: Ineffective string escape `\<'
test/lisp/ibuffer-tests.el:85:46: Ineffective string escape `\>'
test/lisp/international/ucs-normalize-tests.el:302:13: Ineffective string escape `\)'
test/lisp/emacs-lisp/ert-x-tests.el:228:21: Ineffective string escape `\('
test/src/regex-emacs-tests.el:164:26: Ineffective string escape `\['
test/src/regex-emacs-tests.el:330:12: Ineffective string escape `\{'
test/src/regex-emacs-tests.el:330:21: Ineffective string escape `\}'

Re: Backslash-escaped brackets in string literals

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 24 Jan 2020 16:12:51 +0100
> 
>    • If a line in a documentation string begins with an
>      open-parenthesis, write a backslash before the open-parenthesis,
>      like this:
> 
>           The argument FOO can be either a number
>           \(a buffer position) or a string (a file name).
> 
>      This prevents the open-parenthesis from being treated as the start
>      of a defun (*note Defuns: (emacs)Defuns.).
> 
> First of all, is this still true?

Not really, but I'd hesitate to remove this, see below.

> I rarely bother escaping brackets in doc strings and it doesn't seem to cause any editing confusion.

Try "C-x 4 a" in a function with such a doc string, but without the
escape, and you will see confusion.

I don't think we should remove the escapes in column zero, at least
not yet.  The changes which made them not 100% required are too young,
and I expect many people to edit new sources with old Emacsen (I do
that all the time).

Thanks.

Re: Backslash-escaped brackets in string literals

[Stefan Monnier]

> First of all, is this still true?

Yes and no.  We have started to remove dependence on this, but there's
still some ways to go.  Eli mentioned `C-x 4 a` but there are others.

> I rarely bother escaping brackets in doc strings and it doesn't seem
> to cause any editing confusion. For example, beginning-of-defun
> doesn't seem to be fooled by a '(' in column 1 inside a doc string.
> (I do escape the (fn ...) annotation, probably out of superstition.)

Indeed, it "should" work fine.  You can report any misbehavior as a bug.

> Moreover, these backslashes appear a bit everywhere (not just doc
> strings), not only at bol, and not only before an opening bracket.

Not my fault ;-)

But yes, some authors probably decided it's easier to put them
"everywhere" than to understand exactly when it's needed (and to fix
the cases where refilling moves a `(` to/from BOL).

> A list of all red backslashes attached.

Without seeing the actual occurrences, it's hard to decide what to do
with them.  Those that occur within "normal strings" would benefit from
being fixed (i.e. removing the backslash).  Those that apply to
something else than an open paren probably should be fixed as well.


        Stefan

Re: Backslash-escaped brackets in string literals

[Mattias Engdegård]

Eli and Stefan, thanks for explaining.

24 jan. 2020 kl. 18.36 skrev Stefan Monnier <monnier@iro.umontreal.ca>:

> Yes and no.  We have started to remove dependence on this, but there's
> still some ways to go.  Eli mentioned `C-x 4 a` but there are others.

Actually, I tried to provoke C-x 4 a into a fit but failed. Perhaps I just didn't have enough patience.

>  Those that occur within "normal strings" would benefit from
> being fixed (i.e. removing the backslash).  Those that apply to
> something else than an open paren probably should be fixed as well.

What I've done now is to remove (or, in some cases, double) redundant backslashes except \( in doc strings. We probably could do away with more of them, but I tweaked the tool to ignore the rest so it's good enough for now.

Re: Backslash-escaped brackets in string literals

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Fri, 24 Jan 2020 23:22:54 +0100
> Cc: Emacs developers <emacs-devel@gnu.org>
> 
> Actually, I tried to provoke C-x 4 a into a fit but failed. Perhaps I just didn't have enough patience.

What did you expect to happen?  The problem manifests itself by having
no function name in the log entry produced by "C-x 4 a".

Re: Backslash-escaped brackets in string literals

[Mattias Engdegård]

25 jan. 2020 kl. 08.44 skrev Eli Zaretskii <eliz@gnu.org>:

> The problem manifests itself by having
> no function name in the log entry produced by "C-x 4 a".

Which is what I was unable to reproduce --- can you give an example? I'm in foreign territory here, but add-log-current-defun calls lisp-current-defun-name, which appears reasonably robust as long as syntax-ppss does its job.

If it used to be a problem but no longer is, then I'm happy and grateful for the hard work!

Re: Backslash-escaped brackets in string literals

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Sat, 25 Jan 2020 11:34:09 +0100
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> 25 jan. 2020 kl. 08.44 skrev Eli Zaretskii <eliz@gnu.org>:
> 
> > The problem manifests itself by having
> > no function name in the log entry produced by "C-x 4 a".
> 
> Which is what I was unable to reproduce --- can you give an example? I'm in foreign territory here, but add-log-current-defun calls lisp-current-defun-name, which appears reasonably robust as long as syntax-ppss does its job.
> 
> If it used to be a problem but no longer is, then I'm happy and grateful for the hard work!

I don't know what "used to be the problem" means in this case, so here
are the details of what happened to me last time I bumped into this:

  . visit minibuffer.el and go to set-minibuffer-message
  . remove the backslash that escapes the '(' in column zero in the
    doc string of that function (I added it when I had the problem)
  . C-x 4 a

In case it matters, I did that in Emacs 26.3.

Re: Backslash-escaped brackets in string literals

[Mattias Engdegård]

[-- Attachment #1: Type: text/plain, Size: 584 bytes --]

25 jan. 2020 kl. 14.33 skrev Eli Zaretskii <eliz@gnu.org>:

> In case it matters, I did that in Emacs 26.3.

Thank you, that explains it --- it appears fixed in Emacs 27 (57e2ca5c50, probably), which is why I didn't observe the glitch.
Good news, of course, and regarding your comment about using older versions, I can confirm that no \ at bol was removed in my latest clean-up.

However, I think the manual should be amended at this point, and that we needn't require new doc strings to escape brackets in the leftmost column.  Would this patch be acceptable for emacs-27?


[-- Attachment #2: 0001-Stop-recommending-to-be-escaped-in-doc-strings.patch --]
[-- Type: application/octet-stream, Size: 2055 bytes --]

From 67ac7feda9031e263cd5f6ef7445287ffdd30f45 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Sat, 25 Jan 2020 16:16:37 +0100
Subject: [PATCH] Stop recommending '(' to be escaped in doc strings

Thanks to 57e2ca5c50 and related changes, opening brackets at the
leftmost column inside doc strings are no longer mistaken for the
start of a defun.

* doc/lispref/tips.texi (Documentation Tips): Remove recommendation.
* etc/NEWS: Announce.
---
 doc/lispref/tips.texi | 12 ------------
 etc/NEWS              |  3 +++
 2 files changed, 3 insertions(+), 12 deletions(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 4395069fe2..a7804ed3f3 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -802,18 +802,6 @@ Documentation Tips
 starting the sentence with lower-case ``t'', which could be somewhat
 distracting.
 
-@item
-If a line in a documentation string begins with an open-parenthesis,
-write a backslash before the open-parenthesis, like this:
-
-@example
-The argument FOO can be either a number
-\(a buffer position) or a string (a file name).
-@end example
-
-This prevents the open-parenthesis from being treated as the start of a
-defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
-
 @item
 Write documentation strings in the active voice, not the passive, and in
 the present tense, not the future.  For instance, use ``Return a list
diff --git a/etc/NEWS b/etc/NEWS
index 792851e5af..4c510668fb 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3338,6 +3338,9 @@ versions.
 'forward-comment', 'scan-sexps', and 'forward-sexp' when parsing backward.
 The new variable 'comment-use-syntax-ppss' can be set to nil to recover
 the old behavior if needed.
+This also means that there is no longer any need to precede opening
+brackets at the start of a line inside documentation strings with a
+backslash.
 
 ---
 ** The 'server-name' and 'server-socket-dir' variables are set when a
-- 
2.21.0 (Apple Git-122.2)

Re: Backslash-escaped brackets in string literals

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Sat, 25 Jan 2020 16:32:58 +0100
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> However, I think the manual should be amended at this point, and that we needn't require new doc strings to escape brackets in the leftmost column.  Would this patch be acceptable for emacs-27?

I thought I've just shown you that disregarding this issue entirely is
still premature.  I'm okay with maybe making the text less mandatory
and more a recommendation, perhaps even mentioning older Emacs
versions.  But removing it entirely? what's the rush?

Re: Backslash-escaped brackets in string literals

[Mattias Engdegård]

[-- Attachment #1: Type: text/plain, Size: 699 bytes --]

25 jan. 2020 kl. 18.15 skrev Eli Zaretskii <eliz@gnu.org>:

> I thought I've just shown you that disregarding this issue entirely is
> still premature.  I'm okay with maybe making the text less mandatory
> and more a recommendation, perhaps even mentioning older Emacs
> versions.  But removing it entirely? what's the rush?

And I thought I just showed you that 'C-x 4 a' had actually been fixed... Let's shake hands.

It's perfectly normal to adjust the documentation to match the implementation; no need for foot-dragging. Your point about being nice to users of older versions is taken, though. Would this patch do? It retains the recommendation while being clear about its purpose.


[-- Attachment #2: 0001-Moderate-recommendation-to-escape-in-doc-strings.patch --]
[-- Type: application/octet-stream, Size: 3029 bytes --]

From 53bceefe2922c2ae36513b1f17f13ab80cda9190 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Sat, 25 Jan 2020 16:16:37 +0100
Subject: [PATCH] Moderate recommendation to escape '(' in doc strings

Thanks to 57e2ca5c50 and related changes, opening brackets at the
leftmost column inside doc strings are no longer mistaken for the
start of a defun.

* doc/lispref/tips.texi (Documentation Tips): Clarify recommendation
and move it down the list.
* etc/NEWS: Announce.
---
 doc/lispref/tips.texi | 27 +++++++++++++++------------
 etc/NEWS              |  4 ++++
 2 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 4395069fe2..0610f8029d 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -802,18 +802,6 @@ Documentation Tips
 starting the sentence with lower-case ``t'', which could be somewhat
 distracting.
 
-@item
-If a line in a documentation string begins with an open-parenthesis,
-write a backslash before the open-parenthesis, like this:
-
-@example
-The argument FOO can be either a number
-\(a buffer position) or a string (a file name).
-@end example
-
-This prevents the open-parenthesis from being treated as the start of a
-defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
-
 @item
 Write documentation strings in the active voice, not the passive, and in
 the present tense, not the future.  For instance, use ``Return a list
@@ -849,6 +837,21 @@ Documentation Tips
 start with words such as ``Non-nil means'', to make it clear that
 all non-@code{nil} values are equivalent and indicate explicitly what
 @code{nil} and non-@code{nil} mean.
+
+@item
+If a line in a documentation string begins with an open-parenthesis,
+consider writing a backslash before the open-parenthesis, like this:
+
+@example
+The argument FOO can be either a number
+\(a buffer position) or a string (a file name).
+@end example
+
+This avoids a bug in Emacs versions older than 27.1, where the
+@samp{(} was treated as the start of a defun
+(@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
+If you do not anticipate anyone editing your code with older Emacs
+versions, there is no need for this work-around.
 @end itemize
 
 @node Comment Tips
diff --git a/etc/NEWS b/etc/NEWS
index 792851e5af..433f1f76b8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3338,6 +3338,10 @@ versions.
 'forward-comment', 'scan-sexps', and 'forward-sexp' when parsing backward.
 The new variable 'comment-use-syntax-ppss' can be set to nil to recover
 the old behavior if needed.
+This also means that there is no longer any need to precede opening
+brackets at the start of a line inside documentation strings with a
+backslash, although there is no harm in doing so to make the code
+easier to edit with an older Emacs version.
 
 ---
 ** The 'server-name' and 'server-socket-dir' variables are set when a
-- 
2.21.0 (Apple Git-122.2)

Re: Backslash-escaped brackets in string literals

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Sun, 26 Jan 2020 12:24:11 +0100
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> > I thought I've just shown you that disregarding this issue entirely is
> > still premature.  I'm okay with maybe making the text less mandatory
> > and more a recommendation, perhaps even mentioning older Emacs
> > versions.  But removing it entirely? what's the rush?
> 
> And I thought I just showed you that 'C-x 4 a' had actually been fixed... Let's shake hands.

🤝

> It's perfectly normal to adjust the documentation to match the implementation; no need for foot-dragging. Your point about being nice to users of older versions is taken, though. Would this patch do? It retains the recommendation while being clear about its purpose.

Fine with me, thanks.

RE: Backslash-escaped brackets in string literals

[Drew Adams]

> I think the manual should be amended at this point, and that
> we needn't require new doc strings to escape brackets in the leftmost
  ^^^^^^^^^^^^^^^^^^
> column.  Would this patch be acceptable for emacs-27?

"We need not" doesn't mean that no users of Elisp
need to use such escaping.

This messaging/doc is for everyone, not just the
developers who provide the code that GNU Emacs
distributes as part of Emacs.  And no user has ever
been "required" to use such escaping.  Let's keep
the target audience in mind: general Elisp users.

I think it's misleading and narrow to say "there
is no longer any need" for such escaping.

There can be such a need, if you're writing code
intended for more than just Emacs 27 and later.
3rd-party code is sometimes intended for multiple
releases.

In fact, it's probable that only a tiny minority
of Emacs users use the latest release, and only
the latest release.

It would be better to point out clearly that:

1. It never _hurts_ to provide such escaping.
2. Such escaping is appropriate for backward
   compatibility.  It presents no advantage for
   Emacs 27+, but it's helpful for older releases.