Re: Backslash-escaped brackets in string literals

["Mattias Engdegård" <mattiase@acm.org>]

[-- 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)