From cf2fa6c87f4da4665ff8a9e8e220bba0b5bccefc Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Mon, 13 Sep 2021 21:57:13 +0200
Subject: [PATCH] Add user option to avoid checkdoc warning for unescaped left
 paren

* lisp/emacs-lisp/checkdoc.el
(checkdoc-column-zero-backslash-before-paren): New user option to
avoid warning on unescaped left parenthesis in column zero.
(checkdoc-this-string-valid-engine): Respect above new option.
---
 etc/NEWS                    |  7 +++++++
 lisp/emacs-lisp/checkdoc.el | 29 +++++++++++++++++++----------
 2 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 76cfb43efc3..d4f4c81f895 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2825,6 +2825,13 @@ after every monthly meeting which takes place on the third Thursday,
 or if you would like to attend a virtual meeting scheduled in a
 different timezone causing a difference in the date.
 
+---
+*** New user option 'checkdoc-column-zero-backslash-before-paren'.
+Checkdoc warns if there is a left parenthesis in column zero of a
+documentation string.  That warning can now be disabled by customizing
+this new user option to nil.  This can be useful if you don't expect
+your code to be edited with an Emacs version older than 27.1.
+
 ---
 *** The old non-SMIE indentation of 'sh-mode' has been removed.
 
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index bc568f10fce..3150ea605f0 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -312,6 +312,14 @@ This should be set in an Emacs Lisp file's local variables."
   :version "28.1")
 ;;;###autoload(put 'checkdoc-symbol-words 'safe-local-variable #'checkdoc-list-of-strings-p)
 
+(defcustom checkdoc-column-zero-backslash-before-paren t
+  "Non-nil means to warn if there is no '\\' before '(' in column zero.
+This backslash is no longer needed on Emacs 27.1 later.
+
+See Info node `(elisp) Documentation Tips' for background."
+  :type 'boolean
+  :version "28.1")
+
 ;;;###autoload
 (defun checkdoc-list-of-strings-p (obj)
   "Return t when OBJ is a list of strings."
@@ -1403,16 +1411,17 @@ buffer, otherwise stop after the first error."
 	      (match-beginning 1)
 	      (match-end 1)))))
      ;; * Check for '(' in column 0.
-     (save-excursion
-       (when (re-search-forward "^(" e t)
-	 (if (checkdoc-autofix-ask-replace (match-beginning 0)
-					   (match-end 0)
-					   (format-message "Escape this `('? ")
-					   "\\(")
-	     nil
-	   (checkdoc-create-error
-	    "Open parenthesis in column 0 should be escaped"
-	    (match-beginning 0) (match-end 0)))))
+     (when checkdoc-column-zero-backslash-before-paren
+       (save-excursion
+         (when (re-search-forward "^(" e t)
+           (if (checkdoc-autofix-ask-replace (match-beginning 0)
+                                     (match-end 0)
+                                     (format-message "Escape this `('? ")
+                                     "\\(")
+               nil
+             (checkdoc-create-error
+              "Open parenthesis in column 0 should be escaped"
+              (match-beginning 0) (match-end 0))))))
      ;; * Do not start or end a documentation string with whitespace.
      (let (start end)
        (if (or (if (looking-at "\"\\([ \t\n]+\\)")
-- 
2.39.5