master cf2fa6c 2/3: Add user option to avoid checkdoc warning for unescaped left paren

[Stefan Kangas]

branch: master
commit cf2fa6c87f4da4665ff8a9e8e220bba0b5bccefc
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    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 76cfb43..d4f4c81 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2826,6 +2826,13 @@ 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 bc568f1..3150ea6 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]+\\)")