Re: Backslash-escaped brackets in string literals

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

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