bug#38248: help-follow-symbol silent when no symbol was found

bug#38248: help-follow-symbol silent when no symbol was found

[Juanma Barranquero]

[-- Attachment #1.1: Type: text/plain, Size: 829 bytes --]

Package: emacs
Severity: minor
Tags: patch

Currently, help-follow and help-follow-mouse signal an error if there's
nothing to follow. However, help-follow-symbol does not, which means that
C-c C-c in the help buffer when over an arbitrary non-symbol does nothing
and says nothing.

That's not just inconsistent, but a bit disconcerting, as sometimes
following a symbol can be slow. In my build, it takes a second or more to
show the symbol documentation, so when there's no symbol I stand waiting
for something to happen for a couple of seconds.

The following patch fixes that. The only reason against I can think of is
when `help-follow-symbol' is called from elisp, because it will now signal
an error. However, at least in the Emacs sources help-follow-symbol is
never called from elisp, just as a keybinding or menu entry.

[-- Attachment #1.2: Type: text/html, Size: 975 bytes --]

[-- Attachment #2: 0001-lisp-help-mode.el-help-follow-symbol-Signal-no-symbo.patch --]
[-- Type: application/octet-stream, Size: 1105 bytes --]

From 4fb8e8c124009ab283fb9d15ad7aaa0a90f56ec7 Mon Sep 17 00:00:00 2001
From: Juanma Barranquero <lekktu@gmail.com>
Date: Sun, 17 Nov 2019 20:27:12 +0100
Subject: [PATCH] * lisp/help-mode.el (help-follow-symbol): Signal no symbol at
 point.

---
 lisp/help-mode.el | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 054a1ef8c2..e70570c3ee 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -749,10 +749,11 @@ help-follow-symbol
 	    (buffer-substring (point)
 			      (progn (skip-syntax-forward "w_")
 				     (point)))))))
-    (when (or (boundp sym)
-	      (get sym 'variable-documentation)
-	      (fboundp sym) (facep sym))
-      (help-do-xref pos #'describe-symbol (list sym)))))
+    (if (or (boundp sym)
+	    (get sym 'variable-documentation)
+	    (fboundp sym) (facep sym))
+        (help-do-xref pos #'describe-symbol (list sym))
+      (user-error "No symbol here"))))
 
 (defun help-mode-revert-buffer (_ignore-auto noconfirm)
   (when (or noconfirm (yes-or-no-p "Revert help buffer? "))
-- 
2.23.0.windows.1

bug#38248: help-follow-symbol silent when no symbol was found

[Lars Ingebrigtsen]

Juanma Barranquero <lekktu@gmail.com> writes:

> That's not just inconsistent, but a bit disconcerting, as sometimes
> following a symbol can be slow. In my build, it takes a second or more
> to show the symbol documentation, so when there's no symbol I stand
> waiting for something to happen for a couple of seconds.
>
> The following patch fixes that. The only reason against I can think of
> is when `help-follow-symbol' is called from elisp, because it will now
> signal an error.  However, at least in the Emacs sources
> help-follow-symbol is never called from elisp, just as a keybinding or
> menu entry.

Adding an error-out here I think should be OK.  I googled a bit and
couldn't see anything out-of-tree that uses that command as a function.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#38248: help-follow-symbol silent when no symbol was found

[Juanma Barranquero]

[-- Attachment #1.1: Type: text/plain, Size: 58 bytes --]

Eli, are you OK with this (slightly) incompatible change?

[-- Attachment #1.2: Type: text/html, Size: 83 bytes --]

[-- Attachment #2: 0001-help-follow-symbol-now-tells-that-no-symbol-was-foun.patch --]
[-- Type: application/octet-stream, Size: 1678 bytes --]

From 088bd2ab28ef17a0cba02ea47aca6a02da1ce939 Mon Sep 17 00:00:00 2001
From: Juanma Barranquero <lekktu@gmail.com>
Date: Fri, 22 Nov 2019 19:47:05 +0100
Subject: [PATCH] help-follow-symbol now tells that no symbol was found

* lisp/help-mode.el (help-follow-symbol): Signal user-error if
there's no symbol at point.

* etc/NEWS: Document it.
---
 etc/NEWS          | 4 ++++
 lisp/help-mode.el | 9 +++++----
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index b92fdeb675..013336835d 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2588,6 +2588,10 @@ pointer is over.  To change this behaviour, you can customize the user
 option 'mouse-wheel-follow-mouse'.  Note that this will also affect
 scrolling.
 
+---
+** help-follow-symbol now signals user-error if point (or the position
+pointed to by the argument POS) is not in a symbol.
+
 \f
 * Lisp Changes in Emacs 27.1
 
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 054a1ef8c2..e70570c3ee 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -749,10 +749,11 @@ help-follow-symbol
 	    (buffer-substring (point)
 			      (progn (skip-syntax-forward "w_")
 				     (point)))))))
-    (when (or (boundp sym)
-	      (get sym 'variable-documentation)
-	      (fboundp sym) (facep sym))
-      (help-do-xref pos #'describe-symbol (list sym)))))
+    (if (or (boundp sym)
+	    (get sym 'variable-documentation)
+	    (fboundp sym) (facep sym))
+        (help-do-xref pos #'describe-symbol (list sym))
+      (user-error "No symbol here"))))
 
 (defun help-mode-revert-buffer (_ignore-auto noconfirm)
   (when (or noconfirm (yes-or-no-p "Revert help buffer? "))
-- 
2.23.0.windows.1

bug#38248: help-follow-symbol silent when no symbol was found

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Fri, 22 Nov 2019 19:50:21 +0100
> Cc: 38248@debbugs.gnu.org, Eli Zaretskii <eliz@gnu.org>
> 
> Eli, are you OK with this (slightly) incompatible change?

Rationale?

> +** help-follow-symbol now signals user-error if point (or the position

user-error should be quoted 'like this'.

bug#38248: help-follow-symbol silent when no symbol was found

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 751 bytes --]

On Fri, Nov 22, 2019 at 8:25 PM Eli Zaretskii <eliz@gnu.org> wrote:

> Rationale?

I quote from my original bug report:

Currently, help-follow and help-follow-mouse signal an error if there's
nothing to follow. However, help-follow-symbol does not, which means
that C-c C-c in the help buffer when over an arbitrary non-symbol does
nothing and says nothing.

That's not just inconsistent, but a bit disconcerting, as sometimes
following a symbol can be slow. In my build, it takes a second or more
to show the symbol documentation, so when there's no symbol I stand
waiting for something to happen for a couple of seconds.

> > +** help-follow-symbol now signals user-error if point (or the position
>
> user-error should be quoted 'like this'.

Ok.

[-- Attachment #2: Type: text/html, Size: 1315 bytes --]

bug#38248: help-follow-symbol silent when no symbol was found

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Fri, 22 Nov 2019 20:40:15 +0100
> Cc: Lars Magne Ingebrigtsen <larsi@gnus.org>, 38248@debbugs.gnu.org
> 
> Currently, help-follow and help-follow-mouse signal an error if there's
> nothing to follow. However, help-follow-symbol does not, which means
> that C-c C-c in the help buffer when over an arbitrary non-symbol does
> nothing and says nothing.
> 
> That's not just inconsistent, but a bit disconcerting, as sometimes
> following a symbol can be slow. In my build, it takes a second or more
> to show the symbol documentation, so when there's no symbol I stand
> waiting for something to happen for a couple of seconds.

OK.

bug#38248: help-follow-symbol silent when no symbol was found

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 54 bytes --]

Committed as b7d4c5d1d1b55fea8382663f18263e2000678be5

[-- Attachment #2: Type: text/html, Size: 81 bytes --]