Documentation of the action of a button

Question

I want to know what happens if I click on a button (a link) in an Emacs buffer, so I type C-h c (describe-key-briefly) and click the button, but all I'm told is:

<mouse-2> (translated from <down-mouse-2> <mouse-2>) at that spot runs the command push-button

C-h k (describe-key) shows me the documentation of push-button, which is not what I'm after.

To find out what actually happens when I click, I need to perform the same lookup that push-button does, and then look at its documentation rather than invoking the function. That is to say, look at the text's action (or mouse-action for a mouse click), and run describe-function on that.

Is there a convenient way to do that? Ideally, I'd like describe-key to show the description of the action in addition to (or even instead of) the description of push-button.

Answer 1

Quick and dirty, minimally tested in 24.3 (and probably fails in ancient and future versions because it makes some assumptions about how describe-key works internally). The following code appends the description of the action to the description of push-button in the help buffer.

(defadvice describe-key
  (around describe-key-button-action activate compile)
  "When describing a key that invokes a button, describe the effect of the button."
  (let (also-describe-action)
    (let ((defn (key-binding key t))
          (is-mouse (and (vectorp key) (mouse-event-p (aref key 0)))))
      (when (eq defn 'push-button)
        (setq also-describe-action
              (let ((button (if is-mouse
                                (let* ((posn (event-start (aref key 0)))
                                       (buffer (window-buffer (posn-window posn))))
                                  (with-current-buffer buffer
                                    (button-at (posn-point posn))))
                              (button-at (point)))))
                (or (and is-mouse (button-get button 'mouse-action))
                    (button-get button 'action))))))
    ad-do-it
    (when (functionp also-describe-action)
      (with-current-buffer (help-buffer)
        (save-excursion
          (goto-char (point-max))
          (forward-line -1)
          (let ((standard-output (current-buffer))
                (buffer-read-only nil))
            (princ "\f\nPushing the button runs the command ")
            (princ also-describe-action)
            (princ ", which is ")
            (describe-function-1 also-describe-action)
            (princ "\n\n")))))))