From ea58276462d93f24c75473c69154ef7a4a47b63c Mon Sep 17 00:00:00 2001
From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Sat, 7 May 2022 12:46:55 +0200
Subject: [PATCH] Allow inhibiting linkification in *Help* buffers

* doc/lispref/help.texi (Keys in Documentation): Document it.
lisp/help-mode.el (help-make-xrefs): Implement a new \+ syntax to
inhibit buttonification.
---
 doc/lispref/help.texi        |  4 ++++
 etc/NEWS                     |  9 ++++++++
 lisp/help-mode.el            | 42 +++++++++++++++++++-----------------
 test/lisp/help-mode-tests.el |  2 +-
 4 files changed, 36 insertions(+), 21 deletions(-)

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index d53bfad8e9e..f029a1c97cc 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -362,6 +362,10 @@ depending on the value of @code{text-quoting-style}.
 quotes the following character and is discarded; thus, @samp{\=`} puts
 @samp{`} into the output, @samp{\=\[} puts @samp{\[} into the output,
 and @samp{\=\=} puts @samp{\=} into the output.
+
+@item \+
+This indicates that the symbol directly following should not be marked
+as link in the @file{*Help*} buffer.
 @end table
 
 @strong{Please note:} Each @samp{\} must be doubled when written in a
diff --git a/etc/NEWS b/etc/NEWS
index b595eae7e10..a2f7f038524 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -461,6 +461,15 @@ This allows you to enter emoji using short strings, eg :face_palm: or
 
 ** Help
 
++++
+*** New doc string syntax to indicate that symbols shouldn't be links.
+When displaying doc strings in *Help* buffers, strings that are
+"`like-this'" are made into links (if they point to a bound
+function/variable).  This can lead to false positives when talking
+about values that are symbols that happen to have the same names as
+functions/variables.  To inhibit this buttonification, the new
+"\\+`like-this'" syntax can be used.
+
 +++
 *** New user option 'help-window-keep-selected'.
 If non-nil, commands to show the info manual and the source will reuse
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index a0a587cd810..4a65f40507b 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -452,6 +452,7 @@ Commands:
  		    "\\(symbol\\|program\\|property\\)\\|" ; Don't link
 		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
 		    "[ \t\n]+\\)?"
+                    "\\(\\\\\\+\\)?"
                     "['`‘]\\(\\(?:\\sw\\|\\s_\\)+\\|`\\)['’]"))
   "Regexp matching doc string references to symbols.
 
@@ -628,27 +629,28 @@ that."
                 ;; Quoted symbols
                 (save-excursion
                   (while (re-search-forward help-xref-symbol-regexp nil t)
-                    (let* ((data (match-string 8))
-                           (sym (intern-soft data)))
-                      (if sym
-                          (cond
-                           ((match-string 3) ; `variable' &c
-                            (and (or (boundp sym) ; `variable' doesn't ensure
+                    (when-let ((sym (intern-soft (match-string 9))))
+                      (if (match-string 8)
+                          (delete-region (match-beginning 8)
+                                         (match-end 8))
+                        (cond
+                         ((match-string 3)        ; `variable' &c
+                          (and (or (boundp sym) ; `variable' doesn't ensure
                                         ; it's actually bound
-                                     (get sym 'variable-documentation))
-                                 (help-xref-button 8 'help-variable sym)))
-                           ((match-string 4) ; `function' &c
-                            (and (fboundp sym) ; similarly
-                                 (help-xref-button 8 'help-function sym)))
-                           ((match-string 5) ; `face'
-                            (and (facep sym)
-                                 (help-xref-button 8 'help-face sym)))
-                           ((match-string 6)) ; nothing for `symbol'
-                           ((match-string 7)
-                            (help-xref-button 8 'help-function-def sym))
-                           ((cl-some (lambda (x) (funcall (nth 1 x) sym))
-                                     describe-symbol-backends)
-                            (help-xref-button 8 'help-symbol sym)))))))
+                                   (get sym 'variable-documentation))
+                               (help-xref-button 9 'help-variable sym)))
+                         ((match-string 4)     ; `function' &c
+                          (and (fboundp sym)   ; similarly
+                               (help-xref-button 9 'help-function sym)))
+                         ((match-string 5) ; `face'
+                          (and (facep sym)
+                               (help-xref-button 9 'help-face sym)))
+                         ((match-string 6)) ; nothing for `symbol'
+                         ((match-string 7)
+                          (help-xref-button 9 'help-function-def sym))
+                         ((cl-some (lambda (x) (funcall (nth 1 x) sym))
+                                   describe-symbol-backends)
+                          (help-xref-button 9 'help-symbol sym)))))))
                 ;; An obvious case of a key substitution:
                 (save-excursion
                   (while (re-search-forward
diff --git a/test/lisp/help-mode-tests.el b/test/lisp/help-mode-tests.el
index c0c1cf8b530..b5bdf6b8d49 100644
--- a/test/lisp/help-mode-tests.el
+++ b/test/lisp/help-mode-tests.el
@@ -81,7 +81,7 @@ Lisp concepts such as car, cdr, cons cell and list.")
         (insert (format fmt fn))
         (goto-char (point-min))
         (re-search-forward help-xref-symbol-regexp)
-        (help-xref-button 8 'help-function)
+        (help-xref-button 9 'help-function)
         (should-not (button-at (1- beg)))
         (should-not (button-at (+ beg (length (symbol-name fn)))))
         (should (eq (button-type (button-at beg)) 'help-function))))))
-- 
2.39.2