bug#29478: [Patch 2]: bug#29478: 26.0.90; `C-h k' followed by mouse clicks no longer shows down event

[Alan Mackenzie <acm@muc.de>]

Hello, Eli.

On Fri, Dec 01, 2017 at 10:31:45 +0200, Eli Zaretskii wrote:
> > Date: Tue, 28 Nov 2017 20:33:00 -0800 (PST)
> > From: Drew Adams <drew.adams@oracle.com>
> > Cc: 29478@debbugs.gnu.org

> > > > > The down mouse-button event is no longer listed along with the up
> > > > > event when you use `C-h k' with a click event.  Dunno whether this
> > > > > was by design or is an oversight.

> > > I think if you press and hold the mouse button for (default) half a
> > > second, when you finally release it, C-h k will report the down mouse
> > > event.  At least this is how GPM behaves for me on a Linux tty.

> > Ah yes, thanks.  I see that now on MS Windows too.

> > > This seems to make sense, because anything bound to a down mouse
> > > event is going to be something like a drag event, where the mouse
> > > button is held for an extended period of time.

> > Sorry, no, I don't buy that.  I mean it's probably true that
> > most such bindings involve dragging.  But (1) a user who wants
> > to check what `mouse-N' does won't necessarily use it the same
> > way when checking with `C-h k' as when using it for its real
> > purpose.  And (2) the problem with this is that it is not
> > easily discoverable.

> > I've used Emacs for quite a while.  OK, I expected both up and
> > down to be documented.  But even I would likely never have
> > thought to hold the button pressed for a long time before
> > releasing, just to see what `C-h k' had to tell me.

> Alan, can we arrange for the doc string of mouse-N clicks (with or
> without all the possible modifiers) to say something like

>   For documentation of the corresponding mouse-down event, click and
>   hold the mouse button longer than %s sec.

> (where %s gets replaced by double-click-time)?

Yes, we can indeed.  The following patch is intended to achieve this.
It's based on the emacs-26 branch.  I've also corrected the bug where the
possibility of double-click-time being nil or t wasn't taken into
account.

Should I commit this one to emacs-26, too?



diff --git a/lisp/help.el b/lisp/help.el
index 212e3679da..3f013e8170 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -738,7 +738,11 @@ help-read-key-sequence
                          ;; spuriously trigger the `sit-for'.
                          (sleep-for 0.01)
                          (while (read-event nil nil 0.01))
-                         (not (sit-for (/ double-click-time 1000.0) t))))))))
+                         (not (sit-for
+                               (if (numberp double-click-time)
+                                   (/ double-click-time 1000.0)
+                                 3.0)
+                               t))))))))
           (list
            key
            ;; If KEY is a down-event, read and include the
@@ -769,6 +773,28 @@ help-read-key-sequence
         (setq yank-menu (copy-sequence saved-yank-menu))
         (fset 'yank-menu (cons 'keymap yank-menu))))))
 
+(defun help-downify-mouse-event-type (base)
+  "Add \"down-\" to BASE if it is not already there.
+BASE is a symbol, a mouse event type.  If the modification is done,
+return the new symbol.  Otherwise return nil."
+  (let ((base-s (symbol-name base)))
+    ;; Note: the order of the components in the following string is
+    ;; determined by `apply_modifiers_uncached' in src/keyboard.c.
+    (string-match "\\(A-\\)?\
+\\(C-\\)?\
+\\(H-\\)?\
+\\(M-\\)?\
+\\(S-\\)?\
+\\(s-\\)?\
+\\(double-\\)?\
+\\(triple-\\)?\
+\\(up-\\)?\
+\\(\\(down-\\)?\\)\
+\\(\\(drag-\\)?\\)" base-s)
+    (when (and (zerop (length (match-string 10 base-s)))  ; "down-"
+               (zerop (length (match-string 12 base-s)))) ; "drag-"
+      (intern (replace-match "down-" t t base-s 10)) )))
+
 (defun describe-key (&optional key untranslated up-event)
   "Display documentation of the function invoked by KEY.
 KEY can be any kind of a key sequence; it can include keyboard events,
@@ -828,6 +854,24 @@ describe-key
             (princ (format " (found in %s)" key-locus))))
         (princ ", which is ")
 	(describe-function-1 defn)
+        (when (vectorp key)
+          (let* ((last (1- (length key)))
+                 (elt (aref key last))
+                 (elt-1 (copy-sequence elt))
+                 key-1 down-event-type)
+            (when (and (eventp elt)
+                       (setq down-event-type (help-downify-mouse-event-type
+                                              (car elt))))
+              (setcar elt-1 down-event-type)
+              (setq key-1 (vector elt-1))
+              (when (key-binding key-1)
+                (princ (format "
+
+For documentation of the corresponding mouse down event <%s>,
+click and hold the mouse button longer than %s second(s)."
+                               down-event-type (if (numberp double-click-time)
+                                                   (/ double-click-time 1000.0)
+                                                 3)))))))
 	(when up-event
 	  (unless (or (null defn-up)
 		      (integerp defn-up)


-- 
Alan Mackenzie (Nuremberg, Germany).